Version
menu_open
Wwise SDK 2023.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) 2024 Audiokinetic Inc.
25 *******************************************************************************/
26 
27 /// \file
28 /// Spatial audio data type definitions.
29 
30 #pragma once
31 
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 8
46 #define AK_SA_EPSILON (0.001f)
47 #define AK_SA_DIFFRACTION_EPSILON (0.002f) // Radians
48 #define AK_SA_DIFFRACTION_DOT_EPSILON (0.000002) // 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 
56 const AkUInt32 kHashListBlockAllocItemCount = 50; // Number of items per block to allocate for in AkStochasticCollectionHashList
57 
58 // Max values that are used for calculating diffraction paths between the listener and a portal.
62 
65 
68 
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, CAkLock> DbString; ///< Instanced string type.
80 
81  typedef AkUInt16 Idx;
82  }
83 }
84 
90 
91 #define AK_INVALID_VERTEX ((AkVertIdx)(-1))
92 #define AK_INVALID_TRIANGLE ((AkTriIdx)(-1))
93 #define AK_INVALID_SURFACE ((AkSurfIdx)(-1))
94 #define AK_INVALID_EDGE ((AkEdgeIdx)(-1))
95 
96 /// Base type for ID's used by Wwise spatial audio.
98 {
99  /// Default constructor. Creates an invalid ID.
100  constexpr AkSpatialAudioID() : id((AkUInt64)-1) {}
101 
102  /// Construct from a 64-bit int.
103  AkSpatialAudioID(AkUInt64 _id) : id(_id) {}
104 
105  /// Conversion from a pointer to a AkSpatialAudioID
106  explicit AkSpatialAudioID(const void * ptr) : id(reinterpret_cast<AkUInt64>(ptr)) {}
107 
108  bool operator == (AkSpatialAudioID rhs) const { return id == rhs.id; }
109  bool operator != (AkSpatialAudioID rhs) const { return id != rhs.id; }
110  bool operator < (AkSpatialAudioID rhs) const { return id < rhs.id; }
111  bool operator > (AkSpatialAudioID rhs) const { return id > rhs.id; }
112  bool operator <= (AkSpatialAudioID rhs) const { return id <= rhs.id; }
113  bool operator >= (AkSpatialAudioID rhs) const { return id >= rhs.id; }
114 
115  /// Determine if this ID is valid.
116  bool IsValid() const { return id != (AkUInt64)-1; }
117 
118  /// Conversion function used internally to convert from a AkSpatialAudioID to a AkGameObjectID.
120 
121  operator</span> AkUInt64 () const { return id; }
122 
124 };
125 
126 /// 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
127 /// 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
128 /// represent rooms using AkRoomID's provided by the client; AkRoomID's are converted to AkGameObjectID's by calling AsGameObjectID().
129 /// \sa
130 /// - \ref AK::SpatialAudio::SetRoom
131 /// - \ref AK::SpatialAudio::RemoveRoom
132 struct AkRoomID : public AkSpatialAudioID
133 {
134  /// Default constructor. Creates an invalid ID.
135  constexpr AkRoomID() : AkSpatialAudioID() {}
136 
137  /// Construct from a 64-bit int.
139 
140  /// Conversion from a pointer to a AkRoomID
141  explicit AkRoomID(const void * ptr) : AkSpatialAudioID(ptr) {}
142 
143  /// Conversion function used to convert AkRoomID's to AkGameObjectIDs.
144  AkGameObjectID AsGameObjectID() const { return IsValid() ? (AkGameObjectID)id : OutdoorsGameObjID; }
145 
146  /// Conversion function used to convert to AkGameObjectIDs to AkRoomID.
147  static AkRoomID FromGameObjectID(AkGameObjectID in_fromGameObject)
148  {
149  AkRoomID id;
150  if (in_fromGameObject != OutdoorsGameObjID)
151  id.id = (AkUInt64)in_fromGameObject;
152  return id;
153  }
154 
155 private:
156  /// A game object ID that is in the reserved range, used for 'outdoor' rooms, i.e. when not in a room.
157  /// \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
158  static const AkGameObjectID OutdoorsGameObjID = (AkGameObjectID)-4;
159 };
161 
162 
164 {
166  explicit AkRoomHierarchyID(AkRoomID in_roomID) : id(in_roomID) {}
167  bool operator == (AkRoomHierarchyID rhs) const { return id == rhs.id; }
168  bool operator != (AkRoomHierarchyID rhs) const { return id != rhs.id; }
169 
171 };
172 
173 namespace AK
174 {
175  namespace SpatialAudio
176  {
177  /// The outdoor room ID. This room is created automatically and is typically used for outdoors, i.e. when not in a room.
179  }
180 }
181 
182 ///< 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
183 /// 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
184 /// represent portals using AkPortalID's provided by the client; AkPortalID's are convertied to AkGameObjectID's by calling AsGameObjectID().
185 /// \sa
186 /// - \ref AK::SpatialAudio::SetPortal
187 /// - \ref AK::SpatialAudio::RemovePortal
189 
190 ///< Unique ID for identifying geometry sets. Chosen by the client using any means desired.
191 /// \sa
192 /// - \ref AK::SpatialAudio::SetGeometry
193 /// - \ref AK::SpatialAudio::RemoveGeometry
195 
196 ///< Unique ID for identifying geometry set instances. Chosen by the client using any means desired.
197 /// \sa
198 /// - \ref AK::SpatialAudio::SetGeometry
199 /// - \ref AK::SpatialAudio::RemoveGeometry
AkUInt16 AkTriIdx
bool operator>(AkSpatialAudioID rhs) const
uint16_t AkUInt16
Unsigned 16-bit integer.
const AkUInt32 kDefaultDiffractionMaxPaths
Audiokinetic namespace.
AkArrayAllocatorAlignedSimd< AkMemID_SpatialAudio > ArrayPoolSpatialAudioSIMD
AkSet< AkRoomID, ArrayPoolSpatialAudio > AkRoomIDSet
Definition: AkSet.h:57
AkArrayAllocatorNoAlign< AkMemID_SpatialAudioPaths > ArrayPoolSpatialAudioPaths
AkUInt64 AkGameObjectID
Game object ID.
Definition: AkTypes.h:60
static AkRoomID FromGameObjectID(AkGameObjectID in_fromGameObject)
Conversion function used to convert to AkGameObjectIDs to AkRoomID.
bool operator!=(AkRoomHierarchyID rhs) const
AkArrayAllocatorAlignedSimd< AkMemID_SpatialAudioGeometry > ArrayPoolSpatialAudioGeometrySIMD
AkSpatialAudioID(AkUInt64 _id)
Construct from a 64-bit int.
AkDbString< ArrayPoolSpatialAudio, char, CAkLock > DbString
Instanced string type.
float AkReal32
32-bit floating point
AkUInt16 AkSurfIdx
bool operator==(AkSpatialAudioID rhs) const
bool operator!=(AkSpatialAudioID rhs) const
const AkReal32 kMaxDiffraction
AkString< ArrayPoolSpatialAudio, AkOSChar > OsString
OS string type for use in Wwise Spatial Audio.
AkSpatialAudioID(const void *ptr)
Conversion from a pointer to a AkSpatialAudioID.
AkString< ArrayPoolSpatialAudio, char > String
String type for use in Wwise Spatial Audio.
AkUInt16 AkEdgeReceptorIdx
AkSpatialAudioID AkGeometrySetID
AkGameObjectID AsGameObjectID() const
Conversion function used to convert AkRoomID's to AkGameObjectIDs.
AkRoomID(AkUInt64 _id)
Construct from a 64-bit int.
bool operator>=(AkSpatialAudioID rhs) const
AkGameObjectID AsGameObjectID() const
Conversion function used internally to convert from a AkSpatialAudioID to a AkGameObjectID.
Base type for ID's used by Wwise spatial audio.
bool IsValid() const
Determine if this ID is valid.
const AkUInt32 kHashListBlockAllocItemCount
constexpr AkSpatialAudioID()
Default constructor. Creates an invalid ID.
bool operator<(AkSpatialAudioID rhs) const
constexpr AkRoomID kOutdoorRoomID
The outdoor room ID. This room is created automatically and is typically used for outdoors,...
constexpr AkRoomID()
Default constructor. Creates an invalid ID.
AkUInt16 AkEdgeIdx
AkRoomID(const void *ptr)
Conversion from a pointer to a AkRoomID.
uint64_t AkUInt64
Unsigned 64-bit integer.
bool operator<=(AkSpatialAudioID rhs) const
uint32_t AkUInt32
Unsigned 32-bit integer.
AkArrayAllocatorNoAlign< AkMemID_SpatialAudio > ArrayPoolSpatialAudio
bool operator==(AkRoomHierarchyID rhs) const
AkUInt16 AkVertIdx
AkSpatialAudioID AkPortalID
AkArrayAllocatorAlignedSimd< AkMemID_SpatialAudioPaths > ArrayPoolSpatialAudioPathsSIMD
const AkUInt32 kDefaultDiffractionMaxEdges
const AkUInt32 kPortalToPortalDiffractionMaxPaths
AkString< ArrayPoolSpatialAudio, wchar_t > WString
Wide string type for use in Wwise Spatial Audio.
AkArrayAllocatorNoAlign< AkMemID_SpatialAudioGeometry > ArrayPoolSpatialAudioGeometry
AkRoomHierarchyID(AkRoomID in_roomID)
const AkUInt32 kDiffractionMaxEdges
const AkUInt32 kDiffractionMaxPaths
AkSpatialAudioID AkGeometryInstanceID

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