FFmpeg
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 <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;
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 78 of file spherical.h.

Field Documentation

◆ projection

enum AVSphericalProjection AVSphericalMapping::projection

◆ yaw

int32_t AVSphericalMapping::yaw

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

Definition at line 122 of file spherical.h.

Referenced by dump_spherical(), mkv_handle_spherical(), mov_parse_uuid_spherical(), mov_read_sv3d(), mov_write_sv3d_tag(), and print_pkt_side_data().

◆ pitch

int32_t AVSphericalMapping::pitch

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

Definition at line 123 of file spherical.h.

Referenced by dump_spherical(), mkv_handle_spherical(), mov_parse_uuid_spherical(), mov_read_sv3d(), mov_write_sv3d_tag(), and print_pkt_side_data().

◆ roll

int32_t AVSphericalMapping::roll

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

Definition at line 124 of file spherical.h.

Referenced by dump_spherical(), mkv_handle_spherical(), mov_parse_uuid_spherical(), mov_read_sv3d(), mov_write_sv3d_tag(), and print_pkt_side_data().

◆ bound_left

uint32_t AVSphericalMapping::bound_left

Distance from the left edge.

Definition at line 163 of file spherical.h.

Referenced by mkv_handle_spherical(), mov_read_sv3d(), and mov_write_sv3d_tag().

◆ bound_top

uint32_t AVSphericalMapping::bound_top

Distance from the top edge.

Definition at line 164 of file spherical.h.

Referenced by mkv_handle_spherical(), mov_read_sv3d(), and mov_write_sv3d_tag().

◆ bound_right

uint32_t AVSphericalMapping::bound_right

Distance from the right edge.

Definition at line 165 of file spherical.h.

Referenced by mkv_handle_spherical(), mov_read_sv3d(), and mov_write_sv3d_tag().

◆ bound_bottom

uint32_t AVSphericalMapping::bound_bottom

Distance from the bottom edge.

Definition at line 166 of file spherical.h.

Referenced by mkv_handle_spherical(), mov_read_sv3d(), and mov_write_sv3d_tag().

◆ 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 178 of file spherical.h.

Referenced by dump_spherical(), mkv_handle_spherical(), mov_read_sv3d(), mov_write_sv3d_tag(), and print_pkt_side_data().


The documentation for this struct was generated from the following file:
AVSphericalMapping::bound_bottom
uint32_t bound_bottom
Distance from the bottom edge.
Definition: spherical.h:166
AVSphericalMapping::bound_top
uint32_t bound_top
Distance from the top edge.
Definition: spherical.h:164
AVSphericalMapping::bound_right
uint32_t bound_right
Distance from the right edge.
Definition: spherical.h:165
AVSphericalMapping::bound_left
uint32_t bound_left
Distance from the left edge.
Definition: spherical.h:163