Audio Buffers

Functions

IPLerror iplAudioBufferAllocate(IPLContext context, IPLint32 numChannels, IPLint32 numSamples, IPLAudioBuffer *audioBuffer)

Allocates an audio buffer.

All audio buffers are uncompressed PCM with 32-bit floating-point samples.

Internally, all audio buffers are stored deinterleaved for performance reasons. If your audio engine provides interleaved audio buffers, you must use iplAudioBufferInterleave and iplAudioBufferDeinterleave to explicitly convert to/from deinterleaved format. If your audio engine provides deinterleaved audio buffers, you can pass them directly using IPLAudioBuffer, thus avoiding the processing and memory overhead of an extra audio buffer.

Parameters

  • context – The context used to initialize Steam Audio.

  • numChannels – Number of channels.

  • numSamples – Number of samples per channel.

  • audioBuffer – The audio buffer to allocate.

Returns

Status code indicating whether or not the operation succeeded.

void iplAudioBufferFree(IPLContext context, IPLAudioBuffer *audioBuffer)

Frees an audio buffer.

Parameters

  • context – The context used to initialize Steam Audio.

  • audioBuffer – The audio buffer to free.

void iplAudioBufferInterleave(IPLContext context, IPLAudioBuffer *src, IPLfloat32 *dst)

Reads samples from an audio buffer and interleaves them into a user-provided array.

Parameters

  • context – The context used to initialize Steam Audio.

  • src – The audio buffer to read from.

  • dst – The interleaved array to write into.

void iplAudioBufferDeinterleave(IPLContext context, IPLfloat32 *src, IPLAudioBuffer *dst)

Writes interleaved samples from a user-provided array into an audio buffer.

Parameters

  • context – The context used to initialize Steam Audio.

  • src – The interleaved array to read from.

  • dst – The audio buffer to write into.

void iplAudioBufferMix(IPLContext context, IPLAudioBuffer *in, IPLAudioBuffer *mix)

Mixes one audio buffer into another.

Both audio buffers must have the same number of channels and samples.

Parameters

  • context – The context used to initialize Steam Audio.

  • in – The source audio buffer.

  • mix – The destination audio buffer, into which the source should be mixed.

void iplAudioBufferDownmix(IPLContext context, IPLAudioBuffer *in, IPLAudioBuffer *out)

Downmixes a multi-channel audio buffer into a mono audio buffer.

Both audio buffers must have the same number of samples.

Downmixing is performed by summing up the source channels and dividing the result by the number of source channels. If this is not the desired downmixing behavior, we recommend that downmixing be performed manually.

Parameters

  • context – The context used to initialize Steam Audio.

  • in – The source audio buffer.

  • out – The destination audio buffer.

void iplAudioBufferConvertAmbisonics(IPLContext context, IPLAmbisonicsType inType, IPLAmbisonicsType outType, IPLAudioBuffer *in, IPLAudioBuffer *out)

Converts an Ambisonic audio buffer from one Ambisonic format to another.

Both audio buffers must have the same number of samples.

This conversion can be applied in-place, i.e., in and out can be the same audio buffer.

Steam Audio’s “native” Ambisonic format is N3D, so for best performance, keep all Ambisonic data in N3D format except when exchanging data with your audio engine.

Parameters

  • context – The context used to initialize Steam Audio.

  • inType – Ambisonic format of in.

  • outType – Ambisonic format that out should be in.

  • in – The source audio buffer.

  • out – The destination audio buffer.

Structures

struct IPLSpeakerLayout

Describes a standard or custom speaker layout.

Public Members

IPLSpeakerLayoutType type

See IPLSpeakerLayoutType.

IPLint32 numSpeakers

Number of speakers.

Only for IPL_SPEAKERLAYOUTTYPE_CUSTOM.

IPLVector3 *speakers

Array of unit-length directions for each speaker.

Only for IPL_SPEAKERLAYOUTTYPE_CUSTOM.

struct IPLAudioSettings

Global settings for audio signal processing.

Public Members

IPLint32 samplingRate

Sampling rate, in Hz.

IPLint32 frameSize

Frame size, in samples.

Independent of number of channels.

struct IPLAudioBuffer

Describes an audio buffer.

All audio buffers passed to Steam Audio must be deinterleaved.

Public Members

IPLint32 numChannels

Number of channels.

IPLint32 numSamples

Number of samples per channel.

IPLfloat32 **data

Array of pointers to sample data for each channel.

Allocation of sample data is up to the user.

Enumerations

enum IPLSpeakerLayoutType

Supported speaker layouts.

Values:

enumerator IPL_SPEAKERLAYOUTTYPE_MONO

Mono.

enumerator IPL_SPEAKERLAYOUTTYPE_STEREO

Stereo (left, right).

enumerator IPL_SPEAKERLAYOUTTYPE_QUADRAPHONIC

Front left, front right, rear left, rear right.

enumerator IPL_SPEAKERLAYOUTTYPE_SURROUND_5_1

Front left, front right, front center, LFE, rear left, rear right.

enumerator IPL_SPEAKERLAYOUTTYPE_SURROUND_7_1

Front left, front right, front center, LFE, rear left, rear right, side left, side right.

enumerator IPL_SPEAKERLAYOUTTYPE_CUSTOM

User-defined speaker layout.

See IPLSpeakerLayout.

enum IPLAmbisonicsType

Supported channel ordering and normalization schemes for Ambisonic audio.

Values:

enumerator IPL_AMBISONICSTYPE_N3D

ACN channel ordering, orthonormal spherical harmonics.

enumerator IPL_AMBISONICSTYPE_SN3D

ACN channel ordering, semi-normalized spherical harmonics.

AmbiX format.

enumerator IPL_AMBISONICSTYPE_FUMA

Furse-Malham (B-format).

enum IPLAudioEffectState

States that an audio effect can be left in after processing a frame of audio.

Values:

enumerator IPL_AUDIOEFFECTSTATE_TAILREMAINING

One or more samples of tail remain in the effect’s internal buffers.

enumerator IPL_AUDIOEFFECTSTATE_TAILCOMPLETE

No tail remains in the effect’s internal buffers.