#include <RenderableSource.h>

Inheritance diagram for Audio::RenderableSource:

Public Types
enum	UpdateFlags { UPDATE_ALL = 0x0F, UPDATE_LOCATION = 0x01, UPDATE_ATTRIBUTES = 0x02, UPDATE_EFFECTS = 0x04, UPDATE_GAIN = 0x08 }

Public Member Functions
virtual	~RenderableSource ()

void	startPlaying (Timestamp start=0) throw (Exception)

void	stopPlaying () throw ()

bool	isPlaying () const throw ()

Timestamp	getPlayingTime () const throw (Exception)

Source *	getSource () const throw ()

void	seek (Timestamp time) throw (Exception)

void	update (int flags, const Listener &sceneListener) throw ()

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

Protected Member Functions
	RenderableSource (Source *source) throw ()

virtual void	startPlayingImpl (Timestamp start)=0 throw (Exception)

virtual void	stopPlayingImpl ()=0 throw (Exception)

virtual bool	isPlayingImpl () const =0 throw (Exception)

virtual Timestamp	getPlayingTimeImpl () const =0 throw (Exception)

virtual void	updateImpl (int flags, const Listener &sceneListener)=0 throw (Exception)

virtual void	seekImpl (Timestamp time)=0 throw (Exception)

Detailed Description

Renderable Source abstract class

Remarks: This is the interface to renderer-specific sources. All abstract sources must get attached to a renderable source. And each renderable source is attached to an abstract source.

All attributes come from the abstract source, so this class only has renderer-specific: state and resources, plus implementation functions. Since it is intended to be attached to abstract sources as any user data would, it is a subclass of UserData.

Note: Since this mutual attachment would create circular references, it is implemented on this side with raw pointers. No problem should arise since the smart pointer used in abstract sources already handles everything correctly, but care must be had not to have detached renderable sources around.

Definition at line 34 of file RenderableSource.h.

Member Enumeration Documentation

enum Audio::RenderableSource::UpdateFlags

Enumerator
UPDATE_ALL
UPDATE_LOCATION
UPDATE_ATTRIBUTES
UPDATE_EFFECTS
UPDATE_GAIN

Definition at line 46 of file RenderableSource.h.

                          {
             UPDATE_ALL          = 0x0F,
             UPDATE_LOCATION     = 0x01,
             UPDATE_ATTRIBUTES   = 0x02,
             UPDATE_EFFECTS      = 0x04,
             UPDATE_GAIN         = 0x08
         };

Constructor & Destructor Documentation

Audio::RenderableSource::RenderableSource	(	Source *	source)
throw	(
	)

protected

Internal constructor used by derived classes

Definition at line 11 of file RenderableSource.cpp.

                                                               : 
         source(_source)
     {
     }

Audio::RenderableSource::~RenderableSource ( )

virtual

Definition at line 16 of file RenderableSource.cpp.

     {
         // Just in case.
         source = 0;
     }

Member Function Documentation

Timestamp Audio::RenderableSource::getPlayingTime	(	)	const
throw	(	Exception
	)

Get the playing position of a playing source

Remarks: Will throw if it's not playing!

Definition at line 57 of file RenderableSource.cpp.

References getPlayingTimeImpl().

     {
         return getPlayingTimeImpl();
     }

virtual Timestamp Audio::RenderableSource::getPlayingTimeImpl	(	)	const
throw	(	Exception
	)

protectedpure virtual

See Also: getPlayingTime.

Implemented in Audio::OpenALRenderableStreamingSource, and Audio::OpenALRenderableSource.

Referenced by getPlayingTime().

Source* Audio::RenderableSource::getSource	(	)	const
throw	(
	)

inline

Get the attached source

Definition at line 75 of file RenderableSource.h.

Referenced by Audio::OpenALRenderableSource::attachALBuffers(), Audio::OpenALRenderableStreamingSource::getPlayingTimeImpl(), and Audio::OpenALRenderableStreamingSource::queueALBuffers().

75 { return source; }

bool Audio::RenderableSource::isPlaying	(	)	const
throw	(
	)

Is the source still playing?

Definition at line 45 of file RenderableSource.cpp.

References e, and isPlayingImpl().

