GstMeta

## GstMeta GstMeta — Buffer metadata |

## Synopsis

    #include <gst/gst.h>

    struct              GstMeta;
    enum                GstMetaFlags;
    #define             GST_META_FLAGS                      (meta)
    #define             GST_META_FLAG_IS_SET                (meta,
                                                             flag)
    #define             GST_META_FLAG_SET                   (meta,
                                                             flag)
    #define             GST_META_FLAG_UNSET                 (meta,
                                                             flag)
    struct              GstMetaInfo;
    gboolean            (*GstMetaInitFunction)              (GstMeta *meta,
                                                             gpointer params,
                                                             GstBuffer *buffer);
    void                (*GstMetaFreeFunction)              (GstMeta *meta,
                                                             GstBuffer *buffer);
    gboolean            (*GstMetaTransformFunction)         (GstBuffer *transbuf,
                                                             GstMeta *meta,
                                                             GstBuffer *buffer,
                                                             GQuark type,
                                                             gpointer data);
                        GstMetaTransformCopy;
    #define             GST_META_TRANSFORM_IS_COPY          (type)
    GType               gst_meta_api_type_register          (const gchar *api,
                                                             const gchar **tags);
    gboolean            gst_meta_api_type_has_tag           (GType api,
                                                             GQuark tag);
    #define             GST_META_TAG_MEMORY
    #define             GST_META_TAG_MEMORY_STR
    const GstMetaInfo * gst_meta_register                   (GType api,
                                                             const gchar *impl,
                                                             gsize size,
                                                             GstMetaInitFunction init_func,
                                                             GstMetaFreeFunction free_func,
                                                             GstMetaTransformFunction transform_func);
    const GstMetaInfo * gst_meta_get_info                   (const gchar *impl);

## Description

The GstMeta structure should be included as the first member of a GstBuffer metadata structure. The structure defines the API of the metadata and should be accessible to all elements using the metadata.

A metadata API is registered with `gst_meta_api_type_register()` which takes a name for the metadata API and some tags associated with the metadata. With `gst_meta_api_type_has_tag()` one can check if a certain metadata API contains a given tag.

Multiple implementations of a metadata API can be registered. To implement a metadata API, `gst_meta_register()` should be used. This function takes all parameters needed to create, free and transform metadata along with the size of the metadata. The function returns a GstMetaInfo structure that contains the information for the implementation of the API.

A specific implementation can be retrieved by name with `gst_meta_get_info()`.

See GstBuffer for how the metadata can be added, retrieved and removed from buffers.

Last reviewed on 2012-03-28 (0.11.3)

## Details

### struct GstMeta

    struct GstMeta {
      GstMetaFlags       flags;
      const GstMetaInfo *info;
    };

Base structure for metadata. Custom metadata will put this structure as the first member of their structure.

GstMetaFlags `flags`; | extra flags for the metadata
const GstMetaInfo *`info`; | pointer to the GstMetaInfo

### enum GstMetaFlags

    typedef enum {
      GST_META_FLAG_NONE        = 0,
      GST_META_FLAG_READONLY    = (1 << 0),
      GST_META_FLAG_POOLED      = (1 << 1),
      GST_META_FLAG_LOCKED      = (1 << 2),

      GST_META_FLAG_LAST        = (1 << 16)
    } GstMetaFlags;

Extra metadata flags.

`GST_META_FLAG_NONE` | no flags
`GST_META_FLAG_READONLY` | metadata should not be modified
`GST_META_FLAG_POOLED` | metadata is managed by a bufferpool
`GST_META_FLAG_LOCKED` | metadata should not be removed
`GST_META_FLAG_LAST` | additional flags can be added starting from this flag.

### GST_META_FLAGS()

    #define GST_META_FLAGS(meta)  (GST_META_CAST (meta)->flags)

A flags word containing GstMetaFlags flags set on `meta`

`meta` : | a GstMeta.

### GST_META_FLAG_IS_SET()

    #define GST_META_FLAG_IS_SET(meta,flag)        !!(GST_META_FLAGS (meta) & (flag))

Gives the status of a specific flag on a metadata.

`meta` : | a GstMeta.
`flag` : | the GstMetaFlags to check.

### GST_META_FLAG_SET()

    #define GST_META_FLAG_SET(meta,flag)           (GST_META_FLAGS (meta) |= (flag))

Sets a metadata flag on a metadata.

`meta` : | a GstMeta.
`flag` : | the GstMetaFlags to set.

### GST_META_FLAG_UNSET()

    #define GST_META_FLAG_UNSET(meta,flag)         (GST_META_FLAGS (meta) &= ~(flag))

Clears a metadata flag.

`meta` : | a GstMeta.
`flag` : | the GstMetaFlags to clear.

