basic: libvips Reference Manual

## basic basic — a few typedefs used everywhere |

## Stability Level

Stable, unless otherwise indicated

## Functions

#define | VIPS_DEPRECATED_FOR()
int | (*VipsCallbackFn) ()
void * | (*VipsSListMap2Fn) ()
void * | (*VipsSListMap4Fn) ()
void * | (*VipsSListFold2Fn) ()
char * | vips_path_filename7 ()
char * | vips_path_mode7 ()

## 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
VipsBlob * | blob | Read / Write
VipsBlob * | blob | Read / Write
gboolean | memory | 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_API
#define | VIPS_DEPRECATED
typedef | VipsPel
enum | VipsPrecision
| VipsBuf
| VipsImage
| VipsRegion
| VipsSource
| VipsTarget

## Object Hierarchy

        GEnum
        ╰── VipsPrecision
        GObject
        ╰── VipsObject
            ├── VipsConnection
            │   ├── VipsSource
            │   │   ╰── VipsSourceCustom
            │   ╰── VipsTarget
            │       ╰── VipsTargetCustom
            ├── VipsImage
            ╰── VipsRegion

## Includes

    #include <vips/vips.h>

## Description

A few simple typedefs used by VIPS.

## Functions

### VIPS_DEPRECATED_FOR()

    #define VIPS_DEPRECATED_FOR(f) VIPS_API

### VipsCallbackFn ()

    int
    (*VipsCallbackFn) (void *a,
                       void *b);

### VipsSListMap2Fn ()

    void *
    (*VipsSListMap2Fn) (void *item,
                        void *a,
                        void *b);

### VipsSListMap4Fn ()

    void *
    (*VipsSListMap4Fn) (void *item,
                        void *a,
                        void *b,
                        void *c,
                        void *d);

### VipsSListFold2Fn ()

    void *
    (*VipsSListFold2Fn) (void *item,
                         void *a,
                         void *b,
                         void *c);

### vips_path_filename7 ()

    char *
    vips_path_filename7 (const char *path);

Return the filename part of a vips7 path. For testing only.

#### Parameters

path | path to split |

### vips_path_mode7 ()

    char *
    vips_path_mode7 (const char *path);

Return the mode part of a vips7 path. For testing only.

#### Parameters

path | path to split |

## Types and Values

### VIPS_API

    #define VIPS_API _VIPS_PUBLIC extern

### VIPS_DEPRECATED

    #define VIPS_DEPRECATED VIPS_API

### VipsPel

    typedef unsigned char VipsPel;

A picture element. Cast this to whatever the associated VipsBandFormat says to get the value.

### enum VipsPrecision

How accurate an operation should be.

#### Members

VIPS_PRECISION_INTEGER | int everywhere |
VIPS_PRECISION_FLOAT | float everywhere |
VIPS_PRECISION_APPROXIMATE | approximate integer output |
VIPS_PRECISION_LAST |  |

### VipsBuf

    typedef struct {
    	/* All fields are private.
    	 */
    } VipsBuf;

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

### VipsRegion

    typedef struct {
    	/* Users may read these two fields.
    	 */
    	VipsImage *im; /* Link back to parent image */
    	VipsRect valid; /* Area of parent we can see */

    	/* The rest of VipsRegion is private.
    	 */
    } VipsRegion;

A small part of a VipsImage. `valid` holds the left/top/width/height of the area of pixels that are available from the region.

See also: `VIPS_REGION_ADDR()`, `vips_region_new()`, `vips_region_prepare()`.

#### Members

VipsImage *`im`; | the VipsImage that this region is defined on |
VipsRect `valid`; | the VipsRect of pixels that this region represents |

### VipsSource

    typedef struct _VipsSource VipsSource;

### VipsTarget

    typedef struct _VipsTarget VipsTarget;

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

### The `“blob”` property

      “blob”                     VipsBlob *

Blob to load from.

Owner: VipsSource

Flags: Read / Write

### The `“blob”` property

      “blob”                     VipsBlob *

Blob to save to.

Owner: VipsTarget

Flags: Read / Write

### The `“memory”` property

      “memory”                   gboolean

File descriptor should output to memory.

Owner: VipsTarget

Flags: Read / Write

Default value: FALSE

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