Cue.Apply3D Method

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

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

Syntax

public void Apply3D (
         AudioListener listener,
         AudioEmitter emitter
)

Parameters

• listener
  The listener to calculate.
• emitter
  The emitter to calculate.

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 via 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.

//3D audio objects
AudioEmitter emitter = new AudioEmitter();
AudioListener listener = new AudioListener();
Vector3 entityPosition;

protected override void Initialize()
{
    base.Initialize();

    //Initialize audio objects
    engine = new AudioEngine("Content\\Audio\\3DAudio.xgs");
    soundBank = new SoundBank(engine, "Content\\Audio\\Sound Bank.xsb");
    waveBank = new WaveBank(engine, "Content\\Audio\\Wave Bank.xwb");

    //Can only apply 3d to GetCue, not PlayCue
    cue3d = soundBank.GetCue("cue3d");

    //Must call Apply3D before calling Play
    cue3d.Apply3D(listener, emitter);
    cue3d.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)
{
    if (GamePad.GetState(PlayerIndex.One).Buttons.Back == ButtonState.Pressed)
        this.Exit();

    //Move the emitter around in a 2d circle
    entityPosition.Z = (float)Math.Sin(gameTime.TotalGameTime.Seconds);
    entityPosition.X = (float)Math.Cos(gameTime.TotalGameTime.Seconds);

    emitter.Position = entityPosition;

    //Now apply the settings to the cue
    cue3d.Apply3D(listener, emitter);

    engine.Update();
    base.Update(gameTime);
}

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.

See Also

Tasks

How to: Apply Basic 3D Positional Effects to a Cue

Reference

Cue Class
Cue Members
Microsoft.Xna.Framework.Audio Namespace

Platforms

Xbox 360, Windows XP SP2, Windows Vista