Swap chains and frames

Functions to create a swap chain, manipulate it and submit frames for lens distortion and presentation on the screen.

Summary

Functions

gvr_bind_default_framebuffer(gvr_context *gvr)
void
Resets the OpenGL framebuffer binding to what it was at the time the passed gvr_context was created.
gvr_buffer_spec_create(gvr_context *gvr)
gvr_buffer_spec *
Creates a default buffer specification.
gvr_buffer_spec_destroy(gvr_buffer_spec **spec)
void
Destroy the buffer specification and null the pointer.
gvr_buffer_spec_get_samples(const gvr_buffer_spec *spec)
int32_t
Gets the number of samples per pixel in the buffer to be created.
gvr_buffer_spec_get_size(const gvr_buffer_spec *spec)
Gets the size of the buffer to be created.
gvr_buffer_spec_set_color_format(gvr_buffer_spec *spec, int32_t color_format)
void
Sets the color format for the buffer to be created.
gvr_buffer_spec_set_depth_stencil_format(gvr_buffer_spec *spec, int32_t depth_stencil_format)
void
Sets the depth and stencil format for the buffer to be created.
gvr_buffer_spec_set_multiview_layers(gvr_buffer_spec *spec, int32_t num_layers)
void
Sets the number of layers in a framebuffer backed by an array texture.
gvr_buffer_spec_set_samples(gvr_buffer_spec *spec, int32_t num_samples)
void
Sets the number of samples per pixel in the buffer to be created.
gvr_buffer_spec_set_size(gvr_buffer_spec *spec, gvr_sizei size)
void
Sets the size of the buffer to be created.
gvr_frame_bind_buffer(gvr_frame *frame, int32_t index)
void
Binds a pixel buffer that is part of the frame to the OpenGL framebuffer.
gvr_frame_get_buffer_size(const gvr_frame *frame, int32_t index)
Returns the dimensions of the pixel buffer with the specified index.
gvr_frame_get_framebuffer_object(const gvr_frame *frame, int32_t index)
int32_t
Gets the name (ID) of the framebuffer object associated with the specified buffer.
gvr_frame_get_hardware_buffer(const gvr_frame *frame, int32_t index)
AHardwareBuffer *
Gets the hardware buffer backing the specified frame buffer.
gvr_frame_submit(gvr_frame **frame, const gvr_buffer_viewport_list *list, gvr_mat4f head_space_from_start_space)
void
Submits the frame for distortion and display on the screen.
gvr_frame_unbind(gvr_frame *frame)
void
Unbinds any buffers bound from this frame and binds the default OpenGL framebuffer.
gvr_swap_chain_acquire_frame(gvr_swap_chain *swap_chain)
gvr_frame *
Acquires a frame from the swap chain for rendering.
gvr_swap_chain_create(gvr_context *gvr, const gvr_buffer_spec **buffers, int32_t count)
gvr_swap_chain *
Creates a swap chain from the given buffer specifications.
gvr_swap_chain_destroy(gvr_swap_chain **swap_chain)
void
Destroys the swap chain and nulls the pointer that is passed in.
gvr_swap_chain_get_buffer_count(const gvr_swap_chain *swap_chain)
int32_t
Gets the number of buffers in each frame of the swap chain.
gvr_swap_chain_get_buffer_size(const gvr_swap_chain *swap_chain, int32_t index)
Retrieves the size of the specified pixel buffer.
gvr_swap_chain_resize_buffer(gvr_swap_chain *swap_chain, int32_t index, gvr_sizei size)
void
Resizes the specified pixel buffer to the given size.

Functions

gvr_bind_default_framebuffer

void gvr_bind_default_framebuffer(
  gvr_context *gvr
)

Resets the OpenGL framebuffer binding to what it was at the time the passed gvr_context was created.

gvr_buffer_spec_create

gvr_buffer_spec * gvr_buffer_spec_create(
  gvr_context *gvr
)

Creates a default buffer specification.

gvr_buffer_spec_destroy

void gvr_buffer_spec_destroy(
  gvr_buffer_spec **spec
)

Destroy the buffer specification and null the pointer.

gvr_buffer_spec_get_samples

int32_t gvr_buffer_spec_get_samples(
  const gvr_buffer_spec *spec
)

Gets the number of samples per pixel in the buffer to be created.

Details
Parameters
spec
Buffer specification.
Returns
Value >= 1 giving the number of samples. 1 means multisampling is disabled. Negative values and 0 are never returned.

gvr_buffer_spec_get_size

gvr_sizei gvr_buffer_spec_get_size(
  const gvr_buffer_spec *spec
)

Gets the size of the buffer to be created.

Details
Parameters
spec
Buffer specification.
Returns
Size of the pixel buffer. The default is equal to the recommended render target size at the time when the specification was created.

gvr_buffer_spec_set_color_format

void gvr_buffer_spec_set_color_format(
  gvr_buffer_spec *spec,
  int32_t color_format
)

Sets the color format for the buffer to be created.

Default format is GVR_COLOR_FORMAT_RGBA_8888. For all alpha-containing formats, the pixels are expected to be premultiplied with alpha. In other words, the 60% opaque primary green color is (0.0, 0.6, 0.0, 0.6).

Details
Parameters
spec
Buffer specification.
color_format
The color format for the buffer. Valid formats are in the gvr_color_format_type enum.

gvr_buffer_spec_set_depth_stencil_format

void gvr_buffer_spec_set_depth_stencil_format(
  gvr_buffer_spec *spec,
  int32_t depth_stencil_format
)

Sets the depth and stencil format for the buffer to be created.

Currently, only packed stencil formats are supported. Default format is GVR_DEPTH_STENCIL_FORMAT_DEPTH_16.

Details
Parameters
spec
Buffer specification.
depth_stencil_format
The depth and stencil format for the buffer. Valid formats are in the gvr_depth_stencil_format_type enum.

gvr_buffer_spec_set_multiview_layers

void gvr_buffer_spec_set_multiview_layers(
  gvr_buffer_spec *spec,
  int32_t num_layers
)

Sets the number of layers in a framebuffer backed by an array texture.

Default is 1, which means a non-layered texture will be created. Not all platforms support multiple layers, so clients can call gvr_is_feature_supported(GVR_FEATURE_MULTIVIEW) to check.

Details
Parameters
spec
Buffer specification.
num_layers
The number of layers in the array texture.

gvr_buffer_spec_set_samples

void gvr_buffer_spec_set_samples(
  gvr_buffer_spec *spec,
  int32_t num_samples
)

Sets the number of samples per pixel in the buffer to be created.

Details
Parameters
spec
Buffer specification.
num_samples
The number of samples. Negative values are an error. The values 0 and 1 are treated identically and indicate that

gvr_buffer_spec_set_size

void gvr_buffer_spec_set_size(
  gvr_buffer_spec *spec,
  gvr_sizei size
)

Sets the size of the buffer to be created.

Details
Parameters
spec
Buffer specification.
size
The size. Width and height must both be greater than zero. Otherwise, the application is aborted.

gvr_frame_bind_buffer

void gvr_frame_bind_buffer(
  gvr_frame *frame,
  int32_t index
)

Binds a pixel buffer that is part of the frame to the OpenGL framebuffer.

Details
Parameters
frame
Frame handle acquired from the swap chain.
index
Index of the pixel buffer to bind. This corresponds to the index in the buffer spec list that was passed to gvr_swap_chain_create().

gvr_frame_get_buffer_size

gvr_sizei gvr_frame_get_buffer_size(
  const gvr_frame *frame,
  int32_t index
)

Returns the dimensions of the pixel buffer with the specified index.

Note that a frame that was acquired before resizing a swap chain buffer will not be resized until it is submitted to the swap chain.

Details
Parameters
frame
Frame handle.
index
Index of the pixel buffer to inspect.
Returns
Dimensions of the specified pixel buffer.

gvr_frame_get_framebuffer_object

int32_t gvr_frame_get_framebuffer_object(
  const gvr_frame *frame,
  int32_t index
)

Gets the name (ID) of the framebuffer object associated with the specified buffer.

The OpenGL state is not modified.

Details
Parameters
frame
Frame handle.
index
Index of a pixel buffer.
Returns
OpenGL object name (ID) of a framebuffer object which can be used to render into the buffer. The ID is valid only until the frame is submitted.

gvr_frame_get_hardware_buffer

AHardwareBuffer * gvr_frame_get_hardware_buffer(
  const gvr_frame *frame,
  int32_t index
)

Gets the hardware buffer backing the specified frame buffer.

Hardware buffers (Android NDK type AHardwareBuffer) are used to back frames if asynchronous reprojection is enabled and GVR_FEATURE_HARDWARE_BUFFERS is supported (currently on Android O and later Android versions). See the documentation for the feature enum value for further information.