Referenced by stopPlaying().

     {
         try {
             return isPlayingImpl();
         } catch(Exception e) {
             // Cannot be playing if an exception rises, 
             // as that implies a problem with the underlying API
             return false;
         }
     }

virtual bool Audio::RenderableSource::isPlayingImpl	(	)	const
throw	(	Exception
	)

protectedpure virtual

See Also: isPlaying.

Implemented in Audio::OpenALRenderableStreamingSource, and Audio::OpenALRenderableSource.

Referenced by isPlaying().

void Audio::RenderableSource::seek	(	Timestamp	time)
throw	(	Exception
	)

Seek to the specified position

Note: It may not be supported by the renderer on all sources. Streaming sources are guaranteed to perform a rough seek on a best effort basis, meaning the effective time after the seek may be off a bit, and the process may be costly. Seeking in non-streaming sources may not be supported at all.

Exceptions

EndOfStreamException if you try to seek past the end

Definition at line 73 of file RenderableSource.cpp.

     {
         seekImpl(time);
     }

virtual void Audio::RenderableSource::seekImpl	(	Timestamp	time)
throw	(	Exception
	)

protectedpure virtual

See Also: seek.

Implemented in Audio::OpenALRenderableStreamingSource, and Audio::OpenALRenderableSource.

void Audio::RenderableSource::startPlaying	(	Timestamp	start = `0`)
throw	(	Exception
	)

Play the source from the specified timestamp

Parameters

start The starting position. Defaults to the beginning.

Remarks: It just plays. Will not synchronize attributes with the underlying API. That must be done through a separate update() call.

Definition at line 22 of file RenderableSource.cpp.

References start.

     {
         try {
             startPlayingImpl(start);
         } catch(EndOfStreamException) {
             // Silently discard EOS, results in the more transparent
             // behavior of simply notifying listeners of source
             // termination ASAP, which is also accurate.
         };
     }

virtual void Audio::RenderableSource::startPlayingImpl	(	Timestamp	start)
throw	(	Exception
	)

protectedpure virtual

See Also: startPlaying

Parameters

start The starting position.

Implemented in Audio::OpenALRenderableStreamingSource, and Audio::OpenALRenderableSource.

void Audio::RenderableSource::stopPlaying	(	)
throw	(
	)

Stop a playing source

Remarks: If the source is playing, stop it. Otherwise, do nothing.

Definition at line 34 of file RenderableSource.cpp.

References e, isPlaying(), and stopPlayingImpl().

     {
         // Cannot be playing if an exception rises, 
         // as that implies a problem with the underlying API
         try {
             if (isPlaying())
                 stopPlayingImpl();
         } catch(Exception e) {}
     }

virtual void Audio::RenderableSource::stopPlayingImpl	(	)
throw	(	Exception
	)

protectedpure virtual

See Also: stopPlaying.

Implemented in Audio::OpenALRenderableStreamingSource, and Audio::OpenALRenderableSource.

Referenced by stopPlaying().

void Audio::RenderableSource::update	(	int	flags,
		const Listener &	sceneListener
	)
throw	(
	)

Update the underlying API with dirty attributes

Parameters

flags	You may specify which attributes to update. Not all attributes are equally costly, so you'll want to ease up on some, pump up some others. You may or-combine flags.
sceneListener	A reference listener. If it is the root listener attached to the renderer, no special translation is done, but if it is not, coordinates will be first translated to listener-space.

Remarks: Although the implementation may throw exceptions, the interface will ignore them (just log them or something like that). Updates are non-critical and may fail silently.

Definition at line 63 of file RenderableSource.cpp.

References e, fprintf, and Audio::Exception::what().

     {
         try {
             updateImpl(flags, sceneListener);
         } catch(Exception e) {
             fprintf(stderr, "Ignoring exception in renderable update: %s", e.what());
         }
     }

virtual void Audio::RenderableSource::updateImpl	(	int	flags,
		const Listener &	sceneListener
	)
throw	(	Exception
	)

protectedpure virtual

See Also: update.

Implemented in Audio::OpenALRenderableStreamingSource, and Audio::OpenALRenderableSource.

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

src/audio/RenderableSource.h
src/audio/RenderableSource.cpp

Public Types

Public Member Functions

Protected Member Functions

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation