SoundBank.PlayCue Method (String, AudioListener, AudioEmitter)

Plays a cue using 3D positional information specified in an AudioListener and AudioEmitter.

Syntax

'Declaration
Public Sub PlayCue ( _
         name As String, _
         listener As AudioListener, _
         emitter As AudioEmitter _
)

public void PlayCue (
         string name,
         AudioListener listener,
         AudioEmitter emitter
)

public:
void PlayCue(
         String name,
         AudioListener listener,
         AudioEmitter emitter
)

Parameters

• name
  Type: String
  Name of the cue to play.
• listener
  Type: AudioListener
  AudioListener that specifies listener 3D audio information.
• emitter
  Type: AudioEmitter
  AudioEmitter that specifies emitter 3D audio information.

Exceptions

Exception type	Condition
ArgumentNullException	The name parameter is null.
InvalidOperationException	The name parameter specifies a cue that does not exist.

Remarks

The 3D audio information in the specified listener and emitter is used to initialize the cue instance and apply a static positional 3D audio effect (the direction from which the player hears the sound). Position and velocity are not updated over time; the 3D audio effects are calculated based on the emitter and listener position at the time of the call. Typically, this is used for short-lived sounds, or when the object and listener are stationary for the duration of the sound but placed somewhere in the world space.

For example, a sound that is played off to the right will continue to sound as if it is coming from the right, even if the listener moves or turns. For very short sounds, this may be imperceptable and thus acceptable. As another example, a voice that comes from the player's vehicle will always be the same distance and direction relative to the player, so static positioning in this case would be correct.

Attenuation and doppler effects, if enabled, will also be static for the duration of the sound.

To enable dynamic 3D audio when the emitter or listener are moving, use GetCue and Apply3D instead.

Each Cue instance that you play is unique, even when playing multiple cues with the same name. This allows multiple instances of the same Cue to play simultaneously.

Calling this method does not return a Cue object. Therefore, once the cue has started playing, it cannot be controlled through any methods of Cue, such as Stop, Pause, or Resume. The cue will play until its authored end, at which point it will be released.

Because no Cue object is retrieved, cues played using this method are also unable to use Apply3D to apply dynamic 3D effects to the cue. To retrieve a cue that you can control during playback, or apply dynamic 3D effects to, use GetCue.

Cue objects whose Playlist Type property has been specified as Interactive cannot be initiated with the PlayCue method. (This property is set in the XACT tool, within the Variation Playlist attributes of the Cue Properties.) Instead, retrieve the Cue object with the GetCue method, invoke its Play method, then release the object through the Dispose method.

Requirements

Namespace: Microsoft.Xna.Framework.Audio

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

See Also

Concepts

Sounds Overview

Reference

SoundBank.PlayCue Method
SoundBank Class
SoundBank Members
Microsoft.Xna.Framework.Audio Namespace

Platforms

Windows Phone