# Surround Renderer API

# 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 ||
|---|---|
| `https://developers.google.com/vr/reference/android-ndk/group/audio-surround#group___audio_surround_1ga6487354c384b54049a7e0e415e23fa22` | typedef `struct gvr_audio_surround_context_` |

| ### Functions ||
|---|---|
| `https://developers.google.com/vr/reference/android-ndk/group/audio-surround#group___audio_surround_1ga9bc0ff92bdaa03f12d4ade5c0c9b27bf(gvr_audio_surround_context *api, const int16_t *input_buffer_ptr, int64_t num_samples)` | `int64_t` Adds interleaved audio data to the renderer. |
| `https://developers.google.com/vr/reference/android-ndk/group/audio-surround#group___audio_surround_1gaacbb3206db208b0b8d705745eafb0ce0(gvr_audio_surround_context *api)` | `void` Removes all buffered input and processed output buffers from the buffer queues. |
| `https://developers.google.com/vr/reference/android-ndk/group/audio-surround#group___audio_surround_1ga31f1e804fe02850fc105a64422a584ce(https://developers.google.com/vr/reference/android-ndk/group/types#group__types_1gab85687cb403c1ee4b589bb29d5b0dfa0 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. |
| `https://developers.google.com/vr/reference/android-ndk/group/audio-surround#group___audio_surround_1ga4d0df6153aa69ac3bdd8b6a5b7289c03(gvr_audio_surround_context **api)` | `void` Destroys a gvr_audio_surround_context that was previously created with gvr_audio_surround_create. |
| `https://developers.google.com/vr/reference/android-ndk/group/audio-surround#group___audio_surround_1gac06bedb0b155d54e1f4f721aa1ce144b(const gvr_audio_surround_context *api)` | `int64_t` Returns the number of samples the input buffer is currently able to consume. |
| `https://developers.google.com/vr/reference/android-ndk/group/audio-surround#group___audio_surround_1ga0435f5c19ce1900ab8ff0d45d0f25fc6(const gvr_audio_surround_context *api)` | `int64_t` Returns the number of samples available in the output buffer. |
| `https://developers.google.com/vr/reference/android-ndk/group/audio-surround#group___audio_surround_1ga51d3aeefaa2c480f66d7949d0888588c(gvr_audio_surround_context *api, int16_t *output_buffer_ptr, int64_t num_samples)` | `int64_t` Gets a processed output buffer in interleaved format. |
| `https://developers.google.com/vr/reference/android-ndk/group/audio-surround#group___audio_surround_1ga7bd29287df0cd57c51981406678782de(gvr_audio_surround_context *api, float w, float x, float y, float z)` | `void` Updates the head rotation. |
| `https://developers.google.com/vr/reference/android-ndk/group/audio-surround#group___audio_surround_1ga868300c2322231fbb2cec8f9dce8bede(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()](https://developers.google.com/vr/reference/android-ndk/group/audio-surround#group___audio_surround_1ga51d3aeefaa2c480f66d7949d0888588c). 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()](https://developers.google.com/vr/reference/android-ndk/group/audio-surround#group___audio_surround_1ga0435f5c19ce1900ab8ff0d45d0f25fc6).

<br />

| 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.

<br />

| 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.

<br />

| 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.

<br />

| 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.

<br />

| 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.

<br />

| 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.

<br />

| 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.

<br />

| 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()](https://developers.google.com/vr/reference/android-ndk/group/audio-surround#group___audio_surround_1ga51d3aeefaa2c480f66d7949d0888588c) before adding new input buffers.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `api` | Pointer to a gvr_audio_surround_context. | |
| **Returns** | Whether any data was processed. |