generate

generate — calculate pixels and pixel buffers

Stability Level

Stable, unless otherwise indicated

Synopsis

#include <vips/vips.h>

int                 (*VipsRegionWrite)                  (VipsRegion *region,
                                                         VipsRect *area,
                                                         void *a);
int                 vips_sink_disc                      (VipsImage *im,
                                                         VipsRegionWrite write_fn,
                                                         void *a);
void *              (*VipsStartFn)                      (VipsImage *out,
                                                         void *a,
                                                         void *b);
int                 (*VipsGenerateFn)                   (VipsRegion *out,
                                                         void *seq,
                                                         void *a,
                                                         void *b,
                                                         gboolean *stop);
int                 (*VipsStopFn)                       (void *seq,
                                                         void *a,
                                                         void *b);
int                 vips_sink                           (VipsImage *im,
                                                         VipsStartFn start_fn,
                                                         VipsGenerateFn generate_fn,
                                                         VipsStopFn stop_fn,
                                                         void *a,
                                                         void *b);
int                 vips_sink_tile                      (VipsImage *im,
                                                         int tile_width,
                                                         int tile_height,
                                                         VipsStartFn start_fn,
                                                         VipsGenerateFn generate_fn,
                                                         VipsStopFn stop_fn,
                                                         void *a,
                                                         void *b);
void                (*VipsSinkNotify)                   (VipsImage *im,
                                                         VipsRect *rect,
                                                         void *a);
int                 vips_sink_screen                    (VipsImage *in,
                                                         VipsImage *out,
                                                         VipsImage *mask,
                                                         int tile_width,
                                                         int tile_height,
                                                         int max_tiles,
                                                         int priority,
                                                         VipsSinkNotify notify,
                                                         void *a);
int                 vips_sink_memory                    (VipsImage *im);
int                 vips_sink_memory2                   (VipsImage *image);
void *              vips_start_one                      (VipsImage *out,
                                                         void *a,
                                                         void *b);
int                 vips_stop_one                       (void *seq,
                                                         void *a,
                                                         void *b);
void *              vips_start_many                     (VipsImage *out,
                                                         void *a,
                                                         void *b);
int                 vips_stop_many                      (void *seq,
                                                         void *a,
                                                         void *b);
VipsImage **        vips_allocate_input_array           (VipsImage *out,
                                                         ...);
int                 vips_image_generate                 (VipsImage *im,
                                                         VipsStartFn start_fn,
                                                         VipsGenerateFn generate_fn,
                                                         VipsStopFn stop_fn,
                                                         void *a,
                                                         void *b);
void                vips_demand_hint_array              (VipsImage *image,
                                                         VipsDemandStyle hint,
                                                         VipsImage **in);
void                vips_demand_hint                    (VipsImage *image,
                                                         VipsDemandStyle hint,
                                                         ...);

Description

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

Details

VipsRegionWrite ()

int                 (*VipsRegionWrite)                  (VipsRegion *region,
                                                         VipsRect *area,
                                                         void *a);

The function should write the pixels in area from region. a is the value passed into vips_discsink().

See also: vips_sink_disc().

region :

get pixels from here

area :

area to write

a :

client data

Returns :

0 on success, -1 on error.

vips_sink_disc ()

int                 vips_sink_disc                      (VipsImage *im,
                                                         VipsRegionWrite write_fn,
                                                         void *a);

vips_sink_disc() loops over im, top-to-bottom, generating it in sections. As each section is produced, write_fn is called.

write_fn is always called single-threaded (though not always from the same thread), it's always given image sections in top-to-bottom order, and there are never any gaps.

This operation is handy for making image sinks which output to things like disc files.

See also: vips_concurrency_set().

im :

image to process

write_fn :

called for every batch of pixels

a :

client data

Returns :

0 on success, -1 on error.

VipsStartFn ()

