2 * Copyright (C) <2011> Wim Taymans <wim.taymans@gmail.com>
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.
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.
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.
20 #ifndef __GST_VIDEO_INFO_H__
21 #define __GST_VIDEO_INFO_H__
24 #include <gst/video/video-format.h>
25 #include <gst/video/video-color.h>
29 #include <gst/video/video-enumtypes.h>
31 typedef struct _GstVideoInfo GstVideoInfo;
34 * GstVideoInterlaceMode:
35 * @GST_VIDEO_INTERLACE_MODE_PROGRESSIVE: all frames are progressive
36 * @GST_VIDEO_INTERLACE_MODE_INTERLEAVED: 2 fields are interleaved in one video
37 * frame. Extra buffer flags describe the field order.
38 * @GST_VIDEO_INTERLACE_MODE_MIXED: frames contains both interlaced and
39 * progressive video, the buffer flags describe the frame and fields.
40 * @GST_VIDEO_INTERLACE_MODE_FIELDS: 2 fields are stored in one buffer, use the
41 * frame ID to get access to the required field. For multiview (the
42 * 'views' property > 1) the fields of view N can be found at frame ID
43 * (N * 2) and (N * 2) + 1.
44 * Each field has only half the amount of lines as noted in the
45 * height property. This mode requires multiple GstVideoMeta metadata
46 * to describe the fields.
48 * The possible values of the #GstVideoInterlaceMode describing the interlace
52 GST_VIDEO_INTERLACE_MODE_PROGRESSIVE = 0,
53 GST_VIDEO_INTERLACE_MODE_INTERLEAVED,
54 GST_VIDEO_INTERLACE_MODE_MIXED,
55 GST_VIDEO_INTERLACE_MODE_FIELDS
56 } GstVideoInterlaceMode;
58 const gchar * gst_video_interlace_mode_to_string (GstVideoInterlaceMode mode);
59 GstVideoInterlaceMode gst_video_interlace_mode_from_string (const gchar * mode);
62 * GstVideoMultiviewMode:
63 * @GST_VIDEO_MULTIVIEW_MODE_NONE: A special value indicating
64 * no multiview information. Used in GstVideoInfo and other places to
65 * indicate that no specific multiview handling has been requested or
66 * provided. This value is never carried on caps.
67 * @GST_VIDEO_MULTIVIEW_MODE_MONO: All frames are monoscopic.
68 * @GST_VIDEO_MULTIVIEW_MODE_LEFT: All frames represent a left-eye view.
69 * @GST_VIDEO_MULTIVIEW_MODE_RIGHT: All frames represent a right-eye view.
70 * @GST_VIDEO_MULTIVIEW_MODE_SIDE_BY_SIDE: Left and right eye views are
71 * provided in the left and right half of the frame respectively.
72 * @GST_VIDEO_MULTIVIEW_MODE_SIDE_BY_SIDE_QUINCUNX: Left and right eye
73 * views are provided in the left and right half of the frame, but
74 * have been sampled using quincunx method, with half-pixel offset
75 * between the 2 views.
76 * @GST_VIDEO_MULTIVIEW_MODE_COLUMN_INTERLEAVED: Alternating vertical
77 * columns of pixels represent the left and right eye view respectively.
78 * @GST_VIDEO_MULTIVIEW_MODE_ROW_INTERLEAVED: Alternating horizontal
79 * rows of pixels represent the left and right eye view respectively.
80 * @GST_VIDEO_MULTIVIEW_MODE_TOP_BOTTOM: The top half of the frame
81 * contains the left eye, and the bottom half the right eye.
82 * @GST_VIDEO_MULTIVIEW_MODE_CHECKERBOARD: Pixels are arranged with
83 * alternating pixels representing left and right eye views in a
84 * checkerboard fashion.
85 * @GST_VIDEO_MULTIVIEW_MODE_FRAME_BY_FRAME: Left and right eye views
86 * are provided in separate frames alternately.
87 * @GST_VIDEO_MULTIVIEW_MODE_MULTIVIEW_FRAME_BY_FRAME: Multiple
88 * independent views are provided in separate frames in sequence.
89 * This method only applies to raw video buffers at the moment.
90 * Specific view identification is via the #GstVideoMultiviewMeta
91 * and #GstVideoMeta(s) on raw video buffers.
92 * @GST_VIDEO_MULTIVIEW_MODE_SEPARATED: Multiple views are
93 * provided as separate #GstMemory framebuffers attached to each
94 * #GstBuffer, described by the #GstVideoMultiviewMeta
95 * and #GstVideoMeta(s)
97 * All possible stereoscopic 3D and multiview representations.
98 * In conjunction with #GstVideoMultiviewFlags, describes how
99 * multiview content is being transported in the stream.
102 GST_VIDEO_MULTIVIEW_MODE_NONE = -1,
103 GST_VIDEO_MULTIVIEW_MODE_MONO = 0,
104 /* Single view modes */
105 GST_VIDEO_MULTIVIEW_MODE_LEFT,
106 GST_VIDEO_MULTIVIEW_MODE_RIGHT,
107 /* Stereo view modes */
108 GST_VIDEO_MULTIVIEW_MODE_SIDE_BY_SIDE,
109 GST_VIDEO_MULTIVIEW_MODE_SIDE_BY_SIDE_QUINCUNX,
110 GST_VIDEO_MULTIVIEW_MODE_COLUMN_INTERLEAVED,
111 GST_VIDEO_MULTIVIEW_MODE_ROW_INTERLEAVED,
112 GST_VIDEO_MULTIVIEW_MODE_TOP_BOTTOM,
113 GST_VIDEO_MULTIVIEW_MODE_CHECKERBOARD,
114 /* Padding for new frame packing modes */
116 GST_VIDEO_MULTIVIEW_MODE_FRAME_BY_FRAME = 32,
117 /* Multivew mode(s) */
118 GST_VIDEO_MULTIVIEW_MODE_MULTIVIEW_FRAME_BY_FRAME,
119 GST_VIDEO_MULTIVIEW_MODE_SEPARATED
120 /* future expansion for annotated modes */
121 } GstVideoMultiviewMode;
124 * GstVideoMultiviewFramePacking:
125 * @GST_VIDEO_MULTIVIEW_FRAME_PACKING_NONE: A special value indicating
126 * no frame packing info.
127 * @GST_VIDEO_MULTIVIEW_FRAME_PACKING_MONO: All frames are monoscopic.
128 * @GST_VIDEO_MULTIVIEW_FRAME_PACKING_LEFT: All frames represent a left-eye view.
129 * @GST_VIDEO_MULTIVIEW_FRAME_PACKING_RIGHT: All frames represent a right-eye view.
130 * @GST_VIDEO_MULTIVIEW_FRAME_PACKING_SIDE_BY_SIDE: Left and right eye views are
131 * provided in the left and right half of the frame respectively.
132 * @GST_VIDEO_MULTIVIEW_FRAME_PACKING_SIDE_BY_SIDE_QUINCUNX: Left and right eye
133 * views are provided in the left and right half of the frame, but
134 * have been sampled using quincunx method, with half-pixel offset
135 * between the 2 views.
136 * @GST_VIDEO_MULTIVIEW_FRAME_PACKING_COLUMN_INTERLEAVED: Alternating vertical
137 * columns of pixels represent the left and right eye view respectively.
138 * @GST_VIDEO_MULTIVIEW_FRAME_PACKING_ROW_INTERLEAVED: Alternating horizontal
139 * rows of pixels represent the left and right eye view respectively.
140 * @GST_VIDEO_MULTIVIEW_FRAME_PACKING_TOP_BOTTOM: The top half of the frame
141 * contains the left eye, and the bottom half the right eye.
142 * @GST_VIDEO_MULTIVIEW_FRAME_PACKING_CHECKERBOARD: Pixels are arranged with
143 * alternating pixels representing left and right eye views in a
144 * checkerboard fashion.
146 * #GstVideoMultiviewFramePacking represents the subset of #GstVideoMultiviewMode
147 * values that can be applied to any video frame without needing extra metadata.
148 * It can be used by elements that provide a property to override the
149 * multiview interpretation of a video stream when the video doesn't contain
152 * This enum is used (for example) on playbin, to re-interpret a played
153 * video stream as a stereoscopic video. The individual enum values are
154 * equivalent to and have the same value as the matching #GstVideoMultiviewMode.
158 GST_VIDEO_MULTIVIEW_FRAME_PACKING_NONE = GST_VIDEO_MULTIVIEW_MODE_NONE,
159 GST_VIDEO_MULTIVIEW_FRAME_PACKING_MONO = GST_VIDEO_MULTIVIEW_MODE_MONO,
160 GST_VIDEO_MULTIVIEW_FRAME_PACKING_LEFT = GST_VIDEO_MULTIVIEW_MODE_LEFT,
161 GST_VIDEO_MULTIVIEW_FRAME_PACKING_RIGHT = GST_VIDEO_MULTIVIEW_MODE_RIGHT,
162 GST_VIDEO_MULTIVIEW_FRAME_PACKING_SIDE_BY_SIDE = GST_VIDEO_MULTIVIEW_MODE_SIDE_BY_SIDE,
163 GST_VIDEO_MULTIVIEW_FRAME_PACKING_SIDE_BY_SIDE_QUINCUNX = GST_VIDEO_MULTIVIEW_MODE_SIDE_BY_SIDE_QUINCUNX,
164 GST_VIDEO_MULTIVIEW_FRAME_PACKING_COLUMN_INTERLEAVED = GST_VIDEO_MULTIVIEW_MODE_COLUMN_INTERLEAVED,
165 GST_VIDEO_MULTIVIEW_FRAME_PACKING_ROW_INTERLEAVED = GST_VIDEO_MULTIVIEW_MODE_ROW_INTERLEAVED,
166 GST_VIDEO_MULTIVIEW_FRAME_PACKING_TOP_BOTTOM = GST_VIDEO_MULTIVIEW_MODE_TOP_BOTTOM,
167 GST_VIDEO_MULTIVIEW_FRAME_PACKING_CHECKERBOARD = GST_VIDEO_MULTIVIEW_MODE_CHECKERBOARD
168 } GstVideoMultiviewFramePacking;
170 #define GST_VIDEO_MULTIVIEW_MAX_FRAME_PACKING GST_VIDEO_MULTIVIEW_FRAME_PACKING_CHECKERBOARD
173 * GstVideoMultiviewFlags:
174 * @GST_VIDEO_MULTIVIEW_FLAGS_NONE: No flags
175 * @GST_VIDEO_MULTIVIEW_FLAGS_RIGHT_VIEW_FIRST: For stereo streams, the
176 * normal arrangement of left and right views is reversed.
177 * @GST_VIDEO_MULTIVIEW_FLAGS_LEFT_FLIPPED: The left view is vertically
179 * @GST_VIDEO_MULTIVIEW_FLAGS_LEFT_FLOPPED: The left view is horizontally
181 * @GST_VIDEO_MULTIVIEW_FLAGS_RIGHT_FLIPPED: The right view is
182 * vertically mirrored.
183 * @GST_VIDEO_MULTIVIEW_FLAGS_RIGHT_FLOPPED: The right view is
184 * horizontally mirrored.
185 * @GST_VIDEO_MULTIVIEW_FLAGS_HALF_ASPECT: For frame-packed
186 * multiview modes, indicates that the individual
187 * views have been encoded with half the true width or height
188 * and should be scaled back up for display. This flag
189 * is used for overriding input layout interpretation
190 * by adjusting pixel-aspect-ratio.
191 * For side-by-side, column interleaved or checkerboard packings, the
192 * pixel width will be doubled. For row interleaved and top-bottom
193 * encodings, pixel height will be doubled.
194 * @GST_VIDEO_MULTIVIEW_FLAGS_MIXED_MONO: The video stream contains both
195 * mono and multiview portions, signalled on each buffer by the
196 * absence or presence of the @GST_VIDEO_BUFFER_FLAG_MULTIPLE_VIEW
199 * GstVideoMultiviewFlags are used to indicate extra properties of a
200 * stereo/multiview stream beyond the frame layout and buffer mapping
201 * that is conveyed in the #GstMultiviewMode.
204 GST_VIDEO_MULTIVIEW_FLAGS_NONE = 0,
205 GST_VIDEO_MULTIVIEW_FLAGS_RIGHT_VIEW_FIRST = (1 << 0),
206 GST_VIDEO_MULTIVIEW_FLAGS_LEFT_FLIPPED = (1 << 1),
207 GST_VIDEO_MULTIVIEW_FLAGS_LEFT_FLOPPED = (1 << 2),
208 GST_VIDEO_MULTIVIEW_FLAGS_RIGHT_FLIPPED = (1 << 3),
209 GST_VIDEO_MULTIVIEW_FLAGS_RIGHT_FLOPPED = (1 << 4),
210 GST_VIDEO_MULTIVIEW_FLAGS_HALF_ASPECT = (1 << 14),
211 GST_VIDEO_MULTIVIEW_FLAGS_MIXED_MONO = (1 << 15)
212 } GstVideoMultiviewFlags;
216 * @GST_VIDEO_FLAG_NONE: no flags
217 * @GST_VIDEO_FLAG_VARIABLE_FPS: a variable fps is selected, fps_n and fps_d
218 * denote the maximum fps of the video
219 * @GST_VIDEO_FLAG_PREMULTIPLIED_ALPHA: Each color has been scaled by the alpha
225 GST_VIDEO_FLAG_NONE = 0,
226 GST_VIDEO_FLAG_VARIABLE_FPS = (1 << 0),
227 GST_VIDEO_FLAG_PREMULTIPLIED_ALPHA = (1 << 1)
232 * @finfo: the format info of the video
233 * @interlace_mode: the interlace mode
234 * @flags: additional video flags
235 * @width: the width of the video
236 * @height: the height of the video
237 * @views: the number of views for multiview video
238 * @size: the default size of one frame
239 * @chroma_site: a #GstVideoChromaSite.
240 * @colorimetry: the colorimetry info
241 * @par_n: the pixel-aspect-ratio numerator
242 * @par_d: the pixel-aspect-ratio demnominator
243 * @fps_n: the framerate numerator
244 * @fps_d: the framerate demnominator
245 * @offset: offsets of the planes
246 * @stride: strides of the planes
247 * @multiview_mode: delivery mode for multiple views. (Since 1.6)
248 * @multiview_flags: flags for multiple views configuration (Since 1.6)
250 * Information describing image properties. This information can be filled
251 * in from GstCaps with gst_video_info_from_caps(). The information is also used
252 * to store the specific video info when mapping a video frame with
253 * gst_video_frame_map().
255 * Use the provided macros to access the info in this structure.
257 struct _GstVideoInfo {
258 const GstVideoFormatInfo *finfo;
260 GstVideoInterlaceMode interlace_mode;
267 GstVideoChromaSite chroma_site;
268 GstVideoColorimetry colorimetry;
275 gsize offset[GST_VIDEO_MAX_PLANES];
276 gint stride[GST_VIDEO_MAX_PLANES];
278 /* Union preserves padded struct size for backwards compat
279 * Consumer code should use the accessor macros for fields */
282 GstVideoMultiviewMode multiview_mode;
283 GstVideoMultiviewFlags multiview_flags;
286 gpointer _gst_reserved[GST_PADDING];
291 #define GST_VIDEO_INFO_FORMAT(i) (GST_VIDEO_FORMAT_INFO_FORMAT((i)->finfo))
292 #define GST_VIDEO_INFO_NAME(i) (GST_VIDEO_FORMAT_INFO_NAME((i)->finfo))
293 #define GST_VIDEO_INFO_IS_YUV(i) (GST_VIDEO_FORMAT_INFO_IS_YUV((i)->finfo))
294 #define GST_VIDEO_INFO_IS_RGB(i) (GST_VIDEO_FORMAT_INFO_IS_RGB((i)->finfo))
295 #define GST_VIDEO_INFO_IS_GRAY(i) (GST_VIDEO_FORMAT_INFO_IS_GRAY((i)->finfo))
296 #define GST_VIDEO_INFO_HAS_ALPHA(i) (GST_VIDEO_FORMAT_INFO_HAS_ALPHA((i)->finfo))
298 #define GST_VIDEO_INFO_INTERLACE_MODE(i) ((i)->interlace_mode)
299 #define GST_VIDEO_INFO_IS_INTERLACED(i) ((i)->interlace_mode != GST_VIDEO_INTERLACE_MODE_PROGRESSIVE)
300 #define GST_VIDEO_INFO_FLAGS(i) ((i)->flags)
301 #define GST_VIDEO_INFO_WIDTH(i) ((i)->width)
302 #define GST_VIDEO_INFO_HEIGHT(i) ((i)->height)
303 #define GST_VIDEO_INFO_SIZE(i) ((i)->size)
304 #define GST_VIDEO_INFO_VIEWS(i) ((i)->views)
305 #define GST_VIDEO_INFO_PAR_N(i) ((i)->par_n)
306 #define GST_VIDEO_INFO_PAR_D(i) ((i)->par_d)
307 #define GST_VIDEO_INFO_FPS_N(i) ((i)->fps_n)
308 #define GST_VIDEO_INFO_FPS_D(i) ((i)->fps_d)
310 #define GST_VIDEO_INFO_COLORIMETRY(i) ((i)->colorimetry)
311 #define GST_VIDEO_INFO_CHROMA_SITE(i) ((i)->chroma_site)
313 #define GST_VIDEO_INFO_MULTIVIEW_MODE(i) ((i)->ABI.abi.multiview_mode)
314 #define GST_VIDEO_INFO_MULTIVIEW_FLAGS(i) ((i)->ABI.abi.multiview_flags)
316 /* dealing with GstVideoInfo flags */
317 #define GST_VIDEO_INFO_FLAG_IS_SET(i,flag) ((GST_VIDEO_INFO_FLAGS(i) & (flag)) == (flag))
318 #define GST_VIDEO_INFO_FLAG_SET(i,flag) (GST_VIDEO_INFO_FLAGS(i) |= (flag))
319 #define GST_VIDEO_INFO_FLAG_UNSET(i,flag) (GST_VIDEO_INFO_FLAGS(i) &= ~(flag))
321 /* dealing with planes */
322 #define GST_VIDEO_INFO_N_PLANES(i) (GST_VIDEO_FORMAT_INFO_N_PLANES((i)->finfo))
323 #define GST_VIDEO_INFO_PLANE_OFFSET(i,p) ((i)->offset[p])
324 #define GST_VIDEO_INFO_PLANE_STRIDE(i,p) ((i)->stride[p])
326 /* dealing with components */
327 #define GST_VIDEO_INFO_N_COMPONENTS(i) GST_VIDEO_FORMAT_INFO_N_COMPONENTS((i)->finfo)
328 #define GST_VIDEO_INFO_COMP_DEPTH(i,c) GST_VIDEO_FORMAT_INFO_DEPTH((i)->finfo,(c))
329 #define GST_VIDEO_INFO_COMP_DATA(i,d,c) GST_VIDEO_FORMAT_INFO_DATA((i)->finfo,d,(c))
330 #define GST_VIDEO_INFO_COMP_OFFSET(i,c) GST_VIDEO_FORMAT_INFO_OFFSET((i)->finfo,(i)->offset,(c))
331 #define GST_VIDEO_INFO_COMP_STRIDE(i,c) GST_VIDEO_FORMAT_INFO_STRIDE((i)->finfo,(i)->stride,(c))
332 #define GST_VIDEO_INFO_COMP_WIDTH(i,c) GST_VIDEO_FORMAT_INFO_SCALE_WIDTH((i)->finfo,(c),(i)->width)
333 #define GST_VIDEO_INFO_COMP_HEIGHT(i,c) GST_VIDEO_FORMAT_INFO_SCALE_HEIGHT((i)->finfo,(c),(i)->height)
334 #define GST_VIDEO_INFO_COMP_PLANE(i,c) GST_VIDEO_FORMAT_INFO_PLANE((i)->finfo,(c))
335 #define GST_VIDEO_INFO_COMP_PSTRIDE(i,c) GST_VIDEO_FORMAT_INFO_PSTRIDE((i)->finfo,(c))
336 #define GST_VIDEO_INFO_COMP_POFFSET(i,c) GST_VIDEO_FORMAT_INFO_POFFSET((i)->finfo,(c))
338 void gst_video_info_init (GstVideoInfo *info);
340 void gst_video_info_set_format (GstVideoInfo *info, GstVideoFormat format,
341 guint width, guint height);
343 gboolean gst_video_info_from_caps (GstVideoInfo *info, const GstCaps * caps);
345 GstCaps * gst_video_info_to_caps (GstVideoInfo *info);
347 gboolean gst_video_info_convert (GstVideoInfo *info,
348 GstFormat src_format,
350 GstFormat dest_format,
352 gboolean gst_video_info_is_equal (const GstVideoInfo *info,
353 const GstVideoInfo *other);
355 #include <gst/video/video.h>
357 void gst_video_info_align (GstVideoInfo * info, GstVideoAlignment * align);
362 #endif /* __GST_VIDEO_INFO_H__ */