Panning Effect

Typedefs

typedef struct _IPLPanningEffect_t *IPLPanningEffect

Pans a single-channel point source to a multi-channel speaker layout based on the 3D position of the source relative to the listener.

Functions

IPLerror iplPanningEffectCreate(IPLContext context, IPLAudioSettings *audioSettings, IPLPanningEffectSettings *effectSettings, IPLPanningEffect *effect)

Creates a panning effect.

Parameters:

  • context – The context used to initialize Steam Audio.

  • audioSettings – Global audio processing settings.

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

  • effect – [out] The created panning effect.

Returns:

Status code indicating whether or not the operation succeeded.

IPLPanningEffect iplPanningEffectRetain(IPLPanningEffect effect)

Retains an additional reference to a panning effect.

Parameters:

effect – The panning effect to retain a reference to.

Returns:

The additional reference to the panning effect.

void iplPanningEffectRelease(IPLPanningEffect *effect)

Releases a reference to a panning effect.

Parameters:

effect – The panning effect to release a reference to.

void iplPanningEffectReset(IPLPanningEffect effect)

Resets the internal processing state of a panning effect.

Parameters:

effect – The panning effect to reset.

IPLAudioEffectState iplPanningEffectApply(IPLPanningEffect effect, IPLPanningEffectParams *params, IPLAudioBuffer *in, IPLAudioBuffer *out)

Applies a panning effect to an audio buffer.

This effect CANNOT be applied in-place.

Parameters:

  • effect – The panning effect to apply.

  • params – Parameters for applying the effect.

  • in – The input audio buffer. Must be 1-channel.

  • out – The output audio buffer. Must have as many channels as needed for the speaker layout specified when creating the panning effect. For example, if the speaker layout is IPL_SPEAKERLAYOUTTYPE_SURROUND_5_1, the output buffer must contain 6 channels.

Returns:

IPL_AUDIOEFFECTSTATE_TAILCOMPLETE to indicate that this effect does not generate any tail samples.

IPLAudioEffectState iplPanningEffectGetTail(IPLPanningEffect effect, IPLAudioBuffer *out)

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

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

Parameters:

  • effect – The panning effect.

  • out – The output audio buffer. Must have as many channels as needed for the speaker layout specified when creating the panning effect. For example, if the speaker layout is IPL_SPEAKERLAYOUTTYPE_SURROUND_5_1, the output buffer must contain 6 channels.

Returns:

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

IPLint32 iplPanningEffectGetTailSize(IPLPanningEffect effect)

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

Returns:

The number of tail samples remaining.

Structures

struct IPLPanningEffectSettings

Settings used to create a panning effect.

Public Members

IPLSpeakerLayout speakerLayout

The speaker layout to pan input audio to.

struct IPLPanningEffectParams

Parameters for applying a panning effect to an audio buffer.

Public Members

IPLVector3 direction

Unit vector pointing from the listener towards the source.