type: VIPS Reference Manual

## type type — basic types |

## Stability Level

Stable, unless otherwise indicated

## Functions

VipsThing * | vips_thing_new ()
VipsArea * | vips_area_copy ()
int | vips_area_free_cb ()
void | vips_area_unref ()
VipsArea * | vips_area_new ()
VipsArea * | vips_area_new_array ()
VipsArea * | vips_area_new_array_object ()
void * | vips_area_get_data ()
#define | VIPS_ARRAY_ADDR()
VipsRefString * | vips_ref_string_new ()
const char * | vips_ref_string_get ()
VipsBlob * | vips_blob_new ()
VipsBlob * | vips_blob_copy ()
const void * | vips_blob_get ()
void | vips_blob_set ()
VipsArrayDouble * | vips_array_double_new ()
VipsArrayDouble * | vips_array_double_newv ()
double * | vips_array_double_get ()
VipsArrayInt * | vips_array_int_new ()
VipsArrayInt * | vips_array_int_newv ()
int * | vips_array_int_get ()
void | vips_value_set_area ()
void * | vips_value_get_area ()
const char * | vips_value_get_save_string ()
void | vips_value_set_save_string ()
void | vips_value_set_save_stringf ()
const char * | vips_value_get_ref_string ()
void | vips_value_set_ref_string ()
void * | vips_value_get_blob ()
void | vips_value_set_blob ()
void | vips_value_set_blob_free ()
void | vips_value_set_array ()
void * | vips_value_get_array ()
double * | vips_value_get_array_double ()
void | vips_value_set_array_double ()
int * | vips_value_get_array_int ()
void | vips_value_set_array_int ()
GObject ** | vips_value_get_array_object ()
void | vips_value_set_array_object ()

## Object Hierarchy

        GBoxed
        ├── VipsArea
        ├── VipsArrayDouble
        ├── VipsArrayImage
        ├── VipsArrayInt
        ├── VipsBlob
        ├── VipsRefString
        ╰── VipsThing

## Includes

    #include <vips/vips.h>

## Description

A selection of `GType` defintions used by VIPS.

## Functions

### vips_thing_new ()

    VipsThing *
    vips_thing_new (int i);

#### Returns

a new VipsThing.

[transfer full]

### vips_area_copy ()

    VipsArea *
    vips_area_copy (VipsArea *area);

### vips_area_free_cb ()

    int
    vips_area_free_cb (void *mem,
                       VipsArea *area);

### vips_area_unref ()

    void
    vips_area_unref (VipsArea *area);

### vips_area_new ()

    VipsArea *
    vips_area_new (VipsCallbackFn free_fn,
                   void *data);

A VipsArea wraps a chunk of memory. It adds reference counting and a free function. It also keeps a count and a `GType`, so the area can be an array.

This type is used for things like passing an array of double or an array of VipsObject pointers to operations, and for reference-counted immutable strings.

Inital count == 1, so `_unref()` after attaching somewhere.

See also: `vips_area_unref()`.

[constructor]

#### Parameters

free_fn | `data` will be freed with this function. | [scope async]
data | data will be freed with this function |

#### Returns

the new VipsArea.

[transfer full]

### vips_area_new_array ()

    VipsArea *
    vips_area_new_array (GType type,
                         size_t sizeof_type,
                         int n);

An area which holds an array of elements of some `GType`. To set values for the elements, get the pointer and write.

See also: `vips_area_unref()`.

#### Parameters

type | `GType` of elements to store |
sizeof_type | sizeof() an element in the array |
n | number of elements in the array |

#### Returns

the new VipsArea.

[transfer full]

### vips_area_new_array_object ()

    VipsArea *
    vips_area_new_array_object (int n);

An area which holds an array of `GObject` s. See `vips_area_new_array()`. When the area is freed, each `GObject` will be unreffed.

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

See also: `vips_area_unref()`.

[constructor]

#### Parameters

n | number of elements in the array |

