Man Linux: Main Page and Category List

NAME

       im_prepare, im_prepare_to - fill region with data

SYNOPSIS

       #include <vips/vips.h>

       int im_prepare( reg, r )
       REGION *reg;
       Rect *r;

       int im_prepare_to( reg, dest, r, x, y )
       REGION *reg, *dest;
       Rect *r;
       int x, y;

       int im_prepare_many( reg, r )
       REGION **reg;
       Rect *r;

DESCRIPTION

       im_prepare(3) fills region reg with pels covering the area inside r.

       r  is  expected to lie within the image on which reg was defined; if it
       does not it will be clipped against the size of the image. Consequence:
       if

           im_prepare( reg, r )

       succeeds,  VIPS guarantees that pels within reg->valid may be read from
       reg with IM_REGION_ADDR(3).  It does not guarantee that  you  may  read
       all of r!

       The  action taken by im_prepare(3) depends upon the image descriptor on
       which reg was defined:

       PARTIAL: The area requested is clipped against the edges of the  image,
       local  memory is attached to reg with im_region_buffer(3) and that area
       requested from the image’s generate function, see  im_generate(3).   If
       necessary, a new sequence is started.

       SETBUF:  MMAPIN: MMAPINRW: The area defined by r is clipped against the
       edges of the image, and that area attached to reg.

       im_prepare_to(3) is very like im_prepare(3), but  rather  than  writing
       pixels  to local memory on reg (or attaching reg to some other piece of
       memory), it instead writes pixels into the region dest at  position  x,
       y.  The  parameters  dest,  r,  x,  y  behave  in  the  same way as the
       paramaters to im_region_region(3).

       Effectively, it’s just like im_prepare(3) followed by a copy operation.
       Except that the copy will be skipped when possible.

       This  call  is used by (among others) im_generate(3) to make operations
       output to disc buffers, and by im_embed(3) to get images written inside
       larger images.

       im_prepare_many(3) prepares the same Rect on a NULL terminated array of
       REGION pointers, as returned by im_start_many(3).

RETURN VALUE

       The function returns 0 on success and non-zero on error.

SEE ALSO

       im_generate(3), im_open(3).

COPYRIGHT

       National Gallery

AUTHOR

       J. Cupitt - 23/7/93

                                 11 April 1990                   IM_PREPARE(3)