#include <OpenALRenderer.h>

Inheritance diagram for Audio::OpenALRenderer:

Public Member Functions
	OpenALRenderer () throw (Exception)

virtual	~OpenALRenderer ()

virtual SharedPtr< Sound >	getSound (const std::string &name, VSFileSystem::VSFileType type=VSFileSystem::UnknownFile, bool streaming=false) throw (Exception)

virtual bool	owns (SharedPtr< Sound > sound)

virtual void	attach (SharedPtr< Source > source) throw (Exception)

virtual void	attach (SharedPtr< Listener > listener) throw (Exception)

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

virtual void	detach (SharedPtr< Listener > listener) throw ()

virtual void	setMeterDistance (Scalar distance) throw ()

virtual void	setDopplerFactor (Scalar factor) throw ()

virtual void	setOutputFormat (const Format &format) throw (Exception)

virtual void	beginTransaction () throw (Exception)

virtual void	commitTransaction () throw (Exception)

Public Member Functions inherited from Audio::Renderer
	Renderer () throw (Exception)

virtual	~Renderer ()

virtual Scalar	getMeterDistance () const throw ()

virtual Scalar	getDopplerFactor () const throw ()

virtual const Format &	getOutputFormat () const throw ()

Protected Member Functions
virtual void	checkContext () throw (Exception)

virtual void	initContext () throw (Exception)

void	setupDopplerEffect () throw (Exception)

Protected Attributes
AutoPtr < __impl::OpenAL::RendererData >	data

Detailed Description

OpenAL Renderer implementation

Remarks: Audio renderer implementation based on OpenAL.

Definition at line 29 of file OpenALRenderer.h.

Constructor & Destructor Documentation

Audio::OpenALRenderer::OpenALRenderer	(	)
throw	(	Exception
	)

Initialize the renderer with default or config-driven settings.

Definition at line 235 of file OpenALRenderer.cpp.

                          :
         data(new RendererData)
     {
     }

Audio::OpenALRenderer::~OpenALRenderer ( )

virtual

Definition at line 241 of file OpenALRenderer.cpp.

242 {

243 }

Member Function Documentation

void Audio::OpenALRenderer::attach	(	SharedPtr< Source >	source)
throw	(	Exception
	)

virtual

Attach a source to this renderer

Remarks: A source may only be attached to one renderer. If the source was attached already, an exception will be thrown.

Attachment may mean resource allocation. Either immediate or deferred. So it may: fail if resources are scarce.

Implements Audio::Renderer.

Definition at line 279 of file OpenALRenderer.cpp.

     {
         checkContext();
         source->setRenderable( SharedPtr<RenderableSource>(
                 source->getSound()->isStreaming() 
                     ? (RenderableSource*)new OpenALRenderableStreamingSource(source.get())
                     : (RenderableSource*)new OpenALRenderableSource(source.get())
             ) 
         );
     }

void Audio::OpenALRenderer::attach	(	SharedPtr< Listener >	listener)
throw	(	Exception
	)

virtual

Attach a listener to this renderer

Remarks: A listener may only be attached to one renderer. If the listener was attached already, an exception will be thrown.

Attachment may mean resource allocation. Either immediate or deferred. So it may: fail if resources are scarce.

Implements Audio::Renderer.

Definition at line 291 of file OpenALRenderer.cpp.

     {
         checkContext();
         listener->setRenderable( SharedPtr<RenderableListener>(
             new OpenALRenderableListener(listener.get()) ) );
     }

void Audio::OpenALRenderer::beginTransaction	(	)
throw	(	Exception
	)

virtual

Begins a transaction

Remarks: state changes will be piled up and applied at commit. This is, though, an optional feature: renderers may choose not to implement it, and perform state changes immediately. In any case, the result ought to be the same.

Reimplemented from Audio::Renderer.

Definition at line 356 of file OpenALRenderer.cpp.

     {
         data->suspend();
         
         if (data->dirty.dopplerFactor)
             setupDopplerEffect();
     }

void Audio::OpenALRenderer::checkContext	(	)
throw	(	Exception
	)

protectedvirtual

Makes sure the AL context is valid, creating one if necessary

Reimplemented in Audio::BorrowedOpenALRenderer.

Definition at line 345 of file OpenALRenderer.cpp.

     {
         if (!data->alDevice)
             data->openDevice(NULL);
         if (!data->alContext) {
             data->openContext(getOutputFormat());
             initContext();
         }
     }

void Audio::OpenALRenderer::commitTransaction	(	)
throw	(	Exception
	)

virtual

See Also: begin()

Reimplemented from Audio::Renderer.

Definition at line 365 of file OpenALRenderer.cpp.

     {
         data->commit();
     }

void Audio::OpenALRenderer::detach	(	SharedPtr< Source >	source)
throw	(
	)

virtual

Detach a source from this renderer.

Remarks: Immediately frees any allocated resources.

Implements Audio::Renderer.

Definition at line 299 of file OpenALRenderer.cpp.

     {
         // Just clear it... RenderableListener's destructor will handle everything fine.
         source->setRenderable( SharedPtr<RenderableSource>() );
     }

void Audio::OpenALRenderer::detach	(	SharedPtr< Listener >	listener)
throw	(
	)

virtual

Detach a listener from this renderer.

Remarks: Immediately frees any allocated resources.

Implements Audio::Renderer.

Definition at line 306 of file OpenALRenderer.cpp.

     {
         // Just clear it... RenderableListener's destructor will handle everything fine.
         listener->setRenderable( SharedPtr<RenderableListener>() );
     }

