![]() |
![]() |
![]() |
VIPS Reference Manual | ![]() |
---|---|---|---|---|
Top | Description |
#include <vips/vips.h> int im_prepare (REGION *reg
,Rect *r
); int im_prepare_to (REGION *reg
,REGION *dest
,Rect *r
,int x
,int y
); void * (*im_start_fn) (IMAGE *out
,void *a
,void *b
); int (*im_generate_fn) (REGION *out
,void *seq
,void *a
,void *b
); int (*im_stop_fn) (void *seq
,void *a
,void *b
); void * im_start_one (IMAGE *out
,void *in
,void *dummy
); int im_stop_one (void *seq
,void *dummy1
,void *dummy2
); void * im_start_many (IMAGE *out
,void *in
,void *dummy
); int im_stop_many (void *seq
,void *dummy1
,void *dummy2
); IMAGE ** im_allocate_input_array (IMAGE *out
,...
); int im_generate (IMAGE *im
,im_start_fn start
,im_generate_fn generate
,im_stop_fn stop
,void *a
,void *b
); int im_iterate (IMAGE *im
,im_start_fn start
,im_generate_fn generate
,im_stop_fn stop
,void *a
,void *b
); int im_demand_hint_array (IMAGE *im
,im_demand_type hint
,IMAGE **in
); int im_demand_hint (IMAGE *im
,im_demand_type hint
,...
); void (*im_wrapone_fn) (void *in
,void *out
,int width
,void *a
,void *b
); int im_wrapone (IMAGE *in
,IMAGE *out
,im_wrapone_fn fn
,void *a
,void *b
); void (*im_wraptwo_fn) (void *in1
,void *in2
,void *out
,int width
,void *a
,void *b
); int im_wraptwo (IMAGE *in1
,IMAGE *in2
,IMAGE *out
,im_wraptwo_fn fn
,void *a
,void *b
); void (*im_wrapmany_fn) (void **in
,void *out
,int width
,void *a
,void *b
); int im_wrapmany (IMAGE **in
,IMAGE *out
,im_wrapmany_fn fn
,void *a
,void *b
); int im_render_priority (IMAGE *in
,IMAGE *out
,IMAGE *mask
,int width
,int height
,int max
,int priority
,void (notify IMAGE *, Rect *, void * ) ()
,void *client
); int im_cache (IMAGE *in
,IMAGE *out
,int width
,int height
,int max
); int im_setupout (IMAGE *im
); int im_writeline (int ypos
,IMAGE *im
,PEL *linebuffer
);
These functions let you generate regions of pixels in an image processing operation, and ask for regions of image to be calculated.
int im_prepare (REGION *reg
,Rect *r
);
im_prepare()
fills reg
with pixels. After calling, you can address at
least the area r
with IM_REGION_ADDR()
and get valid pixels.
im_prepare()
runs in-line, that is, computation is done by the calling
thread, no new threads are involved, and computation blocks until the
pixels are ready.
Use im_prepare_thread()
to calculate an area of pixels with many
threads. Use im_render_priority()
to calculate an area of pixels in the
background.
See also: im_prepare_thread()
, im_render_priority()
, im_prepare_to()
.
|
region to prepare |
|
Rect of pixels you need to be able to address |
Returns : |
0 on success, or -1 on error. |
int im_prepare_to (REGION *reg
,REGION *dest
,Rect *r
,int x
,int y
);
Like im_prepare()
: fill reg
with data, ready to be read from by our caller.
Unlike im_prepare()
, rather than allocating memory local to reg
for the
result, we guarantee that we will fill the pixels in dest
at offset x
, y
.
In other words, we generate an extra copy operation if necessary.
Also unlike im_prepare()
, dest
is not set up for writing for you with
im_region_buffer()
. You can
point dest
at anything, and pixels really will be written there.
This makes im_prepare_to()
useful for making the ends of pipelines, since
it (effectively) makes a break in the pipe.
See also: im_prepare()
, vips_sink_disc()
.
|
region to prepare |
|
region to write to |
|
Rect of pixels you need to be able to address |
|
postion of r in dest
|
|
postion of r in dest
|
Returns : |
0 on success, or -1 on error |
void * (*im_start_fn) (IMAGE *out
,void *a
,void *b
);
Start a new processing sequence for this generate function. This allocates per-thread state, such as an input region.
See also: im_start_one()
, im_start_many()
.
|
image being calculated |
|
user data |
|
user data |
Returns : |
a new sequence value |
int (*im_generate_fn) (REGION *out
,void *seq
,void *a
,void *b
);
Fill out->valid
with pixels. seq
contains per-thread state, such as the
input regions.
See also: im_generate()
, im_stop_many()
.
|
REGION to fill |
|
sequence value |
|
user data |
|
user data |
Returns : |
0 on success, -1 on error. |
int (*im_stop_fn) (void *seq
,void *a
,void *b
);
Stop a processing sequence. This frees per-thread state, such as an input region.
See also: im_stop_one()
, im_stop_many()
.
|
sequence value |
|
user data |
|
user data |
Returns : |
0 on success, -1 on error. |
void * im_start_one (IMAGE *out
,void *in
,void *dummy
);
Start function for one image in. Input image is first user data.
See also: im_generate()
.
int im_stop_one (void *seq
,void *dummy1
,void *dummy2
);
Stop function for one image in. Input image is first user data.
See also: im_generate()
.
void * im_start_many (IMAGE *out
,void *in
,void *dummy
);
Start function for many images in. First client is a pointer to
a NULL
-terminated array of input images.
See also: im_generate()
, im_allocate_input_array()
int im_stop_many (void *seq
,void *dummy1
,void *dummy2
);
Stop function for many images in. First client is a pointer to
a NULL
-terminated array of input images.
See also: im_generate()
.
IMAGE ** im_allocate_input_array (IMAGE *out
,...
);
Convenience function --- make a NULL
-terminated array of input images.
Use with im_start_many()
.
See also: im_generate()
, im_start_many()
.
int im_generate (IMAGE *im
,im_start_fn start
,im_generate_fn generate
,im_stop_fn stop
,void *a
,void *b
);
Generates an image. The action depends on the image type.
For images opened with "p", im_generate()
just attaches the
start/generate/stop callbacks and returns.
For "t" images, memory is allocated for the whole image and it is entirely
generated using vips_sink()
.
For "w" images, memory for a few scanlines is allocated and
vips_sink_disc()
used to generate the image in small chunks. As each
chunk is generated, it is written to disc.
See also: vips_sink()
, im_open()
, im_prepare()
, im_wrapone()
.
|
generate this image |
|
start sequences with this function |
|
generate pixels with this function |
|
stop sequences with this function |
|
user data |
|
user data |
Returns : |
0 on success, or -1 on error. |
int im_iterate (IMAGE *im
,im_start_fn start
,im_generate_fn generate
,im_stop_fn stop
,void *a
,void *b
);
int im_demand_hint_array (IMAGE *im
,im_demand_type hint
,IMAGE **in
);
Operations can set demand hints, that is, hints to the VIPS IO system about
the type of region geometry this operation works best with. For example,
operations which transform coordinates will usually work best with
IM_SMALLTILE
, operations which work on local windows of pixels will like
IM_FATSTRIP
.
VIPS uses the list of input images to build the tree of operations it needs
for the cache invalidation system. You have to call this function, or its
varargs friend im_demand_hint()
.
See also: im_demand_hint()
, im_generate()
.
|
image to set hint for |
|
hint for this image |
|
array of input images to this operation |
Returns : |
0 on success, or -1 on error. |
int im_demand_hint (IMAGE *im
,im_demand_type hint
,...
);
Build an array and call im_demand_hint_array()
.
See also: im_demand_hint()
, im_generate()
.
|
image to set hint for |
|
hint for this image |
|
NULL -terminated list of input images to this operation
|
Returns : |
0 on success, or -1 on error. |
void (*im_wrapone_fn) (void *in
,void *out
,int width
,void *a
,void *b
);
Given a buffer of input pixels, write a buffer of output pixels.
|
input pixels |
|
write processed pixels here |
|
number of pixels in buffer |
|
user data |
|
user data |
int im_wrapone (IMAGE *in
,IMAGE *out
,im_wrapone_fn fn
,void *a
,void *b
);
Wrap-up a buffer processing function as a PIO VIPS function.
Given an input image, an output image and a buffer processing function, make a PIO image processing operation.
See also: im_wrapmany()
, im_wraptwo()
, im_generate()
.
|
input image |
|
image to generate |
|
buffer-processing function |
|
user data |
|
user data |
Returns : |
0 on success, or -1 on error. |
void (*im_wraptwo_fn) (void *in1
,void *in2
,void *out
,int width
,void *a
,void *b
);
Given a pair of buffers of input pixels, write a buffer of output pixels.
|
input pixels from image 1 |
|
input pixels from image 2 |
|
write processed pixels here |
|
number of pixels in buffer |
|
user data |
|
user data |
int im_wraptwo (IMAGE *in1
,IMAGE *in2
,IMAGE *out
,im_wraptwo_fn fn
,void *a
,void *b
);
Wrap-up a buffer processing function as a PIO VIPS function.
Given a pair of input images of the same size, an output image and a buffer processing function, make a PIO image processing operation.
See also: im_wrapone()
, im_wrapmany()
, im_generate()
.
|
first input image |
|
second input image |
|
image to generate |
|
buffer-processing function |
|
user data |
|
user data |
Returns : |
0 on success, or -1 on error. |
void (*im_wrapmany_fn) (void **in
,void *out
,int width
,void *a
,void *b
);
Given an array of buffers of input pixels, write a buffer of output pixels.
|
NULL -terminated array of input buffers
|
|
write processed pixels here |
|
number of pixels in buffer |
|
user data |
|
user data |
int im_wrapmany (IMAGE **in
,IMAGE *out
,im_wrapmany_fn fn
,void *a
,void *b
);
Wrap-up a buffer processing function as a PIO VIPS function.
Given a NULL-terminated list of input images all of the same size, an output image and a buffer processing function, make a PIO image processing operation.
See also: im_wrapone()
, im_wraptwo()
, im_generate()
.
|
NULL -terminated array of input images
|
|
image to generate |
|
buffer-processing function |
|
user data |
|
user data |
Returns : |
0 on success, or -1 on error. |
int im_render_priority (IMAGE *in
,IMAGE *out
,IMAGE *mask
,int width
,int height
,int max
,int priority
,void (notify IMAGE *, Rect *, void * ) ()
,void *client
);
int im_setupout (IMAGE *im
);
This call gets the IMAGE ready for scanline-based writing with
im_writeline()
. You need to have set all the image fields, such as Xsize
and BandFmt
, before calling this.
See also: im_writeline()
, im_generate()
, im_initdesc()
, im_cp_desc()
.
|
image to prepare for writing |
Returns : |
0 on success, or -1 on error. |
int im_writeline (int ypos
,IMAGE *im
,PEL *linebuffer
);
Write a line of pixels to an image. This function must be called repeatedly
with ypos
increasing from 0 to YSize
-
1. linebuffer
must be IM_IMAGE_SIZEOF_LINE()
bytes long.
See also: im_setupout()
, im_generate()
.
|
vertical position of scan-line to write |
|
image to write to |
|
scanline of pixels |
Returns : |
0 on success, or -1 on error. |