GeglMetadata

GeglMetadata — A metadata interface for use with file modules.

Functions

Types and Values

Description

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:

  1. 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.

  2. 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.

  3. 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.

Functions

gegl_metadata_register_map ()

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.

Parameters

metadata

The GeglMetadata interface

 

file_module

String identifying the file module, e.g, "gegl:png-save"

 

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 map

 

gegl_metadata_unregister_map ()

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.

Parameters

metadata

The GeglMetadata interface

 

gegl_metadata_set_resolution ()

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.

Parameters

metadata

The GeglMetadata interface

 

unit

Specify GeglResolutionUnit

 

x

X resolution

 

y

Y resolution

 

Returns

TRUE if successful.


gegl_metadata_get_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.

Parameters

metadata

The GeglMetadata interface

 

unit

GeglResolutionUnit return location

 

x

X resolution return location

 

y

Y resolution return location

 

Returns

TRUE if successful.


gegl_metadata_iter_lookup ()

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().

Parameters

metadata

The GeglMetadata interface

 

iter

GeglMetadataIter to be initialised

 

key

Name of the value look up

 

Returns

TRUE if key is found.


gegl_metadata_iter_init ()

void
gegl_metadata_iter_init (GeglMetadata *metadata,
                         GeglMetadataIter *iter);

Initialise an iterator to find all supported metadata keys.

Parameters

metadata

The GeglMetadata interface

 

iter

GeglMetadataIter to be initialised

 

gegl_metadata_iter_next ()

const gchar *
gegl_metadata_iter_next (GeglMetadata *metadata,
                         GeglMetadataIter *iter);

Move the iterator to the next metadata item

Parameters

metadata

The GeglMetadata interface

 

iter

GeglMetadataIter to be updated

 

Returns

key name if found, else NULL


gegl_metadata_iter_set_value ()

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.

Parameters

metadata

The GeglMetadata interface

 

iter

GeglMetadataIter referencing the value to set

 

value

Value to set in the interface

 

Returns

TRUE if successful.


gegl_metadata_iter_get_value ()

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.

Parameters

metadata

The GeglMetadata interface

 

iter

GeglMetadataIter referencing the value to get

 

value

Value to set in the interface

 

Returns

TRUE if successful.

Types and Values

enum GeglResolutionUnit

An enumerated type specifying resolution (density) units. If resolution units are unknown, X and Y resolution specify the pixel aspect ratio.

Members

GEGL_RESOLUTION_UNIT_NONE

Unknown or resolution not applicable.

 

GEGL_RESOLUTION_UNIT_DPI

Dots or pixels per inch.

 

GEGL_RESOLUTION_UNIT_DPM

Dots or pixels per metre.

 

enum GeglMapFlags

Flags controlling the mapping strategy.

Members

GEGL_MAP_EXCLUDE_UNMAPPED

Prevent further mapping from being registered.

 

GEGL_TYPE_METADATA

#define GEGL_TYPE_METADATA          (gegl_metadata_get_type ())

GeglMetadataMap

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.

Members

const gchar *local_name;

Name of metadata variable used in the file module.

 

const gchar *name;

Standard metadata variable name used by Gegl.

 

GValueTransform transform;

Optional GValue transform function.

 

GeglMetadataIter

typedef struct {
} GeglMetadataIter;

An opaque type representing a metadata iterator.


struct GeglMetadataInterface

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.

Members

set_resolution ()

See gegl_metadata_set_resolution().

 

get_resolution ()

See gegl_metadata_get_resolution().

 

iter_lookup ()

See gegl_metadata_iter_lookup().

 

iter_init ()

See gegl_metadata_iter_init().

 

iter_next ()

See gegl_metadata_iter_next().

 

iter_set_value ()

See gegl_metadata_iter_set_value().

 

iter_get_value ()

See gegl_metadata_iter_get_value().

 

GeglMetadata

typedef struct _GeglMetadata GeglMetadata;

See Also

GeglMetadataStore GeglMetadataHash