## gstvideometa gstvideometa |

## Synopsis

    #include <gst/video/gstvideometa.h>

    struct              GstVideoMeta;
                        GstVideoMetaTransform;
    gboolean            gst_video_meta_map                  (GstVideoMeta *meta,
                                                             guint plane,
                                                             GstMapInfo *info,
                                                             gpointer *data,
                                                             gint *stride,
                                                             GstMapFlags flags);
    gboolean            gst_video_meta_unmap                (GstVideoMeta *meta,
                                                             guint plane,
                                                             GstMapInfo *info);
    const GstMetaInfo * gst_video_meta_get_info             (void);
    GstVideoMeta *      gst_buffer_add_video_meta           (GstBuffer *buffer,
                                                             GstVideoFrameFlags flags,
                                                             GstVideoFormat format,
                                                             guint width,
                                                             guint height);
    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]);
    #define             gst_buffer_get_video_meta           (b)
    GstVideoMeta *      gst_buffer_get_video_meta_id        (GstBuffer *buffer,
                                                             gint id);
    struct              GstVideoCropMeta;
    #define             gst_buffer_add_video_crop_meta      (b)
    #define             gst_buffer_get_video_crop_meta      (b)
                        GstVideoRegionOfInterestMeta;
    GstVideoRegionOfInterestMeta * gst_buffer_add_video_region_of_interest_meta
                                                            (GstBuffer *buffer,
                                                             const gchar *roi_type,
                                                             guint x,
                                                             guint y,
                                                             guint w,
                                                             guint h);
    GstVideoRegionOfInterestMeta * gst_buffer_add_video_region_of_interest_meta_id
                                                            (GstBuffer *buffer,
                                                             GQuark roi_type,
                                                             guint x,
                                                             guint y,
                                                             guint w,
                                                             guint h);
    #define             gst_buffer_get_video_region_of_interest_meta(b)
    GstVideoRegionOfInterestMeta * gst_buffer_get_video_region_of_interest_meta_id
                                                            (GstBuffer *buffer,
                                                             gint id);
    gboolean            (*GstVideoGLTextureUpload)          (GstVideoGLTextureUploadMeta *meta,
                                                             guint texture_id[4]);
    struct              GstVideoGLTextureUploadMeta;
    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);
    #define             gst_buffer_get_video_gl_texture_upload_meta(b)
    gboolean            gst_video_gl_texture_upload_meta_upload
                                                            (GstVideoGLTextureUploadMeta *meta,
                                                             guint texture_id[4]);

## Description

## Details

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

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

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

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

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

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

`buffer` : | a GstBuffer
`flags` : | GstVideoFrameFlags
`format` : | a GstVideoFormat
`width` : | the width
`height` : | the height
Returns : | the GstVideoMeta on `buffer`.

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

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

### gst_buffer_get_video_meta()

    #define gst_buffer_get_video_meta(b) ((GstVideoMeta*)gst_buffer_get_meta((b),GST_VIDEO_META_API_TYPE))

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

`buffer` : | a GstBuffer
`id` : | a metadata id
Returns : | the GstVideoMeta with `id` or `NULL` when there is no such metadata on `buffer`.

### struct GstVideoCropMeta

    struct GstVideoCropMeta {
      GstMeta       meta;

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

Extra buffer metadata describing image cropping.

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

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

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

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`; |
guint `h`; |

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

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

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

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

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

`buffer` : | a GstBuffer
`id` : | a metadata id
Returns : | the GstVideoeRegionOfInterestMeta with `id` or `NULL` when there is no such metadata on `buffer`.

### GstVideoGLTextureUpload ()

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

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

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

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

`buffer` : | a GstBuffer
`upload` : | the function to upload the buffer to a specific texture ID
`user_data` : | user data for the implementor of `upload`
`user_data_copy` : | function to copy `user_data`
`user_data_free` : | function to free `user_data`
Returns : | the GstVideoGLTextureUploadMeta on `buffer`.

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

`meta` : | a GstVideoGLTextureUploadMeta
`texture_id` : | the texture IDs to upload to
Returns : | `TRUE` if uploading succeeded, `FALSE` otherwise.