#### Returns

the new VipsArea.

[transfer full]

### vips_area_get_data ()

    void *
    vips_area_get_data (VipsArea *area,
                        size_t *length,
                        int *n,
                        GType *type,
                        size_t *sizeof_type);

Return the data pointer plus optionally the length in bytes of an area, the number of elements, the `GType` of each element and the `sizeof()` each element.

[method]

#### Parameters

area | VipsArea to fetch from |
length | optionally return length in bytes here. | [optional]
n | optionally return number of elements here. | [optional]
type | optionally return element type here. | [optional]
sizeof_type | optionally return `sizeof()` element type here. | [optional]

#### Returns

The pointer held by `area` .

[transfer none]

### VIPS_ARRAY_ADDR()

    #define             VIPS_ARRAY_ADDR( X, I )

### vips_ref_string_new ()

    VipsRefString *
    vips_ref_string_new (const char *str);

Create a new refstring. These are reference-counted immutable strings, used to store string data in vips image metadata.

Strings must be valid utf-8; use blob for binary data.

See also: `vips_area_unref()`.

#### Parameters

str | string to store. | [transfer none]

#### Returns

the new VipsRefString, or NULL on error.

[transfer full]

### vips_ref_string_get ()

    const char *
    vips_ref_string_get (VipsRefString *refstr,
                         size_t *length);

Get a pointer to the private string inside a refstr. Handy for language bindings.

See also: `vips_value_get_ref_string()`.

#### Parameters

refstr | the VipsRefString to fetch from |
length | return length here, optionally. | [allow-none]

#### Returns

The C string held by `refstr` .

[transfer none]

### vips_blob_new ()

    VipsBlob *
    vips_blob_new (VipsCallbackFn free_fn,
                   const void *data,
                   size_t length);

Like `vips_area_new()`, but track a length as well. The returned VipsBlob takes ownership of `data` and will free it with `free_fn` . Pass NULL for `free_fn` to not transfer ownership.

An area of mem with a free func and a length (some sort of binary object, like an ICC profile).

See also: `vips_area_unref()`.

#### Parameters

free_fn | `data` will be freed with this function. | [scope async][allow-none]
data | data to store. | [array length=length][element-type guint8][transfer full]
length | number of bytes in `data` |

#### Returns

the new VipsBlob.

[transfer full]

### vips_blob_copy ()

    VipsBlob *
    vips_blob_copy (const void *data,
                    size_t length);

Like `vips_blob_new()`, but take a copy of the data. Useful for bindings which strugle with callbacks.

See also: `vips_blob_new()`.

#### Parameters

data | data to store. | [array length=length][element-type guint8][transfer none]
length | number of bytes in `data` |

#### Returns

the new VipsBlob.

[transfer full]

### vips_blob_get ()

    const void *
    vips_blob_get (VipsBlob *blob,
                   size_t *length);

Get the data from a VipsBlob.

See also: `vips_blob_new()`.

#### Parameters

blob | VipsBlob to fetch from |
length | return number of bytes of data |

#### Returns

the data.

[array length=length][element-type guint8][transfer none]

### vips_blob_set ()

    void
    vips_blob_set (VipsBlob *blob,
                   VipsCallbackFn free_fn,
                   const void *data,
                   size_t length);

### vips_array_double_new ()

    VipsArrayDouble *
    vips_array_double_new (const double *array,
                           int n);

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

See also: VipsArea.

#### Parameters

array | array of double. | [array length=n]
n | number of doubles |

#### Returns

A new VipsArrayDouble.

[transfer full]

### vips_array_double_newv ()

    VipsArrayDouble *
    vips_array_double_newv (int n,
                            ...);

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

See also: `vips_array_double_new()`

#### Parameters

n | number of doubles |
... | list of double arguments |

#### Returns

A new VipsArrayDouble.

[transfer full]

### vips_array_double_get ()

    double *
    vips_array_double_get (VipsArrayDouble *array,
                           int *n);