void *              (*VipsStartFn)                      (VipsImage *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: vips_start_one(), vips_start_many().

a :

user data

b :

user data

Returns :

a new sequence value

VipsGenerateFn ()

int                 (*VipsGenerateFn)                   (VipsRegion *out,
                                                         void *seq,
                                                         void *a,
                                                         void *b,
                                                         gboolean *stop);

Fill image->valid with pixels. seq contains per-thread state, such as the input regions.

See also: vips_image_generate(), vips_stop_many().

seq :

sequence value

a :

user data

b :

user data

Returns :

0 on success, -1 on error.

VipsStopFn ()

int                 (*VipsStopFn)                       (void *seq,
                                                         void *a,
                                                         void *b);

Stop a processing sequence. This frees per-thread state, such as an input region.

See also: vips_stop_one(), vips_stop_many().

seq :

sequence value

a :

user data

b :

user data

Returns :

0 on success, -1 on error.

vips_sink ()

int                 vips_sink                           (VipsImage *im,
                                                         VipsStartFn start_fn,
                                                         VipsGenerateFn generate_fn,
                                                         VipsStopFn stop_fn,
                                                         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. vips_sink() is used to implement operations like VipsAvg which have no image output.

Each set of pixels is sized according to the requirements of the image pipeline that generated im.

See also: vips_image_generate(), vips_image_new().

im :

scan over this image

start_fn :

start sequences with this function

generate_fn :

generate pixels with this function

stop_fn :

stop sequences with this function

a :

user data

b :

user data

Returns :

0 on success, or -1 on error.

vips_sink_tile ()

int                 vips_sink_tile                      (VipsImage *im,
                                                         int tile_width,
                                                         int tile_height,
                                                         VipsStartFn start_fn,
                                                         VipsGenerateFn generate_fn,
                                                         VipsStopFn stop_fn,
                                                         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.

Each set of pixels is tile_width by tile_height pixels (less at the image edges). This is handy for things like writing a tiled TIFF image, where tiles have to be generated with a certain size.

See also: vips_sink(), vips_get_tile_size().

im :

scan over this image

tile_width :

tile width

tile_height :

tile height

start_fn :

start sequences with this function

generate_fn :

generate pixels with this function

stop_fn :

stop sequences with this function

a :

user data

b :

user data

Returns :

0 on success, or -1 on error.

VipsSinkNotify ()

void                (*VipsSinkNotify)                   (VipsImage *im,
                                                         VipsRect *rect,
                                                         void *a);


vips_sink_screen ()

int                 vips_sink_screen                    (VipsImage *in,
                                                         VipsImage *out,
                                                         VipsImage *mask,
                                                         int tile_width,
                                                         int tile_height,
                                                         int max_tiles,
                                                         int priority,
                                                         VipsSinkNotify notify,
                                                         void *a);

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 tile_width by tile_height pixels and with at most max_tiles tiles. If max_tiles is -1, the cache is of unlimited size (up to the maximum image size). The mask image is a one-band uchar image and has 255 for pixels which are currently in cache and 0 for uncalculated pixels.

Only a single sink is calculated at any one time, though many may be alive. Use priority to indicate which renders are more important: zero means normal priority, negative numbers are low priority, positive numbers high priority.

Calls to vips_region_prepare() on out return immediately and hold whatever is currently in cache for that VipsRect (check mask to see which parts of the VipsRect are valid). Any pixels in the VipsRect 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 one of the background threads. 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 vips_sink_screen() runs synchronously. vips_region_prepare() on out will always block until the pixels have been calculated.

See also: vips_tilecache(), vips_region_prepare(), vips_sink_disc(), vips_sink().

in :

input image

out :

output image

mask :

mask image indicating valid pixels

tile_width :

tile width

tile_height :

tile height

max_tiles :

maximum tiles to cache

priority :

rendering priority

notify :

pixels are ready notification callback

a :

client data for callback

Returns :

0 on sucess, -1 on error.

vips_sink_memory ()

int                 vips_sink_memory                    (VipsImage *im);

Loops over an image, generating it to a memory buffer attached to the image.

See also: vips_sink(), vips_get_tile_size().

im :

generate this image to memory

Returns :

0 on success, or -1 on error.

vips_sink_memory2 ()

int                 vips_sink_memory2                   (VipsImage *image);


vips_start_one ()

void *              vips_start_one                      (VipsImage *out,
                                                         void *a,
                                                         void *b);

Start function for one image in. Input image is a.

See also: vips_image_generate().

out :

image to generate

a :

user data

b :

user data

vips_stop_one ()

int                 vips_stop_one                       (void *seq,
                                                         void *a,
                                                         void *b);

Stop function for one image in. Input image is a.

See also: vips_image_generate().

seq :

sequence value

a :

user data

b :

user data

vips_start_many ()

void *              vips_start_many                     (VipsImage *out,
                                                         void *a,
                                                         void *b);

Start function for many images in. a is a pointer to a NULL-terminated array of input images.

See also: vips_image_generate(), vips_allocate_input_array()

out :

image to generate

a :

user data

b :

user data

vips_stop_many ()

int                 vips_stop_many                      (void *seq,
                                                         void *a,
                                                         void *b);

Stop function for many images in. a is a pointer to a NULL-terminated array of input images.

See also: vips_image_generate().

seq :

sequence value

a :

user data

b :

user data

vips_allocate_input_array ()

VipsImage **        vips_allocate_input_array           (VipsImage *out,
                                                         ...);

Convenience function --- make a NULL-terminated array of input images. Use with vips_start_many().

See also: vips_image_generate(), vips_start_many().

Returns :

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

vips_image_generate ()

int                 vips_image_generate                 (VipsImage *im,
                                                         VipsStartFn start_fn,
                                                         VipsGenerateFn generate_fn,
                                                         VipsStopFn stop_fn,
                                                         void *a,
                                                         void *b);

Generates an image. The action depends on the image type.

For images opened with "p", vips_image_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(), vips_image_new(), vips_region_prepare().

start_fn :

start sequences with this function

generate_fn :

generate pixels with this function

stop_fn :

stop sequences with this function

a :

user data

b :

user data

Returns :

0 on success, or -1 on error.

vips_demand_hint_array ()

void                vips_demand_hint_array              (VipsImage *image,
                                                         VipsDemandStyle hint,
                                                         VipsImage **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 VIPS_DEMAND_STYLE_SMALLTILE, operations which work on local windows of pixels will like VIPS_DEMAND_STYLE_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 vips_demand_hint().

See also: vips_demand_hint(), vips_image_generate().

image :

image to set hint for

hint :

hint for this image

in :

array of input images to this operation

vips_demand_hint ()

void                vips_demand_hint                    (VipsImage *image,
                                                         VipsDemandStyle hint,
                                                         ...);

Build an array and call vips_demand_hint_array().

See also: vips_demand_hint(), vips_image_generate().

image :

image to set hint for

hint :

hint for this image

See Also

image, region