IM_META

Section: C Library Functions (3)
Updated: 7 June 2005
Index Return to Main Contents

NAME

im_meta_set_int, im_meta_get_int, im_meta_set_double, im_meta_get_double, im_meta_set_area, im_meta_get_area, im_meta_set_string, im_meta_get_string, im_meta_set_blob, im_meta_get_blob, im_meta_set, im_meta_get - read and write extra header fields

SYNOPSIS

#include <vips/vips.h>

int im_meta_set_int( IMAGE *im, const char *field, int i );
int im_meta_get_int( IMAGE *im, const char *field, int *i );
int im_meta_set_double( IMAGE *im, const char *field, double d );
int im_meta_get_double( IMAGE *im, const char *field, double *d );
int im_meta_set_area( IMAGE *im, const char *field,
  im_callback_fn free_fn, void *data );
int im_meta_get_area( IMAGE *im, const char *field, void **data );
int im_meta_set_string( IMAGE *im, const char *field,
  const char *str );
int im_meta_get_string( IMAGE *im, const char *field, char **str );
int im_meta_set_blob( IMAGE *im, const char *field,
  im_callback_fn free_fn, void *blob, size_t blob_length );
int im_meta_get_blob( IMAGE *im, const char *field,
  void **blob, size_t *blob_length );

typedef int (*im_callback_fn)( void *, void * );

int im_meta_set( IMAGE *im, const char *field, GValue *value );
int im_meta_get( IMAGE *im, const char *field, GValue *value_copy );
GType im_meta_get_type( IMAGE *im, const char *field );

#define IM_TYPE_SAVE_STRING (im_save_string_get_type())
GType im_save_string_get_type( void );
const char *im_save_string_get( const GValue *value );
void im_save_string_set( GValue *value, const char *str );
void im_save_string_setf( GValue *value, const char *fmt, ... );

DESCRIPTION

These functions read and write extra image header fields. Writing to a field destroys any old value. You must read a field with the correct type of reader: you can't read an int field as a string. Fields are copied when images are processed, so you can use them to pass information to subsequent operations. Unless otherwise noted, image header fields created with these functions are also saved to disc when an image is saved in VIPS format, and automatically restored when the image is loaded again.

im_meta_set_int(3) sets an integer field. Any existing field of any type with this name is removed. It returns 0 for success, or -1 on error setting im_error(3).

im_meta_get_int(3) reads an integer field. It returns 0 for success, or -1 on error, setting im_error(3). It can fail if the field does not exist, or if the field is not an int.

im_meta_set_double(3) and im_meta_get_double(3) work exactly as im_meta_set_int(3) and im_meta_get_int(3).

im_meta_set_area(3) sets a field which is an area of memory. When the field is copied to a subsequent IMAGE, VIPS just copies the pointer. VIPS keeps a reference count and when the last IMAGE using this field is closed, VIPS will call free_fn to release the memory. You can therefore use this function to attach very large areas of memory to images efficiently. Areas cannot be saved to VIPS files on disc, since there is no known length.

im_meta_set_string(3) is a convenience function over im_meta_set_area(3). It copies the string, and then shares that copy between all images derived from this IMAGE.

im_meta_get_string(3) is a convenience function over im_meta_get_area(3). It returns a pointer to the string being mananged by VIPS. Do not free the return result!

im_meta_set_blob(3) sets a field which is a blob (binary object). A blob is just like string, except that rather than being NULL-terminated, you must pass an explicit length.

im_meta_set(3), im_meta_get_type(3) and im_meta_get(3) operate at a lower level: they let you set image header fields as GValue. Use one of the convenience functions above if possible. im_meta_get_type(3) returns 0 if the field is not defined.

In order for the autoload/save to VIPS files to work, you need to use a GType with a transform defined to and from IM_TYPE_SAVE_STRING.

RETURN VALUE

The functions return 0 success and -1 on error.

COPYRIGHT

The National Gallery, 2005.

AUTHOR

Markus Wollgarten and John Cupitt