generate: libvips Reference Manual

## generate generate — calculate pixels and pixel buffers |

## Stability Level

Stable, unless otherwise indicated

## Functions

int | (*VipsRegionWrite) ()
int | vips_sink_disc ()
int | vips_sink ()
int | vips_sink_tile ()
void | (*VipsSinkNotify) ()
int | vips_sink_screen ()
int | vips_sink_memory ()
void * | vips_start_one ()
int | vips_stop_one ()
void * | vips_start_many ()
int | vips_stop_many ()
VipsImage ** | vips_allocate_input_array ()
int | vips_image_generate ()
int | vips_image_pipeline_array ()
int | vips_image_pipelinev ()

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

<link linkend="VipsImage">VipsImage</link>, <link linkend="VipsRegion">VipsRegion</link>