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      * Video represents a portion of a sphere mapped on a flat surface
  69      * using equirectangular projection. The @ref bounding fields indicate
  70      * the position of the current video in a larger surface.
  71      */
  72     AV_SPHERICAL_EQUIRECTANGULAR_TILE,
  73 };
  74
  75 /**
  76  * This structure describes how to handle spherical videos, outlining
  77  * information about projection, initial layout, and any other view modifier.
  78  *
  79  * @note The struct must be allocated with av_spherical_alloc() and
  80  *       its size is not a part of the public ABI.
  81  */
  82 typedef struct AVSphericalMapping {
  83     /**
  84      * Projection type.
  85      */
  86     enum AVSphericalProjection projection;
  87
  88     /**
  89      * @name Initial orientation
  90      * @{
  91      * There fields describe additional rotations applied to the sphere after
  92      * the video frame is mapped onto it. The sphere is rotated around the
  93      * viewer, who remains stationary. The order of transformation is always
  94      * yaw, followed by pitch, and finally by roll.
  95      *
  96      * The coordinate system matches the one defined in OpenGL, where the
  97      * forward vector (z) is coming out of screen, and it is equivalent to
  98      * a rotation matrix of R = r_y(yaw) * r_x(pitch) * r_z(roll).
  99      *
 100      * A positive yaw rotates the portion of the sphere in front of the viewer
 101      * toward their right. A positive pitch rotates the portion of the sphere
 102      * in front of the viewer upwards. A positive roll tilts the portion of
 103      * the sphere in front of the viewer to the viewer's right.
 104      *
 105      * These values are exported as 16.16 fixed point.
 106      *
 107      * See this equirectangular projection as example:
 108      *
 109      * @code{.unparsed}
 110      *                   Yaw
 111      *     -180           0           180
 112      *   90 +-------------+-------------+  180
 113      *      |             |             |                  up
 114      * P    |             |             |                 y|    forward
 115      * i    |             ^             |                  |   /z
 116      * t  0 +-------------X-------------+    0 Roll        |  /
 117      * c    |             |             |                  | /
 118      * h    |             |             |                 0|/_____right
 119      *      |             |             |                        x
 120      *  -90 +-------------+-------------+ -180
 121      *
 122      * X - the default camera center
 123      * ^ - the default up vector
 124      * @endcode
 125      */
 126     int32_t yaw;   ///< Rotation around the up vector [-180, 180].
 127     int32_t pitch; ///< Rotation around the right vector [-90, 90].
 128     int32_t roll;  ///< Rotation around the forward vector [-180, 180].
 129     /**
 130      * @}
 131      */
 132
 133     /**
 134      * @name Bounding rectangle
 135      * @anchor bounding
 136      * @{
 137      * These fields indicate the location of the current tile, and where
 138      * it should be mapped relative to the original surface. They are
 139      * exported as 0.32 fixed point, and can be converted to classic
 140      * pixel values with av_spherical_bounds().
 141      *
 142      * @code{.unparsed}
 143      *      +----------------+----------+
 144      *      |                |bound_top |
 145      *      |            +--------+     |
 146      *      | bound_left |tile    |     |
 147      *      +<---------->|        |<--->+bound_right
 148      *      |            +--------+     |
 149      *      |                |          |
 150      *      |    bound_bottom|          |
 151      *      +----------------+----------+
 152      * @endcode
 153      *
 154      * If needed, the original video surface dimensions can be derived
 155      * by adding the current stream or frame size to the related bounds,
 156      * like in the following example:
 157      *
 158      * @code{c}
 159      *     original_width  = tile->width  + bound_left + bound_right;
 160      *     original_height = tile->height + bound_top  + bound_bottom;
 161      * @endcode
 162      *
 163      * @note These values are valid only for the tiled equirectangular
 164      *       projection type (@ref AV_SPHERICAL_EQUIRECTANGULAR_TILE),
 165      *       and should be ignored in all other cases.
 166      */
 167     uint32_t bound_left;   ///< Distance from the left edge
 168     uint32_t bound_top;    ///< Distance from the top edge
 169     uint32_t bound_right;  ///< Distance from the right edge
 170     uint32_t bound_bottom; ///< Distance from the bottom edge
 171     /**
 172      * @}
 173      */
 174
 175     /**
 176      * Number of pixels to pad from the edge of each cube face.
 177      *
 178      * @note This value is valid for only for the cubemap projection type
 179      *       (@ref AV_SPHERICAL_CUBEMAP), and should be ignored in all other
 180      *       cases.
 181      */
 182     uint32_t padding;
 183 } AVSphericalMapping;
 184
 185 /**
 186  * Allocate a AVSphericalVideo structure and initialize its fields to default
 187  * values.
 188  *
 189  * @return the newly allocated struct or NULL on failure
 190  */
 191 AVSphericalMapping *av_spherical_alloc(size_t *size);
 192
 193 /**
 194  * Convert the @ref bounding fields from an AVSphericalVideo
 195  * from 0.32 fixed point to pixels.
 196  *
 197  * @param map    The AVSphericalVideo map to read bound values from.
 198  * @param width  Width of the current frame or stream.
 199  * @param height Height of the current frame or stream.
 200  * @param left   Pixels from the left edge.
 201  * @param top    Pixels from the top edge.
 202  * @param right  Pixels from the right edge.
 203  * @param bottom Pixels from the bottom edge.
 204  */
 205 void av_spherical_tile_bounds(const AVSphericalMapping *map,
 206                               size_t width, size_t height,
 207                               size_t *left, size_t *top,
 208                               size_t *right, size_t *bottom);
 209
 210 /**
 211  * Provide a human-readable name of a given AVSphericalProjection.
 212  *
 213  * @param projection The input AVSphericalProjection.
 214  *
 215  * @return The name of the AVSphericalProjection, or "unknown".
 216  */
 217 const char *av_spherical_projection_name(enum AVSphericalProjection projection);
 218
 219 /**
 220  * Get the AVSphericalProjection form a human-readable name.
 221  *
 222  * @param name The input string.
 223  *
 224  * @return The AVSphericalProjection value, or -1 if not found.
 225  */
 226 int av_spherical_from_name(const char *name);
 227 /**
 228  * @}
 229  * @}
 230  */
 231
 232 #endif /* AVUTIL_SPHERICAL_H */