Virtual Surround Effect

Typedefs

typedef struct _IPLVirtualSurroundEffect_t *IPLVirtualSurroundEffect

Spatializes multi-channel speaker-based audio (e.g., stereo, quadraphonic, 5.1, or 7.1) using HRTF-based binaural rendering.

The audio signal for each speaker is spatialized from a point in space corresponding to the speaker’s location. This allows users to experience a surround sound mix over regular stereo headphones.

Virtual surround is also a fast way to get approximate binaural rendering. All sources can be panned to some surround format (say, 7.1). After the sources are mixed, the mix can be rendered using virtual surround. This can reduce CPU usage, at the cost of spatialization accuracy.

Functions

IPLerror iplVirtualSurroundEffectCreate(IPLContext context, IPLAudioSettings *audioSettings, IPLVirtualSurroundEffectSettings *effectSettings, IPLVirtualSurroundEffect *effect)

Creates a virtual surround effect.

Parameters

  • context – The context used to initialize Steam Audio.

  • audioSettings – Global audio processing settings.

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

  • effect – [out] The created virtual surround effect.

Returns

Status code indicating whether or not the operation succeeded.

IPLVirtualSurroundEffect iplVirtualSurroundEffectRetain(IPLVirtualSurroundEffect effect)

Retains an additional reference to a virtual surround effect.

Parameters

effect – The virtual surround effect to retain a reference to.

Returns

The additional reference to the virtual surround effect.

void iplVirtualSurroundEffectRelease(IPLVirtualSurroundEffect *effect)

Releases a reference to a virtual surround effect.

Parameters

effect – The virtual surround effect to release a reference to.

void iplVirtualSurroundEffectReset(IPLVirtualSurroundEffect effect)

Resets the internal processing state of a virtual surround effect.

Parameters

effect – The virtual surround effect to reset.

IPLAudioEffectState iplVirtualSurroundEffectApply(IPLVirtualSurroundEffect effect, IPLVirtualSurroundEffectParams *params, IPLAudioBuffer *in, IPLAudioBuffer *out)

Applies a virtual surround effect to an audio buffer.

This effect CANNOT be applied in-place.

Parameters

  • effect – The virtual surround effect to apply.

  • params – Parameters for applying the effect.

  • in – The input audio buffer. Must have as many channels as needed for the speaker layout specified when creating the virtual surround effect.

  • out – The output audio buffer. Must be 2-channel.

Returns

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

Structures

struct IPLVirtualSurroundEffectSettings

Settings used to create a virtual surround effect.

Public Members

IPLSpeakerLayout speakerLayout

The speaker layout that will be used by input audio buffers.

IPLHRTF hrtf

The HRTF to use.

struct IPLVirtualSurroundEffectParams

Parameters for applying a virtual surround effect to an audio buffer.

Public Members

IPLHRTF hrtf

The HRTF to use.