Fetch a double array from a VipsArrayDouble. Useful for language bindings.

#### Parameters

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

#### Returns

array of double.

[array length=n][transfer none]

### vips_array_int_new ()

    VipsArrayInt *
    vips_array_int_new (const int *array,
                        int n);

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

See also: VipsArea.

#### Parameters

array | array of int. | [array length=n]
n | number of ints |

#### Returns

A new VipsArrayInt.

[transfer full]

### vips_array_int_newv ()

    VipsArrayInt *
    vips_array_int_newv (int n,
                         ...);

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

See also: `vips_array_int_new()`

#### Parameters

n | number of ints |
... | list of int arguments |

#### Returns

A new VipsArrayInt.

[transfer full]

### vips_array_int_get ()

    int *
    vips_array_int_get (VipsArrayInt *array,
                        int *n);

Fetch an int array from a VipsArrayInt. Useful for language bindings.

#### Parameters

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

#### Returns

array of int.

[array length=n][transfer none]

### vips_value_set_area ()

    void
    vips_value_set_area (GValue *value,
                         VipsCallbackFn free_fn,
                         void *data);

Set value to be a ref-counted area of memory with a free function.

#### Parameters

value | set this value. | [out]
free_fn | data will be freed with this function. | [scope async]
data | set `value` to track this pointer |

### vips_value_get_area ()

    void *
    vips_value_get_area (const GValue *value,
                         size_t *length);

Get the pointer from an area. Don't touch count (area is static).

#### Parameters

value | get from this value |
length | optionally return length here. | [allow-none]

#### Returns

The pointer held by `value` .

[transfer none]

### vips_value_get_save_string ()

    const char *
    vips_value_get_save_string (const GValue *value);

Get the C string held internally by the GValue.

#### Parameters

value | GValue to get from |

#### Returns

The C string held by `value` .

[transfer none]

### vips_value_set_save_string ()

    void
    vips_value_set_save_string (GValue *value,
                                const char *str);

Copies the C string into `value` .

`str` should be a valid utf-8 string.

#### Parameters

value | GValue to set. | [out]
str | C string to copy into the GValue |

### vips_value_set_save_stringf ()

    void
    vips_value_set_save_stringf (GValue *value,
                                 const char *fmt,
                                 ...);

Generates a string and copies it into `value` .

#### Parameters

value | GValue to set. | [out]
fmt | printf()-style format string |
... | arguments to `printf()`-formatted `fmt` |

### vips_value_get_ref_string ()

    const char *
    vips_value_get_ref_string (const GValue *value,
                               size_t *length);

Get the C string held internally by the `GValue`.

#### Parameters

value | `GValue` to get from |
length | return length here, optionally. | [allow-none]

#### Returns

The C string held by `value` .

[transfer none]

### vips_value_set_ref_string ()

    void
    vips_value_set_ref_string (GValue *value,
                               const char *str);

Copies the C string `str` into `value` .

vips_ref_string are immutable C strings that are copied between images by copying reference-counted pointers, making them much more efficient than regular `GValue` strings.

`str` should be a valid utf-8 string.

#### Parameters

value | `GValue` to set. | [out]
str | C string to copy into the GValue |

### vips_value_get_blob ()

    void *
    vips_value_get_blob (const GValue *value,
                         size_t *length);

Returns the data pointer from a blob. Optionally returns the length too.

blobs are things like ICC profiles or EXIF data. They are relocatable, and are saved to VIPS files for you coded as base64 inside the XML. They are copied by copying reference-counted pointers.

See also: `vips_value_set_blob()`

#### Parameters

value | GValue to set |
length | optionally return length of memory area. | [allow-none]

#### Returns

The pointer held by `value` .

[transfer none]

### vips_value_set_blob ()

    void
    vips_value_set_blob (GValue *value,
                         VipsCallbackFn free_fn,
                         const void *data,
                         size_t length);

