This site has been permanently archived. The content on this site was last updated in 2019.

All developers actively developing experiences for Google Cardboard should use the open source Cardboard SDKs for iOS, Android NDK, and Unity XR Plugin.
The Daydream View VR headset is no longer available for purchase as of October 15, 2019. As of November 2023, previously supported devices will no longer be able to download and install Google VR Serivces (Android application ID com.google.vr.vrcore) for new users.

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)`	`gvr_sizei` 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)`	`gvr_sizei` 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)`	`gvr_sizei` 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.