VipsImage: libvips Reference Manual

## VipsImage VipsImage — the VIPS image class |

## Stability Level

Stable, unless otherwise indicated

## Functions

void * | (*VipsStartFn) ()
int | (*VipsGenerateFn) ()
int | (*VipsStopFn) ()
#define | VIPS_IMAGE_SIZEOF_ELEMENT()
#define | VIPS_IMAGE_SIZEOF_PEL()
#define | VIPS_IMAGE_SIZEOF_LINE()
#define | VIPS_IMAGE_N_ELEMENTS()
#define | VIPS_IMAGE_N_PELS()
#define | VIPS_IMAGE_ADDR()
#define | VIPS_MATRIX()
void | vips_progress_set ()
void | vips_image_invalidate_all ()
void | vips_image_minimise_all ()
gboolean | vips_image_is_sequential ()
void | vips_image_set_progress ()
gboolean | vips_image_iskilled ()
void | vips_image_set_kill ()
char * | vips_filename_get_filename ()
char * | vips_filename_get_options ()
VipsImage * | vips_image_new ()
VipsImage * | vips_image_new_memory ()
VipsImage * | vips_image_memory ()
VipsImage * | vips_image_new_from_file ()
VipsImage * | vips_image_new_from_file_RW ()
VipsImage * | vips_image_new_from_file_raw ()
VipsImage * | vips_image_new_from_memory ()
VipsImage * | vips_image_new_from_memory_copy ()
VipsImage * | vips_image_new_from_buffer ()
VipsImage * | vips_image_new_from_source ()
VipsImage * | vips_image_new_matrix ()
VipsImage * | vips_image_new_matrixv ()
VipsImage * | vips_image_new_matrix_from_array ()
VipsImage * | vips_image_matrix_from_array ()
VipsImage * | vips_image_new_from_image ()
VipsImage * | vips_image_new_from_image1 ()
void | vips_image_set_delete_on_close ()
guint64 | vips_get_disc_threshold ()
VipsImage * | vips_image_new_temp_file ()
int | vips_image_write ()
int | vips_image_write_to_file ()
int | vips_image_write_to_buffer ()
int | vips_image_write_to_target ()
void * | vips_image_write_to_memory ()
int | vips_image_decode_predict ()
int | vips_image_decode ()
int | vips_image_encode ()
gboolean | vips_image_isMSBfirst ()
gboolean | vips_image_isfile ()
gboolean | vips_image_ispartial ()
gboolean | vips_image_hasalpha ()
VipsImage * | vips_image_copy_memory ()
int | vips_image_wio_input ()
int | vips_image_pio_input ()
int | vips_image_pio_output ()
int | vips_image_inplace ()
int | vips_image_write_prepare ()
int | vips_image_write_line ()
gboolean | vips_band_format_isint ()
gboolean | vips_band_format_isuint ()
gboolean | vips_band_format_is8bit ()
gboolean | vips_band_format_isfloat ()
gboolean | vips_band_format_iscomplex ()
int | vips_system ()
VipsArrayImage * | vips_array_image_new ()
VipsArrayImage * | vips_array_image_newv ()
VipsArrayImage * | vips_array_image_new_from_string ()
VipsArrayImage * | vips_array_image_empty ()
VipsArrayImage * | vips_array_image_append ()
VipsImage ** | vips_array_image_get ()
VipsImage ** | vips_value_get_array_image ()
void | vips_value_set_array_image ()
int | vips_reorder_prepare_many ()
void | vips_reorder_margin_hint ()
void | vips_image_free_buffer ()

## Properties

int | bands | Read / Write
VipsCoding | coding | Read / Write
VipsDemandStyle | demand | Read / Write
char * | filename | Read / Write
gpointer | foreign-buffer | Read / Write
VipsBandFormat | format | Read / Write
int | height | Read / Write
VipsInterpretation | interpretation | Read / Write
gboolean | kill | Read / Write
char * | mode | Read / Write
guint64 | sizeof-header | Read / Write
int | width | Read / Write
int | xoffset | Read / Write
double | xres | Read / Write
int | yoffset | Read / Write
double | yres | Read / Write

## Signals

void | eval | Run Last
void | invalidate | Action
void | minimise | Action
void | posteval | Run Last
void | preeval | Run Last
void | written | Action

## Types and Values

#define | VIPS_MAGIC_INTEL
#define | VIPS_MAGIC_SPARC
#define | VIPS_MAX_COORD
enum | VipsDemandStyle
enum | VipsImageType
enum | VipsInterpretation
enum | VipsBandFormat
enum | VipsCoding
enum | VipsAccess
| VipsProgress

## Object Hierarchy

        GEnum
        ├── VipsAccess
        ├── VipsBandFormat
        ├── VipsCoding
        ├── VipsDemandStyle
        ├── VipsImageType
        ╰── VipsInterpretation
        GObject
        ╰── VipsObject
            ╰── VipsImage

## Includes

    #include <vips/vips.h>

## Description

The image class and associated types and macros.

Images can be created from formatted files on disc, from C-style arrays on disc, from formatted areas of memory, or from C-style arrays in memory. See `vips_image_new_from_file()` and friends. Creating an image is fast. VIPS reads just enough of the image to be able to get the various properties, such as width in pixels. It delays reading any pixels until they are really needed.

Once you have an image, you can get properties from it in the usual way. You can use projection functions, like `vips_image_get_width()` or `g_object_get()`, to get `GObject` properties.

VIPS images are three-dimensional arrays, the dimensions being width, height and bands. Each dimension can be up to 2 ** 31 pixels (or band elements). An image has a format, meaning the machine number type used to represent each value. VIPS supports 10 formats, from 8-bit unsigned integer up to 128-bit double complex, see `vips_image_get_format()`.

In VIPS, images are uninterpreted arrays, meaning that from the point of view of most operations, they are just large collections of numbers. There's no difference between an RGBA (RGB with alpha) image and a CMYK image, for example, they are both just four-band images. It's up to the user of the library to pass the right sort of image to each operation.

To take an example, VIPS has `vips_Lab2XYZ()`, an operation to transform an image from CIE LAB colour space to CIE XYZ space. It assumes the first three bands represent pixels in LAB colour space and returns an image where the first three bands are transformed to XYZ and any remaining bands are just copied. Pass it a RGB image by mistake and you'll just get nonsense.

VIPS has a feature to help (a little) with this: it sets a VipsInterpretation hint for each image (see `vips_image_get_interpretation()`); a hint which says how pixels should be interpreted. For example, `vips_Lab2XYZ()` will set the interpretation of the output image to VIPS_INTERPRETATION_XYZ. A few utility operations will also use interpretation as a guide. For example, you can give `vips_colourspace()` an input image and a desired colourspace and it will use the input's interpretation hint to apply the best sequence of colourspace transforms to get to the desired space.

