Emergency 2017 Dokumentation  v3.0.1
qsf::AudioManager Class Referenceabstract

Abstract audio manager base class. More...

#include <AudioManager.h>

Classes

struct  Format
 Audio format. More...
 
struct  Statistics
 Audio statistics. More...
 

Public Types

enum  ListenerAttribute {
  LISTENER_POSITION = 0, LISTENER_VELOCITY = 1, LISTENER_FORWARD = 2, LISTENER_UPWARD = 3,
  LISTENER_ATTRIBUTES = 4
}
 Listener attribute. More...
 
enum  DefaultMixerChannels {
  MIXERCHANNEL_MASTER = 0, MIXERCHANNEL_SPEECH = 1, MIXERCHANNEL_SFX = 2, MIXERCHANNEL_MUSIC = 3,
  MIXERCHANNEL_GUI = 4, MIXERCHANNEL_VIDEO = 5
}
 Default hard-codec mixer channels TODO(oi) Mixer channel configuration should be project-dependent and not hardcoded. More...
 

Public Member Functions

virtual ~AudioManager ()
 Destructor. More...
 
const StatisticsgetStatistics () const
 Return the audio statistics. More...
 
AudioMixergetAudioMixer ()
 Access to the audio mixer for mixing channel management. More...
 
const AudioMixergetAudioMixer () const
 Access to the audio mixer for mixing channel management. More...
 
virtual std::string getDescription () const =0
 Return the audio manager description. More...
 
virtual void getFormatList (std::vector< Format > &formats) const =0
 Get a list of all known audio formats. More...
 
virtual float getVolume () const =0
 Get the master volume. More...
 
virtual void setVolume (float volume)=0
 Set the master volume. More...
 
virtual float getPitch () const =0
 Return the master pitch multiplier. More...
 
virtual void setPitch (float pitch)=0
 Set the master pitch multiplier. More...
 
virtual float getDopplerFactor () const =0
 Get the doppler factor. More...
 
virtual void setDopplerFactor (float factor)=0
 Set the doppler factor. More...
 
virtual void pauseAllActiveAudioSources ()=0
 Pauses all currently active audio sources. More...
 
virtual void resumeAllActiveAudioSources ()=0
 Resume all currently active audio sources. More...
 
virtual void update ()=0
 Update the audio manager. More...
 
virtual AudioBuffercreateAudioBuffer (const std::string &filename, bool stream=false)=0
 Create a new audio buffer. More...
 
virtual AudioBuffercreateAudioBuffer ()=0
 
virtual void destroyAudioBuffer (AudioBuffer &audioBuffer)=0
 Destroys a audio buffer instance. More...
 
virtual AudioSourcecreateAudioSourceWithAudioBuffer (AudioBuffer *audioBuffer=nullptr, bool isSpatial=false)=0
 Create an audio source with the specified audio buffer. More...
 
virtual AudioSourcecreateAudioSource (const std::string &filename, bool stream=false, bool isSpatial=false)=0
 Create an audio source, potentially sharing and caching the underlying audio buffer. More...
 
virtual void destroyAudioSource (AudioSource &audioSource)=0
 Destroys a audio source instance. More...
 
virtual bool queryDurationOfAudioAsset (const std::string &audioFile, Time &outDuration)=0
 Queries the playback duration of any audio file. More...
 
virtual const glm::vec3 & getListenerAttribute (ListenerAttribute listenerAttribute) const =0
 Get a listener attribute value. More...
 
virtual bool setListenerAttribute (ListenerAttribute listenerAttribute, const glm::vec3 &value)=0
 Set a listener attribute value. More...
 
virtual bool startup ()=0
 Startup the audio manager. More...
 

Protected Member Functions

 AudioManager ()
 Default constructor. More...
 
virtual void notifyChannelVolumeChanged (uint32 channelIndex, float newVolume)=0
 Notifies the implementation of the audio manager that a channel volume has changed. More...
 
- Protected Member Functions inherited from qsf::Manager
 Manager ()
 Default constructor. More...
 
virtual ~Manager ()
 Destructor. More...
 

Protected Attributes

