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