#include <SceneManager.h>

Inheritance diagram for Audio::SceneManager:

Public Types
typedef VirtualIterator < SharedPtr< Scene > >	SceneIterator

Public Member Functions
	SceneManager () throw ()

virtual	~SceneManager ()

virtual SharedPtr< Source >	createSource (SharedPtr< Sound > sound, bool looping=false) throw (Exception)

SharedPtr< Source >	createSource (SharedPtr< SourceTemplate > tpl) throw (Exception)

SharedPtr< Source >	createSource (SharedPtr< SourceTemplate > tpl, const std::string &name) throw (Exception)

virtual void	destroySource (SharedPtr< Source > source) throw ()

void	playSource (SharedPtr< SourceTemplate > tpl, const std::string &sceneName, LVector3 position, Vector3 direction, Vector3 velocity, Scalar radius) throw (Exception)

void	playSource (SharedPtr< SourceTemplate > tpl, const std::string &soundName, const std::string &sceneName, LVector3 position, Vector3 direction, Vector3 velocity, Scalar radius) throw (Exception)

virtual SharedPtr< Scene >	createScene (const std::string &name) throw (DuplicateObjectException)

virtual SharedPtr< Scene >	getScene (const std::string &name) const throw (NotFoundException)

virtual void	destroyScene (const std::string &name) throw (NotFoundException)

virtual void	setSceneActive (const std::string &name, bool active) throw (NotFoundException)

virtual bool	getSceneActive (const std::string &name) throw (NotFoundException)

virtual SharedPtr< Listener >	getRootListener () const throw ()

virtual SharedPtr< SceneIterator >	getSceneIterator () const throw ()

virtual SharedPtr< SceneIterator >	getActiveSceneIterator () const throw ()

virtual void	setRenderer (SharedPtr< Renderer > renderer) throw (Exception)

SharedPtr< Renderer >	getRenderer () const throw ()

virtual void	commit () throw (Exception)

Duration	getPositionUpdateFrequency () const throw ()

Duration	getListenerUpdateFrequency () const throw ()

Duration	getAttributeUpdateFrequency () const throw ()

Duration	getActivationFrequency () const throw ()

virtual void	setPositionUpdateFrequency (Duration interval) const throw ()

virtual void	setListenerUpdateFrequency (Duration interval) const throw ()

virtual void	setAttributeUpdateFrequency (Duration interval) const throw ()

virtual void	setActivationFrequency (Duration interval) const throw ()

virtual unsigned int	getMaxSources () const throw ()

virtual void	setMaxSources (unsigned int n) throw (Exception)

virtual float	getMinGain () const throw ()

virtual void	setMinGain (float gain) throw (Exception)

virtual double	getMaxDistance () const throw ()

virtual void	setMaxDistance (double distance) throw (Exception)

virtual void	notifySourcePlaying (SharedPtr< Source > source, SharedPtr< Scene > scene, bool playing) throw (Exception)

Protected Member Functions
const SharedPtr< Renderer > &	internalRenderer () const

void	addScene (SharedPtr< Scene > scene) throw (DuplicateObjectException)

virtual void	activationPhaseImpl () throw (Exception)

virtual void	updateSourcesImpl (bool withAttributes) throw (Exception)

virtual void	updateListenerImpl (bool withAttributes) throw (Exception)

Protected Member Functions inherited from Singleton< SceneManager >
	~Singleton ()

Additional Inherited Members
Static Public Member Functions inherited from Singleton< SceneManager >
static SceneManager *	getSingleton ()

Static Protected Member Functions inherited from Singleton< SceneManager >
static void	initializeSingleton ()

static void	deinitializeSingleton ()

Static Protected Attributes inherited from Singleton< SceneManager >
static SceneManager *	_singletonInstance

Detailed Description

Audio Scene Manager.

Remarks: Use it to create and manage sources, listeners, instantiate source templates, scenes, and other various scene management tasks.

SceneManager s will handle the complex task of prioritizing sources, managing: source channels, volume levels, and doing all kinds of culling.

Another responsability of scene managers is the manipulation and analysis of: environments to feed environmental information to capable renderers.

