| .TH IM_META 3 "7 June 2005" |
| .SH 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 |
| .SH SYNOPSIS |
| #include <vips/vips.h> |
| |
| int im_meta_set_int( IMAGE *im, const char *field, int i ); |
| .br |
| int im_meta_get_int( IMAGE *im, const char *field, int *i ); |
| .br |
| int im_meta_set_double( IMAGE *im, const char *field, double d ); |
| .br |
| int im_meta_get_double( IMAGE *im, const char *field, double *d ); |
| .br |
| int im_meta_set_area( IMAGE *im, const char *field, |
| im_callback_fn free_fn, void *data ); |
| .br |
| int im_meta_get_area( IMAGE *im, const char *field, void **data ); |
| .br |
| int im_meta_set_string( IMAGE *im, const char *field, |
| const char *str ); |
| .br |
| int im_meta_get_string( IMAGE *im, const char *field, char **str ); |
| .br |
| int im_meta_set_blob( IMAGE *im, const char *field, |
| im_callback_fn free_fn, void *blob, size_t blob_length ); |
| .br |
| 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 ); |
| .br |
| int im_meta_get( IMAGE *im, const char *field, GValue *value_copy ); |
| .br |
| GType im_meta_get_type( IMAGE *im, const char *field ); |
| |
| #define IM_TYPE_SAVE_STRING (im_save_string_get_type()) |
| .br |
| GType im_save_string_get_type( void ); |
| .br |
| const char *im_save_string_get( const GValue *value ); |
| .br |
| void im_save_string_set( GValue *value, const char *str ); |
| .br |
| void im_save_string_setf( GValue *value, const char *fmt, ... ); |
| |
| .SH 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. |
| |
| .B 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 |
| .B im_error(3). |
| |
| .B im_meta_get_int(3) |
| reads an integer field. It returns 0 for success, or -1 on error, setting |
| .B im_error(3). |
| It can fail if the field does not exist, or if the field is not an int. |
| |
| .B im_meta_set_double(3) |
| and |
| .B im_meta_get_double(3) |
| work exactly as |
| .B im_meta_set_int(3) |
| and |
| .B im_meta_get_int(3). |
| |
| .B 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 |
| .B 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. |
| |
| .B im_meta_set_string(3) |
| is a convenience function over |
| .B im_meta_set_area(3). |
| It copies the string, and |
| then shares that copy between all images derived from this IMAGE. |
| |
| .B im_meta_get_string(3) |
| is a convenience function over |
| .B im_meta_get_area(3). |
| It returns a pointer to the string being mananged by VIPS. Do not free the |
| return result! |
| |
| .B 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. |
| |
| .B im_meta_set(3), |
| .B im_meta_get_type(3) |
| and |
| .B 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. |
| .B 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 |
| .B IM_TYPE_SAVE_STRING. |
| |
| .SH RETURN VALUE |
| The functions return 0 success and -1 on error. |
| .SH SEE ALSO |
| im_header_int(3), im_header_map(3). |
| .SH COPYRIGHT |
| The National Gallery, 2005. |
| .SH AUTHOR |
| Markus Wollgarten and John Cupitt |
