Direct Effect

Typedefs

typedef struct _IPLDirectEffect_t *IPLDirectEffect

Filters and attenuates an audio signal based on various properties of the direct path between a point source and the listener.

Functions

IPLerror iplDirectEffectCreate(IPLContext context, IPLAudioSettings *audioSettings, IPLDirectEffectSettings *effectSettings, IPLDirectEffect *effect)

Creates a direct effect.

Parameters

• context – The context used to initialize Steam Audio.

• audioSettings – Global audio processing settings.

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

• effect – [out] The created direct effect.

Returns

Status code indicating whether or not the operation succeeded.

IPLDirectEffect iplDirectEffectRetain(IPLDirectEffect effect)

Retains an additional reference to a direct effect.

Parameters

effect – The direct effect to retain a reference to.

Returns

The additional reference to the direct effect.

void iplDirectEffectRelease(IPLDirectEffect *effect)

Releases a reference to a direct effect.

Parameters

effect – The direct effect to release a reference to.

void iplDirectEffectReset(IPLDirectEffect effect)

Resets the internal processing state of a direct effect.

Parameters

effect – The direct effect to reset.

IPLAudioEffectState iplDirectEffectApply(IPLDirectEffect effect, IPLDirectEffectParams *params, IPLAudioBuffer *in, IPLAudioBuffer *out)

Applies a direct effect to an audio buffer.

This effect CAN be applied in-place.

Parameters

• effect – The direct effect to apply.

• params – Parameters for applying the effect.

• in – The input audio buffer. Must have as many channels as specified when creating the effect.

• out – The output audio buffer. Must have as many channels as 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.

Structures

struct IPLDirectEffectSettings

Settings used to create a direct effect.

Public Members

IPLint32 numChannels

Number of channels that will be used by input and output buffers.

struct IPLDirectEffectParams

Parameters for applying a direct effect to an audio buffer.

Public Members

IPLDirectEffectFlags flags

Flags indicating which direct path effects to apply.

IPLTransmissionType transmissionType

Mode of applying transmission effect, if IPL_DIRECTEFFECTFLAGS_APPLYTRANSMISSION is enabled.

IPLfloat32 distanceAttenuation

Value of distance attenuation, between 0 and 1.

IPLfloat32 airAbsorption[3]

3-band EQ coefficients for air absorption, each between 0 and 1.

IPLfloat32 directivity

Value of directivity term, between 0 and 1.

IPLfloat32 occlusion

Value of occlusion factor, between 0 and 1.

IPLfloat32 transmission[3]

3-band EQ coefficients for transmission, each between 0 and 1.

Enumerations

enum IPLDirectEffectFlags

Flags indicating which direct path parameters to apply.

Values:

enumerator IPL_DIRECTEFFECTFLAGS_APPLYDISTANCEATTENUATION

Apply frequency-independent distance attenuation.

enumerator IPL_DIRECTEFFECTFLAGS_APPLYAIRABSORPTION

Apply frequency-dependent air absorption as a function of distance.

enumerator IPL_DIRECTEFFECTFLAGS_APPLYDIRECTIVITY

Apply attenuation due to source directivity pattern.

enumerator IPL_DIRECTEFFECTFLAGS_APPLYOCCLUSION

Apply occlusion.

enumerator IPL_DIRECTEFFECTFLAGS_APPLYTRANSMISSION

Apply transmission along with occlusion.

enum IPLTransmissionType

Modes of applying transmission effects.

Values:

enumerator IPL_TRANSMISSIONTYPE_FREQINDEPENDENT

Transmission is frequency-independent.

enumerator IPL_TRANSMISSIONTYPE_FREQDEPENDENT

Transmission is frequency-dependent.