#include <OpenALStreamingSound.h>

Inheritance diagram for Audio::OpenALStreamingSound:

Public Member Functions
	OpenALStreamingSound (const std::string &name, VSFileSystem::VSFileType type=VSFileSystem::UnknownFile, unsigned int bufferSamples=0) throw ()

virtual	~OpenALStreamingSound ()

ALBufferHandle	readAndFlip () throw (Exception)

void	unqueueBuffer (ALBufferHandle buffer) throw (Exception)

void	flushBuffers () throw ()

Timestamp	getTimeBase () const throw ()

void	seek (double position) throw (Exception)

Public Member Functions inherited from Audio::SimpleSound
virtual	~SimpleSound ()

VSFileSystem::VSFileType	getType () const

Public Member Functions inherited from Audio::Sound
virtual	~Sound ()

const std::string &	getName () const throw ()

const Format &	getFormat () const throw ()

bool	isLoaded () const throw ()

bool	isLoading () const throw ()

bool	isStreaming () const throw ()

void	load (bool wait=true) throw (Exception)

void	unload () throw ()

Protected Member Functions
virtual void	loadImpl (bool wait) throw (Exception)

virtual void	unloadImpl () throw ()

Protected Member Functions inherited from Audio::SimpleSound
	SimpleSound (const std::string &name, VSFileSystem::VSFileType type=VSFileSystem::UnknownFile, bool streaming=false) throw ()

bool	isStreamLoaded () const

void	loadStream () throw (Exception)

void	closeStream () throw (ResourceNotLoadedException)

SharedPtr< Stream >	getStream () const throw (ResourceNotLoadedException)

void	readBuffer (SoundBuffer &buffer) throw (Exception)

virtual void	abortLoad () throw ()

Protected Member Functions inherited from Audio::Sound
	Sound (const std::string &name, bool streaming) throw ()

Format &	getFormat () throw ()

virtual void	onLoaded (bool success) throw ()

virtual void	waitLoad () throw (Exception)

Additional Inherited Members
Protected Attributes inherited from Audio::Sound
struct Audio::Sound::Flags	flags

Detailed Description

OpenAL Streaming Sound implementation class

Remarks: This class implements streaming OpenAL sounds. This will load the sound in chunks into OpenAL buffers, with double-buffering to make certain there's something to be played while the application is loading the next.

A package-private function is called to fill buffers for a configurable amount of buffer time - whenever a source is playing this sound, this has to happen regularly.

See Also: Sound, SimpleSound

Definition at line 34 of file OpenALStreamingSound.h.

Constructor & Destructor Documentation

Audio::OpenALStreamingSound::OpenALStreamingSound	(	const std::string &	name,
		VSFileSystem::VSFileType	type = `VSFileSystem::UnknownFile`,
		unsigned int	bufferSamples = `0`
	)
throw	(
	)

Internal constructor used by derived classes

Parameters

name	the resource's name
type	the resource's type
bufferSamples	how many samples a single buffer should hold. remember double buffering is used, so this holds the number of samples below which a read would be triggered.

Definition at line 29 of file OpenALStreamingSound.cpp.

References AL_NULL_BUFFER, i, and NUM_BUFFERS.

                 :
         SimpleSound(name, type, true),
         bufferSamples(_bufferSamples)
     {
         for (size_t i=0; i < NUM_BUFFERS; ++i)
             bufferHandles[i] = AL_NULL_BUFFER;
     }

Audio::OpenALStreamingSound::~OpenALStreamingSound ( )

virtual

Definition at line 39 of file OpenALStreamingSound.cpp.

40 {

41 }

Member Function Documentation

void Audio::OpenALStreamingSound::flushBuffers	(	)
throw	(
	)

Reset the buffer queue

Definition at line 94 of file OpenALStreamingSound.cpp.

References NUM_BUFFERS.

     {
         // Mark as detached, so that readAndFlip() knows to initialize the source
         // and streaming indices
         readBufferIndex = 0;
         
         // Mark the playBufferIndex as uninitialized, by setting it to NUM_BUFFERS
         // readAndFlip will initialize it later.
         playBufferIndex = NUM_BUFFERS;
     }

Timestamp Audio::OpenALStreamingSound::getTimeBase	(	)	const
throw	(
	)

Get the time base of the stream

Returns: The timestamp of the first unreturned buffer's starting point.

Definition at line 166 of file OpenALStreamingSound.cpp.

     {
         return bufferStarts[playBufferIndex];
     }

void Audio::OpenALStreamingSound::loadImpl	(	bool	wait)
throw	(	Exception
	)

protectedvirtual

Load the resource

Note: Assume it is unloaded and not loading

Implements Audio::Sound.

Definition at line 43 of file OpenALStreamingSound.cpp.

