sfxDevice.h
Classes:
class
Abstract base class for back-end sound API implementations.
Detailed Description
1 2//----------------------------------------------------------------------------- 3// Copyright (c) 2012 GarageGames, LLC 4// 5// Permission is hereby granted, free of charge, to any person obtaining a copy 6// of this software and associated documentation files (the "Software"), to 7// deal in the Software without restriction, including without limitation the 8// rights to use, copy, modify, merge, publish, distribute, sublicense, and/or 9// sell copies of the Software, and to permit persons to whom the Software is 10// furnished to do so, subject to the following conditions: 11// 12// The above copyright notice and this permission notice shall be included in 13// all copies or substantial portions of the Software. 14// 15// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 20// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS 21// IN THE SOFTWARE. 22//----------------------------------------------------------------------------- 23 24#ifndef _SFXDEVICE_H_ 25#define _SFXDEVICE_H_ 26 27#ifndef _PLATFORM_H_ 28 #include "platform/platform.h" 29#endif 30#ifndef _TVECTOR_H_ 31 #include "core/util/tVector.h" 32#endif 33#ifndef _SFXCOMMON_H_ 34 #include "sfx/sfxCommon.h" 35#endif 36#ifndef _THREADSAFEREF_H_ 37 #include "platform/threads/threadSafeRefCount.h" 38#endif 39 40 41class SFXProvider; 42class SFXListener; 43class SFXBuffer; 44class SFXVoice; 45class SFXProfile; 46class SFXDevice; 47class SFXStream; 48class SFXDescription; 49 50 51 52/// Abstract base class for back-end sound API implementations. 53class SFXDevice 54{ 55 public: 56 57 typedef void Parent; 58 59 /// Device capability flags. 60 enum ECaps 61 { 62 CAPS_Reverb = BIT( 0 ), ///< Device supports reverb environments. 63 CAPS_VoiceManagement = BIT( 1 ), ///< Device manages voices on its own; deactivates virtualization code in SFX system. 64 CAPS_Occlusion = BIT( 2 ), ///< Device has its own sound occlusion handling (SFXOcclusionManager). 65 CAPS_DSPEffects = BIT( 3 ), ///< Device implements DSP effects (SFXDSPManager). 66 CAPS_MultiListener = BIT( 4 ), ///< Device supports multiple listeners. 67 CAPS_FMODDesigner = BIT( 5 ), ///< FMOD Designer support. 68 }; 69 70 protected: 71 72 typedef Vector< SFXBuffer*> BufferVector; 73 typedef Vector< SFXVoice*> VoiceVector; 74 75 typedef BufferVector::iterator BufferIterator; 76 typedef VoiceVector::iterator VoiceIterator; 77 78 SFXDevice( const String& name, SFXProvider* provider, bool useHardware, S32 maxBuffers ); 79 80 /// The name of this device. 81 String mName; 82 83 /// The provider which created this device. 84 SFXProvider* mProvider; 85 86 /// Should the device try to use hardware processing. 87 bool mUseHardware; 88 89 /// The maximum playback buffers this device will use. 90 S32 mMaxBuffers; 91 92 /// Current set of sound buffers. 93 BufferVector mBuffers; 94 95 /// Current set of voices. 96 VoiceVector mVoices; 97 98 /// Device capabilities. 99 U32 mCaps; 100 101 /// Current number of buffers. Reflected in $SFX::Device::numBuffers. 102 U32 mStatNumBuffers; 103 104 /// Current number of voices. Reflected in $SFX::Device::numVoices. 105 U32 mStatNumVoices; 106 107 /// Current total memory size of sound buffers. Reflected in $SFX::Device::numBufferBytes. 108 U32 mStatNumBufferBytes; 109 110 /// Register a buffer with the device. 111 /// This also triggers the buffer's stream packet request chain. 112 void _addBuffer( SFXBuffer* buffer ); 113 114 /// Unregister the given buffer. 115 void _removeBuffer( SFXBuffer* buffer ); 116 117 /// Register a voice with the device. 118 void _addVoice( SFXVoice* voice ); 119 120 /// Unregister the given voice. 121 virtual void _removeVoice( SFXVoice* buffer ); 122 123 /// Release all resources tied to the device. Can be called repeatedly 124 /// without harm. It is meant for device destructors that will severe 125 /// the connection to the sound API and thus need all resources freed 126 /// before the base destructor is called. 127 void _releaseAllResources(); 128 129public: 130 131 virtual ~SFXDevice(); 132 133 /// Returns the provider which created this device. 134 SFXProvider* getProvider() const { return mProvider; } 135 136 /// Is the device set to use hardware processing. 137 bool getUseHardware() const { return mUseHardware; } 138 139 /// The maximum number of playback buffers this device will use. 140 S32 getMaxBuffers() const { return mMaxBuffers; } 141 142 /// Returns the name of this device. 143 const String& getName() const { return mName; } 144 145 /// Return the device capability flags. 146 U32 getCaps() const { return mCaps; } 147 148 /// Tries to create a new sound buffer. If creation fails 149 /// freeing another buffer will usually allow a new one to 150 /// be created. 151 /// 152 /// @param stream The sound data stream. 153 /// @param description The playback configuration. 154 /// 155 /// @return Returns a new buffer or NULL if one cannot be created. 156 /// 157 virtual SFXBuffer* createBuffer( const ThreadSafeRef< SFXStream>& stream, SFXDescription* description ) = 0; 158 159 /// Create a sound buffer directly for a file. This is for 160 /// devices that implemented their own custom file loading. 161 /// 162 /// @note Only implemented on specific SFXDevices. 163 /// @return Return a new buffer or NULL. 164 virtual SFXBuffer* createBuffer( const String& fileName, SFXDescription* description ) { return NULL; } 165 166 /// Tries to create a new voice. 167 /// 168 /// @param is3d True if the voice should have 3D sound enabled. 169 /// @param buffer The sound data to play by the voice. 170 /// 171 /// @return Returns a new voice or NULL if one cannot be created. 172 virtual SFXVoice* createVoice( bool is3D, SFXBuffer* buffer ) = 0; 173 174 /// Set the rolloff curve to be used by distance attenuation of 3D sounds. 175 virtual void setDistanceModel( SFXDistanceModel model ) {} 176 177 /// Set the scale factor to use for doppler effects on 3D sounds. 178 virtual void setDopplerFactor( F32 factor ) {} 179 180 /// Set the rolloff scale factor for distance attenuation of 3D sounds. 181 virtual void setRolloffFactor( F32 factor ) {} 182 183 /// send empty function to all sfxdevices 184 virtual void openSlots() {} 185 186 /// Set the global reverb environment. 187 virtual void setReverb( const SFXReverbProperties& reverb ) {} 188 189 /// Reset the global reverb environment to its default. 190 virtual void resetReverb() {} 191 192 /// Set the number of concurrent listeners on the device. 193 /// 194 /// @note On devices that do not support multiple listeners, any value 195 /// other than 1 will be ignored. 196 virtual void setNumListeners( U32 num ) {} 197 198 /// Set the properties of the given listener. 199 /// 200 /// @note On devices that do not support multiple listeners, only setting 201 /// the properties on index=0 will have a effect. 202 virtual void setListener( U32 index, const SFXListenerProperties& listener ) {} 203 204 /// Return the current total number of sound buffers. 205 U32 getBufferCount() const { return mBuffers.size(); } 206 207 /// Return the current total number of voices. 208 U32 getVoiceCount() const { return mVoices.size(); } 209 210 /// Called from SFXSystem to do any updates the device may need to make. 211 virtual void update(); 212}; 213 214 215#endif // _SFXDEVICE_H_ 216