![]() |
![]() |
![]() |
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.
See also: im_prepare()
.
|
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 image and im_prepare_thread()
used to fill it with pixels.
For "w" images, memory for a few scanlines is allocated and
im_prepare_thread()
used to generate the image in small chunks. As each
chunk is generated, it is written to disc.
See also: im_iterate()
, 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);
Loops over an image. generate
is called for every pixel in the image, with
the reg
argument being a region of pixels for processing. im_iterate()
is
used to implement operations like im_avg()
which have no image output.
See also: im_generate()
, im_open()
.
|
scan over 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_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);
This operation renders in
in the background, making pixels available on
out
as they are calculated. The notify
callback is run every time a new
set of pixels are available. Calculated pixels are kept in a cache with
tiles sized width
by height
pixels and at most max
tiles.
If max
is -1, the cache is of unlimited size (up to the maximum image
size).
The mask
image s a one-band uchar image and has 255 for pixels which are
currently in cache and 0 for uncalculated pixels.
The pixel rendering system has a single global im_threadgroup_t which is
used for all currently active instances of im_render_priority()
. As
renderers are added and removed from the system, the threadgroup switches
between renderers based on their priority setting. Zero means normal
priority, negative numbers are low priority, positive numbers high
priority.
Calls to im_prepare()
on out
return immediately and hold whatever is
currently in cache for that Rect (check mask
to see which parts of the
Rect are valid). Any pixels in the Rect which are not in cache are added
to a queue, and the notify
callback will trigger when those pixels are
ready.
The notify
callback is run from the background thread. In the callback,
you need to somehow send a message to the main thread that the pixels are
ready. In a glib-based application, this is easily done with g_idle_add()
.
If notify
is NULL
, then im_render_priority()
runs synchronously.
im_prepare()
on out
will always block until the pixels have been
calculated by the background im_threadgroup_t.
See also: im_cache()
, im_prepare()
.
|
input image |
|
output image |
|
mask image indicating valid pixels |
|
tile width |
|
tile height |
|
maximum tiles to cache |
|
rendering priority |
|
pixels are ready notification callback |
|
client data for callback |
Returns : |
0 on sucess, -1 on error. |
int im_cache (IMAGE *in, IMAGE *out, int width, int height, int max);
im_cache()
works exactly as im_copy()
, except that calculated pixels are
kept in a cache. If in
is the result of a large computation and you are
expecting to reuse the result in a number of places, im_cache()
can save a
lot of time.
im_cache()
is a convenience function over im_render_priority()
.
See also: im_render_priority()
, im_copy()
, im_prepare_thread()
.
|
input image |
|
output image |
|
tile width |
|
tile height |
|
maximum tiles to cache |
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. |