_ak_dynamic_sequence_8h

Wwise SDK 2025.1.0

 /*******************************************************************************
 The content of this file includes portions of the AUDIOKINETIC Wwise Technology
 released in source code form as part of the SDK installer package.
  
 Commercial License Usage
  
 Licensees holding valid commercial licenses to the AUDIOKINETIC Wwise Technology
 may use this file in accordance with the end user license agreement provided 
 with the software or, alternatively, in accordance with the terms contained in a
 written agreement between you and Audiokinetic Inc.
  
 Apache License Usage
  
 Alternatively, this file may be used under the Apache License, Version 2.0 (the 
 "Apache License"); you may not use this file except in compliance with the 
 Apache License. You may obtain a copy of the Apache License at 
 http://www.apache.org/licenses/LICENSE-2.0.
  
 Unless required by applicable law or agreed to in writing, software distributed
 under the Apache License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES
 OR CONDITIONS OF ANY KIND, either express or implied. See the Apache License for
 the specific language governing permissions and limitations under the License.
  
   Copyright (c) 2025 Audiokinetic Inc.
 *******************************************************************************/
  
 #ifndef _AK_SOUNDENGINE_AKDYNAMICSEQUENCE_H
 #define _AK_SOUNDENGINE_AKDYNAMICSEQUENCE_H
  
 #include <AK/SoundEngine/Common/AkSoundEngine.h>
 #include <AK/Tools/Common/AkArray.h>
  
 namespace AK
 {
     namespace SoundEngine
     {
         /// 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, see \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>.
         /// \remarks The functions in this namespace are thread-safe, unless stated otherwise.
         namespace DynamicSequence
         {
             /// Playlist Item for Dynamic Sequence Playlist.
             /// \sa
             /// - AK::SoundEngine::DynamicSequence::Playlist
             /// - AK::SoundEngine::PostEvent
             /// - \ref integrating_external_sources
             class PlaylistItem
             {
             public:
                 PlaylistItem();
                 PlaylistItem(const PlaylistItem& in_rCopy);
                 ~PlaylistItem();
  
                 PlaylistItem& operator=(const PlaylistItem& in_rCopy);
                 bool operator==(const PlaylistItem& in_rCopy)
                 {
                     AKASSERT(pExternalSrcs == NULL);
                     return audioNodeID == in_rCopy.audioNodeID && 
                         msDelay == in_rCopy.msDelay && 
                         pCustomInfo == in_rCopy.pCustomInfo;
                 };
  
                 /// Sets the external sources used by this item.
                 /// \sa 
                 /// \ref integrating_external_sources
                 AKRESULT SetExternalSources(AkUInt32 in_nExternalSrc, AkExternalSourceInfo* in_pExternalSrc);
  
                 AkUniqueID audioNodeID; ///< Unique ID of Audio Node
                 AkTimeMs   msDelay;     ///< Delay before playing this item, in milliseconds
                 void *     pCustomInfo; ///< Optional user data
                 AkExternalSourceArray pExternalSrcs;
             };
  
             /// List of items to play in a Dynamic Sequence.
             /// \sa
             /// - AK::SoundEngine::DynamicSequence::LockPlaylist
             /// - AK::SoundEngine::DynamicSequence::UnlockPlaylist
             class Playlist
                 : public AkArray<PlaylistItem, const PlaylistItem&>
             {
             public:
                 /// Enqueue an Audio Node.
                 /// \return AK_Success if successful, AK_Fail otherwise
                 AkForceInline AKRESULT Enqueue( 
                     AkUniqueID in_audioNodeID,      ///< Unique ID of Audio Node
                     AkTimeMs in_msDelay = 0,        ///< Delay before playing this item, in milliseconds
                     void * in_pCustomInfo = NULL,   ///< Optional user data
                     AkUInt32 in_cExternals = 0,                 ///< Optional count of external source structures
                     AkExternalSourceInfo *in_pExternalSources = NULL///< Optional array of external source resolution information
                     )
                 {
                     PlaylistItem * pItem = AddLast();
                     if ( !pItem )
                         return AK_InsufficientMemory;
  
                     pItem->audioNodeID = in_audioNodeID;
                     pItem->msDelay = in_msDelay;
                     pItem->pCustomInfo = in_pCustomInfo;
                     return pItem->SetExternalSources(in_cExternals, in_pExternalSources);
                 }
             };
  
             // \deprecated Use AkDynamicSequenceType in the global scope.
             using DynamicSequenceType = ::AkDynamicSequenceType;
             const AkDynamicSequenceType DynamicSequenceType_SampleAccurate = AkDynamicSequenceType_SampleAccurate;
             const AkDynamicSequenceType DynamicSequenceType_NormalTransition = AkDynamicSequenceType_NormalTransition;
             const AkDynamicSequenceType DynamicSequenceType_Last = AkDynamicSequenceType_Last;
  
             /// Open a new Dynamic Sequence.
             /// \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
             /// 
             /// If \c AK_DynamicSequenceSelect bit is set in \c in_uFlags, the dynamic sequence uses the callback for determining the next item to play.
             /// If this bit is not set, then the dynamic sequence uses the Playlist to determine the next item to play.
             ///
             /// \sa
             /// - AK::SoundEngine::DynamicSequence::DynamicSequenceType
             AK_EXTERNAPIFUNC( AkPlayingID, Open )(
                 AkGameObjectID      in_gameObjectID,            ///< Associated game object ID
                 AkUInt32            in_uFlags      = 0,         ///< Bitmask: see \ref AkCallbackType
                 AkCallbackFunc      in_pfnCallback = NULL,      ///< Callback function
                 void*               in_pCookie     = NULL,      ///< Callback cookie that will be sent to the callback function along with additional information;
                 AkDynamicSequenceType in_eDynamicSequenceType = AkDynamicSequenceType_SampleAccurate ///< See : \ref AkDynamicSequenceType
                 );
                                                         
             /// Close specified Dynamic Sequence. The Dynamic Sequence will play until finished and then
             /// deallocate itself.
             /// \return 
             /// - AK_Success if the command was successfully queued
             /// - AK_PlayingIDNotFound if the playing ID does not match to any open Dynamic Sequence
             AK_EXTERNAPIFUNC( AKRESULT, Close )(
                 AkPlayingID in_playingID                        ///< AkPlayingID returned by DynamicSequence::Open
                 );
  
             /// Play specified Dynamic Sequence.
             /// \return 
             /// - AK_Success if the command was successfully queued
             /// - AK_PlayingIDNotFound if the playing ID does not match to any open Dynamic Sequence
             AK_EXTERNAPIFUNC( AKRESULT, Play )( 
                 AkPlayingID in_playingID,                                           ///< AkPlayingID returned by DynamicSequence::Open
                 AkTimeMs in_uTransitionDuration = 0,                                ///< Fade duration
                 AkCurveInterpolation in_eFadeCurve = AkCurveInterpolation_Linear    ///< Curve type to be used for the transition
                 );
  
             /// Pause specified Dynamic Sequence. 
             /// To restart the sequence, call Resume.  The item paused will resume its playback, followed by the rest of the sequence.
             /// \return 
             /// - AK_Success if the command was successfully queued
             /// - AK_PlayingIDNotFound if the playing ID does not match to any open Dynamic Sequence
             AK_EXTERNAPIFUNC( AKRESULT, Pause )( 
                 AkPlayingID in_playingID,                                           ///< AkPlayingID returned by DynamicSequence::Open
                 AkTimeMs in_uTransitionDuration = 0,                                ///< Fade duration
                 AkCurveInterpolation in_eFadeCurve = AkCurveInterpolation_Linear    ///< Curve type to be used for the transition
                 );
  
             /// Resume specified Dynamic Sequence.
             /// \return 
             /// - AK_Success if the command was successfully queued
             /// - AK_PlayingIDNotFound if the playing ID does not match to any open Dynamic Sequence
             AK_EXTERNAPIFUNC( AKRESULT, Resume )(
                 AkPlayingID in_playingID,                                           ///< AkPlayingID returned by DynamicSequence::Open
                 AkTimeMs in_uTransitionDuration = 0,                                    ///< Fade duration
                 AkCurveInterpolation in_eFadeCurve = AkCurveInterpolation_Linear    ///< Curve type to be used for the transition
                 );
  
             /// Stop specified Dynamic Sequence immediately.  
             /// To restart the sequence, call Play. The sequence will restart with the item that was in the 
             /// playlist after the item that was stopped.
             /// \return 
             /// - AK_Success if the command was successfully queued
             /// - AK_PlayingIDNotFound if the playing ID does not match to any open Dynamic Sequence
             AK_EXTERNAPIFUNC( AKRESULT, Stop )(
                 AkPlayingID in_playingID,                                           ///< AkPlayingID returned by DynamicSequence::Open
                 AkTimeMs in_uTransitionDuration = 0,                                ///< Fade duration
                 AkCurveInterpolation in_eFadeCurve = AkCurveInterpolation_Linear    ///< Curve type to be used for the transition
                 );
  
             /// Break specified Dynamic Sequence.  The sequence will stop after the current item.
             /// \return 
             /// - AK_Success if the command was successfully queued
             /// - AK_PlayingIDNotFound if the playing ID does not match to any open Dynamic Sequence
             AK_EXTERNAPIFUNC( AKRESULT, Break )(
                 AkPlayingID in_playingID                        ///< AkPlayingID returned by DynamicSequence::Open
                 );
  
             /// Seek inside specified Dynamic Sequence.
             /// It is only possible to seek in the first item of the sequence.
             /// 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. 
             /// All the other items in the sequence will continue to play normally.
             /// \return 
             /// - AK_Success if the command was successfully queued
             /// - AK_PlayingIDNotFound if the playing ID does not match to any open Dynamic Sequence
             AK_EXTERNAPIFUNC( AKRESULT, Seek )(
                 AkPlayingID in_playingID,                       ///< AkPlayingID returned by DynamicSequence::Open
                 AkTimeMs in_iPosition,                          ///< Position into the the sound, in milliseconds
                 bool in_bSeekToNearestMarker                    ///< Snap to the marker nearest to the seek position.
                 );
  
             /// Seek inside specified Dynamic Sequence.
             /// It is only possible to seek in the first item of the sequence.
             /// 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.
             /// All the other items in the sequence will continue to play normally.
             /// \return 
             /// - AK_Success if the command was successfully queued
             /// - AK_PlayingIDNotFound if the playing ID does not match to any open Dynamic Sequence
             AK_EXTERNAPIFUNC(AKRESULT, Seek)(
                 AkPlayingID in_playingID,                       ///< AkPlayingID returned by DynamicSequence::Open
                 AkReal32 in_fPercent,                           ///< Position into the the sound, in percentage of the whole duration.
                 bool in_bSeekToNearestMarker                    ///< Snap to the marker nearest to the seek position.
                 );
  
             /// Get pause times.
             /// \return 
             /// - AK_Success if successful
             /// - AK_PlayingIDNotFound if the playing ID does not match to any open Dynamic Sequence
             AK_EXTERNAPIFUNC(AKRESULT, GetPauseTimes)(
                 AkPlayingID in_playingID,                       ///< AkPlayingID returned by DynamicSequence::Open
                 AkUInt32 &out_uTime,                            ///< If sequence is currently paused, returns time when pause started, else 0.
                 AkUInt32 &out_uDuration                         ///< Returns total pause duration since last call to GetPauseTimes, excluding the time elapsed in the current pause.
                 );
  
             /// Get currently playing item. Note that this may be different from the currently heard item
             /// when sequence is in sample-accurate mode.
             /// \return 
             /// - AK_Success if successful
             /// - AK_PlayingIDNotFound if the playing ID does not match to any open Dynamic Sequence
             AK_EXTERNAPIFUNC(AKRESULT, GetPlayingItem)(
                 AkPlayingID in_playingID,                       ///< AkPlayingID returned by DynamicSequence::Open
                 AkUniqueID & out_audioNodeID,                   ///< Returned audio node ID of playing item.
                 void *& out_pCustomInfo                         ///< Returned user data of playing item.
                 );
  
             /// Lock the Playlist for editing. Needs a corresponding UnlockPlaylist call.
             /// \return Pointer to locked Playlist if successful, NULL otherwise (in_playingID not found)
             /// 
             /// \akwarning 
             /// When opening a dynamic sequence with the callback flag \c AK_DynamicSequenceSelect, the callback is the ONLY way to determine the next item to play.
             /// \c AK::SoundEngine::DynamicSequence::LockPlaylist always returns \c NULL for dynamic sequences opened with \c AK_DynamicSequenceSelect.
             /// \endakwarning
             /// 
             /// \sa
             /// - AK::SoundEngine::DynamicSequence::UnlockPlaylist
             AK_EXTERNAPIFUNC( Playlist *, LockPlaylist )(
                 AkPlayingID in_playingID                        ///< AkPlayingID returned by DynamicSequence::Open
                 );
  
             /// Unlock the playlist.
             /// \return 
             /// - AK_Success if successful
             /// - AK_PlayingIDNotFound if the playing ID does not match to any open Dynamic Sequence
             /// \sa
             /// - AK::SoundEngine::DynamicSequence::LockPlaylist
             AK_EXTERNAPIFUNC( AKRESULT, UnlockPlaylist )(
                 AkPlayingID in_playingID                        ///< AkPlayingID returned by DynamicSequence::Open
                 );
         }
     }
 }
  
 #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)

