stereo3d.h (7446B)
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 */ 48 enum AVStereo3DType { 49 /** 50 * Video is not stereoscopic (and metadata has to be there). 51 */ 52 AV_STEREO3D_2D, 53 54 /** 55 * Views are next to each other. 56 * 57 * @code{.unparsed} 58 * LLLLRRRR 59 * LLLLRRRR 60 * LLLLRRRR 61 * ... 62 * @endcode 63 */ 64 AV_STEREO3D_SIDEBYSIDE, 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 */ 76 AV_STEREO3D_TOPBOTTOM, 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 */ 89 AV_STEREO3D_FRAMESEQUENCE, 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 */ 101 AV_STEREO3D_CHECKERBOARD, 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 */ 114 AV_STEREO3D_SIDEBYSIDE_QUINCUNX, 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 */ 126 AV_STEREO3D_LINES, 127 128 /** 129 * Views are packed per column. 130 * 131 * @code{.unparsed} 132 * LRLRLRLR 133 * LRLRLRLR 134 * LRLRLRLR 135 * ... 136 * @endcode 137 */ 138 AV_STEREO3D_COLUMNS, 139 140 /** 141 * Video is stereoscopic but the packing is unspecified. 142 */ 143 AV_STEREO3D_UNSPEC, 144 }; 145 146 /** 147 * List of possible view types. 148 */ 149 enum AVStereo3DView { 150 /** 151 * Frame contains two packed views. 152 */ 153 AV_STEREO3D_VIEW_PACKED, 154 155 /** 156 * Frame contains only the left view. 157 */ 158 AV_STEREO3D_VIEW_LEFT, 159 160 /** 161 * Frame contains only the right view. 162 */ 163 AV_STEREO3D_VIEW_RIGHT, 164 165 /** 166 * Content is unspecified. 167 */ 168 AV_STEREO3D_VIEW_UNSPEC, 169 }; 170 171 /** 172 * List of possible primary eyes. 173 */ 174 enum AVStereo3DPrimaryEye { 175 /** 176 * Neither eye. 177 */ 178 AV_PRIMARY_EYE_NONE, 179 180 /** 181 * Left eye. 182 */ 183 AV_PRIMARY_EYE_LEFT, 184 185 /** 186 * Right eye 187 */ 188 AV_PRIMARY_EYE_RIGHT, 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 */ 207 enum AVStereo3DType type; 208 209 /** 210 * Additional information about the frame packing. 211 */ 212 int flags; 213 214 /** 215 * Determines which views are packed. 216 */ 217 enum AVStereo3DView view; 218 219 /** 220 * Which eye is the primary eye when rendering in 2D. 221 */ 222 enum AVStereo3DPrimaryEye primary_eye; 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 */ 234 AVRational horizontal_disparity_adjustment; 235 236 /** 237 * Horizontal field of view, in degrees. Zero if unset. 238 */ 239 AVRational horizontal_field_of_view; 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 */ 248 AVStereo3D *av_stereo3d_alloc(void); 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 */ 256 AVStereo3D *av_stereo3d_alloc_size(size_t *size); 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 */ 265 AVStereo3D *av_stereo3d_create_side_data(AVFrame *frame); 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 */