Use things like `vips_invert()` to manipulate your images. When you are done, you can write images to disc files (with `vips_image_write_to_file()`), to formatted memory buffers (with `vips_image_write_to_buffer()`) and to C-style memory arrays (with `vips_image_write_to_memory()`.

You can also write images to other images. Create, for example, a temporary disc image with `vips_image_new_temp_file()`, then write your image to that with `vips_image_write()`. You can create several other types of image and write to them, see `vips_image_new_memory()`, for example.

See <link linkend="VipsOperation">operation</link> for an introduction to running operations on images, see <link linkend="libvips-header">header</link> for getting and setting image metadata. See <link linkend="VipsObject">object</link> for a discussion of the lower levels.

## Functions

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

#### Parameters

out | 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,
                       gboolean *stop);

Fill `out->valid` with pixels. `seq` contains per-thread state, such as the input regions. Set `stop` to `TRUE` to stop processing.

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

#### Parameters

out | VipsRegion to fill |
seq | sequence value |
a | user data |
b | user data |
stop | set this to stop processing |

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

#### Parameters

seq | sequence value |
a | user data |
b | user data |

#### Returns

0 on success, -1 on error.

### VIPS_IMAGE_SIZEOF_ELEMENT()

    #define             VIPS_IMAGE_SIZEOF_ELEMENT(I)

#### Parameters

I | a VipsImage |

#### Returns

`sizeof()` a band element.

### VIPS_IMAGE_SIZEOF_PEL()

    #define             VIPS_IMAGE_SIZEOF_PEL(I)

#### Parameters

I | a VipsImage |

#### Returns

`sizeof()` a pixel.

### VIPS_IMAGE_SIZEOF_LINE()

    #define             VIPS_IMAGE_SIZEOF_LINE(I)

#### Parameters

I | a VipsImage |

#### Returns

`sizeof()` a scanline of pixels.

### VIPS_IMAGE_N_ELEMENTS()

    #define             VIPS_IMAGE_N_ELEMENTS(I)

#### Parameters

I | a VipsImage |

#### Returns

The number of band elements in a scanline.

### VIPS_IMAGE_N_PELS()

    #define             VIPS_IMAGE_N_PELS(I)

#### Parameters

I | a VipsImage |

#### Returns

The number of pels in an image. A 64-bit unsigned int.

### VIPS_IMAGE_ADDR()

    #define             VIPS_IMAGE_ADDR(I, X, Y)

This macro returns a pointer to a pixel in an image, cast to a VipsPel *. It only works for images which are fully available in memory, so memory buffers and small mapped images only.

If VIPS_DEBUG is defined, you get a version that checks bounds for you.

See also: `vips_image_wio_input()`, `vips_image_inplace()`, `VIPS_REGION_ADDR()`.

#### Parameters

I | a VipsImage |
X | x coordinate |
Y | y coordinate |

#### Returns

The address of pixel (`X` ,`Y` ) in `I` .

### VIPS_MATRIX()

    #define             VIPS_MATRIX(I, X, Y)

This macro returns a pointer to a pixel in an image, cast to a double*. The image must have a single band, be VIPS_FORMAT_DOUBLE and be fully available in memory, so memory buffers and small mapped images only.

If VIPS_DEBUG is defined, you get a version that checks bounds and image type for you.

See also: `vips_image_wio_input()`, `vips_image_inplace()`, `vips_check_matrix()`.

#### Parameters

I | a VipsImage |
X | x coordinate |
Y | y coordinate |

#### Returns

The address of pixel (`X` ,`Y` ) in `I` .

### vips_progress_set ()

    void
    vips_progress_set (gboolean progress);

If set, vips will print messages about the progress of computation to stdout. This can also be enabled with the --vips-progress option, or by setting the environment variable VIPS_PROGRESS.

#### Parameters

progress | `TRUE` to enable progress messages |

### vips_image_invalidate_all ()

    void
    vips_image_invalidate_all (VipsImage *image);

Invalidate all pixel caches on `image` and any downstream images, that is, images which depend on this image. Additionally, all operations which depend upon this image are dropped from the VIPS operation cache.

You should call this function after destructively modifying an image with something like `vips_draw_circle()`.

The “invalidate” signal is emitted for all invalidated images.

See also: `vips_region_invalidate()`.

#### Parameters

image | VipsImage to invalidate |

### vips_image_minimise_all ()

    void
    vips_image_minimise_all (VipsImage *image);

Minimise memory use on this image and any upstream images, that is, images which this image depends upon. This function is called automatically at the end of a computation, but it might be useful to call at other times.

The “minimise” signal is emitted for all minimised images.

#### Parameters

image | VipsImage to minimise |

### vips_image_is_sequential ()

    gboolean
    vips_image_is_sequential (VipsImage *image);

TRUE if any of the images upstream from `image` were opened in sequential mode. Some operations change behaviour slightly in sequential mode to optimize memory behaviour.

#### Parameters

image | VipsImage to minimise |

#### Returns

`TRUE` if `image` is in sequential mode.

### vips_image_set_progress ()

    void
    vips_image_set_progress (VipsImage *image,
                             gboolean progress);

vips signals evaluation progress via the “preeval”, “eval” and “posteval” signals. Progress is signalled on the most-downstream image for which `vips_image_set_progress()` was called.

#### Parameters

image | image to signal progress on |
progress | turn progress reporting on or off |

### vips_image_iskilled ()

    gboolean
    vips_image_iskilled (VipsImage *image);

If `image` has been killed (see `vips_image_set_kill()`), set an error message, clear the VipsImage.kill flag and return `TRUE`. Otherwise return `FALSE`.

Handy for loops which need to run sets of threads which can fail.

See also: `vips_image_set_kill()`.

#### Parameters

image | image to test |

#### Returns

`TRUE` if `image` has been killed.

### vips_image_set_kill ()

    void
    vips_image_set_kill (VipsImage *image,
                         gboolean kill);

Set the VipsImage.kill flag on an image. Handy for stopping sets of threads.

See also: `vips_image_iskilled()`.

#### Parameters

image | image to test |
kill | the kill state |

### vips_filename_get_filename ()

    char *
    vips_filename_get_filename (const char *vips_filename);

Given a vips filename like "fred.jpg[Q=90]", return a new string of just the filename part, "fred.jpg" in this case.

Useful for language bindings.

See also: `vips_filename_get_options()`.

#### Parameters

vips_filename | a filename including a set of options |

#### Returns

transfer full: just the filename component.

### vips_filename_get_options ()

    char *
    vips_filename_get_options (const char *vips_filename);

Given a vips filename like "fred.jpg[Q=90]", return a new string of just the options part, "[Q=90]" in this case.

Useful for language bindings.

See also: `vips_filename_get_filename()`.

#### Parameters

vips_filename | a filename including a set of options |

#### Returns

transfer full: just the options component.

### vips_image_new ()

    VipsImage *
    vips_image_new (void);

vips_image_new() creates a new, empty VipsImage. If you write to one of these images, vips will just attach some callbacks, no pixels will be generated.

