Man Linux: Main Page and Category List


       im_generate,    im_start_one,   im_stop_one,   im_allocate_input_array,
       im_start_many, im_stop_many - generate image pixels


       #include <vips/vips.h>

       void *im_start_one( out, in )
       IMAGE *out, *in;

       int im_stop_one( reg )
       REGION *reg;

       IMAGE **im_allocate_input_array( IMAGE *out, ... )

       void *im_start_many( out, in )
       IMAGE *out, **in;

       int im_stop_many( REGION **out )
       REGION **out;

       int im_generate( im,
           start_fn, gen_fn, stop_fn, void *a, void *b )
       IMAGE *im;
       void *(*start_fn)();
       int (*gen_fn)();
       int (*stop_fn)();
       void *a, void *b;

       where, typically,

       void *start_fn( im, a, b )
       IMAGE *im;
       void *a, *b;

       int gen_fn( or, seq, a, b )
       REGION *or;
       void *seq;
       void *a, *b;

       int stop_fn( seq, a, b )
       void *seq;
       void *a, *b;


       im_generate(3), with its supporting convenience functions, is used  for
       PIO  image  output.   See also im_wrapone(3) for an easy alternative to
       im_generate(3) for simple image processing operations.

       im_start_one(3) and im_stop_one(3) are  convenience  functions,  useful
       for  simple  one-image-in,  one-image-out  operations.  im_start_one(3)
       assumes the first of the two user arguments (a,  above)  is  the  input
       image.  It  creates a REGION on this image and returns a pointer to the
       region as a sequence value.

       im_stop_one(3) assumes the sequence value  is  a  REGION  pointer,  and
       frees it.

       im_allocate_input_array(3)  takes  as  arguments the output image and a
       list of input images, terminated with a  NULL.  It  allocates  a  NULL-
       terminated  array  to hold the images, and attaches a close callback to
       the output image to free that array. Example:

           IMAGE *in, *in2, *in3, *in4;
           IMAGE **arry;

           if( !(arry = im_allocate_input_array( out,
               in1, in2, in3, in4, NULL )) )
               return( -1 );

       builds the structure

           IMAGE *arry[] = { in1, in2, in3, in4, NULL };

       and makes sure it will be freed.

       im_start_many(3) and im_stop_many(3) work  exactly  as  im_start_one(3)
       and  im_stop_one(3),  but  with  NULL-terminated  arrays  of IMAGEs and
       REGIONs.  They are useful for many-images-in, one-image-out operations.
       im_start_many(3)  assumes that the first of the two user arguments is a
       pointer to a NULL-terminates array of IMAGEs. It builds and returns  as
       the sequence value a NULL-terminated array of REGIONs.

       im_stop_many(3)  assumes  the  sequence  value  is a pointer to a NULL-
       terminated array of REGIONs. It frees all  the  regions  in  turn.  See
       im_add(3) for an example of this pair of functions in action.

       im_generate(3) looks at the type of im and acts accordingly:

           IM_PARTIAL:  the  start, process and stop functions are attached to
       the region, and im_generate returns immediately. See im_prepare(3).

           IM_SETBUF: memory for the output image  is  created  and  sequences
       started to fill it. It is an error to write to the same buffer twice.

           IM_MMAPINRW:  sequences are started, and asked to fill the image in

           IM_OPENOUT: The output file is created  and  a  header  written  to
       disc.  A  buffer  large  enough  to  hold GENERATE_TILE_HEIGHT complete
       horizontal lines is created, and sequences started to fill this buffer.
       When  the buffer has been filled, the whole set of lines are flushed to
       disc in a single write(2) operation, and work starts on the next set of

       Any  other  image  type  is  an  error.   im_generate(3)  returns 0 for
       complete success, and non-zero on failure.

           static int
           wombat_gen( or, ir, in )
           REGION *or, *ir;
           IMAGE *in;
               ... process!

               return( 0 );

           im_wombat( in, out )
           IMAGE *in, *out;
               if( im_iocheck( in, out ) )
                   return( -1 );

               ... check parametersm check image descriptors
               ... for type-compatibility, etc. etc.

               if( im_cp_desc( out, in ) )
                   return( -1 );

               ... set fields in out for the type of image you
               ... wish to write

               if( im_generate( out,
                   im_start_one, wombat_gen, im_stop_one,
                   in, NULL ) )
                   return( -1 );

               return( 0 );

       See also the source to im_invert(3),  im_exptra(3),  and,  if  you  are
       brave, im_conv(3) or im_add(3).

       On   machines  with  several  CPUs,  im_generate(3)  and  im_iterate(3)
       automatically parallelise programs. You can set the desired concurrency
       level with the environment variable IM_CONCURRENCY, for example

           example% export IM_CONCURRENCY=2
           example% lintra 2.0 fred.v 0.0 fred2.v

       will  run lintra with enough concurrency to keep 2 CPUs fully occupied.
       If IM_CONCURRENCY  is  not  set,  then  it  defaults  to  1.  See  also

       Most  programs  which  use  VIPS will also let you use the command-line
       argument    --vips-concurrency    to    set    parallelisation,     see


       National Gallery, 1993


       im_wrapone(3),  im_add_eval_callback(3), im_iterate(3), im_piocheck(3),
       im_concurrency_set(3),  im_get_option_group(3),   ‘VIPS   manual,’   in
       accompanying documentation.


       J. Cupitt - 23/7/93

                                 11 April 1993                  IM_GENERATE(3)