References buffer, checkAlError, clearAlError, e, max(), and NUM_BUFFERS.

     {
         // just in case
         unloadImpl();
         
         try {
         
             flags.loading = 1;
             
             // load the stream
             try {
                 loadStream();
             } catch(ResourceAlreadyLoadedException e) {
                 // Weird...
                 getStream()->seek(0);
             }
             SharedPtr<Stream> stream = getStream();
     
             // setup formatted buffer
             // if the format does not match an OpenAL built-in format, we must convert it.
             targetFormat = stream->getFormat();
             targetFormat.signedSamples = (targetFormat.bitsPerSample > 8);
             targetFormat.nativeOrder = 1;
             if (targetFormat.bitsPerSample > 8)
                 targetFormat.bitsPerSample = 16;
             else
                 targetFormat.bitsPerSample = 8;
             
             // Set capacity to a quarter second or 16k samples, whatever's bigger
             // TODO: make it configurable. But first, implement a central configuration repository.
             bufferSamples = std::max( 16384U, targetFormat.sampleFrequency/4 );
             
             // Prepare a buffer, so we avoid repeated allocation/deallocation
             buffer.reserve(bufferSamples, targetFormat);
 
             // Prepare AL buffers
             clearAlError();
             alGenBuffers(NUM_BUFFERS, bufferHandles);
             checkAlError();
             
             // Initialize the buffer queue
             flushBuffers();
             
             onLoaded(true);
         } catch(Exception e) {
             onLoaded(false);
             throw e;
         }
     }

ALBufferHandle Audio::OpenALStreamingSound::readAndFlip	(	)
throw	(	Exception
	)

Keep buffers going.

Returns: An AL buffer handle that can be queued in an AL streaming source, or AL_NULL_BUFFER if there's no available buffer for the operation (which means the source should free some buffers)

Remarks: It will check the buffer queue, and if there are free buffers, it will free one with new data. Basically, if you call this function often enough, you'll keep the source playing.

Exceptions

EndOfStreamException when there's no more data to feed from the stream. You may seek the stream and keep going, for instance, for a looping stream. Any other exception would be fatal.

Definition at line 115 of file OpenALStreamingSound.cpp.

References AL_NULL_BUFFER, Audio::__impl::OpenAL::asALFormat(), buffer, checkAlError, clearAlError, UnitUtil::getName(), and NUM_BUFFERS.

Referenced by Audio::OpenALRenderableStreamingSource::queueALBuffers().

     {
         if (!isLoaded())
             throw ResourceNotLoadedException(getName());
         
         // Check for a full queue
         if (playBufferIndex == readBufferIndex)
             return AL_NULL_BUFFER;
         
         bufferStarts[readBufferIndex] = getStream()->getPosition();
         
         readBuffer(buffer);
         
         // Break if there's no more data
         if (buffer.getUsedBytes() == 0)
             throw EndOfStreamException();
         
         ALBufferHandle bufferHandle = bufferHandles[readBufferIndex];
 
         clearAlError();
         alBufferData(bufferHandle, 
             asALFormat(targetFormat), 
             buffer.getBuffer(), buffer.getUsedBytes(), 
             targetFormat.sampleFrequency);
         checkAlError();
         
         if (playBufferIndex == NUM_BUFFERS)
             playBufferIndex = readBufferIndex;
         
         readBufferIndex = (readBufferIndex + 1) % NUM_BUFFERS;
         return bufferHandle;
     }

void Audio::OpenALStreamingSound::seek	(	double	position)
throw	(	Exception
	)

Set the stream's position, in seconds

See Also: Stream::seek(double)

Definition at line 157 of file OpenALStreamingSound.cpp.

References UnitUtil::getName().

Referenced by Audio::OpenALRenderableStreamingSource::queueALBuffers().

     {
         if (!isLoaded())
             throw ResourceNotLoadedException(getName());
         
         getStream()->seek(position);
     }

void Audio::OpenALStreamingSound::unloadImpl	(	)
throw	(
	)

protectedvirtual

Unload the resource.

Note: Assume it is loaded

Implements Audio::Sound.

Definition at line 106 of file OpenALStreamingSound.cpp.

References AL_NULL_BUFFER.

     {
         if (isStreamLoaded())
             closeStream();
         if (bufferHandles[0] != AL_NULL_BUFFER)
             alDeleteBuffers(sizeof(bufferHandles)/sizeof(bufferHandles[0]), bufferHandles);
     }

void Audio::OpenALStreamingSound::unqueueBuffer	(	ALBufferHandle	buffer)
throw	(	Exception
	)

Notify a dequeued buffer

Remarks: The function will not do anything, but it will mark the specified buffer as dequeued, allowing readAndFlip() to use it for new data. The caller is expected to have detached the buffer from the source.

Definition at line 149 of file OpenALStreamingSound.cpp.

References buffer, and NUM_BUFFERS.

Referenced by Audio::OpenALRenderableStreamingSource::queueALBuffers().

     {
         if (playBufferIndex < NUM_BUFFERS && buffer == bufferHandles[playBufferIndex]) {
             playBufferIndex = (playBufferIndex + 1) % NUM_BUFFERS;
         }
     }

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

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

Public Member Functions

Protected Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation