1IM_PREPARE(3)              Library Functions Manual              IM_PREPARE(3)
2
3
4

NAME

6       im_prepare, im_prepare_to - fill region with data
7

SYNOPSIS

9       #include <vips/vips.h>
10       #include <vips/region.h>
11
12       int im_prepare( reg, r )
13       REGION *reg;
14       Rect *r;
15
16       int im_prepare_to( reg, dest, r, x, y )
17       REGION *reg, *dest;
18       Rect *r;
19       int x, y;
20
21

DESCRIPTION

23       im_prepare(3)  fills  region  reg with pels covering the area inside r.
24       See `VIPS Library Programmers' Guide,' in the  accompanying  documenta‐
25       tion for an introduction to this call.
26
27       r  is  expected to lie within the image on which reg was defined; if it
28       does not it will be clipped against the size of the image. Consequence:
29       if
30
31           im_prepare( reg, r )
32
33       succeeds,  VIPS guarantees that pels within reg->valid may be read from
34       reg with IM_REGION_ADDR(3).  It does not guarantee that  you  may  read
35       all of r!
36
37       The  action taken by im_prepare(3) depends upon the image descriptor on
38       which reg was defined:
39
40       PARTIAL: The area requested is clipped against the edges of the  image,
41       local  memory  is attached to reg with im_region_local(3) and that area
42       requested from the image's generate function, see  im_generate(3).   If
43       necessary, a new sequence is started.
44
45       SETBUF:  MMAPIN: MMAPINRW: The area defined by r is clipped against the
46       edges of the image, and that area attached to reg.
47
48       im_prepare_to(3) is very like im_prepare(3), but  rather  than  writing
49       pixels  to local memory on reg (or attaching reg to some other piece of
50       memory), it instead writes pixels into the region dest at  position  x,
51       y.  The  parameters  dest,  r, x, y behave in the same way as the para‐
52       maters to im_region_region(3).
53
54       Effectively, it's just like im_prepare(3) followed by a copy operation.
55       Except that the copy will be skipped when possible.
56
57       This  call  is used by (among others) im_generate(3) to make operations
58       output to disc buffers, and by im_embed(3) to get images written inside
59       larger images.
60
61

RETURN VALUE

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

SEE ALSO

66       im_generate(3),  im_open(3).  `VIPS  Library  Programmers'  Guide,'  in
67       accompanying documentation.
68

70       National Gallery
71

AUTHOR

73       J. Cupitt - 23/7/93
74
75
76
77                                 11 April 1990                   IM_PREPARE(3)
Impressum