Path Effect

Typedefs

typedef struct _IPLPathEffect_t *IPLPathEffect

Applies the result of simulating sound paths from the source to the listener.

Multiple paths that sound can take as it propagates from the source to the listener are combined into an Ambisonic sound field.

Functions

IPLerror iplPathEffectCreate(IPLContext context, IPLAudioSettings *audioSettings, IPLPathEffectSettings *effectSettings, IPLPathEffect *effect)

Creates a path effect.

Parameters:

  • context – The context used to initialize Steam Audio.

  • audioSettings – Global audio processing settings.

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

  • effect – [out] The created path effect.

Returns:

Status code indicating whether or not the operation succeeded.

IPLPathEffect iplPathEffectRetain(IPLPathEffect effect)

Retains an additional reference to a path effect.

Parameters:

effect – The path effect to retain a reference to.

Returns:

The additional reference to the path effect.

void iplPathEffectRelease(IPLPathEffect *effect)

Releases a reference to a path effect.

Parameters:

effect – The path effect to release a reference to.

void iplPathEffectReset(IPLPathEffect effect)

Resets the internal processing state of a path effect.

Parameters:

effect – The path effect to reset.

IPLAudioEffectState iplPathEffectApply(IPLPathEffect effect, IPLPathEffectParams *params, IPLAudioBuffer *in, IPLAudioBuffer *out)

Applies a path effect to an audio buffer.

This effect CANNOT be applied in-place.

Parameters:

  • effect – The path effect to apply.

  • params – Parameters for applying the effect.

  • in – The input audio buffer. Must have 1 channel.

  • out – The output audio buffer. Must have as many channels as needed for the Ambisonics order specified when creating the effect.

Returns:

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

IPLAudioEffectState iplPathEffectGetTail(IPLPathEffect effect, IPLAudioBuffer *out)

Retrieves a single frame of tail samples from a path effect’s internal buffers.

After the input to the path effect has stopped, this function must be called instead of iplPathEffectApply until the return value indicates that no more tail samples remain.

Parameters:

  • effect – The path effect.

  • out – The output audio buffer. Must have as many channels as needed for the Ambisonics order specified when creating the effect.

Returns:

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

IPLint32 iplPathEffectGetTailSize(IPLPathEffect effect)

Returns the number of tail samples remaining in a path effect’s internal buffers.

Tail samples are audio samples that should be played even after the input to the effect has stopped playing and no further input samples are available.

Parameters:

effect – The path effect.

Returns:

The number of tail samples remaining.

Structures

struct IPLPathEffectSettings

Settings used to create a path effect.

Public Members

IPLint32 maxOrder

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

IPLbool spatialize

If IPL_TRUE, then this effect will render spatialized audio into the output buffer.

If IPL_FALSE, this effect will render un-spatialized (and un-rotated) Ambisonic audio. Setting this to IPL_FALSE is mainly useful only if you plan to mix multiple Ambisonic buffers and/or apply additional processing to the Ambisonic audio before spatialization. If you plan to immediately spatialize the output of the path effect, setting this value to IPL_TRUE can result in significant performance improvements.

IPLSpeakerLayout speakerLayout

The speaker layout to use when spatializing.

Only used if spatialize is IPL_TRUE.

IPLHRTF hrtf

The HRTF to use when spatializing.

Only used if spatialize is IPL_TRUE.

struct IPLPathEffectParams

Parameters for applying a path effect to an audio buffer.

Public Members

IPLfloat32 eqCoeffs[IPL_NUM_BANDS]

3-band EQ coefficients for modeling frequency-dependent attenuation caused by paths bending around obstacles.

IPLfloat32 *shCoeffs

Ambisonic coefficients for modeling the directional distribution of sound reaching the listener.

The coefficients are specified in world-space, and must be rotated to match the listener’s orientation separately.

IPLint32 order

Ambisonic order of the output buffer.

May be less than the maximum order specified when creating the effect, in which case higher-order shCoeffs will be ignored, and CPU usage will be reduced.

IPLbool binaural

If IPL_TRUE, spatialize using HRTF-based binaural rendering.

Only used if spatialize was set to IPL_TRUE in IPLPathEffectSettings.

IPLHRTF hrtf

The HRTF to use when spatializing.

Only used if spatialize was set to IPL_TRUE in IPLPathEffectSettings and binaural is set to IPL_TRUE.

IPLCoordinateSpace3 listener

The position and orientation of the listener.

Only used if spatialize was set to IPL_TRUE in IPLPathEffectSettings and binaural is set to IPL_TRUE.

IPLbool normalizeEQ

If IPL_TRUE, the values in eqCoeffs will be normalized before being used, i.e., each value in eqCoeffs will be divided by the largest value in eqCoeffs.

This can help counteract overly-aggressive filtering due to a physics-based deviation model. If IPL_FALSE, the values in eqCoeffs will be used as-is.