Write pixels to an image with `vips_image_generate()` or `vips_image_write_line()`. Write a whole image to another image with `vips_image_write()`.

[constructor]

#### Returns

the new VipsImage, or `NULL` on error.

[transfer full]

### vips_image_new_memory ()

    VipsImage *
    vips_image_new_memory (void);

vips_image_new_memory() creates a new VipsImage which, when written to, will create a memory image.

See also: `vips_image_new()`.

[skip]

#### Returns

the new VipsImage, or `NULL` on error.

[transfer full]

### vips_image_memory ()

    VipsImage *
    vips_image_memory (void);

A renamed `vips_image_new_memory()` ... Some gobject binding systems do not like more than one `_new()` method.

See also: `vips_image_new_memory()`.

[constructor]

#### Returns

the new VipsImage, or `NULL` on error.

[transfer full]

### vips_image_new_from_file ()

    VipsImage *
    vips_image_new_from_file (const char *name,
                              ...);

Optional arguments:

- `access` : hint VipsAccess mode to loader

- `memory` : force load via memory

vips_image_new_from_file() opens `name` for reading. It can load files in many image formats, including VIPS, TIFF, PNG, JPEG, FITS, Matlab, OpenEXR, CSV, WebP, Radiance, RAW, PPM and others.

Load options may be appended to `filename` as "[name=value,...]" or given as a NULL-terminated list of name-value pairs at the end of the arguments. Options given in the function call override options given in the filename. Many loaders add extra options, see `vips_jpegload()`, for example.

vips_image_new_from_file() always returns immediately with the header fields filled in. No pixels are actually read until you first access them.

`access` lets you set a VipsAccess hint giving the expected access pattern for this file. VIPS_ACCESS_RANDOM means you can fetch pixels randomly from the image. This is the default mode. VIPS_ACCESS_SEQUENTIAL means you will read the whole image exactly once, top-to-bottom. In this mode, vips can avoid converting the whole image in one go, for a large memory saving. You are allowed to make small non-local references, so area operations like convolution will work.

In VIPS_ACCESS_RANDOM mode, small images are decompressed to memory and then processed from there. Large images are decompressed to temporary random-access files on disc and then processed from there.

Set `memory` to `TRUE` to force loading via memory. The default is to load large random access images via temporary disc files. See `vips_image_new_temp_file()` for an explanation of how VIPS selects a location for the temporary file.

The disc threshold can be set with the "--vips-disc-threshold" command-line argument, or the `VIPS_DISC_THRESHOLD` environment variable. The value is a simple integer, but can take a unit postfix of "k", "m" or "g" to indicate kilobytes, megabytes or gigabytes. The default threshold is 100 MB.

For example:

    1
    2
    3
    VipsImage *image = vips_image_new_from_file("fred.tif",
        "page", 12,
        NULL);

Will open "fred.tif", reading page 12.

    1
    2
    VipsImage *image = vips_image_new_from_file("fred.jpg[shrink=2]",
        NULL);

Will open "fred.jpg", downsampling by a factor of two.

Use `vips_foreign_find_load()` or `vips_foreign_is_a()` to see what format a file is in and therefore what options are available. If you need more control over the loading process, you can call loaders directly, see `vips_jpegload()`, for example.

See also: `vips_foreign_find_load()`, `vips_foreign_is_a()`, `vips_image_write_to_file()`.

[constructor]

#### Parameters

name | file to open |
... | `NULL`-terminated list of optional named arguments |

#### Returns

the new VipsImage, or `NULL` on error.

[transfer full]

### vips_image_new_from_file_RW ()

    VipsImage *
    vips_image_new_from_file_RW (const char *filename);

Opens the named file for simultaneous reading and writing. This will only work for VIPS files in a format native to your machine. It is only for paintbox-type applications.

See also: `vips_draw_circle()`.

[constructor]

#### Parameters

filename | filename to open |

#### Returns

the new VipsImage, or `NULL` on error.

[transfer full]

### vips_image_new_from_file_raw ()

    VipsImage *
    vips_image_new_from_file_raw (const char *filename,
                                  int xsize,
                                  int ysize,
                                  int bands,
                                  guint64 offset);

This function maps the named file and returns a VipsImage you can use to read it.

It returns an 8-bit image with `bands` bands. If the image is not 8-bit, use `vips_copy()` to transform the descriptor after loading it.

See also: `vips_copy()`, `vips_rawload()`, `vips_image_new_from_file()`.

[constructor]

#### Parameters

filename | filename to open |
xsize | image width |
ysize | image height |
bands | image bands (or bytes per pixel) |
offset | bytes to skip at start of file |

#### Returns

the new VipsImage, or `NULL` on error.

[transfer full]

### vips_image_new_from_memory ()

    VipsImage *
    vips_image_new_from_memory (const void *data,
                                size_t size,
                                int width,
                                int height,
                                int bands,
                                VipsBandFormat format);

This function wraps a VipsImage around a memory area. The memory area must be a simple array, for example RGBRGBRGB, left-to-right, top-to-bottom. Use `vips_image_new_from_buffer()` to load an area of memory containing an image in a format.

VIPS does not take responsibility for the area of memory, it's up to you to make sure it's freed when the image is closed. See for example “close”.

Because VIPS is "borrowing" `data` from the caller, this function is extremely dangerous. Unless you are very careful, you will get crashes or memory corruption. Use `vips_image_new_from_memory_copy()` instead if you are at all unsure.

Use `vips_copy()` to set other image properties.

See also: `vips_image_new()`, `vips_image_write_to_memory()`, `vips_image_new_from_memory_copy()`.

[constructor]

#### Parameters

data | start of memory area. | [array length=size][element-type guint8][transfer none]
size | length of memory area. | [type gsize]
width | image width |
height | image height |
bands | image bands (or bytes per pixel) |
format | image format |

#### Returns

the new VipsImage, or `NULL` on error.

[transfer full]

### vips_image_new_from_memory_copy ()

    VipsImage *
    vips_image_new_from_memory_copy (const void *data,
                                     size_t size,
                                     int width,
                                     int height,
                                     int bands,
                                     VipsBandFormat format);

Like `vips_image_new_from_memory()`, but VIPS will make a copy of the memory area. This means more memory use and an extra copy operation, but is much simpler and safer.

See also: `vips_image_new_from_memory()`.

[constructor]

#### Parameters

data | start of memory area. | [array length=size][element-type guint8][transfer none]
size | length of memory area. | [type gsize]
width | image width |
height | image height |
bands | image bands (or bytes per pixel) |
format | image format |

#### Returns

the new VipsImage, or `NULL` on error.

[transfer full]

### vips_image_new_from_buffer ()

    VipsImage *
    vips_image_new_from_buffer (const void *buf,
                                size_t len,
                                const char *option_string,
                                ...);

Loads an image from the formatted area of memory `buf` , `len` using the loader recommended by `vips_foreign_find_load_buffer()`. To load an unformatted area of memory, use `vips_image_new_from_memory()`.

