## VipsImage

VipsImage — the VIPS image class

## Stability Level

Stable, unless otherwise indicated

## Synopsis

    #include <vips/vips.h>

    #define             VIPS_MAGIC_INTEL
    #define             VIPS_MAGIC_SPARC
    enum                VipsDemandStyle;
    enum                VipsImageType;
    enum                VipsInterpretation;
    enum                VipsBandFormat;
    enum                VipsCoding;
    enum                VipsAccess;
                        VipsProgress;
                        VipsImage;
                        VipsImageClass;
    #define             VIPS_IMAGE_SIZEOF_ELEMENT           (I)
    #define             VIPS_IMAGE_SIZEOF_PEL               (I)
    #define             VIPS_IMAGE_SIZEOF_LINE              (I)
    #define             VIPS_IMAGE_N_ELEMENTS               (I)
    #define             VIPS_IMAGE_N_PELS                   (I)
    #define             VIPS_IMAGE_ADDR                     (I,
                                                             X,
                                                             Y)
    #define             VIPS_MATRIX                         (I,
                                                             X,
                                                             Y)
    int                 vips_image_written                  (VipsImage *image);
    void                vips_image_invalidate_all           (VipsImage *image);
    void                vips_image_minimise_all             (VipsImage *image);
    void                vips_image_preeval                  (VipsImage *image);
    void                vips_image_eval                     (VipsImage *image,
                                                             guint64 processed);
    void                vips_image_posteval                 (VipsImage *image);
    void                vips_image_set_progress             (VipsImage *image,
                                                             gboolean progress);
    gboolean            vips_image_iskilled                 (VipsImage *image);
    void                vips_image_set_kill                 (VipsImage *image,
                                                             gboolean kill);
    VipsImage *         vips_image_new                      (void);
    VipsImage *         vips_image_new_mode                 (const char *filename,
                                                             const char *mode);
    VipsImage *         vips_image_new_buffer               (void);
    VipsImage *         vips_image_new_from_file            (const char *filename);
    VipsImage *         vips_image_new_from_file_raw        (const char *filename,
                                                             int xsize,
                                                             int ysize,
                                                             int bands,
                                                             guint64 offset);
    VipsImage *         vips_image_new_from_memory          (void *buffer,
                                                             int xsize,
                                                             int ysize,
                                                             int bands,
                                                             VipsBandFormat bandfmt);
    VipsImage *         vips_image_new_matrix               (int width,
                                                             int height);
    VipsImage *         vips_image_new_matrixv              (int width,
                                                             int height,
                                                             ...);
    void                vips_image_set_delete_on_close      (VipsImage *image,
                                                             gboolean delete_on_close);
    VipsImage *         vips_image_new_temp_file            (const char *format);
    int                 vips_image_write                    (VipsImage *image,
                                                             VipsImage *out);
    int                 vips_image_write_to_file            (VipsImage *image,
                                                             const char *filename);
    gboolean            vips_image_isMSBfirst               (VipsImage *image);
    gboolean            vips_image_isfile                   (VipsImage *image);
    gboolean            vips_image_ispartial                (VipsImage *image);
    int                 vips_image_wio_input                (VipsImage *image);
    int                 vips_image_pio_input                (VipsImage *image);
    int                 vips_image_inplace                  (VipsImage *image);
    int                 vips_image_write_prepare            (VipsImage *image);
    int                 vips_image_write_line               (VipsImage *image,
                                                             int ypos,
                                                             VipsPel *linebuffer);
    gboolean            vips_band_format_isint              (VipsBandFormat format);
    gboolean            vips_band_format_isuint             (VipsBandFormat format);
    gboolean            vips_band_format_is8bit             (VipsBandFormat format);
    gboolean            vips_band_format_isfloat            (VipsBandFormat format);
    gboolean            vips_band_format_iscomplex          (VipsBandFormat format);
    int                 vips_system                         (const char *cmd_format,
                                                             ...);

## Object Hierarchy

      GObject
       +----VipsObject
             +----VipsImage

## Properties

      "bands"                    gint                  : Read / Write
      "coding"                   VipsCoding            : Read / Write
      "demand"                   VipsDemandStyle       : Read / Write
      "filename"                 gchar*                : Read / Write
      "foreign-buffer"           gpointer              : Read / Write
      "format"                   VipsBandFormat        : Read / Write
      "height"                   gint                  : Read / Write
      "interpretation"           VipsInterpretation    : Read / Write
      "kill"                     gboolean              : Read / Write
      "mode"                     gchar*                : Read / Write
      "sizeof-header"            guint64               : Read / Write
      "width"                    gint                  : Read / Write
      "xoffset"                  gint                  : Read / Write
      "xres"                     gdouble               : Read / Write
      "yoffset"                  gint                  : Read / Write
      "yres"                     gdouble               : Read / Write

## Signals

      "eval"                                           : Run Last
      "invalidate"                                     : Action
      "minimise"                                       : Action
      "posteval"                                       : Run Last
      "preeval"                                        : Run Last
      "written"                                        : Action

## Description

The image class and associated types and macros.

`vips_image_wio_input()` and friends indicate the image IO style you intend to use, transforming the underlying VipsImage structure if necessary.

## Details

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

### enum VipsDemandStyle

    typedef enum {
    	VIPS_DEMAND_STYLE_ERROR = -1,
    	VIPS_DEMAND_STYLE_SMALLTILE,
    	VIPS_DEMAND_STYLE_FATSTRIP,
    	VIPS_DEMAND_STYLE_THINSTRIP,
    	VIPS_DEMAND_STYLE_ANY
    } VipsDemandStyle;

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

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

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

This option is only efficient for cases where each output pel depends upon the pel in the corresponding position in the input image.

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

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 bizzare operations like 45 degree rotate.

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 `im_black()` where the pixels are calculated.

See also: `vips_image_pipelinev()`.

