Binaural Effect

Typedefs

typedef struct _IPLBinauralEffect_t *IPLBinauralEffect

Spatializes a point source using an HRTF, based on the 3D position of the source relative to the listener.

The source audio can be 1- or 2-channel; in either case all input channels are spatialized from the same position.

Functions

IPLerror iplBinauralEffectCreate(IPLContext context, IPLAudioSettings *audioSettings, IPLBinauralEffectSettings *effectSettings, IPLBinauralEffect *effect)

Creates a binaural effect.

Parameters:

context – The context used to initialize Steam Audio.
audioSettings – Global audio processing settings.
effectSettings – The settings to use when creating the binaural effect.
effect – [out] The created binaural effect.

Returns:

Status code indicating whether or not the operation succeeded.

IPLBinauralEffect iplBinauralEffectRetain(IPLBinauralEffect effect)

Retains an additional reference to a binaural effect.

Parameters:: effect – The binaural effect to retain a reference to.
Returns:: The additional reference to the binaural effect.

void iplBinauralEffectRelease(IPLBinauralEffect *effect)

Releases a reference to a binaural effect.

Parameters:: effect – The binaural effect to release a reference to.

void iplBinauralEffectReset(IPLBinauralEffect effect)

Resets the internal processing state of a binaural effect.

Parameters:: effect – The binaural effect to reset.

IPLAudioEffectState iplBinauralEffectApply(IPLBinauralEffect effect, IPLBinauralEffectParams *params, IPLAudioBuffer *in, IPLAudioBuffer *out)

Applies a binaural effect to an audio buffer.

This effect CANNOT be applied in-place.

Parameters:

effect – The binaural effect to apply.
params – Parameters for applying the effect.
in – The input audio buffer. Must be 1- or 2-channel.
out – The output audio buffer. Must be 2-channel.

Returns:

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

Structures

struct IPLBinauralEffectSettings

Settings used to create a binaural effect.

Public Members

IPLHRTF hrtf: The HRTF to use.

struct IPLBinauralEffectParams

Parameters for applying a binaural effect to an audio buffer.

Public Members

IPLVector3 direction: Unit vector pointing from the listener towards the source.

IPLHRTFInterpolation interpolation: The interpolation technique to use.

IPLfloat32 spatialBlend

Amount to blend input audio with spatialized audio.

When set to 0, output audio is not spatialized at all and is close to input audio. If set to 1, output audio is fully spatialized.

IPLHRTF hrtf: The HRTF to use.

IPLfloat32 *peakDelays

Base address of an array into which to write the left- and right-ear peak delays for the HRTF used to spatialize the input audio.

Memory for this array must be allocated and managed by the caller. Can be NULL, in which case peak delays will not be written.

Enumerations

enum IPLHRTFInterpolation

Techniques for interpolating HRTF data.

This is used when rendering a point source whose position relative to the listener is not contained in the measured HRTF data.

Values:

enumerator IPL_HRTFINTERPOLATION_NEAREST

Nearest-neighbor filtering, i.e., no interpolation.

Selects the measurement location that is closest to the source’s actual location.

enumerator IPL_HRTFINTERPOLATION_BILINEAR

Bilinear filtering.

Incurs a relatively high CPU overhead as compared to nearest-neighbor filtering, so use this for sounds where it has a significant benefit. Typically, bilinear filtering is most useful for wide-band noise-like sounds, such as radio static, mechanical noise, fire, etc.