manpagez: man pages & more
man im_allocate_input_array(3)
Home | html | info | man
im_generate(3)                                                  im_generate(3)




NAME

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


SYNOPSIS

       #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;


DESCRIPTION

       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-ter-
       minated  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-ter-
       minated 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
       patches.

           IM_OPENOUT: The output file is created  and  a  header  written  to
       disc. A buffer large enough to hold GENERATE_TILE_HEIGHT complete hori-
       zontal 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
       lines.

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

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

               return( 0 );
           }

           int
           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) auto-
       matically 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  im_con-
       currency_set(3).

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



COPYRIGHT

       National Gallery, 1993


SEE ALSO

       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 accom-
       panying documentation.


AUTHOR

       J. Cupitt - 23/7/93



                                 11 April 1993                  im_generate(3)

im_generate 7.14.5 - Generated Fri Sep 5 19:51:17 CDT 2008
© manpagez.com 2000-2024
Individual documents may contain additional copyright information.