Inactive sources without external references are automatically destroyed when: they become permanently inactive (notice this requirement is merely approximate - implementations are free to make reasonable approximations for the determination of such condition as "permanently inactive"). This allows for "fire & forget" sources, where the source is activated (by calling startPlaying), and then immediately unreferenced. The SceneManager will keep track of that source, as it would any other, until it stops playing (make sure though it's not a looping source!), and will remove it when that happens, freeing any associated resources.

In fact this is so common as to make it part of the API: playSource does exactly: that, it creates a source, plays it, and discards the reference.

Thus, SceneManager s are the hub of all activity relating sound. If you're doing: anything bypassing the SceneManager, you're doing it wrong.

This class is NOT abstract, it provides a very basic implementation that does: nothing special.

Note: You must set a renderer or you won't hear anything ;)

Definition at line 59 of file SceneManager.h.

Member Typedef Documentation

typedef VirtualIterator<SharedPtr<Scene> > Audio::SceneManager::SceneIterator

Definition at line 65 of file SceneManager.h.

Constructor & Destructor Documentation

Audio::SceneManager::SceneManager	(	)
throw	(
	)

Construct a new instance of the manager

Remarks: End-users of the class shouldn't be using this. Singletons need it. Instead, end-users should use the Root class to find manager plugins they like.

Definition at line 116 of file SceneManager.cpp.

                                        :
         data(new SceneManagerData)
     {
     }

Audio::SceneManager::~SceneManager ( )

virtual

Definition at line 121 of file SceneManager.cpp.

122 {

123 }

Member Function Documentation

void Audio::SceneManager::activationPhaseImpl	(	)
throw	(	Exception
	)

protectedvirtual

Synchronize activation state with the scenes

Definition at line 454 of file SceneManager.cpp.

References Audio::TVector3< T >::distanceSquared(), Audio::SourcePriorityRef::gain, Audio::SimpleScene::getActiveSources(), Audio::SimpleScene::getActiveSourcesEnd(), Audio::SimpleScene::getListener(), Audio::Listener::getPosition(), and Audio::RenderableSource::UPDATE_LOCATION.

     {
         // Just clear the active source set and recreate it from scratch.
         // Use a "source ref heap" to find the most relevant sources (using the approximated
         // intensity as priority). Since the heap will copy things all over, use cheap
         // "SourceIterator"s as entries. These are SimpleScene-specific, so any subclass of 
         // SceneManager will probably want to override the activation phase.
         
         const SharedPtr<Renderer> &renderer = internalRenderer();
         
         LScalar maxDistanceSq = data->maxDistance * data->maxDistance;
         
         std::vector<SourcePriorityRef> selection;
         bool heapified = false;
         selection.reserve(data->maxSources+1);
         
         for (SceneManagerData::SceneMap::iterator it = data->activeScenes.begin();
              it != data->activeScenes.end();
              ++it)
         {
             SimpleScene *scene = dynamic_cast<SimpleScene*>(it->second.get());
             Listener &listener = scene->getListener();
             
             for (SimpleScene::SourceIterator sit = scene->getActiveSources(), 
                                              send = scene->getActiveSourcesEnd();
                  sit != send;
                  ++sit)
             {
                 if ( (*sit)->getSourceListener().get() ) {
                     // Must invoke the listener to get updated positions
                     (*sit)->getSourceListener()->onUpdate(**sit, RenderableSource::UPDATE_LOCATION);
                 }
                 
                 if (listener.getPosition().distanceSquared((*sit)->getPosition()) < maxDistanceSq) {
                     SourcePriorityRef ref(sit, listener, scene);
                     if (ref.gain > data->minGain) {
                         selection.push_back(ref);
                         if (selection.size() > data->maxSources) {
                             if (!heapified) {
                                 make_heap(selection.begin(), selection.end());
                                 heapified = true;
                             } else {
                                 push_heap(selection.begin(), selection.end());
                             }
                             while (selection.size() > data->maxSources) {
                                 pop_heap(selection.begin(), selection.end());
                                 selection.resize( selection.size()-1 );
                             }
                         }
                     }
                 }
             }
         }
         
         SceneManagerData::SourceRefSet newSources;
         for (std::vector<SourcePriorityRef>::const_iterator it = selection.begin(); it != selection.end(); ++it) {
             newSources.insert( 
                 SceneManagerData::SourceRef(
                     *(it->iter),
                     dynamic_cast<SimpleScene*>(it->scene)->shared_from_this()
                 ) );
         }
         
         // Detach deactivated sources
         for (SceneManagerData::SourceRefSet::iterator sit = data->activeSources.begin(); sit != data->activeSources.end(); ++sit) {
             if (newSources.find(*sit) == newSources.end())
                 renderer->detach(sit->source);
         }
         
         // Attach newly activated sources, detach and remove finished ones
         for (SceneManagerData::SourceRefSet::iterator nit = newSources.begin(); nit != newSources.end(); ) {
             bool erase = false;
             if (data->activeSources.find(*nit) == data->activeSources.end()) {
                 // Newly activated source
                 renderer->attach(nit->source);
                 nit->needsActivation = true;
             } else {
                 // Pre-existing source - check if it's finished
                 if (!nit->source->getRenderable()->isPlaying()) {
                     // Give the renderable an opportunity to restart itself
                     // (by calling update without any update flag set)
                     nit->source->getRenderable()->update(0, nit->scene->getListener());
                     
                     if (!nit->source->getRenderable()->isPlaying()) {
                         // Finished - detach stop and remove
                         renderer->detach(nit->source);
                         nit->source->stopPlaying();
                         erase = true;
                         
                         // Check if it has a listener, notify in that case
                         SharedPtr<SourceListener> listener = nit->source->getSourceListener();
                         if (listener.get() != NULL && listener->wantPlayEvents()) {
                             listener->onEndOfStream(*nit->source);
                         }
                     }
                 }
             }
             if (erase)
                 newSources.erase(nit++);
             else
                 ++nit;
         }
         
         // Swap sets
         data->activeSources.swap(newSources);
     }

void Audio::SceneManager::addScene	(	SharedPtr< Scene >	scene)
throw	(	DuplicateObjectException
	)

protected

Add a new scene

See Also: createScene

Definition at line 186 of file SceneManager.cpp.

     {
         if (   data->activeScenes.count(scene->getName()) 
             || data->inactiveScenes.count(scene->getName()) )
             throw(DuplicateObjectException(scene->getName()));
         
         data->inactiveScenes[scene->getName()] = scene;
     }

void Audio::SceneManager::commit	(	)
throw	(	Exception
	)

virtual

Commit changes done between frames

Remarks: Depending on the underlying implementation, changes applied to sources may or may not be immediately available to the renderer. Calling commit() ensures that they are. Furthermore, some scene managers may use commit boundaries to ensure frame coherence (the renderer receives information coherent to the state as it was at the commit), though this is certainly not a requirement.

The process may be lengthy and throw various exceptions.

Definition at line 392 of file SceneManager.cpp.

References Audio::getRealTime(), and realTime().

     {
         Timestamp realTime         = getRealTime();
         bool needActivation        = ((realTime - getActivationFrequency()) >= data->lastActivationTime);
         bool needPosUpdates        = ((realTime - getPositionUpdateFrequency()) >= data->lastPositionUpdateTime);
         bool needAttUpdates        = ((realTime - getAttributeUpdateFrequency()) >= data->lastAttributeUpdateTime);
         bool needListenerUpdate    = ((realTime - getListenerUpdateFrequency()) >= data->lastListenerUpdateTime);
         bool needListenerAttUpdate = ((realTime - getAttributeUpdateFrequency()) >= data->lastListenerAttUpdateTime);
         
         // If we have an activation phase, in order for it to be effective
         // we'll need an update phase as well.
         needPosUpdates = needPosUpdates || needActivation;
         
         internalRenderer()->beginTransaction();
         
         if (needActivation) {
             activationPhaseImpl();
             
             data->lastActivationTime = realTime;
         }
         
         if (needListenerUpdate) {
             updateListenerImpl(needListenerAttUpdate);
             
             data->lastListenerUpdateTime = realTime;
             if (needListenerAttUpdate)
                 data->lastListenerAttUpdateTime = realTime;
         }
         
         if (needPosUpdates || needAttUpdates) {
             updateSourcesImpl(needAttUpdates);
             
             data->lastPositionUpdateTime = realTime;
             if (needAttUpdates)
                 data->lastAttributeUpdateTime = realTime;
         }
         
         internalRenderer()->commitTransaction();
     }

SharedPtr< Scene > Audio::SceneManager::createScene	(	const std::string &	name)
throw	(	DuplicateObjectException
	)

virtual

Create a new named scene

Definition at line 196 of file SceneManager.cpp.

Referenced by initScenes(), Audio::Test::testComplexScene(), Audio::Test::testMultiStreaming(), Audio::Test::testMultiStreaming2(), Audio::Test::testRendererless(), Audio::Test::testSimpleScene(), Audio::Test::testSimpleSceneWTemplates(), and Audio::Test::testStreaming().

     {
         SharedPtr<Scene> scenePtr(new SimpleScene(name));
         addScene(scenePtr);
         return scenePtr;
     }

SharedPtr< Source > Audio::SceneManager::createSource	(	SharedPtr< Sound >	sound,
		bool	looping = `false`
	)
throw	(	Exception
	)

virtual

Create a new source based on the speicified sound

Remarks: All the attributes will hold unspecified values, so you have to fill them in.}

