Version
menu_open
Wwise SDK 2019.2.15
AkDynamicSequence.h
Go to the documentation of this file.
1 /*******************************************************************************
2 The content of this file includes portions of the AUDIOKINETIC Wwise Technology
3 released in source code form as part of the SDK installer package.
4 
5 Commercial License Usage
6 
7 Licensees holding valid commercial licenses to the AUDIOKINETIC Wwise Technology
8 may use this file in accordance with the end user license agreement provided
9 with the software or, alternatively, in accordance with the terms contained in a
10 written agreement between you and Audiokinetic Inc.
11 
12 Apache License Usage
13 
14 Alternatively, this file may be used under the Apache License, Version 2.0 (the
15 "Apache License"); you may not use this file except in compliance with the
16 Apache License. You may obtain a copy of the Apache License at
17 http://www.apache.org/licenses/LICENSE-2.0.
18 
19 Unless required by applicable law or agreed to in writing, software distributed
20 under the Apache License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES
21 OR CONDITIONS OF ANY KIND, either express or implied. See the Apache License for
22 the specific language governing permissions and limitations under the License.
23 
24  Version: <VERSION> Build: <BUILDNUMBER>
25  Copyright (c) <COPYRIGHTYEAR> Audiokinetic Inc.
26 *******************************************************************************/
27 
28 #ifndef _AK_SOUNDENGINE_AKDYNAMICSEQUENCE_H
29 #define _AK_SOUNDENGINE_AKDYNAMICSEQUENCE_H
30 
31 #include <AK/SoundEngine/Common/AkSoundEngine.h>
32 #include <AK/Tools/Common/AkArray.h>
33 
34 class AkExternalSourceArray;
35 
36 namespace AK
37 {
38  namespace SoundEngine
39  {
40  /// Dynamic Sequence namespace
41  /// \remarks The functions in this namespace are thread-safe, unless stated otherwise.
42  namespace DynamicSequence
43  {
44  /// Playlist Item for Dynamic Sequence Playlist.
45  /// \sa
46  /// - AK::SoundEngine::DynamicSequence::Playlist
47  /// - AK::SoundEngine::PostEvent
48  /// - \ref integrating_external_sources
49  class PlaylistItem
50  {
51  public:
52  PlaylistItem();
53  PlaylistItem(const PlaylistItem& in_rCopy);
54  ~PlaylistItem();
55 
56  PlaylistItem& operator=(const PlaylistItem& in_rCopy);
57  bool operator==(const PlaylistItem& in_rCopy)
58  {
59  AKASSERT(pExternalSrcs == NULL);
60  return audioNodeID == in_rCopy.audioNodeID &&
61  msDelay == in_rCopy.msDelay &&
62  pCustomInfo == in_rCopy.pCustomInfo;
63  };
64 
65  /// Sets the external sources used by this item.
66  /// \sa
67  /// \ref integrating_external_sources
68  AKRESULT SetExternalSources(AkUInt32 in_nExternalSrc, AkExternalSourceInfo* in_pExternalSrc);
69 
70  /// Get the external source array. Internal use only.
71  AkExternalSourceArray* GetExternalSources(){return pExternalSrcs;}
72 
73  AkUniqueID audioNodeID; ///< Unique ID of Audio Node
74  AkTimeMs msDelay; ///< Delay before playing this item, in milliseconds
75  void * pCustomInfo; ///< Optional user data
76 
77  private:
78  AkExternalSourceArray *pExternalSrcs;
79  };
80 
81  /// List of items to play in a Dynamic Sequence.
82  /// \sa
83  /// - AK::SoundEngine::DynamicSequence::LockPlaylist
84  /// - AK::SoundEngine::DynamicSequence::UnlockPlaylist
85  class Playlist
86  : public AkArray<PlaylistItem, const PlaylistItem&>
87  {
88  public:
89  /// Enqueue an Audio Node.
90  /// \return AK_Success if successful, AK_Fail otherwise
91  AkForceInline AKRESULT Enqueue(
92  AkUniqueID in_audioNodeID, ///< Unique ID of Audio Node
93  AkTimeMs in_msDelay = 0, ///< Delay before playing this item, in milliseconds
94  void * in_pCustomInfo = NULL, ///< Optional user data
95  AkUInt32 in_cExternals = 0, ///< Optional count of external source structures
96  AkExternalSourceInfo *in_pExternalSources = NULL///< Optional array of external source resolution information
97  )
98  {
99  PlaylistItem * pItem = AddLast();
100  if ( !pItem )
101  return AK_Fail;
102 
103  pItem->audioNodeID = in_audioNodeID;
104  pItem->msDelay = in_msDelay;
105  pItem->pCustomInfo = in_pCustomInfo;
106  return pItem->SetExternalSources(in_cExternals, in_pExternalSources);
107  }
108  };
109 
110  /// The DynamicSequenceType is specified when creating a new dynamic sequence.\n
111  /// \n
112  /// The default option is DynamicSequenceType_SampleAccurate. \n
113  /// \n
114  /// In sample accurate mode, when a dynamic sequence item finishes playing and there is another item\n
115  /// pending in its playlist, the next sound will be stitched to the end of the ending sound. In this \n
116  /// mode, if there are one or more pending items in the playlist while the dynamic sequence is playing,\n
117  /// or if something is added to the playlist during the playback, the dynamic sequence\n
118  /// can remove the next item to be played from the playlist and prepare it for sample accurate playback before\n
119  /// the first sound is finished playing. This mechanism helps keep sounds sample accurate, but then\n
120  /// you might not be able to remove that next item from the playlist if required.\n
121  /// \n
122  /// If your game requires the capability of removing the next to be played item from the\n
123  /// playlist at any time, then you should use the DynamicSequenceType_NormalTransition option instead.\n
124  /// In this mode, you cannot ensure sample accuracy between sounds.\n
125  /// \n
126  /// Note that a Stop or a Break will always prevent the next to be played sound from actually being played.
127  ///
128  /// \sa
129  /// - AK::SoundEngine::DynamicSequence::Open
130  enum DynamicSequenceType
131  {
132  DynamicSequenceType_SampleAccurate, ///< Sample accurate mode
133  DynamicSequenceType_NormalTransition ///< Normal transition mode, allows the entire playlist to be edited at all times.
134  };
135 
136  /// Open a new Dynamic Sequence.
137  /// \return Playing ID of the dynamic sequence, or AK_INVALID_PLAYING_ID in failure case
138  ///
139  /// \sa
140  /// - AK::SoundEngine::DynamicSequence::DynamicSequenceType
141  AK_EXTERNAPIFUNC( AkPlayingID, Open )(
142  AkGameObjectID in_gameObjectID, ///< Associated game object ID
143  AkUInt32 in_uFlags = 0, ///< Bitmask: see \ref AkCallbackType
144  AkCallbackFunc in_pfnCallback = NULL, ///< Callback function
145  void* in_pCookie = NULL, ///< Callback cookie that will be sent to the callback function along with additional information;
146  DynamicSequenceType in_eDynamicSequenceType = DynamicSequenceType_SampleAccurate ///< See : \ref AK::SoundEngine::DynamicSequence::DynamicSequenceType
147  );
148 
149  /// Close specified Dynamic Sequence. The Dynamic Sequence will play until finished and then
150  /// deallocate itself.
151  AK_EXTERNAPIFUNC( AKRESULT, Close )(
152  AkPlayingID in_playingID ///< AkPlayingID returned by DynamicSequence::Open
153  );
154 
155  /// Play specified Dynamic Sequence.
156  AK_EXTERNAPIFUNC( AKRESULT, Play )(
157  AkPlayingID in_playingID, ///< AkPlayingID returned by DynamicSequence::Open
158  AkTimeMs in_uTransitionDuration = 0, ///< Fade duration
159  AkCurveInterpolation in_eFadeCurve = AkCurveInterpolation_Linear ///< Curve type to be used for the transition
160  );
161 
162  /// Pause specified Dynamic Sequence.
163  /// To restart the sequence, call Resume. The item paused will resume its playback, followed by the rest of the sequence.
164  AK_EXTERNAPIFUNC( AKRESULT, Pause )(
165  AkPlayingID in_playingID, ///< AkPlayingID returned by DynamicSequence::Open
166  AkTimeMs in_uTransitionDuration = 0, ///< Fade duration
167  AkCurveInterpolation in_eFadeCurve = AkCurveInterpolation_Linear ///< Curve type to be used for the transition
168  );
169 
170  /// Resume specified Dynamic Sequence.
171  AK_EXTERNAPIFUNC( AKRESULT, Resume )(
172  AkPlayingID in_playingID, ///< AkPlayingID returned by DynamicSequence::Open
173  AkTimeMs in_uTransitionDuration = 0, ///< Fade duration
174  AkCurveInterpolation in_eFadeCurve = AkCurveInterpolation_Linear ///< Curve type to be used for the transition
175  );
176 
177  /// Stop specified Dynamic Sequence immediately.
178  /// To restart the sequence, call Play. The sequence will restart with the item that was in the
179  /// playlist after the item that was stopped.
180  AK_EXTERNAPIFUNC( AKRESULT, Stop )(
181  AkPlayingID in_playingID, ///< AkPlayingID returned by DynamicSequence::Open
182  AkTimeMs in_uTransitionDuration = 0, ///< Fade duration
183  AkCurveInterpolation in_eFadeCurve = AkCurveInterpolation_Linear ///< Curve type to be used for the transition
184  );
185 
186  /// Break specified Dynamic Sequence. The sequence will stop after the current item.
187  AK_EXTERNAPIFUNC( AKRESULT, Break )(
188  AkPlayingID in_playingID ///< AkPlayingID returned by DynamicSequence::Open
189  );
190 
191  /// Seek inside specified Dynamic Sequence.
192  /// It is only possible to seek in the first item of the sequence.
193  /// If you seek past the duration of the first item, it will be skipped and an error will reported in the Capture Log and debug output.
194  /// All the other items in the sequence will continue to play normally.
195  AK_EXTERNAPIFUNC( AKRESULT, Seek )(
196  AkPlayingID in_playingID, ///< AkPlayingID returned by DynamicSequence::Open
197  AkTimeMs in_iPosition, ///< Position into the the sound, in milliseconds
198  bool in_bSeekToNearestMarker ///< Snap to the marker nearest to the seek position.
199  );
200 
201  /// Seek inside specified Dynamic Sequence.
202  /// It is only possible to seek in the first item of the sequence.
203  /// If you seek past the duration of the first item, it will be skipped and an error will reported in the Capture Log and debug output.
204  /// All the other items in the sequence will continue to play normally.
205  AK_EXTERNAPIFUNC(AKRESULT, Seek)(
206  AkPlayingID in_playingID, ///< AkPlayingID returned by DynamicSequence::Open
207  AkReal32 in_fPercent, ///< Position into the the sound, in percentage of the whole duration.
208  bool in_bSeekToNearestMarker ///< Snap to the marker nearest to the seek position.
209  );
210 
211  /// Get pause times.
212  AK_EXTERNAPIFUNC(AKRESULT, GetPauseTimes)(
213  AkPlayingID in_playingID, ///< AkPlayingID returned by DynamicSequence::Open
214  AkUInt32 &out_uTime, ///< If sequence is currently paused, returns time when pause started, else 0.
215  AkUInt32 &out_uDuration ///< Returns total pause duration since last call to GetPauseTimes, excluding the time elapsed in the current pause.
216  );
217 
218  /// Get currently playing item. Note that this may be different from the currently heard item
219  /// when sequence is in sample-accurate mode.
220  AK_EXTERNAPIFUNC(AKRESULT, GetPlayingItem)(
221  AkPlayingID in_playingID, ///< AkPlayingID returned by DynamicSequence::Open
222  AkUniqueID & out_audioNodeID, ///< Returned audio node ID of playing item.
223  void *& out_pCustomInfo ///< Returned user data of playing item.
224  );
225 
226  /// Lock the Playlist for editing. Needs a corresponding UnlockPlaylist call.
227  /// \return Pointer to locked Playlist if successful, NULL otherwise
228  /// \sa
229  /// - AK::SoundEngine::DynamicSequence::UnlockPlaylist
230  AK_EXTERNAPIFUNC( Playlist *, LockPlaylist )(
231  AkPlayingID in_playingID ///< AkPlayingID returned by DynamicSequence::Open
232  );
233 
234  /// Unlock the playlist.
235  /// \sa
236  /// - AK::SoundEngine::DynamicSequence::LockPlaylist
237  AK_EXTERNAPIFUNC( AKRESULT, UnlockPlaylist )(
238  AkPlayingID in_playingID ///< AkPlayingID returned by DynamicSequence::Open
239  );
240  }
241  }
242 }
243 
244 #endif // _AK_SOUNDENGINE_AKDYNAMICSEQUENCE_H
AK::SoundEngine::DynamicSequence::Stop
AKSOUNDENGINE_API AKRESULT Stop(AkPlayingID in_playingID, AkTimeMs in_uTransitionDuration=0, AkCurveInterpolation in_eFadeCurve=AkCurveInterpolation_Linear)
AK::SoundEngine::DynamicSequence::PlaylistItem::SetExternalSources
AKRESULT SetExternalSources(AkUInt32 in_nExternalSrc, AkExternalSourceInfo *in_pExternalSrc)
AK::SoundEngine::DynamicSequence::GetPlayingItem
AKSOUNDENGINE_API AKRESULT GetPlayingItem(AkPlayingID in_playingID, AkUniqueID &out_audioNodeID, void *&out_pCustomInfo)
AkTimeMs
AkInt32 AkTimeMs
Time in ms.
Definition: AkTypes.h:61
AK
Audiokinetic namespace.
Definition: AkWwiseSDKVersion.cs:32
AK_Fail
@ AK_Fail
The operation failed.
Definition: AkTypes.h:125
AK::SoundEngine::DynamicSequence::PlaylistItem::audioNodeID
AkUniqueID audioNodeID
Unique ID of Audio Node.
Definition: AkDynamicSequence.h:73
AkGameObjectID
AkUInt64 AkGameObjectID
Game object ID.
Definition: AkTypes.h:65
AK_EXTERNAPIFUNC
#define AK_EXTERNAPIFUNC(_type, _name)
Definition: AkSoundEngineExport.h:78
AK::SoundEngine::DynamicSequence::PlaylistItem::msDelay
AkTimeMs msDelay
Delay before playing this item, in milliseconds.
Definition: AkDynamicSequence.h:74
AKRESULT
AKRESULT
Standard function call result.
Definition: AkTypes.h:122
AK::SoundEngine::DynamicSequence::PlaylistItem::operator=
PlaylistItem & operator=(const PlaylistItem &in_rCopy)
AK::SoundEngine::DynamicSequence::Resume
AKSOUNDENGINE_API AKRESULT Resume(AkPlayingID in_playingID, AkTimeMs in_uTransitionDuration=0, AkCurveInterpolation in_eFadeCurve=AkCurveInterpolation_Linear)
Resume specified Dynamic Sequence.
AkArray
Specific implementation of array.
Definition: AkArray.h:202
NULL
#define NULL
Definition: AkTypes.h:49
AK::SoundEngine::DynamicSequence::Pause
AKSOUNDENGINE_API AKRESULT Pause(AkPlayingID in_playingID, AkTimeMs in_uTransitionDuration=0, AkCurveInterpolation in_eFadeCurve=AkCurveInterpolation_Linear)
AK::SoundEngine::DynamicSequence::PlaylistItem::PlaylistItem
PlaylistItem(const PlaylistItem &in_rCopy)
AK::SoundEngine::DynamicSequence::LockPlaylist
AKSOUNDENGINE_API Playlist * LockPlaylist(AkPlayingID in_playingID)
AK::SoundEngine::DynamicSequence::Play
AKSOUNDENGINE_API AKRESULT Play(AkPlayingID in_playingID, AkTimeMs in_uTransitionDuration=0, AkCurveInterpolation in_eFadeCurve=AkCurveInterpolation_Linear)
Play specified Dynamic Sequence.
AkUniqueID
AkUInt32 AkUniqueID
Unique 32-bit ID.
Definition: AkTypes.h:57
AKASSERT
#define AKASSERT(Condition)
Definition: AkAssert.h:76
AK::SoundEngine::DynamicSequence::DynamicSequenceType_SampleAccurate
@ DynamicSequenceType_SampleAccurate
Sample accurate mode.
Definition: AkDynamicSequence.h:132
AkCallbackFunc
void(* AkCallbackFunc)(AkCallbackType in_eType, AkCallbackInfo *in_pCallbackInfo)
Definition: AkCallback.h:245
AK::SoundEngine::DynamicSequence::Playlist::Enqueue
AkForceInline AKRESULT Enqueue(AkUniqueID in_audioNodeID, AkTimeMs in_msDelay=0, void *in_pCustomInfo=NULL, AkUInt32 in_cExternals=0, AkExternalSourceInfo *in_pExternalSources=NULL)
Definition: AkDynamicSequence.h:91
AkCurveInterpolation
AkCurveInterpolation
Curve interpolation types.
Definition: AkTypes.h:564
AkCurveInterpolation_Linear
@ AkCurveInterpolation_Linear
Linear (Default)
Definition: AkTypes.h:571
AK::SoundEngine::DynamicSequence::Seek
AKSOUNDENGINE_API AKRESULT Seek(AkPlayingID in_playingID, AkTimeMs in_iPosition, bool in_bSeekToNearestMarker)
AK::SoundEngine::DynamicSequence::PlaylistItem::GetExternalSources
AkExternalSourceArray * GetExternalSources()
Get the external source array. Internal use only.
Definition: AkDynamicSequence.h:71
AkReal32
float AkReal32
32-bit floating point
Definition: AkTypes.h:103
AkArray< PlaylistItem, const PlaylistItem & >::AddLast
AkForceInline PlaylistItem * AddLast()
Definition: AkArray.h:465
AK::SoundEngine::DynamicSequence::UnlockPlaylist
AKSOUNDENGINE_API AKRESULT UnlockPlaylist(AkPlayingID in_playingID)
AK::SoundEngine::DynamicSequence::Open
AKSOUNDENGINE_API AkPlayingID Open(AkGameObjectID in_gameObjectID, AkUInt32 in_uFlags=0, AkCallbackFunc in_pfnCallback=NULL, void *in_pCookie=NULL, DynamicSequenceType in_eDynamicSequenceType=DynamicSequenceType_SampleAccurate)
AkUInt32
uint32_t AkUInt32
Unsigned 32-bit integer.
Definition: AkTypes.h:85
AkForceInline
#define AkForceInline
Definition: AkTypes.h:62
AkPlayingID
AkUInt32 AkPlayingID
Playing ID.
Definition: AkTypes.h:60
AK::SoundEngine::DynamicSequence::DynamicSequenceType_NormalTransition
@ DynamicSequenceType_NormalTransition
Normal transition mode, allows the entire playlist to be edited at all times.
Definition: AkDynamicSequence.h:133
AK::SoundEngine::DynamicSequence::GetPauseTimes
AKSOUNDENGINE_API AKRESULT GetPauseTimes(AkPlayingID in_playingID, AkUInt32 &out_uTime, AkUInt32 &out_uDuration)
Get pause times.
AK::SoundEngine::DynamicSequence::PlaylistItem::pCustomInfo
void * pCustomInfo
Optional user data.
Definition: AkDynamicSequence.h:75
AK::SoundEngine::DynamicSequence::PlaylistItem::operator==
bool operator==(const PlaylistItem &in_rCopy)
Definition: AkDynamicSequence.h:57
AK::SoundEngine::DynamicSequence::Close
AKSOUNDENGINE_API AKRESULT Close(AkPlayingID in_playingID)
AK::SoundEngine::DynamicSequence::Break
AKSOUNDENGINE_API AKRESULT Break(AkPlayingID in_playingID)
Break specified Dynamic Sequence. The sequence will stop after the current item.

Was this page helpful?

Need Support?

Questions? Problems? Need more info? Contact us, and we can help!

Visit our Support page

Tell us about your project. We're here to help.

Register your project and we'll help you get started with no strings attached!

Get started with Wwise