AkCallbackFunc

AkEventCallbackFunc AkCallbackFunc

Definition: AkCallbackTypes.h:350

AK::SoundEngine::DynamicSequence::GetPlayingItem

AKSOUNDENGINE_API AKRESULT GetPlayingItem(AkPlayingID in_playingID, AkUniqueID &out_audioNodeID, void *&out_pCustomInfo)

AkDynamicSequenceType

Definition: AkEnums.h:378

AkExternalSourceArray

void * AkExternalSourceArray

Definition: AkTypedefs.h:95

AkSoundEngine.h

Definition of data structures for AkAudioObject.

Definition: AkWwiseSDKVersion.cs:31

AK::SoundEngine::DynamicSequence::PlaylistItem::audioNodeID

AkUniqueID audioNodeID

Unique ID of Audio Node.

Definition: AkDynamicSequence.h:67

AkGameObjectID

AkUInt64 AkGameObjectID

Game object ID.

Definition: AkTypedefs.h:47

AK_EXTERNAPIFUNC

#define AK_EXTERNAPIFUNC(_type, _name)

Definition: AkSoundEngineExport.h:81

AkCurveInterpolation

Curve interpolation types.

Definition: AkEnums.h:185

AK::SoundEngine::DynamicSequence::PlaylistItem::msDelay

