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