gstvideometa: GStreamer Base Plugins 1.0 Library Reference Manual

## gstvideometa gstvideometa |

## Functions

gboolean | gst_video_meta_map ()
gboolean | gst_video_meta_unmap ()
const GstMetaInfo * | gst_video_meta_get_info ()
GstVideoMeta * | gst_buffer_add_video_meta ()
GstVideoMeta * | gst_buffer_add_video_meta_full ()
GstVideoMeta * | gst_buffer_get_video_meta ()
GstVideoMeta * | gst_buffer_get_video_meta_id ()
#define | gst_buffer_add_video_crop_meta()
#define | gst_buffer_get_video_crop_meta()
GstVideoRegionOfInterestMeta * | gst_buffer_add_video_region_of_interest_meta ()
GstVideoRegionOfInterestMeta * | gst_buffer_add_video_region_of_interest_meta_id ()
#define | gst_buffer_get_video_region_of_interest_meta()
GstVideoRegionOfInterestMeta * | gst_buffer_get_video_region_of_interest_meta_id ()
gboolean | (*GstVideoGLTextureUpload) ()
GstVideoGLTextureUploadMeta * | gst_buffer_add_video_gl_texture_upload_meta ()
#define | gst_buffer_get_video_gl_texture_upload_meta()
gboolean | gst_video_gl_texture_upload_meta_upload ()
GstVideoTimeCodeMeta * | gst_buffer_add_video_time_code_meta ()
GstVideoTimeCodeMeta * | gst_buffer_add_video_time_code_meta_full ()
#define | gst_buffer_get_video_time_code_meta()

## Types and Values

struct | GstVideoMeta
| GstVideoMetaTransform
struct | GstVideoCropMeta
| GstVideoRegionOfInterestMeta
#define | GST_BUFFER_POOL_OPTION_VIDEO_GL_TEXTURE_UPLOAD_META
struct | GstVideoGLTextureUploadMeta
| GstVideoTimeCodeMeta

## Includes

    #include <gst/video/gstvideometa.h>

## Description

## Functions

### gst_video_meta_map ()

    gboolean
    gst_video_meta_map (GstVideoMeta *meta,
                        guint plane,
                        GstMapInfo *info,
                        gpointer *data,
                        gint *stride,
                        GstMapFlags flags);

Map the video plane with index `plane` in `meta` and return a pointer to the first byte of the plane and the stride of the plane.

#### Parameters

meta | a GstVideoMeta |
plane | a plane |
info | a GstMapInfo |
data | the data of `plane` |
stride | the stride of `plane` |
flags | `GstMapFlags` |

#### Returns

TRUE if the map operation was successful.

### gst_video_meta_unmap ()

    gboolean
    gst_video_meta_unmap (GstVideoMeta *meta,
                          guint plane,
                          GstMapInfo *info);

Unmap a previously mapped plane with `gst_video_meta_map()`.

#### Parameters

meta | a GstVideoMeta |
plane | a plane |
info | a GstMapInfo |

#### Returns

TRUE if the memory was successfully unmapped.

### gst_video_meta_get_info ()

    const GstMetaInfo *
    gst_video_meta_get_info (void);

### gst_buffer_add_video_meta ()

    GstVideoMeta *
    gst_buffer_add_video_meta (GstBuffer *buffer,
                               GstVideoFrameFlags flags,
                               GstVideoFormat format,
                               guint width,
                               guint height);

Attaches GstVideoMeta metadata to `buffer` with the given parameters and the default offsets and strides for `format` and `width` x `height` .

This function calculates the default offsets and strides and then calls `gst_buffer_add_video_meta_full()` with them.

#### Parameters

buffer | a GstBuffer |
flags | GstVideoFrameFlags |
format | a GstVideoFormat |
width | the width |
height | the height |

#### Returns

the GstVideoMeta on `buffer` .

[transfer none]

### gst_buffer_add_video_meta_full ()

    GstVideoMeta *
    gst_buffer_add_video_meta_full (GstBuffer *buffer,
                                    GstVideoFrameFlags flags,
                                    GstVideoFormat format,
                                    guint width,
                                    guint height,
                                    guint n_planes,
                                    gsize offset[GST_VIDEO_MAX_PLANES],
                                    gint stride[GST_VIDEO_MAX_PLANES]);

Attaches GstVideoMeta metadata to `buffer` with the given parameters.

#### Parameters

buffer | a GstBuffer |
flags | GstVideoFrameFlags |
format | a GstVideoFormat |
width | the width |
height | the height |
n_planes | number of planes |
offset | offset of each plane |
stride | stride of each plane |

#### Returns

the GstVideoMeta on `buffer` .

[transfer none]

### gst_buffer_get_video_meta ()

    GstVideoMeta *
    gst_buffer_get_video_meta (GstBuffer *buffer);

Find the GstVideoMeta on `buffer` with the lowest `id` .

Buffers can contain multiple GstVideoMeta metadata items when dealing with multiview buffers.

#### Parameters

buffer | a GstBuffer |

#### Returns

the GstVideoMeta with lowest id (usually 0) or `NULL` when there is no such metadata on `buffer` .

[transfer none]

### gst_buffer_get_video_meta_id ()

    GstVideoMeta *
    gst_buffer_get_video_meta_id (GstBuffer *buffer,
                                  gint id);

Find the GstVideoMeta on `buffer` with the given `id` .

Buffers can contain multiple GstVideoMeta metadata items when dealing with multiview buffers.

#### Parameters

buffer | a GstBuffer |
id | a metadata id |

#### Returns

the GstVideoMeta with `id` or `NULL` when there is no such metadata on `buffer` .

[transfer none]

### gst_buffer_add_video_crop_meta()

    #define gst_buffer_add_video_crop_meta(b) ((GstVideoCropMeta*)gst_buffer_add_meta((b),GST_VIDEO_CROP_META_INFO, NULL))

### gst_buffer_get_video_crop_meta()

    #define gst_buffer_get_video_crop_meta(b) ((GstVideoCropMeta*)gst_buffer_get_meta((b),GST_VIDEO_CROP_META_API_TYPE))

### gst_buffer_add_video_region_of_interest_meta ()

    GstVideoRegionOfInterestMeta *
    gst_buffer_add_video_region_of_interest_meta
                                   (GstBuffer *buffer,
                                    const gchar *roi_type,
                                    guint x,
                                    guint y,
                                    guint w,
                                    guint h);

Attaches GstVideoRegionOfInterestMeta metadata to `buffer` with the given parameters.

#### Parameters

buffer | a GstBuffer |
roi_type | Type of the region of interest (e.g. "face") |
x | X position |
y | Y position |
w | width |
h | height |

#### Returns

the GstVideoRegionOfInterestMeta on `buffer` .

[transfer none]

### gst_buffer_add_video_region_of_interest_meta_id ()

    GstVideoRegionOfInterestMeta *
    gst_buffer_add_video_region_of_interest_meta_id
                                   (GstBuffer *buffer,
                                    GQuark roi_type,
                                    guint x,
                                    guint y,
                                    guint w,
                                    guint h);

Attaches GstVideoRegionOfInterestMeta metadata to `buffer` with the given parameters.

#### Parameters

buffer | a GstBuffer |
roi_type | Type of the region of interest (e.g. "face") |
x | X position |
y | Y position |
w | width |
h | height |

#### Returns

the GstVideoRegionOfInterestMeta on `buffer` .

[transfer none]

### gst_buffer_get_video_region_of_interest_meta()

    #define             gst_buffer_get_video_region_of_interest_meta(b)

### gst_buffer_get_video_region_of_interest_meta_id ()

    GstVideoRegionOfInterestMeta *
    gst_buffer_get_video_region_of_interest_meta_id
                                   (GstBuffer *buffer,
                                    gint id);

Find the GstVideoRegionOfInterestMeta on `buffer` with the given `id` .

Buffers can contain multiple GstVideoRegionOfInterestMeta metadata items if multiple regions of interests are marked on a frame.

#### Parameters

buffer | a GstBuffer |
id | a metadata id |

#### Returns

the GstVideoRegionOfInterestMeta with `id` or `NULL` when there is no such metadata on `buffer` .

[transfer none]

### GstVideoGLTextureUpload ()

    gboolean
    (*GstVideoGLTextureUpload) (GstVideoGLTextureUploadMeta *meta,
                                guint texture_id[4]);

### gst_buffer_add_video_gl_texture_upload_meta ()

    GstVideoGLTextureUploadMeta *
    gst_buffer_add_video_gl_texture_upload_meta
                                   (GstBuffer *buffer,
                                    GstVideoGLTextureOrientation texture_orientation,
                                    guint n_textures,
                                    GstVideoGLTextureType texture_type[4],
                                    GstVideoGLTextureUpload upload,
                                    gpointer user_data,
                                    GBoxedCopyFunc user_data_copy,
                                    GBoxedFreeFunc user_data_free);

Attaches GstVideoGLTextureUploadMeta metadata to `buffer` with the given parameters.

#### Parameters

buffer | a GstBuffer |
texture_orientation | the GstVideoGLTextureOrientation |
n_textures | the number of textures |
texture_type | array of GstVideoGLTextureType |
upload | the function to upload the buffer to a specific texture ID. | [scope call]
user_data | user data for the implementor of `upload` |
user_data_copy | function to copy `user_data` . | [scope call]
user_data_free | function to free `user_data` . | [scope call]

#### Returns

the GstVideoGLTextureUploadMeta on `buffer` .

[transfer none]

### gst_buffer_get_video_gl_texture_upload_meta()

    #define gst_buffer_get_video_gl_texture_upload_meta(b) ((GstVideoGLTextureUploadMeta*)gst_buffer_get_meta((b),GST_VIDEO_GL_TEXTURE_UPLOAD_META_API_TYPE))

### gst_video_gl_texture_upload_meta_upload ()

    gboolean
    gst_video_gl_texture_upload_meta_upload
                                   (GstVideoGLTextureUploadMeta *meta,
                                    guint texture_id[4]);

Uploads the buffer which owns the meta to a specific texture ID.

#### Parameters

meta | a GstVideoGLTextureUploadMeta |
texture_id | the texture IDs to upload to |

#### Returns

`TRUE` if uploading succeeded, `FALSE` otherwise.

### gst_buffer_add_video_time_code_meta ()

    GstVideoTimeCodeMeta *
    gst_buffer_add_video_time_code_meta (GstBuffer *buffer,
                                         GstVideoTimeCode *tc);

Attaches GstVideoTimeCodeMeta metadata to `buffer` with the given parameters.

#### Parameters

buffer | a GstBuffer |
tc | a GstVideoTimeCode |

#### Returns

the GstVideoTimeCodeMeta on `buffer` .

[transfer none]

Since: 1.10

### gst_buffer_add_video_time_code_meta_full ()

    GstVideoTimeCodeMeta *
    gst_buffer_add_video_time_code_meta_full
                                   (GstBuffer *buffer,
                                    guint fps_n,
                                    guint fps_d,
                                    GDateTime *latest_daily_jam,
                                    GstVideoTimeCodeFlags flags,
                                    guint hours,
                                    guint minutes,
                                    guint seconds,
                                    guint frames,
                                    guint field_count);

Attaches GstVideoTimeCodeMeta metadata to `buffer` with the given parameters.

#### Parameters

buffer | a GstBuffer |
fps_n | framerate numerator |
fps_d | framerate denominator |
latest_daily_jam | a GDateTime for the latest daily jam |
flags | a GstVideoTimeCodeFlags |
hours | hours since the daily jam |
minutes | minutes since the daily jam |
seconds | seconds since the daily jam |
frames | frames since the daily jam |
field_count | fields since the daily jam |

#### Returns

the GstVideoTimeCodeMeta on `buffer` .

[transfer none]

Since: 1.10

### gst_buffer_get_video_time_code_meta()

    #define             gst_buffer_get_video_time_code_meta(b)

## Types and Values

### struct GstVideoMeta

    struct GstVideoMeta {
      GstMeta            meta;

      GstBuffer         *buffer;

      GstVideoFrameFlags flags;
      GstVideoFormat     format;
      gint               id;
      guint              width;
      guint              height;

      guint              n_planes;
      gsize              offset[GST_VIDEO_MAX_PLANES];
      gint               stride[GST_VIDEO_MAX_PLANES];

      gboolean (*map)    (GstVideoMeta *meta, guint plane, GstMapInfo *info,
                          gpointer *data, gint * stride, GstMapFlags flags);
      gboolean (*unmap)  (GstVideoMeta *meta, guint plane, GstMapInfo *info);
    };