Statistics mStatistics
 Audio statistics. More...
 
AudioMixermAudioMixer
 Personal audio mixer. More...
 

Friends

class AudioResource
 Audio resources automatically register and unregister themselves. More...
 
class AudioMixer
 Audio mixer notifies when channel volumes change. More...
 

Detailed Description

Abstract audio manager base class.

Note
  • Does not unload unused resources automatically by default
  • The audio manager and related classes are based on codes from the open-source engine PixelLight (MIT license, www.pixellight.org), for more backend like FMOD Ex see PixelLight
Todo:
  • TODO(co) Audio is a good multithreading candidate: Load and stream audio in a separate thread

Definition at line 54 of file AudioManager.h.

Member Enumeration Documentation

Default hard-codec mixer channels TODO(oi) Mixer channel configuration should be project-dependent and not hardcoded.

Enumerator
MIXERCHANNEL_MASTER 

Master channel, everything routes finally into this channel.

MIXERCHANNEL_SPEECH 

Speech channel, routing into the master.

MIXERCHANNEL_SFX 

SFX channel, routing into the master.

MIXERCHANNEL_MUSIC 

Music channel, routing into the master.

MIXERCHANNEL_GUI 

GUI SFX channel, routing into the master.

MIXERCHANNEL_VIDEO 

Video-audio channel, routing into the master.

Definition at line 87 of file AudioManager.h.

Listener attribute.

Enumerator
LISTENER_POSITION 

Listener position (float3, x/y/z)

LISTENER_VELOCITY 

Listener velocity in meters per second (float3, x/y/z)

LISTENER_FORWARD 

Listener forward unit length orientation vector (float3, x/y/z)

LISTENER_UPWARD 

Listener upwards facing unit length orientation vector (float3, x/y/z)

LISTENER_ATTRIBUTES 

Number of listener attributes.

Definition at line 73 of file AudioManager.h.

Constructor & Destructor Documentation

virtual qsf::AudioManager::~AudioManager ( )
virtual

Destructor.

qsf::AudioManager::AudioManager ( )
protected

Default constructor.

Member Function Documentation

virtual AudioBuffer* qsf::AudioManager::createAudioBuffer ( const std::string &  filename,
bool  stream = false 
)
pure virtual

Create a new audio buffer.

Parameters
[in]filenameUTF-8 audio filename, if empty, only create the audio buffer without loading it (supported file formats are API dependent)
[in]streamStream the file? (recommended for large files!)
Returns
The created audio buffer, a null pointer on error, don't destroy the instance
Note
  • This method will always create a new audio buffer, use "qsf::AudioManager::createCachedAudioSource(...)" instead whenever possible
  • Not each audio buffer can be streamed, use "qsf::AudioBuffer::isStreamed()" to check whether streaming is used

Implemented in qsf::openal::OpenALAudioManager, and qsf::null::NullAudioManager.

virtual AudioBuffer* qsf::AudioManager::createAudioBuffer ( )
pure virtual
virtual AudioSource* qsf::AudioManager::createAudioSource ( const std::string &  filename,
bool  stream = false,
bool  isSpatial = false 
)
pure virtual

Create an audio source, potentially sharing and caching the underlying audio buffer.

Parameters
[in]filenameUTF-8 audio filename
[in]streamStream the file? (recommended for large files!)
[in]isSpatialIndicates if the source is spatial (3D sound)
Returns
The created audio buffer, a null pointer on error, don't destroy the instance
Note
  • This method will add all created audio buffers to an internal cache and will reuse the same audio buffer object if called again with the same filename/stream parameters
  • Not each audio buffer can be streamed, use "qsf::AudioBuffer::isStreamed()" to check whether streaming is used
Remarks
The simplest creation of a audio source ready for playback would be:
AudioSource* audioSource = audioManager->createAudioSource("MyAudio.ogg");

Implemented in qsf::openal::OpenALAudioManager, and qsf::null::NullAudioManager.

virtual AudioSource* qsf::AudioManager::createAudioSourceWithAudioBuffer ( AudioBuffer audioBuffer = nullptr,
bool  isSpatial = false 
)
pure virtual

