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.

Surround Renderer API

This is the GVR Binaural Surround Renderer C API which reads in PCM buffers of surround sound as well as ambisonic soundfield content to render binaural stereo.

Summary

In contrast to GVR's Spatial Audio API, the Surround Renderer API is designed to be integrated into media players to enable head-tracked binaural audio in VR movie and 360 video experiences. It accepts input and output buffers of arbitrary frame size. However note that the binaural output is only generated when the number of input frames exceed the process_num_frames size specified during construction.

Typedefs
`gvr_audio_surround_context`	typedef `struct gvr_audio_surround_context_`

Functions
`gvr_audio_surround_add_interleaved_input(gvr_audio_surround_context api, const int16_t input_buffer_ptr, int64_t num_samples)`	`int64_t` Adds interleaved audio data to the renderer.
`gvr_audio_surround_clear(gvr_audio_surround_context *api)`	`void` Removes all buffered input and processed output buffers from the buffer queues.
`gvr_audio_surround_create(gvr_audio_surround_format_type surround_format, int32_t num_input_channels, int32_t frames_per_processing, int sample_rate_hz)`	`gvr_audio_surround_context *` Creates and initializes a gvr_audio_surround_context.
`gvr_audio_surround_destroy(gvr_audio_surround_context **api)`	`void` Destroys a gvr_audio_surround_context that was previously created with gvr_audio_surround_create.
`gvr_audio_surround_get_available_input_size_samples(const gvr_audio_surround_context *api)`	`int64_t` Returns the number of samples the input buffer is currently able to consume.
`gvr_audio_surround_get_available_output_size_samples(const gvr_audio_surround_context *api)`	`int64_t` Returns the number of samples available in the output buffer.
`gvr_audio_surround_get_interleaved_output(gvr_audio_surround_context api, int16_t output_buffer_ptr, int64_t num_samples)`	`int64_t` Gets a processed output buffer in interleaved format.
`gvr_audio_surround_set_head_rotation(gvr_audio_surround_context *api, float w, float x, float y, float z)`	`void` Updates the head rotation.
`gvr_audio_surround_trigger_processing(gvr_audio_surround_context *api)`	`bool` Triggers the processing of data that has been input but not yet processed.

Typedefs

gvr_audio_surround_context

struct gvr_audio_surround_context_ gvr_audio_surround_context

Functions

gvr_audio_surround_add_interleaved_input

int64_t gvr_audio_surround_add_interleaved_input(
  gvr_audio_surround_context *api,
  const int16_t *input_buffer_ptr,
  int64_t num_samples
)

Adds interleaved audio data to the renderer.

If enough data has been provided for an output buffer to be generated then it will be immediately available via gvr_audio_surround_get_interleaved_output(). The input data is copied into an internal buffer which allows the caller to re-use the input buffer immediately. The available space in the internal buffer can be obtained via gvr_audio_surround_get_available_output_size_samples().

Details

Parameters

`api`	Pointer to a gvr_audio_surround_context.
`input_buffer_ptr`	Pointer to interleaved input data.
`num_samples`	Size of interleaved input data in samples.

Returns

The number of consumed samples.

gvr_audio_surround_clear

void gvr_audio_surround_clear(
  gvr_audio_surround_context *api
)

Removes all buffered input and processed output buffers from the buffer queues.

Details

Parameters

api

Pointer to a gvr_audio_surround_context.

gvr_audio_surround_create

gvr_audio_surround_context * gvr_audio_surround_create(
  gvr_audio_surround_format_type surround_format,
  int32_t num_input_channels,
  int32_t frames_per_processing,
  int sample_rate_hz
)

Creates and initializes a gvr_audio_surround_context.

Note that the returned instance must be deleted with gvr_audio_surround_destroy.

Details

Parameters

`surround_format`	Input surround format.
`num_input_channels`	Number of input channels. This must match with the selected surround rendering mode.
`frames_per_processing`	Number of frames required to trigger internal processing. Best performance is achieved for power of two sizes.
`sample_rate_hz`	Sample rate of audio buffers.

gvr_audio_surround_destroy

void gvr_audio_surround_destroy(
  gvr_audio_surround_context **api
)

Destroys a gvr_audio_surround_context that was previously created with gvr_audio_surround_create.

Details

Parameters

api

Pointer to a pointer to a gvr_audio_surround_context. The pointer will be set to NULL after destruction.

gvr_audio_surround_get_available_input_size_samples

int64_t gvr_audio_surround_get_available_input_size_samples(
  const gvr_audio_surround_context *api
)

Returns the number of samples the input buffer is currently able to consume.

Details

Parameters

api

Pointer to a gvr_audio_surround_context.

Returns

Number of available samples in input buffer.

gvr_audio_surround_get_available_output_size_samples

int64_t gvr_audio_surround_get_available_output_size_samples(
  const gvr_audio_surround_context *api
)

Returns the number of samples available in the output buffer.

Details

Parameters

api

Pointer to a gvr_audio_surround_context.

Returns

Number of available samples in output buffer.

gvr_audio_surround_get_interleaved_output

int64_t gvr_audio_surround_get_interleaved_output(
  gvr_audio_surround_context *api,
  int16_t *output_buffer_ptr,
  int64_t num_samples
)

Gets a processed output buffer in interleaved format.

Details

Parameters

`api`	Pointer to a gvr_audio_surround_context.
`output_buffer_ptr`	Pointer to allocated interleaved output buffer.
`num_samples`	Size of output buffer in samples.

Returns

The number of consumed samples.

gvr_audio_surround_set_head_rotation

void gvr_audio_surround_set_head_rotation(
  gvr_audio_surround_context *api,
  float w,
  float x,
  float y,
  float z
)

Updates the head rotation.

Details

Parameters

`api`	Pointer to a gvr_audio_surround_context.
`w`	W component of quaternion.
`x`	X component of quaternion.
`y`	Y component of quaternion.
`z`	Z component of quaternion.

gvr_audio_surround_trigger_processing

bool gvr_audio_surround_trigger_processing(
  gvr_audio_surround_context *api
)

Triggers the processing of data that has been input but not yet processed.

Note after calling this method, all processed output must be consumed via gvr_audio_surround_get_interleaved_output() before adding new input buffers.

Details

Parameters

api

Pointer to a gvr_audio_surround_context.

Returns

Whether any data was processed.