stereo3d: Support view type for frame sequence type
[libav.git] / libavutil / stereo3d.h
1 /*
2 * Copyright (c) 2013 Vittorio Giovara <vittorio.giovara@gmail.com>
3 *
4 * This file is part of Libav.
5 *
6 * Libav 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 * Libav 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 Libav; 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 * Stereoscopic video
24 */
25
26 #ifndef AVUTIL_STEREO3D_H
27 #define AVUTIL_STEREO3D_H
28
29 #include <stdint.h>
30
31 #include "frame.h"
32
33 /**
34 * @addtogroup lavu_video
35 * @{
36 *
37 * @defgroup lavu_video_stereo3d Stereo3D types and functions
38 * @{
39 */
40
41 /**
42 * @addtogroup lavu_video_stereo3d
43 * A stereoscopic video file consists in multiple views embedded in a single
44 * frame, usually describing two views of a scene. This file describes all
45 * possible codec-independent view arrangements.
46 * */
47
48 /**
49 * List of possible 3D Types
50 */
51 enum AVStereo3DType {
52 /**
53 * Video is not stereoscopic (and metadata has to be there).
54 */
55 AV_STEREO3D_2D,
56
57 /**
58 * Views are next to each other.
59 *
60 * @code{.unparsed}
61 * LLLLRRRR
62 * LLLLRRRR
63 * LLLLRRRR
64 * ...
65 * @endcode
66 */
67 AV_STEREO3D_SIDEBYSIDE,
68
69 /**
70 * Views are on top of each other.
71 *
72 * @code{.unparsed}
73 * LLLLLLLL
74 * LLLLLLLL
75 * RRRRRRRR
76 * RRRRRRRR
77 * @endcode
78 */
79 AV_STEREO3D_TOPBOTTOM,
80
81 /**
82 * Views are alternated temporally.
83 *
84 * @code{.unparsed}
85 * frame0 frame1 frame2 ...
86 * LLLLLLLL RRRRRRRR LLLLLLLL
87 * LLLLLLLL RRRRRRRR LLLLLLLL
88 * LLLLLLLL RRRRRRRR LLLLLLLL
89 * ... ... ...
90 * @endcode
91 */
92 AV_STEREO3D_FRAMESEQUENCE,
93
94 /**
95 * Views are packed in a checkerboard-like structure per pixel.
96 *
97 * @code{.unparsed}
98 * LRLRLRLR
99 * RLRLRLRL
100 * LRLRLRLR
101 * ...
102 * @endcode
103 */
104 AV_STEREO3D_CHECKERBOARD,
105
106 /**
107 * Views are next to each other, but when upscaling
108 * apply a checkerboard pattern.
109 *
110 * @code{.unparsed}
111 * LLLLRRRR L L L L R R R R
112 * LLLLRRRR => L L L L R R R R
113 * LLLLRRRR L L L L R R R R
114 * LLLLRRRR L L L L R R R R
115 * @endcode
116 */
117 AV_STEREO3D_SIDEBYSIDE_QUINCUNX,
118
119 /**
120 * Views are packed per line, as if interlaced.
121 *
122 * @code{.unparsed}
123 * LLLLLLLL
124 * RRRRRRRR
125 * LLLLLLLL
126 * ...
127 * @endcode
128 */
129 AV_STEREO3D_LINES,
130
131 /**
132 * Views are packed per column.
133 *
134 * @code{.unparsed}
135 * LRLRLRLR
136 * LRLRLRLR
137 * LRLRLRLR
138 * ...
139 * @endcode
140 */
141 AV_STEREO3D_COLUMNS,
142 };
143
144 /**
145 * List of possible view types.
146 */
147 enum AVStereo3DView {
148 /**
149 * Frame contains two packed views.
150 */
151 AV_STEREO3D_VIEW_PACKED,
152
153 /**
154 * Frame contains only the left view.
155 */
156 AV_STEREO3D_VIEW_LEFT,
157
158 /**
159 * Frame contains only the right view.
160 */
161 AV_STEREO3D_VIEW_RIGHT,
162 };
163
164 /**
165 * Inverted views, Right/Bottom represents the left view.
166 */
167 #define AV_STEREO3D_FLAG_INVERT (1 << 0)
168
169 /**
170 * Stereo 3D type: this structure describes how two videos are packed
171 * within a single video surface, with additional information as needed.
172 *
173 * @note The struct must be allocated with av_stereo3d_alloc() and
174 * its size is not a part of the public ABI.
175 */
176 typedef struct AVStereo3D {
177 /**
178 * How views are packed within the video.
179 */
180 enum AVStereo3DType type;
181
182 /**
183 * Additional information about the frame packing.
184 */
185 int flags;
186
187 /**
188 * Determines which views are packed.
189 */
190 enum AVStereo3DView view;
191 } AVStereo3D;
192
193 /**
194 * Allocate an AVStereo3D structure and set its fields to default values.
195 * The resulting struct can be freed using av_freep().
196 *
197 * @return An AVStereo3D filled with default values or NULL on failure.
198 */
199 AVStereo3D *av_stereo3d_alloc(void);
200
201 /**
202 * Allocate a complete AVFrameSideData and add it to the frame.
203 *
204 * @param frame The frame which side data is added to.
205 *
206 * @return The AVStereo3D structure to be filled by caller.
207 */
208 AVStereo3D *av_stereo3d_create_side_data(AVFrame *frame);
209
210 /**
211 * Provide a human-readable name of a given stereo3d type.
212 *
213 * @param type The input stereo3d type value.
214 *
215 * @return The name of the stereo3d value, or "unknown".
216 */
217 const char *av_stereo3d_type_name(unsigned int type);
218
219 /**
220 * Get the AVStereo3DType form a human-readable name.
221 *
222 * @param name The input string.
223 *
224 * @return The AVStereo3DType value, or -1 if not found.
225 */
226 int av_stereo3d_from_name(const char *name);
227
228 /**
229 * @}
230 * @}
231 */
232
233 #endif /* AVUTIL_STEREO3D_H */