 | PixelLight 0.9.10-R1 Copyright (C) 2002-2011 by The PixelLight Team Last modified Fri Dec 23 2011 15:51:03 |  | The content of this PixelLight
document is published under the Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported |
|
PixelLightAPI
.
|
00001 /*********************************************************\ 00002 * File: SoundManager.h * 00003 * 00004 * Copyright (C) 2002-2011 The PixelLight Team (http://www.pixellight.org/) 00005 * 00006 * This file is part of PixelLight. 00007 * 00008 * PixelLight is free software: you can redistribute it and/or modify 00009 * it under the terms of the GNU Lesser General Public License as published by 00010 * the Free Software Foundation, either version 3 of the License, or 00011 * (at your option) any later version. 00012 * 00013 * PixelLight is distributed in the hope that it will be useful, 00014 * but WITHOUT ANY WARRANTY; without even the implied warranty of 00015 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 00016 * GNU Lesser General Public License for more details. 00017 * 00018 * You should have received a copy of the GNU Lesser General Public License 00019 * along with PixelLight. If not, see <http://www.gnu.org/licenses/>. 00020 \*********************************************************/ 00021 00022 00023 #ifndef __PLSOUND_SOUNDMANAGER_H__ 00024 #define __PLSOUND_SOUNDMANAGER_H__ 00025 #pragma once 00026 00027 00028 //[-------------------------------------------------------] 00029 //[ Includes ] 00030 //[-------------------------------------------------------] 00031 #include <PLCore/Base/Object.h> 00032 #include <PLCore/Container/ResourceManager.h> 00033 #include <PLMath/Vector3.h> 00034 #include "PLSound/Buffer.h" 00035 #include "PLSound/BufferHandler.h" 00036 00037 00038 //[-------------------------------------------------------] 00039 //[ Namespace ] 00040 //[-------------------------------------------------------] 00041 namespace PLSound { 00042 00043 00044 //[-------------------------------------------------------] 00045 //[ Forward declarations ] 00046 //[-------------------------------------------------------] 00047 class Resource; 00048 class Source; 00049 00050 00051 //[-------------------------------------------------------] 00052 //[ Classes ] 00053 //[-------------------------------------------------------] 00054 /** 00055 * @brief 00056 * Abstract sound manager main class 00057 * 00058 * @note 00059 * - Does not unload unused resources automatically by default 00060 */ 00061 class SoundManager : public PLCore::Object, public PLCore::ResourceManager<Buffer> { 00062 00063 00064 //[-------------------------------------------------------] 00065 //[ Public definitions ] 00066 //[-------------------------------------------------------] 00067 public: 00068 /** 00069 * @brief 00070 * Listener attributes 00071 */ 00072 enum EListener { 00073 ListenerPosition = 0, /**< Position (float3, x/y/z) */ 00074 ListenerVelocity = 1, /**< Velocity in meters per second (float3, x/y/z) */ 00075 ListenerForward = 2, /**< Forward unit length orientation vector (float3, x/y/z) */ 00076 ListenerUpward = 3, /**< Upwards facing unit length orientation vector (float3, x/y/z) */ 00077 ListenerNumber = 4 /**< Number of listener properties */ 00078 }; 00079 00080 00081 //[-------------------------------------------------------] 00082 //[ RTTI interface ] 00083 //[-------------------------------------------------------] 00084 pl_class(PLSOUND_RTTI_EXPORT, SoundManager, "PLSound", PLCore::Object, "Abstract sound manager main class") 00085 pl_class_end 00086 00087 00088 //[-------------------------------------------------------] 00089 //[ Public structures ] 00090 //[-------------------------------------------------------] 00091 public: 00092 /** 00093 * @brief 00094 * Sound statistics 00095 */ 00096 struct Statistics { 00097 PLCore::uint32 nNumOfBuffers; /**< Number of sound buffers */ 00098 PLCore::uint32 nNumOfSources; /**< Number of sound sources */ 00099 PLCore::uint32 nNumOfActiveSources; /**< Number of currently active sound sources */ 00100 }; 00101 00102 /** 00103 * @brief 00104 * Sound format 00105 */ 00106 class Format { 00107 public: 00108 PLCore::String sFormat; /**< Sound format */ 00109 PLCore::String sDescription; /**< Sound format description */ 00110 bool operator ==(const Format &cOther) const 00111 { 00112 return sFormat == cOther.sFormat && sDescription == cOther.sDescription; 00113 } 00114 }; 00115 00116 00117 //[-------------------------------------------------------] 00118 //[ Public functions ] 00119 //[-------------------------------------------------------] 00120 public: 00121 /** 00122 * @brief 00123 * Destructor 00124 */ 00125 PLSOUND_API virtual ~SoundManager(); 00126 00127 /** 00128 * @brief 00129 * Returns the sound statistics 00130 * 00131 * @return 00132 * The sound statistics 00133 */ 00134 PLSOUND_API const Statistics &GetStatistics() const; 00135 00136 //[-------------------------------------------------------] 00137 //[ Resources ] 00138 //[-------------------------------------------------------] 00139 /** 00140 * @brief 00141 * Returns the number of resources 00142 * 00143 * @return 00144 * Number of resources 00145 */ 00146 PLSOUND_API PLCore::uint32 GetNumOfResources() const; 00147 00148 /** 00149 * @brief 00150 * Returns a sound resource 00151 * 00152 * @param[in] nIndex 00153 * Index of the resource to return 00154 * 00155 * @return 00156 * The resource at the given index, a null pointer on error 00157 */ 00158 PLSOUND_API Resource *GetResource(PLCore::uint32 nIndex = 0) const; 00159 00160 /** 00161 * @brief 00162 * Adds a sound resource to the sound manager 00163 * 00164 * @param[in] cResource 00165 * Sound resource to add 00166 * 00167 * @return 00168 * 'true' if all went fine and the sound resource was added to the sound manager, 00169 * else 'false' 00170 * 00171 * @note 00172 * - The sound resource itself is only added to the sound manager's list of resources! 00173 */ 00174 PLSOUND_API bool AddResource(Resource &cResource); 00175 00176 /** 00177 * @brief 00178 * Removes a sound resource from the sound manager 00179 * 00180 * @param[in] cResource 00181 * Sound resource to remove 00182 * 00183 * @return 00184 * 'true' if all went fine and the sound resource was removed from the 00185 * sound manager, else 'false' (maybe the resource isn't in the sound manager) 00186 * 00187 * @note 00188 * - The sound resource itself isn't destroyed, it is just removed 00189 * from the sound manager's list of resources! 00190 */ 00191 PLSOUND_API bool RemoveResource(Resource &cResource); 00192 00193 00194 //[-------------------------------------------------------] 00195 //[ Public virtual SoundManager functions ] 00196 //[-------------------------------------------------------] 00197 public: 00198 /** 00199 * @brief 00200 * Returns the sound manager description 00201 * 00202 * @return 00203 * Sound manager description 00204 */ 00205 virtual PLCore::String GetDescription() const = 0; 00206 00207 /** 00208 * @brief 00209 * Gets a list of all known sound formats 00210 * 00211 * @param[out] lstList 00212 * List to receive the known sound formats (see Format) 00213 * 00214 * @return 00215 * 'true' if all went fine, else 'false' 00216 * 00217 * @note 00218 * - The given list is NOT cleared before the formats are added 00219 */ 00220 virtual bool GetFormatList(PLCore::List<Format> &lstList) const = 0; 00221 00222 /** 00223 * @brief 00224 * Gets the master volume 00225 * 00226 * @return 00227 * Volume (value from 0.0-1.0 -> 0.0 = silence, 1.0 = full volume) 00228 */ 00229 virtual float GetVolume() const = 0; 00230 00231 /** 00232 * @brief 00233 * Sets the master volume 00234 * 00235 * @param[in] fVolume 00236 * Volume (value from 0.0-1.0 -> 0.0 = silence, 1.0 = full volume) 00237 */ 00238 virtual void SetVolume(float fVolume = 1.0f) = 0; 00239 00240 /** 00241 * @brief 00242 * Returns the master pitch multiplier 00243 * 00244 * @return 00245 * Pitch multiplier 00246 * 00247 * @remarks 00248 * pitch < 1.0 = slower\n 00249 * pitch = 1.0 = normal\n 00250 * pitch > 1.0 = faster 00251 */ 00252 virtual float GetPitch() const = 0; 00253 00254 /** 00255 * @brief 00256 * Sets the master pitch multiplier 00257 * 00258 * @param[in] fPitch 00259 * Pitch multiplier 00260 * 00261 * @see 00262 * - GetPitch() 00263 */ 00264 virtual void SetPitch(float fPitch = 1.0f) = 0; 00265 00266 /** 00267 * @brief 00268 * Gets the doppler factor 00269 * 00270 * @return 00271 * Doppler factor 00272 * 00273 * @remarks 00274 * If velocities are applied to the listener object or to any source object, then 00275 * doppler shift will be applied to the audio. The following formula is used to 00276 * calculate doppler shift:\n 00277 * f’ = f*(DV – DF*vl)/(DV + DF*vs)\n 00278 * DV = doppler velocity\n 00279 * DF = doppler factor\n 00280 * vl = listener velocity (scalar value along source-to-listener vector)\n 00281 * vs = source velocity (scalar value along source-to-listener vector)\n 00282 * f = frequency of sample\n 00283 * f’ = Doppler shifted frequency\n 00284 * The doppler velocity (340) represents the speed of sound.\n 00285 * The doppler factor is used to exaggerate or de-emphasize the doppler shift. 00286 */ 00287 virtual float GetDopplerFactor() const = 0; 00288 00289 /** 00290 * @brief 00291 * Sets the doppler factor 00292 * 00293 * @param[in] fFactor 00294 * Doppler factor 00295 * 00296 * @see 00297 * - GetDopplerFactor() 00298 */ 00299 virtual void SetDopplerFactor(float fFactor = 1.0f) = 0; 00300 00301 //[-------------------------------------------------------] 00302 //[ Create sound buffer/source ] 00303 //[-------------------------------------------------------] 00304 /** 00305 * @brief 00306 * Creates a sound buffer 00307 * 00308 * @param[in] sFilename 00309 * Sound filename, if empty, only create the sound buffer without loading it (full path, supported file formats are API dependent) 00310 * @param[in] bStream 00311 * Stream the file? (recommended for large files!) 00312 * 00313 * @return 00314 * The created sound buffer, a null pointer on error 00315 * 00316 * @note 00317 * - If there's already a sound buffer with this name, this sound buffer is returned 00318 * - Not each sound buffer can be streamed, use SoundBuffer::IsStreamed() to 00319 * check whether streaming is used. 00320 */ 00321 virtual Buffer *CreateSoundBuffer(const PLCore::String &sFilename = "", bool bStream = false) = 0; 00322 00323 /** 00324 * @brief 00325 * Creates a sound source 00326 * 00327 * @param[in] pSoundBuffer 00328 * Sound buffer to load, a null pointer if load no sound buffer by default 00329 * 00330 * @return 00331 * The created sound source, a null pointer on error 00332 * 00333 * @remarks 00334 * The simplest creation of a sound source ready for playback would be\n 00335 * SoundSource *pSS = pSM->CreateSoundSource(CreateSoundBuffer("MySound.wav"));\n 00336 * Whereby 'MySound.wav' isn't loaded twice if there's already such a sound buffer. 00337 */ 00338 virtual Source *CreateSoundSource(Buffer *pSoundBuffer = nullptr) = 0; 00339 00340 //[-------------------------------------------------------] 00341 //[ Listener ] 00342 //[-------------------------------------------------------] 00343 /** 00344 * @brief 00345 * Gets a listener attribute value 00346 * 00347 * @param[in] nAttribute 00348 * Listener attribute to return 00349 * 00350 * @return 00351 * Requested listener attribute value 00352 */ 00353 virtual PLMath::Vector3 GetListenerAttribute(EListener nAttribute) const = 0; 00354 00355 /** 00356 * @brief 00357 * Sets a listener attribute value 00358 * 00359 * @param[in] nAttribute 00360 * Listener attribute to set 00361 * @param[in] vV 00362 * New listener attribute value 00363 * 00364 * @return 00365 * 'true' if all went fine, else 'false' 00366 */ 00367 virtual bool SetListenerAttribute(EListener nAttribute, const PLMath::Vector3 &vV) = 0; 00368 00369 00370 //[-------------------------------------------------------] 00371 //[ Protected functions ] 00372 //[-------------------------------------------------------] 00373 protected: 00374 /** 00375 * @brief 00376 * Constructor 00377 */ 00378 PLSOUND_API SoundManager(); 00379 00380 00381 //[-------------------------------------------------------] 00382 //[ Protected data ] 00383 //[-------------------------------------------------------] 00384 protected: 00385 Statistics m_sStatistics; /**< Sound statistics */ 00386 PLCore::Array<Resource*> m_lstResources; /**< Sound resources of this sound manager */ 00387 00388 00389 //[-------------------------------------------------------] 00390 //[ Private functions ] 00391 //[-------------------------------------------------------] 00392 private: 00393 /** 00394 * @brief 00395 * Copy constructor 00396 * 00397 * @param[in] cSource 00398 * Source to copy from 00399 */ 00400 SoundManager(const SoundManager &cSource); 00401 00402 /** 00403 * @brief 00404 * Copy operator 00405 * 00406 * @param[in] cSource 00407 * Source to copy from 00408 * 00409 * @return 00410 * Reference to this instance 00411 */ 00412 SoundManager &operator =(const SoundManager &cSource); 00413 00414 00415 //[-------------------------------------------------------] 00416 //[ Private virtual PLCore::ResourceManager functions ] 00417 //[-------------------------------------------------------] 00418 private: 00419 virtual Buffer *CreateResource(const PLCore::String &sName) override; 00420 00421 00422 }; 00423 00424 00425 //[-------------------------------------------------------] 00426 //[ Namespace ] 00427 //[-------------------------------------------------------] 00428 } // PLSound 00429 00430 00431 #endif // __PLSOUND_SOUNDMANAGER_H__
|