Note: The sound must be associated to the correct renderer, or bad things will happen.

See Also: Renderer, which creates sounds.

Definition at line 132 of file SceneManager.cpp.

Referenced by Audio::Test::testComplexScene(), Audio::Test::testMultiStreaming(), Audio::Test::testMultiStreaming2(), Audio::Test::testSimpleScene(), Audio::Test::testSimpleSceneWTemplates(), and Audio::Test::testStreaming().

     {
         if (!internalRenderer()->owns(sound))
             throw Exception("Invalid sound: incompatible renderers used");
         
         return SharedPtr<Source>( new SimpleSource(sound, looping) );
     }

SharedPtr< Source > Audio::SceneManager::createSource	(	SharedPtr< SourceTemplate >	tpl)
throw	(	Exception
	)

Create a new source based on the specified template

Remarks: All location information will hold unspecified values, so you have to fill them in.

Definition at line 141 of file SceneManager.cpp.

     {
         return createSource(tpl, tpl->getSoundName());
     }

SharedPtr< Source > Audio::SceneManager::createSource	(	SharedPtr< SourceTemplate >	tpl,
		const std::string &	name
	)
throw	(	Exception
	)

Create a new source based on the specified template, but overriding its sound resource.

Remarks: All location information will hold unspecified values, so you have to fill them in.

