xref: /third_party/ffmpeg/libavutil/stereo3d.h (revision cabdff1a) 
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 * 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 */
51enum 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 */
147enum 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 */
176typedef 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 */
199AVStereo3D *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 */
208AVStereo3D *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 */
217const 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 */
226int av_stereo3d_from_name(const char *name);
227
228/**
229 * @}
230 * @}
231 */
232
233#endif /* AVUTIL_STEREO3D_H */
234