SharedPtr< Sound > Audio::OpenALRenderer::getSound	(	const std::string &	name,
		VSFileSystem::VSFileType	type = `VSFileSystem::UnknownFile`,
		bool	streaming = `false`
	)
throw	(	Exception
	)

virtual

Create a sound, from the stream of the specified name.

Parameters

name	The path of the soundfile.
type	The file type (needed by the filesystem).
straeming	If true, requests for a streaming sound - one that is not loaded to memory for playback, but rather read on-demand during playback.

Remarks: The name is the path of a soundstream as it would be passed to the CodecRegistry.

Streaming sounds can also be created, which depending on the renderer implementation: may or may not result in a different kind of sound resource. Most notably, the difference may depend on runtime-dependant state. For instance, it is quite reasonable that a streaming sound won't be created if the same sound file exists in a non-streaming form.

See Also: CodecRegistry

Implements Audio::Renderer.

Definition at line 245 of file OpenALRenderer.cpp.

     {
         checkContext();
         SharedPtr<Sound> sound = data->lookupSound(type,name);
         if (!sound.get() || streaming) {
             if (streaming) {
                 // Streaming sounds cannot be cached, so if a streaming sound
                 // is in the cache, it must be evicted and re-created
                 sound.reset();
                 data->addSound(
                     type,
                     name,
                     sound = SharedPtr<Sound>(new OpenALStreamingSound(name,type))
                 );
             } else {
                 data->addSound(
                     type,
                     name,
                     sound = SharedPtr<Sound>(new OpenALSimpleSound(name,type))
                 );
             }
         }
         return sound;
     }

void Audio::OpenALRenderer::initContext	(	)
throw	(	Exception
	)

protectedvirtual

Sets expected defaults into the context

Definition at line 371 of file OpenALRenderer.cpp.

     {
         // Set the distance model
         alDistanceModel(AL_INVERSE_DISTANCE_CLAMPED);
         
         // Flag everything as dirty
         data->dirty.meterDistance = 1;
         data->dirty.dopplerFactor = 1;
     }

bool Audio::OpenALRenderer::owns ( SharedPtr< Sound > sound)

virtual

Return whether the specified sound has been created using this renderer or not

Implements Audio::Renderer.

Definition at line 274 of file OpenALRenderer.cpp.

     {
         return !data->lookupSound(sound).isNull();
     }

void Audio::OpenALRenderer::setDopplerFactor	(	Scalar	factor)
throw	(
	)

virtual

Sets how much the doppler effect will be accounted for.

Remarks: This sets a semi-opaque value which controls how much of the doppler effect will be simulated. All that is required is that 0 maps to fully disabled doppler effect, 1 maps to a realistic effect, in between a disimulated effect, and above 1 an exaggerated effect. The spec is purposefully vague on the specifics.

Reimplemented from Audio::Renderer.

Definition at line 326 of file OpenALRenderer.cpp.

References Audio::Renderer::setDopplerFactor().

     {
         Renderer::setDopplerFactor(factor);
         
         // Just flag it as dirty so that the next commit reconfigures the doppler effect.
         data->dirty.dopplerFactor = 1;
     }

void Audio::OpenALRenderer::setMeterDistance	(	Scalar	distance)
throw	(
	)

virtual

Sets the distance in world units that represents one meter.

Remarks: This reference distance is required by environmental effect processing to accurately account for distance factors beyond simple gain falloff.

Reimplemented from Audio::Renderer.

Definition at line 313 of file OpenALRenderer.cpp.

References Audio::Renderer::setMeterDistance().

     {
         // ToDo
         // Nothing yet - this is an extension to OpenAL 1.1's specs and in this phase
         // we'll implement only basic functionality.
         Renderer::setMeterDistance(distance);
         
         // meterDistance affects doppler settings (since it affects the speed of sound)
         data->dirty.dopplerFactor = 1;
         data->dirty.meterDistance = 1;
     }

void Audio::OpenALRenderer::setOutputFormat	(	const Format &	format)
throw	(	Exception
	)

virtual

Sets the (preferred) output format.

Remarks: Renderers are encouraged to set their effective output format to the closest "better" format, where better is defined as either having heigher sampling frequency, bit depth, or number of channels. The effective output format, if known, must be reflected in subsequent calls to getOutputFormat.

Reimplemented from Audio::Renderer.

Reimplemented in Audio::BorrowedOpenALRenderer.

Definition at line 335 of file OpenALRenderer.cpp.

References Audio::Renderer::setOutputFormat().

     {
         if (!data->alDevice)
             data->openDevice(NULL);
         data->closeContext();
         data->openContext(format);
         Renderer::setOutputFormat(format);
     }

void Audio::OpenALRenderer::setupDopplerEffect	(	)
throw	(	Exception
	)

protected

Sets doppler effect globals into the context

Definition at line 382 of file OpenALRenderer.cpp.

References checkAlError, and clearAlError.

     {
         clearAlError();
         
         // First of all, compute the speed of sound (in world units)
         Scalar speedOfSound = 343.3f * getMeterDistance();
         
         // Set doppler factor and speed of sound
         alDopplerFactor(getDopplerFactor());
 #ifdef _WIN32
         alDopplerVelocity(speedOfSound);
 #else
         alSpeedOfSound(speedOfSound);
 #endif
         
         data->dirty.dopplerFactor = 0;
         
         checkAlError();
     }

Member Data Documentation

AutoPtr<__impl::OpenAL::RendererData> Audio::OpenALRenderer::data

protected

Definition at line 32 of file OpenALRenderer.h.

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

src/audio/renderers/OpenAL/OpenALRenderer.h
src/audio/renderers/OpenAL/OpenALRenderer.cpp

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation