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.

IPLAudioEffectState iplDirectEffectGetTail(IPLDirectEffect effect, IPLAudioBuffer *out)

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

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

Parameters:

effect – The direct 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.

IPLint32 iplDirectEffectGetTailSize(IPLDirectEffect effect)

Returns the number of tail samples remaining in a direct 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 direct effect.
Returns:: The number of tail samples remaining.

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[IPL_NUM_BANDS]: 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[IPL_NUM_BANDS]: 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.