sfxVoice.h
Classes:
class
The voice interface provides for playback of sound buffers and positioning of 3D sounds.
Namespaces:
namespace
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 _SFXVOICE_H_ 25#define _SFXVOICE_H_ 26 27#ifndef _REFBASE_H_ 28#include "core/util/refBase.h" 29#endif 30 31#ifndef _TSTREAM_H_ 32#include "core/stream/tStream.h" 33#endif 34 35#ifndef _MPOINT3_H_ 36#include "math/mPoint3.h" 37#endif 38 39#ifndef _MMATRIX_H_ 40#include "math/mMatrix.h" 41#endif 42 43#ifndef _SFXBUFFER_H_ 44#include "sfx/sfxBuffer.h" 45#endif 46 47 48namespace SFXInternal { 49 class SFXVoiceTimeSource; 50 class SFXAynscQueue; 51} 52 53 54/// The voice interface provides for playback of sound buffers and positioning 55/// of 3D sounds. 56/// 57/// This abstract class is derived from in the different device layers to implement 58/// device-specific playback control. 59/// 60/// The primary responsibility of this class is to mediate between the user requests 61/// (play(), stop(), pause(), setPosition()), the buffer (which may change state 62/// asynchronously), and the underlying device playback control (_play(), _stop(), 63/// _pause(), _seek()). 64class SFXVoice : public StrongRefBase, 65 public IPositionable< U32 > 66{ 67 public: 68 69 typedef void Parent; 70 71 friend class SFXDevice; // _attachToBuffer 72 friend class SFXInternal::SFXVoiceTimeSource; // _tell 73 friend class SFXInternal::SFXAsyncQueue; // mOffset 74 75 protected: 76 77 /// Current playback status. 78 /// @note This is maintained on both the sound update thread as well 79 /// as the main thread. 80 mutable volatile SFXStatus mStatus; 81 82 /// Sound data played back by the voice. 83 WeakRefPtr< SFXBuffer> mBuffer; 84 85 /// For streaming voices, this keeps track of play start offset 86 /// after seeking. Expressed in number of samples. 87 U32 mOffset; 88 89 explicit SFXVoice( SFXBuffer* buffer ); 90 91 /// @name Device Control Methods 92 /// @{ 93 94 /// Return the current playback status (playing, paused, or stopped). Default 95 /// status is stopped. 96 virtual SFXStatus _status() const = 0; 97 98 /// Stop playback on the device. 99 /// @note Called from both the SFX update thread and the main thread. 100 virtual void _stop() = 0; 101 102 /// Start playback on the device. 103 /// @note Called from both the SFX update thread and the main thread. 104 virtual void _play() = 0; 105 106 /// Pause playback on the device. 107 /// @note Called from both the SFX update thread and the main thread. 108 virtual void _pause() = 0; 109 110 /// Set the playback cursor on the device. 111 /// @note Only used for non-streaming voices. 112 virtual void _seek( U32 sample ) = 0; 113 114 /// Get the playback cursor on the device. 115 /// 116 /// When the voice is playing or paused, this method must return a valid sample position. 117 /// When the voice is stopped, the result of this method is undefined. 118 /// 119 /// For streaming voices that are looping, the sample position must be a total count of the 120 /// number of samples played so far which thus includes the count of all cycles before the 121 /// current one. For non-looping voices, this behavior is optional. 122 /// 123 /// @note This is called for both streaming and non-streaming voices. 124 virtual U32 _tell() const = 0; 125 126 /// @} 127 128 /// Hooked up to SFXBuffer::mOnStatusChange of #mBuffer. 129 /// @note Called on the SFX update thread. 130 virtual void _onBufferStatusChange( SFXBuffer* buffer, SFXBuffer::Status newStatus ); 131 132 /// 133 void _attachToBuffer(); 134 135 /// @name Streaming 136 /// The following methods are for streaming voices only. 137 /// @{ 138 139 /// Reset streaming of the voice by cloning the current streaming source and 140 /// letting the resulting stream start from @a sampleStartPos. 141 void _resetStream( U32 sampleStartPos, bool triggerUpdate = true ); 142 143 /// @} 144 145 public: 146 147 static Signal< void( SFXVoice* ) > smVoiceCreatedSignal; 148 static Signal< void( SFXVoice* ) > smVoiceDestroyedSignal; 149 150 /// The destructor. 151 virtual ~SFXVoice(); 152 153 /// 154 const SFXFormat& getFormat() const { return mBuffer->getFormat(); } 155 156 /// Return the current playback position (in number of samples). 157 /// 158 /// @note For looping sounds, this will return the position in the 159 /// current cycle and not the total number of samples played so far. 160 virtual U32 getPosition() const; 161 162 /// Sets the playback position to the given sample count. 163 /// 164 /// @param sample Offset in number of samples. This is allowed to use an offset 165 /// accumulated from multiple cycles. Each cycle will wrap around back to the 166 /// beginning of the buffer. 167 virtual void setPosition( U32 sample ); 168 169 /// @return the current playback status. 170 /// @note For streaming voices, the reaction to for the voice to update its status 171 /// to SFXStatusStopped after the voice has stopped playing depends on the synchronization 172 /// of the underlying device. If, for example, the underlying device uses periodic updates 173 /// and doesn't have notifications, then a delay up to the total length of the period time 174 /// may occur before the status changes. Note that in-between the actual playback stopping 175 /// and the voice updating its status, the result of getPosition() is undefined. 176 virtual SFXStatus getStatus() const; 177 178 /// Starts playback from the current position. 179 virtual void play( bool looping ); 180 181 /// Stops playback and moves the position to the start. 182 virtual void stop(); 183 184 /// Pauses playback. 185 virtual void pause(); 186 187 /// Sets the position and orientation for a 3d voice. 188 virtual void setTransform( const MatrixF &transform ) = 0; 189 190 /// Sets the velocity for a 3d voice. 191 virtual void setVelocity( const VectorF &velocity ) = 0; 192 193 /// Sets the minimum and maximum distances for 3d falloff. 194 virtual void setMinMaxDistance( F32 min, F32 max ) = 0; 195 196 /// Set the distance attenuation rolloff factor. Support by device optional. 197 virtual void setRolloffFactor( F32 factor ) {} 198 199 /// Sets the volume. 200 virtual void setVolume( F32 volume ) = 0; 201 202 /// Sets the pitch scale. 203 virtual void setPitch( F32 pitch ) = 0; 204 205 /// Set sound cone of a 3D sound. 206 /// 207 /// @param innerAngle Inner cone angle in degrees. 208 /// @param outerAngle Outer cone angle in degrees. 209 /// @param outerVolume Outer volume factor. 210 virtual void setCone( F32 innerAngle, 211 F32 outerAngle, 212 F32 outerVolume ) = 0; 213 214 /// Set the reverb properties for playback of this sound. 215 /// @note Has no effect on devices that do not support reverb. 216 virtual void setReverb( const SFXSoundReverbProperties& reverb ) {} 217 218 /// Set the priority of this voice. Default 1.0. 219 /// @note Has no effect on devices that do not support voice management. 220 virtual void setPriority( F32 priority ) {} 221 222 /// Returns true if the voice is virtualized on the device. 223 /// @note Always false on devices that do not support voice management. 224 virtual bool isVirtual() const { return false; } 225}; 226 227#endif // _SFXVOICE_H_ 228