git.sesse.net Git - ffmpeg/blob - libavutil/spherical.h

   1 /*
   2  * Copyright (c) 2016 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  * Spherical video
  24  */
  25
  26 #ifndef AVUTIL_SPHERICAL_H
  27 #define AVUTIL_SPHERICAL_H
  28
  29 #include <stddef.h>
  30 #include <stdint.h>
  31
  32 /**
  33  * @addtogroup lavu_video
  34  * @{
  35  *
  36  * @defgroup lavu_video_spherical Spherical video mapping
  37  * @{
  38  */
  39
  40 /**
  41  * @addtogroup lavu_video_spherical
  42  * A spherical video file contains surfaces that need to be mapped onto a
  43  * sphere. Depending on how the frame was converted, a different distortion
  44  * transformation or surface recomposition function needs to be applied before
  45  * the video should be mapped and displayed.
  46  */
  47
  48 /**
  49  * Projection of the video surface(s) on a sphere.
  50  */
  51 enum AVSphericalProjection {
  52     /**
  53      * Video represents a sphere mapped on a flat surface using
  54      * equirectangular projection.
  55      */
  56     AV_SPHERICAL_EQUIRECTANGULAR,
  57
  58     /**
  59      * Video frame is split into 6 faces of a cube, and arranged on a
  60      * 3x2 layout. Faces are oriented upwards for the front, left, right,
  61      * and back faces. The up face is oriented so the top of the face is
  62      * forwards and the down face is oriented so the top of the face is
  63      * to the back.
  64      */
  65     AV_SPHERICAL_CUBEMAP,
  66 };
  67
  68 /**
  69  * This structure describes how to handle spherical videos, outlining
  70  * information about projection, initial layout, and any other view modifier.
  71  *
  72  * @note The struct must be allocated with av_spherical_alloc() and
  73  *       its size is not a part of the public ABI.
  74  */
  75 typedef struct AVSphericalMapping {
  76     /**
  77      * Projection type.
  78      */
  79     enum AVSphericalProjection projection;
  80
  81     /**
  82      * @name Initial orientation
  83      * @{
  84      * There fields describe additional rotations applied to the sphere after
  85      * the video frame is mapped onto it. The sphere is rotated around the
  86      * viewer, who remains stationary. The order of transformation is always
  87      * yaw, followed by pitch, and finally by roll.
  88      *
  89      * The coordinate system matches the one defined in OpenGL, where the
  90      * forward vector (z) is coming out of screen, and it is equivalent to
  91      * a rotation matrix of R = r_y(yaw) * r_x(pitch) * r_z(roll).
  92      *
  93      * A positive yaw rotates the portion of the sphere in front of the viewer
  94      * toward their right. A positive pitch rotates the portion of the sphere
  95      * in front of the viewer upwards. A positive roll tilts the portion of
  96      * the sphere in front of the viewer to the viewer's right.
  97      *
  98      * These values are exported as 16.16 fixed point.
  99      *
 100      * See this equirectangular projection as example:
 101      *
 102      * @code{.unparsed}
 103      *                   Yaw
 104      *     -180           0           180
 105      *   90 +-------------+-------------+  180
 106      *      |             |             |                  up
 107      * P    |             |             |                 y|    forward
 108      * i    |             ^             |                  |   /z
 109      * t  0 +-------------X-------------+    0 Roll        |  /
 110      * c    |             |             |                  | /
 111      * h    |             |             |                 0|/_____right
 112      *      |             |             |                        x
 113      *  -90 +-------------+-------------+ -180
 114      *
 115      * X - the default camera center
 116      * ^ - the default up vector
 117      * @endcode
 118      */
 119     int32_t yaw;   ///< Rotation around the up vector [-180, 180].
 120     int32_t pitch; ///< Rotation around the right vector [-90, 90].
 121     int32_t roll;  ///< Rotation around the forward vector [-180, 180].
 122     /**
 123      * @}
 124      */
 125 } AVSphericalMapping;
 126
 127 /**
 128  * Allocate a AVSphericalVideo structure and initialize its fields to default
 129  * values.
 130  *
 131  * @return the newly allocated struct or NULL on failure
 132  */
 133 AVSphericalMapping *av_spherical_alloc(size_t *size);
 134
 135 /**
 136  * @}
 137  * @}
 138  */
 139
 140 #endif /* AVUTIL_SPHERICAL_H */