Viewports and viewport lists

Objects to define the mapping between the application's rendering output and the user's field of view.

Summary

Functions
gvr_buffer_viewport_create(gvr_context *gvr)
gvr_buffer_viewport *
Creates a gvr_buffer_viewport instance.
gvr_buffer_viewport_destroy(gvr_buffer_viewport **viewport)
void
Frees a gvr_buffer_viewport instance and clears the pointer.
gvr_buffer_viewport_equal(const gvr_buffer_viewport *a, const gvr_buffer_viewport *b)
bool
Compares two gvr_buffer_viewport instances and returns true if they specify the same view mapping.
gvr_buffer_viewport_get_external_surface_id(const gvr_buffer_viewport *viewport)
int32_t
Gets the ID of the externally-managed Surface texture from which this viewport reads undistored pixels.
gvr_buffer_viewport_get_opacity(const gvr_buffer_viewport *viewport)
float
Gets the opacity to perform on the specified viewport.
gvr_buffer_viewport_get_reprojection(const gvr_buffer_viewport *viewport)
int32_t
Gets the type of reprojection to perform on the specified viewport.
gvr_buffer_viewport_get_source_buffer_index(const gvr_buffer_viewport *viewport)
int32_t
Gets the index of the source buffer from which the viewport reads its undistorted pixels.
gvr_buffer_viewport_get_source_fov(const gvr_buffer_viewport *viewport)
Retrieves the field of view for the referenced buffer region.
gvr_buffer_viewport_get_source_uv(const gvr_buffer_viewport *viewport)
Gets the UV coordinates specifying where the output buffer is sampled.
gvr_buffer_viewport_get_target_eye(const gvr_buffer_viewport *viewport)
int32_t
Gets the target logical eye for the specified viewport.
gvr_buffer_viewport_get_transform(const gvr_buffer_viewport *viewport)
Gets the matrix that positions the viewport in eye space.
gvr_buffer_viewport_list_create(const gvr_context *gvr)
gvr_buffer_viewport_list *
Creates a new, empty list of viewports.
gvr_buffer_viewport_list_destroy(gvr_buffer_viewport_list **viewport_list)
void
Destroys a gvr_buffer_viewport_list instance.
gvr_buffer_viewport_list_get_item(const gvr_buffer_viewport_list *viewport_list, size_t index, gvr_buffer_viewport *viewport)
void
Retrieve a buffer viewport entry from a list.
gvr_buffer_viewport_list_get_size(const gvr_buffer_viewport_list *viewport_list)
size_t
Returns the size of the given viewport list.
gvr_buffer_viewport_list_set_item(gvr_buffer_viewport_list *viewport_list, size_t index, const gvr_buffer_viewport *viewport)
void
Update an element of the viewport list or append a new one at the end.
gvr_buffer_viewport_set_external_surface_id(gvr_buffer_viewport *viewport, int32_t external_surface_id)
void
Sets the ID of the externally-managed Surface texture from which this viewport reads.
gvr_buffer_viewport_set_opacity(gvr_buffer_viewport *viewport, float opacity)
void
Sets the opacity to perform on the specified viewport.
gvr_buffer_viewport_set_reprojection(gvr_buffer_viewport *viewport, int32_t reprojection)
void
Sets the type of reprojection to perform on the specified viewport.
gvr_buffer_viewport_set_source_buffer_index(gvr_buffer_viewport *viewport, int32_t buffer_index)
void
Sets the buffer from which the viewport reads its undistorted pixels.
gvr_buffer_viewport_set_source_fov(gvr_buffer_viewport *viewport, gvr_rectf fov)
void
Sets the field of view for the viewport contents.
gvr_buffer_viewport_set_source_layer(gvr_buffer_viewport *viewport, int32_t layer_index)
void
Sets the layer in a multiview buffer from which the viewport should sample.
gvr_buffer_viewport_set_source_uv(gvr_buffer_viewport *viewport, gvr_rectf uv)
void
Sets the UV coordinates specifying where the output buffer should be sampled when compositing the final distorted image.
gvr_buffer_viewport_set_target_eye(gvr_buffer_viewport *viewport, int32_t index)
void
Sets the target logical eye for the specified viewport.
gvr_buffer_viewport_set_transform(gvr_buffer_viewport *viewport, gvr_mat4f transform)
void
Sets the matrix that positions the viewport in eye space.

Functions

gvr_buffer_viewport_create

gvr_buffer_viewport * gvr_buffer_viewport_create(
  gvr_context *gvr
)

Creates a gvr_buffer_viewport instance.

gvr_buffer_viewport_destroy

void gvr_buffer_viewport_destroy(
  gvr_buffer_viewport **viewport
)

Frees a gvr_buffer_viewport instance and clears the pointer.

gvr_buffer_viewport_equal

bool gvr_buffer_viewport_equal(
  const gvr_buffer_viewport *a,
  const gvr_buffer_viewport *b
)

