Cue.Apply3D Method

Article
08/15/2012

Calculates the 3D audio values between an AudioEmitter and an AudioListener object, and applies the resulting values to this Cue.

Syntax

'Declaration
Public Sub Apply3D ( _
         listener As AudioListener, _
         emitter As AudioEmitter _
)

public void Apply3D (
         AudioListener listener,
         AudioEmitter emitter
)

public:
void Apply3D(
         AudioListener listener,
         AudioEmitter emitter
)

Parameters

listener
Type: AudioListener
The listener to calculate.
emitter
Type: AudioEmitter
The emitter to calculate.

Exceptions

Exception type	Condition
ArgumentNullException	Both listener and emitter must be non-null.
InvalidOperationException	You must call the Cue.Apply3D method before you call the Cue.Play method.

Remarks

If you want to apply 3D effects to a Cue, you must call this method before you call the Play method. Not doing so will throw an exception the next time Apply3D is called.

Calling this method automatically sets the speaker mix for any sound played by this cue to a value calculated by the difference in Position values between listener and emitter. In preparation for the mix, the sound is converted to monoaural. Any stereo information in the sound is discarded.

Calling this method sets the cue-instance variables Distance, DopplerPitchScalar, and OrientationAngle to the resulting values of the 3D calculation between listener and emitter. These values do not modify sound attenuation over distance, or pitch shifting using Doppler values, on their own. You must set up a Runtime Parameter Curve (RPC) that defines how to map the cue-instance variable values to pitch and volume shifts, and associate sounds to these curves in the Microsoft Cross-Platform Audio Creation Tool (XACT). .

Example

When first retrieving a Cue object using SoundBank.GetCue, you must call Cue.Apply3D before calling Cue.Play, if you want to apply 3D effects to the cue.

// Get the cue and play it.
// For 3D cues, you must call Apply3D before calling Play.
cue = soundBank.GetCue("buzz");
cue.Apply3D(listener, emitter);
cue.Play();

Once you have called Cue.Apply3D then Cue.Play, you can call Cue.Apply3D each Game.Update loop after specifying new positions and velocities for the listener and emitter objects.

protected override void Update(GameTime gameTime)
{
    
    // Apply 3D settings to the cue.
    emitter.Position = objectPos;

    cue.Apply3D(listener, emitter);

    // Update the audio engine
    engine.Update();

    base.Update(gameTime);
    
}

Requirements

Namespace: Microsoft.Xna.Framework.Audio

Assembly: Microsoft.Xna.Framework (in microsoft.xna.framework.dll)

Platforms

Windows Phone

Share via