00001 /******************************************************************************* 00002 The content of this file includes portions of the AUDIOKINETIC Wwise Technology 00003 released in source code form as part of the SDK installer package. 00004 00005 Commercial License Usage 00006 00007 Licensees holding valid commercial licenses to the AUDIOKINETIC Wwise Technology 00008 may use this file in accordance with the end user license agreement provided 00009 with the software or, alternatively, in accordance with the terms contained in a 00010 written agreement between you and Audiokinetic Inc. 00011 00012 Apache License Usage 00013 00014 Alternatively, this file may be used under the Apache License, Version 2.0 (the 00015 "Apache License"); you may not use this file except in compliance with the 00016 Apache License. You may obtain a copy of the Apache License at 00017 http://www.apache.org/licenses/LICENSE-2.0. 00018 00019 Unless required by applicable law or agreed to in writing, software distributed 00020 under the Apache License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES 00021 OR CONDITIONS OF ANY KIND, either express or implied. See the Apache License for 00022 the specific language governing permissions and limitations under the License. 00023 00024 Version: <VERSION> Build: <BUILDNUMBER> 00025 Copyright (c) <COPYRIGHTYEAR> Audiokinetic Inc. 00026 *******************************************************************************/ 00027 00028 #ifndef _AK_SOUNDENGINE_AKDYNAMICSEQUENCE_H 00029 #define _AK_SOUNDENGINE_AKDYNAMICSEQUENCE_H 00030 00031 #include <AK/SoundEngine/Common/AkSoundEngine.h> 00032 #include <AK/Tools/Common/AkArray.h> 00033 00034 class AkExternalSourceArray; 00035 00036 namespace AK 00037 { 00038 namespace SoundEngine 00039 { 00040 /// Dynamic Sequence namespace 00041 /// \remarks The functions in this namespace are thread-safe, unless stated otherwise. 00042 namespace DynamicSequence 00043 { 00044 /// Playlist Item for Dynamic Sequence Playlist. 00045 /// \sa 00046 /// - AK::SoundEngine::DynamicSequence::Playlist 00047 /// - AK::SoundEngine::PostEvent 00048 /// - \ref integrating_external_sources 00049 class PlaylistItem 00050 { 00051 public: 00052 PlaylistItem(); 00053 PlaylistItem(const PlaylistItem& in_rCopy); 00054 ~PlaylistItem(); 00055 00056 PlaylistItem& operator=(const PlaylistItem& in_rCopy); 00057 bool operator==(const PlaylistItem& in_rCopy) 00058 { 00059 AKASSERT(pExternalSrcs == NULL); 00060 return audioNodeID == in_rCopy.audioNodeID && 00061 msDelay == in_rCopy.msDelay && 00062 pCustomInfo == in_rCopy.pCustomInfo; 00063 }; 00064 00065 /// Sets the external sources used by this item. 00066 /// \sa 00067 /// \ref integrating_external_sources 00068 AKRESULT SetExternalSources(AkUInt32 in_nExternalSrc, AkExternalSourceInfo* in_pExternalSrc); 00069 00070 /// Get the external source array. Internal use only. 00071 AkExternalSourceArray* GetExternalSources(){return pExternalSrcs;} 00072 00073 AkUniqueID audioNodeID; ///< Unique ID of Audio Node 00074 AkTimeMs msDelay; ///< Delay before playing this item, in milliseconds 00075 void * pCustomInfo; ///< Optional user data 00076 00077 private: 00078 AkExternalSourceArray *pExternalSrcs; 00079 }; 00080 00081 /// List of items to play in a Dynamic Sequence. 00082 /// \sa 00083 /// - AK::SoundEngine::DynamicSequence::LockPlaylist 00084 /// - AK::SoundEngine::DynamicSequence::UnlockPlaylist 00085 class Playlist 00086 : public AkArray<PlaylistItem, const PlaylistItem&, ArrayPoolDefault, 4> 00087 { 00088 public: 00089 /// Enqueue an Audio Node. 00090 /// \return AK_Success if successful, AK_Fail otherwise 00091 AkForceInline AKRESULT Enqueue( 00092 AkUniqueID in_audioNodeID, ///< Unique ID of Audio Node 00093 AkTimeMs in_msDelay = 0, ///< Delay before playing this item, in milliseconds 00094 void * in_pCustomInfo = NULL, ///< Optional user data 00095 AkUInt32 in_cExternals = 0, ///< Optional count of external source structures 00096 AkExternalSourceInfo *in_pExternalSources = NULL///< Optional array of external source resolution information 00097 ) 00098 { 00099 PlaylistItem * pItem = AddLast(); 00100 if ( !pItem ) 00101 return AK_Fail; 00102 00103 pItem->audioNodeID = in_audioNodeID; 00104 pItem->msDelay = in_msDelay; 00105 pItem->pCustomInfo = in_pCustomInfo; 00106 return pItem->SetExternalSources(in_cExternals, in_pExternalSources); 00107 } 00108 }; 00109 00110 /// The DynamicSequenceType is specified when creating a new dynamic sequence.\n 00111 /// \n 00112 /// The default option is DynamicSequenceType_SampleAccurate. \n 00113 /// \n 00114 /// In sample accurate mode, when a dynamic sequence item finishes playing and there is another item\n 00115 /// pending in its playlist, the next sound will be stitched to the end of the ending sound. In this \n 00116 /// mode, if there are one or more pending items in the playlist while the dynamic sequence is playing,\n 00117 /// or if something is added to the playlist during the playback, the dynamic sequence\n 00118 /// can remove the next item to be played from the playlist and prepare it for sample accurate playback before\n 00119 /// the first sound is finished playing. This mechanism helps keep sounds sample accurate, but then\n 00120 /// you might not be able to remove that next item from the playlist if required.\n 00121 /// \n 00122 /// If your game requires the capability of removing the next to be played item from the\n 00123 /// playlist at any time, then you should use the DynamicSequenceType_NormalTransition option instead.\n 00124 /// In this mode, you cannot ensure sample accuracy between sounds.\n 00125 /// \n 00126 /// Note that a Stop or a Break will always prevent the next to be played sound from actually being played. 00127 /// 00128 /// \sa 00129 /// - AK::SoundEngine::DynamicSequence::Open 00130 enum DynamicSequenceType 00131 { 00132 DynamicSequenceType_SampleAccurate, ///< Sample accurate mode 00133 DynamicSequenceType_NormalTransition ///< Normal transition mode, allows the entire playlist to be edited at all times. 00134 }; 00135 00136 /// Open a new Dynamic Sequence. 00137 /// \return Playing ID of the dynamic sequence, or AK_INVALID_PLAYING_ID in failure case 00138 /// 00139 /// \sa 00140 /// - AK::SoundEngine::DynamicSequence::DynamicSequenceType 00141 AK_EXTERNAPIFUNC( AkPlayingID, Open )( 00142 AkGameObjectID in_gameObjectID, ///< Associated game object ID 00143 AkUInt32 in_uFlags = 0, ///< Bitmask: see \ref AkCallbackType 00144 AkCallbackFunc in_pfnCallback = NULL, ///< Callback function 00145 void* in_pCookie = NULL, ///< Callback cookie that will be sent to the callback function along with additional information; 00146 DynamicSequenceType in_eDynamicSequenceType = DynamicSequenceType_SampleAccurate ///< See : \ref AK::SoundEngine::DynamicSequence::DynamicSequenceType 00147 ); 00148 00149 /// Close specified Dynamic Sequence. The Dynamic Sequence will play until finished and then 00150 /// deallocate itself. 00151 AK_EXTERNAPIFUNC( AKRESULT, Close )( 00152 AkPlayingID in_playingID ///< AkPlayingID returned by DynamicSequence::Open 00153 ); 00154 00155 /// Play specified Dynamic Sequence. 00156 AK_EXTERNAPIFUNC( AKRESULT, Play )( 00157 AkPlayingID in_playingID, ///< AkPlayingID returned by DynamicSequence::Open 00158 AkTimeMs in_uTransitionDuration = 0, ///< Fade duration 00159 AkCurveInterpolation in_eFadeCurve = AkCurveInterpolation_Linear ///< Curve type to be used for the transition 00160 ); 00161 00162 /// Pause specified Dynamic Sequence. 00163 /// To restart the sequence, call Resume. The item paused will resume its playback, followed by the rest of the sequence. 00164 AK_EXTERNAPIFUNC( AKRESULT, Pause )( 00165 AkPlayingID in_playingID, ///< AkPlayingID returned by DynamicSequence::Open 00166 AkTimeMs in_uTransitionDuration = 0, ///< Fade duration 00167 AkCurveInterpolation in_eFadeCurve = AkCurveInterpolation_Linear ///< Curve type to be used for the transition 00168 ); 00169 00170 /// Resume specified Dynamic Sequence. 00171 AK_EXTERNAPIFUNC( AKRESULT, Resume )( 00172 AkPlayingID in_playingID, ///< AkPlayingID returned by DynamicSequence::Open 00173 AkTimeMs in_uTransitionDuration = 0, ///< Fade duration 00174 AkCurveInterpolation in_eFadeCurve = AkCurveInterpolation_Linear ///< Curve type to be used for the transition 00175 ); 00176 00177 /// Stop specified Dynamic Sequence immediately. 00178 /// To restart the sequence, call Play. The sequence will restart with the item that was in the 00179 /// playlist after the item that was stopped. 00180 AK_EXTERNAPIFUNC( AKRESULT, Stop )( 00181 AkPlayingID in_playingID, ///< AkPlayingID returned by DynamicSequence::Open 00182 AkTimeMs in_uTransitionDuration = 0, ///< Fade duration 00183 AkCurveInterpolation in_eFadeCurve = AkCurveInterpolation_Linear ///< Curve type to be used for the transition 00184 ); 00185 00186 /// Break specified Dynamic Sequence. The sequence will stop after the current item. 00187 AK_EXTERNAPIFUNC( AKRESULT, Break )( 00188 AkPlayingID in_playingID ///< AkPlayingID returned by DynamicSequence::Open 00189 ); 00190 00191 /// Get pause times. 00192 AK_EXTERNAPIFUNC(AKRESULT, GetPauseTimes)( 00193 AkPlayingID in_playingID, ///< AkPlayingID returned by DynamicSequence::Open 00194 AkUInt32 &out_uTime, ///< If sequence is currently paused, returns time when pause started, else 0. 00195 AkUInt32 &out_uDuration ///< Returns total pause duration since last call to GetPauseTimes, excluding the time elapsed in the current pause. 00196 ); 00197 00198 /// Get currently playing item. Note that this may be different from the currently heard item 00199 /// when sequence is in sample-accurate mode. 00200 AK_EXTERNAPIFUNC(AKRESULT, GetPlayingItem)( 00201 AkPlayingID in_playingID, ///< AkPlayingID returned by DynamicSequence::Open 00202 AkUniqueID & out_audioNodeID, ///< Returned audio node ID of playing item. 00203 void *& out_pCustomInfo ///< Returned user data of playing item. 00204 ); 00205 00206 /// Lock the Playlist for editing. Needs a corresponding UnlockPlaylist call. 00207 /// \return Pointer to locked Playlist if successful, NULL otherwise 00208 /// \sa 00209 /// - AK::SoundEngine::DynamicSequence::UnlockPlaylist 00210 AK_EXTERNAPIFUNC( Playlist *, LockPlaylist )( 00211 AkPlayingID in_playingID ///< AkPlayingID returned by DynamicSequence::Open 00212 ); 00213 00214 /// Unlock the playlist. 00215 /// \sa 00216 /// - AK::SoundEngine::DynamicSequence::LockPlaylist 00217 AK_EXTERNAPIFUNC( AKRESULT, UnlockPlaylist )( 00218 AkPlayingID in_playingID ///< AkPlayingID returned by DynamicSequence::Open 00219 ); 00220 } 00221 } 00222 } 00223 00224 #endif // _AK_SOUNDENGINE_AKDYNAMICSEQUENCE_H