SFXSystem Class Reference

#include <sfxSystem.h>

Detailed Description

This class provides access to the sound system.

There are a few script preferences that are used by the sound providers.

$pref::SFX::frequency - This is the playback frequency for the primary sound buffer used for mixing. Although most providers will reformat on the fly, for best quality and performance match your sound files to this setting.

$pref::SFX::bitrate - This is the playback bitrate for the primary sound buffer used for mixing. Although most providers will reformat on the fly, for best quality and performance match your sound files to this setting.

Public Types

NumChannels = 32

The number of volume channels available in the system.

NumChannelBits = 6

The number of bits needed to write a channel value to the network stream.

enum {
NumChannels = 32,
NumChannelBits = 6
}

Public Member Functions

void _update ()

This is only public so that it can be called by the game update loop.

bool createDevice (const char *providerName, const char *deviceName, bool useHardware, S32 maxBuffers, bool changeDevice=false)

This initializes a new device.

const char * getDeviceInfoString ()

Returns the current device information or NULL if no device is present.

void deleteDevice ()

This destroys the current device.

bool hasDevice () const

Returns true if a device is allocated.

SFXSource * createSource (const SFXProfile *profile, const MatrixF *transform=NULL, const VectorF *velocity=NULL)

Used to create new sound sources from a sound profile.

SFXSource * playOnce (const SFXProfile *profile, const MatrixF *transform=NULL, const VectorF *velocity=NULL)

Creates a source which when it finishes playing will auto delete itself.

SFXListener & getListener ()

Returns the one and only listener object.

void stopAll (S32 channel=-1)

Stops all the sounds in a particular channel or across all channels if the channel is -1.

F32 getChannelVolume (U32 channel) const

Returns the volume for the specified sound channel.

void setChannelVolume (U32 channel, F32 volume)

Sets the volume on the specified sound channel, changing the volume on all sources in that channel.

F32 getMasterVolume () const

Returns the system master volume level.

void setMasterVolume (F32 volume)

Sets the master volume level, changing the volume of all sources.

Static Public Member Functions

static SFXSystem * getSingleton ()

Returns the one an only instance of the SFXSystem unless it hasn't been initialized or its been disabled in your build.

static void init ()

This is called from initialization to prepare the sound system singleton.

static void destroy ()

This is called after Sim::shutdown() in shutdownLibraries() to free the sound system singlton.

Protected Member Functions

SFXSystem ()

The protected constructor.

~SFXSystem ()

The non-virtual destructor.

void _updateSources ()

Called to reprioritize and reassign buffers as sources change state, volumes are adjusted, and the listener moves around.

void _assignVoices ()

This called to reprioritize and reassign voices to sources.

void _onRemoveSource (SFXSource *source)

This is called from the source to properly clean itself up.

SFXBuffer * _createBuffer (SFXProfile *profile)

Called from SFXProfile to create a device specific sound buffer used in conjunction with a voice in playback.

Protected Attributes

SFXDevice * mDevice

The current output sound device initialized and ready to play back.

SFXSourceVector mSources

This contains all the sources currently created in the system.

SFXSourceVector mPlayOnceSources

This is used to keep track of play once sources that must be released when they stop playing.

SFXListener mListener

The position and orientation of the listener.

U32 mLastTime

The last time the system got an update.

F32 mChannelVolume [NumChannels]

The channel volume which controls the volume of all sources assigned to that channel.

F32 mMasterVolume

The overall volume for all sounds in the system.

S32 mStatNumSources

Stats reported back to the console for tracking performance.

S32 mStatNumPlaying

S32 mStatNumCulled

S32 mStatNumVoices

Static Protected Attributes

static SFXSystem * smSingleton

The one and only instance of the SFXSystem.

Friends

class SFXSource

class SFXProfile

Member Enumeration Documentation

anonymous enum

Enumerator:

NumChannels	The number of volume channels available in the system.
NumChannelBits	The number of bits needed to write a channel value to the network stream.

Constructor & Destructor Documentation

SFXSystem::SFXSystem ( ) [protected]

The protected constructor.

See also:: SFXSystem::init()

SFXSystem::~SFXSystem ( ) [protected]

The non-virtual destructor.

You shouldn't ever need to overload this class.

Member Function Documentation

void SFXSystem::_updateSources ( ) [protected]

Called to reprioritize and reassign buffers as sources change state, volumes are adjusted, and the listener moves around.

See also:: SFXSource::_update()

void SFXSystem::_assignVoices ( ) [protected]

This called to reprioritize and reassign voices to sources.

void SFXSystem::_onRemoveSource ( SFXSource * source ) [protected]

This is called from the source to properly clean itself up.

See also:: SFXSource::onRemove()

SFXBuffer* SFXSystem::_createBuffer ( SFXProfile * profile ) [protected]

Called from SFXProfile to create a device specific sound buffer used in conjunction with a voice in playback.

static SFXSystem* SFXSystem::getSingleton ( ) [inline, static]

Returns the one an only instance of the SFXSystem unless it hasn't been initialized or its been disabled in your build.

For convienence you can use the SFX-> macro as well.

See also:: SFXSystem::init()
SFX

static void SFXSystem::init ( ) [static]

This is called from initialization to prepare the sound system singleton.

This also includes registering common resource types and initializing available sound providers.

static void SFXSystem::destroy ( ) [static]

This is called after Sim::shutdown() in shutdownLibraries() to free the sound system singlton.

After this the SFX singleton is null and any call to it will crash.

void SFXSystem::_update ( )

This is only public so that it can be called by the game update loop.

It updates the current device and all sources.

bool SFXSystem::createDevice	(	const char *	providerName,
		const char *	deviceName,
		bool	useHardware,
		S32	maxBuffers,
		bool	changeDevice = `false`
	)

This initializes a new device.

Parameters:

	providerName	The name of the provider.
	deviceName	The name of the provider device.
	useHardware	Toggles the use of hardware processing when available.
	maxBuffers	The maximum buffers for this device to use or -1 for the device to pick its own reasonable default.
	changeDevice	Allows this to change the current device to a new one

Returns:: Returns true if the device was created.

const char* SFXSystem::getDeviceInfoString ( )

Returns the current device information or NULL if no device is present.

The information string is in the following format:

Provider Name Name Hardware Buffers

void SFXSystem::deleteDevice ( )

This destroys the current device.

All sources loose their playback buffers, but otherwise continue to function.

bool SFXSystem::hasDevice ( ) const [inline]

Returns true if a device is allocated.

SFXSource* SFXSystem::createSource	(	const SFXProfile *	profile,
		const MatrixF *	transform = `NULL`,
		const VectorF *	velocity = `NULL`
	)

Used to create new sound sources from a sound profile.

The returned source is in a stopped state and ready for playback. Use the SFX_DELETE macro to free the source when your done.

Parameters:

	profile	The sound profile for the created source.
	transform	The optional transform if creating a 3D source.
	velocity	The optional doppler velocity if creating a 3D source.

Returns:: The sound source or NULL if an error occured.

SFXSource* SFXSystem::playOnce	(	const SFXProfile *	profile,
		const MatrixF *	transform = `NULL`,
		const VectorF *	velocity = `NULL`
	)

Creates a source which when it finishes playing will auto delete itself.

Be aware that the returned SFXSource pointer should only be used for error checking or immediate setting changes. It may be deleted as soon as the next system tick.

Parameters:

	profile	The sound profile for the created source.
	transform	The optional transform if creating a 3D source.
	velocity	The optional doppler velocity if creating a 3D source.