Sound::Play

Defined in: C4Sound.h

Plays a sound.

Prototype

SoundResult Play(void);

Description

Calling the Play function causes the sound to begin playing immediately. If the sound is already playing, then calling Play again has no effect.

If the sound is spatialized and has distance delay enabled (see Sound::SetSoundFlags), then the sound begins playing after a travel delay determined by the position of the listener. If the Doppler effect is also enabled, then the delay can be modified by the motion of both the sound and the listener so that the sound becomes audible at the correct time.

When the sound finishes playing, its completion procedure is invoked. A completion procedure can be installed by using the Completable::SetCompletionProc function.

The Play function returns one of the following sound result codes.

`kSoundOkay`	The sound has successfully begun playing.
`kSoundPlayFailed`	There are too many sounds playing. In this case, the sound object behaves as if it had played through and completed. The completion procedure is still invoked and nonpersistent sounds are still destroyed.

Special Considerations

If a sound object is nonpersistent (the default for non-streamed sounds), then it should never be referenced after the Play function has been called for it. Nonpersistent sound objects automatically self-destruct when they have finished playing, making any subsequent references to the object illegal.