VIPS does not take responsibility for the area of memory, it's up to you to make sure it's freed when the image is closed. See for example “close”.

Load options may be given in `option_string` as "[name=value,...]" or given as a NULL-terminated list of name-value pairs at the end of the arguments. Options given in the function call override options given in the filename.

See also: `vips_image_write_to_buffer()`.

[constructor]

#### Parameters

buf | image data. | [array length=len][element-type guint8][transfer none]
len | length of memory buffer. | [type gsize]
option_string | set of extra options as a string |
... | `NULL`-terminated list of optional named arguments |

#### Returns

the new VipsImage, or `NULL` on error.

[transfer full]

### vips_image_new_from_source ()

    VipsImage *
    vips_image_new_from_source (VipsSource *source,
                                const char *option_string,
                                ...);

Loads an image from the formatted source `input` , loader recommended by `vips_foreign_find_load_source()`.

Load options may be given in `option_string` as "[name=value,...]" or given as a NULL-terminated list of name-value pairs at the end of the arguments. Options given in the function call override options given in the string.

See also: `vips_image_write_to_target()`.

[constructor]

#### Parameters

source | source to fetch image from. | [transfer none]
option_string | set of extra options as a string |
... | `NULL`-terminated list of optional named arguments |

#### Returns

the new VipsImage, or `NULL` on error.

[transfer full]

### vips_image_new_matrix ()

    VipsImage *
    vips_image_new_matrix (int width,
                           int height);

This convenience function makes an image which is a matrix: a one-band VIPS_FORMAT_DOUBLE image held in memory.

Use `VIPS_IMAGE_ADDR()`, or `VIPS_MATRIX()` to address pixels in the image.

Use `vips_image_set_double()` to set "scale" and "offset", if required.

See also: `vips_image_new_matrixv()`

[constructor]

#### Parameters

width | image width |
height | image height |

#### Returns

the new VipsImage, or `NULL` on error.

[transfer full]

### vips_image_new_matrixv ()

    VipsImage *
    vips_image_new_matrixv (int width,
                            int height,
                            ...);

As `vips_image_new_matrix()`, but initialise the matrix from the argument list. After `height` should be `width` * `height` double constants which are used to set the matrix elements.

See also: `vips_image_new_matrix()`

[constructor]

#### Parameters

width | image width |
height | image height |
... | matrix coefficients |

#### Returns

the new VipsImage, or `NULL` on error.

[transfer full]

### vips_image_new_matrix_from_array ()

    VipsImage *
    vips_image_new_matrix_from_array (int width,
                                      int height,
                                      const double *array,
                                      int size);

A binding-friendly version of `vips_image_new_matrixv()`.

[constructor]

#### Parameters

width | image width |
height | image height |
array | array of elements. | [array length=size][transfer none]
size | number of elements. | [type gsize]

#### Returns

the new VipsImage, or `NULL` on error.

[transfer full]

### vips_image_matrix_from_array ()

    VipsImage *
    vips_image_matrix_from_array (int width,
                                  int height,
                                  const double *array,
                                  int size);

A renamed `vips_image_new_matrix_from_array()`. Some gobject bindings do not like more than one _new method.

[skip]

#### Parameters

width | image width |
height | image height |
array | array of elements. | [array length=size][transfer none]
size | number of elements. | [type gsize]

#### Returns

the new VipsImage, or `NULL` on error.

[transfer full]

### vips_image_new_from_image ()

    VipsImage *
    vips_image_new_from_image (VipsImage *image,
                               const double *c,
                               int n);

Creates a new image with width, height, format, interpretation, resolution and offset taken from `image` , but with number of bands taken from `n` and the value of each band element set from `c` .

See also: `vips_image_new_from_image1()`

[constructor]

#### Parameters

image | image to copy |
c | array of constants. | [array length=n][transfer none]
n | number of constants |

#### Returns

the new VipsImage, or `NULL` on error.

[transfer full]

### vips_image_new_from_image1 ()

    VipsImage *
    vips_image_new_from_image1 (VipsImage *image,
                                double c);

Creates a new image with width, height, format, interpretation, resolution and offset taken from `image` , but with one band and each pixel having the value `c` .

See also: `vips_image_new_from_image()`

[constructor]

#### Parameters

image | image to copy |
c | constants |

#### Returns

the new VipsImage, or `NULL` on error.

[transfer full]

### vips_image_set_delete_on_close ()

    void
    vips_image_set_delete_on_close (VipsImage *image,
                                    gboolean delete_on_close);

Sets the delete_on_close flag for the image. If this flag is set, when `image` is finalized, the filename held in `image->filename` at the time of this call is deleted.

This function is clearly extremely dangerous, use with great caution.

See also: `vips_image_new_temp_file()`.

#### Parameters

image | image to set |
delete_on_close | format of file |

### vips_get_disc_threshold ()

    guint64
    vips_get_disc_threshold (void);

Return the number of bytes at which we flip between open via memory and open via disc. This defaults to 100mb, but can be changed with the VIPS_DISC_THRESHOLD environment variable or the --vips-disc-threshold command-line flag. See `vips_image_new_from_file()`.

#### Returns

disc threshold in bytes.

### vips_image_new_temp_file ()

    VipsImage *
    vips_image_new_temp_file (const char *format);

Make a VipsImage which, when written to, will create a temporary file on disc. The file will be automatically deleted when the image is destroyed. `format` is something like "%s.v" for a vips file.

The file is created in the temporary directory. This is set with the environment variable TMPDIR. If this is not set, then on Unix systems, vips will default to /tmp. On Windows, vips uses `GetTempPath()` to find the temporary directory.

See also: `vips_image_new()`.

[constructor]

#### Parameters

format | format of file |

#### Returns

the new VipsImage, or `NULL` on error.

### vips_image_write ()

    int
    vips_image_write (VipsImage *image,
                      VipsImage *out);

Write `image` to `out` . Use `vips_image_new()` and friends to create the VipsImage you want to write to.

See also: `vips_image_new()`, `vips_copy()`, `vips_image_write_to_file()`.

#### Parameters

image | image to write |
out | write to this image. | [out]

#### Returns

0 on success, or -1 on error.

### vips_image_write_to_file ()

    int
    vips_image_write_to_file (VipsImage *image,
                              const char *name,
                              ...);

Writes `in` to `name` using the saver recommended by `vips_foreign_find_save()`.

Save options may be appended to `filename` as "[name=value,...]" or given as a NULL-terminated list of name-value pairs at the end of the arguments. Options given in the function call override options given in the filename.

See also: `vips_image_new_from_file()`.

#### Parameters

image | image to write |
name | write to this file |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, or -1 on error.

### vips_image_write_to_buffer ()

    int
    vips_image_write_to_buffer (VipsImage *in,
                                const char *suffix,
                                void **buf,
                                size_t *size,
                                ...);

Writes `in` to a memory buffer in a format specified by `suffix` .

Save options may be appended to `suffix` as "[name=value,...]" or given as a NULL-terminated list of name-value pairs at the end of the arguments. Options given in the function call override options given in the filename.

Currently only TIFF, JPEG and PNG formats are supported.

You can call the various save operations directly if you wish, see `vips_jpegsave_buffer()`, for example.

See also: `vips_image_write_to_memory()`, `vips_image_new_from_buffer()`.

#### Parameters

in | image to write |
suffix | format to write |
buf | return buffer start here. | [array length=size][element-type guint8][transfer full]
size | return buffer length here. | [type gsize]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_image_write_to_target ()

    int
    vips_image_write_to_target (VipsImage *in,
                                const char *suffix,
                                VipsTarget *target,
                                ...);

Writes `in` to `output` in format `suffix` .

Save options may be appended to `suffix` as "[name=value,...]" or given as a NULL-terminated list of name-value pairs at the end of the arguments. Options given in the function call override options given in the filename.

You can call the various save operations directly if you wish, see `vips_jpegsave_target()`, for example.

See also: `vips_image_write_to_file()`.

#### Parameters

in | image to write |
suffix | format to write |
target | target to write to |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_image_write_to_memory ()

    void *
    vips_image_write_to_memory (VipsImage *in,
                                size_t *size);

Writes `in` to memory as a simple, unformatted C-style array.

The caller is responsible for freeing this memory with `g_free()`.

See also: `vips_image_write_to_buffer()`.

#### Parameters

in | image to write |
size | return buffer length here |

#### Returns

return buffer start here.

[array length=size][element-type guint8][transfer full]

### vips_image_decode_predict ()

    int
    vips_image_decode_predict (VipsImage *in,
                               int *bands,
                               VipsBandFormat *format);

We often need to know what an image will decode to without actually decoding it, for example, in arg checking.

See also: `vips_image_decode()`.

#### Parameters

in | image to decode |
bands | predict bands here. | [out]
format | predict format here. | [out]

### vips_image_decode ()

    int
    vips_image_decode (VipsImage *in,
                       VipsImage **out);

A convenience function to unpack to a format that we can compute with. `out.coding` is always VIPS_CODING_NONE.

This unpacks LABQ to plain LAB. Use `vips_LabQ2LabS()` for a bit more speed if you need it.

See also: `vips_image_encode()`, `vips_LabQ2Lab()`, `vips_rad2float()`.

#### Parameters

in | image to decode |
out | write to this image. | [out]

#### Returns

0 on success, or -1 on error.

### vips_image_encode ()

    int
    vips_image_encode (VipsImage *in,
                       VipsImage **out,
                       VipsCoding coding);

A convenience function to pack to a coding. The inverse of `vips_image_decode()`.

See also: `vips_image_decode()`.

#### Parameters

in | image to encode |
out | write to this image. | [out]
coding | coding to apply |

#### Returns

0 on success, or -1 on error.

### vips_image_isMSBfirst ()

    gboolean
    vips_image_isMSBfirst (VipsImage *image);

Return `TRUE` if `image` is in most-significant- byte first form. This is the byte order used on the SPARC architecture and others.

#### Parameters

image | image to test |

### vips_image_isfile ()

    gboolean
    vips_image_isfile (VipsImage *image);

Return `TRUE` if `image` represents a file on disc in some way.

#### Parameters

image | image to test |

### vips_image_ispartial ()

    gboolean
    vips_image_ispartial (VipsImage *image);

Return `TRUE` if `im` represents a partial image (a delayed calculation).

#### Parameters

image | image to test |

### vips_image_hasalpha ()

    gboolean
    vips_image_hasalpha (VipsImage *image);

Look at an image's interpretation and see if it has extra alpha bands. For example, a 4-band VIPS_INTERPRETATION_sRGB would, but a six-band VIPS_INTERPRETATION_MULTIBAND would not.

Return `TRUE` if `image` has an alpha channel.

#### Parameters

image | image to check |

### vips_image_copy_memory ()

    VipsImage *
    vips_image_copy_memory (VipsImage *image);

This function allocates memory, renders `image` into it, builds a new image around the memory area, and returns that.

If the image is already a simple area of memory, it just refs `image` and returns it.

Call this before using the draw operations to make sure you have a memory image that can be modified.

vips_copy() adds a null "copy" node to a pipeline. Use that instead if you want to change metadata and not pixels.

This operation is thread-safe, unlike `vips_image_wio_input()`.

If you are sure that `image` is not shared with another thread (perhaps you have made it yourself), use `vips_image_wio_input()` instead.

See also: `vips_image_wio_input()`.

#### Parameters

image | image to copy to a memory buffer |

#### Returns

the new VipsImage, or `NULL` on error.

[transfer full]

### vips_image_wio_input ()

    int
    vips_image_wio_input (VipsImage *image);

Check that an image is readable via the `VIPS_IMAGE_ADDR()` macro, that is, that the entire image is in memory and all pixels can be read with `VIPS_IMAGE_ADDR()`. If it isn't, try to transform it so that `VIPS_IMAGE_ADDR()` can work.

Since this function modifies `image` , it is not thread-safe. Only call it on images which you are sure have not been shared with another thread. If the image might have been shared, use the less efficient `vips_image_copy_memory()` instead.

See also: `vips_image_copy_memory()`, `vips_image_pio_input()`, `vips_image_inplace()`, `VIPS_IMAGE_ADDR()`.

#### Parameters

image | image to transform |

#### Returns

0 on success, or -1 on error.

### vips_image_pio_input ()

    int
    vips_image_pio_input (VipsImage *image);

Check that an image is readable with `vips_region_prepare()` and friends. If it isn't, try to transform the image so that `vips_region_prepare()` can work.

See also: `vips_image_pio_output()`, `vips_region_prepare()`.

#### Parameters

image | image to check |

#### Returns

0 on success, or -1 on error.

### vips_image_pio_output ()

    int
    vips_image_pio_output (VipsImage *image);

Check that an image is writeable with `vips_image_generate()`. If it isn't, try to transform the image so that `vips_image_generate()` can work.

See also: `vips_image_pio_input()`.

#### Parameters

image | image to check |

#### Returns

0 on success, or -1 on error.

### vips_image_inplace ()

    int
    vips_image_inplace (VipsImage *image);

Gets `image` ready for an in-place operation, such as `vips_draw_circle()`. After calling this function you can both read and write the image with `VIPS_IMAGE_ADDR()`.

This method is called for you by the base class of the draw operations, there's no need to call it yourself.

Since this function modifies `image` , it is not thread-safe. Only call it on images which you are sure have not been shared with another thread. All in-place operations are inherently not thread-safe, so you need to take great care in any case.

See also: `vips_draw_circle()`, `vips_image_wio_input()`.

#### Parameters

image | image to make read-write |

#### Returns

0 on success, or -1 on error.

### vips_image_write_prepare ()

    int
    vips_image_write_prepare (VipsImage *image);

Call this after setting header fields (width, height, and so on) to allocate resources ready for writing.