`VIPS_DEMAND_STYLE_ERROR` |
`VIPS_DEMAND_STYLE_SMALLTILE` | demand in small (typically 64x64 pixel) tiles
`VIPS_DEMAND_STYLE_FATSTRIP` | demand in fat (typically 10 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

    typedef enum {
    	VIPS_IMAGE_ERROR = -1,
    	VIPS_IMAGE_NONE,		/* no type set */
    	VIPS_IMAGE_SETBUF,		/* malloced memory array */
    	VIPS_IMAGE_SETBUF_FOREIGN, /* memory array, don't free on close */
    	VIPS_IMAGE_OPENIN,		/* input from fd with a window */
    	VIPS_IMAGE_MMAPIN,		/* memory mapped input file */
    	VIPS_IMAGE_MMAPINRW,		/* memory mapped read/write file */
    	VIPS_IMAGE_OPENOUT,		/* output to fd */
    	VIPS_IMAGE_PARTIAL		/* partial image */
    } VipsImageType;

`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

    typedef enum {
    	VIPS_INTERPRETATION_ERROR = -1,
    	VIPS_INTERPRETATION_MULTIBAND = 0,
    	VIPS_INTERPRETATION_B_W = 1,
    	VIPS_INTERPRETATION_HISTOGRAM = 10,
    	VIPS_INTERPRETATION_XYZ = 12,
    	VIPS_INTERPRETATION_LAB = 13,
    	VIPS_INTERPRETATION_CMYK = 15,
    	VIPS_INTERPRETATION_LABQ = 16,
    	VIPS_INTERPRETATION_RGB = 17,
    	VIPS_INTERPRETATION_CMC = 18,
    	VIPS_INTERPRETATION_LCH = 19,
    	VIPS_INTERPRETATION_LABS = 21,
    	VIPS_INTERPRETATION_sRGB = 22,
    	VIPS_INTERPRETATION_YXY = 23,
    	VIPS_INTERPRETATION_FOURIER = 24,
    	VIPS_INTERPRETATION_RGB16 = 25,
    	VIPS_INTERPRETATION_GREY16 = 26,
    	VIPS_INTERPRETATION_MATRIX = 27,
    	VIPS_INTERPRETATION_scRGB = 28
    } 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.

These values are set by operations as hints to user-interfaces built on top of VIPS to help them show images to the user in a meaningful way. Operations do not use these values to decide their action.

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

`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

### enum VipsBandFormat

    typedef enum {
    	VIPS_FORMAT_NOTSET = -1,
    	VIPS_FORMAT_UCHAR = 0,
    	VIPS_FORMAT_CHAR = 1,
    	VIPS_FORMAT_USHORT = 2,
    	VIPS_FORMAT_SHORT = 3,
    	VIPS_FORMAT_UINT = 4,
    	VIPS_FORMAT_INT = 5,
    	VIPS_FORMAT_FLOAT = 6,
    	VIPS_FORMAT_COMPLEX = 7,
    	VIPS_FORMAT_DOUBLE = 8,
    	VIPS_FORMAT_DPCOMPLEX = 9,
    	VIPS_FORMAT_LAST = 10
    } VipsBandFormat;

The format used for each band element.

Each corresponnds to a native C type for the current machine. For example, VIPS_FORMAT_USHORT is unsigned short.

`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

    typedef enum {
    	VIPS_CODING_ERROR = -1,
    	VIPS_CODING_NONE = 0,
    	VIPS_CODING_LABQ = 2,
    	VIPS_CODING_RAD = 6,
    	VIPS_CODING_LAST = 7
    } 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.

`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

    typedef enum {
    	VIPS_ACCESS_RANDOM,
    	VIPS_ACCESS_SEQUENTIAL,
    	VIPS_ACCESS_SEQUENTIAL_UNBUFFERED,
    	VIPS_ACCESS_LAST
    } 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.

`VIPS_ACCESS_SEQUENTIAL_UNBUFFERED` means requests will be strictly top-to-bottom with no read-behind. This can save some memory.

`VIPS_ACCESS_RANDOM` | can read anywhere
`VIPS_ACCESS_SEQUENTIAL` | top-to-bottom reading only, but with a small buffer
`VIPS_ACCESS_SEQUENTIAL_UNBUFFERED` | top-to-bottom reading only
`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".

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

### VipsImage

    typedef struct _VipsImage VipsImage;

An image. These can represent an image on disc, a memory buffer, an image in the process of being written to disc or a partially evaluated image in memory.

### VipsImageClass

    typedef struct {
    	VipsObjectClass parent_class;

    	/* Signals we emit.
    	 */

    	/* Evaluation is starting.
    	 */
    	void (*preeval)( VipsImage *image, VipsProgress *progress );

    	/* Evaluation progress.
    	 */
    	void (*eval)( VipsImage *image, VipsProgress *progress );

    	/* Evaluation is ending.
    	 */
    	void (*posteval)( VipsImage *image, VipsProgress *progress );

    	/* An image has been written to.
    	 * Used by eg. vips_image_new_mode("x.jpg", "w") to do the
    	 * final write to jpeg.
    	 * Set *result to non-zero to indicate an error on write.
    	 */
    	void (*written)( VipsImage *image, int *result );

    	/* An image has been modified in some way and all caches
    	 * need dropping.
    	 */
    	void (*invalidate)( VipsImage *image );

    	/* Minimise this pipeline.
    	 *
    	 * This is triggered (sometimes) at the end of eval to signal that
    	 * we're probably done and that operations involved should try to
    	 * minimise memory use by, for example, dropping caches.
    	 *
    	 * See vips_tilecache().
    	 */
    	void (*minimise)( VipsImage *image );
    } VipsImageClass;

### VIPS_IMAGE_SIZEOF_ELEMENT()

    #define             VIPS_IMAGE_SIZEOF_ELEMENT( I )

`I` : | a VipsImage
Returns : | `sizeof()` a band element.

### VIPS_IMAGE_SIZEOF_PEL()

    #define             VIPS_IMAGE_SIZEOF_PEL( I )

`I` : | a VipsImage
Returns : | `sizeof()` a pixel.

### VIPS_IMAGE_SIZEOF_LINE()

    #define             VIPS_IMAGE_SIZEOF_LINE( I )

`I` : | a VipsImage
Returns : | `sizeof()` a scanline of pixels.

### VIPS_IMAGE_N_ELEMENTS()

    #define             VIPS_IMAGE_N_ELEMENTS( I )

`I` : | a VipsImage
Returns : | The number of band elements in a scanline.

### VIPS_IMAGE_N_PELS()

    #define             VIPS_IMAGE_N_PELS( I )

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

`I` : | a VipsImage
`X` : | x coordinate
`Y` : | y coordinate
Returns : | The address of pixel (x,y) in the image.

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

`I` : | a VipsImage
`X` : | x coordinate
`Y` : | y coordinate
Returns : | The address of pixel (x,y) in the image.

### vips_image_written ()

    int                 vips_image_written                  (VipsImage *image);

### vips_image_invalidate_all ()

    void                vips_image_invalidate_all           (VipsImage *image);

Invalidate all pixel caches on an `image` and any downstream images, that is, images which depend on this image.

The "invalidate" callback is triggered for all invalidated images.

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

The "minimise" callback is triggered for all minimised images.

`image` : | VipsImage to minimise

### vips_image_preeval ()

    void                vips_image_preeval                  (VipsImage *image);

### vips_image_eval ()

    void                vips_image_eval                     (VipsImage *image,
                                                             guint64 processed);

### vips_image_posteval ()

    void                vips_image_posteval                 (VipsImage *image);

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

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

### vips_image_iskilled ()

    gboolean            vips_image_iskilled                 (VipsImage *image);

### vips_image_set_kill ()

    void                vips_image_set_kill                 (VipsImage *image,
                                                             gboolean kill);

### vips_image_new ()

    VipsImage *         vips_image_new                      (void);

`vips_image_new()` creates a "glue" descriptor you can use to join two image processing operations together.

It is the equivalent of vips_image_new_mode("xxx", "p").

Returns : | the new VipsImage, or `NULL` on error.

### vips_image_new_mode ()

    VipsImage *         vips_image_new_mode                 (const char *filename,
                                                             const char *mode);

`vips_image_new_mode()` examines the mode string and creates an appropriate VipsImage.

- "t" creates a temporary memory buffer image.

- "p" creates a "glue" descriptor you can use to join operations, see also `vips_image_new()`.

- "r" opens the named file for reading. If the file is not in the native VIPS format for your machine, `vips_image_new_mode()` automatically converts the file for you.

  Some formats (eg. tiled tiff) are read directly.

  Some formats (eg. strip tiff) do not support random access and can't be processed directly. Small images are decompressed to memory and loaded from there, large images are decompressed to a disc file and processed from that.

  If the operations you intend to perform are sequential, that is, they operate in a strict top-to-bottom manner, you can use sequential mode instead, see "rs" below, or you can use the lower-level API and control the loading process yourself. See VipsForeign.

  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 IM_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.

  For example:

              vips --vips-disc-threshold 500m copy fred.tif fred.v

  will copy via disc if "fred.tif" is more than 500 Mbytes uncompressed. The default threshold is 100 MB.

  Note that "r" mode works in at least two stages. It should return quickly and let you check header fields. It will only actually read in pixels when you first access them.

- "rs" opens the named file for reading sequentially. It reads the source image top-to-bottom and serves up pixels to the pipeline as required. Provided the operations that connect to the image all demand pixels only top-to-bottom as well, everything is fine and you avoid the separate decompress stage.

- "w" opens the named file for writing. It looks at the file name suffix to determine the type to write -- for example:

              vips_image_new_mode( "fred.tif", "w" )

  will write in TIFF format.

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

`filename` : | file to open
`mode` : | mode to open with
Returns : | the new VipsImage, or `NULL` on error.

### vips_image_new_buffer ()

    VipsImage *         vips_image_new_buffer               (void);

`vips_image_new_buffer()` creates a new VipsImage which when written to will create a memory buffer. It is a convenience function for vips_image_new_mode(`vips_image_temp_name()`, "t").

See also: `vips_image_new()`.

Returns : | the new VipsImage, or `NULL` on error.

### vips_image_new_from_file ()

    VipsImage *         vips_image_new_from_file            (const char *filename);

`vips_image_new_from_file()` opens `filename` for reading in mode "r". See `vips_image_new_mode()` for details.

See also: `vips_image_new_mode()`.

`filename` : | file to open
Returns : | the new VipsImage, or `NULL` on error.

### 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 `im_copy_set()` to transform the descriptor after loading it.

See also: `im_copy_set()`, `im_raw2vips()`, `vips_image_new_from_file()`.

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

### vips_image_new_from_memory ()

    VipsImage *         vips_image_new_from_memory          (void *buffer,
                                                             int xsize,
                                                             int ysize,
                                                             int bands,
                                                             VipsBandFormat bandfmt);

This function wraps an IMAGE around a memory buffer. 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".

See also: `im_binfile()`, `im_raw2vips()`, `vips_image_new()`.

`buffer` : | start of memory area
`xsize` : | image width
`ysize` : | image height
`bands` : | image bands (or bytes per pixel)
`bandfmt` : | image format
Returns : | the new VipsImage, or `NULL` on error.

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

`width` : | image width
`height` : | image height
Returns : | the new VipsImage, or `NULL` on error.

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

`width` : | image width
`height` : | image height
`...` : | matrix coefficients
Returns : | the new VipsImage, or `NULL` on error.

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

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

See also: `vips__temp_name()`, `vips_image_new_temp_file()`.

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

### vips_image_new_temp_file ()

    VipsImage *         vips_image_new_temp_file            (const char *format);

Make a "w" disc VipsImage which will be automatically unlinked when it is destroyed. `format` is something like "`s`.v" for a vips file.

The file is created in the temporary directory, see `vips__temp_name()`.

See also: `vips__temp_name()`.

`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_mode()` and friends to create the VipsImage you want to write to.

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

`image` : | image to write
`out` : | write to this image
Returns : | 0 on success, or -1 on error.

### vips_image_write_to_file ()

    int                 vips_image_write_to_file            (VipsImage *image,
                                                             const char *filename);

A convenience function to write `image` to a file.

`image` : | image to write
`filename` : | write to this file
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.

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

`image` : | image to test

### vips_image_ispartial ()

    gboolean            vips_image_ispartial                (VipsImage *image);

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

`image` : | image to test

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

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

`image` : | image to transform
Returns : | 0 on succeess, 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()`.

`image` : | image to check
Returns : | 0 on succeess, or -1 on error.

### vips_image_inplace ()

    int                 vips_image_inplace                  (VipsImage *image);

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

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

`image` : | image to make read-write
Returns : | 0 on succeess, 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 "t" image.

`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 `YSize` - `linebuffer` must be `VIPS_IMAGE_SIZEOF_LINE()` bytes long.

See also: `vips_image_generate()`.

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

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

`format` : | format to test

### vips_band_format_is8bit ()

    gboolean            vips_band_format_is8bit             (VipsBandFormat format);

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

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

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

`format` : | format to test

### vips_system ()

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

Optional arguments:

`in`: input image `out`: output image `in_format`: write input file like this `out_format`: write output filename like this `log`: stdout of command is returned here

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

First, if `in` is set, it is written to a file. The filename is formed by substituting something like "vips-49857-1" for the first %`s` in `in_format`, then prepending "/tmp". If the environment variable TMPDIR is defined, it can be used to set a different temporary directory.

On Windows, if the environment variable TMPDIR is not defined, VIPS calls `GetTempPath()` to get the user's preferred temporary area. If that fails, it defaults to C:\temp.

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.

The command string to run is made by substituting the first %`s` in `cmd_format` for the name of the input file, if `in` is set, and the second %`s` for the output filename, if set.

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`. Closing the output 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.

    VipsImage *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 ...

`cmd_format` : | command to run
`...` : | `NULL`-terminated list of optional named arguments
Returns : | 0 on success, -1 on failure.

## Property Details

### The `"bands"` property

      "bands"                    gint                  : Read / Write

Number of bands in image.

Allowed values: [1,1000000000]

Default value: 1

### The `"coding"` property

      "coding"                   VipsCoding            : Read / Write

Pixel coding.

Default value: VIPS_CODING_NONE

### The `"demand"` property

      "demand"                   VipsDemandStyle       : Read / Write

Preferred demand style for this image.

Default value: VIPS_DEMAND_STYLE_SMALLTILE

### The `"filename"` property

      "filename"                 gchar*                : Read / Write

Image filename.

Default value: NULL

### The `"foreign-buffer"` property

      "foreign-buffer"           gpointer              : Read / Write

Pointer to foreign pixels.

### The `"format"` property

      "format"                   VipsBandFormat        : Read / Write

Pixel format in image.

Default value: VIPS_FORMAT_UCHAR

### The `"height"` property

      "height"                   gint                  : Read / Write

Image height in pixels.

Allowed values: [1,1000000000]

Default value: 1

### The `"interpretation"` property

      "interpretation"           VipsInterpretation    : Read / Write

Pixel interpretation.

Default value: VIPS_INTERPRETATION_MULTIBAND

### The `"kill"` property

      "kill"                     gboolean              : Read / Write

Block evaluation on this image.

Default value: FALSE

### The `"mode"` property

      "mode"                     gchar*                : Read / Write

Open mode.

Default value: "p"

### The `"sizeof-header"` property

      "sizeof-header"            guint64               : Read / Write

Offset in bytes from start of file.

Allowed values: <= 1000000

Default value: 64

### The `"width"` property

      "width"                    gint                  : Read / Write

Image width in pixels.

Allowed values: [1,1000000000]

Default value: 1

### The `"xoffset"` property

      "xoffset"                  gint                  : Read / Write

Horizontal offset of origin.

Allowed values: [-1000000,1000000]

Default value: 0

### The `"xres"` property

      "xres"                     gdouble               : Read / Write

Horizontal resolution in pixels/mm.

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

Default value: 0

### The `"yoffset"` property

      "yoffset"                  gint                  : Read / Write

Vertical offset of origin.

Allowed values: [-1000000,1000000]

Default value: 0

### The `"yres"` property

      "yres"                     gdouble               : Read / Write

Vertical resolution in pixels/mm.

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

Default value: 0

## Signal Details

### The `"eval"` signal

    void                user_function                      (VipsImage *vipsimage,
                                                            gpointer   arg1,
                                                            gpointer   user_data)      : Run Last

`vipsimage` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.

### The `"invalidate"` signal

    void                user_function                      (VipsImage *vipsimage,
                                                            gpointer   user_data)      : Action

`vipsimage` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.

### The `"minimise"` signal

    void                user_function                      (VipsImage *vipsimage,
                                                            gpointer   user_data)      : Action

`vipsimage` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.

### The `"posteval"` signal

    void                user_function                      (VipsImage *vipsimage,
                                                            gpointer   arg1,
                                                            gpointer   user_data)      : Run Last

`vipsimage` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.

### The `"preeval"` signal

    void                user_function                      (VipsImage *vipsimage,
                                                            gpointer   arg1,
                                                            gpointer   user_data)      : Run Last

`vipsimage` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.

### The `"written"` signal

    void                user_function                      (VipsImage *vipsimage,
                                                            gpointer   arg1,
                                                            gpointer   user_data)      : Action

`vipsimage` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.

## See Also

region