FFmpeg 5.1.6
Data Fields
AVSphericalMapping Struct Reference

This structure describes how to handle spherical videos, outlining information about projection, initial layout, and any other view modifier. More...

#include <libavutil/spherical.h>

Data Fields

enum AVSphericalProjection projection
 Projection type. More...
 
uint32_t padding
 Number of pixels to pad from the edge of each cube face. More...
 
Initial orientation

There fields describe additional rotations applied to the sphere after the video frame is mapped onto it.

The sphere is rotated around the viewer, who remains stationary. The order of transformation is always yaw, followed by pitch, and finally by roll.

The coordinate system matches the one defined in OpenGL, where the forward vector (z) is coming out of screen, and it is equivalent to a rotation matrix of R = r_y(yaw) * r_x(pitch) * r_z(roll).

A positive yaw rotates the portion of the sphere in front of the viewer toward their right. A positive pitch rotates the portion of the sphere in front of the viewer upwards. A positive roll tilts the portion of the sphere in front of the viewer to the viewer's right.

These values are exported as 16.16 fixed point.

See this equirectangular projection as example:

Yaw
-180 0 180
90 +-------------+-------------+ 180
| | | up
P | | | y| forward
i | ^ | | /z
t 0 +-------------X-------------+ 0 Roll | /
c | | | | /
h | | | 0|/_____right
| | | x
-90 +-------------+-------------+ -180
X - the default camera center
^ - the default up vector
int32_t yaw
 Rotation around the up vector [-180, 180]. More...
 
int32_t pitch
 Rotation around the right vector [-90, 90]. More...
 
int32_t roll
 Rotation around the forward vector [-180, 180]. More...
 
Bounding rectangle

These fields indicate the location of the current tile, and where it should be mapped relative to the original surface.

They are exported as 0.32 fixed point, and can be converted to classic pixel values with av_spherical_bounds().

+----------------+----------+
| |bound_top |
| +--------+ |
| bound_left |tile | |
+<---------->| |<--->+bound_right
| +--------+ |
| | |
| bound_bottom| |
+----------------+----------+

If needed, the original video surface dimensions can be derived by adding the current stream or frame size to the related bounds, like in the following example:

original_width = tile->width + bound_left + bound_right;
original_height = tile->height + bound_top + bound_bottom;
uint32_t bound_left
Distance from the left edge.
Definition: spherical.h:167
uint32_t bound_top
Distance from the top edge.
Definition: spherical.h:168
uint32_t bound_bottom
Distance from the bottom edge.
Definition: spherical.h:170
uint32_t bound_right
Distance from the right edge.
Definition: spherical.h:169
Note
These values are valid only for the tiled equirectangular projection type (AV_SPHERICAL_EQUIRECTANGULAR_TILE), and should be ignored in all other cases.
uint32_t bound_left
 Distance from the left edge. More...
 
uint32_t bound_top
 Distance from the top edge. More...
 
uint32_t bound_right
 Distance from the right edge. More...
 
uint32_t bound_bottom
 Distance from the bottom edge. More...
 

Detailed Description

This structure describes how to handle spherical videos, outlining information about projection, initial layout, and any other view modifier.

Note
The struct must be allocated with av_spherical_alloc() and its size is not a part of the public ABI.

Definition at line 82 of file spherical.h.

Field Documentation

◆ projection

enum AVSphericalProjection AVSphericalMapping::projection

Projection type.

Definition at line 86 of file spherical.h.

◆ yaw

int32_t AVSphericalMapping::yaw

Rotation around the up vector [-180, 180].

Definition at line 126 of file spherical.h.

◆ pitch

int32_t AVSphericalMapping::pitch

Rotation around the right vector [-90, 90].

Definition at line 127 of file spherical.h.

◆ roll

int32_t AVSphericalMapping::roll

Rotation around the forward vector [-180, 180].

Definition at line 128 of file spherical.h.

◆ bound_left

uint32_t AVSphericalMapping::bound_left

Distance from the left edge.

Definition at line 167 of file spherical.h.

◆ bound_top

uint32_t AVSphericalMapping::bound_top

Distance from the top edge.

Definition at line 168 of file spherical.h.

◆ bound_right

uint32_t AVSphericalMapping::bound_right

Distance from the right edge.

Definition at line 169 of file spherical.h.

◆ bound_bottom

uint32_t AVSphericalMapping::bound_bottom

Distance from the bottom edge.

Definition at line 170 of file spherical.h.

◆ padding

uint32_t AVSphericalMapping::padding

Number of pixels to pad from the edge of each cube face.

Note
This value is valid for only for the cubemap projection type (AV_SPHERICAL_CUBEMAP), and should be ignored in all other cases.

Definition at line 182 of file spherical.h.


The documentation for this struct was generated from the following file: