Reflection Effect¶

Typedefs¶

typedef struct _IPLReflectionEffect_t *IPLReflectionEffect¶

Applies the result of physics-based reflections simulation to an audio buffer.

The result is encoded in Ambisonics, and can be decoded using an Ambisonics decode effect.

typedef struct _IPLReflectionMixer_t *IPLReflectionMixer¶

Mixes the outputs of multiple reflection effects, and generates a single sound field containing all the reflected sound reaching the listener.

Using this is optional. Depending on the reflection effect algorithm used, a reflection mixer may provide a reduction in CPU usage.

typedef struct _IPLReflectionEffectIR_t *IPLReflectionEffectIR¶

A multi-channel impulse response for use with a reflection effect.

Steam Audio creates and manages objects of this type internally, your application only needs to pass handles to these objects to the appropriate Steam Audio API functions.

Functions¶

IPLerror iplReflectionEffectCreate(IPLContext context, IPLAudioSettings *audioSettings, IPLReflectionEffectSettings *effectSettings, IPLReflectionEffect *effect)¶

Creates a reflection effect.

Parameters

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

Returns

Status code indicating whether or not the operation succeeded.

IPLReflectionEffect iplReflectionEffectRetain(IPLReflectionEffect effect)¶

Retains an additional reference to a reflection effect.

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

void iplReflectionEffectRelease(IPLReflectionEffect *effect)¶

Releases a reference to a reflection effect.

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

void iplReflectionEffectReset(IPLReflectionEffect effect)¶

Resets the internal processing state of a reflection effect.

Parameters: effect – The reflection effect to reset.

IPLAudioEffectState iplReflectionEffectApply(IPLReflectionEffect effect, IPLReflectionEffectParams *params, IPLAudioBuffer *in, IPLAudioBuffer *out, IPLReflectionMixer mixer)¶

Applies a reflection effect to an audio buffer.

This effect CANNOT be applied in-place.

Parameters

effect – The reflection 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 the impulse response specified when creating the effect (for convolution, hybrid, and TAN) or at least 1 channel (for parametric).
mixer – If this is non-null, then the output of this effect will be mixed into the given mixer object instead of being returned in the out parameter. The mixed output can be retrieved elsewhere in the audio pipeline using iplReflectionMixerApply. This can have a performance benefit if using convolution. If using TAN, specifying a mixer is required.

Returns

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

IPLerror iplReflectionMixerCreate(IPLContext context, IPLAudioSettings *audioSettings, IPLReflectionEffectSettings *effectSettings, IPLReflectionMixer *mixer)¶

Creates a reflection effect mixer.

Parameters

context – The context used to initialize Steam Audio.
audioSettings – Global audio processing settings.
effectSettings – The settings used when creating the reflection effects that will be mixed into this reflection mixer.
mixer – [out] The created reflection mixer.

Returns

Status code indicating whether or not the operation succeeded.

IPLReflectionMixer iplReflectionMixerRetain(IPLReflectionMixer mixer)¶

Retains an additional reference to a reflection mixer.

Parameters: mixer – The reflection mixer to retain a reference to.
Returns: The additional reference to the reflection mixer.

void iplReflectionMixerRelease(IPLReflectionMixer *mixer)¶

Releases a reference to a reflection mixer.

Parameters: mixer – The reflection mixer to release a reference to.

void iplReflectionMixerReset(IPLReflectionMixer mixer)¶

Resets the internal processing state of a reflection mixer.

Parameters: mixer – The reflection mixer to reset.

IPLAudioEffectState iplReflectionMixerApply(IPLReflectionMixer mixer, IPLReflectionEffectParams *params, IPLAudioBuffer *out)¶

Retrieves the contents of a reflection mixer and places it into an audio buffer.

Parameters

mixer – The reflection mixer to retrieve audio from.
params – Parameters for applying the effect.
out – The output audio buffer. Must have as many channels as the impulse response specified when creating the mixer.

Returns

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

Structures¶

struct IPLReflectionEffectSettings¶

Settings used to create a reflection effect.

Public Members

IPLReflectionEffectType type¶: Type of reflection effect algorithm to use.

IPLint32 irSize¶: Number of samples per channel in the IR.

IPLint32 numChannels¶: Number of channels in the IR.

struct IPLReflectionEffectParams¶

Parameters for applying a reflection effect to an audio buffer.

Public Members

IPLReflectionEffectType type¶: Type of reflection effect algorithm to use.

IPLReflectionEffectIR ir¶

The impulse response.

For IPL_REFLECTIONEFFECTTYPE_CONVOLUTION or IPL_REFLECTIONEFFECTTYPE_HYBRID.

IPLfloat32 reverbTimes[3]¶

3-band reverb decay times (RT60).

For IPL_REFLECTIONEFFECTTYPE_PARAMETRIC or IPL_REFLECTIONEFFECTTYPE_HYBRID.

IPLfloat32 eq[3]¶

3-band EQ coefficients applied to the parametric part to ensure smooth transition.

For IPL_REFLECTIONEFFECTTYPE_HYBRID.

IPLint32 delay¶

Samples after which parametric part starts.

For IPL_REFLECTIONEFFECTTYPE_HYBRID.

IPLint32 numChannels¶

Number of IR channels to process.

May be less than the number of channels specified when creating the effect, in which case CPU usage will be reduced.

IPLint32 irSize¶

Number of IR samples per channel to process.

May be less than the number of samples specified when creating the effect, in which case CPU usage will be reduced.

IPLTrueAudioNextDevice tanDevice¶

The TrueAudio Next device to use for convolution processing.

For IPL_REFLECTIONEFFECTTYPE_TAN.

IPLint32 tanSlot¶

The TrueAudio Next slot index to use for convolution processing.

The slot identifies the IR to use. For IPL_REFLECTIONEFFECTTYPE_TAN.

Enumerations¶

enum IPLReflectionEffectType¶

Type of reflection effect algorithm to use.

Values:

enumerator IPL_REFLECTIONEFFECTTYPE_CONVOLUTION¶

Multi-channel convolution reverb.

Reflections reaching the listener are encoded in an Impulse Response (IR), which is a filter that records each reflection as it arrives. This algorithm renders reflections with the most detail, but may result in significant CPU usage. Using a reflection mixer with this algorithm provides a reduction in CPU usage.

enumerator IPL_REFLECTIONEFFECTTYPE_PARAMETRIC¶

Parametric (or artificial) reverb, using feedback delay networks.

The reflected sound field is reduced to a few numbers that describe how reflected energy decays over time. This is then used to drive an approximate model of reverberation in an indoor space. This algorithm results in lower CPU usage, but cannot render individual echoes, especially in outdoor spaces. A reflection mixer cannot be used with this algorithm.

enumerator IPL_REFLECTIONEFFECTTYPE_HYBRID¶

A hybrid of convolution and parametric reverb.

The initial portion of the IR is rendered using convolution reverb, but the later part is used to estimate a parametric reverb. The point in the IR where this transition occurs can be controlled. This algorithm allows a trade-off between rendering quality and CPU usage. An reflection mixer cannot be used with this algorithm.

enumerator IPL_REFLECTIONEFFECTTYPE_TAN¶

Multi-channel convolution reverb, using AMD TrueAudio Next for GPU acceleration.

This algorithm is similar to IPL_REFLECTIONEFFECTYPE_CONVOLUTION, but uses the GPU instead of the CPU for processing, allowing significantly more sources to be processed. A reflection mixer must be used with this algorithm, because the GPU will process convolution reverb at a single point in your audio processing pipeline.