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.
SEE ALSO
im_header_int(3), im_header_map(3).
COPYRIGHT
The National Gallery, 2005.
AUTHOR
Markus Wollgarten and John Cupitt
7 June 2005 IM_META(3)