FFmpeg
stereo3d.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2013 Vittorio Giovara <vittorio.giovara@gmail.com>
3  *
4  * This file is part of FFmpeg.
5  *
6  * FFmpeg is free software; you can redistribute it and/or
7  * modify it under the terms of the GNU Lesser General Public
8  * License as published by the Free Software Foundation; either
9  * version 2.1 of the License, or (at your option) any later version.
10  *
11  * FFmpeg is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14  * Lesser General Public License for more details.
15  *
16  * You should have received a copy of the GNU Lesser General Public
17  * License along with FFmpeg; if not, write to the Free Software
18  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
19  */
20 
21 /**
22  * @file
23  * @ingroup lavu_video_stereo3d
24  * Stereoscopic video
25  */
26 
27 #ifndef AVUTIL_STEREO3D_H
28 #define AVUTIL_STEREO3D_H
29 
30 #include <stdint.h>
31 
32 #include "frame.h"
33 
34 /**
35  * @defgroup lavu_video_stereo3d Stereo3D types and functions
36  * @ingroup lavu_video
37  *
38  * A stereoscopic video file consists in multiple views embedded in a single
39  * frame, usually describing two views of a scene. This file describes all
40  * possible codec-independent view arrangements.
41  *
42  * @{
43  */
44 
45 /**
46  * List of possible 3D Types
47  */
49  /**
50  * Video is not stereoscopic (and metadata has to be there).
51  */
53 
54  /**
55  * Views are next to each other.
56  *
57  * @code{.unparsed}
58  * LLLLRRRR
59  * LLLLRRRR
60  * LLLLRRRR
61  * ...
62  * @endcode
63  */
65 
66  /**
67  * Views are on top of each other.
68  *
69  * @code{.unparsed}
70  * LLLLLLLL
71  * LLLLLLLL
72  * RRRRRRRR
73  * RRRRRRRR
74  * @endcode
75  */
77 
78  /**
79  * Views are alternated temporally.
80  *
81  * @code{.unparsed}
82  * frame0 frame1 frame2 ...
83  * LLLLLLLL RRRRRRRR LLLLLLLL
84  * LLLLLLLL RRRRRRRR LLLLLLLL
85  * LLLLLLLL RRRRRRRR LLLLLLLL
86  * ... ... ...
87  * @endcode
88  */
90 
91  /**
92  * Views are packed in a checkerboard-like structure per pixel.
93  *
94  * @code{.unparsed}
95  * LRLRLRLR
96  * RLRLRLRL
97  * LRLRLRLR
98  * ...
99  * @endcode
100  */
102 
103  /**
104  * Views are next to each other, but when upscaling
105  * apply a checkerboard pattern.
106  *
107  * @code{.unparsed}
108  * LLLLRRRR L L L L R R R R
109  * LLLLRRRR => L L L L R R R R
110  * LLLLRRRR L L L L R R R R
111  * LLLLRRRR L L L L R R R R
112  * @endcode
113  */
115 
116  /**
117  * Views are packed per line, as if interlaced.
118  *
119  * @code{.unparsed}
120  * LLLLLLLL
121  * RRRRRRRR
122  * LLLLLLLL
123  * ...
124  * @endcode
125  */
127 
128  /**
129  * Views are packed per column.
130  *
131  * @code{.unparsed}
132  * LRLRLRLR
133  * LRLRLRLR
134  * LRLRLRLR
135  * ...
136  * @endcode
137  */
139 
140  /**
141  * Video is stereoscopic but the packing is unspecified.
142  */
144 };
145 
146 /**
147  * List of possible view types.
148  */
150  /**
151  * Frame contains two packed views.
152  */
154 
155  /**
156  * Frame contains only the left view.
157  */
159 
160  /**
161  * Frame contains only the right view.
162  */
164 
165  /**
166  * Content is unspecified.
167  */
169 };
170 
171 /**
172  * List of possible primary eyes.
173  */
175  /**
176  * Neither eye.
177  */
179 
180  /**
181  * Left eye.
182  */
184 
185  /**
186  * Right eye
187  */
189 };
190 
191 /**
192  * Inverted views, Right/Bottom represents the left view.
193  */
194 #define AV_STEREO3D_FLAG_INVERT (1 << 0)
195 
196 /**
197  * Stereo 3D type: this structure describes how two videos are packed
198  * within a single video surface, with additional information as needed.
199  *
200  * @note The struct must be allocated with av_stereo3d_alloc() and
201  * its size is not a part of the public ABI.
202  */
203 typedef struct AVStereo3D {
204  /**
205  * How views are packed within the video.
206  */
208 
209  /**
210  * Additional information about the frame packing.
211  */
212  int flags;
213 
214  /**
215  * Determines which views are packed.
216  */
218 
219  /**
220  * Which eye is the primary eye when rendering in 2D.
221  */
223 
224  /**
225  * The distance between the centres of the lenses of the camera system,
226  * in micrometers. Zero if unset.
227  */
228  uint32_t baseline;
229 
230  /**
231  * Relative shift of the left and right images, which changes the zero parallax plane.
232  * Range is -1.0 to 1.0. Zero if unset.
233  */
235 
236  /**
237  * Horizontal field of view, in degrees. Zero if unset.
238  */
240 } AVStereo3D;
241 
242 /**
243  * Allocate an AVStereo3D structure and set its fields to default values.
244  * The resulting struct can be freed using av_freep().
245  *
246  * @return An AVStereo3D filled with default values or NULL on failure.
247  */
249 
250 /**
251  * Allocate an AVStereo3D structure and set its fields to default values.
252  * The resulting struct can be freed using av_freep().
253  *
254  * @return An AVStereo3D filled with default values or NULL on failure.
255  */
257 
258 /**
259  * Allocate a complete AVFrameSideData and add it to the frame.
260  *
261  * @param frame The frame which side data is added to.
262  *
263  * @return The AVStereo3D structure to be filled by caller.
264  */
266 
267 /**
268  * Provide a human-readable name of a given stereo3d type.
269  *
270  * @param type The input stereo3d type value.
271  *
272  * @return The name of the stereo3d value, or "unknown".
273  */
274 const char *av_stereo3d_type_name(unsigned int type);
275 
276 /**
277  * Get the AVStereo3DType form a human-readable name.
278  *
279  * @param name The input string.
280  *
281  * @return The AVStereo3DType value, or -1 if not found.
282  */
283 int av_stereo3d_from_name(const char *name);
284 
285 /**
286  * Provide a human-readable name of a given stereo3d view.
287  *
288  * @param type The input stereo3d view value.
289  *
290  * @return The name of the stereo3d view value, or "unknown".
291  */
292 const char *av_stereo3d_view_name(unsigned int view);
293 
294 /**
295  * Get the AVStereo3DView form a human-readable name.
296  *
297  * @param name The input string.
298  *
299  * @return The AVStereo3DView value, or -1 if not found.
300  */
301 int av_stereo3d_view_from_name(const char *name);
302 
303 /**
304  * Provide a human-readable name of a given stereo3d primary eye.
305  *
306  * @param type The input stereo3d primary eye value.
307  *
308  * @return The name of the stereo3d primary eye value, or "unknown".
309  */
310 const char *av_stereo3d_primary_eye_name(unsigned int eye);
311 
312 /**
313  * Get the AVStereo3DPrimaryEye form a human-readable name.
314  *
315  * @param name The input string.
316  *
317  * @return The AVStereo3DPrimaryEye value, or -1 if not found.
318  */
319 int av_stereo3d_primary_eye_from_name(const char *name);
320 
321 /**
322  * @}
323  */
324 
325 #endif /* AVUTIL_STEREO3D_H */
AV_PRIMARY_EYE_RIGHT
@ AV_PRIMARY_EYE_RIGHT
Right eye.
Definition: stereo3d.h:188
name
it s the only field you need to keep assuming you have a context There is some magic you don t need to care about around this just let it vf default minimum maximum flags name is the option name
Definition: writing_filters.txt:88
AV_STEREO3D_VIEW_LEFT
@ AV_STEREO3D_VIEW_LEFT
Frame contains only the left view.
Definition: stereo3d.h:158
AV_STEREO3D_SIDEBYSIDE_QUINCUNX
@ AV_STEREO3D_SIDEBYSIDE_QUINCUNX
Views are next to each other, but when upscaling apply a checkerboard pattern.
Definition: stereo3d.h:114
av_stereo3d_view_from_name
int av_stereo3d_view_from_name(const char *name)
Get the AVStereo3DView form a human-readable name.
Definition: stereo3d.c:121
AVFrame
This structure describes decoded (raw) audio or video data.
Definition: frame.h:389
AVStereo3D::baseline
uint32_t baseline
The distance between the centres of the lenses of the camera system, in micrometers.
Definition: stereo3d.h:228
AV_STEREO3D_VIEW_RIGHT
@ AV_STEREO3D_VIEW_RIGHT
Frame contains only the right view.
Definition: stereo3d.h:163
AV_STEREO3D_VIEW_UNSPEC
@ AV_STEREO3D_VIEW_UNSPEC
Content is unspecified.
Definition: stereo3d.h:168
AV_STEREO3D_UNSPEC
@ AV_STEREO3D_UNSPEC
Video is stereoscopic but the packing is unspecified.
Definition: stereo3d.h:143
AVStereo3D::horizontal_field_of_view
AVRational horizontal_field_of_view
Horizontal field of view, in degrees.
Definition: stereo3d.h:239
AV_STEREO3D_SIDEBYSIDE
@ AV_STEREO3D_SIDEBYSIDE
Views are next to each other.
Definition: stereo3d.h:64
AV_STEREO3D_VIEW_PACKED
@ AV_STEREO3D_VIEW_PACKED
Frame contains two packed views.
Definition: stereo3d.h:153
AV_STEREO3D_2D
@ AV_STEREO3D_2D
Video is not stereoscopic (and metadata has to be there).
Definition: stereo3d.h:52
type
it s the only field you need to keep assuming you have a context There is some magic you don t need to care about around this just let it vf type
Definition: writing_filters.txt:86
av_stereo3d_view_name
const char * av_stereo3d_view_name(unsigned int view)
Provide a human-readable name of a given stereo3d view.
Definition: stereo3d.c:113
AV_STEREO3D_FRAMESEQUENCE
@ AV_STEREO3D_FRAMESEQUENCE
Views are alternated temporally.
Definition: stereo3d.h:89
AV_STEREO3D_LINES
@ AV_STEREO3D_LINES
Views are packed per line, as if interlaced.
Definition: stereo3d.h:126
av_stereo3d_primary_eye_from_name
int av_stereo3d_primary_eye_from_name(const char *name)
Get the AVStereo3DPrimaryEye form a human-readable name.
Definition: stereo3d.c:141
AVStereo3D::flags
int flags
Additional information about the frame packing.
Definition: stereo3d.h:212
AVRational
Rational number (pair of numerator and denominator).
Definition: rational.h:58
AV_PRIMARY_EYE_LEFT
@ AV_PRIMARY_EYE_LEFT
Left eye.
Definition: stereo3d.h:183
AVStereo3D::horizontal_disparity_adjustment
AVRational horizontal_disparity_adjustment
Relative shift of the left and right images, which changes the zero parallax plane.
Definition: stereo3d.h:234
av_stereo3d_alloc_size
AVStereo3D * av_stereo3d_alloc_size(size_t *size)
Allocate an AVStereo3D structure and set its fields to default values.
Definition: stereo3d.c:40
AVStereo3D::primary_eye
enum AVStereo3DPrimaryEye primary_eye
Which eye is the primary eye when rendering in 2D.
Definition: stereo3d.h:222
AV_STEREO3D_CHECKERBOARD
@ AV_STEREO3D_CHECKERBOARD
Views are packed in a checkerboard-like structure per pixel.
Definition: stereo3d.h:101
av_stereo3d_primary_eye_name
const char * av_stereo3d_primary_eye_name(unsigned int eye)
Provide a human-readable name of a given stereo3d primary eye.
Definition: stereo3d.c:133
size
int size
Definition: twinvq_data.h:10344
frame.h
AV_PRIMARY_EYE_NONE
@ AV_PRIMARY_EYE_NONE
Neither eye.
Definition: stereo3d.h:178
AVStereo3DPrimaryEye
AVStereo3DPrimaryEye
List of possible primary eyes.
Definition: stereo3d.h:174
AV_STEREO3D_TOPBOTTOM
@ AV_STEREO3D_TOPBOTTOM
Views are on top of each other.
Definition: stereo3d.h:76
av_stereo3d_alloc
AVStereo3D * av_stereo3d_alloc(void)
Allocate an AVStereo3D structure and set its fields to default values.
Definition: stereo3d.c:35
frame
these buffered frames must be flushed immediately if a new input produces new the filter must not call request_frame to get more It must just process the frame or queue it The task of requesting more frames is left to the filter s request_frame method or the application If a filter has several the filter must be ready for frames arriving randomly on any input any filter with several inputs will most likely require some kind of queuing mechanism It is perfectly acceptable to have a limited queue and to drop frames when the inputs are too unbalanced request_frame For filters that do not use the this method is called when a frame is wanted on an output For a it should directly call filter_frame on the corresponding output For a if there are queued frames already one of these frames should be pushed If the filter should request a frame on one of its repeatedly until at least one frame has been pushed Return or at least make progress towards producing a frame
Definition: filter_design.txt:264
AV_STEREO3D_COLUMNS
@ AV_STEREO3D_COLUMNS
Views are packed per column.
Definition: stereo3d.h:138
AVStereo3D::type
enum AVStereo3DType type
How views are packed within the video.
Definition: stereo3d.h:207
av_stereo3d_create_side_data
AVStereo3D * av_stereo3d_create_side_data(AVFrame *frame)
Allocate a complete AVFrameSideData and add it to the frame.
Definition: stereo3d.c:54
AVStereo3D::view
enum AVStereo3DView view
Determines which views are packed.
Definition: stereo3d.h:217
AVStereo3DView
AVStereo3DView
List of possible view types.
Definition: stereo3d.h:149
AVStereo3DType
AVStereo3DType
List of possible 3D Types.
Definition: stereo3d.h:48
av_stereo3d_type_name
const char * av_stereo3d_type_name(unsigned int type)
Provide a human-readable name of a given stereo3d type.
Definition: stereo3d.c:93
AVStereo3D
Stereo 3D type: this structure describes how two videos are packed within a single video surface,...
Definition: stereo3d.h:203
av_stereo3d_from_name
int av_stereo3d_from_name(const char *name)
Get the AVStereo3DType form a human-readable name.
Definition: stereo3d.c:101