It's useful to have "mode" templates that can be used to spawn many sources based: on many different streams. Eg: a "music" template for spawning music tracks, a "radio" template for spawning radio voiceovers, etc...

Definition at line 147 of file SceneManager.cpp.

     {
         SharedPtr<Source> source = createSource(
             internalRenderer()->getSound(
                 name,
                 tpl->getSoundType(),
                 tpl->isStreaming() ), 
             tpl->isLooping() );
          
         source->setCosAngleRange( tpl->getCosAngleRange() );
         source->setPerFrequencyRadiusRatios( tpl->getPerFrequencyRadiusRatios() );
         source->setReferenceFreqs( tpl->getReferenceFreqs() );
         source->setGain( tpl->getGain() );
         source->setAttenuated( tpl->isAttenuated() );
         source->setRelative( tpl->isRelative() );
         
         return source;
     }

void Audio::SceneManager::destroyScene	(	const std::string &	name)
throw	(	NotFoundException
	)

virtual

Destroy an existing scene by its name

Definition at line 220 of file SceneManager.cpp.

Referenced by Audio::Test::clearScene().

     {
         // By simply unreferencing, it should get destroyed when all references are released.
         // Which is good for multithreading - never destroy something that is being referenced.
         // Any active sources will get deactivated in the next update since there aren't any active scenes
         // containing them.
         data->activeScenes.erase(name);
         data->inactiveScenes.erase(name);
     }

void Audio::SceneManager::destroySource	(	SharedPtr< Source >	source)
throw	(
	)

virtual

Destroy a source created with this manager

Definition at line 167 of file SceneManager.cpp.

     {
         // By simply unreferencing, it should get destroyed when all references are released.
         // Which is good for multithreading - never destroy something that is being referenced.
         
         // We cannot have playing sources without references within the manager
         // Since it's stopped, it will eventually be removed from the active list if there.
         if (source->isPlaying())
             source->stopPlaying();
         
         // Remove all references to it within every scene
         SceneManagerData::SceneMap::iterator it;
         for (it = data->activeScenes.begin(); it != data->activeScenes.end(); ++it)
             it->second->remove(source);
         for (it = data->inactiveScenes.begin(); it != data->inactiveScenes.end(); ++it)
             it->second->remove(source);
     }

Duration Audio::SceneManager::getActivationFrequency	(	)	const
throw	(
	)

Return source activation frequency