Create an audio source with the specified audio buffer.

Parameters
[in]audioBufferAudio buffer to load, a null pointer if load no audio buffer by default
[in]isSpatialIndicates if the source is spatial (3D sound)
Returns
The created audio source, a null pointer on error, don't destroy the instance yourself! Instead, call destroyAudioSource()
Note
  • Only use this method if you need a unique mutable AudioBuffer instance, otherwise use "qsf::AudioManager::createAudioSource(...)" instead

Implemented in qsf::openal::OpenALAudioManager, and qsf::null::NullAudioManager.

virtual void qsf::AudioManager::destroyAudioBuffer ( AudioBuffer audioBuffer)
pure virtual

Destroys a audio buffer instance.

Parameters
[in]audioBufferReference to the audio buffer which should be destroyed. Don't use the reference anymore after destroying it as it will be gone!

Implemented in qsf::openal::OpenALAudioManager, and qsf::null::NullAudioManager.

virtual void qsf::AudioManager::destroyAudioSource ( AudioSource audioSource)
pure virtual

Destroys a audio source instance.

Parameters
[in]audioSourceReference to the audio source which should be destroyed. Don't use the reference anymore after destroying it as it will be gone!

Implemented in qsf::openal::OpenALAudioManager, and qsf::null::NullAudioManager.

AudioMixer & qsf::AudioManager::getAudioMixer ( )
inline

Access to the audio mixer for mixing channel management.

Definition at line 19 of file AudioManager-inl.h.

const AudioMixer & qsf::AudioManager::getAudioMixer ( ) const
inline

Access to the audio mixer for mixing channel management.

Definition at line 24 of file AudioManager-inl.h.

virtual std::string qsf::AudioManager::getDescription ( ) const
pure virtual

Return the audio manager description.

Returns
UTF-8 audio manager description

Implemented in qsf::openal::OpenALAudioManager, and qsf::null::NullAudioManager.

virtual float qsf::AudioManager::getDopplerFactor ( ) const
pure virtual

Get the doppler factor.

Returns
Doppler factor
Remarks
If velocities are applied to the listener object or to any source object, then doppler shift will be applied to the audio. The following formula is used to calculate doppler shift:
f’ = f*(DV – DF*vl)/(DV + DF*vs)
DV = doppler velocity
DF = doppler factor
vl = listener velocity (scalar value along source-to-listener vector)
vs = source velocity (scalar value along source-to-listener vector)
f = frequency of sample
f’ = Doppler shifted frequency
The doppler velocity (340) represents the speed of audio.
The doppler factor is used to exaggerate or de-emphasize the doppler shift.

Implemented in qsf::openal::OpenALAudioManager, and qsf::null::NullAudioManager.

virtual void qsf::AudioManager::getFormatList ( std::vector< Format > &  formats) const
pure virtual

Get a list of all known audio formats.

Parameters
[out]formatsList to receive the known audio formats, the given list is not cleared before the formats are added

Implemented in qsf::openal::OpenALAudioManager, and qsf::null::NullAudioManager.

virtual const glm::vec3& qsf::AudioManager::getListenerAttribute ( ListenerAttribute  listenerAttribute) const
pure virtual

Get a listener attribute value.

Parameters
[in]listenerAttributeListener attribute to return
Returns
Requested listener attribute value

Implemented in qsf::openal::OpenALAudioManager, and qsf::null::NullAudioManager.

virtual float qsf::AudioManager::getPitch ( ) const
pure virtual

Return the master pitch multiplier.

Returns
Pitch multiplier
Remarks
pitch < 1.0 = slower
pitch = 1.0 = normal
pitch > 1.0 = faster

Implemented in qsf::openal::OpenALAudioManager, and qsf::null::NullAudioManager.

const AudioManager::Statistics & qsf::AudioManager::getStatistics ( ) const
inline

Return the audio statistics.

Returns
The audio statistics, do not destroy the instance

Definition at line 14 of file AudioManager-inl.h.

virtual float qsf::AudioManager::getVolume ( ) const
pure virtual

Get the master volume.