AkTimeMs msDelay

Delay before playing this item, in milliseconds.

Definition: AkDynamicSequence.h:68

AkDynamicSequenceType_Last

@ AkDynamicSequenceType_Last

End of enum, invalid value.

Definition: AkEnums.h:381

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)

AK::SoundEngine::DynamicSequence::PlaylistItem::PlaylistItem

PlaylistItem()

AkUniqueID

AkUInt32 AkUniqueID

Unique 32-bit ID.

Definition: AkTypedefs.h:39

AK::SoundEngine::DynamicSequence::DynamicSequenceType_NormalTransition

const AkDynamicSequenceType DynamicSequenceType_NormalTransition

Definition: AkDynamicSequence.h:105

AkArray

Specific implementation of array.

Definition: AkArray.h:260

AkReal32

float AkReal32

32-bit floating point

Definition: AkNumeralTypes.h:43

AK::SoundEngine::DynamicSequence::Pause

AKSOUNDENGINE_API AKRESULT Pause(AkPlayingID in_playingID, AkTimeMs in_uTransitionDuration=0, AkCurveInterpolation in_eFadeCurve=AkCurveInterpolation_Linear)

AK::SoundEngine::DynamicSequence::DynamicSequenceType_Last

const AkDynamicSequenceType DynamicSequenceType_Last

Definition: AkDynamicSequence.h:106

AK::SoundEngine::DynamicSequence::PlaylistItem::PlaylistItem

PlaylistItem(const PlaylistItem &in_rCopy)

AK::SoundEngine::DynamicSequence::PlaylistItem::~PlaylistItem

~PlaylistItem()

AkTimeMs

AkInt32 AkTimeMs

Time in ms.

Definition: AkTypedefs.h:43

AK::SoundEngine::DynamicSequence::LockPlaylist

AKSOUNDENGINE_API Playlist * LockPlaylist(AkPlayingID in_playingID)

AkExternalSourceInfo

Definition: AkSoundEngineTypes.h:94

AK::SoundEngine::DynamicSequence::Play

AKSOUNDENGINE_API AKRESULT Play(AkPlayingID in_playingID, AkTimeMs in_uTransitionDuration=0, AkCurveInterpolation in_eFadeCurve=AkCurveInterpolation_Linear)

AkDynamicSequenceType_SampleAccurate

@ AkDynamicSequenceType_SampleAccurate

Sample accurate mode.

Definition: AkEnums.h:379

AKASSERT

#define AKASSERT(Condition)

Definition: AkAssert.h:67

AK_InsufficientMemory

@ AK_InsufficientMemory

Memory error.

Definition: AkEnums.h:62

AkArray.h

AK::SoundEngine::DynamicSequence::Open

AKSOUNDENGINE_API AkPlayingID Open(AkGameObjectID in_gameObjectID, AkUInt32 in_uFlags=0, AkCallbackFunc in_pfnCallback=NULL, void *in_pCookie=NULL, AkDynamicSequenceType in_eDynamicSequenceType=AkDynamicSequenceType_SampleAccurate)

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:83

NULL

#define NULL

Definition: AkTypedefs.h:33

AK::SoundEngine::DynamicSequence::PlaylistItem::pExternalSrcs

AkExternalSourceArray pExternalSrcs

Definition: AkDynamicSequence.h:70

AKRESULT

Definition: AkEnums.h:32

AK::SoundEngine::DynamicSequence::Seek

AKSOUNDENGINE_API AKRESULT Seek(AkPlayingID in_playingID, AkTimeMs in_iPosition, bool in_bSeekToNearestMarker)

AkCurveInterpolation_Linear