Sets `value` to hold a `data` . When `value` is freed, `data` will be freed with `free_fn` . `value` also holds a note of the size of the memory area.

blobs are things like ICC profiles or EXIF data. They are relocatable, and are saved to VIPS files for you coded as base64 inside the XML. They are copied by copying reference-counted pointers.

See also: `vips_value_get_blob()`

#### Parameters

value | GValue to set. | [out]
free_fn | free function for `data` . | [scope async]
data | pointer to area of memory |
length | length of memory area |

### vips_value_set_blob_free ()

    void
    vips_value_set_blob_free (GValue *value,
                              void *data,
                              size_t length);

Just like `vips_value_set_blob()`, but when `value` is freed, `data` will be freed with `g_free()`.

This can be easier to call for language bindings.

See also: `vips_value_set_blob()`

#### Parameters

value | GValue to set. | [out]
data | pointer to area of memory |
length | length of memory area |

### vips_value_set_array ()

    void
    vips_value_set_array (GValue *value,
                          int n,
                          GType type,
                          size_t sizeof_type);

Set `value` to be an array of things.

This allocates memory but does not initialise the contents: get the pointer and write instead.

#### Parameters

value | `GValue` to set. | [out]
n | number of elements |
type | the type of each element |
sizeof_type | the sizeof each element |

### vips_value_get_array ()

    void *
    vips_value_get_array (const GValue *value,
                          int *n,
                          GType *type,
                          size_t *sizeof_type);

Return the pointer to the array held by `value` . Optionally return the other properties of the array in `n` , `type` , `sizeof_type` .

See also: `vips_value_set_array()`.

#### Parameters

value | `GValue` to get from |
n | return the number of elements here, optionally. | [allow-none]
type | return the type of each element here, optionally. | [allow-none]
sizeof_type | return the sizeof each element here, optionally. | [allow-none]

#### Returns

The array address.

[transfer none]

### vips_value_get_array_double ()

    double *
    vips_value_get_array_double (const GValue *value,
                                 int *n);

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

See also: `vips_array_double_new()`.

#### Parameters

value | `GValue` to get from |
n | return the number of elements here, optionally. | [allow-none]

#### Returns

The array address.

[transfer none]

### vips_value_set_array_double ()

    void
    vips_value_set_array_double (GValue *value,
                                 const double *array,
                                 int n);

Set `value` to hold a copy of `array` . Pass in the array length in `n` .

See also: `vips_array_double_get()`.

#### Parameters

value | `GValue` to get from. | [out]
array | array of doubles. | [array length=n][allow-none]
n | the number of elements |

### vips_value_get_array_int ()

    int *
    vips_value_get_array_int (const GValue *value,
                              int *n);

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

See also: `vips_array_int_new()`.

#### Parameters

value | `GValue` to get from |
n | return the number of elements here, optionally. | [allow-none]

#### Returns

The array address.

[transfer none]

### vips_value_set_array_int ()

    void
    vips_value_set_array_int (GValue *value,
                              const int *array,
                              int n);

Set `value` to hold a copy of `array` . Pass in the array length in `n` .

See also: `vips_array_int_get()`.

#### Parameters

value | `GValue` to get from. | [out]
array | array of ints. | [array length=n][allow-none]
n | the number of elements |

### vips_value_get_array_object ()

    GObject **
    vips_value_get_array_object (const GValue *value,
                                 int *n);

Return the start of the array of `GObject` held by `value` . Optionally return the number of elements in `n` .

See also: `vips_area_new_array_object()`.

[skip]

#### Parameters

value | `GValue` to get from |
n | return the number of elements here, optionally. | [allow-none]

#### Returns

The array address.

[transfer none]

### vips_value_set_array_object ()

    void
    vips_value_set_array_object (GValue *value,
                                 int n);

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

See also: `vips_value_get_array_object()`.

#### Parameters

value | `GValue` to set. | [out]
n | the number of elements |

## See Also

header