Version
menu_open
link
Wwise SDK 2022.1.8
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  Copyright (c) 2023 Audiokinetic Inc.
25 *******************************************************************************/
26 
27 #ifndef _AK_SOUNDENGINE_AKDYNAMICSEQUENCE_H
28 #define _AK_SOUNDENGINE_AKDYNAMICSEQUENCE_H
29 
31 #include <AK/Tools/Common/AkArray.h>
32 
33 class AkExternalSourceArray;
34 
35 namespace AK
36 {
37  namespace SoundEngine
38  {
39  /// Dynamic Sequence namespace. Use the Dynamic Sequence API to play and sequence Dialogue Events dynamically, according to a set of rules and conditions. For more information, refer to \ref integrating_elements_dynamicdialogue and <a href="https://www.audiokinetic.com/library/edge/?source=Help&id=understanding_dynamic_dialogue_system" target="_blank">Understanding the Dynamic Dialogue System</a>.
40  /// \remarks The functions in this namespace are thread-safe, unless stated otherwise.
41  namespace DynamicSequence
42  {
43  /// Playlist Item for Dynamic Sequence Playlist.
44  /// \sa
45  /// - AK::SoundEngine::DynamicSequence::Playlist
46  /// - AK::SoundEngine::PostEvent
47  /// - \ref integrating_external_sources
48  class PlaylistItem
49  {
50  public:
52  PlaylistItem(const PlaylistItem& in_rCopy);
54 
55  PlaylistItem& operator=(const PlaylistItem& in_rCopy);
56  bool operator==(const PlaylistItem& in_rCopy)
57  {
58  AKASSERT(pExternalSrcs == NULL);
59  return audioNodeID == in_rCopy.audioNodeID &&
60  msDelay == in_rCopy.msDelay &&
61  pCustomInfo == in_rCopy.pCustomInfo;
62  };
63 
64  /// Sets the external sources used by this item.
65  /// \sa
66  /// \ref integrating_external_sources
67  AKRESULT SetExternalSources(AkUInt32 in_nExternalSrc, AkExternalSourceInfo* in_pExternalSrc);
68 
69  /// Get the external source array. Internal use only.
70  AkExternalSourceArray* GetExternalSources(){return pExternalSrcs;}
71 
72  AkUniqueID audioNodeID; ///< Unique ID of Audio Node
73  AkTimeMs msDelay; ///< Delay before playing this item, in milliseconds
74  void * pCustomInfo; ///< Optional user data
75 
76  private:
77  AkExternalSourceArray *pExternalSrcs;
78  };
79 
80  /// List of items to play in a Dynamic Sequence.
81  /// \sa
82  /// - AK::SoundEngine::DynamicSequence::LockPlaylist
83  /// - AK::SoundEngine::DynamicSequence::UnlockPlaylist
84  class Playlist
85  : public AkArray<PlaylistItem, const PlaylistItem&>
86  {
87  public:
88  /// Enqueue an Audio Node.
89  /// \return AK_Success if successful, AK_Fail otherwise
91  AkUniqueID in_audioNodeID, ///< Unique ID of Audio Node
92  AkTimeMs in_msDelay = 0, ///< Delay before playing this item, in milliseconds
93  void * in_pCustomInfo = NULL, ///< Optional user data
94  AkUInt32 in_cExternals = 0, ///< Optional count of external source structures
95  AkExternalSourceInfo *in_pExternalSources = NULL///< Optional array of external source resolution information
96  )
97  {
98  PlaylistItem * pItem = AddLast();
99  if ( !pItem )
100  return AK_InsufficientMemory;
101 
102  pItem->audioNodeID = in_audioNodeID;
103  pItem->msDelay = in_msDelay;
104  pItem->pCustomInfo = in_pCustomInfo;
105  return pItem->SetExternalSources(in_cExternals, in_pExternalSources);
106  }
107  };
108 
109  /// The DynamicSequenceType is specified when creating a new dynamic sequence.\n
110  /// \n
111  /// The default option is DynamicSequenceType_SampleAccurate. \n
112  /// \n
113  /// In sample accurate mode, when a dynamic sequence item finishes playing and there is another item\n
114  /// pending in its playlist, the next sound will be stitched to the end of the ending sound. In this \n
115  /// mode, if there are one or more pending items in the playlist while the dynamic sequence is playing,\n
116  /// or if something is added to the playlist during the playback, the dynamic sequence\n
117  /// can remove the next item to be played from the playlist and prepare it for sample accurate playback before\n
118  /// the first sound is finished playing. This mechanism helps keep sounds sample accurate, but then\n
119  /// you might not be able to remove that next item from the playlist if required.\n
120  /// \n
121  /// If your game requires the capability of removing the next to be played item from the\n
122  /// playlist at any time, then you should use the DynamicSequenceType_NormalTransition option instead.\n
123  /// In this mode, you cannot ensure sample accuracy between sounds.\n
124  /// \n
125  /// Note that a Stop or a Break will always prevent the next to be played sound from actually being played.
126  ///
127  /// \sa
128  /// - AK::SoundEngine::DynamicSequence::Open
130  {
131  DynamicSequenceType_SampleAccurate, ///< Sample accurate mode
132  DynamicSequenceType_NormalTransition ///< Normal transition mode, allows the entire playlist to be edited at all times.
133  };
134 
135  /// Open a new Dynamic Sequence.
136  /// \return Playing ID of the dynamic sequence, or AK_INVALID_PLAYING_ID in failure case and an error message in the debug console and Wwise Profiler
137  ///
138  /// \sa
139  /// - AK::SoundEngine::DynamicSequence::DynamicSequenceType
141  AkGameObjectID in_gameObjectID, ///< Associated game object ID
142  AkUInt32 in_uFlags = 0, ///< Bitmask: see \ref AkCallbackType
143  AkCallbackFunc in_pfnCallback = NULL, ///< Callback function
144  void* in_pCookie = NULL, ///< Callback cookie that will be sent to the callback function along with additional information;
145  DynamicSequenceType in_eDynamicSequenceType = DynamicSequenceType_SampleAccurate ///< See : \ref AK::SoundEngine::DynamicSequence::DynamicSequenceType
146  );
147 
148  /// Close specified Dynamic Sequence. The Dynamic Sequence will play until finished and then
149  /// deallocate itself.
150  /// \return
151  /// - AK_Success if the command was successfully queued
152  /// - AK_PlayingIDNotFound if the playing ID does not match to any open Dynamic Sequence
154  AkPlayingID in_playingID ///< AkPlayingID returned by DynamicSequence::Open
155  );
156 
157  /// Play specified Dynamic Sequence.
158  /// \return
159  /// - AK_Success if the command was successfully queued
160  /// - AK_PlayingIDNotFound if the playing ID does not match to any open Dynamic Sequence
162  AkPlayingID in_playingID, ///< AkPlayingID returned by DynamicSequence::Open
163  AkTimeMs in_uTransitionDuration = 0, ///< Fade duration
164  AkCurveInterpolation in_eFadeCurve = AkCurveInterpolation_Linear ///< Curve type to be used for the transition
165  );
166 
167  /// Pause specified Dynamic Sequence.
168  /// To restart the sequence, call Resume. The item paused will resume its playback, followed by the rest of the sequence.
169  /// \return
170  /// - AK_Success if the command was successfully queued
171  /// - AK_PlayingIDNotFound if the playing ID does not match to any open Dynamic Sequence
173  AkPlayingID in_playingID, ///< AkPlayingID returned by DynamicSequence::Open
174  AkTimeMs in_uTransitionDuration = 0, ///< Fade duration
175  AkCurveInterpolation in_eFadeCurve = AkCurveInterpolation_Linear ///< Curve type to be used for the transition
176  );
177 
178  /// Resume specified Dynamic Sequence.
179  /// \return
180  /// - AK_Success if the command was successfully queued
181  /// - AK_PlayingIDNotFound if the playing ID does not match to any open Dynamic Sequence
183  AkPlayingID in_playingID, ///< AkPlayingID returned by DynamicSequence::Open
184  AkTimeMs in_uTransitionDuration = 0, ///< Fade duration
185  AkCurveInterpolation in_eFadeCurve = AkCurveInterpolation_Linear ///< Curve type to be used for the transition
186  );
187 
188  /// Stop specified Dynamic Sequence immediately.
189  /// To restart the sequence, call Play. The sequence will restart with the item that was in the
190  /// playlist after the item that was stopped.
191  /// \return
192  /// - AK_Success if the command was successfully queued
193  /// - AK_PlayingIDNotFound if the playing ID does not match to any open Dynamic Sequence
195  AkPlayingID in_playingID, ///< AkPlayingID returned by DynamicSequence::Open
196  AkTimeMs in_uTransitionDuration = 0, ///< Fade duration
197  AkCurveInterpolation in_eFadeCurve = AkCurveInterpolation_Linear ///< Curve type to be used for the transition
198  );
199 
200  /// Break specified Dynamic Sequence. The sequence will stop after the current item.
201  /// \return
202  /// - AK_Success if the command was successfully queued
203  /// - AK_PlayingIDNotFound if the playing ID does not match to any open Dynamic Sequence
205  AkPlayingID in_playingID ///< AkPlayingID returned by DynamicSequence::Open
206  );
207 
208  /// Seek inside specified Dynamic Sequence.
209  /// It is only possible to seek in the first item of the sequence.
210  /// 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.
211  /// All the other items in the sequence will continue to play normally.
212  /// \return
213  /// - AK_Success if the command was successfully queued
214  /// - AK_PlayingIDNotFound if the playing ID does not match to any open Dynamic Sequence
216  AkPlayingID in_playingID, ///< AkPlayingID returned by DynamicSequence::Open
217  AkTimeMs in_iPosition, ///< Position into the the sound, in milliseconds
218  bool in_bSeekToNearestMarker ///< Snap to the marker nearest to the seek position.
219  );
220 
221  /// Seek inside specified Dynamic Sequence.
222  /// It is only possible to seek in the first item of the sequence.
223  /// 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.
224  /// All the other items in the sequence will continue to play normally.
225  /// \return
226  /// - AK_Success if the command was successfully queued
227  /// - AK_PlayingIDNotFound if the playing ID does not match to any open Dynamic Sequence
229  AkPlayingID in_playingID, ///< AkPlayingID returned by DynamicSequence::Open
230  AkReal32 in_fPercent, ///< Position into the the sound, in percentage of the whole duration.
231  bool in_bSeekToNearestMarker ///< Snap to the marker nearest to the seek position.
232  );
233 
234  /// Get pause times.
235  /// \return
236  /// - AK_Success if successful
237  /// - AK_PlayingIDNotFound if the playing ID does not match to any open Dynamic Sequence
239  AkPlayingID in_playingID, ///< AkPlayingID returned by DynamicSequence::Open
240  AkUInt32 &out_uTime, ///< If sequence is currently paused, returns time when pause started, else 0.
241  AkUInt32 &out_uDuration ///< Returns total pause duration since last call to GetPauseTimes, excluding the time elapsed in the current pause.
242  );
243 
244  /// Get currently playing item. Note that this may be different from the currently heard item
245  /// when sequence is in sample-accurate mode.
246  /// \return
247  /// - AK_Success if successful
248  /// - AK_PlayingIDNotFound if the playing ID does not match to any open Dynamic Sequence
250  AkPlayingID in_playingID, ///< AkPlayingID returned by DynamicSequence::Open
251  AkUniqueID & out_audioNodeID, ///< Returned audio node ID of playing item.
252  void *& out_pCustomInfo ///< Returned user data of playing item.
253  );
254 
255  /// Lock the Playlist for editing. Needs a corresponding UnlockPlaylist call.
256  /// \return Pointer to locked Playlist if successful, NULL otherwise (in_playingID not found)
257  /// \sa
258  /// - AK::SoundEngine::DynamicSequence::UnlockPlaylist
260  AkPlayingID in_playingID ///< AkPlayingID returned by DynamicSequence::Open
261  );
262 
263  /// Unlock the playlist.
264  /// \return
265  /// - AK_Success if successful
266  /// - AK_PlayingIDNotFound if the playing ID does not match to any open Dynamic Sequence
267  /// \sa
268  /// - AK::SoundEngine::DynamicSequence::LockPlaylist
270  AkPlayingID in_playingID ///< AkPlayingID returned by DynamicSequence::Open
271  );
272  }
273  }
274 }
275 
276 #endif // _AK_SOUNDENGINE_AKDYNAMICSEQUENCE_H
AKSOUNDENGINE_API AKRESULT Stop(AkPlayingID in_playingID, AkTimeMs in_uTransitionDuration=0, AkCurveInterpolation in_eFadeCurve=AkCurveInterpolation_Linear)
AKRESULT SetExternalSources(AkUInt32 in_nExternalSrc, AkExternalSourceInfo *in_pExternalSrc)
AKSOUNDENGINE_API AKRESULT GetPlayingItem(AkPlayingID in_playingID, AkUniqueID &out_audioNodeID, void *&out_pCustomInfo)
AkInt32 AkTimeMs
Time in ms.
Definition: AkTypes.h:124
Audiokinetic namespace.
AkUniqueID audioNodeID
Unique ID of Audio Node.
AkUInt64 AkGameObjectID
Game object ID.
Definition: AkTypes.h:128
#define AK_EXTERNAPIFUNC(_type, _name)
AkTimeMs msDelay
Delay before playing this item, in milliseconds.
AKRESULT
Standard function call result.
Definition: AkTypes.h:199
PlaylistItem & operator=(const PlaylistItem &in_rCopy)
AKSOUNDENGINE_API AKRESULT Resume(AkPlayingID in_playingID, AkTimeMs in_uTransitionDuration=0, AkCurveInterpolation in_eFadeCurve=AkCurveInterpolation_Linear)
Specific implementation of array.
Definition: AkArray.h:241
#define NULL
Definition: AkTypes.h:46
float AkReal32
32-bit floating point
Definition: AkNumeralTypes.h:46
AKSOUNDENGINE_API AKRESULT Pause(AkPlayingID in_playingID, AkTimeMs in_uTransitionDuration=0, AkCurveInterpolation in_eFadeCurve=AkCurveInterpolation_Linear)
PlaylistItem(const PlaylistItem &in_rCopy)
AKSOUNDENGINE_API Playlist * LockPlaylist(AkPlayingID in_playingID)
AKSOUNDENGINE_API AKRESULT Play(AkPlayingID in_playingID, AkTimeMs in_uTransitionDuration=0, AkCurveInterpolation in_eFadeCurve=AkCurveInterpolation_Linear)
AkUInt32 AkUniqueID
Unique 32-bit ID.
Definition: AkTypes.h:120
#define AKASSERT(Condition)
Definition: AkAssert.h:67
@ DynamicSequenceType_SampleAccurate
Sample accurate mode.
void(* AkCallbackFunc)(AkCallbackType in_eType, AkCallbackInfo *in_pCallbackInfo)
Definition: AkCallback.h:266
AkForceInline AKRESULT Enqueue(AkUniqueID in_audioNodeID, AkTimeMs in_msDelay=0, void *in_pCustomInfo=NULL, AkUInt32 in_cExternals=0, AkExternalSourceInfo *in_pExternalSources=NULL)
AkCurveInterpolation
Curve interpolation types.
Definition: AkTypes.h:900
@ AkCurveInterpolation_Linear
Linear (Default)
Definition: AkTypes.h:907
AKSOUNDENGINE_API AKRESULT Seek(AkPlayingID in_playingID, AkTimeMs in_iPosition, bool in_bSeekToNearestMarker)
AkExternalSourceArray * GetExternalSources()
Get the external source array. Internal use only.
AkForceInline PlaylistItem * AddLast()
Definition: AkArray.h:575
AKSOUNDENGINE_API AKRESULT UnlockPlaylist(AkPlayingID in_playingID)
uint32_t AkUInt32
Unsigned 32-bit integer.
Definition: AkNumeralTypes.h:38
AKSOUNDENGINE_API AkPlayingID Open(AkGameObjectID in_gameObjectID, AkUInt32 in_uFlags=0, AkCallbackFunc in_pfnCallback=NULL, void *in_pCookie=NULL, DynamicSequenceType in_eDynamicSequenceType=DynamicSequenceType_SampleAccurate)
@ AK_InsufficientMemory
Memory error.
Definition: AkTypes.h:229
#define AkForceInline
Definition: AkTypes.h:61
AkUInt32 AkPlayingID
Playing ID.
Definition: AkTypes.h:123
@ DynamicSequenceType_NormalTransition
Normal transition mode, allows the entire playlist to be edited at all times.
AKSOUNDENGINE_API AKRESULT GetPauseTimes(AkPlayingID in_playingID, AkUInt32 &out_uTime, AkUInt32 &out_uDuration)
void * pCustomInfo
Optional user data.
bool operator==(const PlaylistItem &in_rCopy)
AKSOUNDENGINE_API AKRESULT Close(AkPlayingID in_playingID)
AKSOUNDENGINE_API AKRESULT Break(AkPlayingID in_playingID)

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