Version
menu
Wwise SDK 2025.1.0
AkExternalSourceArray.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 #include <AK/SoundEngine/Common/AkTypedefs.h>
30 
31 #ifdef __cplusplus
32 extern "C" {
33 #endif
34 
35 /// Creates an empty array able to hold the number of sources specified by capacity.
36 ///
37 /// \param[in] capacity Maximum capacity of array
38 /// \return Empty array with specified capacity, or NULL on memory allocation failure.
39 AK_EXTERNAPIFUNC(AkExternalSourceArray, AK_ExternalSourceArray_Create)(AkUInt32 capacity);
40 
41 /// Creates an array from user data. Data is deep-copied into the new array.
42 ///
43 /// The capacity of the created array is the same as in_uNumSrcs. Therefore, it is not possible to add more sources to this array.
44 ///
45 /// \param[in] in_uNumSrcs Number of sources to copy.
46 /// \param[in] in_pSources External source data to copy.
47 /// \return Array containing the copied data.
48 AK_EXTERNAPIFUNC(AkExternalSourceArray, AK_ExternalSourceArray_CreateFromData)(AkUInt32 in_uNumSrcs, struct AkExternalSourceInfo* in_pSources);
49 
50 /// Add an in-memory external source to this array.
51 ///
52 /// \param[in] in_arSources The array to copy data into.
53 /// \param[in] in_codec Codec ID. See documentation for AkExternalSourceInfo::idCodec.
54 /// \param[in] in_cookie Cookie identifying the source. See documentation for AkExternalSourceInfo::iExternalSrcCookie.
55 /// \param[in] in_pInMemory Pointer to the in-memory file. See documentation for AkExternalSourceInfo::pInMemory.
56 /// \param[in] in_uiMemorySize Size of the data pointed by in_pInMemory.
57 /// \return 1 if source was added, 0 if array is already filled to capacity.
58 AK_EXTERNAPIFUNC(int, AK_ExternalSourceArray_AddInMemorySource)(AkExternalSourceArray in_arSources, AkCodecID in_codec, AkUInt32 in_cookie, void* in_pInMemory, AkUInt32 in_uiMemorySize);
59 
60 /// Add a filename-based external source to this array.
61 ///
62 /// The filename string is copied as well. The client may release the string after calling this function.
63 ///
64 /// \param[in] in_arSources The array to copy data into.
65 /// \param[in] in_codec Codec ID. See documentation for AkExternalSourceInfo::idCodec.
66 /// \param[in] in_cookie Cookie identifying the source. See documentation for AkExternalSourceInfo::iExternalSrcCookie.
67 /// \param[in] in_filename File path for the source. See documentation for AkExternalSourceInfo::szFile.
68 /// \return 1 if source was added, 0 if array is already filled to capacity or when running out of memory
69 AK_EXTERNAPIFUNC(int, AK_ExternalSourceArray_AddFileNameSource)(AkExternalSourceArray in_arSources, AkCodecID in_codec, AkUInt32 in_cookie, const char * in_filename);
70 
71 /// Add a file ID-based external source to this array.
72 ///
73 /// \param[in] in_arSources The array to copy data into.
74 /// \param[in] in_codec Codec ID. See documentation for AkExternalSourceInfo::idCodec.
75 /// \param[in] in_cookie Cookie identifying the source. See documentation for AkExternalSourceInfo::iExternalSrcCookie.
76 /// \param[in] in_fileID ID of the file. See documentation for AkExternalSourceInfo::idFile.
77 /// \return 1 if source was added, 0 if array is already filled to capacity.
78 AK_EXTERNAPIFUNC(int, AK_ExternalSourceArray_AddFileIDSource)(AkExternalSourceArray in_arSources, AkCodecID in_codec, AkUInt32 in_cookie, AkFileID in_fileID);
79 
80 /// Returns number of valid items in the array.
81 ///
82 /// \param[in] in_arSources The array
83 /// \return The number of valid items in the array
84 AK_EXTERNAPIFUNC(AkUInt32, AK_ExternalSourceArray_Length)(AkExternalSourceArray in_arSources);
85 
86 /// Returns the capacity (in number of sources) of the array.
87 ///
88 /// \param[in] in_arSources The array
89 /// \return The capacity of the array
90 AK_EXTERNAPIFUNC(AkUInt32, AK_ExternalSourceArray_Capacity)(AkExternalSourceArray in_arSources);
91 
92 /// Returns the raw data of the array.
93 ///
94 /// This raw data can be passed to other functions like AK_CommandBuffer_AddExternalSources.
95 ///
96 /// \param[in] in_arSources The array
97 /// \return Pointer to the raw data of the array.
98 AK_EXTERNAPIFUNC(struct AkExternalSourceInfo*, AK_ExternalSourceArray_Data)(AkExternalSourceArray in_arSources);
99 
100 /// Destroy an external sources array. This releases the memory held by the array.
101 ///
102 /// After this function returns, in_arSources should be discarded and never used again.
103 ///
104 /// \param[in] in_arSources The array to destroy
105 AK_EXTERNAPIFUNC(void, AK_ExternalSourceArray_Destroy)(AkExternalSourceArray in_arSources);
106 
107 #ifdef __cplusplus
108 } // extern "C"
109 #endif
AK_ExternalSourceArray_Create
AKSOUNDENGINE_API AkExternalSourceArray AK_ExternalSourceArray_Create(AkUInt32 capacity)
AkExternalSourceArray
void * AkExternalSourceArray
Definition: AkTypedefs.h:95
AK_EXTERNAPIFUNC
#define AK_EXTERNAPIFUNC(_type, _name)
Definition: AkSoundEngineExport.h:81
AK_ExternalSourceArray_AddFileIDSource
AKSOUNDENGINE_API int AK_ExternalSourceArray_AddFileIDSource(AkExternalSourceArray in_arSources, AkCodecID in_codec, AkUInt32 in_cookie, AkFileID in_fileID)
AK_ExternalSourceArray_Capacity
AKSOUNDENGINE_API AkUInt32 AK_ExternalSourceArray_Capacity(AkExternalSourceArray in_arSources)
AK_ExternalSourceArray_AddFileNameSource
AKSOUNDENGINE_API int AK_ExternalSourceArray_AddFileNameSource(AkExternalSourceArray in_arSources, AkCodecID in_codec, AkUInt32 in_cookie, const char *in_filename)
AK_ExternalSourceArray_AddInMemorySource
AKSOUNDENGINE_API int AK_ExternalSourceArray_AddInMemorySource(AkExternalSourceArray in_arSources, AkCodecID in_codec, AkUInt32 in_cookie, void *in_pInMemory, AkUInt32 in_uiMemorySize)
AkFileID
AkUInt32 AkFileID
Integer-type file identifier.
Definition: AkTypedefs.h:64
AkCodecID
AkUInt32 AkCodecID
Codec plug-in ID.
Definition: AkTypedefs.h:51
AkUInt32
uint32_t AkUInt32
Unsigned 32-bit integer.
Definition: AkNumeralTypes.h:35
AK_ExternalSourceArray_Length
AKSOUNDENGINE_API AkUInt32 AK_ExternalSourceArray_Length(AkExternalSourceArray in_arSources)
AK_ExternalSourceArray_CreateFromData
AKSOUNDENGINE_API AkExternalSourceArray AK_ExternalSourceArray_CreateFromData(AkUInt32 in_uNumSrcs, struct AkExternalSourceInfo *in_pSources)
AK_ExternalSourceArray_Data
AKSOUNDENGINE_API struct AkExternalSourceInfo * AK_ExternalSourceArray_Data(AkExternalSourceArray in_arSources)
AK_ExternalSourceArray_Destroy
AKSOUNDENGINE_API void AK_ExternalSourceArray_Destroy(AkExternalSourceArray in_arSources)

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