Version
menu
Wwise SDK 2025.1.0
AkAudioObject.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 // AkAudioObjectDefs.h
28 
29 /// Definition of data structures for AkAudioObject
30 
31 #pragma once
32 
33 #include <AK/SoundEngine/Common/AkCommonDefs.h>
34 #include <AK/SoundEngine/Common/IAkPluginMemAlloc.h>
35 #include <AK/Tools/Common/AkArray.h>
36 #include <AK/Tools/Common/AkString.h>
37 
38 namespace AK
39 {
40  class IAkPluginParam;
41 }
42 
43 /// An audio object refers to an audio signal with some attached metadata going through the sound engine pipeline.
44 /// The AkAudioObject struct encapsulates the metadata part. The signal itself is contained in a separate AkAudioBuffer instance.
45 struct AkAudioObject
46 {
47  /// Constructor
48  AkAudioObject()
49  :key(AK_INVALID_AUDIO_OBJECT_ID)
50  ,cumulativeGain(1.f, 1.f)
51  ,instigatorID(AK_INVALID_PIPELINE_ID)
52  ,priority(AK_DEFAULT_PRIORITY)
53  {}
54 
55  /// Destructor
56  ~AkAudioObject()
57  {
58  arCustomMetadata.Term();
59  objectName.Term();
60  }
61 
62  static const AkUInt64 kObjectKeyNumBits = 56;
63  static const AkUInt64 kObjectKeyMask = (((AkUInt64)1 << kObjectKeyNumBits) - 1);
64 
65  AkAudioObjectID key; ///< Unique ID, local to a given bus. Only the lower 56 of 64 bits are used for the object itself. The highest 8 bits are available for channel indexing.
66 
67  AkPositioningData positioning; ///< Positioning data for deferred 3D rendering.
68  AkRamp cumulativeGain; ///< Cumulative ramping gain to apply when mixing down to speaker bed or final endpoint
69  AkPipelineID instigatorID; ///< Profiling ID of the node from which the object stems (typically the voice, instance of a Property Container).
70  AkPriority priority; ///< Audio object playback priority. Object with a higher priority will be rendered using the hardware's object functionality on platforms that supports it, whereas objects with a lower priority will be downmixed to a lower resolution 3D bed. Audio object priorities should be retrieved, or set through IAkPluginServiceAudioObjectPriority to retain compatibility with future Wwise releases.
71 
72  /// Custom object metadata.
73  struct CustomMetadata
74  {
75  AkPluginID pluginID; ///< Full plugin ID, including company ID and plugin type. See AKMAKECLASSID macro.
76  AkUniqueID contextID; ///< (Profiling) ID of the sound or bus from which the custom metadata was fetched.
77  AK::IAkPluginParam* pParam; ///< Custom, pluggable medata. Note: any custom metadata is expected to exist for only the current sound engine render tick, and persistent references to it should not be stored.
78  };
79 
80  /// Array type for carrying custom metadata.
81  class ArrayCustomMetadata : public AkArray<CustomMetadata, const CustomMetadata&, AkPluginArrayAllocator>
82  {
83  public:
84  using ArrayType = AkArray<CustomMetadata, const CustomMetadata&, AkPluginArrayAllocator>;
85 
86  ArrayType::Iterator FindByPluginID(AkPluginID pluginID) const
87  {
88  for (auto it = Begin(); it != End(); ++it)
89  {
90  if ((*it).pluginID == pluginID)
91  return it;
92  }
93  return End();
94  }
95  };
96 
97  ArrayCustomMetadata arCustomMetadata; ///< Array of custom metadata, gathered from visited objects. Note: any custom metadata is expected to exist for only the current sound engine render tick, and persistent references to it should not be stored.
98 
99  typedef AkString<AkPluginArrayAllocator, char> String; ///< String type for use in 3D audio objects.
100  String objectName; ///< Name string of the object, to appear in the object profiler. This is normally used by out-of-place object processors for naming their output objects. Built-in sound engine structures don't use it.
101 
102  /// Copies object metadata (everything but the key) from another object.
103  void CopyContents(
104  const AkAudioObject& in_src ///< Object from which metadata is copied.
105  )
106  {
107  positioning = in_src.positioning;
108  cumulativeGain = in_src.cumulativeGain;
109  instigatorID = in_src.instigatorID;
110  priority = in_src.priority;
111  arCustomMetadata.Copy(in_src.arCustomMetadata);
112  objectName = in_src.objectName; // AkString performs a shallow copy when it can, like here.
113  }
114 
115  /// Moves object metadata (everything but the key) from another object.
116  void TransferContents(
117  AkAudioObject& in_src ///< Object from which metadata is moved.
118  )
119  {
120  positioning = in_src.positioning;
121  cumulativeGain = in_src.cumulativeGain;
122  instigatorID = in_src.instigatorID;
123  priority = in_src.priority;
124  arCustomMetadata.Transfer(in_src.arCustomMetadata);
125  objectName.Transfer(in_src.objectName);
126  }
127 
128  void SetCustomMetadata(CustomMetadata* in_aCustomMetadata, AkUInt32 in_uLength)
129  {
130  if (arCustomMetadata.Resize(in_uLength))
131  {
132  for (int i = 0; i < (int)in_uLength; ++i)
133  {
134  arCustomMetadata[i] = in_aCustomMetadata[i];
135  }
136  }
137  }
138 
139  /// Transfer function for transfer move policies.
140  void Transfer(
141  AkAudioObject& in_from ///< Object from which data is transferred.
142  )
143  {
144  key = in_from.key;
145  TransferContents(in_from);
146  }
147 
148  /// Object processors may give an explicit name to objects.
149  /// \return AK_Success if the string was allocated successfully, AK_InsufficientMemory otherwise.
150  AKRESULT SetName(
151  AK::IAkPluginMemAlloc* in_pAllocator, ///< Memory allocator.
152  const char* in_szName ///< Null-terminated string to allocate and store on this object.
153  )
154  {
155  objectName.Init(in_pAllocator);
156  objectName = in_szName;
157  return objectName.AllocCopy();
158  }
159 
160  /// Reset object state in preparation for next frame.
161  void ResetState()
162  {
163  cumulativeGain = AkRamp(1.f, 1.f);
164  arCustomMetadata.Term(); // Reset custom metadata in preparation for next frame.
165  objectName.ClearReference(); // Clear reference to string in preparation for next frame.
166  }
167 };
168 
169 /// A collection of audio objects. Encapsulates the audio data and metadata of each audio object in separate arrays.
170 struct AkAudioObjects
171 {
172  AkAudioObjects(AkUInt32 in_uNumObjects = 0, AkAudioBuffer** in_ppObjectBuffers = nullptr, AkAudioObject** in_ppObjects = nullptr)
173  : uNumObjects(in_uNumObjects)
174  , ppObjectBuffers(in_ppObjectBuffers)
175  , ppObjects(in_ppObjects)
176  {}
177 
178  AkUInt32 uNumObjects; ///< Number of audio objects.
179  AkAudioBuffer** ppObjectBuffers; ///< Array of pointers to audio object buffers.
180  AkAudioObject** ppObjects; ///< Array of pointers to audio objects.
181 };
182 
AkAudioObject::Transfer
void Transfer(AkAudioObject &in_from)
Transfer function for transfer move policies.
Definition: AkAudioObject.h:140
AkAudioObject::String
AkString< AkPluginArrayAllocator, char > String
String type for use in 3D audio objects.
Definition: AkAudioObject.h:99
AK
Definition of data structures for AkAudioObject.
Definition: AkWwiseSDKVersion.cs:31
AkAudioObject::AkAudioObject
AkAudioObject()
Constructor.
Definition: AkAudioObject.h:48
AkAudioObject::kObjectKeyNumBits
static const AkUInt64 kObjectKeyNumBits
Definition: AkAudioObject.h:62
AkAudioObject::positioning
AkPositioningData positioning
Positioning data for deferred 3D rendering.
Definition: AkAudioObject.h:67
AkAudioObject::cumulativeGain
AkRamp cumulativeGain
Cumulative ramping gain to apply when mixing down to speaker bed or final endpoint.
Definition: AkAudioObject.h:68
AkString::Transfer
void Transfer(AkString< TAlloc, T_CHAR > &in_from)
Definition: AkString.h:109
AkArray::Copy
AKRESULT Copy(const AkArray< T, ARG_T, TAlloc, TGrowBy, TMovePolicy > &in_rSource)
Definition: AkArray.h:867
AkAudioObject::kObjectKeyMask
static const AkUInt64 kObjectKeyMask
Definition: AkAudioObject.h:63
AK_INVALID_PIPELINE_ID
static const AkPipelineID AK_INVALID_PIPELINE_ID
Invalid pipeline ID (for profiling)
Definition: AkConstants.h:48
AkAudioObject::key
AkAudioObjectID key
Unique ID, local to a given bus. Only the lower 56 of 64 bits are used for the object itself....
Definition: AkAudioObject.h:65
AkUniqueID
AkUInt32 AkUniqueID
Unique 32-bit ID.
Definition: AkTypedefs.h:39
AkAudioObject::CopyContents
void CopyContents(const AkAudioObject &in_src)
Copies object metadata (everything but the key) from another object.
Definition: AkAudioObject.h:103
AkArray
Specific implementation of array.
Definition: AkArray.h:260
AkAudioObject::TransferContents
void TransferContents(AkAudioObject &in_src)
Moves object metadata (everything but the key) from another object.
Definition: AkAudioObject.h:116
AkAudioObject::SetName
AKRESULT SetName(AK::IAkPluginMemAlloc *in_pAllocator, const char *in_szName)
Definition: AkAudioObject.h:150
AK_DEFAULT_PRIORITY
static const AkPriority AK_DEFAULT_PRIORITY
Default sound / I/O priority.
Definition: AkConstants.h:55
AkPluginArrayAllocator::Init
AkForceInline void Init(AK::IAkPluginMemAlloc *in_pAllocator)
Definition: IAkPluginMemAlloc.h:201
AkArray::Resize
bool Resize(AkUInt32 in_uiSize)
Resize the array to the specified size.
Definition: AkArray.h:824
AkAudioObjects::ppObjectBuffers
AkAudioBuffer ** ppObjectBuffers
Array of pointers to audio object buffers.
Definition: AkAudioObject.h:179
AkAudioObject::ResetState
void ResetState()
Reset object state in preparation for next frame.
Definition: AkAudioObject.h:161
AkAudioObjects::uNumObjects
AkUInt32 uNumObjects
Number of audio objects.
Definition: AkAudioObject.h:178
AkAudioObject::arCustomMetadata
ArrayCustomMetadata arCustomMetadata
Array of custom metadata, gathered from visited objects. Note: any custom metadata is expected to exi...
Definition: AkAudioObject.h:97
AkRamp
Volume ramp specified by end points "previous" and "next".
Definition: AkSoundEngineTypes.h:164
AkArray< CustomMetadata, const CustomMetadata &, AkPluginArrayAllocator >::End
Iterator End() const
Returns the iterator to the end of the array.
Definition: AkArray.h:354
AkAudioObject::CustomMetadata::pluginID
AkPluginID pluginID
Full plugin ID, including company ID and plugin type. See AKMAKECLASSID macro.
Definition: AkAudioObject.h:75
AkPluginID
AkUInt32 AkPluginID
Source or effect plug-in ID.
Definition: AkTypedefs.h:50
AkAudioObject::ArrayCustomMetadata::FindByPluginID
ArrayType::Iterator FindByPluginID(AkPluginID pluginID) const
Definition: AkAudioObject.h:86
AkAudioObject::CustomMetadata::pParam
AK::IAkPluginParam * pParam
Custom, pluggable medata. Note: any custom metadata is expected to exist for only the current sound e...
Definition: AkAudioObject.h:77
AkStringData::ClearReference
void ClearReference()
Definition: AkString.h:50
AkArray::Transfer
void Transfer(AkArray< T, ARG_T, TAlloc, TGrowBy, TMovePolicy > &in_rSource)
Definition: AkArray.h:854
AkAudioObject::instigatorID
AkPipelineID instigatorID
Profiling ID of the node from which the object stems (typically the voice, instance of a Property Con...
Definition: AkAudioObject.h:69
AkArray< CustomMetadata, const CustomMetadata &, AkPluginArrayAllocator >::Begin
Iterator Begin() const
Returns the iterator to the first item of the array, will be End() if the array is empty.
Definition: AkArray.h:346
AkPipelineID
AkUInt32 AkPipelineID
Unique node (bus, voice) identifier for profiling.
Definition: AkTypedefs.h:73
AkAudioObjectID
AkUInt64 AkAudioObjectID
Audio Object ID.
Definition: AkTypedefs.h:75
AkPositioningData
Positioning data of 3D audio objects.
Definition: AkCommonDefs.h:278
AKRESULT
AKRESULT
Definition: AkEnums.h:32
AkAudioObjects
A collection of audio objects. Encapsulates the audio data and metadata of each audio object in separ...
Definition: AkAudioObject.h:171
AkUInt64
uint64_t AkUInt64
Unsigned 64-bit integer.
Definition: AkNumeralTypes.h:36
AkString::AllocCopy
AKRESULT AllocCopy()
Definition: AkString.h:85
AkUInt32
uint32_t AkUInt32
Unsigned 32-bit integer.
Definition: AkNumeralTypes.h:35
AkAudioObject::SetCustomMetadata
void SetCustomMetadata(CustomMetadata *in_aCustomMetadata, AkUInt32 in_uLength)
Definition: AkAudioObject.h:128
AkArray::Term
void Term()
Term the array. Must be called before destroying the object.
Definition: AkArray.h:556
AkAudioObject::~AkAudioObject
~AkAudioObject()
Destructor.
Definition: AkAudioObject.h:56
AkAudioObject::priority
AkPriority priority
Audio object playback priority. Object with a higher priority will be rendered using the hardware's o...
Definition: AkAudioObject.h:70
AkPriority
AkInt8 AkPriority
Priority.
Definition: AkTypedefs.h:54
AkAudioObject::objectName
String objectName
Name string of the object, to appear in the object profiler. This is normally used by out-of-place ob...
Definition: AkAudioObject.h:100
AkAudioObject::CustomMetadata
Custom object metadata.
Definition: AkAudioObject.h:74
AkStringData::Term
void Term()
Definition: AkString.h:40
AkAudioObject::ArrayCustomMetadata
Array type for carrying custom metadata.
Definition: AkAudioObject.h:82
AkAudioObject::CustomMetadata::contextID
AkUniqueID contextID
(Profiling) ID of the sound or bus from which the custom metadata was fetched.
Definition: AkAudioObject.h:76
AkAudioObjects::AkAudioObjects
AkAudioObjects(AkUInt32 in_uNumObjects=0, AkAudioBuffer **in_ppObjectBuffers=nullptr, AkAudioObject **in_ppObjects=nullptr)
Definition: AkAudioObject.h:172
AkAudioObjects::ppObjects
AkAudioObject ** ppObjects
Array of pointers to audio objects.
Definition: AkAudioObject.h:180
AK_INVALID_AUDIO_OBJECT_ID
static const AkAudioObjectID AK_INVALID_AUDIO_OBJECT_ID
Invalid audio object ID.
Definition: AkConstants.h:49

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