GstMeta

GstMeta — Buffer metadata

Functions

Types and Values

Object Hierarchy


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

 

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_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_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]


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]

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;
};

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_STR

#define GST_META_TAG_MEMORY_STR "memory"

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

Since 1.2