There is no need to acquire or release the AHardwareBuffer. The swap chain maintains a reference to it while the frame is acquired.

Details
Parameters
frame
The gvr_frame from which to obtain the buffer.
index
Index of the pixel buffer.
Returns
Pointer to AHardwareBuffer backing the frame's pixel buffer where available, or NULL otherwise.

gvr_frame_submit

void gvr_frame_submit(
  gvr_frame **frame,
  const gvr_buffer_viewport_list *list,
  gvr_mat4f head_space_from_start_space
)

Submits the frame for distortion and display on the screen.

The passed pointer is nulled to prevent reuse.

Note: On Cardboard devices, this function makes OpenGL commands in the current thread's GL context; this can affect various GL state such as texture bindings, depth testing, backface culling, and blending.

Details
Parameters
frame
The frame to submit.
list
Buffer view configuration to be used for this frame.
head_space_from_start_space
Transform from start space (space with head at the origin at last tracking reset) to head space (space with head at the origin and axes aligned to the view vector).

gvr_frame_unbind

void gvr_frame_unbind(
  gvr_frame *frame
)

Unbinds any buffers bound from this frame and binds the default OpenGL framebuffer.

gvr_swap_chain_acquire_frame

gvr_frame * gvr_swap_chain_acquire_frame(
  gvr_swap_chain *swap_chain
)

Acquires a frame from the swap chain for rendering.

Buffers that are part of the frame can then be bound with gvr_frame_bind_buffer(). Once the frame is finished and all its constituent buffers are ready, call gvr_frame_submit() to display it while applying lens distortion.

When this is called, the current thread's GL context must be the same context that was current when gvr_initialize_gl() was called, or at least be in a share group with the initialization context.

Details
Parameters
swap_chain
The swap chain.
Returns
Handle to the acquired frame. NULL if the swap chain is invalid, or if acquire has already been called on this swap chain.

gvr_swap_chain_create

gvr_swap_chain * gvr_swap_chain_create(
  gvr_context *gvr,
  const gvr_buffer_spec **buffers,
  int32_t count
)

Creates a swap chain from the given buffer specifications.

This is a potentially time-consuming operation. All frames within the swapchain will be allocated. Once rendering is stopped, call gvr_swap_chain_destroy() to free GPU resources. The passed gvr_context must not be destroyed until then.

Swap chains can have no buffers. This is useful when only displaying external surfaces. When count is zero, buffers must be null.

Details
Parameters
gvr
GVR instance for which a swap chain will be created.
buffers
Array of pixel buffer specifications. Each frame in the swap chain will be composed of these buffers.
count
Number of buffer specifications in the array.
Returns
Opaque handle to the newly created swap chain.

gvr_swap_chain_destroy

void gvr_swap_chain_destroy(
  gvr_swap_chain **swap_chain
)

Destroys the swap chain and nulls the pointer that is passed in.

This should be called after rendering is finished to free all the buffers that have been allocated in the swap chain.

Details
Parameters
swap_chain
The swap chain to destroy.

gvr_swap_chain_get_buffer_count

int32_t gvr_swap_chain_get_buffer_count(
  const gvr_swap_chain *swap_chain
)

Gets the number of buffers in each frame of the swap chain.

Details
Parameters
swap_chain
The swap chain to query.
Returns
The number of buffers in the swap chain.

gvr_swap_chain_get_buffer_size

gvr_sizei gvr_swap_chain_get_buffer_size(
  const gvr_swap_chain *swap_chain,
  int32_t index
)

Retrieves the size of the specified pixel buffer.

Note that if the buffer was resized while the current frame was acquired, the return value will be different than the value obtained from the equivalent function for the current frame.

Details
Parameters
swap_chain
The swap chain.
index
Index of the pixel buffer.
Returns
Size of the specified pixel buffer in frames that will be returned from gvr_swap_chain_acquire_frame().

gvr_swap_chain_resize_buffer

void gvr_swap_chain_resize_buffer(
  gvr_swap_chain *swap_chain,
  int32_t index,
  gvr_sizei size
)

Resizes the specified pixel buffer to the given size.

The frames are resized when they are unused, so the currently acquired frame will not be resized immediately.

Details
Parameters
swap_chain
The swap chain.
index
Index of the pixel buffer to resize.
size
New size for the specified pixel buffer.