subprojects/gst-plugins-base/gst-libs/gst/video/video-frame.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_FRAME_H__
  21 #define __GST_VIDEO_FRAME_H__
  22
  23 #include <gst/video/video-enumtypes.h>
  24
  25 G_BEGIN_DECLS
  26
  27 typedef struct _GstVideoFrame GstVideoFrame;
  28
  29 /**
  30  * GstVideoFrameFlags:
  31  * @GST_VIDEO_FRAME_FLAG_NONE: no flags
  32  * @GST_VIDEO_FRAME_FLAG_INTERLACED: The video frame is interlaced. In mixed
  33  *           interlace-mode, this flag specifies if the frame is interlaced or
  34  *           progressive.
  35  * @GST_VIDEO_FRAME_FLAG_TFF: The video frame has the top field first
  36  * @GST_VIDEO_FRAME_FLAG_RFF: The video frame has the repeat flag
  37  * @GST_VIDEO_FRAME_FLAG_ONEFIELD: The video frame has one field
  38  * @GST_VIDEO_FRAME_FLAG_MULTIPLE_VIEW: The video contains one or
  39  *     more non-mono views
  40  * @GST_VIDEO_FRAME_FLAG_FIRST_IN_BUNDLE: The video frame is the first
  41  *     in a set of corresponding views provided as sequential frames.
  42  * @GST_VIDEO_FRAME_FLAG_TOP_FIELD: The video frame has the top field only. This
  43  *     is the same as GST_VIDEO_FRAME_FLAG_TFF | GST_VIDEO_FRAME_FLAG_ONEFIELD
  44  *     (Since: 1.16).
  45  * @GST_VIDEO_FRAME_FLAG_BOTTOM_FIELD: The video frame has the bottom field
  46  *     only. This is the same as GST_VIDEO_FRAME_FLAG_ONEFIELD
  47  *     (GST_VIDEO_FRAME_FLAG_TFF flag unset) (Since: 1.16).
  48  *
  49  * Extra video frame flags
  50  */
  51 typedef enum {
  52   GST_VIDEO_FRAME_FLAG_NONE         = 0,
  53   GST_VIDEO_FRAME_FLAG_INTERLACED   = (1 << 0),
  54   GST_VIDEO_FRAME_FLAG_TFF          = (1 << 1),
  55   GST_VIDEO_FRAME_FLAG_RFF          = (1 << 2),
  56   GST_VIDEO_FRAME_FLAG_ONEFIELD     = (1 << 3),
  57   GST_VIDEO_FRAME_FLAG_MULTIPLE_VIEW = (1 << 4),
  58   GST_VIDEO_FRAME_FLAG_FIRST_IN_BUNDLE = (1 << 5),
  59   GST_VIDEO_FRAME_FLAG_TOP_FIELD    = GST_VIDEO_FRAME_FLAG_TFF |
  60                                       GST_VIDEO_FRAME_FLAG_ONEFIELD,
  61   GST_VIDEO_FRAME_FLAG_BOTTOM_FIELD = GST_VIDEO_FRAME_FLAG_ONEFIELD,
  62 } GstVideoFrameFlags;
  63
  64 /* circular dependency, need to include this after defining the enums */
  65 #include <gst/video/video-format.h>
  66 #include <gst/video/video-info.h>
  67
  68 /**
  69  * GstVideoFrame:
  70  * @info: the #GstVideoInfo
  71  * @flags: #GstVideoFrameFlags for the frame
  72  * @buffer: the mapped buffer
  73  * @meta: pointer to metadata if any
  74  * @id: id of the mapped frame. the id can for example be used to
  75  *   identify the frame in case of multiview video.
  76  * @data: pointers to the plane data
  77  * @map: mappings of the planes
  78  *
  79  * A video frame obtained from gst_video_frame_map()
  80  */
  81 struct _GstVideoFrame {
  82   GstVideoInfo info;
  83   GstVideoFrameFlags flags;
  84
  85   GstBuffer *buffer;
  86   gpointer   meta;
  87   gint       id;
  88
  89   gpointer   data[GST_VIDEO_MAX_PLANES];
  90   GstMapInfo map[GST_VIDEO_MAX_PLANES];
  91
  92   /*< private >*/
  93   gpointer _gst_reserved[GST_PADDING];
  94 };
  95
  96 GST_VIDEO_API
  97 gboolean    gst_video_frame_map           (GstVideoFrame *frame, const GstVideoInfo *info,
  98                                            GstBuffer *buffer, GstMapFlags flags);
  99
 100 GST_VIDEO_API
 101 gboolean    gst_video_frame_map_id        (GstVideoFrame *frame, const GstVideoInfo *info,
 102                                            GstBuffer *buffer, gint id, GstMapFlags flags);
 103
 104 GST_VIDEO_API
 105 void        gst_video_frame_unmap         (GstVideoFrame *frame);
 106
 107 GST_VIDEO_API
 108 gboolean    gst_video_frame_copy          (GstVideoFrame *dest, const GstVideoFrame *src);
 109
 110 GST_VIDEO_API
 111 gboolean    gst_video_frame_copy_plane    (GstVideoFrame *dest, const GstVideoFrame *src,
 112                                            guint plane);
 113
 114 /* general info */
 115 #define GST_VIDEO_FRAME_FORMAT(f)         (GST_VIDEO_INFO_FORMAT(&(f)->info))
 116 #define GST_VIDEO_FRAME_WIDTH(f)          (GST_VIDEO_INFO_WIDTH(&(f)->info))
 117 #define GST_VIDEO_FRAME_HEIGHT(f)         (GST_VIDEO_INFO_HEIGHT(&(f)->info))
 118 #define GST_VIDEO_FRAME_SIZE(f)           (GST_VIDEO_INFO_SIZE(&(f)->info))
 119
 120 /* flags */
 121 #define GST_VIDEO_FRAME_FLAGS(f)           ((f)->flags)
 122 #define GST_VIDEO_FRAME_FLAG_IS_SET(f,fl)  ((GST_VIDEO_FRAME_FLAGS(f) & (fl)) == (fl))
 123 #define GST_VIDEO_FRAME_IS_INTERLACED(f)   (GST_VIDEO_FRAME_FLAG_IS_SET(f, GST_VIDEO_FRAME_FLAG_INTERLACED))
 124 #define GST_VIDEO_FRAME_IS_TFF(f)          (GST_VIDEO_FRAME_FLAG_IS_SET(f, GST_VIDEO_FRAME_FLAG_TFF))
 125 #define GST_VIDEO_FRAME_IS_RFF(f)          (GST_VIDEO_FRAME_FLAG_IS_SET(f, GST_VIDEO_FRAME_FLAG_RFF))
 126 #define GST_VIDEO_FRAME_IS_ONEFIELD(f)     (GST_VIDEO_FRAME_FLAG_IS_SET(f, GST_VIDEO_FRAME_FLAG_ONEFIELD))
 127 #define GST_VIDEO_FRAME_IS_TOP_FIELD(f)    (GST_VIDEO_FRAME_FLAG_IS_SET(f, GST_VIDEO_FRAME_FLAG_TOP_FIELD))
 128
 129 /*  GST_VIDEO_FRAME_FLAG_BOTTOM_FIELD is a subset of
 130  *  GST_VIDEO_FRAME_FLAG_TOP_FIELD so needs to be checked accordingly. */
 131 #define _GST_VIDEO_FRAME_FLAG_FIELD_MASK GST_VIDEO_FRAME_FLAG_TOP_FIELD
 132
 133 #define GST_VIDEO_FRAME_IS_BOTTOM_FIELD(f) (((f)->flags & _GST_VIDEO_FRAME_FLAG_FIELD_MASK) == GST_VIDEO_FRAME_FLAG_BOTTOM_FIELD)
 134
 135 /* dealing with planes */
 136 #define GST_VIDEO_FRAME_N_PLANES(f)       (GST_VIDEO_INFO_N_PLANES(&(f)->info))
 137 #define GST_VIDEO_FRAME_PLANE_DATA(f,p)   ((f)->data[p])
 138 #define GST_VIDEO_FRAME_PLANE_OFFSET(f,p) (GST_VIDEO_INFO_PLANE_OFFSET(&(f)->info,(p)))
 139 #define GST_VIDEO_FRAME_PLANE_STRIDE(f,p) (GST_VIDEO_INFO_PLANE_STRIDE(&(f)->info,(p)))
 140
 141 /* dealing with components */
 142 #define GST_VIDEO_FRAME_N_COMPONENTS(f)   GST_VIDEO_INFO_N_COMPONENTS(&(f)->info)
 143 #define GST_VIDEO_FRAME_COMP_DEPTH(f,c)   GST_VIDEO_INFO_COMP_DEPTH(&(f)->info,(c))
 144 #define GST_VIDEO_FRAME_COMP_DATA(f,c)    GST_VIDEO_INFO_COMP_DATA(&(f)->info,(f)->data,(c))
 145 #define GST_VIDEO_FRAME_COMP_STRIDE(f,c)  GST_VIDEO_INFO_COMP_STRIDE(&(f)->info,(c))
 146 #define GST_VIDEO_FRAME_COMP_OFFSET(f,c)  GST_VIDEO_INFO_COMP_OFFSET(&(f)->info,(c))
 147 #define GST_VIDEO_FRAME_COMP_WIDTH(f,c)   GST_VIDEO_INFO_COMP_WIDTH(&(f)->info,(c))
 148 #define GST_VIDEO_FRAME_COMP_HEIGHT(f,c)  GST_VIDEO_INFO_COMP_HEIGHT(&(f)->info,(c))
 149 #define GST_VIDEO_FRAME_COMP_PLANE(f,c)   GST_VIDEO_INFO_COMP_PLANE(&(f)->info,(c))
 150 #define GST_VIDEO_FRAME_COMP_PSTRIDE(f,c) GST_VIDEO_INFO_COMP_PSTRIDE(&(f)->info,(c))
 151 #define GST_VIDEO_FRAME_COMP_POFFSET(f,c) GST_VIDEO_INFO_COMP_POFFSET(&(f)->info,(c))
 152
 153 /* buffer flags */
 154
 155 /**
 156  * GstVideoBufferFlags:
 157  * @GST_VIDEO_BUFFER_FLAG_INTERLACED:  If the #GstBuffer is interlaced. In mixed
 158  *                                     interlace-mode, this flags specifies if the frame is
 159  *                                     interlaced or progressive.
 160  * @GST_VIDEO_BUFFER_FLAG_TFF:         If the #GstBuffer is interlaced, then the first field
 161  *                                     in the video frame is the top field.  If unset, the
 162  *                                     bottom field is first.
 163  * @GST_VIDEO_BUFFER_FLAG_RFF:         If the #GstBuffer is interlaced, then the first field
 164  *                                     (as defined by the %GST_VIDEO_BUFFER_FLAG_TFF flag setting)
 165  *                                     is repeated.
 166  * @GST_VIDEO_BUFFER_FLAG_ONEFIELD:    If the #GstBuffer is interlaced, then only the
 167  *                                     first field (as defined by the %GST_VIDEO_BUFFER_FLAG_TFF
 168  *                                     flag setting) is to be displayed (Since: 1.16).
 169  * @GST_VIDEO_BUFFER_FLAG_MULTIPLE_VIEW: The #GstBuffer contains one or more specific views,
 170  *                                     such as left or right eye view. This flags is set on
 171  *                                     any buffer that contains non-mono content - even for
 172  *                                     streams that contain only a single viewpoint. In mixed
 173  *                                     mono / non-mono streams, the absence of the flag marks
 174  *                                     mono buffers.
 175  * @GST_VIDEO_BUFFER_FLAG_FIRST_IN_BUNDLE: When conveying stereo/multiview content with
 176  *                                     frame-by-frame methods, this flag marks the first buffer
 177  *                                      in a bundle of frames that belong together.
 178  * @GST_VIDEO_BUFFER_FLAG_TOP_FIELD:   The video frame has the top field only. This is the
 179  *                                     same as GST_VIDEO_BUFFER_FLAG_TFF |
 180  *                                     GST_VIDEO_BUFFER_FLAG_ONEFIELD (Since: 1.16).
 181  *                                     Use GST_VIDEO_BUFFER_IS_TOP_FIELD() to check for this flag.
 182  * @GST_VIDEO_BUFFER_FLAG_BOTTOM_FIELD: The video frame has the bottom field only. This is
 183  *                                     the same as GST_VIDEO_BUFFER_FLAG_ONEFIELD
 184  *                                     (GST_VIDEO_BUFFER_FLAG_TFF flag unset) (Since: 1.16).
 185  *                                     Use GST_VIDEO_BUFFER_IS_BOTTOM_FIELD() to check for this flag.
 186  * @GST_VIDEO_BUFFER_FLAG_MARKER:      The #GstBuffer contains the end of a video field or frame
 187  *                                     boundary such as the last subframe or packet (Since: 1.18).
 188  * @GST_VIDEO_BUFFER_FLAG_LAST:        Offset to define more flags
 189  *
 190  * Additional video buffer flags. These flags can potentially be used on any
 191  * buffers carrying closed caption data, or video data - even encoded data.
 192  *
 193  * Note that these are only valid for #GstCaps of type: video/... and caption/...
 194  * They can conflict with other extended buffer flags.
 195  */
 196 typedef enum {
 197   GST_VIDEO_BUFFER_FLAG_INTERLACED  = (GST_BUFFER_FLAG_LAST << 0),
 198   GST_VIDEO_BUFFER_FLAG_TFF         = (GST_BUFFER_FLAG_LAST << 1),
 199   GST_VIDEO_BUFFER_FLAG_RFF         = (GST_BUFFER_FLAG_LAST << 2),
 200   GST_VIDEO_BUFFER_FLAG_ONEFIELD    = (GST_BUFFER_FLAG_LAST << 3),
 201
 202   GST_VIDEO_BUFFER_FLAG_MULTIPLE_VIEW = (GST_BUFFER_FLAG_LAST << 4),
 203   GST_VIDEO_BUFFER_FLAG_FIRST_IN_BUNDLE = (GST_BUFFER_FLAG_LAST << 5),
 204
 205   GST_VIDEO_BUFFER_FLAG_TOP_FIELD   = GST_VIDEO_BUFFER_FLAG_TFF |
 206                                       GST_VIDEO_BUFFER_FLAG_ONEFIELD,
 207   GST_VIDEO_BUFFER_FLAG_BOTTOM_FIELD = GST_VIDEO_BUFFER_FLAG_ONEFIELD,
 208
 209   GST_VIDEO_BUFFER_FLAG_MARKER       = GST_BUFFER_FLAG_MARKER,
 210
 211   GST_VIDEO_BUFFER_FLAG_LAST        = (GST_BUFFER_FLAG_LAST << 8)
 212 } GstVideoBufferFlags;
 213
 214 /* GST_VIDEO_BUFFER_FLAG_TOP_FIELD is a subset of
 215  * GST_VIDEO_BUFFER_FLAG_BOTTOM_FIELD so needs to be checked accordingly. */
 216 #define _GST_VIDEO_BUFFER_FLAG_FIELD_MASK GST_VIDEO_BUFFER_FLAG_TOP_FIELD
 217
 218 /**
 219  * GST_VIDEO_BUFFER_IS_TOP_FIELD:
 220  * @buf: a #GstBuffer
 221  *
 222  * Check if GST_VIDEO_BUFFER_FLAG_TOP_FIELD is set on @buf (Since: 1.18).
 223  */
 224 #define GST_VIDEO_BUFFER_IS_TOP_FIELD(buf) ((GST_BUFFER_FLAGS (buf) & _GST_VIDEO_BUFFER_FLAG_FIELD_MASK) == GST_VIDEO_BUFFER_FLAG_TOP_FIELD)
 225
 226 /**
 227  * GST_VIDEO_BUFFER_IS_BOTTOM_FIELD:
 228  * @buf: a #GstBuffer
 229  *
 230  * Check if GST_VIDEO_BUFFER_FLAG_BOTTOM_FIELD is set on @buf (Since: 1.18).
 231  */
 232 #define GST_VIDEO_BUFFER_IS_BOTTOM_FIELD(buf) ((GST_BUFFER_FLAGS (buf) & _GST_VIDEO_BUFFER_FLAG_FIELD_MASK) == GST_VIDEO_BUFFER_FLAG_BOTTOM_FIELD)
 233
 234 /**
 235  * GstVideoFrameMapFlags:
 236  * @GST_VIDEO_FRAME_MAP_FLAG_NO_REF:  Don't take another reference of the buffer and store it in
 237  *                                    the GstVideoFrame. This makes sure that the buffer stays
 238  *                                    writable while the frame is mapped, but requires that the
 239  *                                    buffer reference stays valid until the frame is unmapped again.
 240  * @GST_VIDEO_FRAME_MAP_FLAG_LAST:    Offset to define more flags
 241  *
 242  * Additional mapping flags for gst_video_frame_map().
 243  *
 244  * Since: 1.6
 245  */
 246 typedef enum {
 247   GST_VIDEO_FRAME_MAP_FLAG_NO_REF   = (GST_MAP_FLAG_LAST << 0),
 248   GST_VIDEO_FRAME_MAP_FLAG_LAST     = (GST_MAP_FLAG_LAST << 8)
 249   /* 8 more flags possible afterwards */
 250 } GstVideoFrameMapFlags;
 251
 252 G_END_DECLS
 253
 254 #endif /* __GST_VIDEO_FRAME_H__ */