Version
menu
Wwise SDK 2025.1.0
AkCommandBuffer.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) 2025 Audiokinetic Inc.
25 *******************************************************************************/
26 
27 #pragma once
28 
29 
30 #include <AK/SoundEngine/Common/AkEnums.h>
31 #include <AK/SoundEngine/Common/AkSoundEngineExport.h>
32 #include <AK/SoundEngine/Common/AkCommandTypes.h>
33 
34 #ifdef __cplusplus
35 extern "C" {
36 #endif
37 
38 /// Returns the minimum size required to accomodate the specified command and its payload.
39 ///
40 /// \param[in] in_cmd_id ID of command (should be one of the values listed in AkCommand enum)
41 /// \return Size required to accomodate one instance of this command in the buffer. 0 if ID is unrecognized.
42 /// \sa AkCommand
43 AK_EXTERNAPIFUNC(size_t, AK_CommandBuffer_CmdSize)(enum AkCommand in_cmd_id);
44 
45 /// Returns the minimum size required for a command buffer containing 0 commands.
46 /// Use this function in conjunction with AK_CommandBuffer_CmdSize to determine the required size to allocate for your needs.
47 /// \sa AK_CommandBuffer_Init
48 AK_EXTERNAPIFUNC(size_t, AK_CommandBuffer_MinSize)(void);
49 
50 /// Allocates and initializes a new command buffer with the specified size using the Wwise SDK's memory manager.
51 /// The buffer is guaranteed to be aligned on 4 bytes. It is allocated using <tt>AkMemID_Integration</tt> memory category.
52 ///
53 /// Use AK_CommandBuffer_MinSize and AK_CommandBuffer_CmdSize to determine how much space to allocate for the planned buffer.
54 ///
55 /// The buffer returned by this function MUST be freed using AK_CommandBuffer_Destroy.
56 ///
57 /// This function will return NULL under the following error conditions:
58 /// - Requested size is smaller than the minimium size required for a command buffer.
59 /// - Memory manager is not initialized.
60 /// - Not enough memory to allocate the buffer.
61 ///
62 /// \param[in] in_size Size of buffer in bytes
63 /// \return Pointer to the allocated buffer, NULL on error.
64 AK_EXTERNAPIFUNC(struct AkCommandBufferHeader *, AK_CommandBuffer_Create)(size_t in_size);
65 
66 /// Destroy a buffer created by AK_CommandBuffer_Create.
67 /// When this function returns the buffer is freed and must not be used anymore.
68 ///
69 /// \akwarning Do not use this function to release a buffer that was not returned by AK_CommandBuffer_Create! Doing so will cause undefined behavior.
70 /// \endakwarning
71 ///
72 /// \param[in] in_buffer Pointer to the buffer returned by AK_CommandBuffer_Create.
73 AK_EXTERNAPIFUNC(void, AK_CommandBuffer_Destroy)(void* in_buffer);
74 
75 /// Initialize a previously-allocated command buffer. Clears any previous data contained in the buffer. A buffer can be re-initialized multiple times with this function.
76 ///
77 /// Note that it is the responsibility of the caller to allocate the buffer. Use AK_CommandBuffer_MinSize and AK_CommandBuffer_CmdSize to determine how much space to allocate for the planned buffer.
78 /// Ensure the allocated buffer is aligned on 4 bytes.
79 ///
80 /// Alternatively, use AK_CommandBuffer_Create to allocate and initialize the buffer in one call.
81 ///
82 /// \param[out] out_buffer Pointer to buffer space
83 /// \param[in] in_size Size of buffer in bytes
84 /// \return Pointer to initialized command buffer header on success, NULL if buffer is smaller than the value returned by AK_CommandBuffer_MinSize or buffer not aligned on 4 bytes.
85 AK_EXTERNAPIFUNC(struct AkCommandBufferHeader *, AK_CommandBuffer_Init)(void* out_buffer, size_t in_size);
86 
87 /// Reserve space for a command in the command buffer
88 /// When this function returns a non-null pointer, the space reserved is zero'ed out.
89 /// It is the responsibility of the caller to write the correct payload data in the command's reserved space.
90 ///
91 /// The buffer must be initialized prior to calling this function, either using AK_CommandBuffer_Create or AK_CommandBuffer_Init. Passing an un-initialized buffer results in undefined behavior.
92 ///
93 /// \param[in,out] in_buffer Pointer to command buffer
94 /// \param[in] in_cmd_id ID of command (should be one of the values listed in AkCommand enum)
95 /// \return Pointer to the corresponding command payload, or NULL if not enough space left in the buffer
96 /// \sa AkCommand
97 AK_EXTERNAPIFUNC(void *, AK_CommandBuffer_Add)(void* in_buffer, enum AkCommand in_cmd_id);
98 
99 /// Calculate the space required to store a null-terminated string in the command buffer.
100 ///
101 /// \param[in] str Null-terminated string.
102 /// \return Size (in bytes) required to copy the string in the command buffer.
103 AK_EXTERNAPIFUNC(size_t, AK_CommandBuffer_StringSize)(const char* str);
104 
105 /// Copy a null-terminated string to the data payload of the last added command.
106 ///
107 /// Some commands, like \c RegisterGameObject, require a string to complete the payload.
108 /// First add the command, then call this function to complete the payload. For example:
109 ///
110 /// auto cmd = (AkCmd_RegisterGameObject*)AK_CommandBuffer_Add(buffer, AkCommand_RegisterGameObject);
111 /// cmd->gameObjectID = 100;
112 /// AK_CommandBuffer_AddString(buffer, "Player Emitter");
113 ///
114 /// Use AK_CommandBuffer_StringSize to calculate the size required to store the string.
115 ///
116 /// \param[in] in_buffer Pointer to command buffer
117 /// \param[in] str Pointer to null-terminated string
118 /// \return Pointer to the copied string, or NULL if there is not enough space left in the buffer.
119 AK_EXTERNAPIFUNC(void*, AK_CommandBuffer_AddString)(void* in_buffer, const char * str);
120 
121 /// Calculate the space required to store an array of arbitrary-sized objects in the command buffer.
122 ///
123 /// \param[in] item_size Size (in bytes) of each element in the array.
124 /// \param[in] num_items Number of elements in the array.
125 /// \return Size (in bytes) required to copy the array data in the command buffer.
126 AK_EXTERNAPIFUNC(size_t, AK_CommandBuffer_ArraySize)(size_t item_size, AkUInt16 num_items);
127 
128 /// Copy an array of arbitrary-sized objects to the data payload of the last added command.
129 ///
130 /// Some commands, like \c SetListeners, require additional data to complete the payload.
131 /// First add the command, then call this function to complete the payload. For example:
132 ///
133 /// auto cmd = (AkCmd_SetListeners*)AK_CommandBuffer_Add(buffer, AkCommand_SetListeners);
134 /// cmd->gameObjectID = 100;
135 /// cmd->numListenerIDs = mylistenerArray.size();
136 /// AK_CommandBuffer_AddArray(buffer, sizeof(AkGameObjectID), mylistenerArray.size(), mylistenerArray.data());
137 ///
138 /// Use AK_CommandBuffer_ArraySize to calculate the size required to store the data.
139 ///
140 /// \param[in] in_buffer Pointer to command buffer
141 /// \param[in] item_size Size (in bytes) of each element in the array.
142 /// \param[in] num_items Number of elements in the array.
143 /// \param[in] items (optional) Pointer to the first element in the array to copy. If NULL, no copy takes place; array space is merely reserved, pointer to the start of the space is returned, and client is responsible for writing to it.
144 /// \return Pointer to the copied array, or NULL if there is not enough space left in the buffer.
145 AK_EXTERNAPIFUNC(void*, AK_CommandBuffer_AddArray)(void* in_buffer, size_t item_size, AkUInt16 num_items, const void* items);
146 
147 /// Calculate the space required to store an array of external sources.
148 ///
149 /// \param[in] in_uNumSources Number of external sources in the array
150 /// \param[in] in_sources Pointer to first element in the external sources array
151 /// \return Size (in bytes) required to copy the external sources data in the command buffer.
152 AK_EXTERNAPIFUNC(size_t, AK_CommandBuffer_ExternalSourcesSize)(AkUInt32 in_uNumSources, const struct AkExternalSourceInfo* in_sources);
153 
154 /// Copy an array of external sources to the data payload of the last added command.
155 ///
156 /// When posting an event using external sources, \c PostEvent command requires additional data to complete the payload.
157 /// First add the command, then call this function to complete the payload. For example:
158 ///
159 /// auto cmd = (AkCmd_PostEvent*)AK_CommandBuffer_Add(buffer, AkCommand_PostEvent);
160 /// // Fill out the command...
161 /// cmd->numExternalSources = myExternalSourcesArray.size();
162 /// AK_CommandBuffer_AddExternalSources(buffer, myExternalSourcesArray.size(), myExternalSourcesArray.data());
163 ///
164 /// Use AK_CommandBuffer_ExternalSourcesSize to calculate the size required to store the data.
165 ///
166 /// \param[in] in_buffer Pointer to command buffer
167 /// \param[in] in_uNumSources Number of elements in the array.
168 /// \param[in] in_pSources Pointer to the first element in the array.
169 /// \return Pointer to the copied array, or NULL if there is not enough space left in the buffer.
170 /// \sa AkCmd_SA_PostEvent
171 AK_EXTERNAPIFUNC(void*, AK_CommandBuffer_AddExternalSources)(void* in_buffer, AkUInt32 in_uNumSources, const struct AkExternalSourceInfo * in_pSources);
172 
173 /// Calculate the space required to store geometry data in a command buffer.
174 ///
175 /// \param[in] in_geometryParams Pointer to the geometry data.
176 /// \return Size (in bytes) required to copy the geometry data in the command buffer.
177 AK_EXTERNAPIFUNC(size_t, AK_CommandBuffer_GeometrySize)(const struct AkGeometryParams* in_geometryParams);
178 
179 /// Copy geometry data to the data payload of the last added command.
180 ///
181 /// The \c SA_SetGeometry command requires additional data to complete the payload.
182 /// First add the command, then call this function to complete the payload. For example:
183 ///
184 /// AkGeometryParams geoParams; // Initialize with valid triangles, vertices, surfaces...
185 /// auto cmd = (AkCmd_SA_SetGeometry*)AK_CommandBuffer_Add(buffer, AkCommand_SA_SetGeometry);
186 /// cmd->geometrySetID = myID;
187 /// AK_CommandBuffer_AddGeometry(buffer, &geoParams);
188 ///
189 /// Use AK_CommandBuffer_GeometrySize to calculate the size required to store the data.
190 ///
191 /// \param[in] in_buffer Pointer to command buffer
192 /// \param[in] in_geometryParams Pointer to the geometry data.
193 /// \return Pointer to the copied data, or NULL if there is not enough space left in the buffer.
194 /// \sa AkCmd_SA_SetGeometry
195 AK_EXTERNAPIFUNC(void*, AK_CommandBuffer_AddGeometry)(void* in_buffer, const struct AkGeometryParams* in_geometryParams);
196 
197 /// Remove the last-added command from the command buffer.
198 /// This function can be useful when the buffer does not have enough space left for a command's extra data.
199 ///
200 /// For example, using the \c SetListeners command requires adding a variable-size array:
201 ///
202 /// auto cmd = (AkCmd_SetListeners*)AK_CommandBuffer_Add(buffer, AkCommand_SetListeners);
203 /// cmd->gameObjectID = 100;
204 /// cmd->numListenerIDs = mylistenerArray.size();
205 /// if (!AK_CommandBuffer_AddArray(buffer, sizeof(AkGameObjectID), mylistenerArray.size(), mylistenerArray.data()))
206 /// AK_CommandBuffer_Remove(buffer); // Not enough space for the array, so remove the last command (SetListeners)
207 ///
208 /// This function is a no-op when called on an empty command buffer.
209 ///
210 /// \param[in] in_buffer Pointer to command buffer
211 AK_EXTERNAPIFUNC(void, AK_CommandBuffer_Remove)(void* in_buffer);
212 
213 /// Submit the commands contained in a buffer. They will be executed asynchronously on the next audio render.
214 /// This function blocks until the buffer is submitted, but not until its commands are processed.
215 /// Commands are always processed asynchronously. Use the AkCommand_Callback command (AkCmd_Callback) to receive a callback at a specific point during command buffer processing.
216 ///
217 /// \param[in] in_buffer Pointer to command buffer
218 AK_EXTERNAPIFUNC(void, AK_CommandBuffer_Submit)(void* in_buffer);
219 
220 /// Submit the commands contained in a buffer. They will be executed asynchronously on the next audio render.
221 /// This function does not block. If the internal message queue of the audio thread is full, this function returns an error.
222 /// When this occurs, no command in the buffer has been submitted, and you can safely re-attempt to submit the same buffer at a later time.
223 ///
224 /// \param[in] in_buffer Pointer to command buffer
225 /// \return
226 /// - AK_Success on success
227 /// - AK_Busy if the internal message queue of the audio render thread is full.
228 AK_EXTERNAPIFUNC(AKRESULT_t, AK_CommandBuffer_SubmitNonBlocking)(void* in_buffer);
229 
230 /// Function to begin iteration of commands in a buffer.
231 ///
232 /// \param[in] in_buffer Pointer to command buffer
233 /// \param[out] out_iterator Pointer to iterator structure to initialize.
234 /// \sa AK_CommandBuffer_Next
235 /// \sa AkCommandBufferIterator
236 AK_EXTERNAPIFUNC(void, AK_CommandBuffer_Begin)(void* in_buffer, struct AkCommandBufferIterator* out_iterator);
237 
238 /// Function to iterate over the next command in the buffer.
239 /// A loop going over all commands in a buffer would be structured as follows:
240 ///
241 /// struct AkCommandBufferIterator it;
242 /// AK_CommandBuffer_Begin(buffer, &it);
243 /// while (AK_CommandBuffer_Next(&it)) {
244 /// printf("Command ID: %d; Command payload: %p\n", it.header->cmd, it.payload);
245 /// }
246 ///
247 /// \param[in,out] inout_iterator Pointer to iterator initialized with \ref AK_CommandBuffer_Begin
248 /// \return non-zero when iterator points to the next command, zero if all commands have been iterated over.
249 /// \sa
250 /// - AK_CommandBuffer_Begin
251 /// - AkCommandBufferIterator
252 AK_EXTERNAPIFUNC(int, AK_CommandBuffer_Next)(struct AkCommandBufferIterator* inout_iterator);
253 
254 /// Generates a new playing ID. This is guaranteed to return a different value every time this is called.
255 AK_EXTERNAPIFUNC(AkPlayingID, AK_SoundEngine_GeneratePlayingID)(void);
256 
257 /// Universal converter from string to ID for the sound engine.
258 /// This function will hash the name based on a algorithm ( provided at : /AK/Tools/Common/AkFNVHash.h )
259 /// Note:
260 /// This function returns a AkUInt32, which is compatible with:
261 /// AkUniqueID, AkStateGroupID, AkStateID, AkSwitchGroupID, AkSwitchStateID, AkRtpcID, and so on.
262 AK_EXTERNAPIFUNC(AkUInt32, AK_SoundEngine_GetIDFromString)(const char* in_pszString);
263 
264 #ifdef AK_SUPPORT_WCHAR
265 /// Universal converter from Unicode string to ID for the sound engine.
266 /// This function will hash the name based on a algorithm ( provided at : /AK/Tools/Common/AkFNVHash.h )
267 /// Note:
268 /// This function returns a AkUInt32, which is compatible with:
269 /// AkUniqueID, AkStateGroupID, AkStateID, AkSwitchGroupID, AkSwitchStateID, AkRtpcID, and so on.
270 AK_EXTERNAPIFUNC(AkUInt32, AK_SoundEngine_GetIDFromStringW)(const wchar_t* in_pszString);
271 #endif //AK_SUPPORT_WCHAR
272 
273 /// Gets the compounded output ID from shareset and device id.
274 /// Outputs are defined by their type (Audio Device shareset) and their specific system ID. A system ID could be reused for other device types on some OS or platforms, hence the compounded ID.
275 /// Use 0 for in_idShareset and in_idDevice to get the Main Output ID (the one usually initialized during AK::SoundEngine::Init)
276 ///
277 /// \param[in] in_idShareset Audio Device ShareSet ID, as defined in the Wwise Project. If needed, use AK::SoundEngine::GetIDFromString() to convert from a string. Set to AK_INVALID_UNIQUE_ID to use the default.
278 /// \param[in] in_idDevice Device specific identifier, when multiple devices of the same type are possible. If only one device is possible, leave to 0.
279 /// \return The id of the output
280 ///
281 /// \sa \ref obtaining_device_id
282 AK_EXTERNAPIFUNC(AkOutputDeviceID, AK_SoundEngine_GetOutputID)(AkUniqueID in_idShareset, AkUInt32 in_idDevice);
283 
284 #ifdef __cplusplus
285 } // extern "C"
286 #endif
AK_CommandBuffer_AddGeometry
AKSOUNDENGINE_API void * AK_CommandBuffer_AddGeometry(void *in_buffer, const struct AkGeometryParams *in_geometryParams)
AkUInt16
uint16_t AkUInt16
Unsigned 16-bit integer.
Definition: AkNumeralTypes.h:33
AK_CommandBuffer_Add
AKSOUNDENGINE_API void * AK_CommandBuffer_Add(void *in_buffer, enum AkCommand in_cmd_id)
AK_CommandBuffer_Create
AKSOUNDENGINE_API struct AkCommandBufferHeader * AK_CommandBuffer_Create(size_t in_size)
AK_CommandBuffer_StringSize
AKSOUNDENGINE_API size_t AK_CommandBuffer_StringSize(const char *str)
AK_CommandBuffer_AddExternalSources
AKSOUNDENGINE_API void * AK_CommandBuffer_AddExternalSources(void *in_buffer, AkUInt32 in_uNumSources, const struct AkExternalSourceInfo *in_pSources)
AK_CommandBuffer_CmdSize
AKSOUNDENGINE_API size_t AK_CommandBuffer_CmdSize(enum AkCommand in_cmd_id)
AK_EXTERNAPIFUNC
#define AK_EXTERNAPIFUNC(_type, _name)
Definition: AkSoundEngineExport.h:81
AkUniqueID
AkUInt32 AkUniqueID
Unique 32-bit ID.
Definition: AkTypedefs.h:39
AkCommand
AkCommand
IDs for commands that can be sent to the sound engine. Each command has an associated structure that ...
Definition: AkCommandTypes.h:35
AK_CommandBuffer_AddString
AKSOUNDENGINE_API void * AK_CommandBuffer_AddString(void *in_buffer, const char *str)
AK_CommandBuffer_ArraySize
AKSOUNDENGINE_API size_t AK_CommandBuffer_ArraySize(size_t item_size, AkUInt16 num_items)
AK_CommandBuffer_Submit
AKSOUNDENGINE_API void AK_CommandBuffer_Submit(void *in_buffer)
AK_CommandBuffer_Destroy
AKSOUNDENGINE_API void AK_CommandBuffer_Destroy(void *in_buffer)
AK_SoundEngine_GetIDFromString
AKSOUNDENGINE_API AkUInt32 AK_SoundEngine_GetIDFromString(const char *in_pszString)
AK_CommandBuffer_SubmitNonBlocking
AKSOUNDENGINE_API AKRESULT_t AK_CommandBuffer_SubmitNonBlocking(void *in_buffer)
AK_CommandBuffer_GeometrySize
AKSOUNDENGINE_API size_t AK_CommandBuffer_GeometrySize(const struct AkGeometryParams *in_geometryParams)
AK_CommandBuffer_Init
AKSOUNDENGINE_API struct AkCommandBufferHeader * AK_CommandBuffer_Init(void *out_buffer, size_t in_size)
AK_CommandBuffer_Remove
AKSOUNDENGINE_API void AK_CommandBuffer_Remove(void *in_buffer)
AK_CommandBuffer_AddArray
AKSOUNDENGINE_API void * AK_CommandBuffer_AddArray(void *in_buffer, size_t item_size, AkUInt16 num_items, const void *items)
AK_CommandBuffer_ExternalSourcesSize
AKSOUNDENGINE_API size_t AK_CommandBuffer_ExternalSourcesSize(AkUInt32 in_uNumSources, const struct AkExternalSourceInfo *in_sources)
AK_CommandBuffer_Next
AKSOUNDENGINE_API int AK_CommandBuffer_Next(struct AkCommandBufferIterator *inout_iterator)
AK_CommandBuffer_MinSize
AKSOUNDENGINE_API size_t AK_CommandBuffer_MinSize(void)
AK_CommandBuffer_Begin
AKSOUNDENGINE_API void AK_CommandBuffer_Begin(void *in_buffer, struct AkCommandBufferIterator *out_iterator)
AkCommandBufferHeader
Describes the data written at the beginning of any initialized command buffer.
Definition: AkCommandTypes.h:1513
AkUInt32
uint32_t AkUInt32
Unsigned 32-bit integer.
Definition: AkNumeralTypes.h:35
AK_SoundEngine_GetOutputID
AKSOUNDENGINE_API AkOutputDeviceID AK_SoundEngine_GetOutputID(AkUniqueID in_idShareset, AkUInt32 in_idDevice)
AK_SoundEngine_GeneratePlayingID
AKSOUNDENGINE_API AkPlayingID AK_SoundEngine_GeneratePlayingID(void)
Generates a new playing ID. This is guaranteed to return a different value every time this is called.
AKRESULT_t
AkUInt32 AKRESULT_t
Definition: AkEnums.h:113
AkGeometryParams
Parameters passed to SetGeometry.
Definition: AkSpatialAudioTypes.h:778
AkOutputDeviceID
AkUInt64 AkOutputDeviceID
Audio Output device ID.
Definition: AkTypedefs.h:72
AkPlayingID
AkUInt32 AkPlayingID
A unique identifier generated whenever a PostEvent is called (or when a Dynamic Sequence is created)....
Definition: AkTypedefs.h:42

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