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__ */ 255