gtkdoc comments for header
This commit is contained in:
John Cupitt
parent
c696bdc1ec
commit
f4ef665b49
|
|
@ -51,6 +51,7 @@
|
|||
- added im_flood_other() as start of simple segmentation operator
|
||||
- added im_segment()
|
||||
- gtk-doc comments for meta
|
||||
- gtk-doc comments for header
|
||||
|
||||
25/3/09 started 7.18.0
|
||||
- revised version numbers
|
||||
|
|
|
|||
|
|
@ -70,9 +70,24 @@
|
|||
* @include: vips/vips.h
|
||||
*
|
||||
* These functions let you get at image header data (including metadata) in a
|
||||
* uniform way.
|
||||
* uniform way. They are handy for language bindings but less useful for C
|
||||
* users.
|
||||
*
|
||||
* They first search the
|
||||
* VIPS header
|
||||
* fields (see <link linkend="libvips-image">image</link>), then search for
|
||||
* a metadata field of that name (see
|
||||
* <link linkend="libvips-meta">meta</link>).
|
||||
* If no field of that name is found, it sets an error and returns -1.
|
||||
* Use im_header_get_typeof() to test for the
|
||||
* existance and GType
|
||||
* of a header field.
|
||||
*
|
||||
* See <link linkend="libvips-meta">meta</link>
|
||||
* for a set of functions for adding new metadata to an image.
|
||||
*/
|
||||
|
||||
|
||||
/* Name, offset pair.
|
||||
*/
|
||||
typedef struct _HeaderField {
|
||||
|
|
@ -106,6 +121,19 @@ static HeaderField string_field[] = {
|
|||
{ "filename", G_STRUCT_OFFSET( IMAGE, filename ) }
|
||||
};
|
||||
|
||||
/**
|
||||
* im_header_int:
|
||||
* @im: image to get the header field from
|
||||
* @field: field name
|
||||
* @out: return field value
|
||||
*
|
||||
* Gets @out from @im under the name @field. This function searches for
|
||||
* int-valued fields.
|
||||
*
|
||||
* See also: im_header_get(), im_header_get_typeof()
|
||||
*
|
||||
* Returns: 0 on success, -1 otherwise.
|
||||
*/
|
||||
int
|
||||
im_header_int( IMAGE *im, const char *field, int *out )
|
||||
{
|
||||
|
|
@ -128,6 +156,20 @@ im_header_int( IMAGE *im, const char *field, int *out )
|
|||
return( 0 );
|
||||
}
|
||||
|
||||
/**
|
||||
* im_header_double:
|
||||
* @im: image to get the header field from
|
||||
* @field: field name
|
||||
* @out: return field value
|
||||
*
|
||||
* Gets @out from @im under the name @field.
|
||||
* This function searches for
|
||||
* double-valued fields.
|
||||
*
|
||||
* See also: im_header_get(), im_header_get_typeof()
|
||||
*
|
||||
* Returns: 0 on success, -1 otherwise.
|
||||
*/
|
||||
int
|
||||
im_header_double( IMAGE *im, const char *field, double *out )
|
||||
{
|
||||
|
|
@ -150,6 +192,20 @@ im_header_double( IMAGE *im, const char *field, double *out )
|
|||
return( 0 );
|
||||
}
|
||||
|
||||
/**
|
||||
* im_header_string:
|
||||
* @im: image to get the header field from
|
||||
* @field: field name
|
||||
* @out: return field value
|
||||
*
|
||||
* Gets @out from @im under the name @field.
|
||||
* This function searches for
|
||||
* string-valued fields.
|
||||
*
|
||||
* See also: im_header_get(), im_header_get_typeof()
|
||||
*
|
||||
* Returns: 0 on success, -1 otherwise.
|
||||
*/
|
||||
int
|
||||
im_header_string( IMAGE *im, const char *field, char **out )
|
||||
{
|
||||
|
|
@ -172,6 +228,19 @@ im_header_string( IMAGE *im, const char *field, char **out )
|
|||
return( 0 );
|
||||
}
|
||||
|
||||
/**
|
||||
* im_header_get_typeof:
|
||||
* @im: image to test
|
||||
* @field: the name to search for
|
||||
*
|
||||
* Read the GType for a header field. Returns zero if there is no
|
||||
* field of that name.
|
||||
*
|
||||
* See also: im_header_get().
|
||||
*
|
||||
* Returns: the GType of the field, or zero if there is no
|
||||
* field of that name.
|
||||
*/
|
||||
GType
|
||||
im_header_get_typeof( IMAGE *im, const char *field )
|
||||
{
|
||||
|
|
@ -196,6 +265,48 @@ im_header_get_typeof( IMAGE *im, const char *field )
|
|||
/* Fill value_copy with a copy of the value, -1 on error. value_copy must be
|
||||
* zeroed but uninitialised. User must g_value_unset( value ).
|
||||
*/
|
||||
|
||||
/**
|
||||
* im_header_get:
|
||||
* @im: image to get the field from from
|
||||
* @field: the name to give the metadata
|
||||
* @value_copy: the GValue is copied into this
|
||||
*
|
||||
* Fill @value_copy with a copy of the header field. @value_copy must be zeroed
|
||||
* but uninitialised.
|
||||
*
|
||||
* This will return -1 and add a message to the error buffer if the field
|
||||
* does not exist. Use im_header_get_typeof() to test for the
|
||||
* existence
|
||||
* of a field 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
|
||||
* im_header_double() in practice):
|
||||
*
|
||||
* |[
|
||||
* GValue value = { 0 };
|
||||
* double d;
|
||||
*
|
||||
* if( im_header_get( im, field, &value ) )
|
||||
* return( -1 );
|
||||
*
|
||||
* if( G_VALUE_TYPE( &value ) != G_TYPE_DOUBLE ) {
|
||||
* im_error( "mydomain", _( "field \"%s\" is of type %s, not double" ),
|
||||
* field, g_type_name( G_VALUE_TYPE( &value ) ) );
|
||||
* g_value_unset( &value );
|
||||
* return( -1 );
|
||||
* }
|
||||
*
|
||||
* d = g_value_get_double( &value );
|
||||
* g_value_unset( &value );
|
||||
*
|
||||
* return( 0 );
|
||||
* ]|
|
||||
*
|
||||
* See also: im_header_get_typeof(), im_header_double().
|
||||
*
|
||||
* Returns: 0 on success, -1 otherwise.
|
||||
*/
|
||||
int
|
||||
im_header_get( IMAGE *im, const char *field, GValue *value_copy )
|
||||
{
|
||||
|
|
@ -240,6 +351,22 @@ header_map_fn( Meta *meta, im_header_map_fn fn, void *a )
|
|||
return( fn( meta->im, meta->field, &meta->value, a ) );
|
||||
}
|
||||
|
||||
/**
|
||||
* im_header_map:
|
||||
* @im: image to map over
|
||||
* @fn: function to call for each header field
|
||||
* @a: user data for function
|
||||
*
|
||||
* This function calls @fn for every header field, including every item of
|
||||
* metadata.
|
||||
*
|
||||
* Like all _map functions, the user function should return %NULL to continue
|
||||
* iteration, or a non-%NULL pointer to indicate early termination.
|
||||
*
|
||||
* See also: im_header_get_typeof(), im_header_get().
|
||||
*
|
||||
* Returns: %NULL on success, the failing pointer otherwise.
|
||||
*/
|
||||
void *
|
||||
im_header_map( IMAGE *im, im_header_map_fn fn, void *a )
|
||||
{
|
||||
|
|
|
|||
|
|
@ -303,11 +303,11 @@ im__meta_cp( IMAGE *dst, const IMAGE *src )
|
|||
|
||||
/**
|
||||
* im_meta_set:
|
||||
* @im: #IMAGE to set the metadata on
|
||||
* @im: image to set the metadata on
|
||||
* @field: the name to give the metadata
|
||||
* @value: the GValue to copy into the image
|
||||
*
|
||||
* Set a piece of metadata on an #IMAGE. Any old metadata with that name is
|
||||
* Set a piece of metadata on @im. Any old metadata with that name is
|
||||
* destroyed. The GValue is copied into the image, so you need to unset the
|
||||
* value when you're done with it.
|
||||
*
|
||||
|
|
@ -354,7 +354,7 @@ im_meta_set( IMAGE *im, const char *field, GValue *value )
|
|||
|
||||
/**
|
||||
* im_meta_get:
|
||||
* @im: #IMAGE to set the metadata on
|
||||
* @im: image to get the metadata from
|
||||
* @field: the name to give the metadata
|
||||
* @value_copy: the GValue is copied into this
|
||||
*
|
||||
|
|
@ -373,7 +373,7 @@ im_meta_set( IMAGE *im, const char *field, GValue *value )
|
|||
* GValue value = { 0 };
|
||||
* double d;
|
||||
*
|
||||
* if( meta_get_value( im, field, &value ) )
|
||||
* if( im_meta_get( im, field, &value ) )
|
||||
* return( -1 );
|
||||
*
|
||||
* if( G_VALUE_TYPE( &value ) != G_TYPE_DOUBLE ) {
|
||||
|
|
@ -416,8 +416,8 @@ im_meta_get( IMAGE *im, const char *field, GValue *value_copy )
|
|||
|
||||
/**
|
||||
* im_meta_get_typeof:
|
||||
* @im: #IMAGE to set the metadata on
|
||||
* @field: the name to give the metadata
|
||||
* @im: image to test
|
||||
* @field: the name to search for
|
||||
*
|
||||
* Read the GType for an item of metadata. Returns zero if there is no
|
||||
* metadata of that name.
|
||||
|
|
|
|||
Loading…
Reference in New Issue