MezzanineEngine 
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
audiomanager.h
1 // © Copyright 2010 - 2014 BlackTopp Studios Inc.
2 /* This file is part of The Mezzanine Engine.
3 
4  The Mezzanine Engine is free software: you can redistribute it and/or modify
5  it under the terms of the GNU General Public License as published by
6  the Free Software Foundation, either version 3 of the License, or
7  (at your option) any later version.
8 
9  The Mezzanine Engine is distributed in the hope that it will be useful,
10  but WITHOUT ANY WARRANTY; without even the implied warranty of
11  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12  GNU General Public License for more details.
13 
14  You should have received a copy of the GNU General Public License
15  along with The Mezzanine Engine. If not, see <http://www.gnu.org/licenses/>.
16 */
17 /* The original authors have included a copy of the license specified above in the
18  'Docs' folder. See 'gpl.txt'
19 */
20 /* We welcome the use of the Mezzanine engine to anyone, including companies who wish to
21  Build professional software and charge for their product.
22 
23  However there are some practical restrictions, so if your project involves
24  any of the following you should contact us and we will try to work something
25  out:
26  - DRM or Copy Protection of any kind(except Copyrights)
27  - Software Patents You Do Not Wish to Freely License
28  - Any Kind of Linking to Non-GPL licensed Works
29  - Are Currently In Violation of Another Copyright Holder's GPL License
30  - If You want to change our code and not add a few hundred MB of stuff to
31  your distribution
32 
33  These and other limitations could cause serious legal problems if you ignore
34  them, so it is best to simply contact us or the Free Software Foundation, if
35  you have any questions.
36 
37  Joseph Toppi - toppij@gmail.com
38  John Blackwood - makoenergy02@gmail.com
39 */
40 // Copyright (c) 2008-2010 Raynaldo (Wildicv) Rivera, Joshua (Dark_Kilauea) Jones
41 // This file is part of the "cAudio Engine"
42 // For conditions of distribution and use, see copyright notice in cAudio-ZLIBLicense.txt
43 #ifndef _audioaudiomanager_h
44 #define _audioaudiomanager_h
45 
46 #include "datatypes.h"
47 #include "managerbase.h"
48 #include "managerfactory.h"
49 #include "singleton.h"
50 #include "objectsettings.h"
51 #include "audioenumerations.h"
52 
53 #include "Resource/datastream.h"
54 #include "Threading/workunit.h"
55 
56 namespace Mezzanine
57 {
58  namespace Audio
59  {
60  class iSound;
61  class iRecorder;
62  class iDecoder;
63  class iDecoderFactory;
64  class iEffectsHandler;
65  class MusicPlayer;
66  class SoundScapeManager;
67 
68  ///////////////////////////////////////////////////////////////////////////////
69  /// @brief This is the work unit for updating audio buffers as necessary for audio playback.
70  /// @details
71  ///////////////////////////////////////
73  {
74  public:
75  /// @brief Class destructor.
77 
78  ///////////////////////////////////////////////////////////////////////////////
79  // Utility
80 
81  /// @brief This does any required updating of audio buffers belonging to sources in this manager.
82  /// @param CurrentThreadStorage The storage class for all resources owned by this work unit during it's execution.
83  virtual void DoWork(Threading::DefaultThreadSpecificStorage::Type& CurrentThreadStorage) = 0;
84  };//iBufferUpdate2DWorkUnit
85 
86  ///////////////////////////////////////////////////////////////////////////////
87  /// @brief This is the work unit for marking all effects and filters as clean after sounds have been processed.
88  /// @details
89  ///////////////////////////////////////
91  {
92  public:
93  /// @brief Class destructor.
95 
96  ///////////////////////////////////////////////////////////////////////////////
97  // Utility
98 
99  /// @brief This does the required cleaning of all effects and filters in use by this manager.
100  /// @param CurrentThreadStorage The storage class for all resources owned by this work unit during it's execution.
101  virtual void DoWork(Threading::DefaultThreadSpecificStorage::Type& CurrentThreadStorage) = 0;
102  };//iEffectFilterCleanWorkUnit
103 
104  // Used by the scripting language binder to help create bindgings for this class. SWIG does know to creation template instances
105  #ifdef SWIG
106  %template(SingletonAudioManager) Singleton<AudioManager>;
107  #endif
108 
109  ///////////////////////////////////////////////////////////////////////////////
110  /// @brief This is the base manager class for the Audio subsystem and it's operations.
111  /// @details This is a place for loading, storing, and running sound files as
112  /// necessary in a given application.
113  ///////////////////////////////////////
115  {
116  public:
117  /// @brief Basic container type for @ref iDecoderFactory storage by this class.
118  typedef std::map<Audio::Encoding,iDecoderFactory*> DecoderFactoryContainer;
119  /// @brief Iterator type for @ref iDecoderFactory instances stored by this class.
120  typedef DecoderFactoryContainer::iterator DecoderFactoryIterator;
121  /// @brief Const Iterator type for @ref iDecoderFactory instances stored by this class.
122  typedef DecoderFactoryContainer::const_iterator ConstDecoderFactoryIterator;
123  protected:
124  /// @internal
125  /// @brief Container storing all registered @ref iDecoderFactory instances.
126  DecoderFactoryContainer DecoderFactories;
127  public:
128  /// @brief Class Constructor.
129  AudioManager();
130  /// @brief XML constructor.
131  /// @param XMLNode The node of the xml document to construct from.
132  AudioManager(XML::Node& XMLNode);
133  /// @brief Class Destructor.
134  /// @details The class destructor.
135  virtual ~AudioManager();
136 
137  ///////////////////////////////////////////////////////////////////////////////
138  // Sound Management
139 
140  /// @brief Creates a blank @ref iSound without a stream attached to it.
141  /// @param Type A UInt16 that is the ID for the type of sound the created @ref iSound is to be categorized as.
142  /// @return Returns a pointer to the @ref iSound instance that was created.
143  virtual iSound* CreateSound(const UInt16 Type) = 0;
144  /// @brief Creates a new @ref iSound from a custom stream that is encoded.
145  /// @param Type A UInt16 that is the ID for the type of sound the created @ref iSound is to be categorized as.
146  /// @param Stream A Datastream containing the data to be streamed for this @ref iSound.
147  /// @param Encode The encoding to be expected when decoding audio for this @ref iSound.
148  /// @return Returns a pointer to the @ref iSound instance that was created.
149  virtual iSound* CreateSound(const UInt16 Type, Resource::DataStreamPtr Stream, const Audio::Encoding Encode) = 0;
150  /// @brief Creates a new @ref iSound from a custom stream that is unencoded.
151  /// @param Type A UInt16 that is the ID for the type of sound the created @ref iSound is to be categorized as.
152  /// @param Stream A Datastream containing the data to be streamed for this @ref iSound.
153  /// @param Frequency The frequency (or sample rate) of the audio data.
154  /// @param Config The bit configuration of the audio data. Helps to determine sample size.
155  /// @return Returns a pointer to the @ref iSound instance that was created.
156  virtual iSound* CreateSound(const UInt16 Type, Resource::DataStreamPtr Stream, const UInt32 Frequency, const Audio::BitConfig Config) = 0;
157  /// @brief Creates a new @ref iSound from a file.
158  /// @param Type A UInt16 that is the ID for the type of sound the created @ref iSound is to be categorized as.
159  /// @param FileName The name of the file to read audio data from.
160  /// @param Group The resource group in which the file resides.
161  /// @return Returns a pointer to the @ref iSound instance that was created.
162  virtual iSound* CreateSound(const UInt16 Type, const String& FileName, const String& Group) = 0;
163  /// @brief Creates a new @ref iSound from a memory buffer that is encoded.
164  /// @note The created stream will take ownership of the buffer you provide. If you want it to have a separate buffer then create a copy and pass that in.
165  /// @param Type A UInt16 that is the ID for the type of sound the created @ref iSound is to be categorized as.
166  /// @param StreamName The name to be given to the stream being created.
167  /// @param Buffer A pointer to the buffer where the audio data is located.
168  /// @param Length The length of the buffer provided to this method(in bytes).
169  /// @param Encode The encoding to be expected when decoding audio for this @ref iSound.
170  /// @return Returns a pointer to the @ref iSound instance that was created.
171  virtual iSound* CreateSound(const UInt16 Type, const String& StreamName, Char8* Buffer, const UInt32 Length, const Audio::Encoding Encode) = 0;
172  /// @brief Creates a new @ref iSound from a memory buffer that is unencoded.
173  /// @note The created stream will take ownership of the buffer you provide. If you want it to have a separate buffer then create a copy and pass that in.
174  /// @param Type A UInt16 that is the ID for the type of sound the created @ref iSound is to be categorized as.
175  /// @param StreamName The name to be given to the stream being created.
176  /// @param Buffer A pointer to the buffer where the audio data is located.
177  /// @param Length The length of the buffer provided to this method(in bytes).
178  /// @param Frequency The frequency (or sample rate) of the audio data.
179  /// @param Config The bit configuration of the audio data. Helps to determine sample size.
180  /// @return Returns a pointer to the @ref iSound instance that was created.
181  virtual iSound* CreateSound(const UInt16 Type, const String& StreamName, Char8* Buffer, const UInt32 Length, const UInt32 Frequency, const Audio::BitConfig Config) = 0;
182  /// @brief Gets an @ref iSound instance by index.
183  /// @param Index The index of the @ref iSound to be retrieved.
184  /// @return Returns a pointer to the @ref iSound at the specified index.
185  virtual iSound* GetSound(const UInt32 Index) const = 0;
186  /// @brief Gets the number of @ref iSound instances in this manager.
187  /// @return Returns a UInt32 representing the number of @ref iSound instances contained in this manager.
188  virtual UInt32 GetNumSounds() const = 0;
189  /// @brief Deletes a @ref iSound.
190  /// @param ToBeDestroyed A pointer to the @ref iSound you want deleted.
191  virtual void DestroySound(iSound* ToBeDestroyed) = 0;
192  /// @brief Deletes all stored @ref iSound instances.
193  virtual void DestroyAllSounds() = 0;
194 
195  ///////////////////////////////////////////////////////////////////////////////
196  // Convenience Creation Methods
197 
198  /// @brief Creates a blank Ambient @ref iSound without a stream attached to it.
199  /// @return Returns a pointer to the @ref iSound instance that was created.
200  virtual iSound* CreateAmbientSound();
201  /// @brief Creates a blank Dialog @ref iSound without a stream attached to it.
202  /// @return Returns a pointer to the @ref iSound instance that was created.
203  virtual iSound* CreateDialogSound();
204  /// @brief Creates a blank Effect @ref iSound without a stream attached to it.
205  /// @return Returns a pointer to the @ref iSound instance that was created.
206  virtual iSound* CreateEffectSound();
207  /// @brief Creates a blank Music @ref iSound without a stream attached to it.
208  /// @return Returns a pointer to the @ref iSound instance that was created.
209  virtual iSound* CreateMusicSound();
210 
211  /// @brief Creates a new Ambient @ref iSound from a custom stream that is encoded.
212  /// @param Stream A Datastream containing the data to be streamed for this @ref iSound.
213  /// @param Encode The encoding to be expected when decoding audio for this @ref iSound.
214  /// @return Returns a pointer to the @ref iSound instance that was created.
215  virtual iSound* CreateAmbientSound(Resource::DataStreamPtr Stream, const Audio::Encoding Encode);
216  /// @brief Creates a new Dialog @ref iSound from a custom stream that is encoded.
217  /// @param Stream A Datastream containing the data to be streamed for this @ref iSound.
218  /// @param Encode The encoding to be expected when decoding audio for this @ref iSound.
219  /// @return Returns a pointer to the @ref iSound instance that was created.
220  virtual iSound* CreateDialogSound(Resource::DataStreamPtr Stream, const Audio::Encoding Encode);
221  /// @brief Creates a new Effect @ref iSound from a custom stream that is encoded.
222  /// @param Stream A Datastream containing the data to be streamed for this @ref iSound.
223  /// @param Encode The encoding to be expected when decoding audio for this @ref iSound.
224  /// @return Returns a pointer to the @ref iSound instance that was created.
225  virtual iSound* CreateEffectSound(Resource::DataStreamPtr Stream, const Audio::Encoding Encode);
226  /// @brief Creates a new Music @ref iSound from a custom stream that is encoded.
227  /// @param Stream A Datastream containing the data to be streamed for this @ref iSound.
228  /// @param Encode The encoding to be expected when decoding audio for this @ref iSound.
229  /// @return Returns a pointer to the @ref iSound instance that was created.
230  virtual iSound* CreateMusicSound(Resource::DataStreamPtr Stream, const Audio::Encoding Encode);
231 
232  /// @brief Creates a new Ambient @ref iSound from a custom stream that is unencoded.
233  /// @param Stream A Datastream containing the data to be streamed for this @ref iSound.
234  /// @param Frequency The frequency (or sample rate) of the audio data.
235  /// @param Config The bit configuration of the audio data. Helps to determine sample size.
236  /// @return Returns a pointer to the @ref iSound instance that was created.
237  virtual iSound* CreateAmbientSound(Resource::DataStreamPtr Stream, const UInt32 Frequency, const Audio::BitConfig Config);
238  /// @brief Creates a new Dialog @ref iSound from a custom stream that is unencoded.
239  /// @param Stream A Datastream containing the data to be streamed for this @ref iSound.
240  /// @param Frequency The frequency (or sample rate) of the audio data.
241  /// @param Config The bit configuration of the audio data. Helps to determine sample size.
242  /// @return Returns a pointer to the @ref iSound instance that was created.
243  virtual iSound* CreateDialogSound(Resource::DataStreamPtr Stream, const UInt32 Frequency, const Audio::BitConfig Config);
244  /// @brief Creates a new Effect @ref iSound from a custom stream that is unencoded.
245  /// @param Stream A Datastream containing the data to be streamed for this @ref iSound.
246  /// @param Frequency The frequency (or sample rate) of the audio data.
247  /// @param Config The bit configuration of the audio data. Helps to determine sample size.
248  /// @return Returns a pointer to the @ref iSound instance that was created.
249  virtual iSound* CreateEffectSound(Resource::DataStreamPtr Stream, const UInt32 Frequency, const Audio::BitConfig Config);
250  /// @brief Creates a new Music @ref iSound from a custom stream that is unencoded.
251  /// @param Stream A Datastream containing the data to be streamed for this @ref iSound.
252  /// @param Frequency The frequency (or sample rate) of the audio data.
253  /// @param Config The bit configuration of the audio data. Helps to determine sample size.
254  /// @return Returns a pointer to the @ref iSound instance that was created.
255  virtual iSound* CreateMusicSound(Resource::DataStreamPtr Stream, const UInt32 Frequency, const Audio::BitConfig Config);
256 
257  /// @brief Creates a new Ambient @ref iSound from a file.
258  /// @param FileName The name of the file to read audio data from.
259  /// @param Group The resource group in which the file resides.
260  /// @return Returns a pointer to the @ref iSound instance that was created.
261  virtual iSound* CreateAmbientSound(const String& FileName, const String& Group);
262  /// @brief Creates a new Dialog @ref iSound from a file.
263  /// @param FileName The name of the file to read audio data from.
264  /// @param Group The resource group in which the file resides.
265  /// @return Returns a pointer to the @ref iSound instance that was created.
266  virtual iSound* CreateDialogSound(const String& FileName, const String& Group);
267  /// @brief Creates a new Effect @ref iSound from a file.
268  /// @param FileName The name of the file to read audio data from.
269  /// @param Group The resource group in which the file resides.
270  /// @return Returns a pointer to the @ref iSound instance that was created.
271  virtual iSound* CreateEffectSound(const String& FileName, const String& Group);
272  /// @brief Creates a new Music @ref iSound from a file.
273  /// @param FileName The name of the file to read audio data from.
274  /// @param Group The resource group in which the file resides.
275  /// @return Returns a pointer to the @ref iSound instance that was created.
276  virtual iSound* CreateMusicSound(const String& FileName, const String& Group);
277 
278  /// @brief Creates a new Ambient @ref iSound from a memory buffer that is encoded.
279  /// @note The buffer is copied and put into a memory stream. Thus safe for disposal afterward.
280  /// @param StreamName The name to be given to the stream being created.
281  /// @param Buffer A pointer to the buffer where the audio data is located.
282  /// @param Length The length of the buffer provided to this method(in bytes).
283  /// @param Encode The encoding to be expected when decoding audio for this @ref iSound.
284  /// @return Returns a pointer to the @ref iSound instance that was created.
285  virtual iSound* CreateAmbientSound(const String& StreamName, Char8* Buffer, const UInt32 Length, const Audio::Encoding Encode);
286  /// @brief Creates a new Dialog @ref iSound from a memory buffer that is encoded.
287  /// @note The buffer is copied and put into a memory stream. Thus safe for disposal afterward.
288  /// @param SoundName The name of the @ref iSound instance.
289  /// @param Buffer A pointer to the buffer where the audio data is located.
290  /// @param Length The length of the buffer provided to this method(in bytes).
291  /// @param Encode The encoding to be expected when decoding audio for this @ref iSound.
292  /// @return Returns a pointer to the @ref iSound instance that was created.
293  virtual iSound* CreateDialogSound(const String& StreamName, Char8* Buffer, const UInt32 Length, const Audio::Encoding Encode);
294  /// @brief Creates a new Effect @ref iSound from a memory buffer that is encoded.
295  /// @note The buffer is copied and put into a memory stream. Thus safe for disposal afterward.
296  /// @param StreamName The name to be given to the stream being created.
297  /// @param Buffer A pointer to the buffer where the audio data is located.
298  /// @param Length The length of the buffer provided to this method(in bytes).
299  /// @param Encode The encoding to be expected when decoding audio for this @ref iSound.
300  /// @return Returns a pointer to the @ref iSound instance that was created.
301  virtual iSound* CreateEffectSound(const String& StreamName, Char8* Buffer, const UInt32 Length, const Audio::Encoding Encode);
302  /// @brief Creates a new Music @ref iSound from a memory buffer that is encoded.
303  /// @note The buffer is copied and put into a memory stream. Thus safe for disposal afterward.
304  /// @param StreamName The name to be given to the stream being created.
305  /// @param Buffer A pointer to the buffer where the audio data is located.
306  /// @param Length The length of the buffer provided to this method(in bytes).
307  /// @param Encode The encoding to be expected when decoding audio for this @ref iSound.
308  /// @return Returns a pointer to the @ref iSound instance that was created.
309  virtual iSound* CreateMusicSound(const String& StreamName, Char8* Buffer, const UInt32 Length, const Audio::Encoding Encode);
310 
311  /// @brief Creates a new Ambient @ref iSound from a memory buffer that is unencoded.
312  /// @note The buffer is copied and put into a memory stream. Thus safe for disposal afterward.
313  /// @param StreamName The name to be given to the stream being created.
314  /// @param Buffer A pointer to the buffer where the audio data is located.
315  /// @param Length The length of the buffer provided to this method(in bytes).
316  /// @param Frequency The frequency (or sample rate) of the audio data.
317  /// @param Config The bit configuration of the audio data. Helps to determine sample size.
318  /// @return Returns a pointer to the @ref iSound instance that was created.
319  virtual iSound* CreateAmbientSound(const String& StreamName, Char8* Buffer, const UInt32 Length, const UInt32 Frequency, const Audio::BitConfig Config);
320  /// @brief Creates a new Dialog @ref iSound from a memory buffer that is unencoded.
321  /// @note The buffer is copied and put into a memory stream. Thus safe for disposal afterward.
322  /// @param StreamName The name to be given to the stream being created.
323  /// @param Buffer A pointer to the buffer where the audio data is located.
324  /// @param Length The length of the buffer provided to this method(in bytes).
325  /// @param Frequency The frequency (or sample rate) of the audio data.
326  /// @param Config The bit configuration of the audio data. Helps to determine sample size.
327  /// @return Returns a pointer to the @ref iSound instance that was created.
328  virtual iSound* CreateDialogSound(const String& StreamName, Char8* Buffer, const UInt32 Length, const UInt32 Frequency, const Audio::BitConfig Config);
329  /// @brief Creates a new Effect @ref iSound from a memory buffer that is unencoded.
330  /// @note The buffer is copied and put into a memory stream. Thus safe for disposal afterward.
331  /// @param StreamName The name to be given to the stream being created.
332  /// @param Buffer A pointer to the buffer where the audio data is located.
333  /// @param Length The length of the buffer provided to this method(in bytes).
334  /// @param Frequency The frequency (or sample rate) of the audio data.
335  /// @param Config The bit configuration of the audio data. Helps to determine sample size.
336  /// @return Returns a pointer to the @ref iSound instance that was created.
337  virtual iSound* CreateEffectSound(const String& StreamName, Char8* Buffer, const UInt32 Length, const UInt32 Frequency, const Audio::BitConfig Config);
338  /// @brief Creates a new Music @ref iSound from a memory buffer that is unencoded.
339  /// @note The buffer is copied and put into a memory stream. Thus safe for disposal afterward.
340  /// @param StreamName The name to be given to the stream being created.
341  /// @param Buffer A pointer to the buffer where the audio data is located.
342  /// @param Length The length of the buffer provided to this method(in bytes).
343  /// @param Frequency The frequency (or sample rate) of the audio data.
344  /// @param Config The bit configuration of the audio data. Helps to determine sample size.
345  /// @return Returns a pointer to the @ref iSound instance that was created.
346  virtual iSound* CreateMusicSound(const String& StreamName, Char8* Buffer, const UInt32 Length, const UInt32 Frequency, const Audio::BitConfig Config);
347 
348  ///////////////////////////////////////////////////////////////////////////////
349  // Volume Management
350 
351  /// @brief Sets the volume for all stored Sound instances of the specified type.
352  /// @note Although this can accept any UInt16 value, be mindful of the SoundType enum to avoid type collisions.
353  /// @exception This method can throw a "II_IDENTITY_NOT_FOUND_EXCEPTION" if the a handler of the specified type does not exist.
354  /// @param Type A UInt16 that is the ID for the type of Sound instances to set the volume for.
355  /// @param Vol The new volume to apply to all sounds of the specified type.
356  virtual void SetTypeVolume(const UInt16 Type, const Real Vol) = 0;
357  /// @brief Gets the volume for all stored Sound instances of the specified type.
358  /// @note Although this can accept any UInt16 value, be mindful of the SoundType enum to avoid type collisions.
359  /// @exception This method can throw a "II_IDENTITY_NOT_FOUND_EXCEPTION" if the a handler of the specified type does not exist.
360  /// @param Type A UInt16 that is the ID for the type of Sound instances to get the volume of.
361  /// @return Returns a Real representing the current volume of the specified sound type.
362  virtual Real GetTypeVolume(const UInt16 Type) const = 0;
363  /// @brief Sets whether or not to mute all Sound instances of a specified type.
364  /// @note Although this can accept any UInt16 value, be mindful of the SoundType enum to avoid type collisions.
365  /// @exception This method can throw a "II_IDENTITY_NOT_FOUND_EXCEPTION" if the a handler of the specified type does not exist.
366  /// @param Type A UInt16 that is the ID for the type of Sound instances to mute or unmute.
367  /// @param Enable True to mute sounds of the specified type, false to unmute them.
368  virtual void MuteType(const UInt16 Type, bool Enable) = 0;
369  /// @brief Gets whether or not Sound instances of the specified type are currently muted.
370  /// @note Although this can accept any UInt16 value, be mindful of the SoundType enum to avoid type collisions.
371  /// @exception This method can throw a "II_IDENTITY_NOT_FOUND_EXCEPTION" if the a handler of the specified type does not exist.
372  /// @param Type A UInt16 that is the ID for the type of Sound instances to check.
373  /// @return Returns true if sounds of the specifed type are muted, false otherwise.
374  virtual bool IsTypeMuted(const UInt16 Type) const = 0;
375 
376  /// @brief Sets the volume for all stored Sound instances.
377  /// @param Music The volume to apply to all sounds.
378  virtual void SetMasterVolume(const Real& Master) = 0;
379  /// @brief Gets the currently set Master volume.
380  /// @return Returns a Real representing the current Master volume.
381  virtual Real GetMasterVolume() const = 0;
382  /// @brief Sets whether or not to mute all Audio.
383  /// @param Enable Whether or not all sounds should be muted.
384  virtual void SetMasterMute(bool Enable) = 0;
385  /// @brief Gets whether or not the Audio subsystem is muted.
386  /// @return Returns a bool indicating whether or not the Audio subsystem is currently muted.
387  virtual bool IsMuted() const = 0;
388 
389  ///////////////////////////////////////////////////////////////////////////////
390  // Convenience Type Volume Methods
391 
392  /// @brief Sets the volume for all stored Ambient Sound instances.
393  /// @param Ambient The volume to apply to all Ambient sounds.
394  virtual void SetAmbientVolume(const Real& Ambient);
395  /// @brief Gets the currently set Ambient volume.
396  /// @return Returns a Real representing the current Ambient volume.
397  virtual Real GetAmbientVolume() const;
398  /// @brief Sets whether or not to mute all Ambient Sound instances.
399  /// @param Enable True to mute Ambient sounds, false to unmute them.
400  virtual void MuteAmbient(bool Enable);
401  /// @brief Gets whether or not Ambient Sound instances are muted.
402  /// @return Returns true if Ambient sounds are muted, false otherwise.
403  virtual bool IsAmbientMuted() const;
404 
405  /// @brief Sets the volume for all stored Dialog Sound instances.
406  /// @param Dialog The volume to apply to all Dialog sounds.
407  virtual void SetDialogVolume(const Real& Dialog);
408  /// @brief Gets the currently set Dialog volume.
409  /// @return Returns a Real representing the current Dialog volume.
410  virtual Real GetDialogVolume() const;
411  /// @brief Sets whether or not to mute all Dialog Sound instances.
412  /// @param Enable True to mute Dialog sounds, false to unmute them.
413  virtual void MuteDialog(bool Enable);
414  /// @brief Gets whether or not Dialog Sound instances are muted.
415  /// @return Returns true if Dialog sounds are muted, false otherwise.
416  virtual bool IsDialogMuted() const;
417 
418  /// @brief Sets the volume for all stored Effect Sound instances.
419  /// @param Effect The volume to apply to all Effect sounds.
420  virtual void SetEffectVolume(const Real& Effect);
421  /// @brief Gets the currently set Effect volume.
422  /// @return Returns a Real representing the current Effect volume.
423  virtual Real GetEffectVolume() const;
424  /// @brief Sets whether or not to mute all Effect Sound instances.
425  /// @param Enable True to mute Effect sounds, false to unmute them.
426  virtual void MuteEffect(bool Enable);
427  /// @brief Gets whether or not Effect Sound instances are muted.
428  /// @return Returns true if Effect sounds are muted, false otherwise.
429  virtual bool IsEffectMuted() const;
430 
431  /// @brief Sets the volume for all stored Music Sound instances.
432  /// @param Music The volume to apply to all Music sounds.
433  virtual void SetMusicVolume(const Real& Music);
434  /// @brief Gets the currently set Music volume.
435  /// @return Returns a Real representing the current Music volume.
436  virtual Real GetMusicVolume() const;
437  /// @brief Sets whether or not to mute all Music Sound instances.
438  /// @param Enable True to mute Music sounds, false to unmute them.
439  virtual void MuteMusic(bool Enable);
440  /// @brief Gets whether or not Music Sound instances are muted.
441  /// @return Returns true if Music sounds are muted, false otherwise.
442  virtual bool IsMusicMuted() const;
443 
444  ///////////////////////////////////////////////////////////////////////////////
445  // Recorder Management
446 
447  /// @brief Creates a new @ref iRecorder.
448  /// @return Returns a pointer to the created @ref iRecorder.
449  virtual iRecorder* CreateRecorder() = 0;
450  /// @brief Gets a @ref iRecorder by index.
451  /// @param Index The index of the @ref iRecorder to retrieve.
452  /// @return Returns a pointer to the @ref iRecorder at the specified index.
453  virtual iRecorder* GetRecorder(const UInt32 Index) const = 0;
454  /// @brief Gets the number of @ref iRecorder instances being stored by this manager.
455  /// @return Returns a UInt32 representing the number of @ref iRecorder instances within this manager.
456  virtual UInt32 GetNumRecorders() const = 0;
457  /// @brief Destroys a @ref iRecorder instance by pointer.
458  /// @param ToBeDestroyed A pointer to the @ref iRecorder instance to be destroyed.
459  virtual void DestroyRecorder(iRecorder* ToBeDestroyed) = 0;
460  /// @brief Destroys all @ref iRecorder instances being stored by this manager.
461  virtual void DestroyAllRecorders() = 0;
462 
463  ///////////////////////////////////////////////////////////////////////////////
464  // Playback Device Management
465 
466  /// @brief Gets the name of the playback device currently in use.
467  /// @return Returns a String containing the name of the device this manager was initiailzed with, or empty if one hasn't been set.
468  virtual String GetCurrentPlaybackDeviceName() const = 0;
469 
470  /// @brief Gets the name of an available playback device by index.
471  /// @details This function will retrieve the name of a device by it's index on the sound managers device list.
472  /// @param Index The position on the device list you wish to access the name of.
473  /// @return Returns the name of the device.
474  virtual String GetAvailablePlaybackDeviceName(const Whole& Index) const = 0;
475  /// @brief Gets the number of available playback devices.
476  /// @details This function will return the total number of available devices, including the default.
477  /// @return Returns the number of available devices.
478  virtual Whole GetAvailablePlaybackDeviceCount() const = 0;
479  /// @brief Gets the name of the default playback device.
480  /// @details This function will return the name of the system default device.
481  /// @return Returns the name of the default device.
482  virtual String GetDefaultPlaybackDeviceName() const = 0;
483  /// @brief Checks to see if the named playback device is available.
484  /// @param DeviceName The name of the device to check for.
485  /// @return Returns true if the device is available on this system, false otherwise.
486  virtual bool PlaybackDeviceNameValid(const String& DeviceName) const = 0;
487 
488  /// @brief Initializes the playback device.
489  /// @details This function will initialize the device using the parameters provided.
490  /// You need to call this function if you passed false into the sound manager constructor before
491  /// you can use the manager.
492  /// @param DeviceName The name of the device you wish to have this manager interface with/use.
493  /// @param OutputFrequency Frequency of the output audio, -1 for the devices default.
494  /// @return Returns true if the device was initialized successfully. False on a failure.
495  virtual bool InitializePlaybackDevice(const String& DeviceName, const Integer OutputFrequency = 44100) = 0;
496  /// @brief Shuts down the current playback device and unloads all sounds.
497  /// @warning This will destroy all sounds and sound proxies in the system.
498  virtual void ShutdownPlaybackDevice() = 0;
499 
500  ///////////////////////////////////////////////////////////////////////////////
501  // Recording Device Management
502 
503  /// @brief Gets the name of an available recording device by index.
504  /// @param Index The index of the device to retrieve the name for.
505  /// @return Returns a String containing the available device name at the specified index.
506  virtual String GetAvailableRecordingDeviceName(const UInt32 Index) = 0;
507  /// @brief Gets the number of currently available recording devices.
508  /// @return Returns a UInt32 containing the number of recording devices on this system.
509  virtual UInt32 GetAvailableRecordingDeviceCount() = 0;
510  /// @brief Gets the name of the default recording device.
511  /// @return Returns a String containing the name of the default recording device on this system.
512  virtual String GetDefaultRecordingDeviceName() = 0;
513 
514  ///////////////////////////////////////////////////////////////////////////////
515  // Decoder Management
516 
517  /// @brief Adds a @ref iDecoderFactory to this manager allowing the playback of new types of sound formats.
518  /// @note If an @ref iDecoderFactory is already registered to the same @ref Audio::Encoding, it will be replaced. It will not be deleted. Use with care.
519  /// @param ToBeAdded A pointer to the @ref iDecoderFactory to be added.
520  void AddDecoderFactory(iDecoderFactory* ToBeAdded);
521  /// @brief Checks if a @ref iDecoderFactory is already registered with this manager.
522  /// @param Format The @ref Audio::Encoding supported by the @ref iDecoderFactory to look for.
523  /// @return Returns true if a @ref iDecoderFactory supporting that @ref Audio::Encoding exists, false otherwise.
524  bool DecoderFactoryExists(const Audio::Encoding Format);
525  /// @brief Gets an @ref iDecoderFactory by it's supported @ref Audio::Encoding.
526  /// @param Format The @ref Audio::Encoding supported by the @ref iDecoderFactory to retrieve.
527  /// @return Returns a pointer to the @ref iDecoderFactory registered to the provided @ref Audio::Encoding, or NULL if none are registered.
528  iDecoderFactory* GetDecoderFactory(const Audio::Encoding Format);
529  /// @brief Removes (but does not destroy) an @ref iDecoderFactory.
530  /// @param ToBeRemoved A pointer to the @ref iDecoderFactory to be removed.
531  void RemoveDecoderFactory(iDecoderFactory* ToBeRemoved);
532  /// @brief Removes (but does not destroy) an @ref iDecoderFactory.
533  /// @param Format The @ref Audio::Encoding supported by the @ref iDecoderFactory to remove.
534  void RemoveDecoderFactory(const Audio::Encoding Format);
535  /// @brief Removes (but does not destroy) all registered @ref iDecoderFactory instances.
536  void RemoveAllDecoderFactories();
537  /// @brief Destroy a registered @ref iDecoderFactory.
538  /// @param ToBeDestroyed A pointer to the @ref iDecoderFactory to be destroyed.
539  void DestroyDecoderFactory(iDecoderFactory* ToBeDestroyed);
540  /// @brief Destroy a registered @ref iDecoderFactory.
541  /// @param Format The @ref Audio::Encoding supported by the @ref iDecoderFactory to be destroyed.
542  void DestroyDecoderFactory(const Encoding Format);
543  /// @brief Destroys all registered @ref iDecoderFactory instances.
544  void DestroyAllDecoderFactories();
545 
546  ///////////////////////////////////////////////////////////////////////////////
547  // Utility
548 
549  /// @copydoc ManagerBase::Initialize()
550  virtual void Initialize() = 0;
551  /// @copydoc ManagerBase::Deinitialize()
552  virtual void Deinitialize() = 0;
553 
554  /// @brief Gets the handler responsible for audio effects.
555  /// @return Returns a pointer to the @ref iEffectsHandler for this audio subsystem.
556  virtual iEffectsHandler* GetEffectsHandler() const = 0;
557  /// @brief Gets the music player for this audio subsystem.
558  /// @return Returns a pointer to the Music player belonging to this system, or NULL if this manager does not support one.
559  virtual MusicPlayer* GetMusicPlayer() const = 0;
560 
561  /// @brief Gets the work unit responsible for updating the buffers of sounds.
562  /// @return Returns a pointer to the BufferUpdate2DWorkUnit used by this manager.
563  virtual iBufferUpdate2DWorkUnit* GetBufferUpdate2DWork() = 0;
564  /// @brief Gets the work unit responsible for cleaning all effects and filters.
565  /// @return Returns a pointer to the BufferUpdateWorkUnit used by this manager.
566  virtual iEffectFilterCleanWorkUnit* GetEffectFilterCleanWork() = 0;
567 
568  ///////////////////////////////////////////////////////////////////////////////
569  // Type Identifier Methods
570 
571  /// @copydoc ManagerBase::GetInterfaceType()
572  virtual ManagerType GetInterfaceType() const;
573 
574  ///////////////////////////////////////////////////////////////////////////////
575  // Internal Methods
576 
577  /// @internal
578  /// @brief Notifies this AudioManager of the creation of a new SoundScapeManager.
579  /// @param Manager A pointer to the manager being registered.
580  virtual void _RegisterSoundScapeManager(Audio::SoundScapeManager* Manager) = 0;
581  /// @internal
582  /// @brief Notifies this AudioManager of the destruction of a SoundScapeManager.
583  /// @param Manager A pointer to the manager being unregistered.
584  virtual void _UnregisterSoundScapeManager(Audio::SoundScapeManager* Manager) = 0;
585  };//AudioManager
586  }//Audio
587 }//Mezzanine
588 
589 #endif