## generate

generate — calculate pixels and pixel buffers

## Stability Level

Stable, unless otherwise indicated

## Synopsis

    #include <vips/vips.h>

    void *              (*VipsStartFn)                      (VipsImage *out,
                                                             void *a,
                                                             void *b);
    int                 (*VipsGenerateFn)                   (VipsRegion *out,
                                                             void *seq,
                                                             void *a,
                                                             void *b);
    int                 (*VipsStopFn)                       (void *seq,
                                                             void *a,
                                                             void *b);
    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,
                                                             VipsGenerateFn generate,
                                                             VipsStopFn stop,
                                                             void *a,
                                                             void *b);
    int                 vips_demand_hint_array              (VipsImage *image,
                                                             VipsDemandStyle hint,
                                                             VipsImage **in);
    int                 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

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

`image` : | image being calculated
`a` : | user data
`b` : | user data
Returns : | a new sequence value

### VipsGenerateFn ()

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

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

See also: `vips_image_generate()`, `vips_stop_many()`.

`region` : | VipsRegion to fill
`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_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()`.

`image` : | 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 *im,
                                                             VipsStartFn start,
                                                             VipsGenerateFn generate,
                                                             VipsStopFn stop,
                                                             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()`.

`image` : | 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.

### vips_demand_hint_array ()

    int                 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
Returns : | 0 on success, or -1 on error.

### vips_demand_hint ()

    int                 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
`...` : | `NULL`-terminated list of input images to this operation
Returns : | 0 on success, or -1 on error.

## See Also

image, region