generate

generate — calculate pixels and pixel buffers

Stability Level

Stable, unless otherwise indicated

Synopsis


#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);

Description

These functions let you generate regions of pixels in an image processing operation, and ask for regions of image to be calculated.

Details

im_prepare ()

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().

reg :

region to prepare

r :

Rect of pixels you need to be able to address

Returns :

0 on success, or -1 on error.

im_prepare_to ()

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().

reg :

region to prepare

dest :

region to write to

r :

Rect of pixels you need to be able to address

x :

postion of r in dest

y :

postion of r in dest

Returns :

0 on success, or -1 on error

im_start_fn ()

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().

out :

image being calculated

a :

user data

b :

user data

Returns :

a new sequence value

im_generate_fn ()

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().

out :

REGION to fill

seq :

sequence value

a :

user data

b :

user data

Returns :

0 on success, -1 on error.

im_stop_fn ()

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().

seq :

sequence value

a :

user data

b :

user data

Returns :

0 on success, -1 on error.

im_start_one ()

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().


im_stop_one ()

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().


im_start_many ()

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()


im_stop_many ()

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().


im_allocate_input_array ()

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().

out :

free array when this image closes

... :

NULL-terminated list of input images

Returns :

NULL-terminated array of images. Do not free the result.

im_generate ()

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().

im :

generate this image

start :

start sequences with this function

generate :

generate pixels with this function

stop :

stop sequences with this function

a :

user data

b :

user data

Returns :

0 on success, or -1 on error.

im_iterate ()

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().

im :

scan over this image

start :

start sequences with this function

generate :

generate pixels with this function

stop :

stop sequences with this function

a :

user data

b :

user data

Returns :

0 on success, or -1 on error.

im_demand_hint_array ()

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().

im :

image to set hint for

hint :

hint for this image

in :

array of input images to this operation

Returns :

0 on success, or -1 on error.

im_demand_hint ()

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().

im :

image to set hint for

hint :

hint for this image

... :

NULL-terminated list of input images to this operation

Returns :

0 on success, or -1 on error.

im_wrapone_fn ()

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.

in :

input pixels

out :

write processed pixels here

width :

number of pixels in buffer

a :

user data

b :

user data

im_wrapone ()

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().

in :

input image

out :

image to generate

fn :

buffer-processing function

a :

user data

b :

user data

Returns :

0 on success, or -1 on error.

im_wraptwo_fn ()

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.

in1 :

input pixels from image 1

in2 :

input pixels from image 2

out :

write processed pixels here

width :

number of pixels in buffer

a :

user data

b :

user data

im_wraptwo ()

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().

in1 :

first input image

in2 :

second input image

out :

image to generate

fn :

buffer-processing function

a :

user data

b :

user data

Returns :

0 on success, or -1 on error.

im_wrapmany_fn ()

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.

in :

NULL-terminated array of input buffers

out :

write processed pixels here

width :

number of pixels in buffer

a :

user data

b :

user data

im_wrapmany ()

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().

in :

NULL-terminated array of input images

out :

image to generate

fn :

buffer-processing function

a :

user data

b :

user data

Returns :

0 on success, or -1 on error.

im_render_priority ()

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().

in :

input image

out :

output image

mask :

mask image indicating valid pixels

width :

tile width

height :

tile height

max :

maximum tiles to cache

priority :

rendering priority

notify :

pixels are ready notification callback

client :

client data for callback

Returns :

0 on sucess, -1 on error.

im_cache ()

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().

in :

input image

out :

output image

width :

tile width

height :

tile height

max :

maximum tiles to cache

im_setupout ()

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().

im :

image to prepare for writing

Returns :

0 on success, or -1 on error.

im_writeline ()

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().

ypos :

vertical position of scan-line to write

im :

image to write to

linebuffer :

scanline of pixels

Returns :

0 on success, or -1 on error.

See Also

image, region