path: root/libavutil/spherical.h (plain)
blob: cef759cf278bf8ac239746056c8daa16f923f43d

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