Top | ![]() |
![]() |
![]() |
![]() |
enum | GeglResolutionUnit |
enum | GeglMapFlags |
#define | GEGL_TYPE_METADATA |
GeglMetadataMap | |
GeglMetadataIter | |
struct | GeglMetadataInterface |
GeglMetadata |
Objects which need to store or retrieve image metadata when saving and
loading image files should implement GeglMetadata. The object should be cast
with GEGL_METADATA()
and passed to the file load or save module via the
metadata
property. Image file modules should not implement the metadata
property if either the module or file format does not support metadata.
Gegl understands (but is not limited to) the following well-known metadata variables:
artist: Name of image creator.
comment: Miscellaneous comment; conversion from GIF comment.
copyright: Copyright notice.
description: Description of image (possibly long).
disclaimer: Legal disclaimer.
software: Software used to create the image.
source: Device used to create the image.
timestamp: Time of original image creation.
title: Short (one line) title or caption for image.
warning: Warning of nature of content.
The Gegl Metadata subsystem can be used in one of three ways described below in order of increasing complexity:
Recommended: Create a GeglMetadataHash and pass it to a file loader
or saver via its metadata
property. GeglMetadataHash is a subclass of
GeglMetadataStore which saves metadata in a hash table but which adds no
new properties or methods. Image file metadata to be retrieved or saved
is accessed via GeglMetadataStore properties or methods. Metadata values
not directly supported by Gegl may be declared using a GParamSpec.
Subclass GeglMetadataStore. This may be useful if an application stores metadata in internal structures which may be accessed via the subclass. The subclass is used identically to GeglMetadataHash. GeglMetadataStore aims to be sufficiently flexible to cover the majority of application requirements.
Implement the GeglMetadata interface. This option should only be used if GeglMetadataStore cannot adequately satisfy application requirements. Particular attention should be paid to semantics of the interface methods as the file modules interact directly with these.
For more complex requirements than provided by the metadata subsystem it is
probably better to use a library such as exiv2
or similar.
void gegl_metadata_register_map (GeglMetadata *metadata
,const gchar *file_module
,guint flags
,const GeglMetadataMap *map
,gsize n_map
);
Set the name of the file module and pass an array of mappings from file-format specific metadata names to those used by Gegl. A GValue transformation function may be supplied, e.g. to parse or format timestamps.
metadata |
The GeglMetadata interface |
|
file_module |
String identifying the file module, e.g, |
|
flags |
Flags specifying capabilities of underlying file format |
|
map |
Array of mappings from file module metadata names to Gegl well-known names. |
[array length=n_map] |
n_map |
Number of entries in |
void
gegl_metadata_unregister_map (GeglMetadata *metadata
);
Unregister the file module mappings and any further mappings added or modified by the application. This should be called after the file module completes operations.
gboolean gegl_metadata_set_resolution (GeglMetadata *metadata
,GeglResolutionUnit unit
,gfloat x
,gfloat y
);
Set resolution retrieved from image file's metadata. Intended for use by
the image file reader. If resolution is not supported by the application or
if the operation fails FALSE
is returned and the values are ignored.
metadata |
The GeglMetadata interface |
|
unit |
Specify GeglResolutionUnit |
|
x |
X resolution |
|
y |
Y resolution |
gboolean gegl_metadata_get_resolution (GeglMetadata *metadata
,GeglResolutionUnit *unit
,gfloat *x
,gfloat *y
);
Retrieve resolution from the application image metadata. Intended for use
by the image file writer. If resolution is not supported by the application
or if the operation fails FALSE
is returned and the resolution values are
not updated.
metadata |
The GeglMetadata interface |
|
unit |
GeglResolutionUnit return location |
|
x |
X resolution return location |
|
y |
Y resolution return location |
gboolean gegl_metadata_iter_lookup (GeglMetadata *metadata
,GeglMetadataIter *iter
,const gchar *key
);
Look up the specified key and initialise an iterator to reference the
associated metadata. The iterator is used in conjunction with
gegl_metadata_set_value()
and gegl_metadata_get_value()
. Note that this
iterator is not valid for gegl_metadata_iter_next()
.
metadata |
The GeglMetadata interface |
|
iter |
GeglMetadataIter to be initialised |
|
key |
Name of the value look up |
void gegl_metadata_iter_init (GeglMetadata *metadata
,GeglMetadataIter *iter
);
Initialise an iterator to find all supported metadata keys.
const gchar * gegl_metadata_iter_next (GeglMetadata *metadata
,GeglMetadataIter *iter
);
Move the iterator to the next metadata item
gboolean gegl_metadata_iter_set_value (GeglMetadata *metadata
,GeglMetadataIter *iter
,const GValue *value
);
Set application data retrieved from image file's metadata. Intended for use
by the image file reader. If the operation fails it returns FALSE
and
value
is ignored.
metadata |
The GeglMetadata interface |
|
iter |
GeglMetadataIter referencing the value to set |
|
value |
Value to set in the interface |
gboolean gegl_metadata_iter_get_value (GeglMetadata *metadata
,GeglMetadataIter *iter
,GValue *value
);
Retrieve image file metadata from the application. Intended for use by the
image file writer. If the operation fails it returns FALSE
and value
is
not updated.
metadata |
The GeglMetadata interface |
|
iter |
GeglMetadataIter referencing the value to get |
|
value |
Value to set in the interface |
An enumerated type specifying resolution (density) units. If resolution units are unknown, X and Y resolution specify the pixel aspect ratio.
typedef struct { const gchar *local_name; const gchar *name; GValueTransform transform; } GeglMetadataMap;
Struct to describe how a metadata variable is mapped from the name used by the image file module to the name used by Gegl. An optional transform function may be specified, e.g. to transform from a GDatetime to a string.
const gchar * |
Name of metadata variable used in the file module. |
|
const gchar * |
Standard metadata variable name used by Gegl. |
|
GValueTransform |
Optional GValue transform function. |
typedef struct { } GeglMetadataIter;
An opaque type representing a metadata iterator.
struct GeglMetadataInterface { gboolean (*set_resolution) (GeglMetadata *metadata, GeglResolutionUnit unit, gfloat x, gfloat y); gboolean (*get_resolution) (GeglMetadata *metadata, GeglResolutionUnit *unit, gfloat *x, gfloat *y); gboolean (*iter_lookup) (GeglMetadata *metadata, GeglMetadataIter *iter, const gchar *key); void (*iter_init) (GeglMetadata *metadata, GeglMetadataIter *iter); const gchar *(*iter_next) (GeglMetadata *metadata, GeglMetadataIter *iter); gboolean (*iter_set_value) (GeglMetadata *metadata, GeglMetadataIter *iter, const GValue *value); gboolean (*iter_get_value) (GeglMetadata *metadata, GeglMetadataIter *iter, GValue *value); };
The GeglMetadata interface structure.