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]