Compares two gvr_buffer_viewport instances and returns true if they specify the same view mapping.

Details
Parameters
a
Instance of a buffer viewport.
b
Another instance of a buffer viewport.
Returns
True if the passed viewports are the same.

gvr_buffer_viewport_get_external_surface_id

int32_t gvr_buffer_viewport_get_external_surface_id(
  const gvr_buffer_viewport *viewport
)

Gets the ID of the externally-managed Surface texture from which this viewport reads undistored pixels.

Details
Parameters
viewport
The buffer viewport.
Returns
ID of the externally-managed Surface of undistorted pixels.

gvr_buffer_viewport_get_opacity

float gvr_buffer_viewport_get_opacity(
  const gvr_buffer_viewport *viewport
)

Gets the opacity to perform on the specified viewport.

Details
Parameters
viewport
The buffer viewport.
Returns
opacity that is applied to the viewport, default to be 1.

gvr_buffer_viewport_get_reprojection

int32_t gvr_buffer_viewport_get_reprojection(
  const gvr_buffer_viewport *viewport
)

Gets the type of reprojection to perform on the specified viewport.

Details
Parameters
viewport
The buffer viewport.
Returns
Type of reprojection that is applied to the viewport.

gvr_buffer_viewport_get_source_buffer_index

int32_t gvr_buffer_viewport_get_source_buffer_index(
  const gvr_buffer_viewport *viewport
)

Gets the index of the source buffer from which the viewport reads its undistorted pixels.

Details
Parameters
viewport
The buffer viewport.
Returns
Index of the source buffer. This corresponds to the index in the list of buffer specs that was passed to gvr_swap_chain_create().

gvr_buffer_viewport_get_source_fov

gvr_rectf gvr_buffer_viewport_get_source_fov(
  const gvr_buffer_viewport *viewport
)

Retrieves the field of view for the referenced buffer region.

This is a helper that converts the stored projection matrix to a field of view. Note that if the previously set projection matrix cannot be expressed as a view frustum aligned with the eye's optical axis, the result will be incorrect.

Details
Parameters
viewport
The buffer viewport.
Returns
The field of view of the rendered image, in degrees.

gvr_buffer_viewport_get_source_uv

gvr_rectf gvr_buffer_viewport_get_source_uv(
  const gvr_buffer_viewport *viewport
)

Gets the UV coordinates specifying where the output buffer is sampled.

Details
Parameters
viewport
The buffer viewport.
Returns
UV coordinates as a rectangle.

gvr_buffer_viewport_get_target_eye

int32_t gvr_buffer_viewport_get_target_eye(
  const gvr_buffer_viewport *viewport
)

Gets the target logical eye for the specified viewport.

Details
Parameters
viewport
The buffer viewport.
Returns
Index of the target logical eye for this viewport.

gvr_buffer_viewport_get_transform

gvr_mat4f gvr_buffer_viewport_get_transform(
  const gvr_buffer_viewport *viewport
)

Gets the matrix that positions the viewport in eye space.

Details
Parameters
viewport
The buffer viewport.
Returns
Matrix that transforms a quad with vertices (-1, -1, 0), (1, -1, 0), (-1, 1, 0), (1, 1, 0) representing the viewport contents to its desired eye space position for the target eye.

gvr_buffer_viewport_list_create

gvr_buffer_viewport_list * gvr_buffer_viewport_list_create(
  const gvr_context *gvr
)

Creates a new, empty list of viewports.

The viewport list defines how the application's rendering output should be transformed into the stabilized, lens-distorted image that is sent to the screen.

The caller should populate the returned viewport using one of:

Details
Parameters
gvr
Pointer the gvr instance from which to allocate the viewport list.
Returns
Pointer to an allocated gvr_buffer_viewport_list object. The caller returned object when it is no longer needed.

gvr_buffer_viewport_list_destroy

void gvr_buffer_viewport_list_destroy(
  gvr_buffer_viewport_list **viewport_list
)

Destroys a gvr_buffer_viewport_list instance.

The parameter will be nulled by this operation.

Details
Parameters
viewport_list
Pointer to a pointer to the viewport list instance to be destroyed and nulled.

gvr_buffer_viewport_list_get_item

void gvr_buffer_viewport_list_get_item(
  const gvr_buffer_viewport_list *viewport_list,
  size_t index,
  gvr_buffer_viewport *viewport
)

Retrieve a buffer viewport entry from a list.

Details
Parameters
viewport_list
Pointer to the previously allocated viewport list.
index
Zero-based index of the viewport entry to query. Must be smaller than the list size.
viewport
The buffer viewport structure that will be populated with retrieved data.

gvr_buffer_viewport_list_get_size

size_t gvr_buffer_viewport_list_get_size(
  const gvr_buffer_viewport_list *viewport_list
)

Returns the size of the given viewport list.

Details
Parameters
viewport_list
Pointer to a viewport list.
Returns
The number of entries in the viewport list.

