subprojects/gst-plugins-base/gst-libs/gst/video/gstvideometa.h

   1 /* GStreamer
   2  * Copyright (C) <2011> Wim Taymans <wim.taymans@gmail.com>
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Library General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2 of the License, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Library General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Library General Public
  15  * License along with this library; if not, write to the
  16  * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
  17  * Boston, MA 02110-1301, USA.
  18  */
  19
  20 #ifndef __GST_VIDEO_META_H__
  21 #define __GST_VIDEO_META_H__
  22
  23 #include <gst/gst.h>
  24
  25 #include <gst/video/video.h>
  26 #include <gst/video/gstvideotimecode.h>
  27
  28 G_BEGIN_DECLS
  29
  30 #define GST_VIDEO_META_API_TYPE (gst_video_meta_api_get_type())
  31 #define GST_VIDEO_META_INFO  (gst_video_meta_get_info())
  32 typedef struct _GstVideoMeta GstVideoMeta;
  33
  34 #define GST_CAPS_FEATURE_META_GST_VIDEO_META "meta:GstVideoMeta"
  35
  36 #define GST_VIDEO_CROP_META_API_TYPE  (gst_video_crop_meta_api_get_type())
  37 #define GST_VIDEO_CROP_META_INFO  (gst_video_crop_meta_get_info())
  38 typedef struct _GstVideoCropMeta GstVideoCropMeta;
  39
  40 /**
  41  * GstVideoMeta:
  42  * @meta: parent #GstMeta
  43  * @buffer: the buffer this metadata belongs to
  44  * @flags: additional video flags
  45  * @format: the video format
  46  * @id: identifier of the frame
  47  * @width: the video width
  48  * @height: the video height
  49  * @n_planes: the number of planes in the image
  50  * @offset: array of offsets for the planes. This field might not always be
  51  *          valid, it is used by the default implementation of @map.
  52  * @stride: array of strides for the planes. This field might not always be
  53  *          valid, it is used by the default implementation of @map.
  54  * @map: map the memory of a plane
  55  * @unmap: unmap the memory of a plane
  56  * @alignment: the paddings and alignment constraints of the video buffer.
  57  * It is up to the caller of `gst_buffer_add_video_meta_full()` to set it
  58  * using gst_video_meta_set_alignment(), if they did not it defaults
  59  * to no padding and no alignment. Since: 1.18
  60  *
  61  * Extra buffer metadata describing image properties
  62  *
  63  * This meta can also be used by downstream elements to specifiy their
  64  * buffer layout requirements for upstream. Upstream should try to
  65  * fit those requirements, if possible, in order to prevent buffer copies.
  66  *
  67  * This is done by passing a custom #GstStructure to
  68  * gst_query_add_allocation_meta() when handling the ALLOCATION query.
  69  * This structure should be named 'video-meta' and can have the following
  70  * fields:
  71  * - padding-top (uint): extra pixels on the top
  72  * - padding-bottom (uint): extra pixels on the bottom
  73  * - padding-left (uint): extra pixels on the left side
  74  * - padding-right (uint): extra pixels on the right side
  75  * The padding fields have the same semantic as #GstVideoMeta.alignment
  76  * and so represent the paddings requested on produced video buffers.
  77  */
  78 struct _GstVideoMeta {
  79   GstMeta            meta;
  80
  81   GstBuffer         *buffer;
  82
  83   GstVideoFrameFlags flags;
  84   GstVideoFormat     format;
  85   gint               id;
  86   guint              width;
  87   guint              height;
  88
  89   guint              n_planes;
  90   gsize              offset[GST_VIDEO_MAX_PLANES];
  91   gint               stride[GST_VIDEO_MAX_PLANES];
  92
  93   gboolean (*map)    (GstVideoMeta *meta, guint plane, GstMapInfo *info,
  94                       gpointer *data, gint * stride, GstMapFlags flags);
  95   gboolean (*unmap)  (GstVideoMeta *meta, guint plane, GstMapInfo *info);
  96
  97   GstVideoAlignment  alignment;
  98 };
  99
 100 GST_VIDEO_API
 101 GType gst_video_meta_api_get_type (void);
 102
 103 GST_VIDEO_API
 104 const GstMetaInfo * gst_video_meta_get_info (void);
 105
 106 GST_VIDEO_API
 107 GstVideoMeta * gst_buffer_get_video_meta (GstBuffer *buffer);
 108
 109 GST_VIDEO_API
 110 GstVideoMeta * gst_buffer_get_video_meta_id    (GstBuffer *buffer, gint id);
 111
 112 GST_VIDEO_API
 113 GstVideoMeta * gst_buffer_add_video_meta       (GstBuffer *buffer, GstVideoFrameFlags flags,
 114                                                 GstVideoFormat format, guint width, guint height);
 115
 116 GST_VIDEO_API
 117 GstVideoMeta * gst_buffer_add_video_meta_full  (GstBuffer *buffer, GstVideoFrameFlags flags,
 118                                                 GstVideoFormat format, guint width, guint height,
 119                                                 guint n_planes, gsize offset[GST_VIDEO_MAX_PLANES],
 120                                                 gint stride[GST_VIDEO_MAX_PLANES]);
 121
 122 GST_VIDEO_API
 123 gboolean       gst_video_meta_map        (GstVideoMeta *meta, guint plane, GstMapInfo *info,
 124                                           gpointer *data, gint *stride, GstMapFlags flags);
 125
 126 GST_VIDEO_API
 127 gboolean       gst_video_meta_unmap      (GstVideoMeta *meta, guint plane, GstMapInfo *info);
 128
 129 GST_VIDEO_API
 130 gboolean       gst_video_meta_set_alignment (GstVideoMeta * meta, GstVideoAlignment alignment);
 131
 132 GST_VIDEO_API
 133 gboolean       gst_video_meta_get_plane_size (GstVideoMeta * meta, gsize plane_size[GST_VIDEO_MAX_PLANES]);
 134
 135 GST_VIDEO_API
 136 gboolean       gst_video_meta_get_plane_height (GstVideoMeta * meta, guint plane_height[GST_VIDEO_MAX_PLANES]);
 137
 138 /**
 139  * GstVideoCropMeta:
 140  * @meta: parent #GstMeta
 141  * @x: the horizontal offset
 142  * @y: the vertical offset
 143  * @width: the cropped width
 144  * @height: the cropped height
 145  *
 146  * Extra buffer metadata describing image cropping.
 147  */
 148 struct _GstVideoCropMeta {
 149   GstMeta       meta;
 150
 151   guint         x;
 152   guint         y;
 153   guint         width;
 154   guint         height;
 155 };
 156
 157 GST_VIDEO_API
 158 GType gst_video_crop_meta_api_get_type (void);
 159
 160 GST_VIDEO_API
 161 const GstMetaInfo * gst_video_crop_meta_get_info (void);
 162
 163 #define gst_buffer_get_video_crop_meta(b) ((GstVideoCropMeta*)gst_buffer_get_meta((b),GST_VIDEO_CROP_META_API_TYPE))
 164 #define gst_buffer_add_video_crop_meta(b) ((GstVideoCropMeta*)gst_buffer_add_meta((b),GST_VIDEO_CROP_META_INFO, NULL))
 165
 166 /* video metadata transforms */
 167
 168 GST_VIDEO_API
 169 GQuark gst_video_meta_transform_scale_get_quark (void);
 170 /**
 171  * gst_video_meta_transform_scale:
 172  *
 173  * GQuark for the video "gst-video-scale" transform.
 174  */
 175 #define GST_VIDEO_META_TRANSFORM_IS_SCALE(type) ((type) == gst_video_meta_transform_scale_get_quark())
 176
 177 /**
 178  * GstVideoMetaTransform:
 179  * @in_info: the input #GstVideoInfo
 180  * @out_info: the output #GstVideoInfo
 181  *
 182  * Extra data passed to a video transform #GstMetaTransformFunction such as:
 183  * "gst-video-scale".
 184  */
 185 typedef struct {
 186   GstVideoInfo *in_info;
 187   GstVideoInfo *out_info;
 188 } GstVideoMetaTransform;
 189
 190 /**
 191  * GstVideoGLTextureType:
 192  * @GST_VIDEO_GL_TEXTURE_TYPE_LUMINANCE: Luminance texture, GL_LUMINANCE
 193  * @GST_VIDEO_GL_TEXTURE_TYPE_LUMINANCE_ALPHA: Luminance-alpha texture, GL_LUMINANCE_ALPHA
 194  * @GST_VIDEO_GL_TEXTURE_TYPE_RGB16: RGB 565 texture, GL_RGB
 195  * @GST_VIDEO_GL_TEXTURE_TYPE_RGB: RGB texture, GL_RGB
 196  * @GST_VIDEO_GL_TEXTURE_TYPE_RGBA: RGBA texture, GL_RGBA
 197  * @GST_VIDEO_GL_TEXTURE_TYPE_R: R texture, GL_RED_EXT
 198  * @GST_VIDEO_GL_TEXTURE_TYPE_RG: RG texture, GL_RG_EXT
 199  *
 200  * The GL texture type.
 201  */
 202 typedef enum
 203 {
 204   GST_VIDEO_GL_TEXTURE_TYPE_LUMINANCE,
 205   GST_VIDEO_GL_TEXTURE_TYPE_LUMINANCE_ALPHA,
 206   GST_VIDEO_GL_TEXTURE_TYPE_RGB16,
 207   GST_VIDEO_GL_TEXTURE_TYPE_RGB,
 208   GST_VIDEO_GL_TEXTURE_TYPE_RGBA,
 209   GST_VIDEO_GL_TEXTURE_TYPE_R,
 210   GST_VIDEO_GL_TEXTURE_TYPE_RG
 211 } GstVideoGLTextureType;
 212
 213 /**
 214  * GstVideoGLTextureOrientation:
 215  * @GST_VIDEO_GL_TEXTURE_ORIENTATION_X_NORMAL_Y_NORMAL: Top line first in memory, left row first
 216  * @GST_VIDEO_GL_TEXTURE_ORIENTATION_X_NORMAL_Y_FLIP: Bottom line first in memory, left row first
 217  * @GST_VIDEO_GL_TEXTURE_ORIENTATION_X_FLIP_Y_NORMAL: Top line first in memory, right row first
 218  * @GST_VIDEO_GL_TEXTURE_ORIENTATION_X_FLIP_Y_FLIP: Bottom line first in memory, right row first
 219  *
 220  * The orientation of the GL texture.
 221  */
 222 typedef enum
 223 {
 224   GST_VIDEO_GL_TEXTURE_ORIENTATION_X_NORMAL_Y_NORMAL,
 225   GST_VIDEO_GL_TEXTURE_ORIENTATION_X_NORMAL_Y_FLIP,
 226   GST_VIDEO_GL_TEXTURE_ORIENTATION_X_FLIP_Y_NORMAL,
 227   GST_VIDEO_GL_TEXTURE_ORIENTATION_X_FLIP_Y_FLIP
 228 } GstVideoGLTextureOrientation;
 229
 230 #define GST_VIDEO_GL_TEXTURE_UPLOAD_META_API_TYPE (gst_video_gl_texture_upload_meta_api_get_type())
 231 #define GST_VIDEO_GL_TEXTURE_UPLOAD_META_INFO  (gst_video_gl_texture_upload_meta_get_info())
 232
 233 typedef struct _GstVideoGLTextureUploadMeta GstVideoGLTextureUploadMeta;
 234 typedef gboolean (*GstVideoGLTextureUpload) (GstVideoGLTextureUploadMeta *meta, guint texture_id[4]);
 235
 236 #define GST_CAPS_FEATURE_META_GST_VIDEO_GL_TEXTURE_UPLOAD_META "meta:GstVideoGLTextureUploadMeta"
 237
 238 /**
 239  * GST_BUFFER_POOL_OPTION_VIDEO_GL_TEXTURE_UPLOAD_META:
 240  *
 241  * An option that can be activated on a bufferpool to request gl texture upload
 242  * meta on buffers from the pool.
 243  *
 244  * When this option is enabled on the bufferpool,
 245  * @GST_BUFFER_POOL_OPTION_VIDEO_META should also be enabled.
 246  *
 247  * Since: 1.2.2
 248  */
 249 #define GST_BUFFER_POOL_OPTION_VIDEO_GL_TEXTURE_UPLOAD_META "GstBufferPoolOptionVideoGLTextureUploadMeta"
 250
 251 /**
 252  * GstVideoGLTextureUploadMeta:
 253  * @meta: parent #GstMeta
 254  * @texture_orientation: Orientation of the textures
 255  * @n_textures: Number of textures that are generated
 256  * @texture_type: Type of each texture
 257  *
 258  * Extra buffer metadata for uploading a buffer to an OpenGL texture
 259  * ID. The caller of gst_video_gl_texture_upload_meta_upload() must
 260  * have OpenGL set up and call this from a thread where it is valid
 261  * to upload something to an OpenGL texture.
 262  */
 263
 264 struct _GstVideoGLTextureUploadMeta {
 265   GstMeta       meta;
 266
 267   GstVideoGLTextureOrientation texture_orientation;
 268   guint n_textures;
 269   GstVideoGLTextureType texture_type[4];
 270
 271   /* <private> */
 272   GstBuffer *buffer;
 273   GstVideoGLTextureUpload upload;
 274
 275   gpointer      user_data;
 276   GBoxedCopyFunc user_data_copy;
 277   GBoxedFreeFunc user_data_free;
 278 };
 279
 280 GST_VIDEO_API
 281 GType gst_video_gl_texture_upload_meta_api_get_type (void);
 282
 283 GST_VIDEO_API
 284 const GstMetaInfo * gst_video_gl_texture_upload_meta_get_info (void);
 285
 286 #define gst_buffer_get_video_gl_texture_upload_meta(b) ((GstVideoGLTextureUploadMeta*)gst_buffer_get_meta((b),GST_VIDEO_GL_TEXTURE_UPLOAD_META_API_TYPE))
 287
 288 GST_VIDEO_API
 289 GstVideoGLTextureUploadMeta *
 290           gst_buffer_add_video_gl_texture_upload_meta (GstBuffer *buffer,
 291                                                        GstVideoGLTextureOrientation texture_orientation,
 292                                                        guint n_textures,
 293                                                        GstVideoGLTextureType texture_type[4],
 294                                                        GstVideoGLTextureUpload upload,
 295                                                        gpointer user_data,
 296                                                        GBoxedCopyFunc user_data_copy,
 297                                                        GBoxedFreeFunc user_data_free);
 298
 299 GST_VIDEO_API
 300 gboolean  gst_video_gl_texture_upload_meta_upload     (GstVideoGLTextureUploadMeta *meta,
 301                                                        guint texture_id[4]);
 302
 303
 304 /**
 305  * GstVideoRegionOfInterestMeta:
 306  * @meta: parent #GstMeta
 307  * @roi_type: GQuark describing the semantic of the Roi (f.i. a face, a pedestrian)
 308  * @id: identifier of this particular ROI
 309  * @parent_id: identifier of its parent ROI, used f.i. for ROI hierarchisation.
 310  * @x: x component of upper-left corner
 311  * @y: y component of upper-left corner
 312  * @w: bounding box width
 313  * @h: bounding box height
 314  * @params: list of #GstStructure containing element-specific params for downstream,
 315  *          see gst_video_region_of_interest_meta_add_param(). (Since: 1.14)
 316  *
 317  * Extra buffer metadata describing an image region of interest
 318  */
 319 typedef struct {
 320   GstMeta meta;
 321
 322   GQuark roi_type;
 323   gint id;
 324   gint parent_id;
 325
 326   guint x;
 327   guint y;
 328   guint w;
 329   guint h;
 330
 331   GList *params;
 332 } GstVideoRegionOfInterestMeta;
 333
 334 GST_VIDEO_API
 335 GType              gst_video_region_of_interest_meta_api_get_type (void);
 336 #define GST_VIDEO_REGION_OF_INTEREST_META_API_TYPE (gst_video_region_of_interest_meta_api_get_type())
 337 GST_VIDEO_API
 338 const GstMetaInfo *gst_video_region_of_interest_meta_get_info (void);
 339 #define GST_VIDEO_REGION_OF_INTEREST_META_INFO (gst_video_region_of_interest_meta_get_info())
 340
 341 #define gst_buffer_get_video_region_of_interest_meta(b) \
 342         ((GstVideoRegionOfInterestMeta*)gst_buffer_get_meta((b),GST_VIDEO_REGION_OF_INTEREST_META_API_TYPE))
 343 GST_VIDEO_API
 344 GstVideoRegionOfInterestMeta *gst_buffer_get_video_region_of_interest_meta_id (GstBuffer   * buffer,
 345                                                                                gint          id);
 346
 347 GST_VIDEO_API
 348 GstVideoRegionOfInterestMeta *gst_buffer_add_video_region_of_interest_meta    (GstBuffer   * buffer,
 349                                                                                const gchar * roi_type,
 350                                                                                guint         x,
 351                                                                                guint         y,
 352                                                                                guint         w,
 353                                                                                guint         h);
 354
 355 GST_VIDEO_API
 356 GstVideoRegionOfInterestMeta *gst_buffer_add_video_region_of_interest_meta_id (GstBuffer   * buffer,
 357                                                                                GQuark        roi_type,
 358                                                                                guint         x,
 359                                                                                guint         y,
 360                                                                                guint         w,
 361                                                                                guint         h);
 362 GST_VIDEO_API
 363 void gst_video_region_of_interest_meta_add_param (GstVideoRegionOfInterestMeta * meta,
 364                                                   GstStructure * s);
 365
 366 GST_VIDEO_API
 367 GstStructure *gst_video_region_of_interest_meta_get_param (GstVideoRegionOfInterestMeta * meta,
 368                                                            const gchar * name);
 369
 370 /**
 371  * GstVideoTimeCodeMeta:
 372  * @meta: parent #GstMeta
 373  * @tc: the GstVideoTimeCode to attach
 374  *
 375  * Extra buffer metadata describing the GstVideoTimeCode of the frame.
 376  *
 377  * Each frame is assumed to have its own timecode, i.e. they are not
 378  * automatically incremented/interpolated.
 379  *
 380  * Since: 1.10
 381  */
 382 typedef struct {
 383   GstMeta meta;
 384
 385   GstVideoTimeCode tc;
 386 } GstVideoTimeCodeMeta;
 387
 388 GST_VIDEO_API
 389 GType              gst_video_time_code_meta_api_get_type (void);
 390 #define GST_VIDEO_TIME_CODE_META_API_TYPE (gst_video_time_code_meta_api_get_type())
 391
 392 GST_VIDEO_API
 393 const GstMetaInfo *gst_video_time_code_meta_get_info (void);
 394 #define GST_VIDEO_TIME_CODE_META_INFO (gst_video_time_code_meta_get_info())
 395
 396 #define gst_buffer_get_video_time_code_meta(b) \
 397         ((GstVideoTimeCodeMeta*)gst_buffer_get_meta((b),GST_VIDEO_TIME_CODE_META_API_TYPE))
 398
 399 GST_VIDEO_API
 400 GstVideoTimeCodeMeta *gst_buffer_add_video_time_code_meta    (GstBuffer             * buffer,
 401                                                               const GstVideoTimeCode* tc);
 402
 403 GST_VIDEO_API
 404 GstVideoTimeCodeMeta *
 405 gst_buffer_add_video_time_code_meta_full                     (GstBuffer             * buffer,
 406                                                               guint fps_n,
 407                                                               guint fps_d,
 408                                                               GDateTime             * latest_daily_jam,
 409                                                               GstVideoTimeCodeFlags   flags,
 410                                                               guint                   hours,
 411                                                               guint                   minutes,
 412                                                               guint                   seconds,
 413                                                               guint                   frames,
 414                                                               guint                   field_count);
 415
 416 G_END_DECLS
 417
 418 #endif /* __GST_VIDEO_META_H__ */