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.