libavutil/stereo3d.h

   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 */