gvr_buffer_viewport_list_set_item

void gvr_buffer_viewport_list_set_item(
  gvr_buffer_viewport_list *viewport_list,
  size_t index,
  const gvr_buffer_viewport *viewport
)

Update an element of the viewport list or append a new one at the end.

Details
Parameters
viewport_list
Pointer to a previously allocated viewport list.
index
Index of the buffer viewport entry to update. If the viewport_list size is equal to the index, a new viewport entry will be added. The viewport_list size must not be less than the index value.
viewport
A pointer to the buffer viewport object.

gvr_buffer_viewport_set_external_surface_id

void gvr_buffer_viewport_set_external_surface_id(
  gvr_buffer_viewport *viewport,
  int32_t external_surface_id
)

Sets the ID of the externally-managed Surface texture from which this viewport reads.

The ID is issued by GvrLayout. If this viewport does not read from an external surface, this should be set to GVR_EXTERNAL_SURFACE_ID_NONE, which is also the default value. If it does read from an external surface, set this to the ID obtained from GvrLayout and set the source buffer index to the special value GVR_BUFFER_INDEX_EXTERNAL_SURFACE.

Details
Parameters
viewport
The buffer viewport.
external_surface_id
The ID of the surface to read from.

gvr_buffer_viewport_set_opacity

void gvr_buffer_viewport_set_opacity(
  gvr_buffer_viewport *viewport,
  float opacity
)

Sets the opacity to perform on the specified viewport.

Details
Parameters
viewport
The buffer viewport.
opacity
Opacity that will be applied per viewport. It should be within [0,1], default to be 1.

gvr_buffer_viewport_set_reprojection

void gvr_buffer_viewport_set_reprojection(
  gvr_buffer_viewport *viewport,
  int32_t reprojection
)

Sets the type of reprojection to perform on the specified viewport.

Viewports that display world content should use full reprojection. Viewports that display head-locked UI should disable reprojection to avoid excessive judder. The default is to perform full reprojection.

Details
Parameters
viewport
The buffer viewport.
reprojection
Type of reprojection that will be applied to the passed viewport.

gvr_buffer_viewport_set_source_buffer_index

void gvr_buffer_viewport_set_source_buffer_index(
  gvr_buffer_viewport *viewport,
  int32_t buffer_index
)

Sets the buffer from which the viewport reads its undistorted pixels.

To use the contents of the external surface as buffer contents, associate an external surface with the viewport by calling gvr_buffer_viewport_set_external_surface_id(), then call this function and pass GVR_BUFFER_INDEX_EXTERNAL_SURFACE.

Details
Parameters
viewport
The buffer viewport.
buffer_index
The index of the source buffer. This is either an index in the list of buffer specs that was passed to gvr_swap_chain_create(), or GVR_BUFFER_INDEX_EXTERNAL_SURFACE.

gvr_buffer_viewport_set_source_fov

void gvr_buffer_viewport_set_source_fov(
  gvr_buffer_viewport *viewport,
  gvr_rectf fov
)

Sets the field of view for the viewport contents.

This is a helper that sets the projection matrix in such a way that the viewport's contents fill the specified FOV around the eye's optical axis.

Details
Parameters
viewport
The buffer viewport.
fov
The field of view to use when compositing the rendered image, in degrees.

gvr_buffer_viewport_set_source_layer

void gvr_buffer_viewport_set_source_layer(
  gvr_buffer_viewport *viewport,
  int32_t layer_index
)

Sets the layer in a multiview buffer from which the viewport should sample.

Details
Parameters
layer_index
The layer in the array texture that distortion samples from. Must be non-negative. Defaults to 0.

gvr_buffer_viewport_set_source_uv

void gvr_buffer_viewport_set_source_uv(
  gvr_buffer_viewport *viewport,
  gvr_rectf uv
)

Sets the UV coordinates specifying where the output buffer should be sampled when compositing the final distorted image.

Details
Parameters
viewport
The buffer viewport.
uv
The new UV coordinates for sampling. The coordinates must be valid, that is, left <= right and bottom <= top. Otherwise an empty source region is set, which will result in no output for this viewport.

gvr_buffer_viewport_set_target_eye

void gvr_buffer_viewport_set_target_eye(
  gvr_buffer_viewport *viewport,
  int32_t index
)

Sets the target logical eye for the specified viewport.

Details
Parameters
viewport
The buffer viewport.
index
Index of the target logical eye.

gvr_buffer_viewport_set_transform

void gvr_buffer_viewport_set_transform(
  gvr_buffer_viewport *viewport,
  gvr_mat4f transform
)

Sets the matrix that positions the viewport in eye space.

Details
Parameters
viewport
The buffer viewport.
transform
Matrix that transforms a quad with vertices (-1, -1, 0), (1, -1, 0), (-1, 1, 0), (1, 1, 0) representing the viewport contents to its desired eye space position for the target eye.