## GstMeta

GstMeta — Buffer metadata

## Functions

#define | GST_META_FLAGS()
#define | GST_META_FLAG_IS_SET()
#define | GST_META_FLAG_SET()
#define | GST_META_FLAG_UNSET()
gboolean | (*GstMetaInitFunction) ()
void | (*GstMetaFreeFunction) ()
gboolean | (*GstMetaTransformFunction) ()
#define | GST_META_TRANSFORM_IS_COPY()
GType | gst_meta_api_type_register ()
gboolean | gst_meta_api_type_has_tag ()
const gchar * const* | gst_meta_api_type_get_tags ()
const GstMetaInfo * | gst_meta_register ()
const GstMetaInfo * | gst_meta_get_info ()
guint64 | gst_meta_get_seqnum ()
gint | gst_meta_compare_seqnum ()

## Types and Values

struct | GstMeta
enum | GstMetaFlags
struct | GstMetaInfo
| GstMetaTransformCopy
#define | GST_META_TAG_MEMORY
#define | GST_META_TAG_MEMORY_STR

## Includes

    #include <gst/gst.h>

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

## Functions

### GST_META_FLAGS()

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

A flags word containing GstMetaFlags flags set on `meta`

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

### GstMetaInitFunction ()

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

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

#### Parameters

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

#### Parameters

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

#### Parameters

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

### 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

#### Parameters

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

#### Parameters

api | an API to register |
tags | tags for `api` . | [array zero-terminated=1]

#### 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` .

#### Parameters

api | an API |
tag | the tag to check |

#### Returns

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

### gst_meta_api_type_get_tags ()

    const gchar * const*
    gst_meta_api_type_get_tags (GType api);

#### Parameters

api | an API |

#### Returns

an array of tags as strings.

[transfer none][array zero-terminated=1][element-type utf8]

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.

#### Parameters

api | the type of the GstMeta API |
impl | the name of the GstMeta implementation |
size | the size of the GstMeta structure |
init_func | a GstMetaInitFunction. | [scope async]
free_func | a GstMetaFreeFunction. | [scope async]
transform_func | a GstMetaTransformFunction. | [scope async]

#### Returns

a GstMetaInfo that can be used to access metadata.

[transfer none][nullable]

### 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` .

#### Parameters

impl | the name |

#### Returns

a GstMetaInfo with `impl` , or `NULL` when no such metainfo exists.

[transfer none][nullable]

### gst_meta_get_seqnum ()

    guint64
    gst_meta_get_seqnum (const GstMeta *meta);

Gets seqnum for this meta.

#### Parameters

meta | a GstMeta |

Since: 1.16

### gst_meta_compare_seqnum ()

    gint
    gst_meta_compare_seqnum (const GstMeta *meta1,
                             const GstMeta *meta2);

Meta sequence number compare function. Can be used as GCompareFunc or a GCompareDataFunc.

#### Parameters

meta1 | a GstMeta |
meta2 | a GstMeta |

#### Returns

a negative number if `meta1` comes before `meta2` , 0 if both metas have an equal sequence number, or a positive integer if `meta1` comes after `meta2` .

Since: 1.16

## Types and Values

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

#### Members

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

### enum GstMetaFlags

Extra metadata flags.

#### Members

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

### struct GstMetaInfo

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

      GstMetaInitFunction        init_func;
      GstMetaFreeFunction        free_func;
      GstMetaTransformFunction   transform_func;

      /* No padding needed, GstMetaInfo is always allocated by GStreamer and is
       * not subclassable or stack-allocatable, so we can extend it as we please
       * just like interfaces */
    };

The GstMetaInfo provides information about a specific metadata structure.

#### Members

GType `api`; | tag identifying the metadata structure and api |
GType `type`; | type identifying 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 |

### GstMetaTransformCopy

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

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

#### Members

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_TAG_MEMORY

    #define GST_META_TAG_MEMORY (_gst_meta_tag_memory)

`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"

This metadata stays relevant as long as memory layout is unchanged.

Since: 1.2