GL Studio C++ Runtime API
sound.h
Go to the documentation of this file.
1/// \file sound.h
2/// \brief The SoundSystem class for playback of audio files.
3///
4/// \par Copyright Information
5///
6/// Copyright (c) 2017 by The DiSTI Corporation.<br>
7/// 12249 Science Drive; Suite 300<br>
8/// Orlando, Florida 32826<br>
9/// USA<br>
10/// <br>
11/// All rights reserved.<br>
12///
13/// This Software contains proprietary trade secrets of DiSTI and may not be
14/// reproduced, in whole or part, in any form, or by any means of electronic,
15/// mechanical, or otherwise, without the written permission of DiSTI. Said
16/// permission may be derived through the purchase of applicable DiSTI product
17/// licenses which detail the distribution rights of this content and any
18/// Derivative Works based on this or other copyrighted DiSTI Software.
19///
20/// NO WARRANTY. THE SOFTWARE IS PROVIDED "AS-IS," WITHOUT WARRANTY OF ANY KIND,
21/// AND ANY USE OF THIS SOFTWARE PRODUCT IS AT YOUR OWN RISK. TO THE MAXIMUM EXTENT
22/// PERMITTED BY APPLICABLE LAW, DISTI AND ITS SUPPLIERS DISCLAIM ALL WARRANTIES
23/// AND CONDITIONS, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
24/// IMPLIED WARRANTIES AND CONDITIONS OF MERCHANTABILITY AND/OR FITNESS FOR A
25/// PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT, WITH REGARD TO THE SOFTWARE.
26///
27/// LIMITATION OF LIABILITY. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW,
28/// IN NO EVENT SHALL DISTI OR ITS SUPPLIERS BE LIABLE FOR ANY SPECIAL, INCIDENTAL,
29/// INDIRECT, OR CONSEQUENTIAL DAMAGES WHATSOEVER (INCLUDING, WITHOUT LIMITATION,
30/// DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS
31/// INFORMATION, OR ANY OTHER PECUNIARY LOSS) ARISING OUT OF THE USE OF OR
32/// INABILITY TO USE THE SOFTWARE, EVEN IF DISTI HAS BEEN ADVISED OF THE POSSIBILITY
33/// OF SUCH DAMAGES. DISTI'S ENTIRE LIABILITY AND YOUR EXCLUSIVE REMEDY SHALL NOT
34/// EXCEED FIVE DOLLARS (US$5.00).
35///
36/// The aforementioned terms and restrictions are governed by the laws of the
37/// State of Florida and the United States of America.
38
39#ifndef INCLUDED_DISTI_SOUND_H
40#define INCLUDED_DISTI_SOUND_H
41
43#include "scoped_ptr.h"
44
45namespace disti
46{
47/// \details The SoundSystem class. Plays WAV files on Desktop Windows.
49{
50public:
51 /** Constructor
52 * \param maxSounds Maximum number of soundfiles in the sound system
53 * \throw std::bad_alloc if unable to allocate memory.
54 */
55 DISTI_EXPORT explicit SoundSystem( int maxSounds );
56
57 /** Destructor */
58 DISTI_EXPORT ~SoundSystem();
59
60 /// \return Whether the sound device was initialized sucessfully.
61 DISTI_EXPORT bool IsValid() const;
62
63 /** Plays the sound at the given index
64 * \param which The zero based index of the sound to play
65 */
66 DISTI_EXPORT void Play( int which );
67
68 /** Plays the sound at the given index, attenuated for distancec
69 * \param which The zero based index of the sound to play
70 * \param volumeOrDistance The volume of the sound, from 0.0 (min) to FLT_MAX (max) or the
71 * distance in meters of the sound, depending on the platform.
72 */
73 DISTI_EXPORT void Play( int which, float volumeOrDistance );
74
75 /** Loads the sound from a file into a slot in the sound system
76 * \param fn The name of the file to load from
77 * \param index The zero based index to load the file into
78 * \throw std::bad_alloc if unable to allocate memory
79 */
80 DISTI_EXPORT void LoadSound( const char* fn, int index );
81
82 /** Loads a number of sounds from files into the sound system
83 * The sounds are loaded sequentially starting at slot zero
84 * \param firstArg Filenames to load, followed by a NULL
85 * \throw std::bad_alloc if unable to allocate memory
86 */
87 DISTI_EXPORT void LoadSounds( const char* firstArg, ... );
88
89 /** Deletes the sound from the given index
90 * \param index Zero based index to clear
91 */
92 DISTI_EXPORT void ClearSound( int index );
93
94 /** Sets the master volume of the sound system, from 0.0 (min) to FLT_MAX (max)
95 * \param volume The master volume of the sound system, from 0.0 (min) to FLT_MAX (max)
96 */
97 DISTI_EXPORT void SetMasterVolume( float volume );
98
99 /** Gets the master volume of the sound system, from 0.0 (min) to FLT_MAX (max)
100 * \return The master volume of the sound system, from 0.0 (min) to FLT_MAX (max)
101 */
102 DISTI_EXPORT float GetMasterVolume() const;
103
104 /// \cond INTERNAL
105 // Base class for all platform-specific implementations of the sound system
106 class ISoundSystemImpl
107 {
108 public:
109 DISTI_EXPORT virtual bool IsValid() const = 0;
110 DISTI_EXPORT virtual void LoadSound( const char* fileName, int index ) = 0;
111 DISTI_EXPORT virtual void ClearSound( int index ) = 0;
112 DISTI_EXPORT virtual void SetMasterVolume( float volume ) = 0;
113 DISTI_EXPORT virtual float GetMasterVolume() const = 0;
114 DISTI_EXPORT virtual void Play( int index ) = 0;
115 DISTI_EXPORT virtual void Play( int index, float volume ) = 0;
116
117 DISTI_EXPORT virtual ~ISoundSystemImpl() {}
118
119 protected:
120 DISTI_EXPORT ISoundSystemImpl() {}
121
122 private:
123 // Disabled
124 ISoundSystemImpl( const ISoundSystemImpl& ) DISTI_SPECIAL_MEM_FUN_DELETE;
125 void operator=( const ISoundSystemImpl& ) DISTI_SPECIAL_MEM_FUN_DELETE;
126 };
127 /// \endcond
128
129private:
130 // Pimpl idiom for platform-specific overrides
131 // Note: The abstract base class + pimpl is an unusual construction, but it allows us to keep
132 // backwards compatibility with our existing code while swapping out the internals.
133 ScopedPtr<ISoundSystemImpl> _impl;
134
135 // The following are to be defined by the platform implementation.
136 // Only one should be present in any build of the GL Studio runtime.
137 static ISoundSystemImpl* CreateSoundSystemImpl( int maxSounds );
138 static const char* const s_errorMsg;
139
140 // Copying/moving is disabled
142 void operator=( const SoundSystem& ) DISTI_SPECIAL_MEM_FUN_DELETE;
143};
144} // namespace disti
145
146#endif
Definition: sound.h:49
SoundSystem(int maxSounds)
float GetMasterVolume() const
void LoadSounds(const char *firstArg,...)
void SetMasterVolume(float volume)
void Play(int which)
void ClearSound(int index)
bool IsValid() const
void LoadSound(const char *fn, int index)
Macros and helper code to determine what subset of C++11/14/17 is available.
#define DISTI_SPECIAL_MEM_FUN_DELETE
Macro to wrap function deletion, removed on compilers that don't support it.
Definition: gls_cpp_lang_support.h:245
Definition: bmpimage.h:46
A smart pointer with unique ownership – poor man's std::unique_ptr.