Remarks: Sources may become active or inactive over time, and depending on the impementation the effects may not be immediate. More so, since there's a "maximum renderable sources" limit, activation may depend on a lot of factors, and not just a call to startPlaying(). So, activation updates are the costlier of all updates since it involves evaluating and prioritizing all sources in all scenes, not just active ones (sources). Frequent activation passes are however necessary (but perhaps not that often) since otherwise sources that didn't start off as active may never become so.

Definition at line 621 of file SceneManager.cpp.

     {
         return data->activationFrequency;
     }

SharedPtr< SceneManager::SceneIterator > Audio::SceneManager::getActiveSceneIterator	(	)	const
throw	(
	)

virtual

Get an iterator over all active scenes

Definition at line 383 of file SceneManager.cpp.

     {
         return SharedPtr<SceneIterator>(
             new VirtualValuesIterator<SceneManagerData::SceneMap::iterator>(
                 data->activeScenes.begin(),
                 data->activeScenes.end() ) );
     }

Duration Audio::SceneManager::getAttributeUpdateFrequency	(	)	const
throw	(
	)

Return attribute update frequency

Remarks: Source attribute updates are rare but necessary. They are very costly since all active sources must be updated (and each update is far more costly than simple position updates). This value specifies how often they're updated, however the actual interval may vary depending on the implementation (it's a mere guideline).

Definition at line 615 of file SceneManager.cpp.

     {
         return data->attributeUpdateFrequency;
     }

Duration Audio::SceneManager::getListenerUpdateFrequency	(	)	const
throw	(
	)

Return listener update frequency

Remarks: Position updates are a very important kind of update that needs to be performed regularly and quite often - even more so for listeners. Since there are very few listeners (one per scene), they're perhaps not so costly, or perhaps so? (depending on the underlying implementation). This value specifies how often they're updated, however the actual interval may vary depending on the implementation (it's a mere guideline).

Definition at line 609 of file SceneManager.cpp.

     {
         return data->listenerUpdateFrequency;
     }

double Audio::SceneManager::getMaxDistance	(	)	const
throw	(
	)

virtual

Get the maximum distance of active sources

Remarks: This value specifies the maximum distance of active sources. If a source is at a greater distance from the listener, it is ignored and deactivated, to conserve resources.

See Also: For more culling options: get/setMinGain

Definition at line 355 of file SceneManager.cpp.

     {
         return data->maxDistance;
     }

unsigned int Audio::SceneManager::getMaxSources	(	)	const
throw	(
	)

virtual

Get the maximum number of simultaneous sources that can be playing at a time

Remarks: This value may be approximate, and it refers to the maximum number of Source class instances that can effectively be in playing state. Some sources, when environmental effects are being applied, can count more than once towards the effective limit, and the manager will try to compensate this when setting the "MaxSources" attribute. However, this compensation may not be perfect.

Definition at line 283 of file SceneManager.cpp.

     {
         return data->maxSources;
     }

float Audio::SceneManager::getMinGain	(	)	const
throw	(
	)

virtual

Get the minimum gain that would be culled off

Remarks: This value specifies the minimum gain of active sources. If a source ends having a lesser gain, it is ignored and deactivated, to conserve resources.

The manager is free to approximate such determination in order to optimize: culling: for instance, it could, given attenuation factors and the like, compute a maximum distance that would result in gains potentially greater than this value to avoid processing of any source beyond that distance. However, such a computation is required to be conservative (never cull sources that would fall outside of the culling rule based on actual gain), and as such may be difficult without aid.

See Also: For more culling options: get/setMaxDistance

Definition at line 342 of file SceneManager.cpp.

     {
         return data->minGain;
     }

Duration Audio::SceneManager::getPositionUpdateFrequency	(	)	const
throw	(
	)

Return position update frequency

Remarks: Source position updates are a very important kind of update that needs to be performed regularly and quite often. They are costly (all active sources have to be updated). This value specifies how often they're updated, however the actual interval may vary depending on the implementation (it's a mere guideline).

Definition at line 603 of file SceneManager.cpp.

     {
         return data->positionUpdateFrequency;
     }

SharedPtr< Renderer > Audio::SceneManager::getRenderer	(	)	const
throw	(
	)

Get the current renderer

Definition at line 277 of file SceneManager.cpp.

Referenced by Audio::Test::testComplexScene(), Audio::Test::testMultiStreaming(), Audio::Test::testMultiStreaming2(), Audio::Test::testSimpleScene(), and Audio::Test::testStreaming().

     {
         return data->renderer;
     }

