nw::snd::SoundHandle Class

Header file: nw/snd/snd_SoundHandle.h

Syntax

class SoundHandle

Description

A handle class used to control sounds that are played back.

To associate a sound handle with a sound, call SoundArchivePlayer::PrepareSound or SoundArchivePlayer::StartSound.

If the handle is already associated with another sound, this association is removed, and it is newly associated with the sound to be played back.

The association between the handle and the sound is removed, and that handle can no longer control that sound in the following situations:

- Playback stops at the end of the sound.
- Stop is called at fade frame 0.
- Stop is called when one or more fade frames have been specified and playback stops after only that number of frames has elapsed.
- SoundHandle::DetachSound is called explicitly.

As a result, you can check whether a sound has stopped after being played through to the end by monitoring IsAttachedSound each frame. However, you must take into consideration the effect of sounds that were stopped by calls to Stop, explicit calls to DetachSound, or determinations made about player priorities.

For determinations made about player priorities, refer to the "Priority Operations" chapter of the Sound System Manual.

There are three types of sounds: sequence sounds, stream sounds, and wave sounds. The SoundHandle class can be used to handle operations that are common to all these sounds.

The SequenceSoundHandle, StreamSoundHandle, and WaveSoundHandle classes provide operations specific to each sound type that cannot be handled with the SoundHandle class.

Member Functions

Constructors/Destructors
SoundHandle Constructor.
~SoundHandle Destructor.
Play, Stop, Pause, Resume
StartPrepared Plays the sound whose preparation for playback has completed.
Stop Stops the sound.
Pause Pauses or restarts a sound.
IsPrepared Checks whether preparation for sound playback is complete.
IsPause Checks whether the sound is currently paused.
FadeIn Fades in the sound when playback starts.
GetRemainingFadeFrames Obtains the number of frames that remain until the fade-in or fade-out completes.
GetRemainingPauseFadeFrames Obtains the number of remaining frames until the fade completes when the system is paused.
Parameters
SetVolume Changes the volume of the sound.
SetPitch Changes the pitch of the sound.
SetPan Changes the pan (right/left location) of the sound.
SetSurroundPan Changes the surround pan (front-to-back location) of the sound.
SetLpfFreq Changes the low pass filter cutoff value of the sound.
SetBiquadFilter Changes the biquad filter setting for sound.
SetPlayerPriority Changes the player priority.
Output Parameters
SetMainSend Changes the main send volume of the sound.
SetFxSend Changes the effect send volume of the sound.
Handle Operations
IsAttachedSound Checks whether there is a sound associated with the handle.
DetachSound Frees sounds from handles.
SetId Sets the ID of a sound.
GetId Obtains the ID of a sound.

See Also

SoundArchivePlayer Class
SequenceSoundHandle Class
StreamSoundHandle Class
WaveSoundHandle Class

Revision History

2010/04/28
Added the conditions under which handles and sounds will cease to be associated. Added information about how to determine if a sound has played through to completion.
2010/01/25
Added information about the SequenceSoundHandle, StreamSoundHandle, and WaveSoundHandle classes.
2010/01/15
Initial version.

CONFIDENTIAL