generate

generate — calculate pixels and pixel buffers

Stability Level

Stable, unless otherwise indicated

Includes

#include <vips/vips.h>

Description

These functions let you attach generate functions to images and ask for regions of images to be calculated.

Functions

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

See also: vips_sink_disc().

Parameters

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. Things like vips_jpegsave(), for example, use this to write images to files in JPEG format.

See also: vips_concurrency_set().

[method]

Parameters

im

image to process

 

write_fn

called for every batch of pixels.

[scope call]

a

client data.

[closure write_fn]

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_fn is called for every pixel in the image, with the reg argument being a region of calculated pixels. vips_sink() is used to implement operations like vips_avg() 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().

[method]

Parameters

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_fn is called for every pixel in the image, with the reg argument being a region of calculated pixels.

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

[method]

Parameters

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_fn,
                  void *a);

This operation renders in in the background, making pixels available on out as they are calculated. The notify_fn 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_fn callback will trigger when those pixels are ready.

The notify_fn 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_fn 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().

[method]

Parameters

in

input image

 

out

output image.

[out]

mask

mask image indicating valid pixels

 

tile_width

tile width

 

tile_height

tile height

 

max_tiles

maximum tiles to cache

 

priority

rendering priority

 

notify_fn

pixels are ready notification callback.

[scope call][nullable]

a

client data for callback.

[closure notify_fn][nullable]

Returns

0 on sucess, -1 on error.


vips_sink_memory ()

int
vips_sink_memory (VipsImage *im);

Loops over im , generating it to a memory buffer attached to im . It is used by vips to implement writing to a memory buffer.

See also: vips_sink(), vips_get_tile_size(), vips_image_new_memory().

Parameters

im

generate this image to memory

 

Returns

0 on success, or -1 on error.


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

Parameters

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

Parameters

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

Parameters

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

Parameters

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

Parameters

out

free array when this image closes

 

...

NULL-terminated list of input images

 

Returns

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


vips_image_generate ()

int
vips_image_generate (VipsImage *image,
                     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 created with vips_image_new(), vips_image_generate() just attaches the start/generate/stop callbacks and returns.

For images created with vips_image_new_memory(), memory is allocated for the whole image and it is entirely generated using vips_sink_memory().

For images created with vips_image_new_temp_file() and friends, 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().

Parameters

image

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

int
vips_image_pipeline_array (VipsImage *image,
                           VipsDemandStyle hint,
                           VipsImage **in);

Add an image to a pipeline. image depends on all of the images in in , image prefers to supply pixels according to hint .

Operations can set demand hints, that is, hints to the VIPS IO system about the type of region geometry they work 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.

Header fields in image are set from the fields in in , with lower-numbered images in in taking priority. For example, if in [0] and in [1] both have an item called "icc-profile", it's the profile attached to in [0] that will end up on image . Image history is completely copied from all in . image will have the history of all the input images. The array of input images can be empty, meaning image is at the start of a pipeline.

VIPS uses the list of input images to build the tree of operations it needs for the cache invalidation system.

See also: vips_image_pipelinev(), vips_image_generate().

Parameters

image

output image.

[out]

hint

demand hint for image

 

in

NULL-terminated array of input images.

[array zero-terminated=1]

Returns

0 on success, -1 on error.


vips_image_pipelinev ()

int
vips_image_pipelinev (VipsImage *image,
                      VipsDemandStyle hint,
                      ...);

Build an array and call vips_image_pipeline_array().

See also: vips_image_generate().

Parameters

image

output image of pipeline

 

hint

hint for this image

 

...

NULL-terminated list of input images

 

See Also

VipsImage, VipsRegion