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 struct _GstVideoMeta {
  64   GstMeta            meta;
  65
  66   GstBuffer         *buffer;
  67
  68   GstVideoFrameFlags flags;
  69   GstVideoFormat     format;
  70   gint               id;
  71   guint              width;
  72   guint              height;
  73
  74   guint              n_planes;
  75   gsize              offset[GST_VIDEO_MAX_PLANES];
  76   gint               stride[GST_VIDEO_MAX_PLANES];
  77
  78   gboolean (*map)    (GstVideoMeta *meta, guint plane, GstMapInfo *info,
  79                       gpointer *data, gint * stride, GstMapFlags flags);
  80   gboolean (*unmap)  (GstVideoMeta *meta, guint plane, GstMapInfo *info);
  81
  82   GstVideoAlignment  alignment;
  83 };
  84
  85 GST_VIDEO_API
  86 GType gst_video_meta_api_get_type (void);
  87
  88 GST_VIDEO_API
  89 const GstMetaInfo * gst_video_meta_get_info (void);
  90
  91 GST_VIDEO_API
  92 GstVideoMeta * gst_buffer_get_video_meta (GstBuffer *buffer);
  93
  94 GST_VIDEO_API
  95 GstVideoMeta * gst_buffer_get_video_meta_id    (GstBuffer *buffer, gint id);
  96
  97 GST_VIDEO_API
  98 GstVideoMeta * gst_buffer_add_video_meta       (GstBuffer *buffer, GstVideoFrameFlags flags,
  99                                                 GstVideoFormat format, guint width, guint height);
 100
 101 GST_VIDEO_API
 102 GstVideoMeta * gst_buffer_add_video_meta_full  (GstBuffer *buffer, GstVideoFrameFlags flags,
 103                                                 GstVideoFormat format, guint width, guint height,
 104                                                 guint n_planes, gsize offset[GST_VIDEO_MAX_PLANES],
 105                                                 gint stride[GST_VIDEO_MAX_PLANES]);
 106
 107 GST_VIDEO_API
 108 gboolean       gst_video_meta_map        (GstVideoMeta *meta, guint plane, GstMapInfo *info,
 109                                           gpointer *data, gint *stride, GstMapFlags flags);
 110
 111 GST_VIDEO_API
 112 gboolean       gst_video_meta_unmap      (GstVideoMeta *meta, guint plane, GstMapInfo *info);
 113
 114 GST_VIDEO_API
 115 gboolean       gst_video_meta_set_alignment (GstVideoMeta * meta, GstVideoAlignment alignment);
 116
 117 GST_VIDEO_API
 118 gboolean       gst_video_meta_get_plane_size (GstVideoMeta * meta, gsize plane_size[GST_VIDEO_MAX_PLANES]);
 119
 120 GST_VIDEO_API
 121 gboolean       gst_video_meta_get_plane_height (GstVideoMeta * meta, guint plane_height[GST_VIDEO_MAX_PLANES]);
 122
 123 /**
 124  * GstVideoCropMeta:
 125  * @meta: parent #GstMeta
 126  * @x: the horizontal offset
 127  * @y: the vertical offset
 128  * @width: the cropped width
 129  * @height: the cropped height
 130  *
 131  * Extra buffer metadata describing image cropping.
 132  */
 133 struct _GstVideoCropMeta {
 134   GstMeta       meta;
 135
 136   guint         x;
 137   guint         y;
 138   guint         width;
 139   guint         height;
 140 };
 141
 142 GST_VIDEO_API
 143 GType gst_video_crop_meta_api_get_type (void);
 144
 145 GST_VIDEO_API
 146 const GstMetaInfo * gst_video_crop_meta_get_info (void);
 147
 148 #define gst_buffer_get_video_crop_meta(b) ((GstVideoCropMeta*)gst_buffer_get_meta((b),GST_VIDEO_CROP_META_API_TYPE))
 149 #define gst_buffer_add_video_crop_meta(b) ((GstVideoCropMeta*)gst_buffer_add_meta((b),GST_VIDEO_CROP_META_INFO, NULL))
 150
 151 /* video metadata transforms */
 152
 153 GST_VIDEO_API
 154 GQuark gst_video_meta_transform_scale_get_quark (void);
 155 /**
 156  * gst_video_meta_transform_scale:
 157  *
 158  * GQuark for the video "gst-video-scale" transform.
 159  */
 160 #define GST_VIDEO_META_TRANSFORM_IS_SCALE(type) ((type) == gst_video_meta_transform_scale_get_quark())
 161
 162 /**
 163  * GstVideoMetaTransform:
 164  * @in_info: the input #GstVideoInfo
 165  * @out_info: the output #GstVideoInfo
 166  *
 167  * Extra data passed to a video transform #GstMetaTransformFunction such as:
 168  * "gst-video-scale".
 169  */
 170 typedef struct {
 171   GstVideoInfo *in_info;
 172   GstVideoInfo *out_info;
 173 } GstVideoMetaTransform;
 174
 175 /**
 176  * GstVideoGLTextureType:
 177  * @GST_VIDEO_GL_TEXTURE_TYPE_LUMINANCE: Luminance texture, GL_LUMINANCE
 178  * @GST_VIDEO_GL_TEXTURE_TYPE_LUMINANCE_ALPHA: Luminance-alpha texture, GL_LUMINANCE_ALPHA
 179  * @GST_VIDEO_GL_TEXTURE_TYPE_RGB16: RGB 565 texture, GL_RGB
 180  * @GST_VIDEO_GL_TEXTURE_TYPE_RGB: RGB texture, GL_RGB
 181  * @GST_VIDEO_GL_TEXTURE_TYPE_RGBA: RGBA texture, GL_RGBA
 182  * @GST_VIDEO_GL_TEXTURE_TYPE_R: R texture, GL_RED_EXT
 183  * @GST_VIDEO_GL_TEXTURE_TYPE_RG: RG texture, GL_RG_EXT
 184  *
 185  * The GL texture type.
 186  */
 187 typedef enum
 188 {
 189   GST_VIDEO_GL_TEXTURE_TYPE_LUMINANCE,
 190   GST_VIDEO_GL_TEXTURE_TYPE_LUMINANCE_ALPHA,
 191   GST_VIDEO_GL_TEXTURE_TYPE_RGB16,
 192   GST_VIDEO_GL_TEXTURE_TYPE_RGB,
 193   GST_VIDEO_GL_TEXTURE_TYPE_RGBA,
 194   GST_VIDEO_GL_TEXTURE_TYPE_R,
 195   GST_VIDEO_GL_TEXTURE_TYPE_RG
 196 } GstVideoGLTextureType;
 197
 198 /**
 199  * GstVideoGLTextureOrientation:
 200  * @GST_VIDEO_GL_TEXTURE_ORIENTATION_X_NORMAL_Y_NORMAL: Top line first in memory, left row first
 201  * @GST_VIDEO_GL_TEXTURE_ORIENTATION_X_NORMAL_Y_FLIP: Bottom line first in memory, left row first
 202  * @GST_VIDEO_GL_TEXTURE_ORIENTATION_X_FLIP_Y_NORMAL: Top line first in memory, right row first
 203  * @GST_VIDEO_GL_TEXTURE_ORIENTATION_X_FLIP_Y_FLIP: Bottom line first in memory, right row first
 204  *
 205  * The orientation of the GL texture.
 206  */
 207 typedef enum
 208 {
 209   GST_VIDEO_GL_TEXTURE_ORIENTATION_X_NORMAL_Y_NORMAL,
 210   GST_VIDEO_GL_TEXTURE_ORIENTATION_X_NORMAL_Y_FLIP,
 211   GST_VIDEO_GL_TEXTURE_ORIENTATION_X_FLIP_Y_NORMAL,
 212   GST_VIDEO_GL_TEXTURE_ORIENTATION_X_FLIP_Y_FLIP
 213 } GstVideoGLTextureOrientation;
 214
 215 #define GST_VIDEO_GL_TEXTURE_UPLOAD_META_API_TYPE (gst_video_gl_texture_upload_meta_api_get_type())
 216 #define GST_VIDEO_GL_TEXTURE_UPLOAD_META_INFO  (gst_video_gl_texture_upload_meta_get_info())
 217
 218 typedef struct _GstVideoGLTextureUploadMeta GstVideoGLTextureUploadMeta;
 219 typedef gboolean (*GstVideoGLTextureUpload) (GstVideoGLTextureUploadMeta *meta, guint texture_id[4]);
 220
 221 #define GST_CAPS_FEATURE_META_GST_VIDEO_GL_TEXTURE_UPLOAD_META "meta:GstVideoGLTextureUploadMeta"
 222
 223 /**
 224  * GST_BUFFER_POOL_OPTION_VIDEO_GL_TEXTURE_UPLOAD_META:
 225  *
 226  * An option that can be activated on a bufferpool to request gl texture upload
 227  * meta on buffers from the pool.
 228  *
 229  * When this option is enabled on the bufferpool,
 230  * @GST_BUFFER_POOL_OPTION_VIDEO_META should also be enabled.
 231  *
 232  * Since: 1.2.2
 233  */
 234 #define GST_BUFFER_POOL_OPTION_VIDEO_GL_TEXTURE_UPLOAD_META "GstBufferPoolOptionVideoGLTextureUploadMeta"
 235
 236 /**
 237  * GstVideoGLTextureUploadMeta:
 238  * @meta: parent #GstMeta
 239  * @texture_orientation: Orientation of the textures
 240  * @n_textures: Number of textures that are generated
 241  * @texture_type: Type of each texture
 242  *
 243  * Extra buffer metadata for uploading a buffer to an OpenGL texture
 244  * ID. The caller of gst_video_gl_texture_upload_meta_upload() must
 245  * have OpenGL set up and call this from a thread where it is valid
 246  * to upload something to an OpenGL texture.
 247  */
 248
 249 struct _GstVideoGLTextureUploadMeta {
 250   GstMeta       meta;
 251
 252   GstVideoGLTextureOrientation texture_orientation;
 253   guint n_textures;
 254   GstVideoGLTextureType texture_type[4];
 255
 256   /* <private> */
 257   GstBuffer *buffer;
 258   GstVideoGLTextureUpload upload;
 259
 260   gpointer      user_data;
 261   GBoxedCopyFunc user_data_copy;
 262   GBoxedFreeFunc user_data_free;
 263 };
 264
 265 GST_VIDEO_API
 266 GType gst_video_gl_texture_upload_meta_api_get_type (void);
 267
 268 GST_VIDEO_API
 269 const GstMetaInfo * gst_video_gl_texture_upload_meta_get_info (void);
 270
 271 #define gst_buffer_get_video_gl_texture_upload_meta(b) ((GstVideoGLTextureUploadMeta*)gst_buffer_get_meta((b),GST_VIDEO_GL_TEXTURE_UPLOAD_META_API_TYPE))
 272
 273 GST_VIDEO_API
 274 GstVideoGLTextureUploadMeta *
 275           gst_buffer_add_video_gl_texture_upload_meta (GstBuffer *buffer,
 276                                                        GstVideoGLTextureOrientation texture_orientation,
 277                                                        guint n_textures,
 278                                                        GstVideoGLTextureType texture_type[4],
 279                                                        GstVideoGLTextureUpload upload,
 280                                                        gpointer user_data,
 281                                                        GBoxedCopyFunc user_data_copy,
 282                                                        GBoxedFreeFunc user_data_free);
 283
 284 GST_VIDEO_API
 285 gboolean  gst_video_gl_texture_upload_meta_upload     (GstVideoGLTextureUploadMeta *meta,
 286                                                        guint texture_id[4]);
 287
 288
 289 /**
 290  * GstVideoRegionOfInterestMeta:
 291  * @meta: parent #GstMeta
 292  * @roi_type: GQuark describing the semantic of the Roi (f.i. a face, a pedestrian)
 293  * @id: identifier of this particular ROI
 294  * @parent_id: identifier of its parent ROI, used f.i. for ROI hierarchisation.
 295  * @x: x component of upper-left corner
 296  * @y: y component of upper-left corner
 297  * @w: bounding box width
 298  * @h: bounding box height
 299  * @params: list of #GstStructure containing element-specific params for downstream, see gst_video_region_of_interest_meta_add_params(). (Since: 1.14)
 300  *
 301  * Extra buffer metadata describing an image region of interest
 302  */
 303 typedef struct {
 304   GstMeta meta;
 305
 306   GQuark roi_type;
 307   gint id;
 308   gint parent_id;
 309
 310   guint x;
 311   guint y;
 312   guint w;
 313   guint h;
 314
 315   GList *params;
 316 } GstVideoRegionOfInterestMeta;
 317
 318 GST_VIDEO_API
 319 GType              gst_video_region_of_interest_meta_api_get_type (void);
 320 #define GST_VIDEO_REGION_OF_INTEREST_META_API_TYPE (gst_video_region_of_interest_meta_api_get_type())
 321 GST_VIDEO_API
 322 const GstMetaInfo *gst_video_region_of_interest_meta_get_info (void);
 323 #define GST_VIDEO_REGION_OF_INTEREST_META_INFO (gst_video_region_of_interest_meta_get_info())
 324
 325 #define gst_buffer_get_video_region_of_interest_meta(b) \
 326         ((GstVideoRegionOfInterestMeta*)gst_buffer_get_meta((b),GST_VIDEO_REGION_OF_INTEREST_META_API_TYPE))
 327 GST_VIDEO_API
 328 GstVideoRegionOfInterestMeta *gst_buffer_get_video_region_of_interest_meta_id (GstBuffer   * buffer,
 329                                                                                gint          id);
 330
 331 GST_VIDEO_API
 332 GstVideoRegionOfInterestMeta *gst_buffer_add_video_region_of_interest_meta    (GstBuffer   * buffer,
 333                                                                                const gchar * roi_type,
 334                                                                                guint         x,
 335                                                                                guint         y,
 336                                                                                guint         w,
 337                                                                                guint         h);
 338
 339 GST_VIDEO_API
 340 GstVideoRegionOfInterestMeta *gst_buffer_add_video_region_of_interest_meta_id (GstBuffer   * buffer,
 341                                                                                GQuark        roi_type,
 342                                                                                guint         x,
 343                                                                                guint         y,
 344                                                                                guint         w,
 345                                                                                guint         h);
 346 GST_VIDEO_API
 347 void gst_video_region_of_interest_meta_add_param (GstVideoRegionOfInterestMeta * meta,
 348                                                   GstStructure * s);
 349
 350 GST_VIDEO_API
 351 GstStructure *gst_video_region_of_interest_meta_get_param (GstVideoRegionOfInterestMeta * meta,
 352                                                            const gchar * name);
 353
 354 /**
 355  * GstVideoTimeCodeMeta:
 356  * @meta: parent #GstMeta
 357  * @tc: the GstVideoTimeCode to attach
 358  *
 359  * Extra buffer metadata describing the GstVideoTimeCode of the frame.
 360  *
 361  * Each frame is assumed to have its own timecode, i.e. they are not
 362  * automatically incremented/interpolated.
 363  *
 364  * Since: 1.10
 365  */
 366 typedef struct {
 367   GstMeta meta;
 368
 369   GstVideoTimeCode tc;
 370 } GstVideoTimeCodeMeta;
 371
 372 GST_VIDEO_API
 373 GType              gst_video_time_code_meta_api_get_type (void);
 374 #define GST_VIDEO_TIME_CODE_META_API_TYPE (gst_video_time_code_meta_api_get_type())
 375
 376 GST_VIDEO_API
 377 const GstMetaInfo *gst_video_time_code_meta_get_info (void);
 378 #define GST_VIDEO_TIME_CODE_META_INFO (gst_video_time_code_meta_get_info())
 379
 380 #define gst_buffer_get_video_time_code_meta(b) \
 381         ((GstVideoTimeCodeMeta*)gst_buffer_get_meta((b),GST_VIDEO_TIME_CODE_META_API_TYPE))
 382
 383 GST_VIDEO_API
 384 GstVideoTimeCodeMeta *gst_buffer_add_video_time_code_meta    (GstBuffer             * buffer,
 385                                                               GstVideoTimeCode      * tc);
 386
 387 GST_VIDEO_API
 388 GstVideoTimeCodeMeta *
 389 gst_buffer_add_video_time_code_meta_full                     (GstBuffer             * buffer,
 390                                                               guint fps_n,
 391                                                               guint fps_d,
 392                                                               GDateTime             * latest_daily_jam,
 393                                                               GstVideoTimeCodeFlags   flags,
 394                                                               guint                   hours,
 395                                                               guint                   minutes,
 396                                                               guint                   seconds,
 397                                                               guint                   frames,
 398                                                               guint                   field_count);
 399
 400 G_END_DECLS
 401
 402 #endif /* __GST_VIDEO_META_H__ */