QSDK 1.1 Documentation
Main Page | Modules | Class Hierarchy | Alphabetical List | Compound List | File List | Compound Members | File Members | Related Pages

Q::SoundInstance Struct Reference
[Audio]

Instance required for using Sounds. More...

#include <Q/q.h>

Inheritance diagram for Q::SoundInstance:

Q::Instance Q::Object Q::ObjectBase List of all members.

Public Types

enum  ReplayMode {
  normal = 0,
  looping = 1,
  hit = 2
}
enum  LifetimeMode {
  removeNone = 0,
  removeInstance = 1,
  removeGroup = 2
}

Public Member Functions

 SoundInstance ()
 SoundInstance (const char *name)
Sound sound () const
bool multiChannel () const
bool playing () const
float volume () const
AudioEffect effectOverride () const
Utils::Result setMultiChannel (bool)
Utils::Result setVolume (float)
Utils::Result setEffectOverride (const AudioEffect &)
Utils::Result play (unsigned int sampleIndex=0, ReplayMode replay=normal, LifetimeMode life=removeNone)
Utils::Result stop ()

Static Public Member Functions

SoundInstance create (const char *name, const Sound &sound, const Group &group, const Database &db=Database())
SoundInstance find (const char *name)
ClassType classType ()
SoundInstance cast (const ObjectBase &)

Detailed Description

Instance required for using Sounds.

The SoundInstance is used to bind a sound to the scene graph, and to play those sounds. A SoundInstance object has a default volume of 0.0f.

See also:
QDemo2 production guide for guidance on how to build and import sound files in Q files.

Member Enumeration Documentation

enum Q::SoundInstance::LifetimeMode
 

This enumeration defines options to be passed to the play() method that indicate what should happen when the sound finishes playing, or when stop() is called.

Enumeration values:
removeNone  All objects are left intact at the end of play.
removeInstance  The SoundInstance is unplugged and destroyed.
removeGroup  The Group holding the SoundInstance is unplugged and destroyed. This implies that the SoundInstance is also unplugged and destroyed.

enum Q::SoundInstance::ReplayMode
 

This enumerated type defines options to be passed to the play() method that indicate how the sound is to be moved/replayed.

Enumeration values:
normal  The sound plays once and moves with the instance.
looping  The sound is looped and moves with the instance.
hit  The sound is played once and remains at the position it was played at regardless of whether or not the instance moves. In this mode the bounding box used is still the bounding box of the instance. You should not use hit for long sounds, but should create a new instance instead.

Constructor & Destructor Documentation

Q::SoundInstance::SoundInstance (   )  [inline]
 

Create a null sound instance reference.

Q::SoundInstance::SoundInstance (  const char *  name  ) 
 

Search the currently attached databases for a sound instance with the given name.

Member Function Documentation

SoundInstance Q::SoundInstance::cast (  const ObjectBase &   )  [static]
 

If the object referenced by obj is a sound instance, then return a suitable SoundInstance reference to the object.

Note:
Casting this object will cause it to be loaded from the database if it is not currently resident.

Reimplemented from Q::Instance.

ClassType Q::SoundInstance::classType (   )  [static]
 

Return the type for this class.

Reimplemented from Q::Instance.

SoundInstance Q::SoundInstance::create (  const char *  name,
const Sound &  sound,
const Group &  group,
const Database &  db = Database()
)  [static]
 

Create a new sound instance named name in the given database, db, (or the most recently attached read-write database if db is null). The sound sound is bound into the scene graph at location group.

AudioEffect Q::SoundInstance::effectOverride (   )  const
 

The effect override of this sound. This effect overrides any other AudioEffect objects that may affect this sound (Microphone, Environment, Sound).

SoundInstance Q::SoundInstance::find (  const char *  name  )  [static]
 

Search the currently attached databases for a sound instance with the given name and return that object, if it exists.

Reimplemented from Q::Instance.

bool Q::SoundInstance::multiChannel (   )  const
 

Return whether the sound instance is multi channel or single channel. A single channel sound instance will play only one sound at a time, i.e. calling SoundInstance::play again will cause the previous sound to stop. In a multi channel sound instance, calling SoundInstance::play twice will cause two sounds to be played simultaneously. The default for new sound instances is single channel.

Utils::Result Q::SoundInstance::play (  unsigned int  sampleIndex = 0,
ReplayMode  replay = normal,
LifetimeMode  life = removeNone
) 
 

Play a sample. In single channel mode, this will stop any sound that is currently playing. In multi channel mode, it will play on top of previous sounds.

The replay parameter indicates how the sound should move during playout and whether it should loop.

The life parameter indicates whether the Group and/or SoundInstance should be destroyed at the end of playing. This can be useful for lightweight temporary sounds so that the game code does not need to keep track of them and destroy them itself.

Note:
The playback of a SoundInstance is intimately linked to the Microphone objects that hear it and to the Scope it belongs to. Playback will stop if the Scope that contains the SoundInstance changes. If its Scope is dropped and a new one is created that includes its Zone, the playback is lost even if the Zone remained in scope, because the Scope where the playback was initiated in has been dropped. As for Microphone hearing, see playing for more details.

bool Q::SoundInstance::playing (   )  const
 

Checks whether the instance is playing. In multi channel mode, this method returns true if and only if at least one sound is playing.

Note:
AudioEffect objects carried by the Sound, the SoundInstance, the Microphone or the Environment of the instance's Zone affect the duration of the sound. For instance, pitch shift may speed up or slow down playback. As a consequence, playback length may be different depending on which Microphone is playing it. A SoundInstance is regarded as playing if it is playing for at least one microphone. If there is no microphone around, it is playing for its theoric duration modulated by the closest AudioEffect.

Utils::Result Q::SoundInstance::setEffectOverride (  const AudioEffect &   ) 
 

Set the effect of this sound. This effect overrides any other AudioEffect objects that may affect this sound (Microphone, Environment, Sound).

Utils::Result Q::SoundInstance::setMultiChannel (  bool   ) 
 

Set whether the sound instance is multi channel or single channel.

Utils::Result Q::SoundInstance::setVolume (  float   ) 
 

Set the volume of the sound instance. In multi channel mode, this sets the volume of all playing sounds. Volume is represented as an attenuation in decibels (dBFS). 0.0f and above is no attenuation.

Sound Q::SoundInstance::sound (   )  const
 

Return the Sound associated with this instance.

Utils::Result Q::SoundInstance::stop (   ) 
 

Stop all playing samples. In multi channel mode, this stops all the sounds at once.

float Q::SoundInstance::volume (   )  const
 

Returns the volume of the instance. In multi channel mode, this will set the volume of all the playing samples. Volume is represented as an attenuation in decibels (dBFS). 0.0f and above is no attenuation.

Return to QSDK documentation Contents page. Contact details for support, information and fault-reporting.
Qube Software Limited © 2000-2004