### struct GstMetaInfo

    struct GstMetaInfo {
      GType                      api;
      GType                      type;
      gsize                      size;

      GstMetaInitFunction        init_func;
      GstMetaFreeFunction        free_func;
      GstMetaTransformFunction   transform_func;
    };

The GstMetaInfo provides information about a specific metadata structure.

GType `api`; | tag indentifying the metadata structure and api
GType `type`; | type indentifying the implementor of the api
gsize `size`; | size of the metadata
GstMetaInitFunction `init_func`; | function for initializing the metadata
GstMetaFreeFunction `free_func`; | function for freeing the metadata
GstMetaTransformFunction `transform_func`; | function for transforming the metadata

### GstMetaInitFunction ()

    gboolean            (*GstMetaInitFunction)              (GstMeta *meta,
                                                             gpointer params,
                                                             GstBuffer *buffer);

Function called when `meta` is initialized in `buffer`.

`meta` : | a GstMeta
`params` : | parameters passed to the init function
`buffer` : | a GstBuffer

### GstMetaFreeFunction ()

    void                (*GstMetaFreeFunction)              (GstMeta *meta,
                                                             GstBuffer *buffer);

Function called when `meta` is freed in `buffer`.

`meta` : | a GstMeta
`buffer` : | a GstBuffer

### GstMetaTransformFunction ()

    gboolean            (*GstMetaTransformFunction)         (GstBuffer *transbuf,
                                                             GstMeta *meta,
                                                             GstBuffer *buffer,
                                                             GQuark type,
                                                             gpointer data);

Function called for each `meta` in `buffer` as a result of performing a transformation on `transbuf`. Additional `type` specific transform data is passed to the function as `data`.

Implementations should check the `type` of the transform and parse additional type specific fields in `data` that should be used to update the metadata on `transbuf`.

`transbuf` : | a GstBuffer
`meta` : | a GstMeta
`buffer` : | a GstBuffer
`type` : | the transform type
`data` : | transform specific data.
Returns : | `TRUE` if the transform could be performed

### GstMetaTransformCopy

    typedef struct {
      gboolean region;
      gsize offset;
      gsize size;
    } GstMetaTransformCopy;

Extra data passed to a "gst-copy" transform GstMetaTransformFunction.

gboolean `region`; | `TRUE` if only region is copied
gsize `offset`; | the offset to copy, 0 if `region` is `FALSE`, otherwise > 0
gsize `size`; | the size to copy, -1 or the buffer size when `region` is `FALSE`

### GST_META_TRANSFORM_IS_COPY()

    #define GST_META_TRANSFORM_IS_COPY(type) ((type) == _gst_meta_transform_copy)

Check if the transform type is a copy transform

`type` : | a transform type

### gst_meta_api_type_register ()

    GType               gst_meta_api_type_register          (const gchar *api,
                                                             const gchar **tags);

Register and return a GType for the `api` and associate it with `tags`.

`api` : | an API to register
`tags` : | tags for `api`
Returns : | a unique GType for `api`.

### gst_meta_api_type_has_tag ()

    gboolean            gst_meta_api_type_has_tag           (GType api,
                                                             GQuark tag);

Check if `api` was registered with `tag`.

`api` : | an API
`tag` : | the tag to check
Returns : | `TRUE` if `api` was registered with `tag`.

### GST_META_TAG_MEMORY

    #define GST_META_TAG_MEMORY (_gst_meta_tag_memory)

### Warning

`GST_META_TAG_MEMORY` is deprecated and should not be used in newly-written code. The GQuarks are not exported by any public API, use GST_META_TAG_MEMORY_STR instead.

Metadata tagged with this tag depends on the particular memory or buffer that it is on.

### GST_META_TAG_MEMORY_STR

    #define GST_META_TAG_MEMORY_STR "memory"

Since 1.2

### gst_meta_register ()

    const GstMetaInfo * gst_meta_register                   (GType api,
                                                             const gchar *impl,
                                                             gsize size,
                                                             GstMetaInitFunction init_func,
                                                             GstMetaFreeFunction free_func,
                                                             GstMetaTransformFunction transform_func);

Register a new GstMeta implementation.

The same `info` can be retrieved later with `gst_meta_get_info()` by using `impl` as the key.

`api` : | the type of the GstMeta API
`impl` : | the name of the GstMeta implementation
`size` : | the size of the GstMeta structure
`init_func` : | (scope async) a GstMetaInitFunction
`free_func` : | (scope async) a GstMetaFreeFunction
`transform_func` : | (scope async) a GstMetaTransformFunction
Returns : | a GstMetaInfo that can be used to access metadata. [transfer none]

### gst_meta_get_info ()

    const GstMetaInfo * gst_meta_get_info                   (const gchar *impl);

Lookup a previously registered meta info structure by its implementation name `impl`.

`impl` : | the name
Returns : | a GstMetaInfo with `impl`, or NULL when no such metainfo exists. [transfer none]