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
25G_BEGIN_DECLS
26
27typedef 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 */
51typedef 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 */
81struct _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/**
97 * GST_VIDEO_FRAME_INIT:
98 *
99 * Initializer for #GstVideoFrame
100 *
101 * Since: 1.22
102 */
103#define GST_VIDEO_FRAME_INIT { { NULL, }, }
104
105
106GST_VIDEO_API
107gboolean gst_video_frame_map (GstVideoFrame *frame, const GstVideoInfo *info,
108 GstBuffer *buffer, GstMapFlags flags);
109
110GST_VIDEO_API
111gboolean gst_video_frame_map_id (GstVideoFrame *frame, const GstVideoInfo *info,
112 GstBuffer *buffer, gint id, GstMapFlags flags);
113
114GST_VIDEO_API
115void gst_video_frame_unmap (GstVideoFrame *frame);
116
117GST_VIDEO_API
118gboolean gst_video_frame_copy (GstVideoFrame *dest, const GstVideoFrame *src);
119
120GST_VIDEO_API
121gboolean gst_video_frame_copy_plane (GstVideoFrame *dest, const GstVideoFrame *src,
122 guint plane);
123
124/* general info */
125#define GST_VIDEO_FRAME_FORMAT(f) (GST_VIDEO_INFO_FORMAT(&(f)->info))
126#define GST_VIDEO_FRAME_WIDTH(f) (GST_VIDEO_INFO_WIDTH(&(f)->info))
127#define GST_VIDEO_FRAME_HEIGHT(f) (GST_VIDEO_INFO_HEIGHT(&(f)->info))
128#define GST_VIDEO_FRAME_SIZE(f) (GST_VIDEO_INFO_SIZE(&(f)->info))
129
130/* flags */
131#define GST_VIDEO_FRAME_FLAGS(f) ((f)->flags)
132#define GST_VIDEO_FRAME_FLAG_IS_SET(f,fl) ((GST_VIDEO_FRAME_FLAGS(f) & (fl)) == (fl))
133#define GST_VIDEO_FRAME_IS_INTERLACED(f) (GST_VIDEO_FRAME_FLAG_IS_SET(f, GST_VIDEO_FRAME_FLAG_INTERLACED))
134#define GST_VIDEO_FRAME_IS_TFF(f) (GST_VIDEO_FRAME_FLAG_IS_SET(f, GST_VIDEO_FRAME_FLAG_TFF))
135#define GST_VIDEO_FRAME_IS_RFF(f) (GST_VIDEO_FRAME_FLAG_IS_SET(f, GST_VIDEO_FRAME_FLAG_RFF))
136#define GST_VIDEO_FRAME_IS_ONEFIELD(f) (GST_VIDEO_FRAME_FLAG_IS_SET(f, GST_VIDEO_FRAME_FLAG_ONEFIELD))
137#define GST_VIDEO_FRAME_IS_TOP_FIELD(f) (GST_VIDEO_FRAME_FLAG_IS_SET(f, GST_VIDEO_FRAME_FLAG_TOP_FIELD))
138
139/* GST_VIDEO_FRAME_FLAG_BOTTOM_FIELD is a subset of
140 * GST_VIDEO_FRAME_FLAG_TOP_FIELD so needs to be checked accordingly. */
141#define _GST_VIDEO_FRAME_FLAG_FIELD_MASK GST_VIDEO_FRAME_FLAG_TOP_FIELD
142
143#define GST_VIDEO_FRAME_IS_BOTTOM_FIELD(f) (((f)->flags & _GST_VIDEO_FRAME_FLAG_FIELD_MASK) == GST_VIDEO_FRAME_FLAG_BOTTOM_FIELD)
144
145/* dealing with planes */
146#define GST_VIDEO_FRAME_N_PLANES(f) (GST_VIDEO_INFO_N_PLANES(&(f)->info))
147#define GST_VIDEO_FRAME_PLANE_DATA(f,p) ((f)->data[p])
148#define GST_VIDEO_FRAME_PLANE_OFFSET(f,p) (GST_VIDEO_INFO_PLANE_OFFSET(&(f)->info,(p)))
149#define GST_VIDEO_FRAME_PLANE_STRIDE(f,p) (GST_VIDEO_INFO_PLANE_STRIDE(&(f)->info,(p)))
150
151/* dealing with components */
152#define GST_VIDEO_FRAME_N_COMPONENTS(f) GST_VIDEO_INFO_N_COMPONENTS(&(f)->info)
153#define GST_VIDEO_FRAME_COMP_DEPTH(f,c) GST_VIDEO_INFO_COMP_DEPTH(&(f)->info,(c))
154#define GST_VIDEO_FRAME_COMP_DATA(f,c) GST_VIDEO_INFO_COMP_DATA(&(f)->info,(f)->data,(c))
155#define GST_VIDEO_FRAME_COMP_STRIDE(f,c) GST_VIDEO_INFO_COMP_STRIDE(&(f)->info,(c))
156#define GST_VIDEO_FRAME_COMP_OFFSET(f,c) GST_VIDEO_INFO_COMP_OFFSET(&(f)->info,(c))
157#define GST_VIDEO_FRAME_COMP_WIDTH(f,c) GST_VIDEO_INFO_COMP_WIDTH(&(f)->info,(c))
158#define GST_VIDEO_FRAME_COMP_HEIGHT(f,c) GST_VIDEO_INFO_COMP_HEIGHT(&(f)->info,(c))
159#define GST_VIDEO_FRAME_COMP_PLANE(f,c) GST_VIDEO_INFO_COMP_PLANE(&(f)->info,(c))
160#define GST_VIDEO_FRAME_COMP_PSTRIDE(f,c) GST_VIDEO_INFO_COMP_PSTRIDE(&(f)->info,(c))
161#define GST_VIDEO_FRAME_COMP_POFFSET(f,c) GST_VIDEO_INFO_COMP_POFFSET(&(f)->info,(c))
162
163/* buffer flags */
164
165/**
166 * GstVideoBufferFlags:
167 * @GST_VIDEO_BUFFER_FLAG_INTERLACED: If the #GstBuffer is interlaced. In mixed
168 * interlace-mode, this flags specifies if the frame is
169 * interlaced or progressive.
170 * @GST_VIDEO_BUFFER_FLAG_TFF: If the #GstBuffer is interlaced, then the first field
171 * in the video frame is the top field. If unset, the
172 * bottom field is first.
173 * @GST_VIDEO_BUFFER_FLAG_RFF: If the #GstBuffer is interlaced, then the first field
174 * (as defined by the %GST_VIDEO_BUFFER_FLAG_TFF flag setting)
175 * is repeated.
176 * @GST_VIDEO_BUFFER_FLAG_ONEFIELD: If the #GstBuffer is interlaced, then only the
177 * first field (as defined by the %GST_VIDEO_BUFFER_FLAG_TFF
178 * flag setting) is to be displayed (Since: 1.16).
179 * @GST_VIDEO_BUFFER_FLAG_MULTIPLE_VIEW: The #GstBuffer contains one or more specific views,
180 * such as left or right eye view. This flags is set on
181 * any buffer that contains non-mono content - even for
182 * streams that contain only a single viewpoint. In mixed
183 * mono / non-mono streams, the absence of the flag marks
184 * mono buffers.
185 * @GST_VIDEO_BUFFER_FLAG_FIRST_IN_BUNDLE: When conveying stereo/multiview content with
186 * frame-by-frame methods, this flag marks the first buffer
187 * in a bundle of frames that belong together.
188 * @GST_VIDEO_BUFFER_FLAG_TOP_FIELD: The video frame has the top field only. This is the
189 * same as GST_VIDEO_BUFFER_FLAG_TFF |
190 * GST_VIDEO_BUFFER_FLAG_ONEFIELD (Since: 1.16).
191 * Use GST_VIDEO_BUFFER_IS_TOP_FIELD() to check for this flag.
192 * @GST_VIDEO_BUFFER_FLAG_BOTTOM_FIELD: The video frame has the bottom field only. This is
193 * the same as GST_VIDEO_BUFFER_FLAG_ONEFIELD
194 * (GST_VIDEO_BUFFER_FLAG_TFF flag unset) (Since: 1.16).
195 * Use GST_VIDEO_BUFFER_IS_BOTTOM_FIELD() to check for this flag.
196 * @GST_VIDEO_BUFFER_FLAG_MARKER: The #GstBuffer contains the end of a video field or frame
197 * boundary such as the last subframe or packet (Since: 1.18).
198 * @GST_VIDEO_BUFFER_FLAG_LAST: Offset to define more flags
199 *
200 * Additional video buffer flags. These flags can potentially be used on any
201 * buffers carrying closed caption data, or video data - even encoded data.
202 *
203 * Note that these are only valid for #GstCaps of type: video/... and caption/...
204 * They can conflict with other extended buffer flags.
205 */
206typedef enum {
207 GST_VIDEO_BUFFER_FLAG_INTERLACED = (GST_BUFFER_FLAG_LAST << 0),
208 GST_VIDEO_BUFFER_FLAG_TFF = (GST_BUFFER_FLAG_LAST << 1),
209 GST_VIDEO_BUFFER_FLAG_RFF = (GST_BUFFER_FLAG_LAST << 2),
210 GST_VIDEO_BUFFER_FLAG_ONEFIELD = (GST_BUFFER_FLAG_LAST << 3),
211
212 GST_VIDEO_BUFFER_FLAG_MULTIPLE_VIEW = (GST_BUFFER_FLAG_LAST << 4),
213 GST_VIDEO_BUFFER_FLAG_FIRST_IN_BUNDLE = (GST_BUFFER_FLAG_LAST << 5),
214
215 GST_VIDEO_BUFFER_FLAG_TOP_FIELD = GST_VIDEO_BUFFER_FLAG_TFF |
216 GST_VIDEO_BUFFER_FLAG_ONEFIELD,
217 GST_VIDEO_BUFFER_FLAG_BOTTOM_FIELD = GST_VIDEO_BUFFER_FLAG_ONEFIELD,
218
219 GST_VIDEO_BUFFER_FLAG_MARKER = GST_BUFFER_FLAG_MARKER,
220
221 GST_VIDEO_BUFFER_FLAG_LAST = (GST_BUFFER_FLAG_LAST << 8)
222} GstVideoBufferFlags;
223
224/* GST_VIDEO_BUFFER_FLAG_TOP_FIELD is a subset of
225 * GST_VIDEO_BUFFER_FLAG_BOTTOM_FIELD so needs to be checked accordingly. */
226#define _GST_VIDEO_BUFFER_FLAG_FIELD_MASK GST_VIDEO_BUFFER_FLAG_TOP_FIELD
227
228/**
229 * GST_VIDEO_BUFFER_IS_TOP_FIELD:
230 * @buf: a #GstBuffer
231 *
232 * Check if GST_VIDEO_BUFFER_FLAG_TOP_FIELD is set on @buf (Since: 1.18).
233 */
234#define GST_VIDEO_BUFFER_IS_TOP_FIELD(buf) ((GST_BUFFER_FLAGS (buf) & _GST_VIDEO_BUFFER_FLAG_FIELD_MASK) == GST_VIDEO_BUFFER_FLAG_TOP_FIELD)
235
236/**
237 * GST_VIDEO_BUFFER_IS_BOTTOM_FIELD:
238 * @buf: a #GstBuffer
239 *
240 * Check if GST_VIDEO_BUFFER_FLAG_BOTTOM_FIELD is set on @buf (Since: 1.18).
241 */
242#define GST_VIDEO_BUFFER_IS_BOTTOM_FIELD(buf) ((GST_BUFFER_FLAGS (buf) & _GST_VIDEO_BUFFER_FLAG_FIELD_MASK) == GST_VIDEO_BUFFER_FLAG_BOTTOM_FIELD)
243
244/**
245 * GstVideoFrameMapFlags:
246 * @GST_VIDEO_FRAME_MAP_FLAG_NO_REF: Don't take another reference of the buffer and store it in
247 * the GstVideoFrame. This makes sure that the buffer stays
248 * writable while the frame is mapped, but requires that the
249 * buffer reference stays valid until the frame is unmapped again.
250 * @GST_VIDEO_FRAME_MAP_FLAG_LAST: Offset to define more flags
251 *
252 * Additional mapping flags for gst_video_frame_map().
253 *
254 * Since: 1.6
255 */
256typedef enum {
257 GST_VIDEO_FRAME_MAP_FLAG_NO_REF = (GST_MAP_FLAG_LAST << 0),
258 GST_VIDEO_FRAME_MAP_FLAG_LAST = (GST_MAP_FLAG_LAST << 8)
259 /* 8 more flags possible afterwards */
260} GstVideoFrameMapFlags;
261
262G_DEFINE_AUTO_CLEANUP_CLEAR_FUNC(GstVideoFrame, gst_video_frame_unmap)
263
264G_END_DECLS
265
266#endif /* __GST_VIDEO_FRAME_H__ */
267

source code of include/gstreamer-1.0/gst/video/video-frame.h