SharedPtr< Listener > Audio::SceneManager::getRootListener	(	)	const
throw	(
	)

virtual

Get the root listener

Remarks: Renderers can only have one listener. Sources attached to scenes require translation into the reference listener. It is usually convenient to apply some listener changes directly into the root listener rather than into the scenes. For instance, if one scene represents the cockpit and another the ship's exterior, the cockpit listener will be fixed and the exterior listener will move with the ship. But if the user wants to "look to the right", the best way to achieve this would be to rotate the renderer's listener to the right rather than rotate all sources to the left (what would be required if the listeners of each scene were rotated, since they're "artificial" listeners).

Definition at line 651 of file SceneManager.cpp.

     {
         return data->rootListener;
     }

SharedPtr< Scene > Audio::SceneManager::getScene	(	const std::string &	name)	const
throw	(	NotFoundException
	)

virtual

Get an existing scene by its name

Definition at line 204 of file SceneManager.cpp.

Referenced by Audio::Test::testComplexScene(), Audio::Test::testMultiStreaming(), Audio::Test::testMultiStreaming2(), Audio::Test::testRendererless(), Audio::Test::testSimpleScene(), Audio::Test::testSimpleSceneWTemplates(), and Audio::Test::testStreaming().

     {
         SceneManagerData::SceneMap::const_iterator it;
         
         it = data->activeScenes.find(name);
         if (it != data->activeScenes.end())
             return it->second;
         
         it = data->inactiveScenes.find(name);
         if (it != data->inactiveScenes.end())
             return it->second;
         
         throw(NotFoundException(name));
     }

bool Audio::SceneManager::getSceneActive	(	const std::string &	name)
throw	(	NotFoundException
	)

virtual

Get the active state of a scene

Definition at line 246 of file SceneManager.cpp.

     {
         return data->activeScenes.count(name) > 0;
     }

SharedPtr< SceneManager::SceneIterator > Audio::SceneManager::getSceneIterator	(	)	const
throw	(
	)

virtual

Get an iterator over all scenes

Definition at line 368 of file SceneManager.cpp.

Referenced by Audio::Test::clearScene().

     {
         return SharedPtr<SceneIterator>(
             new ChainingIterator<VirtualValuesIterator<SceneManagerData::SceneMap::iterator> >(
                 VirtualValuesIterator<SceneManagerData::SceneMap::iterator>(
                     data->activeScenes.begin(),
                     data->activeScenes.end() ),
                 VirtualValuesIterator<SceneManagerData::SceneMap::iterator>(
                     data->inactiveScenes.begin(),
                     data->inactiveScenes.end() )
             )
         );
     }

const SharedPtr< Renderer > & Audio::SceneManager::internalRenderer ( ) const

protected

Returns the renderer

Remarks: Throws an exception if no renderer has been set

Definition at line 125 of file SceneManager.cpp.

     {
         if (!data->renderer.get())
             throw Exception("No renderer");
         return data->renderer;
     }

void Audio::SceneManager::notifySourcePlaying	(	SharedPtr< Source >	source,
		SharedPtr< Scene >	scene,
		bool	playing
	)
throw	(	Exception
	)

virtual

Notify the scene manager of a source that starts or stops playing.

Definition at line 657 of file SceneManager.cpp.

Referenced by Audio::SimpleScene::notifySourcePlaying().

     {
         // If the source is within maxDistance from its scene's listener,
         // schedule an immediate activation phase
         double maxDistanceSq = getMaxDistance();
         maxDistanceSq *= maxDistanceSq;
         
         if (scene->getListener().getPosition().distanceSquared(source->getPosition()) <= maxDistanceSq)
             data->lastActivationTime = -std::numeric_limits<Timestamp>::infinity();
     }

void Audio::SceneManager::playSource	(	SharedPtr< SourceTemplate >	tpl,
		const std::string &	sceneName,
		LVector3	position,
		Vector3	direction,
		Vector3	velocity,
		Scalar	radius
	)
throw	(	Exception
	)

Convenience API to play a source once and forget.

Parameters

tpl	The source template from which a source should be instanced
sceneName	The name of the scene to which the source should be attached
position	The initial position of the source
direction	The direction of the (if directional) source
velocity	The movement velocity of the source
radius	The base radius of the source

Remarks: The source should not be looping, and an exception will be thrown if it is.

Definition at line 295 of file SceneManager.cpp.

Referenced by Audio::Test::testSimpleSceneWTemplates().

     {
         if (tpl->isLooping())
             throw(Exception("Cannot fire a looping source and forget!"));
         
         SharedPtr<Source> src = createSource(tpl);
         
         src->setPosition(position);
         src->setDirection(direction);
         src->setVelocity(velocity);
         src->setRadius(radius);
         
         getScene(sceneName)->add(src);
         
         src->startPlaying();
     }

void Audio::SceneManager::playSource	(	SharedPtr< SourceTemplate >	tpl,
		const std::string &	soundName,
		const std::string &	sceneName,
		LVector3	position,
		Vector3	direction,
		Vector3	velocity,
		Scalar	radius
	)
throw	(	Exception
	)

Convenience API to play a source once and forget.

Parameters

tpl	The source template from which a source should be instanced
soundName	The name of the sound stream from which the source will be created, overriding the template's
sceneName	The name of the scene to which the source should be attached
position	The initial position of the source
direction	The direction of the (if directional) source
velocity	The movement velocity of the source
radius	The base radius of the source

Remarks: The source should not be looping, and an exception will be thrown if it is.

Definition at line 318 of file SceneManager.cpp.

     {
         if (tpl->isLooping())
             throw(Exception("Cannot fire a looping source and forget!"));
         
         SharedPtr<Source> src = createSource(tpl, soundName);
         
         src->setPosition(position);
         src->setDirection(direction);
         src->setVelocity(velocity);
         src->setRadius(radius);
         
         getScene(sceneName)->add(src);
         
         src->startPlaying();
     }

void Audio::SceneManager::setActivationFrequency	(	Duration	interval)	const
throw	(
	)

virtual

See Also: getActivationFrequency

Definition at line 645 of file SceneManager.cpp.

     {
         data->activationFrequency = interval;
     }

void Audio::SceneManager::setAttributeUpdateFrequency	(	Duration	interval)	const
throw	(
	)

virtual

See Also: getAttributeUpdateFrequency

Definition at line 639 of file SceneManager.cpp.

     {
         data->attributeUpdateFrequency = interval;
     }

void Audio::SceneManager::setListenerUpdateFrequency	(	Duration	interval)	const
throw	(
	)

virtual

See Also: getListenerUpdateFrequency

Definition at line 633 of file SceneManager.cpp.

     {
         data->listenerUpdateFrequency = interval;
     }

void Audio::SceneManager::setMaxDistance	(	double	distance)
throw	(	Exception
	)

virtual

Set the maximum distance of active sources

Parameters

distance The new limit.

See Also: getMaxDistance

Definition at line 361 of file SceneManager.cpp.

References f.

Referenced by Audio::Test::testComplexScene().

     {
         assert(distance >= 0.f);
         data->maxDistance = distance;
     }

void Audio::SceneManager::setMaxSources	(	unsigned int	n)
throw	(	Exception
	)

virtual

Set the maximum number of simultaneous sources that can be playing at a time

Parameters

n	The maximum number of simultaneous playing sources desired.

Remarks: This is not guaranteed to success. If failure arises, either no change or a seemingly approximate change will be made (ie: if the specified number is too high, the closest possible one will be set instead).

See Also: getMaxSources

Definition at line 289 of file SceneManager.cpp.

Referenced by initSceneManager(), and Audio::Test::testComplexScene().

     {
         data->maxSources = n;
     }

void Audio::SceneManager::setMinGain	(	float	gain)
throw	(	Exception
	)

virtual

Set the minimum gain that would be culled off

Parameters

gain	The new minimum gain.

See Also: getMinGain

Definition at line 348 of file SceneManager.cpp.

References f.

     {
         assert(gain >= 0.f);
         data->minGain = gain;
     }

void Audio::SceneManager::setPositionUpdateFrequency	(	Duration	interval)	const
throw	(
	)

virtual

See Also: getPositionUpdateFrequency

Definition at line 627 of file SceneManager.cpp.

     {
         data->positionUpdateFrequency = interval;
     }

void Audio::SceneManager::setRenderer	(	SharedPtr< Renderer >	renderer)
throw	(	Exception
	)

virtual

Set a new renderer

Parameters

renderer A new renderer to be used.

Remarks: Setting the renderer should be done at the very beginning. It is possible to switch renderers at any point, but the operation is rather costly: all sounds must be unloaded and recreated, all active sources must be detached and reattached.

Note: Overriding implementations must call the base implementation, since getRenderer is not overridable.

Definition at line 252 of file SceneManager.cpp.

Referenced by initALRenderer(), and Audio::Test::initALRenderer().

     {
         if (data->renderer.get()) {
             // Detach all active sources
             for (SceneManagerData::SourceRefSet::const_iterator it = data->activeSources.begin(); it != data->activeSources.end(); ++it)
                 data->renderer->detach(it->source);
             
             // Detach the root listener
             data->renderer->detach(data->rootListener);
         }
         
         // Swap renderers
         data->renderer.swap(renderer);
         
         if (data->renderer.get()) {
             // Attach the root listener
             data->renderer->attach(data->rootListener);
             
             // Attach all active sources
             for (SceneManagerData::SourceRefSet::const_iterator it = data->activeSources.begin(); it != data->activeSources.end(); ++it)
                 data->renderer->attach(it->source);
         }
     }

void Audio::SceneManager::setSceneActive	(	const std::string &	name,
		bool	active
	)
throw	(	NotFoundException
	)

virtual

Sets the active state of a scene

Definition at line 231 of file SceneManager.cpp.

Referenced by initScenes(), Audio::Test::testComplexScene(), Audio::Test::testMultiStreaming(), Audio::Test::testMultiStreaming2(), Audio::Test::testRendererless(), Audio::Test::testSimpleScene(), Audio::Test::testSimpleSceneWTemplates(), and Audio::Test::testStreaming().

     {
         // Simply move the pointer from one map to the other.
         // The next update will take care of activating sources as necessary.
         SharedPtr<Scene> scene = getScene(name);
         if (active) {
             data->inactiveScenes.erase(name);
             data->activeScenes[name] = scene;
         } else {
             data->activeScenes.erase(name);
             data->inactiveScenes[name] = scene;
         }
     }

void Audio::SceneManager::updateListenerImpl	(	bool	withAttributes)
throw	(	Exception
	)

protectedvirtual

Synchronize listeners

Remarks: Since renderer implementations require one listener, this only updates the root listener. Scene listeners fall under the category of position updates.

Definition at line 587 of file SceneManager.cpp.

References i, Audio::RenderableListener::UPDATE_ALL, and Audio::RenderableListener::UPDATE_LOCATION.

     {
         // Update root listener
         RenderableListener::UpdateFlags updateFlags = 
             withAttributes ? 
                 RenderableListener::UPDATE_ALL :
                 RenderableListener::UPDATE_LOCATION;
         if (data->rootListener.get()) 
             data->rootListener->update(updateFlags);
         
         // And all scene listeners
         for (SceneManagerData::SceneMap::const_iterator i = data->activeScenes.begin(); i != data->activeScenes.end(); ++i)
             i->second->getListener().update(updateFlags);
     }

void Audio::SceneManager::updateSourcesImpl	(	bool	withAttributes)
throw	(	Exception
	)

protectedvirtual

Synchronize source positions/attributes with the renderer

Definition at line 562 of file SceneManager.cpp.

References Audio::RenderableSource::UPDATE_ALL, and Audio::RenderableSource::UPDATE_LOCATION.

     {
         // Two-pass stuff.
         
         // First, update attributes (mostly location)
         RenderableSource::UpdateFlags updateFlags = 
             withAttributes ? 
                 RenderableSource::UPDATE_ALL :
                 RenderableSource::UPDATE_LOCATION;
         for (SceneManagerData::SourceRefSet::const_iterator it = data->activeSources.begin(); it != data->activeSources.end(); ++it) {
             // Update the renderable (attributes)
             it->source->updateRenderable(
                 updateFlags | (it->needsActivation ? RenderableSource::UPDATE_ALL : 0), 
                 it->scene->getListener());
         
             // Then, start playing if not playing and should be playing
             if (it->needsActivation) {
                 it->source->getRenderable()->startPlaying(
                     it->source->getWouldbePlayingTime() );
                 it->needsActivation = false;
             }
         }
     }

The documentation for this class was generated from the following files:

src/audio/SceneManager.h
src/audio/SceneManager.cpp

Public Types

Public Member Functions

Protected Member Functions

Additional Inherited Members

Detailed Description

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation