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, orIPL_AUDIOEFFECTSTATE_TAILCOMPLETE
otherwise.
Structures
-
struct IPLPathEffectSettings
Settings used to create a path effect.
Public Members
-
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 toIPL_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 toIPL_TRUE
can result in significant performance improvements.
-
IPLSpeakerLayout speakerLayout
The speaker layout to use when spatializing.
Only used if
spatialize
isIPL_TRUE
.
-
IPLbool spatialize
-
struct IPLPathEffectParams
Parameters for applying a path effect to an audio buffer.
Public Members
-
IPLfloat32 eqCoeffs[3]
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 toIPL_TRUE
inIPLPathEffectSettings
.
-
IPLHRTF hrtf
The HRTF to use when spatializing.
Only used if
spatialize
was set toIPL_TRUE
inIPLPathEffectSettings
andbinaural
is set toIPL_TRUE
.
-
IPLCoordinateSpace3 listener
The position and orientation of the listener.
Only used if
spatialize
was set toIPL_TRUE
inIPLPathEffectSettings
andbinaural
is set toIPL_TRUE
.
-
IPLfloat32 eqCoeffs[3]