バージョン

menu_open
Wwise SDK 2024.1.1
AkCallback.h
[詳解]
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) 2024 Audiokinetic Inc.
25 *******************************************************************************/
26 
27 // AkCallback.h
28 
29 /// \file
30 /// Declaration of callback prototypes
31 
32 
33 #ifndef _AK_CALLBACK_H_
34 #define _AK_CALLBACK_H_
35 
38 
39 namespace AK
40 {
41  class IAkGlobalPluginContext;
42  class IAkMixerInputContext;
43  class IAkMixerPluginContext;
44 }
45 
46 /// Type of callback. Used as a bitfield in methods AK::SoundEngine::PostEvent() and AK::SoundEngine::DynamicSequence::Open().
48 {
49  AK_EndOfEvent = 0x0001, ///< Callback triggered when reaching the end of an event. AkCallbackInfo can be cast to AkEventCallbackInfo.
50  AK_EndOfDynamicSequenceItem = 0x0002, ///< Callback triggered when reaching the end of a dynamic sequence item. AkCallbackInfo can be cast to AkDynamicSequenceItemCallbackInfo.
51  AK_Marker = 0x0004, ///< Callback triggered when encountering a marker during playback. AkCallbackInfo can be cast to AkMarkerCallbackInfo.
52  AK_Duration = 0x0008, ///< Callback triggered when the duration of the sound is known by the sound engine. AkCallbackInfo can be cast to AkDurationCallbackInfo.
53 
54  AK_SpeakerVolumeMatrix = 0x0010, ///< Callback triggered at each frame, letting the client modify the speaker volume matrix. AkCallbackInfo can be cast to AkSpeakerVolumeMatrixCallbackInfo.
55 
56  AK_Starvation = 0x0020, ///< Callback triggered when playback skips a frame due to stream starvation. AkCallbackInfo can be cast to AkEventCallbackInfo.
57 
58  AK_MusicPlaylistSelect = 0x0040, ///< Callback triggered when music playlist container must select the next item to play. AkCallbackInfo can be cast to AkMusicPlaylistCallbackInfo.
59  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.
60 
61  AK_MusicSyncBeat = 0x0100, ///< Enable notifications on Music Beat. AkCallbackInfo can be cast to AkMusicSyncCallbackInfo.
62  AK_MusicSyncBar = 0x0200, ///< Enable notifications on Music Bar. AkCallbackInfo can be cast to AkMusicSyncCallbackInfo.
63  AK_MusicSyncEntry = 0x0400, ///< Enable notifications on Music Entry Cue. AkCallbackInfo can be cast to AkMusicSyncCallbackInfo.
64  AK_MusicSyncExit = 0x0800, ///< Enable notifications on Music Exit Cue. AkCallbackInfo can be cast to AkMusicSyncCallbackInfo.
65  AK_MusicSyncGrid = 0x1000, ///< Enable notifications on Music Grid. AkCallbackInfo can be cast to AkMusicSyncCallbackInfo.
66  AK_MusicSyncUserCue = 0x2000, ///< Enable notifications on Music Custom Cue. AkCallbackInfo can be cast to AkMusicSyncCallbackInfo.
67  AK_MusicSyncPoint = 0x4000, ///< Enable notifications on Music switch transition synchronization point. AkCallbackInfo can be cast to AkMusicSyncCallbackInfo.
68 
69  AK_MIDIEvent = 0x8000, ///< Enable notifications for MIDI events. AkCallbackInfo can be cast to AkMIDIEventCallbackInfo.
70 
71  AK_Callback_Last = 0x10000, ///< Last calblack unused bit, invalid value.
72 
73  //A few useful bitmasks.
74  AK_MusicSyncAll = 0x7f00, ///< Use this flag if you want to receive all notifications concerning AK_MusicSync registration.
75  AK_CallbackBits = 0xffff, ///< Bitmask for all callback types.
76 
77  // Not callback types, but need to be part of same bitfield for AK::SoundEngine::PostEvent().
78  AK_EnableGetSourcePlayPosition = 0x100000, ///< Enable play position information for use by AK::SoundEngine::GetSourcePlayPosition().
79  AK_EnableGetMusicPlayPosition = 0x200000, ///< Enable play position information of music objects, queried via AK::MusicEngine::GetPlayingSegmentInfo().
80  AK_EnableGetSourceStreamBuffering = 0x400000,///< Enable stream buffering information for use by AK::SoundEngine::GetSourceStreamBuffering().
81 
82  AK_SourceInfo_Last = 0x800000, ///< Last source info enable bit, invalid value.
83 };
84 
85 /// Callback information structure used as base for all notifications handled by \ref AkCallbackFunc.
86 /// \sa
87 /// - AK::SoundEngine::PostEvent()
88 /// - \ref soundengine_events
90 {
91  void * pCookie; ///< User data, passed to PostEvent()
92  AkGameObjectID gameObjID; ///< Game object ID
93 };
94 
95 /// Callback information structure corresponding to \ref AK_EndOfEvent, \ref AK_MusicPlayStarted and \ref AK_Starvation.
96 /// \sa
97 /// - AK::SoundEngine::PostEvent()
98 /// - \ref soundengine_events
100 {
101  AkPlayingID playingID; ///< Playing ID of Event, returned by PostEvent()
102  AkUniqueID eventID; ///< Unique ID of Event, passed to PostEvent()
103 };
104 
105 /// Callback information structure corresponding to \ref AkCallbackType::AK_MIDIEvent
106 /// \sa
107 /// - AK::SoundEngine::PostEvent()
108 /// - \ref soundengine_events
110 {
111  AkMIDIEvent midiEvent; ///< MIDI event triggered by event.
112 };
113 
114 
115 /// Callback information structure corresponding to \ref AK_Marker.
116 /// \sa
117 /// - AK::SoundEngine::PostEvent()
118 /// - \ref soundengine_events
119 /// - \ref soundengine_markers
121 {
122  AkUInt32 uIdentifier; ///< Cue point identifier
123  AkUInt32 uPosition; ///< Position in the cue point (unit: sample frames)
124  const char* strLabel; ///< Label of the marker (null-terminated)
125  AkUInt32 uLabelSize; ///< Size of the label string (including the terminating null character)
126 };
127 
128 /// Callback information structure corresponding to \ref AK_Duration.
129 /// \sa
130 /// - AK::SoundEngine::PostEvent()
131 /// - \ref soundengine_events
133 {
134  AkReal32 fDuration; ///< Duration of the sound (unit: milliseconds)
135  AkReal32 fEstimatedDuration; ///< Estimated duration of the sound depending on source settings such as pitch. (unit: milliseconds)
136  AkUniqueID audioNodeID; ///< Audio Node ID of playing item
137  AkUniqueID mediaID; ///< Media ID of playing item. (corresponds to 'ID' attribute of 'File' element in SoundBank metadata file)
138  bool bStreaming; ///< True if source is streaming, false otherwise.
139 };
140 
141 /// Callback information structure corresponding to \ref AK_EndOfDynamicSequenceItem.
142 /// \sa
143 /// - AK::SoundEngine::PostEvent()
144 /// - AK::SoundEngine::DynamicSequence::Open()
145 /// - \ref soundengine_events
147 {
148  AkPlayingID playingID; ///< Playing ID of Dynamic Sequence, returned by AK::SoundEngine:DynamicSequence::Open()
149  AkUniqueID audioNodeID; ///< Audio Node ID of finished item
150  void* pCustomInfo; ///< Custom info passed to the DynamicSequence::Open function
151 };
152 
153 /// Callback information structure corresponding to \ref AK_SpeakerVolumeMatrix, and passed to callbacks registered in RegisterBusVolumeCallback()
154 /// or PostEvent() with AK_SpeakerVolumeMatrix. These callbacks are called at every audio frame for every connection from an input (voice
155 /// 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
156 /// having been scaled in accordance to volumes authored in Wwise. The volumes are passed via this structure as pointers because they can be modified
157 /// in the callbacks. They are factored into two linear values ([0..1]): a common base value (pfBaseVolume), that is channel-agnostic and represents
158 /// the collapsed gain of all volume changes in Wwise (sliders, actions, RTPC, attenuations, ...), and a matrix of gains per input/output channel,
159 /// which depends on spatialization. Use the methods of AK::SpeakerVolumes::Matrix, defined in AkCommonDefs.h, to perform operations on them.
160 /// Access each input channel of the volumes matrix with AK::SpeakerVolumes::Matrix::GetChannel(), passing it the input and output channel configuration.
161 /// Then, you may access each element of the output vector using the standard bracket [] operator. See AK::SpeakerVolumes for more details.
162 /// It is crucial that the processing done in the callback be lightweight and non-blocking.
163 /// \sa
164 /// - \ref goingfurther_speakermatrixcallback
165 /// - AK::SoundEngine::PostEvent()
166 /// - \ref soundengine_events
167 /// - AK::SoundEngine::RegisterBusVolumeCallback()
169 {
170  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.
171  AkChannelConfig inputConfig; ///< Channel configuration of the voice/bus.
172  AkChannelConfig outputConfig; ///< Channel configuration of the output bus.
173  AkReal32 * pfBaseVolume; ///< Base volume, common to all channels.
174  AkReal32 * pfEmitterListenerVolume; ///< Emitter-listener pair-specific gain. When there are multiple emitter-listener pairs, this volume is set to that of the loudest pair, and the relative gain of other pairs is applied directly on the channel volume matrix pVolumes.
175  AK::IAkMixerInputContext * pContext; ///< Context of the current voice/bus about to be mixed into the output bus with specified base volume and volume matrix.
176  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.
177 };
178 
179 /// Callback information structure allowing to query signal metering on busses, at each frame, after having mixed all their inputs and processed their effects.
180 /// Register the callback using AK::SoundEngine::RegisterBusMeteringCallback.
182 {
183  AK::AkMetering* pMetering; ///< Struct containing metering information.
184  AkChannelConfig channelConfig; ///< Channel configuration of the bus.
185  AkMeteringFlags eMeteringFlags; ///< Metering flags that were asked for in RegisterBusMeteringCallback(). You may only access corresponding meter values from in_pMeteringInfo. Others will fail.
186 };
187 
188 /// Callback information structure allowing to query signal metering on output devices, at each frame.
189 /// Register the callback using AK::SoundEngine::RegisterOutputDeviceMeteringCallback.
191 {
192  AK::AkMetering * pMainMixMetering; ///< Metering information for the main mix
193  AkChannelConfig mainMixConfig; ///< Channel configuration of the main mix
194  AK::AkMetering * pPassthroughMetering; ///< Metering information for the passthrough mix (if any; will be null otherwise)
195  AkChannelConfig passthroughMixConfig; ///< Channel configuration of the passthrough mix (if any; will be invalid otherwise)
196  AkUInt32 uNumSystemAudioObjects; ///< Number of System Audio Objects going out of the output device
197  AK::AkMetering ** ppSystemAudioObjectMetering; ///< Metering information for each System Audio Object (number of elements is equal to uNumSystemAudioObjects)
198  AkMeteringFlags eMeteringFlags; ///< Metering flags that were asked for in RegisterOutputDeviceMeteringCallback(). You may only access corresponding meter values from the metering objects. Others will fail.
199 };
200 
201 /// Callback information structure corresponding to \ref AK_MusicPlaylistSelect.
202 /// Called when a music playlist container must select its next item to play.
203 /// The members uPlaylistSelection and uPlaylistItemDone are set by the sound
204 /// engine before the callback function call. They are set to the next item
205 /// selected by the sound engine. They are to be modified by the callback
206 /// function if the selection is to be changed.
207 /// \sa
208 /// - \ref soundengine_events
209 /// - AK::SoundEngine::PostEvent()
210 /// - \ref soundengine_music_callbacks
212 {
213  AkUniqueID playlistID; ///< ID of playlist node
214  AkUInt32 uNumPlaylistItems; ///< Number of items in playlist node (may be segments or other playlists)
215  AkUInt32 uPlaylistSelection; ///< Selection: set by sound engine, modified by callback function (if not in range 0 <= uPlaylistSelection < uNumPlaylistItems then ignored).
216  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)
217 };
218 
219 /// Structure used to query info on active playing segments.
221 {
222  AkTimeMs iCurrentPosition; ///< Current position of the segment, relative to the Entry Cue, in milliseconds. Range is [-iPreEntryDuration, iActiveDuration+iPostExitDuration].
223  AkTimeMs iPreEntryDuration; ///< Duration of the pre-entry region of the segment, in milliseconds.
224  AkTimeMs iActiveDuration; ///< Duration of the active region of the segment (between the Entry and Exit Cues), in milliseconds.
225  AkTimeMs iPostExitDuration; ///< Duration of the post-exit region of the segment, in milliseconds.
226  AkTimeMs iRemainingLookAheadTime;///< Number of milliseconds remaining in the "looking-ahead" state of the segment, when it is silent but streamed tracks are being prefetched.
227  AkReal32 fBeatDuration; ///< Beat Duration in seconds.
228  AkReal32 fBarDuration; ///< Bar Duration in seconds.
229  AkReal32 fGridDuration; ///< Grid duration in seconds.
230  AkReal32 fGridOffset; ///< Grid offset in seconds.
231 };
232 
233 /// 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.
234 /// If you need the Tempo, you can compute it using the fBeatDuration
235 /// Tempo (beats per minute) = 60/fBeatDuration
236 /// \sa
237 /// - \ref soundengine_events
238 /// - AK::SoundEngine::PostEvent()
239 /// - \ref soundengine_music_callbacks
241 {
242  AkPlayingID playingID; ///< Playing ID of Event, returned by PostEvent()
243  AkSegmentInfo segmentInfo; ///< Segment information corresponding to the segment triggering this callback.
244  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.
245  char * pszUserCueName; ///< Cue name (UTF-8 string). Set for notifications AK_MusicSyncUserCue. NULL if cue has no name.
246 };
247 
248 /// Resources data summary structure containing general information about the system
250 {
251  AkReal32 totalCPU; ///< Pourcentage of the cpu time used for processing audio. Please note that the numbers may add up when using multiple threads.
252  AkReal32 pluginCPU; ///< Pourcentage of the cpu time used by plugin processing. Please note that the numbers may add up when using multiple threads.
253  AkUInt32 physicalVoices; ///< Number of active physical voices
254  AkUInt32 virtualVoices; ///< Number of active virtual voices
255  AkUInt32 totalVoices; ///< Number of active physical and virtual voices
256  AkUInt32 nbActiveEvents; ///< Number of events triggered at a certain time
257 };
258 
259 /// Function called on completion of an event, or when a marker is reached.
260 /// \param in_eType Type of callback.
261 /// \param in_pCallbackInfo Pointer to structure containing callback information. This pointer is invalidated as soon as the callback function returns.
262 /// \remarks An event is considered completed once all of its actions have been executed and all the playbacks in this events are terminated.
263 /// \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.
264 /// \remarks Before waiting on an \ref AK_EndOfEvent, make sure that the event is going to end.
265 /// 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.
266 /// \sa
267 /// - AK::SoundEngine::PostEvent()
268 /// - AK::SoundEngine::DynamicSequence::Open()
269 /// - \ref soundengine_events
270 /// - \ref soundengine_markers
271 /// - \ref soundengine_music_callbacks
273  AkCallbackType in_eType, ///< Callback type.
274  AkCallbackInfo* in_pCallbackInfo ///< Structure containing desired information. You can cast it to the proper sub-type, depending on the callback type.
275  );
276 
277 /// Function called on at every audio frame for the specified registered busses.
278 /// \sa
279 /// - AkSpeakerVolumeMatrixCallbackInfo
280 /// - AK::SoundEngine::RegisterBusVolumeCallback()
281 /// - \ref goingfurther_speakermatrixcallback
283  AkSpeakerVolumeMatrixCallbackInfo* in_pCallbackInfo ///< Structure containing desired bus information.
284  );
285 
286 /// Function called on at every audio frame for the specified registered busses, just after metering has been computed.
287 /// \sa
288 /// - AK::SoundEngine::RegisterBusMeteringCallback()
289 /// - AK::AkMetering
290 /// - AkBusMeteringCallbackInfo
291 /// - \ref goingfurther_speakermatrixcallback
293  AkBusMeteringCallbackInfo * in_pCallbackInfo ///< Structure containing desired bus information.
294  );
295 
296 /// Function called on at every audio frame for the specified registered output devices, just after metering has been computed.
297 /// \sa
298 /// - AK::SoundEngine::RegisterOutputDeviceMeteringCallback()
299 /// - AK::AkMetering
300 /// - AkOutputDeviceMeteringCallbackInfo
301 /// - \ref goingfurther_speakermatrixcallback
303  AkOutputDeviceMeteringCallbackInfo * in_pCallbackInfo ///< Structure containing desired output device information.
304  );
305 
306 /// Callback prototype used with asynchronous bank load/unload requests.
307 /// This function is called when the bank request has been processed
308 /// and indicates if it was successfully executed or if an error occurred.
309 /// \param in_bankID Identifier of the bank that was explicitly loaded/unloaded.
310 /// In the case of PrepareEvent() or PrepareGameSyncs(), this value contains
311 /// the AkUniqueID of the event/game sync that was prepared/unprepared, if the array contained only
312 /// one element. Otherwise, in_bankID equals AK_INVALID_UNIQUE_ID.
313 /// \param in_pInMemoryBankPtr Value returned when the unloaded bank was loaded using an in memory location
314 /// \param in_eLoadResult Result of the requested action.
315 /// - AK_Success: Load or unload successful.
316 /// - AK_IDNotFound: At least one of the event/game sync identifiers passed to PrepareEvent() or PrepareGameSyncs() does not exist.
317 /// - AK_InsufficientMemory: Insufficient memory to store bank data.
318 /// - AK_BankReadError: I/O error.
319 /// - AK_WrongBankVersion: Invalid bank version: make sure the version of Wwise that
320 /// you used to generate the SoundBanks matches that of the SDK you are currently using.
321 /// - AK_InvalidFile: File specified could not be opened.
322 /// - AK_InvalidParameter: Invalid parameter.
323 /// - AK_Fail: Load or unload failed for any other reason. (Most likely small allocation failure)
324 /// \param in_pCookie Optional cookie that was passed to the bank request.
325 /// \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.
326 /// \sa
327 /// - AK::SoundEngine::LoadBank()
328 /// - AK::SoundEngine::UnloadBank()
329 /// - AK::SoundEngine::PrepareEvent()
330 /// - AK::SoundEngine::PrepareGameSyncs()
331 /// - \ref soundengine_banks
333  AkUInt32 in_bankID,
334  const void * in_pInMemoryBankPtr,
335  AKRESULT in_eLoadResult,
336  void * in_pCookie
337  );
338 
339 /// Bit field of various locations in the audio processing loop where the game can be called back.
341 {
342  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.
343 
344  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.
345 
346  AkGlobalCallbackLocation_PreProcessMessageQueueForRender = (1 << 2), ///< Start of frame rendering, before having processed game messages.
347  AkGlobalCallbackLocation_PostMessagesProcessed = (1 << 3), ///< After one or more messages have been processed, but before updating game object and listener positions internally.
348  AkGlobalCallbackLocation_BeginRender = (1 << 4), ///< Start of frame rendering, after having processed game messages.
349  AkGlobalCallbackLocation_EndRender = (1 << 5), ///< End of frame rendering.
350 
351  AkGlobalCallbackLocation_End = (1 << 6), ///< End of audio processing.
352 
353  AkGlobalCallbackLocation_Term = (1 << 7), ///< Sound engine termination.
354 
355  AkGlobalCallbackLocation_Monitor = (1 << 8), ///< Send monitor data
356  AkGlobalCallbackLocation_MonitorRecap = (1 << 9), ///< Send monitor data connection to recap.
357 
358  AkGlobalCallbackLocation_Init = (1 << 10), ///< Sound engine initialization.
359 
360  AkGlobalCallbackLocation_Suspend = (1 << 11), ///< Sound engine suspension through \ref AK::SoundEngine::Suspend
361  AkGlobalCallbackLocation_WakeupFromSuspend = (1 << 12), ///< Sound engine awakening through \ref AK::SoundEngine::WakeupFromSuspend
362 
363  AkGlobalCallbackLocation_ProfilerConnect = (1 << 13), ///< Wwise Profiler has connected to the game.
364  AkGlobalCallbackLocation_ProfilerDisconnect = (1 << 14), ///< Wwise Profiler has disconnected from the game.
365 
366 
367  // IMPORTANT: Keep in sync with number of locations.
368  AkGlobalCallbackLocation_Num = 15 ///< Total number of global callback locations.
369 };
370 
371 /// Callback prototype used for global callback registration.
372 /// 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
373 /// that were passed to RegisterGlobalCallback(). See the possible values of AkGlobalCallbackLocation for more details about the available locations.
374 /// \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.
375 /// \sa
376 /// - AK::SoundEngine::RegisterGlobalCallback()
377 /// - AK::SoundEngine::UnregisterGlobalCallback()
379  AK::IAkGlobalPluginContext * in_pContext, ///< Engine context.
380  AkGlobalCallbackLocation in_eLocation, ///< Location where this callback is fired.
381  void * in_pCookie ///< User cookie passed to AK::SoundEngine::RegisterGlobalCallback().
382  );
383 
384 
386  const AkResourceMonitorDataSummary * in_pdataSummary ///< Data summary passed to the function registered using AK::SoundEngine::RegisterResourceMonitorCallback().
387  );
388 
389 namespace AK
390 {
392  {
393  AkAudioDeviceEvent_Initialization, ///< Sent after an Audio Device has initialized. Initialization might have failed, check the AKRESULT.
394  AkAudioDeviceEvent_Removal, ///< Audio device was removed through explicit call (AK::SoundEngine::RemoveOutput or AK::SoundEngine::Term)
395  AkAudioDeviceEvent_SystemRemoval, ///< Audio device was removed because of a system event (disconnection), hardware or driver problem. Check the AKRESULT when called through AkDeviceStatusCallbackFunc, it may give more context.
396  AkAudioDeviceEvent_Last ///< End of enum, invalid value.
397  };
398 
399  /// Callback for Audio Device status changes.
400  /// \sa AK::SoundEngine::AddOutput
402  AK::IAkGlobalPluginContext * in_pContext, ///< Engine context.
403  AkUniqueID in_idAudioDeviceShareset, ///< The audio device shareset attached, as passed to AK::SoundEngine::AddOutput or AK::SoundEngine::Init
404  AkUInt32 in_idDeviceID, ///< The audio device specific id, as passed to AK::SoundEngine::AddOutput or AK::SoundEngine::Init
405  AkAudioDeviceEvent in_idEvent, ///< The event for which this callback was called. See AK::AkAudioDeviceEvent. AKRESULT may provide more information.
406  AKRESULT in_AkResult ///< Result of the last operation.
407  );
408 }
409 
410 /// Callback prototype used for audio capture callback registration.
411 /// This callback will be called at the end of each audio frame for each output device that has been registered.
412 /// \remarks This callback will be executed on the main audio thread during real-time rendering and will be executed on the thread that \ref AK::SoundEngine::RenderAudio is called from when offline rendering is enabled.
413 /// \remarks The processing time in the callback function should be minimal. Having too much processing time could cause voice starvation during real-time rendering.
414 /// \remarks Note that a callback registered with <tt>in_idOutput</tt> equal to <tt>AK_INVALID_OUTPUT_DEVICE_ID</tt>, will receive the <tt>AkOutputDeviceID</tt> associated with the main output device.
415 /// \sa
416 /// - AK::SoundEngine::RenderAudio()
417 /// - AK::SoundEngine::RegisterCaptureCallback()
418 /// - AK::SoundEngine::UnregisterCaptureCallback()
420  AkAudioBuffer& in_CaptureBuffer, ///< Capture audio buffer. The data is always float interleaved.
421  AkOutputDeviceID in_idOutput, ///< The audio device specific id, as passed to AK::SoundEngine::AddOutput or AK::SoundEngine::Init
422  void* in_pCookie ///< Callback cookie that will be sent to the callback function along with additional information
423  );
424 
425 #endif // _AK_CALLBACK_H_
426 
Interface to retrieve contextual information for a mixer.
Definition: IAkPlugin.h:445
@ AK_MIDIEvent
Enable notifications for MIDI events. AkCallbackInfo can be cast to AkMIDIEventCallbackInfo.
Definition: AkCallback.h:69
AK::IAkMixerInputContext * pContext
Context of the current voice/bus about to be mixed into the output bus with specified base volume and...
Definition: AkCallback.h:175
@ AkGlobalCallbackLocation_Num
Total number of global callback locations.
Definition: AkCallback.h:368
const char * strLabel
Label of the marker (null-terminated)
Definition: AkCallback.h:124
AkUniqueID audioNodeID
Audio Node ID of playing item
Definition: AkCallback.h:136
Resources data summary structure containing general information about the system
Definition: AkCallback.h:250
AK::AkMetering ** ppSystemAudioObjectMetering
Metering information for each System Audio Object (number of elements is equal to uNumSystemAudioObje...
Definition: AkCallback.h:197
AkInt32 AkTimeMs
Time in ms
Definition: AkTypes.h:56
Definition of data structures for AkAudioObject
char * pszUserCueName
Cue name (UTF-8 string). Set for notifications AK_MusicSyncUserCue. NULL if cue has no name.
Definition: AkCallback.h:245
@ AK_EndOfEvent
Callback triggered when reaching the end of an event. AkCallbackInfo can be cast to AkEventCallbackIn...
Definition: AkCallback.h:49
AkGameObjectID gameObjID
Game object ID
Definition: AkCallback.h:92
@ AkAudioDeviceEvent_Initialization
Sent after an Audio Device has initialized. Initialization might have failed, check the AKRESULT.
Definition: AkCallback.h:393
@ AK_MusicSyncEntry
Enable notifications on Music Entry Cue. AkCallbackInfo can be cast to AkMusicSyncCallbackInfo.
Definition: AkCallback.h:63
void(* AkResourceMonitorCallbackFunc)(const AkResourceMonitorDataSummary *in_pdataSummary)
Definition: AkCallback.h:385
@ AK_MusicSyncBar
Enable notifications on Music Bar. AkCallbackInfo can be cast to AkMusicSyncCallbackInfo.
Definition: AkCallback.h:62
AkReal32 * pfBaseVolume
Base volume, common to all channels.
Definition: AkCallback.h:173
@ AkGlobalCallbackLocation_EndRender
End of frame rendering.
Definition: AkCallback.h:349
AkChannelConfig mainMixConfig
Channel configuration of the main mix
Definition: AkCallback.h:193
AkUInt32 uPlaylistSelection
Selection: set by sound engine, modified by callback function (if not in range 0 <= uPlaylistSelectio...
Definition: AkCallback.h:215
@ AK_SourceInfo_Last
Last source info enable bit, invalid value.
Definition: AkCallback.h:82
@ AkGlobalCallbackLocation_Begin
Start of audio processing. The number of frames about to be rendered depends on the sink/end-point an...
Definition: AkCallback.h:344
@ AkGlobalCallbackLocation_Register
Right after successful registration of callback/plugin. Typically used by plugins along with AkGlobal...
Definition: AkCallback.h:342
AkChannelConfig outputConfig
Channel configuration of the output bus.
Definition: AkCallback.h:172
@ AkGlobalCallbackLocation_ProfilerDisconnect
Wwise Profiler has disconnected from the game.
Definition: AkCallback.h:364
@ AK_Duration
Callback triggered when the duration of the sound is known by the sound engine. AkCallbackInfo can be...
Definition: AkCallback.h:52
@ AkGlobalCallbackLocation_End
End of audio processing.
Definition: AkCallback.h:351
AkTimeMs iActiveDuration
Duration of the active region of the segment (between the Entry and Exit Cues), in milliseconds.
Definition: AkCallback.h:224
AkChannelConfig inputConfig
Channel configuration of the voice/bus.
Definition: AkCallback.h:171
AkUInt64 AkGameObjectID
Game object ID
Definition: AkTypes.h:60
@ AK_MusicSyncAll
Use this flag if you want to receive all notifications concerning AK_MusicSync registration.
Definition: AkCallback.h:74
@ AkGlobalCallbackLocation_Term
Sound engine termination.
Definition: AkCallback.h:353
AKRESULT
Standard function call result.
Definition: AkTypes.h:134
Interface to retrieve information about an input of a mix connection (for processing during the Speak...
Definition: IAkPlugin.h:938
void(* AkGlobalCallbackFunc)(AK::IAkGlobalPluginContext *in_pContext, AkGlobalCallbackLocation in_eLocation, void *in_pCookie)
Definition: AkCallback.h:378
AkMeteringFlags
Metering flags. Used for specifying bus metering, through AK::SoundEngine::RegisterBusVolumeCallback(...
Definition: AkTypes.h:1171
@ AK_Callback_Last
Last calblack unused bit, invalid value.
Definition: AkCallback.h:71
AK::IAkMixerPluginContext * pMixerContext
Output mixing bus context. Use it to access a few useful panning and mixing services,...
Definition: AkCallback.h:176
Structure used to query info on active playing segments.
Definition: AkCallback.h:221
AkReal32 fBeatDuration
Beat Duration in seconds.
Definition: AkCallback.h:227
@ AK_CallbackBits
Bitmask for all callback types.
Definition: AkCallback.h:75
@ AkAudioDeviceEvent_SystemRemoval
Audio device was removed because of a system event (disconnection), hardware or driver problem....
Definition: AkCallback.h:395
void(* AkBusMeteringCallbackFunc)(AkBusMeteringCallbackInfo *in_pCallbackInfo)
Definition: AkCallback.h:292
@ AkGlobalCallbackLocation_Suspend
Sound engine suspension through AK::SoundEngine::Suspend
Definition: AkCallback.h:360
AkCallbackType
Type of callback. Used as a bitfield in methods AK::SoundEngine::PostEvent() and AK::SoundEngine::Dyn...
Definition: AkCallback.h:48
AkReal32 fDuration
Duration of the sound (unit: milliseconds)
Definition: AkCallback.h:134
@ AkGlobalCallbackLocation_WakeupFromSuspend
Sound engine awakening through AK::SoundEngine::WakeupFromSuspend
Definition: AkCallback.h:361
@ AkGlobalCallbackLocation_Init
Sound engine initialization.
Definition: AkCallback.h:358
void(* AkOutputDeviceMeteringCallbackFunc)(AkOutputDeviceMeteringCallbackInfo *in_pCallbackInfo)
Definition: AkCallback.h:302
AkTimeMs iPreEntryDuration
Duration of the pre-entry region of the segment, in milliseconds.
Definition: AkCallback.h:223
float AkReal32
32-bit floating point
AkChannelConfig passthroughMixConfig
Channel configuration of the passthrough mix (if any; will be invalid otherwise)
Definition: AkCallback.h:195
AK::AkMetering * pMetering
Struct containing metering information.
Definition: AkCallback.h:183
AK::AkMetering * pMainMixMetering
Metering information for the main mix
Definition: AkCallback.h:192
void * pCustomInfo
Custom info passed to the DynamicSequence::Open function
Definition: AkCallback.h:150
@ AkAudioDeviceEvent_Last
End of enum, invalid value.
Definition: AkCallback.h:396
AkUniqueID eventID
Unique ID of Event, passed to PostEvent()
Definition: AkCallback.h:102
AkUInt32 uIdentifier
Cue point identifier
Definition: AkCallback.h:122
@ AK_Starvation
Callback triggered when playback skips a frame due to stream starvation. AkCallbackInfo can be cast t...
Definition: AkCallback.h:56
AkCallbackType musicSyncType
Would be either AK_MusicSyncEntry, AK_MusicSyncBeat, AK_MusicSyncBar, AK_MusicSyncExit,...
Definition: AkCallback.h:244
AkUInt32 AkUniqueID
Unique 32-bit ID
Definition: AkTypes.h:52
@ AK_EnableGetSourceStreamBuffering
Enable stream buffering information for use by AK::SoundEngine::GetSourceStreamBuffering().
Definition: AkCallback.h:80
AkReal32 fGridOffset
Grid offset in seconds.
Definition: AkCallback.h:230
AkUInt32 uLabelSize
Size of the label string (including the terminating null character)
Definition: AkCallback.h:125
AkUInt32 uPosition
Position in the cue point (unit: sample frames)
Definition: AkCallback.h:123
AkUInt32 physicalVoices
Number of active physical voices
Definition: AkCallback.h:253
@ AkAudioDeviceEvent_Removal
Audio device was removed through explicit call (AK::SoundEngine::RemoveOutput or AK::SoundEngine::Ter...
Definition: AkCallback.h:394
@ AkGlobalCallbackLocation_MonitorRecap
Send monitor data connection to recap.
Definition: AkCallback.h:356
void(* AkCaptureCallbackFunc)(AkAudioBuffer &in_CaptureBuffer, AkOutputDeviceID in_idOutput, void *in_pCookie)
Definition: AkCallback.h:419
AkPlayingID playingID
Playing ID of Event, returned by PostEvent()
Definition: AkCallback.h:242
@ AK_MusicSyncGrid
Enable notifications on Music Grid. AkCallbackInfo can be cast to AkMusicSyncCallbackInfo.
Definition: AkCallback.h:65
void(* AkCallbackFunc)(AkCallbackType in_eType, AkCallbackInfo *in_pCallbackInfo)
Definition: AkCallback.h:272
AkGlobalCallbackLocation
Bit field of various locations in the audio processing loop where the game can be called back.
Definition: AkCallback.h:341
AkReal32 totalCPU
Pourcentage of the cpu time used for processing audio. Please note that the numbers may add up when u...
Definition: AkCallback.h:251
AkTimeMs iPostExitDuration
Duration of the post-exit region of the segment, in milliseconds.
Definition: AkCallback.h:225
@ AkGlobalCallbackLocation_PreProcessMessageQueueForRender
Start of frame rendering, before having processed game messages.
Definition: AkCallback.h:346
AkUInt32 uPlaylistItemDone
Playlist node done: set by sound engine, modified by callback function (if set to anything but 0 then...
Definition: AkCallback.h:216
AkReal32 * pfEmitterListenerVolume
Emitter-listener pair-specific gain. When there are multiple emitter-listener pairs,...
Definition: AkCallback.h:174
#define AK_CALLBACK(_type, _name)
@ AK_EnableGetSourcePlayPosition
Enable play position information for use by AK::SoundEngine::GetSourcePlayPosition().
Definition: AkCallback.h:78
AkReal32 fEstimatedDuration
Estimated duration of the sound depending on source settings such as pitch. (unit: milliseconds)
Definition: AkCallback.h:135
void(* AkBusCallbackFunc)(AkSpeakerVolumeMatrixCallbackInfo *in_pCallbackInfo)
Definition: AkCallback.h:282
AkUniqueID audioNodeID
Audio Node ID of finished item
Definition: AkCallback.h:149
AkUInt32 uNumSystemAudioObjects
Number of System Audio Objects going out of the output device
Definition: AkCallback.h:196
AkUniqueID playlistID
ID of playlist node
Definition: AkCallback.h:213
AkPlayingID playingID
Playing ID of Dynamic Sequence, returned by AK::SoundEngine:DynamicSequence::Open()
Definition: AkCallback.h:148
void * pCookie
User data, passed to PostEvent()
Definition: AkCallback.h:91
AkMeteringFlags eMeteringFlags
Metering flags that were asked for in RegisterOutputDeviceMeteringCallback(). You may only access cor...
Definition: AkCallback.h:198
@ AK_EndOfDynamicSequenceItem
Callback triggered when reaching the end of a dynamic sequence item. AkCallbackInfo can be cast to Ak...
Definition: AkCallback.h:50
void(* AkBankCallbackFunc)(AkUInt32 in_bankID, const void *in_pInMemoryBankPtr, AKRESULT in_eLoadResult, void *in_pCookie)
Definition: AkCallback.h:332
@ AkGlobalCallbackLocation_ProfilerConnect
Wwise Profiler has connected to the game.
Definition: AkCallback.h:363
AK::AkMetering * pPassthroughMetering
Metering information for the passthrough mix (if any; will be null otherwise)
Definition: AkCallback.h:194
AkChannelConfig channelConfig
Channel configuration of the bus.
Definition: AkCallback.h:184
Struct containing metering information about a buffer. Depending on when this struct is generated,...
Definition: AkCommonDefs.h:192
@ AK_MusicPlaylistSelect
Callback triggered when music playlist container must select the next item to play....
Definition: AkCallback.h:58
@ AK_MusicSyncExit
Enable notifications on Music Exit Cue. AkCallbackInfo can be cast to AkMusicSyncCallbackInfo.
Definition: AkCallback.h:64
AkReal32 * MatrixPtr
Volume matrix. Access each input channel vector with AK::SpeakerVolumes::Matrix::GetChannel().
@ AK_MusicSyncBeat
Enable notifications on Music Beat. AkCallbackInfo can be cast to AkMusicSyncCallbackInfo.
Definition: AkCallback.h:61
bool bStreaming
True if source is streaming, false otherwise.
Definition: AkCallback.h:138
AkReal32 fBarDuration
Bar Duration in seconds.
Definition: AkCallback.h:228
AkAudioDeviceEvent
Definition: AkCallback.h:392
uint32_t AkUInt32
Unsigned 32-bit integer
@ AK_EnableGetMusicPlayPosition
Enable play position information of music objects, queried via AK::MusicEngine::GetPlayingSegmentInfo...
Definition: AkCallback.h:79
void(* AkDeviceStatusCallbackFunc)(AK::IAkGlobalPluginContext *in_pContext, AkUniqueID in_idAudioDeviceShareset, AkUInt32 in_idDeviceID, AkAudioDeviceEvent in_idEvent, AKRESULT in_AkResult)
Definition: AkCallback.h:401
AkUInt64 AkOutputDeviceID
Audio Output device ID
Definition: AkTypes.h:85
@ AK_MusicSyncPoint
Enable notifications on Music switch transition synchronization point. AkCallbackInfo can be cast to ...
Definition: AkCallback.h:67
AkReal32 pluginCPU
Pourcentage of the cpu time used by plugin processing. Please note that the numbers may add up when u...
Definition: AkCallback.h:252
AkTimeMs iCurrentPosition
Current position of the segment, relative to the Entry Cue, in milliseconds. Range is [-iPreEntryDura...
Definition: AkCallback.h:222
@ AkGlobalCallbackLocation_PostMessagesProcessed
After one or more messages have been processed, but before updating game object and listener position...
Definition: AkCallback.h:347
AkUInt32 uNumPlaylistItems
Number of items in playlist node (may be segments or other playlists)
Definition: AkCallback.h:214
AkReal32 fGridDuration
Grid duration in seconds.
Definition: AkCallback.h:229
AkUInt32 totalVoices
Number of active physical and virtual voices
Definition: AkCallback.h:255
@ AK_SpeakerVolumeMatrix
Callback triggered at each frame, letting the client modify the speaker volume matrix....
Definition: AkCallback.h:54
AK::SpeakerVolumes::MatrixPtr pVolumes
Pointer to volume matrix describing the contribution of each source channel to destination channels....
Definition: AkCallback.h:170
AkMeteringFlags eMeteringFlags
Metering flags that were asked for in RegisterBusMeteringCallback(). You may only access correspondin...
Definition: AkCallback.h:185
AkUInt32 nbActiveEvents
Number of events triggered at a certain time
Definition: AkCallback.h:256
AkUniqueID mediaID
Media ID of playing item. (corresponds to 'ID' attribute of 'File' element in SoundBank metadata file...
Definition: AkCallback.h:137
AkMIDIEvent midiEvent
MIDI event triggered by event.
Definition: AkCallback.h:111
AkUInt32 AkPlayingID
Playing ID
Definition: AkTypes.h:55
@ AK_Marker
Callback triggered when encountering a marker during playback. AkCallbackInfo can be cast to AkMarker...
Definition: AkCallback.h:51
AkTimeMs iRemainingLookAheadTime
Number of milliseconds remaining in the "looking-ahead" state of the segment, when it is silent but s...
Definition: AkCallback.h:226
AkPlayingID playingID
Playing ID of Event, returned by PostEvent()
Definition: AkCallback.h:101
@ AK_MusicSyncUserCue
Enable notifications on Music Custom Cue. AkCallbackInfo can be cast to AkMusicSyncCallbackInfo.
Definition: AkCallback.h:66
@ AkGlobalCallbackLocation_BeginRender
Start of frame rendering, after having processed game messages.
Definition: AkCallback.h:348
AkUInt32 virtualVoices
Number of active virtual voices
Definition: AkCallback.h:254
@ AK_MusicPlayStarted
Callback triggered when a "Play" or "Seek" command has been executed ("Seek" commands are issued from...
Definition: AkCallback.h:59
AkSegmentInfo segmentInfo
Segment information corresponding to the segment triggering this callback.
Definition: AkCallback.h:243
@ AkGlobalCallbackLocation_Monitor
Send monitor data
Definition: AkCallback.h:355

このページはお役に立ちましたか?

サポートは必要ですか?

ご質問や問題、ご不明点はございますか?お気軽にお問い合わせください。

サポートページをご確認ください

あなたのプロジェクトについて教えてください。ご不明な点はありませんか。

プロジェクトを登録していただくことで、ご利用開始のサポートをいたします。

Wwiseからはじめよう