sergiotarxz/libvips
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

gtkdoc for meta

Browse Source
This commit is contained in:
John Cupitt 2009-10-01 17:30:02 +00:00
parent cf7e44bfde
commit f94146df7c
6 changed files with 286 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
ChangeLog
View File

@ -50,6 +50,7 @@
- better im_check() functions
- added im_flood_other() as start of simple segmentation operator
- added im_segment()
- gtk-doc comments for meta
25/3/09 started 7.18.0
- revised version numbers

4
TODO
View File

@ -1,7 +1,3 @@
- doing meta.c, reached im_save_string_get_type()
how should we doc im_save_string? read the gobject sources for param spec
types for hints?
- im_flood*() should use inline rather than #define

10
doc/reference/libvips-docs.sgml.in
View File

@ -16,12 +16,17 @@
</bookinfo>
<chapter>
<title>API by section</title>
<title>Core VIPS API</title>
<xi:include href="xml/image.xml"/>
<xi:include href="xml/meta.xml"/>
<xi:include href="xml/buf.xml"/>
</chapter>
<chapter>
<title>VIPS operation API by section</title>
<xi:include href="xml/arithmetic.xml"/>
<xi:include href="xml/boolean.xml"/>
<xi:include href="xml/relational.xml"/>
<xi:include href="xml/buf.xml"/>
</chapter>
<chapter>
@ -32,7 +37,6 @@
<xi:include href="xml/proto.xml"/>
<xi:include href="xml/colour.xml"/>
<xi:include href="xml/region.xml"/>
<xi:include href="xml/meta.xml"/>
<xi:include href="xml/transform.xml"/>
<xi:include href="xml/util.xml"/>
<xi:include href="xml/threadgroup.xml"/>

45
libvips/include/vips/meta.h
View File

@ -34,14 +34,40 @@
extern "C" {
#endif /*__cplusplus*/
/* Reserved header names.
/**
* IM_META_EXIF_NAME:
*
* The name that JPEG read and write operations use for the image's EXIF data.
*/
#define IM_META_EXIF_NAME "exif-data"
/**
* IM_META_ICC_NAME:
*
* The name we use to attach an ICC profile. The file read and write
* operations for TIFF, JPEG, PNG and others use this item of metadata to
* attach and save ICC profiles. The profile is updated by the
* im_icc_transform() operations.
*/
#define IM_META_ICC_NAME "icc-profile-data"
/**
* IM_META_XML:
*
* The original XML that was used to code the metadata after reading a VIPS
* format file.
*/
#define IM_META_XML "xml-header"
/**
* IM_META_RESOLUTION_UNIT:
*
* The JPEG and TIFF read and write operations use this to record the
* file's preferred unit for resolution.
*/
#define IM_META_RESOLUTION_UNIT "resolution-unit"
/* Types we add for meta fields.
/**
* IM_TYPE_SAVE_STRING:
*
* The #GType for an "im_save_string".
*/
#define IM_TYPE_SAVE_STRING (im_save_string_get_type())
GType im_save_string_get_type( void );
@ -50,15 +76,30 @@ void im_save_string_set( GValue *value, const char *str );
void im_save_string_setf( GValue *value, const char *fmt, ... )
__attribute__((format(printf, 2, 3)));
/**
* IM_TYPE_AREA:
*
* The #GType for an #im_area.
*/
#define IM_TYPE_AREA (im_area_get_type())
GType im_area_get_type( void );
/**
* IM_TYPE_REF_STRING:
*
* The #GType for an #im_refstring.
*/
#define IM_TYPE_REF_STRING (im_ref_string_get_type())
GType im_ref_string_get_type( void );
int im_ref_string_set( GValue *value, const char *str );
const char *im_ref_string_get( const GValue *value );
size_t im_ref_string_get_length( const GValue *value );
/**
* IM_TYPE_BLOB:
*
* The #GType for an #im_blob.
*/
#define IM_TYPE_BLOB (im_blob_get_type())
GType im_blob_get_type( void );
void *im_blob_get( const GValue *value, size_t *data_length );

4
libvips/iofuncs/im_open_vips.c
View File

@ -84,10 +84,10 @@
* SECTION: image
* @short_description: the VIPS image class
* @stability: Stable
* @see_also: #vips
* @see_also: vips
* @include: vips/vips.h
*
* The VIPS image class and associated macros.
* The VIPS image class and associated types and macros.
*/
/**

249
libvips/iofuncs/meta.c
View File

@ -20,6 +20,8 @@
* 29/8/09
* - im_meta_get_type() renamed as im_meta_get_typeof() to prevent
* confusion with GObject-style type definers
* 1/10/09
* - gtkdoc comments
*/
/*
@ -84,18 +86,21 @@
* SECTION: meta
* @short_description: get and set image metadata
* @stability: Stable
* @see_also: #vips
* @see_also: header
* @include: vips/vips.h
*
* You can attach arbitary metadata to images. Metadata is copied as images
* You can attach arbitrary metadata to images. Metadata is copied as images
* are processed, so all images which used this image as input, directly or
* indirectly, will have this same bit of metadata attached to them. Metadata
* indirectly, will have this same bit of metadata attached to them. Copying
* is implemented with reference-counted pointers, so it is efficient, even for
* large items of data. This does however mean that metadata items need to be
* immutable. Metadata
* is handy for things like ICC profiles or EXIF data.
*
* Various convenience functions (eg. im_meta_set_int()) let you easily attach
* simple types like
* numbers, strings and memory blocks to images. Use im_meta_map() to loop
* over an image's metadata.
* numbers, strings and memory blocks to images. Use im_header_map() to loop
* over an image's fields, including all metadata.
*
* Items of metadata are identified by strings. Some strings are reserved, for
* example the ICC pofile for an image is known by convention as
@ -357,7 +362,8 @@ im_meta_set( IMAGE *im, const char *field, GValue *value )
* but uninitialised.
*
* This will return -1 and add a message to the error buffer if the item
* of metadata does not exist. Use im_meta_typeof() to test for the existence
* of metadata does not exist. Use im_meta_get_typeof() to test for the
* existence
* of a piece of metadata first if you are not certain it will be there.
*
* For example, to read a double from an image (though of course you would use
@ -383,7 +389,7 @@ im_meta_set( IMAGE *im, const char *field, GValue *value )
* return( 0 );
* ]|
*
* See also: im_meta_typeof(), im_meta_set().
* See also: im_meta_get_typeof(), im_meta_set().
*
* Returns: 0 on success, -1 otherwise.
*/
@ -486,12 +492,27 @@ im_save_string_get_type( void )
return( type );
}
/**
* im_save_string_get:
* @value: GValue to get from
*
* Get the C string held internally by the GValue.
*
* Returns: The C string held by @value. This must not be freed.
*/
const char *
im_save_string_get( const GValue *value )
{
return( (char *) g_value_get_boxed( value ) );
}
/**
* im_save_string_set:
* @value: GValue to set
* @str: C string to copy into the GValue
*
* Copies the C string into @value.
*/
void
im_save_string_set( GValue *value, const char *str )
{
@ -500,6 +521,14 @@ im_save_string_set( GValue *value, const char *str )
g_value_set_boxed( value, str );
}
/**
* im_save_string_setf:
* @value: GValue to set
* @fmt: printf()-style format string
* @Varargs: arguments to printf()-formatted @fmt
*
* Generates a string and copies it into @value.
*/
void
im_save_string_setf( GValue *value, const char *fmt, ... )
{
@ -515,7 +544,18 @@ im_save_string_setf( GValue *value, const char *fmt, ... )
g_free( str );
}
/* Read/write int, double metadata.
/**
* im_meta_set_int:
* @im: image to attach the metadata to
* @field: metadata name
* @i: metadata value
*
* Attaches @i as a metadata item on @im under the name @field. A convenience
* function over im_meta_set().
*
* See also: im_meta_get_int(), im_meta_set()
*
* Returns: 0 on success, -1 otherwise.
*/
int
im_meta_set_int( IMAGE *im, const char *field, int i )
@ -528,6 +568,21 @@ im_meta_set_int( IMAGE *im, const char *field, int i )
return( meta_set_value( im, field, &value ) );
}
/**
* im_meta_get_int:
* @im: image to get the metadata from
* @field: metadata name
* @i: return metadata value
*
* Gets @i from @im under the name @field. A convenience
* function over im_meta_get(). Use im_meta_get_typeof() to test for the
* existance
* of a piece of metadata.
*
* See also: im_meta_set_int(), im_meta_get(), im_meta_get_typeof()
*
* Returns: 0 on success, -1 otherwise.
*/
int
im_meta_get_int( IMAGE *im, const char *field, int *i )
{
@ -541,6 +596,19 @@ im_meta_get_int( IMAGE *im, const char *field, int *i )
return( 0 );
}
/**
* im_meta_set_double:
* @im: image to attach the metadata to
* @field: metadata name
* @d: metadata value
*
* Attaches @d as a metadata item on @im under the name @field. A convenience
* function over im_meta_set().
*
* See also: im_meta_get_double(), im_meta_set()
*
* Returns: 0 on success, -1 otherwise.
*/
int
im_meta_set_double( IMAGE *im, const char *field, double d )
{
@ -552,6 +620,21 @@ im_meta_set_double( IMAGE *im, const char *field, double d )
return( meta_set_value( im, field, &value ) );
}
/**
* im_meta_get_double:
* @im: image to get the metadata from
* @field: metadata name
* @d: return metadata value
*
* Gets @d from @im under the name @field. A convenience
* function over im_meta_get(). Use im_meta_get_typeof() to test for the
* existance
* of a piece of metadata.
*
* See also: im_meta_set_double(), im_meta_get(), im_meta_get_typeof()
*
* Returns: 0 on success, -1 otherwise.
*/
int
im_meta_get_double( IMAGE *im, const char *field, double *d )
{
@ -758,7 +841,19 @@ value_get_area_length( const GValue *value )
return( area->length );
}
/* Read/write ref-counted mem area.
/**
* im_meta_set_area:
* @im: image to attach the metadata to
* @field: metadata name
* @free_fn: free function for @data
* @data: pointer to area of memory
*
* Attaches @data as a metadata item on @im under the name @field. When VIPS
* no longer needs the metadata, it will be freed with @free_fn.
*
* See also: im_meta_get_double(), im_meta_set()
*
* Returns: 0 on success, -1 otherwise.
*/
int
im_meta_set_area( IMAGE *im, const char *field,
@ -771,6 +866,21 @@ im_meta_set_area( IMAGE *im, const char *field,
return( meta_set_value( im, field, &value ) );
}
/**
* im_meta_get_area:
* @im: image to get the metadata from
* @field: metadata name
* @data: return metadata value
*
* Gets @data from @im under the name @field. A convenience
* function over im_meta_get(). Use im_meta_get_typeof() to test for the
* existance
* of a piece of metadata.
*
* See also: im_meta_set_area(), im_meta_get(), im_meta_get_typeof()
*
* Returns: 0 on success, -1 otherwise.
*/
int
im_meta_get_area( IMAGE *im, const char *field, void **data )
{
@ -784,7 +894,13 @@ im_meta_get_area( IMAGE *im, const char *field, void **data )
return( 0 );
}
/* Get a char* from a refstring.
/**
* im_ref_string_get:
* @value: GValue to get from
*
* Get the C string held internally by the GValue.
*
* Returns: The C string held by @value. This must not be freed.
*/
const char *
im_ref_string_get( const GValue *value )
@ -792,7 +908,13 @@ im_ref_string_get( const GValue *value )
return( value_get_area_data( value ) );
}
/* Get cached strlen() from a refstring.
/**
* im_ref_string_get_length:
* @value: GValue to get from
*
* Gets the cached string length held internally by the refstring.
*
* Returns: The length of the string.
*/
size_t
im_ref_string_get_length( const GValue *value )
@ -800,7 +922,18 @@ im_ref_string_get_length( const GValue *value )
return( value_get_area_length( value ) );
}
/* Set value to be a ref-counted string.
/**
* im_ref_string_set:
* @value: GValue to set
* @str: C string to copy into the GValue
*
* Copies the C string @str into @value.
*
* im_ref_string are immutable C strings that are copied between images by
* copying reference-counted pointers, making the much more efficient than
* regular GValue strings.
*
* Returns: 0 on success, -1 otherwise.
*/
int
im_ref_string_set( GValue *value, const char *str )
@ -877,7 +1010,18 @@ im_ref_string_get_type( void )
return( type );
}
/* Read/write C string.
/**
* im_meta_set_string:
* @im: image to attach the metadata to
* @field: metadata name
* @str: metadata value
*
* Attaches @str as a metadata item on @im under the name @field. A convenience
* function over im_meta_set() using an im_ref_string.
*
* See also: im_meta_get_double(), im_meta_set(), im_ref_string
*
* Returns: 0 on success, -1 otherwise.
*/
int
im_meta_set_string( IMAGE *im, const char *field, const char *str )
@ -890,6 +1034,22 @@ im_meta_set_string( IMAGE *im, const char *field, const char *str )
return( meta_set_value( im, field, &value ) );
}
/**
* im_meta_get_string:
* @im: image to get the metadata from
* @field: metadata name
* @str: return metadata value
*
* Gets @str from @im under the name @field. A convenience
* function over im_meta_get(). Use im_meta_get_typeof() to test for the
* existance
* of a piece of metadata.
*
* See also: im_meta_set_string(), im_meta_get(), im_meta_get_typeof(),
* im_ref_string
*
* Returns: 0 on success, -1 otherwise.
*/
int
im_meta_get_string( IMAGE *im, const char *field, char **str )
{
@ -905,7 +1065,17 @@ im_meta_get_string( IMAGE *im, const char *field, char **str )
return( 0 );
}
/* Get a void * from a BLOB.
/**
* im_blob_get:
* @value: GValue to get from
* @blob_length: return the blob length here, optionally
*
* Get the address of the blob (binary large object) being held in @value and
* optionally return its length in @blob_length.
*
* See also: im_blob_set()
*
* Returns: The blob address.
*/
void *
im_blob_get( const GValue *value, size_t *blob_length )
@ -987,7 +1157,24 @@ im_blob_get_type( void )
return( type );
}
/* Set value to be a blob.
/**
* im_blob_set:
* @value: GValue to set
* @free_fn: free function for @data
* @blob: pointer to area of memory
* @blob_length: length of memory area
*
* Sets @value to hold a pointer to @blob. When @value is freed, @blob will be
* freed with @free_fn. @value also holds a note of the length 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: im_blob_get()
*
* Returns: 0 on success, -1 otherwise.
*/
int
im_blob_set( GValue *value,
@ -1006,7 +1193,20 @@ im_blob_set( GValue *value,
return( 0 );
}
/* Read/write blob.
/**
* im_meta_set_blob:
* @im: image to attach the metadata to
* @field: metadata name
* @free_fn: free function for @data
* @blob: pointer to area of memory
* @blob_length: length of memory area
*
* Attaches @blob as a metadata item on @im under the name @field. A convenience
* function over im_meta_set() using an im_blob.
*
* See also: im_meta_get_blob(), im_meta_set(), im_blob
*
* Returns: 0 on success, -1 otherwise.
*/
int
im_meta_set_blob( IMAGE *im, const char *field,
@ -1020,6 +1220,23 @@ im_meta_set_blob( IMAGE *im, const char *field,
return( meta_set_value( im, field, &value ) );
}
/**
* im_meta_get_blob:
* @im: image to get the metadata from
* @field: metadata name
* @blob: pointer to area of memory
* @blob_length: return the blob length here, optionally
*
* Gets @blob from @im under the name @field, optionally return its length in
* @blob_length. A convenience
* function over im_meta_get(). Use im_meta_get_typeof() to test for the
* existance
* of a piece of metadata.
*
* See also: im_meta_get(), im_meta_get_typeof(), im_blob_get(), im_blob
*
* Returns: 0 on success, -1 otherwise.
*/
int
im_meta_get_blob( IMAGE *im, const char *field,
void **blob, size_t *blob_length )