Version
menu_open
Wwise SDK 2024.1.5
AkSpatialAudioTypes.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 /// \file
28 /// Spatial audio data type definitions.
29 
30 #pragma once
31 
32 #include <AK/Tools/Common/AkString.h>
33 #include <AK/Tools/Common/AkLock.h>
34 #include <AK/Tools/Common/AkSet.h>
35 
36 class AkAcousticRoom;
37 class AkAcousticPortal;
38 class AkImageSourceTriangle;
39 class AkImageSourcePlane;
40 
41 #define AK_MAX_REFLECT_ORDER 4
42 #define AK_MAX_REFLECTION_PATH_LENGTH (AK_MAX_REFLECT_ORDER + 4)
43 #define AK_STOCHASTIC_RESERVE_LENGTH AK_MAX_REFLECTION_PATH_LENGTH
44 #define AK_MAX_SOUND_PROPAGATION_DEPTH 8
45 #define AK_MAX_SOUND_PROPAGATION_WIDTH 32 // Can not exceed 32 total sound propagation paths.
46 #define AK_SA_EPSILON (0.001f)
47 #define AK_SA_DIFFRACTION_EPSILON (0.01f) // Radians (~0.57 degrees)
48 #define AK_SA_DIFFRACTION_DOT_EPSILON (0.00005f) // 1.f - cos(AK_SA_DIFFRACTION_EPSILON)
49 #define AK_SA_PLANE_THICKNESS (0.01f)
50 #define AK_SA_MIN_ENVIRONMENT_ABSORPTION (0.01f)
51 #define AK_SA_MIN_ENVIRONMENT_SURFACE_AREA (1.0f)
52 
53 const AkUInt32 kDefaultDiffractionMaxEdges = 8;
54 const AkUInt32 kDefaultDiffractionMaxPaths = 8;
55 const AkUInt32 kHashListBlockAllocItemCount = 50; // Number of items per block to allocate for in AkStochasticCollectionHashList
56 const AkUInt32 kRayPoolBlockAllocItemCount = 35; // Number of items per block to allocate for in AkStochasticRay
57 
58 // Max values that are used for calculating diffraction paths between the listener and a portal.
59 const AkUInt32 kDiffractionMaxEdges = 8;
60 const AkUInt32 kDiffractionMaxPaths = 8;
61 const AkUInt32 kPortalToPortalDiffractionMaxPaths = 8;
62 
63 typedef AkArrayAllocatorNoAlign<AkMemID_SpatialAudio> ArrayPoolSpatialAudio;
64 typedef AkArrayAllocatorAlignedSimd<AkMemID_SpatialAudio> ArrayPoolSpatialAudioSIMD;
65 
66 typedef AkArrayAllocatorNoAlign<AkMemID_SpatialAudioPaths> ArrayPoolSpatialAudioPaths;
67 typedef AkArrayAllocatorAlignedSimd<AkMemID_SpatialAudioPaths> ArrayPoolSpatialAudioPathsSIMD;
68 
69 typedef AkArrayAllocatorNoAlign<AkMemID_SpatialAudioGeometry> ArrayPoolSpatialAudioGeometry;
70 typedef AkArrayAllocatorAlignedSimd<AkMemID_SpatialAudioGeometry> ArrayPoolSpatialAudioGeometrySIMD;
71 
72 namespace AK
73 {
74  namespace SpatialAudio
75  {
76  typedef AkString<ArrayPoolSpatialAudio, wchar_t> WString; ///< Wide string type for use in Wwise Spatial Audio
77  typedef AkString<ArrayPoolSpatialAudio, AkOSChar> OsString; ///< OS string type for use in Wwise Spatial Audio
78  typedef AkString<ArrayPoolSpatialAudio, char> String; ///< String type for use in Wwise Spatial Audio
79  typedef AkDbString<ArrayPoolSpatialAudio, char> DbString; ///< Instanced string type.
80  typedef AkDbWeakString<ArrayPoolSpatialAudio, char> DbWeakString; ///< Weak reference to DbString. Multi-thread reading is safe.
81 
82  typedef AkUInt16 Idx;
83  }
84 }
85 
86 typedef AkUInt16 AkVertIdx;
87 typedef AkUInt16 AkTriIdx;
88 typedef AkUInt16 AkSurfIdx;
89 typedef AkUInt16 AkEdgeIdx;
90 typedef AkUInt16 AkEdgeReceptorIdx;
91 
92 #define AK_INVALID_VERTEX ((AkVertIdx)(-1))
93 #define AK_INVALID_TRIANGLE ((AkTriIdx)(-1))
94 #define AK_INVALID_SURFACE ((AkSurfIdx)(-1))
95 #define AK_INVALID_EDGE ((AkEdgeIdx)(-1))
96 
97 /// Base type for ID's used by Wwise spatial audio.
98 struct AkSpatialAudioID
99 {
100  /// Default constructor. Creates an invalid ID.
101  constexpr AkSpatialAudioID() : id((AkUInt64)-1) {}
102 
103  /// Construct from a 64-bit int.
104  AkSpatialAudioID(AkUInt64 _id) : id(_id) {}
105 
106  /// Conversion from a pointer to a AkSpatialAudioID
107  explicit AkSpatialAudioID(const void * ptr) : id(reinterpret_cast<AkUInt64>(ptr)) {}
108 
109  bool operator == (const AkSpatialAudioID& rhs) const { return id == rhs.id; }
110  bool operator != (const AkSpatialAudioID& rhs) const { return id != rhs.id; }
111  bool operator < (const AkSpatialAudioID& rhs) const { return id < rhs.id; }
112  bool operator > (const AkSpatialAudioID& rhs) const { return id > rhs.id; }
113  bool operator <= (const AkSpatialAudioID& rhs) const { return id <= rhs.id; }
114  bool operator >= (const AkSpatialAudioID& rhs) const { return id >= rhs.id; }
115 
116  /// Determine if this ID is valid.
117  bool IsValid() const { return id != (AkUInt64)-1; }
118 
119  /// Conversion function used internally to convert from a AkSpatialAudioID to a AkGameObjectID.
120  AkGameObjectID AsGameObjectID() const { return (AkGameObjectID)id; }
121 
122  operator AkUInt64 () const { return id; }
123 
124  AkUInt64 id;
125 };
126 
127 /// Spatial Audio Room ID type. This ID type exists in the same ID-space as game object ID's. The client is responsible for not choosing room ID's
128 /// that conflict with registered game objects' ID's. Internally, the spatial audio rooms and portals API manages registration and un-registration of game objects that
129 /// represent rooms using AkRoomID's provided by the client; AkRoomID's are converted to AkGameObjectID's by calling AsGameObjectID().
130 /// \sa
131 /// - \ref AK::SpatialAudio::SetRoom
132 /// - \ref AK::SpatialAudio::RemoveRoom
133 struct AkRoomID : public AkSpatialAudioID
134 {
135  /// Default constructor. Creates an invalid ID.
136  constexpr AkRoomID() : AkSpatialAudioID() {}
137 
138  /// Construct from a 64-bit int.
139  AkRoomID(AkUInt64 _id) : AkSpatialAudioID(_id) {}
140 
141  /// Conversion from a pointer to a AkRoomID
142  explicit AkRoomID(const void * ptr) : AkSpatialAudioID(ptr) {}
143 
144  /// Conversion function used to convert AkRoomID's to AkGameObjectIDs.
145  AkGameObjectID AsGameObjectID() const { return IsValid() ? (AkGameObjectID)id : OutdoorsGameObjID; }
146 
147  /// Conversion function used to convert to AkGameObjectIDs to AkRoomID.
148  static AkRoomID FromGameObjectID(AkGameObjectID in_fromGameObject)
149  {
150  AkRoomID id;
151  if (in_fromGameObject != OutdoorsGameObjID)
152  id.id = (AkUInt64)in_fromGameObject;
153  return id;
154  }
155 
156 private:
157  /// A game object ID that is in the reserved range, used for 'outdoor' rooms, i.e. when not in a room.
158  /// \akwarning This AkGameObjectID is the underlying game object ID of the outdoor room, and should not be confused with the actual outdoor room's ID, AK::SpatialAudio::kOutdoorRoomID.\endakwarning
159  static const AkGameObjectID OutdoorsGameObjID = (AkGameObjectID)-4;
160 };
161 typedef AkSet<AkRoomID, ArrayPoolSpatialAudio> AkRoomIDSet;
162 
163 
164 struct AkRoomHierarchyID
165 {
166  AkRoomHierarchyID() : id() {}
167  explicit AkRoomHierarchyID(AkRoomID in_roomID) : id(in_roomID) {}
168  bool operator == (AkRoomHierarchyID rhs) const { return id == rhs.id; }
169  bool operator != (AkRoomHierarchyID rhs) const { return id != rhs.id; }
170 
171  AkRoomID id;
172 };
173 
174 namespace AK
175 {
176  namespace SpatialAudio
177  {
178  /// The outdoor room ID. This room is created automatically and is typically used for outdoors, i.e. when not in a room.
179  constexpr AkRoomID kOutdoorRoomID;
180  }
181 }
182 
183 ///< Unique ID for portals. This ID type exists in the same ID-space as game object ID's. The client is responsible for not choosing portal ID's
184 /// that conflict with registered game objects' ID's. Internally, the spatial audio rooms and portals API manages registration and un-registration of game objects that
185 /// represent portals using AkPortalID's provided by the client; AkPortalID's are convertied to AkGameObjectID's by calling AsGameObjectID().
186 /// \sa
187 /// - \ref AK::SpatialAudio::SetPortal
188 /// - \ref AK::SpatialAudio::RemovePortal
189 typedef AkSpatialAudioID AkPortalID;
190 
191 ///< Unique ID for identifying geometry sets. Chosen by the client using any means desired.
192 /// \sa
193 /// - \ref AK::SpatialAudio::SetGeometry
194 /// - \ref AK::SpatialAudio::RemoveGeometry
195 typedef AkSpatialAudioID AkGeometrySetID;
196 
197 ///< Unique ID for identifying geometry set instances. Chosen by the client using any means desired.
198 /// \sa
199 /// - \ref AK::SpatialAudio::SetGeometry
200 /// - \ref AK::SpatialAudio::RemoveGeometry
201 typedef AkSpatialAudioID AkGeometryInstanceID;
AkTriIdx
AkUInt16 AkTriIdx
Definition: AkSpatialAudioTypes.h:87
AkUInt16
uint16_t AkUInt16
Unsigned 16-bit integer.
Definition: AkNumeralTypes.h:37
kDefaultDiffractionMaxPaths
const AkUInt32 kDefaultDiffractionMaxPaths
Definition: AkSpatialAudioTypes.h:54
AK
Definition of data structures for AkAudioObject.
Definition: AkWwiseSDKVersion.cs:31
ArrayPoolSpatialAudioSIMD
AkArrayAllocatorAlignedSimd< AkMemID_SpatialAudio > ArrayPoolSpatialAudioSIMD
Definition: AkSpatialAudioTypes.h:64
kRayPoolBlockAllocItemCount
const AkUInt32 kRayPoolBlockAllocItemCount
Definition: AkSpatialAudioTypes.h:56
AkRoomIDSet
AkSet< AkRoomID, ArrayPoolSpatialAudio > AkRoomIDSet
Definition: AkSpatialAudioTypes.h:161
AkSet
Definition: AkSet.h:57
ArrayPoolSpatialAudioPaths
AkArrayAllocatorNoAlign< AkMemID_SpatialAudioPaths > ArrayPoolSpatialAudioPaths
Definition: AkSpatialAudioTypes.h:66
AkGameObjectID
AkUInt64 AkGameObjectID
Game object ID.
Definition: AkTypes.h:60
AkSpatialAudioID::operator!=
bool operator!=(const AkSpatialAudioID &rhs) const
Definition: AkSpatialAudioTypes.h:110
AkRoomID::FromGameObjectID
static AkRoomID FromGameObjectID(AkGameObjectID in_fromGameObject)
Conversion function used to convert to AkGameObjectIDs to AkRoomID.
Definition: AkSpatialAudioTypes.h:148
AkRoomHierarchyID::operator!=
bool operator!=(AkRoomHierarchyID rhs) const
Definition: AkSpatialAudioTypes.h:169
ArrayPoolSpatialAudioGeometrySIMD
AkArrayAllocatorAlignedSimd< AkMemID_SpatialAudioGeometry > ArrayPoolSpatialAudioGeometrySIMD
Definition: AkSpatialAudioTypes.h:70
AkSpatialAudioID::AkSpatialAudioID
AkSpatialAudioID(AkUInt64 _id)
Construct from a 64-bit int.
Definition: AkSpatialAudioTypes.h:104
AkSurfIdx
AkUInt16 AkSurfIdx
Definition: AkSpatialAudioTypes.h:88
AK::SpatialAudio::OsString
AkString< ArrayPoolSpatialAudio, AkOSChar > OsString
OS string type for use in Wwise Spatial Audio.
Definition: AkSpatialAudioTypes.h:77
AkSpatialAudioID::AkSpatialAudioID
AkSpatialAudioID(const void *ptr)
Conversion from a pointer to a AkSpatialAudioID.
Definition: AkSpatialAudioTypes.h:107
AK::SpatialAudio::String
AkString< ArrayPoolSpatialAudio, char > String
String type for use in Wwise Spatial Audio.
Definition: AkSpatialAudioTypes.h:78
AkEdgeReceptorIdx
AkUInt16 AkEdgeReceptorIdx
Definition: AkSpatialAudioTypes.h:90
AkGeometrySetID
AkSpatialAudioID AkGeometrySetID
Definition: AkSpatialAudioTypes.h:195
AkRoomID::AsGameObjectID
AkGameObjectID AsGameObjectID() const
Conversion function used to convert AkRoomID's to AkGameObjectIDs.
Definition: AkSpatialAudioTypes.h:145
AkRoomID::AkRoomID
AkRoomID(AkUInt64 _id)
Construct from a 64-bit int.
Definition: AkSpatialAudioTypes.h:139
AkSpatialAudioID::operator<
bool operator<(const AkSpatialAudioID &rhs) const
Definition: AkSpatialAudioTypes.h:111
AkSpatialAudioID::AsGameObjectID
AkGameObjectID AsGameObjectID() const
Conversion function used internally to convert from a AkSpatialAudioID to a AkGameObjectID.
Definition: AkSpatialAudioTypes.h:120
AkSpatialAudioID
Base type for ID's used by Wwise spatial audio.
Definition: AkSpatialAudioTypes.h:99
AkSpatialAudioID::IsValid
bool IsValid() const
Determine if this ID is valid.
Definition: AkSpatialAudioTypes.h:117
kHashListBlockAllocItemCount
const AkUInt32 kHashListBlockAllocItemCount
Definition: AkSpatialAudioTypes.h:55
AkSpatialAudioID::AkSpatialAudioID
constexpr AkSpatialAudioID()
Default constructor. Creates an invalid ID.
Definition: AkSpatialAudioTypes.h:101
AkSpatialAudioID::operator<=
bool operator<=(const AkSpatialAudioID &rhs) const
Definition: AkSpatialAudioTypes.h:113
AK::SpatialAudio::kOutdoorRoomID
constexpr AkRoomID kOutdoorRoomID
The outdoor room ID. This room is created automatically and is typically used for outdoors,...
Definition: AkSpatialAudioTypes.h:179
AkRoomID::AkRoomID
constexpr AkRoomID()
Default constructor. Creates an invalid ID.
Definition: AkSpatialAudioTypes.h:136
AkEdgeIdx
AkUInt16 AkEdgeIdx
Definition: AkSpatialAudioTypes.h:89
AkRoomID::AkRoomID
AkRoomID(const void *ptr)
Conversion from a pointer to a AkRoomID.
Definition: AkSpatialAudioTypes.h:142
AkUInt64
uint64_t AkUInt64
Unsigned 64-bit integer.
Definition: AkNumeralTypes.h:39
AK::SpatialAudio::DbString
AkDbString< ArrayPoolSpatialAudio, char > DbString
Instanced string type.
Definition: AkSpatialAudioTypes.h:79
AkSpatialAudioID::operator>
bool operator>(const AkSpatialAudioID &rhs) const
Definition: AkSpatialAudioTypes.h:112
AkUInt32
uint32_t AkUInt32
Unsigned 32-bit integer.
Definition: AkNumeralTypes.h:38
AK::SpatialAudio::DbWeakString
AkDbWeakString< ArrayPoolSpatialAudio, char > DbWeakString
Weak reference to DbString. Multi-thread reading is safe.
Definition: AkSpatialAudioTypes.h:80
ArrayPoolSpatialAudio
AkArrayAllocatorNoAlign< AkMemID_SpatialAudio > ArrayPoolSpatialAudio
Definition: AkSpatialAudioTypes.h:63
AkRoomHierarchyID::operator==
bool operator==(AkRoomHierarchyID rhs) const
Definition: AkSpatialAudioTypes.h:168
AkVertIdx
AkUInt16 AkVertIdx
Definition: AkSpatialAudioTypes.h:86
AkPortalID
AkSpatialAudioID AkPortalID
Definition: AkSpatialAudioTypes.h:189
ArrayPoolSpatialAudioPathsSIMD
AkArrayAllocatorAlignedSimd< AkMemID_SpatialAudioPaths > ArrayPoolSpatialAudioPathsSIMD
Definition: AkSpatialAudioTypes.h:67
kDefaultDiffractionMaxEdges
const AkUInt32 kDefaultDiffractionMaxEdges
Definition: AkSpatialAudioTypes.h:53
kPortalToPortalDiffractionMaxPaths
const AkUInt32 kPortalToPortalDiffractionMaxPaths
Definition: AkSpatialAudioTypes.h:61
AK::SpatialAudio::WString
AkString< ArrayPoolSpatialAudio, wchar_t > WString
Wide string type for use in Wwise Spatial Audio.
Definition: AkSpatialAudioTypes.h:76
AkSpatialAudioID::operator==
bool operator==(const AkSpatialAudioID &rhs) const
Definition: AkSpatialAudioTypes.h:109
ArrayPoolSpatialAudioGeometry
AkArrayAllocatorNoAlign< AkMemID_SpatialAudioGeometry > ArrayPoolSpatialAudioGeometry
Definition: AkSpatialAudioTypes.h:69
AkRoomHierarchyID::AkRoomHierarchyID
AkRoomHierarchyID(AkRoomID in_roomID)
Definition: AkSpatialAudioTypes.h:167
AkSpatialAudioID::operator>=
bool operator>=(const AkSpatialAudioID &rhs) const
Definition: AkSpatialAudioTypes.h:114
kDiffractionMaxEdges
const AkUInt32 kDiffractionMaxEdges
Definition: AkSpatialAudioTypes.h:59
kDiffractionMaxPaths
const AkUInt32 kDiffractionMaxPaths
Definition: AkSpatialAudioTypes.h:60
AkGeometryInstanceID
AkSpatialAudioID AkGeometryInstanceID
Definition: AkSpatialAudioTypes.h:201

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