Table of Contents

include/AK/SoundEngine/Common/AkDynamicSequence.h

Go to the documentation of this file.
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