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 // AkCallback.h 00029 00030 /// \file 00031 /// Declaration of callback prototypes 00032 00033 00034 #ifndef _AK_CALLBACK_H_ 00035 #define _AK_CALLBACK_H_ 00036 00037 #include <AK/SoundEngine/Common/AkCommonDefs.h> 00038 #include <AK/SoundEngine/Common/AkMidiTypes.h> 00039 00040 namespace AK 00041 { 00042 class IAkGlobalPluginContext; 00043 class IAkMixerInputContext; 00044 class IAkMixerPluginContext; 00045 } 00046 00047 /// Type of callback. Used as a bitfield in methods AK::SoundEngine::PostEvent() and AK::SoundEngine::DynamicSequence::Open(). 00048 enum AkCallbackType 00049 { 00050 AK_EndOfEvent = 0x0001, ///< Callback triggered when reaching the end of an event. AkCallbackInfo can be cast to AkEventCallbackInfo. 00051 AK_EndOfDynamicSequenceItem = 0x0002, ///< Callback triggered when reaching the end of a dynamic sequence item. AkCallbackInfo can be cast to AkDynamicSequenceItemCallbackInfo. 00052 AK_Marker = 0x0004, ///< Callback triggered when encountering a marker during playback. AkCallbackInfo can be cast to AkMarkerCallbackInfo. 00053 AK_Duration = 0x0008, ///< Callback triggered when the duration of the sound is known by the sound engine. AkCallbackInfo can be cast to AkDurationCallbackInfo. 00054 00055 AK_SpeakerVolumeMatrix = 0x0010, ///< Callback triggered at each frame, letting the client modify the speaker volume matrix. AkCallbackInfo can be cast to AkSpeakerVolumeMatrixCallbackInfo. 00056 00057 AK_Starvation = 0x0020, ///< Callback triggered when playback skips a frame due to stream starvation. AkCallbackInfo can be cast to AkEventCallbackInfo. 00058 00059 AK_MusicPlaylistSelect = 0x0040, ///< Callback triggered when music playlist container must select the next item to play. AkCallbackInfo can be cast to AkMusicPlaylistCallbackInfo. 00060 AK_MusicPlayStarted = 0x0080, ///< Callback triggered when a "Play" or "Seek" command has been executed ("Seek" commands are issued from AK::SoundEngine::SeekOnEvent()). Applies to objects of the Interactive-Music Hierarchy only. AkCallbackInfo can be cast to AkEventCallbackInfo. 00061 00062 AK_MusicSyncBeat = 0x0100, ///< Enable notifications on Music Beat. AkCallbackInfo can be cast to AkMusicSyncCallbackInfo. 00063 AK_MusicSyncBar = 0x0200, ///< Enable notifications on Music Bar. AkCallbackInfo can be cast to AkMusicSyncCallbackInfo. 00064 AK_MusicSyncEntry = 0x0400, ///< Enable notifications on Music Entry Cue. AkCallbackInfo can be cast to AkMusicSyncCallbackInfo. 00065 AK_MusicSyncExit = 0x0800, ///< Enable notifications on Music Exit Cue. AkCallbackInfo can be cast to AkMusicSyncCallbackInfo. 00066 AK_MusicSyncGrid = 0x1000, ///< Enable notifications on Music Grid. AkCallbackInfo can be cast to AkMusicSyncCallbackInfo. 00067 AK_MusicSyncUserCue = 0x2000, ///< Enable notifications on Music Custom Cue. AkCallbackInfo can be cast to AkMusicSyncCallbackInfo. 00068 AK_MusicSyncPoint = 0x4000, ///< Enable notifications on Music switch transition synchronization point. AkCallbackInfo can be cast to AkMusicSyncCallbackInfo. 00069 AK_MusicSyncAll = 0x7f00, ///< Use this flag if you want to receive all notifications concerning AK_MusicSync registration. 00070 00071 AK_MIDIEvent = 0x10000, ///< Enable notifications for MIDI events. AkCallbackInfo can be cast to AkMIDIEventCallbackInfo. 00072 00073 AK_CallbackBits = 0xfffff, ///< Bitmask for all callback types. 00074 00075 // Not callback types, but need to be part of same bitfield for AK::SoundEngine::PostEvent(). 00076 AK_EnableGetSourcePlayPosition = 0x100000, ///< Enable play position information for use by AK::SoundEngine::GetSourcePlayPosition(). 00077 AK_EnableGetMusicPlayPosition = 0x200000, ///< Enable play position information of music objects, queried via AK::MusicEngine::GetPlayingSegmentInfo(). 00078 AK_EnableGetSourceStreamBuffering = 0x400000 ///< Enable stream buffering information for use by AK::SoundEngine::GetSourceStreamBuffering(). 00079 }; 00080 00081 /// Callback information structure used as base for all notifications handled by \ref AkCallbackFunc. 00082 /// \sa 00083 /// - AK::SoundEngine::PostEvent() 00084 /// - \ref soundengine_events 00085 struct AkCallbackInfo 00086 { 00087 void * pCookie; ///< User data, passed to PostEvent() 00088 AkGameObjectID gameObjID; ///< Game object ID 00089 }; 00090 00091 /// Callback information structure corresponding to \ref AK_EndOfEvent, \ref AK_MusicPlayStarted and \ref AK_Starvation. 00092 /// \sa 00093 /// - AK::SoundEngine::PostEvent() 00094 /// - \ref soundengine_events 00095 struct AkEventCallbackInfo : public AkCallbackInfo 00096 { 00097 AkPlayingID playingID; ///< Playing ID of Event, returned by PostEvent() 00098 AkUniqueID eventID; ///< Unique ID of Event, passed to PostEvent() 00099 }; 00100 00101 /// Callback information structure corresponding to \ref AK_MidiEvent 00102 /// \sa 00103 /// - AK::SoundEngine::PostEvent() 00104 /// - \ref soundengine_events 00105 struct AkMIDIEventCallbackInfo : public AkEventCallbackInfo 00106 { 00107 AkMIDIEvent midiEvent; ///< MIDI event triggered by event. 00108 }; 00109 00110 00111 /// Callback information structure corresponding to \ref AK_Marker. 00112 /// \sa 00113 /// - AK::SoundEngine::PostEvent() 00114 /// - \ref soundengine_events 00115 /// - \ref soundengine_markers 00116 struct AkMarkerCallbackInfo : public AkEventCallbackInfo 00117 { 00118 AkUInt32 uIdentifier; ///< Cue point identifier 00119 AkUInt32 uPosition; ///< Position in the cue point (unit: sample frames) 00120 const char* strLabel; ///< Label of the marker, read from the file 00121 }; 00122 00123 /// Callback information structure corresponding to \ref AK_Duration. 00124 /// \sa 00125 /// - AK::SoundEngine::PostEvent() 00126 /// - \ref soundengine_events 00127 struct AkDurationCallbackInfo : public AkEventCallbackInfo 00128 { 00129 AkReal32 fDuration; ///< Duration of the sound (unit: milliseconds) 00130 AkReal32 fEstimatedDuration; ///< Estimated duration of the sound depending on source settings such as pitch. (unit: milliseconds) 00131 AkUniqueID audioNodeID; ///< Audio Node ID of playing item 00132 AkUniqueID mediaID; ///< Media ID of playing item. (corresponds to 'ID' attribute of 'File' element in SoundBank metadata file) 00133 bool bStreaming; ///< True if source is streaming, false otherwise. 00134 }; 00135 00136 /// Callback information structure corresponding to \ref AK_EndOfDynamicSequenceItem. 00137 /// \sa 00138 /// - AK::SoundEngine::PostEvent() 00139 /// - AK::SoundEngine::DynamicSequence::Open() 00140 /// - \ref soundengine_events 00141 struct AkDynamicSequenceItemCallbackInfo : public AkCallbackInfo 00142 { 00143 AkPlayingID playingID; ///< Playing ID of Dynamic Sequence, returned by AK::SoundEngine:DynamicSequence::Open() 00144 AkUniqueID audioNodeID; ///< Audio Node ID of finished item 00145 void* pCustomInfo; ///< Custom info passed to the DynamicSequence::Open function 00146 }; 00147 00148 /// Callback information structure corresponding to \ref AK_SpeakerVolumeMatrix, and passed to callbacks registered in RegisterBusVolumeCallback() 00149 /// or PostEvent() with AK_SpeakerVolumeMatrix. These callbacks are called at every audio frame for every connection from an input (voice 00150 /// or bus) to an output bus (standard or auxiliary), at the point when an input signal is about to be mixed into a mixing bus, but just before 00151 /// having been scaled in accordance to volumes authored in Wwise. The volumes are passed via this structure as pointers because they can be modified 00152 /// in the callbacks. They are factored into two linear values ([0..1]): a common base value (pfBaseVolume), that is channel-agnostic and represents 00153 /// the collapsed gain of all volume changes in Wwise (sliders, actions, RTPC, attenuations, ...), and a matrix of gains per input/output channel, 00154 /// which depends on spatialization. Use the methods of AK::SpeakerVolumes::Matrix, defined in AkCommonDefs.h, to perform operations on them. 00155 /// Access each input channel of the volumes matrix with AK::SpeakerVolumes::Matrix::GetChannel(), passing it the input and output channel configuration. 00156 /// Then, you may access each element of the output vector using the standard bracket [] operator. See AK::SpeakerVolumes for more details. 00157 /// It is crucial that the processing done in the callback be lightweight and non-blocking. 00158 /// \sa 00159 /// - \ref goingfurther_speakermatrixcallback 00160 /// - AK::SoundEngine::PostEvent() 00161 /// - \ref soundengine_events 00162 /// - AK::SoundEngine::RegisterBusVolumeCallback() 00163 struct AkSpeakerVolumeMatrixCallbackInfo : public AkEventCallbackInfo 00164 { 00165 AK::SpeakerVolumes::MatrixPtr pVolumes; ///< Pointer to volume matrix describing the contribution of each source channel to destination channels. Use methods of AK::SpeakerVolumes::Matrix to interpret them. 00166 AkChannelConfig inputConfig; ///< Channel configuration of the voice/bus. 00167 AkChannelConfig outputConfig; ///< Channel configuration of the output bus. 00168 AkReal32 * pfBaseVolume; ///< Base volume, common to all channels. 00169 AkReal32 * pfEmitterListenerVolume; ///< Emitter-listener pair-specific gain. When there are multiple emitter-listener pairs, this volume equals 1, and pair gains are applied directly on the channel volume matrix pVolumes. 00170 AK::IAkMixerInputContext * pContext; ///< Context of the current voice/bus about to be mixed into the output bus with specified base volume and volume matrix. 00171 AK::IAkMixerPluginContext * pMixerContext; ///< Output mixing bus context. Use it to access a few useful panning and mixing services, as well as the ID of the output bus. NULL if pContext is the master audio bus. 00172 }; 00173 00174 /// Callback information structure corresponding to \ref AK_MusicPlaylistSelect. 00175 /// Called when a music playlist container must select its next item to play. 00176 /// The members uPlaylistSelection and uPlaylistItemDone are set by the sound 00177 /// engine before the callback function call. They are set to the next item 00178 /// selected by the sound engine. They are to be modified by the callback 00179 /// function if the selection is to be changed. 00180 /// \sa 00181 /// - \ref soundengine_events 00182 /// - AK::SoundEngine::PostEvent() 00183 /// - \ref soundengine_music_callbacks 00184 struct AkMusicPlaylistCallbackInfo : public AkEventCallbackInfo 00185 { 00186 AkUniqueID playlistID; ///< ID of playlist node 00187 AkUInt32 uNumPlaylistItems; ///< Number of items in playlist node (may be segments or other playlists) 00188 AkUInt32 uPlaylistSelection; ///< Selection: set by sound engine, modified by callback function (if not in range 0 <= uPlaylistSelection < uNumPlaylistItems then ignored). 00189 AkUInt32 uPlaylistItemDone; ///< Playlist node done: set by sound engine, modified by callback function (if set to anything but 0 then the current playlist item is done, and uPlaylistSelection is ignored) 00190 }; 00191 00192 /// Structure used to query info on active playing segments. 00193 struct AkSegmentInfo 00194 { 00195 AkTimeMs iCurrentPosition; ///< Current position of the segment, relative to the Entry Cue, in milliseconds. Range is [-iPreEntryDuration, iActiveDuration+iPostExitDuration]. 00196 AkTimeMs iPreEntryDuration; ///< Duration of the pre-entry region of the segment, in milliseconds. 00197 AkTimeMs iActiveDuration; ///< Duration of the active region of the segment (between the Entry and Exit Cues), in milliseconds. 00198 AkTimeMs iPostExitDuration; ///< Duration of the post-exit region of the segment, in milliseconds. 00199 AkTimeMs iRemainingLookAheadTime;///< Number of milliseconds remaining in the "looking-ahead" state of the segment, when it is silent but streamed tracks are being prefetched. 00200 AkReal32 fBeatDuration; ///< Beat Duration in seconds. 00201 AkReal32 fBarDuration; ///< Bar Duration in seconds. 00202 AkReal32 fGridDuration; ///< Grid duration in seconds. 00203 AkReal32 fGridOffset; ///< Grid offset in seconds. 00204 }; 00205 00206 /// Callback information structure corresponding to \ref AK_MusicSyncEntry, \ref AK_MusicSyncBeat, \ref AK_MusicSyncBar, \ref AK_MusicSyncExit, \ref AK_MusicSyncGrid, \ref AK_MusicSyncPoint and \ref AK_MusicSyncUserCue. 00207 /// If you need the Tempo, you can compute it using the fBeatDuration 00208 /// Tempo (beats per minute) = 60/fBeatDuration 00209 /// \sa 00210 /// - \ref soundengine_events 00211 /// - AK::SoundEngine::PostEvent() 00212 /// - \ref soundengine_music_callbacks 00213 struct AkMusicSyncCallbackInfo : public AkCallbackInfo 00214 { 00215 AkPlayingID playingID; ///< Playing ID of Event, returned by PostEvent() 00216 AkSegmentInfo segmentInfo; ///< Segment information corresponding to the segment triggering this callback. 00217 AkCallbackType musicSyncType; ///< Would be either \ref AK_MusicSyncEntry, \ref AK_MusicSyncBeat, \ref AK_MusicSyncBar, \ref AK_MusicSyncExit, \ref AK_MusicSyncGrid, \ref AK_MusicSyncPoint or \ref AK_MusicSyncUserCue. 00218 char * pszUserCueName; ///< Cue name (UTF-8 string). Set for notifications AK_MusicSyncUserCue. NULL if cue has no name. 00219 }; 00220 00221 /// Function called on completion of an event, or when a marker is reached. 00222 /// \param in_eType Type of callback. 00223 /// \param in_pCallbackInfo Pointer to structure containing callback information. This pointer is invalidated as soon as the callback function returns. 00224 /// \remarks An event is considered completed once all of its actions have been executed and all the playbacks in this events are terminated. 00225 /// \remarks This callback is executed from the audio processing thread. The processing time in the callback function should be minimal. Having too much processing time could result in slowing down the audio processing. 00226 /// \remarks Before waiting on an \ref AK_EndOfEvent, make sure that the event is going to end. 00227 /// Some events can be continuously playing or infinitely looping, and the callback will not occur unless a specific stop event is sent to terminate the event. 00228 /// \sa 00229 /// - AK::SoundEngine::PostEvent() 00230 /// - AK::SoundEngine::DynamicSequence::Open() 00231 /// - \ref soundengine_events 00232 /// - \ref soundengine_markers 00233 /// - \ref soundengine_music_callbacks 00234 AK_CALLBACK( void, AkCallbackFunc )( 00235 AkCallbackType in_eType, ///< Callback type. 00236 AkCallbackInfo* in_pCallbackInfo ///< Structure containing desired information. You can cast it to the proper sub-type, depending on the callback type. 00237 ); 00238 00239 /// Function called on at every audio frame for the specified registered busses. 00240 /// \sa 00241 /// - AkSpeakerVolumeMatrixCallbackInfo 00242 /// - AK::SoundEngine::RegisterBusVolumeCallback() 00243 /// - \ref goingfurther_speakermatrixcallback 00244 AK_CALLBACK( void, AkBusCallbackFunc )( 00245 AkSpeakerVolumeMatrixCallbackInfo* in_pCallbackInfo ///< Structure containing desired bus information. 00246 ); 00247 00248 /// Function called on at every audio frame for the specified registered busses, just after metering has been computed. 00249 /// \sa 00250 /// - AK::SoundEngine::RegisterBusMeteringCallback() 00251 /// - AK::IAkMetering 00252 /// - \ref goingfurther_speakermatrixcallback 00253 AK_CALLBACK( void, AkBusMeteringCallbackFunc )( 00254 AK::IAkMetering * in_pMetering, ///< AK::IAkMetering interface for retrieving metering information. 00255 AkChannelConfig in_channelConfig, ///< Channel configuration of the bus. 00256 AkMeteringFlags in_eMeteringFlags ///< Metering flags that were asked for in RegisterBusMeteringCallback(). You may only access corresponding meter values from in_pMeteringInfo. Others will fail. 00257 ); 00258 00259 /// Callback prototype used with asynchronous bank load/unload requests. 00260 /// This function is called when the bank request has been processed 00261 /// and indicates if it was successfully executed or if an error occurred. 00262 /// \param in_bankID Identifier of the bank that was explicitly loaded/unloaded. 00263 /// In the case of PrepareEvent() or PrepareGameSyncs(), this value contains 00264 /// the AkUniqueID of the event/game sync that was prepared/unprepared, if the array contained only 00265 /// one element. Otherwise, in_bankID equals AK_INVALID_UNIQUE_ID. 00266 /// \param in_pInMemoryBankPtr Value returned when the unloaded bank was loaded using an in memory location 00267 /// \param in_eLoadResult Result of the requested action. 00268 /// - AK_Success: Load or unload successful. 00269 /// - AK_IDNotFound: At least one of the event/game sync identifiers passed to PrepareEvent() or PrepareGameSyncs() does not exist. 00270 /// - AK_InsufficientMemory: Insufficient memory to store bank data. 00271 /// - AK_BankReadError: I/O error. 00272 /// - AK_WrongBankVersion: Invalid bank version: make sure the version of Wwise that 00273 /// you used to generate the SoundBanks matches that of the SDK you are currently using. 00274 /// - AK_InvalidFile: File specified could not be opened. 00275 /// - AK_InvalidParameter: Invalid parameter. 00276 /// - AK_Fail: Load or unload failed for any other reason. (Most likely small allocation failure) 00277 /// \param in_memPoolId ID of the memory pool in which the bank was explicitly loaded/unloaded. 00278 /// AK_DEFAULT_POOL_ID is returned whenever this callback is issued from an implicit bank load (PrepareEvent(), PrepareGameSyncs()), 00279 /// the bank memory was managed internally, or an error occurred. 00280 /// \param in_pCookie Optional cookie that was passed to the bank request. 00281 /// \remarks This callback is executed from the bank thread. The processing time in the callback function should be minimal. Having too much processing time could slow down the bank loading process. 00282 /// \sa 00283 /// - AK::SoundEngine::LoadBank() 00284 /// - AK::SoundEngine::UnloadBank() 00285 /// - AK::SoundEngine::PrepareEvent() 00286 /// - AK::SoundEngine::PrepareGameSyncs() 00287 /// - \ref soundengine_banks 00288 AK_CALLBACK( void, AkBankCallbackFunc )( 00289 AkUInt32 in_bankID, 00290 const void * in_pInMemoryBankPtr, 00291 AKRESULT in_eLoadResult, 00292 AkMemPoolId in_memPoolId, 00293 void * in_pCookie 00294 ); 00295 00296 /// Bit field of various locations in the audio processing loop where the game can be called back. 00297 enum AkGlobalCallbackLocation 00298 { 00299 AkGlobalCallbackLocation_Register = (1 << 0), ///< Right after successful registration of callback/plugin. Typically used by plugins along with AkGlobalCallbackLocation_Term for allocating memory for the lifetime of the sound engine. 00300 00301 AkGlobalCallbackLocation_Begin = (1 << 1), ///< Start of audio processing. The number of frames about to be rendered depends on the sink/end-point and can be zero. 00302 00303 AkGlobalCallbackLocation_PreProcessMessageQueueForRender = (1 << 2), ///< Start of frame rendering, before having processed game messages. 00304 AkGlobalCallbackLocation_PostMessagesProcessed = (1 << 3), ///< After one or more messages have been processed, but before updating game object and listener positions internally. 00305 AkGlobalCallbackLocation_BeginRender = (1 << 4), ///< Start of frame rendering, after having processed game messages. 00306 AkGlobalCallbackLocation_EndRender = (1 << 5), ///< End of frame rendering. 00307 00308 AkGlobalCallbackLocation_End = (1 << 6), ///< End of audio processing. 00309 00310 AkGlobalCallbackLocation_Term = (1 << 7), ///< Sound engine termination. 00311 00312 // IMPORTANT: Keep in sync with number of locations. 00313 AkGlobalCallbackLocation_Num = 8 ///< Total number of global callback locations. 00314 }; 00315 00316 /// Callback prototype used for global callback registration. 00317 /// This callback may be called from various locations within the audio processing loop. The exact location from which it is called is passed in in_eLocation, and corresponds to one of the values 00318 /// that were passed to RegisterGlobalCallback(). See the possible values of AkGlobalCallbackLocation for more details about the available locations. 00319 /// \remarks This callback is normally executed from the main audio thread. The processing time in the callback function should be minimal. Having too much processing time could cause voice starvation. 00320 /// \sa 00321 /// - AK::SoundEngine::RegisterGlobalCallback() 00322 /// - AK::SoundEngine::UnregisterGlobalCallback() 00323 AK_CALLBACK( void, AkGlobalCallbackFunc )( 00324 AK::IAkGlobalPluginContext * in_pContext, ///< Engine context. 00325 AkGlobalCallbackLocation in_eLocation, ///< Location where this callback is fired. 00326 void * in_pCookie ///< User cookie passed to AK::SoundEngine::RegisterGlobalCallback(). 00327 ); 00328 00329 #endif // _AK_CALLBACK_H_ 00330
Questions? Problems? Need more info? Contact us, and we can help!
Visit our Support pageRegister your project and we'll help you get started with no strings attached!
Get started with Wwise