Ambisonics Binaural Effect

Typedefs

typedef struct _IPLAmbisonicsBinauralEffect_t *IPLAmbisonicsBinauralEffect

Renders Ambisonic audio using HRTF-based binaural rendering.

This results in more immersive spatialization of the Ambisonic audio as compared to using an Ambisonics panning effect, at the cost of slightly increased CPU usage.

Functions

IPLerror iplAmbisonicsBinauralEffectCreate(IPLContext context, IPLAudioSettings *audioSettings, IPLAmbisonicsBinauralEffectSettings *effectSettings, IPLAmbisonicsBinauralEffect *effect)

Creates an Ambisonics binaural effect.

Parameters

  • context – The context used to initialize Steam Audio.

  • audioSettings – Global audio processing settings.

  • effectSettings – The settings to use when creating the Ambisonics binaural effect.

  • effect – [out] The created Ambisonics binaural effect.

Returns

Status code indicating whether or not the operation succeeded.

IPLAmbisonicsBinauralEffect iplAmbisonicsBinauralEffectRetain(IPLAmbisonicsBinauralEffect effect)

Retains an additional reference to an Ambisonics binaural effect.

Parameters

effect – The Ambisonics binaural effect to retain a reference to.

Returns

The additional reference to the Ambisonics binaural effect.

void iplAmbisonicsBinauralEffectRelease(IPLAmbisonicsBinauralEffect *effect)

Releases a reference to an Ambisonics binaural effect.

Parameters

effect – The Ambisonics binaural effect to release a reference to.

void iplAmbisonicsBinauralEffectReset(IPLAmbisonicsBinauralEffect effect)

Resets the internal processing state of an Ambisonics binaural effect.

Parameters

effect – The Ambisonics binaural effect to reset.

IPLAudioEffectState iplAmbisonicsBinauralEffectApply(IPLAmbisonicsBinauralEffect effect, IPLAmbisonicsBinauralEffectParams *params, IPLAudioBuffer *in, IPLAudioBuffer *out)

Applies an Ambisonics binaural effect to an audio buffer.

This effect CANNOT be applied in-place.

Parameters

  • effect – The Ambisonics binaural effect to apply.

  • params – Parameters for applying the effect.

  • in – The input audio buffer. Must have as many channels as needed for the Ambisonics order specified in the parameters.

  • out – The output audio buffer. Must have 2 channels.

Returns

IPL_AUDIOEFFECTSTATE_TAILREMAINING if any tail samples remain in the effect’s internal buffers, or IPL_AUDIOEFFECTSTATE_TAILCOMPLETE otherwise.

Structures

struct IPLAmbisonicsBinauralEffectSettings

Settings used to create an Ambisonics binaural effect.

Public Members

IPLHRTF hrtf

The HRTF to use.

IPLint32 maxOrder

The maximum Ambisonics order that will be used by input audio buffers.

struct IPLAmbisonicsBinauralEffectParams

Parameters for applying an Ambisonics binaural effect to an audio buffer.

Public Members

IPLHRTF hrtf

The HRTF to use.

IPLint32 order

Ambisonic order of the input buffer.

May be less than the maxOrder specified when creating the effect, in which case the effect will process fewer input channels, reducing CPU usage.