Extra buffer metadata describing image properties

#### Members

GstMeta `meta`; | parent GstMeta |
GstBuffer *`buffer`; | the buffer this metadata belongs to |
GstVideoFrameFlags `flags`; | additional video flags |
GstVideoFormat `format`; | the video format |
gint `id`; | identifier of the frame |
guint `width`; | the video width |
guint `height`; | the video height |
guint `n_planes`; | the number of planes in the image |
gsize `offset`[GST_VIDEO_MAX_PLANES]; | array of offsets for the planes. This field might not always be valid, it is used by the default implementation of `map` . |
gint `stride`[GST_VIDEO_MAX_PLANES]; | array of strides for the planes. This field might not always be valid, it is used by the default implementation of `map` . |
`map` () | map the memory of a plane |
`unmap` () | unmap the memory of a plane |

### GstVideoMetaTransform

    typedef struct {
      GstVideoInfo *in_info;
      GstVideoInfo *out_info;
    } GstVideoMetaTransform;

Extra data passed to a video transform GstMetaTransformFunction such as: "gst-video-scale".

#### Members

GstVideoInfo *`in_info`; | the input GstVideoInfo |
GstVideoInfo *`out_info`; | the output GstVideoInfo |

### struct GstVideoCropMeta

    struct GstVideoCropMeta {
      GstMeta       meta;

      guint         x;
      guint         y;
      guint         width;
      guint         height;
    };

Extra buffer metadata describing image cropping.

#### Members

GstMeta `meta`; | parent GstMeta |
guint `x`; | the horizontal offset |
guint `y`; | the vertical offset |
guint `width`; | the cropped width |
guint `height`; | the cropped height |

### GstVideoRegionOfInterestMeta

    typedef struct {
      GstMeta meta;

      GQuark roi_type;
      gint id;
      gint parent_id;

      guint x;
      guint y;
      guint w;
      guint h;
    } GstVideoRegionOfInterestMeta;

Extra buffer metadata describing an image region of interest

#### Members

GstMeta `meta`; | parent GstMeta |
GQuark `roi_type`; | GQuark describing the semantic of the Roi (f.i. a face, a pedestrian) |
gint `id`; | identifier of this particular ROI |
gint `parent_id`; | identifier of its parent ROI, used f.i. for ROI hierarchisation. |
guint `x`; | x component of upper-left corner |
guint `y`; | y component of upper-left corner |
guint `w`; | bounding box width |
guint `h`; | bounding box height |

### GST_BUFFER_POOL_OPTION_VIDEO_GL_TEXTURE_UPLOAD_META

    #define GST_BUFFER_POOL_OPTION_VIDEO_GL_TEXTURE_UPLOAD_META "GstBufferPoolOptionVideoGLTextureUploadMeta"

An option that can be activated on a bufferpool to request gl texture upload meta on buffers from the pool.

When this option is enabled on the bufferpool, `GST_BUFFER_POOL_OPTION_VIDEO_META` should also be enabled.

Since: 1.2.2

### struct GstVideoGLTextureUploadMeta

    struct GstVideoGLTextureUploadMeta {
      GstMeta       meta;

      GstVideoGLTextureOrientation texture_orientation;
      guint n_textures;
      GstVideoGLTextureType texture_type[4];
    };

Extra buffer metadata for uploading a buffer to an OpenGL texture ID. The caller of `gst_video_gl_texture_upload_meta_upload()` must have OpenGL set up and call this from a thread where it is valid to upload something to an OpenGL texture.

#### Members

GstMeta `meta`; | parent GstMeta |
GstVideoGLTextureOrientation `texture_orientation`; | Orientation of the textures |
guint `n_textures`; | Number of textures that are generated |
GstVideoGLTextureType `texture_type`[4]; | Type of each texture |

### GstVideoTimeCodeMeta

    typedef struct {
      GstMeta meta;

      GstVideoTimeCode tc;
    } GstVideoTimeCodeMeta;

Extra buffer metadata describing the GstVideoTimeCode of the frame.

Each frame is assumed to have its own timecode, i.e. they are not automatically incremented/interpolated.

#### Members

GstMeta `meta`; | parent GstMeta |
GstVideoTimeCode `tc`; | the GstVideoTimeCode to attach |

Since: 1.10