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