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.

Also unlike im_prepare(), dest is not set up for writing for you with im_region_buffer(). You can point dest at anything, and pixels really will be written there. This makes im_prepare_to() useful for making the ends of pipelines, since it (effectively) makes a break in the pipe.

See also: im_prepare(), vips_sink_disc().

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

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

im_cache ()

int                 im_cache                            (IMAGE *in,
                                                         IMAGE *out,
                                                         int width,
                                                         int height,
                                                         int max);

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