Returns
Volume (value from 0.0-1.0 -> 0.0 = silence, 1.0 = full volume)

Implemented in qsf::openal::OpenALAudioManager, and qsf::null::NullAudioManager.

virtual void qsf::AudioManager::notifyChannelVolumeChanged ( uint32  channelIndex,
float  newVolume 
)
protectedpure virtual

Notifies the implementation of the audio manager that a channel volume has changed.

Remarks
When channels are chained, this is called for every channel which volume is changing, not only the actually changed channel, so no need to do recursive resolves in here.

Implemented in qsf::openal::OpenALAudioManager, and qsf::null::NullAudioManager.

virtual void qsf::AudioManager::pauseAllActiveAudioSources ( )
pure virtual

Pauses all currently active audio sources.

Implemented in qsf::openal::OpenALAudioManager, and qsf::null::NullAudioManager.

virtual bool qsf::AudioManager::queryDurationOfAudioAsset ( const std::string &  audioFile,
Time outDuration 
)
pure virtual

Queries the playback duration of any audio file.

Parameters
[in]audioFileAny reference to a file which resembles a valid audio asset (i.e. you could create an AudioBuffer from it)
[out]outDurationReference to a qsf::Time where the duration of the asset is stored in case it can be retrieved from the asset.
Returns
Returns "true" when the outDuration could be filled out or "false" if there was an error, e.g. the passed asset is no audio asset or the length could not be determined from the data of the asset.

Implemented in qsf::openal::OpenALAudioManager, and qsf::null::NullAudioManager.

virtual void qsf::AudioManager::resumeAllActiveAudioSources ( )
pure virtual

Resume all currently active audio sources.

Implemented in qsf::openal::OpenALAudioManager, and qsf::null::NullAudioManager.

virtual void qsf::AudioManager::setDopplerFactor ( float  factor)
pure virtual

Set the doppler factor.

Parameters
[in]factorDoppler factor
See also
  • "qsf::AudioManager::getDopplerFactor()"

Implemented in qsf::openal::OpenALAudioManager, and qsf::null::NullAudioManager.

virtual bool qsf::AudioManager::setListenerAttribute ( ListenerAttribute  listenerAttribute,
const glm::vec3 &  value 
)
pure virtual

Set a listener attribute value.

Parameters
[in]listenerAttributeListener attribute to set
[in]valueNew listener attribute value
Returns
"true" if all went fine, else "false"

Implemented in qsf::openal::OpenALAudioManager, and qsf::null::NullAudioManager.

virtual void qsf::AudioManager::setPitch ( float  pitch)
pure virtual

Set the master pitch multiplier.

Parameters
[in]pitchPitch multiplier
See also
  • "qsf::AudioManager::getPitch()"

Implemented in qsf::openal::OpenALAudioManager, and qsf::null::NullAudioManager.

virtual void qsf::AudioManager::setVolume ( float  volume)
pure virtual

Set the master volume.

Parameters
[in]volumeVolume (value from 0.0-1.0 -> 0.0 = silence, 1.0 = full volume)

Implemented in qsf::openal::OpenALAudioManager, and qsf::null::NullAudioManager.

virtual bool qsf::AudioManager::startup ( )
pure virtual

Startup the audio manager.

Implemented in qsf::openal::OpenALAudioManager, and qsf::null::NullAudioManager.

virtual void qsf::AudioManager::update ( )
pure virtual

Update the audio manager.

Implemented in qsf::openal::OpenALAudioManager, and qsf::null::NullAudioManager.

Friends And Related Function Documentation

friend class AudioMixer
friend

Audio mixer notifies when channel volumes change.

Definition at line 62 of file AudioManager.h.

friend class AudioResource
friend

Audio resources automatically register and unregister themselves.

Definition at line 61 of file AudioManager.h.

Member Data Documentation

AudioMixer* qsf::AudioManager::mAudioMixer
protected

Personal audio mixer.

Definition at line 445 of file AudioManager.h.

Statistics qsf::AudioManager::mStatistics
protected

Audio statistics.

Definition at line 444 of file AudioManager.h.


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