Normally this function is called for you by `vips_image_generate()` or `vips_image_write_line()`. You will need to call it yourself if you plan to write directly to the ->data member of a memory image.

#### Parameters

image | image to prepare |

#### Returns

0 on success, or -1 on error.

### vips_image_write_line ()

    int
    vips_image_write_line (VipsImage *image,
                           int ypos,
                           VipsPel *linebuffer);

Write a line of pixels to an image. This function must be called repeatedly with `ypos` increasing from 0 to “height” . `linebuffer` must be `VIPS_IMAGE_SIZEOF_LINE()` bytes long.

See also: `vips_image_generate()`.

#### Parameters

image | image to write to |
ypos | vertical position of scan-line to write |
linebuffer | scanline of pixels |

#### Returns

0 on success, or -1 on error.

### vips_band_format_isint ()

    gboolean
    vips_band_format_isint (VipsBandFormat format);

Return `TRUE` if `format` is one of the integer types.

#### Parameters

format | format to test |

### vips_band_format_isuint ()

    gboolean
    vips_band_format_isuint (VipsBandFormat format);

Return `TRUE` if `format` is one of the unsigned integer types.

#### Parameters

format | format to test |

### vips_band_format_is8bit ()

    gboolean
    vips_band_format_is8bit (VipsBandFormat format);

Return `TRUE` if `format` is uchar or schar.

#### Parameters

format | format to test |

### vips_band_format_isfloat ()

    gboolean
    vips_band_format_isfloat (VipsBandFormat format);

Return `TRUE` if `format` is one of the float types.

#### Parameters

format | format to test |

### vips_band_format_iscomplex ()

    gboolean
    vips_band_format_iscomplex (VipsBandFormat format);

Return `TRUE` if `fmt` is one of the complex types.

#### Parameters

format | format to test |

### vips_system ()

    int
    vips_system (const char *cmd_format,
                 ...);

Optional arguments:

- `in` : array of input images

- `out` : output image

- `in_format` : write input files like this

- `out_format` : write output filename like this

- `log` : stdout of command is returned here

vips_system() runs a command, optionally passing a set of images in and optionally getting an image back. The command's stdout is returned in `log` .

First, if `in` is set, the array of images are written to files. See `vips_image_new_temp_file()` to see how temporary files are created. If `in_format` is something like %s.png, the file will be written in PNG format. By default, `in_format` is %s.tif.

If `out_format` is set, an output filename is formed in the same way. Any trailing [options] are stripped from `out_format` .

The command string to run is made by substituting the first set of %s in `cmd_format` for the names of the input files, if `in` is set, and then the next %s for the output filename, if `out_format` is set. You can put a number between the % and the s to change the order in which the substitution occurs.

The command is executed with `popen()` and the output captured in `log` .

After the command finishes, if `out_format` is set, the output image is opened and returned in `out` . You can append [options] to `out_format` to control how this open happens. Closing `out` image will automatically delete the output file.

Finally the input images are deleted.

For example, this call will run the ImageMagick convert program on an image, using JPEG files to pass images into and out of the convert command.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    VipsArrayImage *in;
    VipsImage *out;
    char *log;

    if (vips_system("convert %s -swirl 45 %s",
            "in", in,
            "out", &out,
            "in_format", "%s.jpg",
            "out_format", "%s.jpg",
            "log", &log,
            NULL))
        error ...

#### Parameters

cmd_format | command to run |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on failure.

### vips_array_image_new ()

    VipsArrayImage *
    vips_array_image_new (VipsImage **array,
                          int n);

Allocate a new array of images and copy `array` into it. Free with `vips_area_unref()`.

The images will all be reffed by this function. They will be automatically unreffed for you by `vips_area_unref()`.

Add an extra NULL element at the end, handy for eg. `vips_image_pipeline_array()` etc.

See also: VipsArea.

[constructor]

#### Parameters

array | array of VipsImage. | [array length=n]
n | number of images |

#### Returns

A new VipsArrayImage.

[transfer full]

### vips_array_image_newv ()

    VipsArrayImage *
    vips_array_image_newv (int n,
                           ...);

Allocate a new array of `n` VipsImage and copy @... into it. Free with `vips_area_unref()`.

The images will all be reffed by this function. They will be automatically unreffed for you by `vips_area_unref()`.

Add an extra NULL element at the end, handy for eg. `vips_image_pipeline_array()` etc.

See also: `vips_array_image_new()`

[constructor]

#### Parameters

n | number of images |
... | list of VipsImage arguments |

#### Returns

A new VipsArrayImage.

[transfer full]

### vips_array_image_new_from_string ()

    VipsArrayImage *
    vips_array_image_new_from_string (const char *string,
                                      VipsAccess flags);

### vips_array_image_empty ()

    VipsArrayImage *
    vips_array_image_empty (void);

Make an empty image array. Handy with `vips_array_image_add()` for bindings which can't handle object array arguments.

See also: `vips_array_image_add()`.

[constructor]

#### Returns

A new VipsArrayImage.

[transfer full]

### vips_array_image_append ()

    VipsArrayImage *
    vips_array_image_append (VipsArrayImage *array,
                             VipsImage *image);

Make a new VipsArrayImage, one larger than `array` , with `image` appended to the end. Handy with `vips_array_image_empty()` for bindings which can't handle object array arguments.

See also: `vips_array_image_empty()`.

#### Parameters

array | append to this. | [transfer none]
image | add this |

#### Returns

A new VipsArrayImage.

[transfer full]

### vips_array_image_get ()

    VipsImage **
    vips_array_image_get (VipsArrayImage *array,
                          int *n);

Fetch an image array from a VipsArrayImage. Useful for language bindings.

#### Parameters

array | the VipsArrayImage to fetch from |
n | length of array |

#### Returns

array of VipsImage.

[array length=n][transfer none]

### vips_value_get_array_image ()

    VipsImage **
    vips_value_get_array_image (const GValue *value,
                                int *n);

Return the start of the array of images held by `value` . optionally return the number of elements in `n` .

See also: `vips_value_set_array_image()`.

#### Parameters

value | `GValue` to get from |
n | return the number of elements here, optionally. | [out][optional]

#### Returns

The array address.

[transfer none][array length=n]

### vips_value_set_array_image ()

    void
    vips_value_set_array_image (GValue *value,
                                int n);

Set `value` to hold an array of images. Pass in the array length in `n` .

See also: `vips_array_image_get()`.

#### Parameters

value | `GValue` to get from |
n | the number of elements |

### vips_reorder_prepare_many ()

    int
    vips_reorder_prepare_many (VipsImage *image,
                               VipsRegion **regions,
                               VipsRect *r);

vips_reorder_prepare_many() runs `vips_region_prepare()` on each region in `regions` , requesting the pixels in `r` .

It tries to request the regions in the order which will cause least recomputation. This can give a large speedup, in some cases.

See also: `vips_region_prepare()`, `vips_reorder_margin_hint()`.

[method]

#### Parameters

image | the image that's being written |
regions | the set of regions to prepare. | [array]
r | the VipsRect to prepare on each region |

#### Returns

0 on success, or -1 on error.

### vips_reorder_margin_hint ()

    void
    vips_reorder_margin_hint (VipsImage *image,
                              int margin);

vips_reorder_margin_hint() sets a hint that `image` contains a margin, that is, that each `vips_region_prepare()` on `image` will request a slightly larger region from it's inputs. A good value for `margin` is (width * height) for the window the operation uses.

This information is used by `vips_image_prepare_many()` to attempt to reorder computations to minimise recomputation.

See also: `vips_image_prepare_many()`.

[method]

#### Parameters

image | the image to hint on |
margin | the size of the margin this operation has added |

### vips_image_free_buffer ()

    void
    vips_image_free_buffer (VipsImage *image,
                            void *buffer);

Free the externally allocated buffer found in the input image. This function is intended to be used with g_signal_connect.

#### Parameters

image | the image that contains the buffer |
buffer | the original buffer that was stolen |

## Types and Values

### VIPS_MAGIC_INTEL

    #define VIPS_MAGIC_INTEL (0xb6a6f208U)

The first four bytes of a VIPS file in Intel byte ordering.

### VIPS_MAGIC_SPARC

    #define VIPS_MAGIC_SPARC (0x08f2a6b6U)

The first four bytes of a VIPS file in SPARC byte ordering.

### VIPS_MAX_COORD

    #define VIPS_MAX_COORD (10000000)

### enum VipsDemandStyle

See `vips_image_pipelinev()`. Operations can hint the kind of demand geometry they prefer to the VIPS image IO system.

These demand styles are given below in order of increasing specialisation. When demanding output from a pipeline, `vips_image_generate()` will use the most general style requested by the operations in the pipeline.

VIPS_DEMAND_STYLE_SMALLTILE --- This is the most general demand format. Output is demanded in small (around 100x100 pel) sections. This style works reasonably efficiently, even for bizarre operations like 45 degree rotate.

VIPS_DEMAND_STYLE_FATSTRIP --- This operation would like to output strips the width of the image and as high as possible. This option is suitable for area operations which do not violently transform coordinates, such as `vips_conv()`.

VIPS_DEMAND_STYLE_THINSTRIP --- This operation would like to output strips the width of the image and a few pels high. This option is suitable for point-to-point operations, such as those in the arithmetic package.

VIPS_DEMAND_STYLE_ANY --- This image is not being demand-read from a disc file (even indirectly) so any demand style is OK. It's used for things like `vips_black()` where the pixels are calculated.

See also: `vips_image_pipelinev()`.

#### Members

VIPS_DEMAND_STYLE_ERROR |  |
VIPS_DEMAND_STYLE_SMALLTILE | demand in small (typically 128x128 pixel) tiles |
VIPS_DEMAND_STYLE_FATSTRIP | demand in fat (typically 16 pixel high) strips |
VIPS_DEMAND_STYLE_THINSTRIP | demand in thin (typically 1 pixel high) strips |
VIPS_DEMAND_STYLE_ANY | demand geometry does not matter |

### enum VipsImageType

#### Members

VIPS_IMAGE_ERROR |  |
VIPS_IMAGE_NONE |  |
VIPS_IMAGE_SETBUF |  |
VIPS_IMAGE_SETBUF_FOREIGN |  |
VIPS_IMAGE_OPENIN |  |
VIPS_IMAGE_MMAPIN |  |
VIPS_IMAGE_MMAPINRW |  |
VIPS_IMAGE_OPENOUT |  |
VIPS_IMAGE_PARTIAL |  |

### enum VipsInterpretation

How the values in an image should be interpreted. For example, a three-band float image of type VIPS_INTERPRETATION_LAB should have its pixels interpreted as coordinates in CIE Lab space.

RGB and sRGB are treated in the same way. Use the colourspace functions if you want some other behaviour.

The gaps in numbering are historical and must be maintained. Allocate new numbers from the end.

#### Members

VIPS_INTERPRETATION_ERROR |  |
VIPS_INTERPRETATION_MULTIBAND | generic many-band image |
VIPS_INTERPRETATION_B_W | some kind of single-band image |
VIPS_INTERPRETATION_HISTOGRAM | a 1D image, eg. histogram or lookup table |
VIPS_INTERPRETATION_XYZ | the first three bands are CIE XYZ |
VIPS_INTERPRETATION_LAB | pixels are in CIE Lab space |
VIPS_INTERPRETATION_CMYK | the first four bands are in CMYK space |
VIPS_INTERPRETATION_LABQ | implies VIPS_CODING_LABQ |
VIPS_INTERPRETATION_RGB | generic RGB space |
VIPS_INTERPRETATION_CMC | a uniform colourspace based on CMC(1:1) |
VIPS_INTERPRETATION_LCH | pixels are in CIE LCh space |
VIPS_INTERPRETATION_LABS | CIE LAB coded as three signed 16-bit values |
VIPS_INTERPRETATION_sRGB | pixels are sRGB |
VIPS_INTERPRETATION_YXY | pixels are CIE Yxy |
VIPS_INTERPRETATION_FOURIER | image is in fourier space |
VIPS_INTERPRETATION_RGB16 | generic 16-bit RGB |
VIPS_INTERPRETATION_GREY16 | generic 16-bit mono |
VIPS_INTERPRETATION_MATRIX | a matrix |
VIPS_INTERPRETATION_scRGB | pixels are scRGB |
VIPS_INTERPRETATION_HSV | pixels are HSV |
VIPS_INTERPRETATION_LAST |  |

### enum VipsBandFormat

The format used for each band element.

Each corresponds to a native C type for the current machine. For example, VIPS_FORMAT_USHORT is <type>unsigned short</type>.

#### Members

VIPS_FORMAT_NOTSET | invalid setting |
VIPS_FORMAT_UCHAR | unsigned char format |
VIPS_FORMAT_CHAR | char format |
VIPS_FORMAT_USHORT | unsigned short format |
VIPS_FORMAT_SHORT | short format |
VIPS_FORMAT_UINT | unsigned int format |
VIPS_FORMAT_INT | int format |
VIPS_FORMAT_FLOAT | float format |
VIPS_FORMAT_COMPLEX | complex (two floats) format |
VIPS_FORMAT_DOUBLE | double float format |
VIPS_FORMAT_DPCOMPLEX | double complex (two double) format |
VIPS_FORMAT_LAST |  |

### enum VipsCoding

How pixels are coded.

Normally, pixels are uncoded and can be manipulated as you would expect. However some file formats code pixels for compression, and sometimes it's useful to be able to manipulate images in the coded format.

The gaps in the numbering are historical and must be maintained. Allocate new numbers from the end.

#### Members

VIPS_CODING_ERROR |  |
VIPS_CODING_NONE | pixels are not coded |
VIPS_CODING_LABQ | pixels encode 3 float CIELAB values as 4 uchar |
VIPS_CODING_RAD | pixels encode 3 float RGB as 4 uchar (Radiance coding) |
VIPS_CODING_LAST |  |

### enum VipsAccess

The type of access an operation has to supply. See `vips_tilecache()` and VipsForeign.

`VIPS_ACCESS_RANDOM` means requests can come in any order.

`VIPS_ACCESS_SEQUENTIAL` means requests will be top-to-bottom, but with some amount of buffering behind the read point for small non-local accesses.

#### Members

VIPS_ACCESS_RANDOM | can read anywhere |
VIPS_ACCESS_SEQUENTIAL | top-to-bottom reading only, but with a small buffer |
VIPS_ACCESS_SEQUENTIAL_UNBUFFERED |  |
VIPS_ACCESS_LAST |  |

### VipsProgress

    typedef struct {
    	int run;	   /* Time we have been running */
    	int eta;	   /* Estimated seconds of computation left */
    	gint64 tpels;  /* Number of pels we expect to calculate */
    	gint64 npels;  /* Number of pels calculated so far */
    	int percent;   /* Percent complete */
    	GTimer *start; /* Start time */
    } VipsProgress;

A structure available to eval callbacks giving information on evaluation progress. See “eval”.

#### Members

int `run`; | Time we have been running |
int `eta`; | Estimated seconds of computation left |
gint64 `tpels`; | Number of pels we expect to calculate |
gint64 `npels`; | Number of pels calculated so far |
int `percent`; | Percent complete |
GTimer *`start`; | Start time |

## Property Details

### The `“bands”` property

      “bands”                    int

Number of bands in image.

Owner: VipsImage

Flags: Read / Write

Allowed values: [1,10000000]

Default value: 1

### The `“coding”` property

      “coding”                   VipsCoding

Pixel coding.

Owner: VipsImage

Flags: Read / Write

Default value: VIPS_CODING_NONE

### The `“demand”` property

      “demand”                   VipsDemandStyle

Preferred demand style for this image.

Owner: VipsImage

Flags: Read / Write

Default value: VIPS_DEMAND_STYLE_SMALLTILE

### The `“filename”` property

      “filename”                 char *

Image filename.

Owner: VipsImage

Flags: Read / Write

Default value: NULL

### The `“foreign-buffer”` property

      “foreign-buffer”           gpointer

Pointer to foreign pixels.

Owner: VipsImage

Flags: Read / Write

### The `“format”` property

      “format”                   VipsBandFormat

Pixel format in image.

Owner: VipsImage

Flags: Read / Write

Default value: VIPS_FORMAT_UCHAR

### The `“height”` property

      “height”                   int

Image height in pixels.

Owner: VipsImage

Flags: Read / Write

Allowed values: [1,10000000]

Default value: 1

### The `“interpretation”` property

      “interpretation”           VipsInterpretation

Pixel interpretation.

Owner: VipsImage

Flags: Read / Write

Default value: VIPS_INTERPRETATION_MULTIBAND

### The `“kill”` property

      “kill”                     gboolean

Block evaluation on this image.

Owner: VipsImage

Flags: Read / Write

Default value: FALSE

### The `“mode”` property

      “mode”                     char *

Open mode.

Owner: VipsImage

Flags: Read / Write

Default value: "p"

### The `“sizeof-header”` property

      “sizeof-header”            guint64

Offset in bytes from start of file.

Owner: VipsImage

Flags: Read / Write

Allowed values: <= 1000000000

Default value: 64

### The `“width”` property

      “width”                    int

Image width in pixels.

Owner: VipsImage

Flags: Read / Write

Allowed values: [1,10000000]

Default value: 1

### The `“xoffset”` property

      “xoffset”                  int

Horizontal offset of origin.

Owner: VipsImage

Flags: Read / Write

Allowed values: [-10000000,10000000]

Default value: 0

### The `“xres”` property

      “xres”                     double

Horizontal resolution in pixels/mm.

Owner: VipsImage

Flags: Read / Write

Allowed values: [-0,1e+06]

Default value: 0

### The `“yoffset”` property

      “yoffset”                  int

Vertical offset of origin.

Owner: VipsImage

Flags: Read / Write

Allowed values: [-10000000,10000000]

Default value: 0

### The `“yres”` property

      “yres”                     double

Vertical resolution in pixels/mm.

Owner: VipsImage

Flags: Read / Write

Allowed values: [-0,1e+06]

Default value: 0

## Signal Details

### The `“eval”` signal

    void
    user_function (VipsImage *image,
                   gpointer   progress,
                   gpointer   user_data)

The ::eval signal is emitted once per work unit (typically a 128 x 128 area of pixels) during image computation.

You can use this signal to update user-interfaces with progress feedback. Beware of updating too frequently: you will usually need some throttling mechanism.

Use `vips_image_set_progress()` to turn on progress reporting for an image.

#### Parameters

image | the image being calculated |
progress | VipsProgress for this image. | [type VipsProgress]
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“invalidate”` signal

    void
    user_function (VipsImage *image,
                   gpointer   user_data)

The ::invalidate signal is emitted when an image or one of it's upstream data sources has been destructively modified. See `vips_image_invalidate_all()`.

#### Parameters

image | the image that has changed |
user_data | user data set when the signal handler was connected. |

Flags: Action

### The `“minimise”` signal

    void
    user_function (VipsImage *image,
                   gpointer   user_data)

The ::minimise signal is emitted when an image has been asked to minimise memory usage. All non-essential caches are dropped. See `vips_image_minimise_all()`.

#### Parameters

image | the image that is being minimised |
user_data | user data set when the signal handler was connected. |

Flags: Action

### The `“posteval”` signal

    void
    user_function (VipsImage *image,
                   gpointer   progress,
                   gpointer   user_data)

The ::posteval signal is emitted once at the end of the computation of `image` . It's a good place to shut down evaluation feedback.

Use `vips_image_set_progress()` to turn on progress reporting for an image.

#### Parameters

image | the image that was calculated |
progress | VipsProgress for this image. | [type VipsProgress]
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“preeval”` signal

    void
    user_function (VipsImage *image,
                   gpointer   progress,
                   gpointer   user_data)

The ::preeval signal is emitted once before computation of `image` starts. It's a good place to set up evaluation feedback.

Use `vips_image_set_progress()` to turn on progress reporting for an image.

#### Parameters

image | the image to be calculated |
progress | VipsProgress for this image. | [type VipsProgress]
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“written”` signal

    void
    user_function (VipsImage *image,
                   gpointer   result,
                   gpointer   user_data)

The ::written signal is emitted just after an image has been written to. It is used by vips to implement things like write to foreign file formats.

#### Parameters

image | the image that was calculated |
result | set to non-zero to indicate error. | [out][type gint]
user_data | user data set when the signal handler was connected. |

Flags: Action

## See Also

<link linkend="libvips-header">header</link> <link linkend="VipsRegion">VipsRegion</link> <link linkend="libvips-generate">generate</link> <link linkend="VipsOperation">VipsOperation</link>