Export (0) Print
Expand All

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)

public void Apply3D (
         AudioListener listener,
         AudioEmitter emitter
)

Parameters

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

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

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). For information on doing so, see How To: Apply Attenuation and Doppler 3D Audio Effects.

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();
Cue cue;

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");

    // 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)
{
    // Allow the game to exit.
    if (GamePad.GetState(PlayerIndex.One).Buttons.Back == 
        ButtonState.Pressed)
        this.Exit();

    // Move the object around in a circle.
    Vector3 objectPos = new Vector3(
        (float)Math.Cos(gameTime.TotalGameTime.Seconds) / 2,
        0,
        (float)Math.Sin(gameTime.TotalGameTime.Seconds));

    // Apply 3D settings to the cue.
    emitter.Position = objectPos;
    cue.Apply3D(listener, emitter);

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

    base.Update(gameTime);
}

Xbox 360, Windows XP SP2, Windows Vista

Community Additions

ADD
Show:
© 2014 Microsoft