| .TH IM_PREPARE 3 "11 April 1990" |
| .SH NAME |
| im_prepare, im_prepare_to \- fill region with data |
| .SH SYNOPSIS |
| .B #include <vips/vips.h> |
| |
| int im_prepare( reg, r ) |
| .br |
| REGION *reg; |
| .br |
| Rect *r; |
| |
| int im_prepare_to( reg, dest, r, x, y ) |
| .br |
| REGION *reg, *dest; |
| .br |
| Rect *r; |
| .br |
| int x, y; |
| |
| int im_prepare_many( reg, r ) |
| .br |
| REGION **reg; |
| .br |
| Rect *r; |
| |
| .SH DESCRIPTION |
| .B 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 |
| .B 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 |
| .B im_region_buffer(3) |
| and that area requested |
| from the image's generate function, see |
| .B 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. |
| |
| .B im_prepare_to(3) |
| is very like |
| .B 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 |
| .B im_region_region(3). |
| |
| Effectively, it's just like |
| .B im_prepare(3) |
| followed by a copy operation. Except that the copy will be skipped when |
| possible. |
| |
| This call is used by (among others) |
| .B im_generate(3) |
| to make operations output to |
| disc buffers, and by |
| .B im_embed(3) |
| to get images written inside larger images. |
| |
| .B im_prepare_many(3) |
| prepares the same Rect on a NULL terminated array of REGION pointers, as |
| returned by |
| .BR im_start_many(3) . |
| |
| .SH RETURN VALUE |
| The function returns 0 on success and non-zero on error. |
| .SH SEE ALSO |
| im_generate(3), im_open(3). |
| .SH COPYRIGHT |
| National Gallery |
| .SH AUTHOR |
| J. Cupitt \- 23/7/93 |
