Version
menu_open
Wwise SDK 2019.1.11
AkSpatialAudio.h
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 Version: <VERSION> Build: <BUILDNUMBER>
25 Copyright (c) <COPYRIGHTYEAR> Audiokinetic Inc.
26 *******************************************************************************/
27 
28 /// \file
29 /// Spatial Audio interface.
30 
31 #pragma once
32 
33 #include <AK/SpatialAudio/Common/AkSpatialAudioTypes.h>
34 #include <AK/Plugin/AkReflectGameData.h>
35 #include <AK/SoundEngine/Common/AkSoundEngine.h>
36 
37 /// AkDiffractionFlags determine if diffraction values for sound passing through portals will be calculated, and how to apply those calculations to Wwise parameters.
38 enum AkDiffractionFlags
39 {
40  DiffractionFlags_UseBuiltInParam = 1 << 0, ///< Set the Wwise built-in game parameter value for diffraction angle. This is a flexible approach that can be mapped to any Wwise parameter. Can also be used simply to monitor diffraction using the game object profiler in Wwise.
41  DiffractionFlags_UseObstruction = 1 << 1, ///< Use Wwise obstruction for dry-path diffraction. Dry-path diffraction is related to the angle off of a straight line of sight to a sound emitter.
42  DiffractionFlags_CalcEmitterVirtualPosition = 1 << 3, ///< An emitter that is not in the same room as the listener will have its apparent or virtual position calculated by Wwise spatial audio and passed on to the sound engine.
43 
44  DefaultDiffractionFlags = DiffractionFlags_UseBuiltInParam | DiffractionFlags_UseObstruction | DiffractionFlags_CalcEmitterVirtualPosition
45 };
46 
47 /// Initialization settings of the spatial audio module.
48 struct AkSpatialAudioInitSettings
49 {
50  AkSpatialAudioInitSettings() : uPoolID(AK_INVALID_POOL_ID)
51  , uPoolSize(4 * 1024 * 1024)
52  , uMaxSoundPropagationDepth(AK_MAX_SOUND_PROPAGATION_DEPTH)
53  , uDiffractionFlags((AkUInt32)DefaultDiffractionFlags)
54  , fDiffractionShadowAttenFactor(AK_DEFAULT_DIFFR_SHADOW_ATTEN)
55  , fDiffractionShadowDegrees(AK_DEFAULT_DIFFR_SHADOW_DEGREES)
56  , fMovementThreshold(AK_DEFAULT_MOVEMENT_THRESHOLD)
57  {}
58 
59  AkMemPoolId uPoolID; ///< User-provided pool ID (see AK::MemoryMgr::CreatePool).
60  AkUInt32 uPoolSize; ///< Desired memory pool size if a new pool should be created. A pool will be created if uPoolID is not set (AK_INVALID_POOL_ID).
61  AkUInt32 uMaxSoundPropagationDepth; ///< Maximum number of portals that sound can propagate through; must be less than or equal to AK_MAX_SOUND_PROPAGATION_DEPTH.
62  AkUInt32 uDiffractionFlags; ///< Enable or disable specific diffraction features. See AkDiffractionFlags.
63  AkReal32 fDiffractionShadowAttenFactor; ///< Multiplier that is applied to the distance attenuation of diffracted sounds (sounds that are in the 'shadow region') to simulate the phenomenon where by diffracted sound waves decay faster than incident sound waves.
64  AkReal32 fDiffractionShadowDegrees; ///< Interpolation angle, in degrees, over which the fDiffractionShadowAttenFactor is applied.
65  ///< At a diffraction of 0, a multiplier of 1 (ie. none) is applied, and at an angle of fDiffractionShadowDegrees or greater, fDiffractionShadowAttenFactor is applied.
66  ///< A linear interpolation between 1 and fDiffractionShadowAttenFactor is applied when the angle is between 0 and fDiffractionShadowDegrees.
67 
68  AkReal32 fMovementThreshold; ///< Amount that an emitter or listener has to move to trigger a recalculation of reflections/diffraction. Larger values can reduce the CPU load at the cost of reduced accuracy.
69 };
70 
71 // Settings for individual image sources.
72 struct AkImageSourceSettings
73 {
74  AkImageSourceSettings() {}
75 
76  AkImageSourceSettings(AkVector in_sourcePosition, AkReal32 in_fDistanceScalingFactor, AkReal32 in_fLevel)
77  : params(in_sourcePosition, in_fDistanceScalingFactor, in_fLevel)
78  , texture()
79  , name()
80  {
81  }
82 
83  ~AkImageSourceSettings()
84  {
85  name.Term();
86  }
87 
88  /// Operator =
89  AkImageSourceSettings& operator =(const AkImageSourceSettings & src)
90  {
91  params = src.params;
92  texture = src.texture;
93  name = src.name;
94  name.AllocCopy();
95  return *this;
96  }
97 
98  void SetOneTexture(AkUniqueID in_texture)
99  {
100  texture.uNumTexture = 1;
101  texture.arTextureID[0] = in_texture;
102  }
103 
104  void SetName(const char* in_pName)
105  {
106  name = in_pName;
107  name.AllocCopy();
108  }
109 
110  /// Image source parameters.
111  AkImageSourceParams params;
112 
113  /// Acoustic texture that goes with this image source.
114  AkImageSourceTexture texture;
115 
116  /// Name given to image source, can be used to identify the image source in the AK Reflect plugin UI.
117  AK::SpatialAudio::String name;
118 };
119 
120 /// Settings for a sound emitter.
121 struct AkEmitterSettings
122 {
123  /// Constructor
124  AkEmitterSettings() : reflectAuxBusID(AK_INVALID_UNIQUE_ID)
125  , reflectionMaxPathLength(kDefaultMaxPathLength)
126  , reflectionsAuxBusGain(1.0f)
127  , reflectionsOrder(1)
128  , reflectorFilterMask(0xFFFFFFFF)
129  , roomReverbAuxBusGain(1.0f)
130  , diffractionMaxEdges(kDefaultDiffractionMaxEdges)
131  , diffractionMaxPaths(kDefaultDiffractionMaxPaths)
132  , diffractionMaxPathLength(0.f)
133  {
134  useImageSources = true;
135  }
136 
137  /// Name given to this sound emitter.
138  AK::SpatialAudio::OsString name;
139 
140  /// Aux bus with the AkReflect plug-in that is used by the geometric reflections API. Set to AK_INVALID_UNIQUE_ID to disable geometric reflections.
141  /// \aknote For proper operation with AkReflect and the SpatialAudio API, any aux bus using AkReflect should have 'Listener Relative Routing' checked and the 3D Spatialization set to None in the Wwise authoring tool. See \ref spatial_audio_wwiseprojectsetup_businstances for more details. \endaknote
142  AkUniqueID reflectAuxBusID;
143 
144  /// A heuristic to stop the computation of reflections, and reduce the search space for reflective surfaces. Should be no longer (and possibly shorter for less CPU usage) than the maximum attenuation of
145  /// the reflections, as defined in the AkReflect plug-in.
146  /// Setting \c reflectionMaxPathLength is critical for performance. This value should be set as small as possible to reduce the number of possible surfaces to consider for reflections.
147  /// Setting \c reflectionMaxPathLength to 0.f effectively disables reflection processing for this sound emitter.
148  AkReal32 reflectionMaxPathLength;
149 
150  /// Send gain (0.f-1.f) that is applied when sending to the bus that has the AkReflect plug-in. (reflectAuxBusID)
151  AkReal32 reflectionsAuxBusGain;
152 
153  /// Maximum number of reflections that will be processed when computing indirect paths via the geometric reflections API. Reflection processing grows
154  /// exponentially with the order of reflections, so this number should be kept low. Valid range: 1-4.
155  /// Setting \c reflectionsOrder to 0 effectively disables reflection processing for this sound emitter.
156  /// A good starting point is 1 (1st order reflections). \c reflectionsOrder can be increased to 2 or more if geometry is sufficiently simple, and there are a low number of sound emitters that need reflection processing at a given time.
157  AkUInt32 reflectionsOrder;
158 
159  /// Bit field that allows for filtering of reflector surfaces (triangles) for this sound emitter. Setting/or clearing bits that correspond to the same bits set in
160  /// the \c reflectorChannelMask of each \c AkTriangle can be used to filter out specific geometry for specific emitters. An example usage is to disable reflections
161  /// off the floor for sounds positioned at the camera. When processing the reflections, this bit mask is ANDed with each potential triangle's reflectorChannelMask to determine if the reflector/emitter pair can produce a valid hit.
162  AkUInt32 reflectorFilterMask;
163 
164  /// Send gain (0.f-1.f) that is applied when sending to the bus that is associated with the room that the emitter is in (assigned via ReverbAuxBus field of AkRoomParams).
165  /// This value is multiplied with the room-specific gain (ReverbLevel of AkRoomParams). Note that this value is not applied to aux sends that are set via SetEmitterAuxSendValues(),
166  /// and therefore may be used to scale and/or disable room reverb, either temporarily or permanently, for a specific emitter.
167  /// \sa
168  /// - \ref AkRoomParams
169  /// - \ref AK::SpatialAudio::SetEmitterAuxSendValues
170  AkReal32 roomReverbAuxBusGain;
171 
172  /// The maximum number of edges that the sound can diffract around between the emitter and the listener, or the emitter and a single portal. Applies only to geometric diffraction, and not to sound propagation through rooms and portals.
173  /// Setting \c diffractionMaxEdges to 0 effectively disables geometric diffraction for this sound emitter.
174  /// When using geometric diffraction, the default value is a good starting point.
175  AkUInt32 diffractionMaxEdges;
176 
177  /// The maximum number of paths to the listener that the sound can take around obstacles between the emitter and the listener, or the emitter and a single portal. Applies only to geometric diffraction, and not sound propagation through rooms and portals.
178  /// Diffraction paths map directly to virtual sound positions. Setting \c diffractionMaxPaths limits the number sound positions that are rendered for the game object.
179  /// Setting \c diffractionMaxPaths to 0 effectively disables geometric diffraction for this sound emitter.
180  /// When using geometric diffraction, the default value is a good starting point.
181  AkUInt32 diffractionMaxPaths;
182 
183  /// The maximum length of a geometric diffraction path between the emitter and the listener, in the case that they are in the same room. When the emitter and listener are in different rooms, this value represents
184  /// the maximum possible diffracted path-segment length between the emitter and a portal (in the same room as the emitter). When the listener and emitter are in different rooms, calculated paths
185  /// between the listener and portals, and/or those between two portals, are shared between all emitters requiring them, and so are not subject to \c diffractionMaxPathLength. The final path from the emitter to the listener may
186  /// end up being longer than \c diffractionMaxPathLength, when the total path traverses a number of rooms and portals.
187  /// Should generally be no longer (and possibly shorter for less CPU usage) than the maximum attenuation used on the sound emitter.
188  /// Setting \c diffractionMaxPathLength to 0 effectively disables geometric diffraction for this sound emitter.
189  /// When using geometric diffraction, a good starting point is the maximum possible distance that the sound should travel.
190  AkReal32 diffractionMaxPathLength;
191 
192  /// Enable reflections from image sources that have been added via the \c AK::SpatialAudio::SetImageSource() API. (Does not apply to geometric reflections.)
193  AkUInt8 useImageSources : 1;
194 };
195 
196 /// Vertex for a spatial audio mesh.
197 struct AkVertex
198 {
199  /// Constructor
200  AkVertex() : X(0.f), Y(0.f), Z(0.f) {}
201 
202  /// Constructor
203  AkVertex(AkReal32 in_X, AkReal32 in_Y, AkReal32 in_Z) : X(in_X), Y(in_Y), Z(in_Z) {}
204 
205  AkReal32 X; ///< X coordinate
206  AkReal32 Y; ///< Y coordinate
207  AkReal32 Z; ///< Z coordinate
208 };
209 
210 /// Triangle for a spatial audio mesh.
211 struct AkTriangle
212 {
213  /// Constructor
214  AkTriangle() : point0(AK_INVALID_VERTEX)
215  , point1(AK_INVALID_VERTEX)
216  , point2(AK_INVALID_VERTEX)
217  , surface(AK_INVALID_SURFACE)
218  {}
219 
220  /// Constructor
221  AkTriangle(AkVertIdx in_pt0, AkVertIdx in_pt1, AkVertIdx in_pt2, AkSurfIdx in_surfaceInfo)
222  : point0(in_pt0)
223  , point1(in_pt1)
224  , point2(in_pt2)
225  , surface(in_surfaceInfo)
226  {}
227 
228  /// Index into the vertex table passed into \c AkGeometryParams that describes the first vertex of the triangle. Triangles are double-sided, so vertex order in not important.
229  AkVertIdx point0;
230 
231  /// Index into the vertex table passed into \c AkGeometryParams that describes the second vertex of the triangle. Triangles are double-sided, so vertex order in not important.
232  AkVertIdx point1;
233 
234  /// Index into the vertex table passed into \c AkGeometryParams that describes the third vertex of the triangle. Triangles are double-sided, so vertex order in not important.
235  AkVertIdx point2;
236 
237  /// Index into the surface table passed into \c AkGeometryParams that describes the surface properties of the triangle.
238  /// If this field is left as \c AK_INVALID_SURFACE, then a default-constructed \c AkAcousticSurface is used.
239  AkSurfIdx surface;
240 };
241 
242 /// Describes the acoustic surface properties of one or more triangles.
243 /// An single acoustic surface may describe any number of triangles, depending on the granularity desired. For example, if desired for debugging, one could create a unique
244 /// \c AkAcousticSurface struct for each triangle, and define a unique name for each. Alternatively, a single \c AkAcousticSurface could be used to describe all triangles.
245 /// In fact it is not necessary to define any acoustic surfaces at all. If the \c AkTriangle::surface field is left as \c AK_INVALID_SURFACE, then a default-constructed \c AkAcousticSurface is used.
246 struct AkAcousticSurface
247 {
248  /// Constructor
249  AkAcousticSurface(): textureID(AK_INVALID_UNIQUE_ID)
250  , reflectorChannelMask((AkUInt32)-1)
251  , strName(NULL)
252  {}
253 
254  /// Acoustic texture ShareSet ID for the surface. The acoustic texture is authored in Wwise, and the shareset ID may be obtained by calling \c AK::SoundEngine::GetIDFromString
255  /// \sa <tt>\ref AK::SoundEngine::GetIDFromString()</tt>
256  AkUInt32 textureID;
257 
258  /// Bitfield of channels that this surface belongs to. When processing the reflections, this bit mask is ANDed with each of the emitter's <tt>reflectorFilterMask</tt>s to determine if the reflector/emitter pair can produce a valid hit.
259  AkUInt32 reflectorChannelMask;
260 
261  /// Name to describe this surface
262  const char* strName;
263 };
264 
265 /// Structure for retrieving information about the indirect paths of a sound that have been calculated via the geometric reflections API. Useful for debug draw applications.
266 struct AkReflectionPathInfo
267 {
268  /// Apparent source of the reflected sound that follows this path.
269  AkVector imageSource;
270 
271  /// Vertices of the indirect path.
272  /// pathPoint[0] is closest to the emitter, pathPoint[numPathPoints-1] is closest to the listener.
273  AkVector pathPoint[AK_MAX_REFLECTION_PATH_LENGTH];
274 
275  /// The surfaces that were hit in the path.
276  /// surfaces[0] is closest to the emitter, surfaces[numPathPoints-1] is closest to the listener.
277  AkAcousticSurface surfaces[AK_MAX_REFLECTION_PATH_LENGTH];
278 
279  /// Number of valid elements in the \c pathPoint[], \c surfaces[], and \c diffraction[] arrays.
280  AkUInt32 numPathPoints;
281 
282  /// Number of reflections in the \c pathPoint[] array. Shadow zone diffraction does not count as a reflection. If there is no shadow zone diffraction, \c numReflections is equal to \c numPathPoints.
283  AkUInt32 numReflections;
284 
285  /// Diffraction amount, normalized to the range [0,1]
286  AkReal32 diffraction[AK_MAX_REFLECTION_PATH_LENGTH];
287 
288  /// Linear gain applied to image source.
289  AkReal32 level;
290 
291  /// True if the sound path was occluded. Note that the spatial audio library must be recompiled with \c \#define AK_DEBUG_OCCLUSION to enable generation of occluded paths.
292  bool isOccluded;
293 };
294 
295 /// Structure for retrieving information about diffraction paths for a given emitter.
296 /// The diffraction paths represent indirect sound paths from the emitter to the listener, whether they go through portals
297 /// (via the rooms and portals API) or are diffracted around edges (via the geometric diffraction API).
298 struct AkDiffractionPathInfo
299 {
300  /// Defines the maximum number of nodes that a user can retrieve information about. Longer paths will be truncated.
301  static const AkUInt32 kMaxNodes = AK_MAX_SOUND_PROPAGATION_DEPTH;
302 
303  /// Diffraction points along the path. nodes[0] is the point closest to the listener; nodes[numNodes-1] is the point closest to the emitter.
304  /// Neither the emitter position nor the listener position are represented in this array.
305  AkVector nodes[kMaxNodes];
306 
307  /// Raw diffraction angles at each point, in radians.
308  AkReal32 angles[kMaxNodes];
309 
310  /// ID of the portals that the path passes through. For a given node at position i (in the nodes array), if the path diffracts on a geometric edge, then portals[i] will be an invalid portal ID (ie. portals[i].IsValid() will return false).
311  /// Otherwise, if the path diffracts through a portal at position i, then portals[i] will be the ID of that portal.
312  /// portal[0] represents the node closest to the listener; portal[numNodes-1] represents the node closest to the emitter.
313  AkPortalID portals[kMaxNodes];
314 
315  /// ID's of the rooms that the path passes through. For a given node at position i, room[i] is the room on the listener's side of the node. If node i diffracts through a portal,
316  /// then rooms[i] is on the listener's side of the portal, and rooms[i+1] is on the emitters side of the portal.
317  /// There is always one extra slot for a room so that the emitters room is always returned in slot room[numNodes] (assuming the path has not been truncated).
318  AkRoomID rooms[kMaxNodes + 1];
319 
320  /// Virtual emitter position. This is the position that is passed to the sound engine to render the audio using multi-positioning, for this particular path.
321  AkTransform virtualPos;
322 
323  /// Total number of nodes in the path. Defines the number of valid entries in the \c nodes, \c angles, and \c portals arrays. The \c rooms array has one extra slot to fit the emitter's room.
324  AkUInt32 nodeCount;
325 
326  /// Calculated total diffraction from this path, normalized to the range [0,1]
327  /// The diffraction amount is calculated from the sum of the deviation angles from a straight line, of all angles at each nodePoint.
328  // Can be thought of as how far into the 'shadow region' the sound has to 'bend' to reach the listener.
329  /// Depending on the spatial audio initialization settings, this value is applied internally, by spatial audio, to the obstruction or built-in parameter of the emitter game object.
330  /// \sa
331  /// - \ref AkDiffractionFlags
332  /// - \ref AkSpatialAudioInitSettings
333  AkReal32 diffraction;
334 
335  /// Total path length
336  /// Represents the sum of the length of the individual segments between nodes, with a correction factor applied for diffraction.
337  /// The correction factor simulates the phenomenon where by diffracted sound waves decay faster than incident sound waves and can be customized in the spatial audio init settings.
338  /// \sa
339  /// - \ref AkSpatialAudioInitSettings
340  AkReal32 totLength;
341 
342  /// Obstruction value for this path
343  /// This value includes the accumulated portal obstruction for all portals along the path. In the case that no valid diffraction paths are found, this value is set to 1.0.
344  /// The obstruction value sent to the sound engine is normally calculated from the result of the \c diffraction calculation, and then max'ed with the portal obstruciton value.
345  /// If no path is found between the emitter and listener or if the maximum path length for a given sound is exceeded, the sound engine is sent 1.0 for obstruction.
346  /// In this case \c obstructionValue is set to 1.0, and \c nodeCount is set to 0. The maximum path length for an emitter is defined in \c AkEmitterSettings.
347  /// \sa
348  /// - \ref AkEmitterSettings
349  AkReal32 obstructionValue;
350 };
351 
352 /// Parameters passed to \c SetPortal
353 struct AkPortalParams
354 {
355  /// Constructor
356  AkPortalParams() :
357  bEnabled(false)
358  {}
359 
360  /// Portal's position and orientation in the 3D world.
361  /// Position vector is the center of the opening.
362  /// OrientationFront vector must be unit-length and point along the normal of the portal, and must be orthogonal to Up. It defines the local positive-Z dimension (depth/transition axis) of the portal, used by Extent.
363  /// OrientationTop vector must be unit-length and point along the top of the portal (tangent to the wall), must be orthogonal to Front. It defines the local positive-Y direction (height) of the portal, used by Extent.
364  AkTransform Transform;
365 
366  /// Portal extent. Defines the dimensions of the portal relative to its center; all components must be positive numbers. The local X and Y dimensions (side and top) are used in diffraction calculations,
367  /// whereas the Z dimension (front) defines a depth value which is used to implement smooth transitions between rooms. It is recommended that users experiment with different portal depths to find a value
368  /// that results in appropriately smooth transitions between rooms.
369  AkVector Extent;
370 
371  /// Whether or not the portal is active/enabled. For example, this parameter may be used to simulate open/closed doors.
372  /// Portal diffraction is simulated when at least one portal exists and is active between an emitter and the listener. Otherwise, transmission is simulated.
373  /// Diffraction uses obstruction or the diffraction built-in game parameter, while transmission uses occlusion.
374  bool bEnabled;
375 
376  /// Name used to identify portal (optional).
377  AK::SpatialAudio::OsString strName;
378 
379  /// ID of the room to which the portal connects, in the direction of the Front vector. If a room with this ID has not been added via AK::SpatialAudio::SetRoom,
380  /// a room will be created with this ID and with default AkRoomParams. If you would later like to update the AkRoomParams, simply call AK::SpatialAudio::SetRoom again with this same ID.
381  /// - \ref AK::SpatialAudio::SetRoom
382  /// - \ref AK::SpatialAudio::RemoveRoom
383  /// - \ref AkRoomParams
384  AkRoomID FrontRoom;
385 
386  /// ID of the room to which the portal connects, in the direction opposite to the Front vector. If a room with this ID has not been added via AK::SpatialAudio::SetRoom,
387  /// a room will be created with this ID and with default AkRoomParams. If you would later like to update the AkRoomParams, simply call AK::SpatialAudio::SetRoom again with this same ID.
388  /// - \ref AK::SpatialAudio::SetRoom
389  /// - \ref AK::SpatialAudio::RemoveRoom
390  /// - \ref AkRoomParams
391  AkRoomID BackRoom;
392 };
393 
394 /// Parameters passed to \c SetRoom
395 struct AkRoomParams
396 {
397  /// Constructor
398  AkRoomParams() : ReverbAuxBus(AK_INVALID_AUX_ID)
399  , ReverbLevel(1.f)
400  , WallOcclusion(1.f)
401  , RoomGameObj_AuxSendLevelToSelf(0.f)
402  , RoomGameObj_KeepRegistered(false)
403 
404  {
405  Up.X = 0.f;
406  Up.Y = 1.f;
407  Up.Z = 0.f;
408  Front.X = 0.f;
409  Front.Y = 0.f;
410  Front.Z = 1.f;
411  }
412 
413  /// Room Orientation. Up and Front must be orthonormal.
414  /// Room orientation has an effect when the associated aux bus (see ReverbAuxBus) is set with 3D Spatialization in Wwise, as 3D Spatialization implements relative rotation of the emitter (room) and listener.
415  AkVector Up;
416  AkVector Front;
417 
418  /// The reverb aux bus that is associated with this room.
419  /// When Spatial Audio is told that a game object is in a particular room via SetGameObjectInRoom, a send to this aux bus will be created to model the reverb of the room.
420  /// Using a combination of Rooms and Portals, Spatial Audio manages which game object the aux bus is spawned on, and what control gain is sent to the bus.
421  /// When a game object is inside a connected portal, as defined by the portal's orientation and extent vectors, both this aux send and the aux send of the adjacent room are active.
422  /// Spatial audio modulates the control value for each send based on the game object's position, in relation to the portal's z-azis and extent, to crossfade the reverb between the two rooms.
423  /// If more advanced control of reverb is desired, SetEmitterAuxSendValues can be used to add additional sends on to a game object.
424  /// - \ref AK::SpatialAudio::SetGameObjectInRoom
425  /// - \ref AK::SpatialAudio::SetEmitterAuxSendValues
426  AkAuxBusID ReverbAuxBus;
427 
428  /// The reverb control value for the send to ReverbAuxBus. Valid range: (0.f-1.f)
429  /// Can be used to implement multiple rooms that share the same aux bus, but have different reverb levels.
430  AkReal32 ReverbLevel;
431 
432  /// Occlusion level to set when modeling transmission through walls. Transmission is modeled only when no sound propagation paths to the listener are found, meaning that there are no active portals between the listener's
433  /// room and the emitter's room. Valid range: (0.f-1.f)
434  AkReal32 WallOcclusion;
435 
436  /// Name used to identify room (optional)
437  AK::SpatialAudio::OsString strName;
438 
439  /// Send level for sounds that are posted on the room game object; adds reverb to ambience and room tones. Valid range: (0.f-1.f). Set to a value greater than 0 to have spatial audio create a send on the room game object,
440  /// where the room game object itself is specified as the listener and ReverbAuxBus is specified as the aux bus. A value of 0 disables the aux send. This should not be confused with ReverbLevel, which is the send level
441  /// for spatial audio emitters sending to the room game object.
442  /// \aknote The room game object can be accessed though the ID that is passed to \c SetRoom() and the \c AkRoomID::AsGameObjectID() method. Posting an event on the room game object leverages automatic room game object placement
443  /// by spatial audio so that when the listener is inside the room, the sound comes from all around the listener, and when the listener is outside the room, the sound comes from the portal(s). Typically, this would be used for
444  /// surround ambiance beds or room tones. Point source sounds should use separate game objects that are registered as spatial audio emitters.
445  /// \sa
446  /// - \ref AkRoomParams::RoomGameObj_KeepRegistered
447  /// - \ref AkRoomID
448  AkReal32 RoomGameObj_AuxSendLevelToSelf;
449 
450  /// If set to true, the room game object will be registered on calling \c SetRoom(), and not released untill the room is deleted or removed with \c RemoveRoom(). If set to false, spatial audio will register
451  /// the room object only when it is needed by the sound propagation system for the purposes of reverb, and will unregister the game object when all reverb tails have finished.
452  /// If the game intends to post events on the room game object for the purpose of ambiance or room tones, RoomGameObj_KeepRegistered should be set to true.
453  /// \aknote The room game object can be accessed though the ID that is passed to \c SetRoom() and the \c AkRoomID::AsGameObjectID() method. Posting an event on the room game object leverages automatic room game object placement
454  /// by spatial audio so that when the listener is inside the room, the sound comes from all around the listener, and when the listener is outside the room, the sound comes from the portal(s). Typically, this would be used for
455  /// surround ambiance beds or room tones. Point source sounds should use separate game objects that are registered as spatial audio emitters.
456  /// \sa
457  /// - \ref AkRoomParams::RoomGameObj_AuxSendLevelToSelf
458  /// - \ref AkRoomID
459  bool RoomGameObj_KeepRegistered;
460 
461 
462 };
463 
464 /// Parameters passed to \c SetGeometry
465 struct AkGeometryParams
466 {
467  /// Constructor
468  AkGeometryParams() : Triangles(NULL), NumTriangles(0), Vertices(NULL), NumVertices(0), Surfaces(NULL), NumSurfaces(0), EnableDiffraction(false), EnableDiffractionOnBoundaryEdges(false) {}
469 
470  /// Pointer to an array of AkTriangle structures.
471  /// This array will be copied into the spatial audio memory pool and will not be accessed after \c SetGeometry returns.
472  /// - \ref AkTriangle
473  /// - \ref AK::SpatialAudio::SetGeometry
474  /// - \ref AK::SpatialAudio::RemoveGeometry
475  AkTriangle* Triangles;
476 
477  /// Number of triangles in Triangles.
478  AkTriIdx NumTriangles;
479 
480  /// Pointer to an array of AkVertex structures.
481  /// This array will be copied into the spatial audio memory pool and will not be accessed after \c SetGeometry returns.
482  /// - \ref AkVertex
483  /// - \ref AK::SpatialAudio::SetGeometry
484  /// - \ref AK::SpatialAudio::RemoveGeometry
485  AkVertex* Vertices;
486 
487  ///< Number of vertices in Vertices.
488  AkVertIdx NumVertices;
489 
490  ///< Pointer to an array of AkAcousticSurface structures.
491  /// This array will be copied into the spatial audio memory pool and will not be accessed after \c SetGeometry returns.
492  /// - \ref AkVertex
493  /// - \ref AK::SpatialAudio::SetGeometry
494  /// - \ref AK::SpatialAudio::RemoveGeometry
495  AkAcousticSurface* Surfaces;
496 
497  /// Number of of AkTriangleInfo structures in in_pTriangleInfo and number of AkTriIdx's in in_infoMap.
498  AkSurfIdx NumSurfaces;
499 
500  /// Associate this geometry set with the room \c RoomID. Associating a geometry set with a particular room will limit the scope in which the geometry is visible/accessible. \c RoomID can be left as default (-1), in which case
501  /// this geometry set will have a global scope. It is recommended to associate geometry with a room when the geometry is (1) fully contained within the room (ie. not visible to other rooms accept by portals),
502  /// and (2) the room does not share geometry with other rooms. Doing so reduces the search space for ray casting performed by reflection and diffraction calculations. Take note that once one or more geometry sets
503  /// are associated with a room, that room will no longer be able to access geometry that is in the global scope.
504  /// - \ref AK::SpatialAudio::SetRoom
505  /// - \ref AkRoomParams
506  AkRoomID RoomID;
507 
508  /// Switch to enable or disable geometric diffraction for this Geometry.
509  bool EnableDiffraction;
510 
511  /// Switch to enable or disable geometric diffraction on boundary edges for this Geometry. Boundary edges are edges that are connected to only one triangle.
512  bool EnableDiffractionOnBoundaryEdges;
513 };
514 
515 /// Audiokinetic namespace
516 namespace AK
517 {
518  /// Audiokinetic spatial audio namespace
519  namespace SpatialAudio
520  {
521  ////////////////////////////////////////////////////////////////////////
522  /// @name Basic functions.
523  /// In order to use SpatialAudio, you need to initalize it using Init, and register all emitters and listeners that you plan on using with any of the services offered by SpatialAudio, using
524  /// RegisterEmitter and RegisterListener respectively, _after_ having registered their corresponding game object to the sound engine. The position of these objects and game-defined sends should be updated with
525  /// SetPosition and SetEmitterAuxSendValues instead of their AK::SoundEngine counterparts.
526  /// \akwarning At the moment, there can be only one Spatial Audio listener registered at any given time.
527  //@{
528 
529  /// Access the internal pool ID passed to Init.
530  AK_EXTERNAPIFUNC(AkMemPoolId, GetPoolID)();
531 
532  /// Initialize the SpatialAudio API.
533  AK_EXTERNAPIFUNC(AKRESULT, Init)(const AkSpatialAudioInitSettings& in_initSettings);
534 
535  /// Register a game object as a sound emitter in the SpatialAudio API or update settings on a previously registered sound emitter. The game object must have already been
536  /// registered in the sound engine via \c AK::SoundEngine::RegisterGameObj().
537  /// \sa
538  /// - \ref AkEmitterSettings
539  AK_EXTERNAPIFUNC(AKRESULT, RegisterEmitter)(
540  AkGameObjectID in_gameObjectID, ///< Game object ID
541  const AkEmitterSettings& in_settings ///< Settings for the spatial audio emitter.
542  );
543 
544  /// Unregister a game object as a sound emitter in the SpatialAudio API; clean up Spatial Audio listener data associated with in_gameObjectID.
545  /// This function is optional - emitters are automatically unregistered when their game object is deleted in the sound engine.
546  /// \sa
547  /// - \ref AK::SpatialAudio::RegisterEmitter
548  AK_EXTERNAPIFUNC(AKRESULT, UnregisterEmitter)(
549  AkGameObjectID in_gameObjectID ///< Game object ID
550  );
551 
552  /// Assign a game object as the Spatial Audio listener. There can be only one Spatial Audio listener registered at any given time; in_gameObjectID will replace any previously set Spatial Audio listener.
553  /// The game object passed in must be registered by the client, at some point, for sound to be heard. It is not necessary to be registered at the time of calling this function.
554  /// If not listener is explicitly registered to spatial audio, then a default listener (set via \c AK::SoundEngine::SetDefaultListeners()) is selected. If the are no default listeners, or there are more than one
555  /// default listeners, then it is necessary to call RegisterListener() to specify which listener to use with Spatial Audio.
556  AK_EXTERNAPIFUNC(AKRESULT, RegisterListener)(
557  AkGameObjectID in_gameObjectID ///< Game object ID
558  );
559 
560  /// Unregister a game object as a listener in the SpatialAudio API; clean up Spatial Audio listener data associated with in_gameObjectID.
561  /// If in_gameObjectID is the current registered listener, calling this function will clear the Spatial Audio listener and
562  /// Spatial Audio features will be disabled until another listener is registered.
563  /// This function is optional - listener are automatically unregistered when their game object is deleted in the sound engine.
564  /// \sa
565  /// - \ref AK::SpatialAudio::RegisterListener
566  AK_EXTERNAPIFUNC(AKRESULT, UnregisterListener)(
567  AkGameObjectID in_gameObjectID ///< Game object ID
568  );
569 
570  /// Set the position of an emitter game object that has been registered with the SpatialAudio API.
571  /// This function should be called instead of \c AK::SoundEngine::SetPosition(). The argument \c in_sourcePosition should represent the real position of the emitter. It is this position that is used
572  /// for all spatial audio services, such as Rooms and GeometrySets (see SpatialAudio::SetRoom and SpatialAudio::SetGeometry).
573  /// When an emitter is in a different room from the listener, its virtual positions are automatically calculated based on the relative positions of the listener and nearby portals, and it is these virtual positions
574  /// that are passed to the sound engine and used to render audio.
575  /// If the game object is registered with the sound engine, but not with the SpatialAudio API, then the call will be passed on to AK::SoundEngine::SetPosition().
576  AK_EXTERNAPIFUNC(AKRESULT, SetPosition)(
577  AkGameObjectID in_gameObjectID, ///< Game object ID of the sound emitter.
578  const AkTransform& in_sourcePosition ///< Physical position of the emitter in the simulation.
579  );
580 
581  /// Set the aux send values for an emitter game object that has been registered with the SpatialAudio API.
582  /// This function should be called instead of \c AK::SoundEngine::SetGameObjectAuxSendValues() because the spatial audio API adds additional sends for room's late reverb and
583  // for early reflection processing.
584  /// If the game object is registered with the sound engine, but not with the SpatialAudio API, then the call will be passed on to \c AK::SoundEngine::SetGameObjectAuxSendValues().
585  /// \sa
586  /// - \ref AK::SoundEngine::SetGameObjectAuxSendValues
587  AK_EXTERNAPIFUNC(AKRESULT, SetEmitterAuxSendValues)(
588  AkGameObjectID in_gameObjectID, ///< Game object ID of the sound emitter.
589  AkAuxSendValue* in_pAuxSends, ///< Aux send values
590  AkUInt32 in_uNumAux ///< Number of elements in in_pAuxSends
591  );
592 
593  //@}
594 
595  ////////////////////////////////////////////////////////////////////////
596  /// @name Helper functions for passing game data to the Wwise Reflect plug-in.
597  /// Use this API for detailed placement of reflection image sources.
598  /// \aknote These functions are low-level and useful when your game engine already implements a geometrical approach to sound propagation such as an image-source or a ray tracing algorithm.
599  /// Functions of Geometry are preferred and easier to use with the Wwise Reflect plug-in. \endaknote
600  //@{
601 
602  /// Add or update an individual image source for processing via the AkReflect plug-in. Use this API for detailed placement of
603  /// reflection image sources, whose positions have been determined by the client, such as from the results of a ray cast, computation or by manual placement. One possible
604  /// use case is generating reflections that originate far enough away that they can be modeled as a static point source, for example, off of a distant mountain.
605  /// The SpatialAudio API manages image sources added via SetImageSource() and sends them to the AkReflect plug-in that is on the aux bus with ID \c in_AuxBusID.
606  /// The image source will apply to all registered spatial audio emitters, if \c AK_INVALID_GAME_OBJECT is passed for \c in_gameObjectID,
607  /// or to one particular game object, if \c in_gameObjectID contains the ID of a valid registered spatial audio emitter.
608  /// SetImageSource takes a room ID to indicate which room the reflection is logically part of, even though the position of the image source may be outside of the extents of the room.
609  /// This ID is used as a filter, so that it is not possible to hear reflections for rooms that the emitter is not inside. To use this feature, the emitter and listeners rooms must be
610  /// specified using SetGameObjectInRoom. If you are not using the rooms and portals API, or the image source is not associated with a room, pass a default-constructed room ID.
611  /// \aknote The \c AkImageSourceSettings struct passed in \c in_info must contain a unique image source ID to be able to identify this image source across frames and when updating and/or removing it later.
612  /// Each instance of AkReflect has its own set of data, so you may reuse ID, if desired, as long as \c in_gameObjectID and \c in_AuxBusID are different.
613  /// If you are using the geometric reflections API on the same aux bus (as set in \c AkEmitterSettings) and game object(s), there is a small chance of ID conflict, because IDs for
614  /// geometric reflections' image sources are generated internally using a hash function. If a conflict does occur, you will only hear one of the two reflections. \endaknote
615  /// \aknote For proper operation with AkReflect and the SpatialAudio API, any aux bus using AkReflect should have 'Listener Relative Routing' checked and the 3D Spatialization set to None in the Wwise authoring tool. See \ref spatial_audio_wwiseprojectsetup_businstances for more details. \endaknote
616  /// \sa
617  /// - \ref AK::SpatialAudio::RegisterEmitter
618  /// - \ref AK::SpatialAudio::RemoveImageSource
619  /// - \ref AK::SpatialAudio::SetGameObjectInRoom
620  AK_EXTERNAPIFUNC(AKRESULT, SetImageSource)(
621  AkImageSourceID in_srcID, ///< The ID of the image source being added.
622  const AkImageSourceSettings& in_info, ///< Image source information.
623  AkUniqueID in_AuxBusID, ///< Aux bus that has the AkReflect plug in for early reflection DSP.
624  AkRoomID in_roomID, ///< The ID of the room that the image source is logically a part of; pass a default-constructed ID if not in, or not using, a room.
625  AkGameObjectID in_gameObjectID = AK_INVALID_GAME_OBJECT ///< The ID of the emitter game object to which the image source applies. Pass AK_INVALID_GAME_OBJECT to apply to all emitter game objects.
626  );
627 
628  /// Remove an individual reflection image source that was previously added via \c SetImageSource.
629  /// \sa
630  /// - \ref AK::SpatialAudio::SetImageSource
631  AK_EXTERNAPIFUNC(AKRESULT, RemoveImageSource)(
632  AkImageSourceID in_srcID, ///< The ID of the image source to remove.
633  AkUniqueID in_AuxBusID, ///< Aux bus that was passed to SetImageSource.
634  AkGameObjectID in_gameObjectID = AK_INVALID_GAME_OBJECT ///< Game object ID that was passed to SetImageSource.
635  );
636 
637  //@}
638 
639  ////////////////////////////////////////////////////////////////////////
640  /// @name Geometry
641  /// Geometry API for early reflection processing using Wwise Reflect.
642  //@{
643 
644  /// Add or update a set of geometry from the \c SpatialAudio module for geometric reflection and diffaction processing. A geometry set is a logical set of vertices, triangles, and acoustic surfaces,
645  /// which are referenced by the same \c AkGeometrySetID. The ID (\c in_GeomSetID) must be unique and is also chosen by the client in a manner similar to \c AkGameObjectID's.
646  /// \sa
647  /// - \ref AkGeometryParams
648  /// - \ref AK::SpatialAudio::RemoveGeometry
649  AK_EXTERNAPIFUNC(AKRESULT, SetGeometry)(
650  AkGeometrySetID in_GeomSetID, ///< Unique geometry set ID, chosen by client.
651  const AkGeometryParams& in_params ///< Geometry parameters to set.
652  );
653 
654  /// Remove a set of geometry to the SpatialAudio API.
655  /// \sa
656  /// - \ref AK::SpatialAudio::SetGeometry
657  AK_EXTERNAPIFUNC(AKRESULT, RemoveGeometry)(
658  AkGeometrySetID in_SetID ///< ID of geometry set to be removed.
659  );
660 
661  /// Query information about the reflection paths that have been calculated via geometric reflection processing in the SpatialAudio API. This function can be used for debugging purposes.
662  /// This function must acquire the global sound engine lock and therefore, may block waiting for the lock.
663  /// \sa
664  /// - \ref AkReflectionPathInfo
665  AK_EXTERNAPIFUNC(AKRESULT, QueryReflectionPaths)(
666  AkGameObjectID in_gameObjectID, ///< The ID of the game object that the client wishes to query.
667  AkVector& out_listenerPos, ///< Returns the position of the listener game object that is associated with the game object \c in_gameObjectID.
668  AkVector& out_emitterPos, ///< Returns the position of the emitter game object \c in_gameObjectID.
669  AkReflectionPathInfo* out_aPaths, ///< Pointer to an array of \c AkReflectionPathInfo's which will be filled after returning.
670  AkUInt32& io_uArraySize ///< The number of slots in \c out_aPaths, after returning the number of valid elements written.
671  );
672 
673  //@}
674 
675  ////////////////////////////////////////////////////////////////////////
676  /// @name Rooms and Portals
677  /// Sound Propagation API using rooms and portals.
678  //@{
679 
680  /// Add or update a room. Rooms are used to connect portals and define an orientation for oriented reverbs. This function may be called multiple times with the same ID to update the parameters of the room.
681  /// The ID (\c in_RoomID) must be chosen in the same manner as \c AkGameObjectID's, as they are in the same ID-space. The spatial audio lib manages the
682  /// registration/unregistration of internal game objects for rooms that use these IDs and, therefore, must not collide.
683  /// \sa
684  /// - \ref AkRoomID
685  /// - \ref AkRoomParams
686  /// - \ref AK::SpatialAudio::RemoveRoom
687  AK_EXTERNAPIFUNC(AKRESULT, SetRoom)(
688  AkRoomID in_RoomID, ///< Unique room ID, chosen by the client.
689  const AkRoomParams& in_Params ///< Parameter for the room.
690  );
691 
692  /// Remove a room.
693  /// \sa
694  /// - \ref AkRoomID
695  /// - \ref AK::SpatialAudio::SetRoom
696  AK_EXTERNAPIFUNC(AKRESULT, RemoveRoom)(
697  AkRoomID in_RoomID ///< Room ID that was passed to \c SetRoom.
698  );
699 
700  /// Add or update an acoustic portal. A portal is an opening that connects two or more rooms to simulate the transmission of reverberated (indirect) sound between the rooms.
701  /// This function may be called multiple times with the same ID to update the parameters of the portal. The ID (\c in_PortalID) must be chosen in the same manner as \c AkGameObjectID's,
702  /// as they are in the same ID-space. The spatial audio lib manages the registration/unregistration of internal game objects for portals that use these IDs, and therefore must not collide.
703  /// \sa
704  /// - \ref AkPortalID
705  /// - \ref AkPortalParams
706  /// - \ref AK::SpatialAudio::RemovePortal
707  AK_EXTERNAPIFUNC(AKRESULT, SetPortal)(
708  AkPortalID in_PortalID, ///< Unique portal ID, chosen by the client.
709  const AkPortalParams& in_Params ///< Parameter for the portal.
710  );
711 
712  /// Remove a portal.
713  /// \sa
714  /// - \ref AkPortalID
715  /// - \ref AK::SpatialAudio::SetPortal
716  AK_EXTERNAPIFUNC(AKRESULT, RemovePortal)(
717  AkPortalID in_PortalID ///< ID of portal to be removed, which was originally passed to SetPortal.
718  );
719 
720  /// Set the room that the game object is currently located in - usually the result of a containment test performed by the client. The room must have been registered with \c SetRoom.
721  /// Setting the room for a game object provides the basis for the sound propagation service, and also sets which room's reverb aux bus to send to. The sound propagation service traces the path
722  /// of the sound from the emitter to the listener, and calculates the diffraction as the sound passes through each portal. The portals are used to define the spatial location of the diffracted and reverberated
723  /// audio.
724  /// \sa
725  /// - \ref AK::SpatialAudio::SetRoom
726  /// - \ref AK::SpatialAudio::RemoveRoom
727  AK_EXTERNAPIFUNC(AKRESULT, SetGameObjectInRoom)(
728  AkGameObjectID in_gameObjectID, ///< Game object ID
729  AkRoomID in_CurrentRoomID ///< RoomID that was passed to \c AK::SpatialAudio::SetRoom
730  );
731 
732  /// Set the obstruction and occlusion values of an emitter game object that has been registered with the SpatialAudio API.
733  /// This function should be called instead of \c AK::SoundEngine::SetObjectObstructionAndOcclusion(), and can be used for setting the obstruction and occlusion values on a Spatial Audio emitter.
734  /// The obstruction value passed to SetEmitterObstructionAndOcclusion() should be used to simulate obstructing objects between the emitter and the listener, if they are in the same room, or between the emitter and a portal, if the emitter
735  /// and listener are in different room.
736  /// The occlusion value that is passed to SetEmitterObstructionAndOcclusion() is send to the sound engine directly, unless the emitter is unreachable via sound propagation. In this case, the occlusion value is maxed with the \c AkRoomParams::WallOcclusion value
737  /// to simulate sound transmission through walls.
738  /// If the listener and the emitter are in different rooms, the maximum of the obstruction value passed into SetEmitterObstructionAndOcclusion() and the the obstruction value calculated from the diffraction angle is passed to the sound engine.
739  /// If the game object is not registered as an emitter with Spatial Audio, then an error will be reported, and the call will have no effect.
740  /// \aknote The game is responsible to differentiate between obstruction between the emitter and the portal (where \c AK::SpatialAudio::SetEmitterObstructionAndOcclusion() should be used), and occlusion from room boundaries,
741  /// which is better handled by the spatial audio diffraction system. For example, games that use ray-testing for obstruction may report 100 % obstruction when an object is very close to the opening of a portal,
742  /// because the ray between the emitter and the listener hits a nearby wall. If the game then sends 100 %, this will erroneously override the diffraction calculation which is probably much less than 100% (180 degrees),
743  /// and better matches the expected audibility of the sound. To prevent this scenario, games can ray-test for obstruction objects between the emitter and the portal, passing the results with \c AK::SpatialAudio::SetEmitterObstructionAndOcclusion(),
744  /// and then test for obstructing objects between the portal and the listener, passing the results with \c AK::SpatialAudio::SetPortalObstructionAndOcclusion().
745  /// \sa
746  /// - \ref AK::SpatialAudio::SetPortalObstructionAndOcclusion
747  AK_EXTERNAPIFUNC(AKRESULT, SetEmitterObstructionAndOcclusion)(
748  AkGameObjectID in_gameObjectID, ///< Game object ID of the sound emitter.
749  AkReal32 in_fObstruction, ///< Obstruction value. Valid range 0.f-1.f
750  AkReal32 in_fOcclusion ///< Occlusion value. Valid range 0.f-1.f
751  );
752 
753  /// Set the obstruction and occlusion value for a portal that has been registered with Spatial Audio.
754  /// Portal obstruction is used to simulate objects between the portal and the listener that are obstructing the sound coming from the portal.
755  /// The obstruction value affects only the portals dry path, and should relate to how much of the opening
756  /// is obstructed, and must be calculated by the client. It is applied to the room's game object, as well as to all the emitters virtual positions
757  /// which propagate from that room through this portal.
758  /// Portal occlusion is applied only on the room game object, and affects both the wet and dry path of the signal emitted from the room's bus.
759  /// \sa
760  /// - \ref AK::SpatialAudio::SetEmitterObstructionAndOcclusion
761  AK_EXTERNAPIFUNC(AKRESULT, SetPortalObstructionAndOcclusion)(
762  AkPortalID in_PortalID, ///< Portal ID.
763  AkReal32 in_fObstruction, ///< Obstruction value. Valid range 0.f-1.f
764  AkReal32 in_fOcclusion ///< Occlusion value. Valid range 0.f-1.f
765  );
766 
767  /// Query information about the wet diffraction amount for the portal \c in_portal, returned as a normalized value \c out_wetDiffraction in the range [0,1].
768  /// The wet diffraction is calculated from how far into the 'shadow region' the listener is from the portal. Unlike dry diffraction, the
769  /// wet diffraction does not depend on the incident angle, but only the normal of the portal.
770  /// Depending on the spatial audio initialization settings, this value is applied by spatial audio, to the obstruction and/or built-in game parameter of the room game object that is
771  /// on the other side of the portal (relative to the listener).
772  /// This function must acquire the global sound engine lock and therefore, may block waiting for the lock.
773  /// \sa
774  /// - \ref AkDiffractionFlags
775  /// - \ref AkSpatialAudioInitSettings
776  AK_EXTERNAPIFUNC(AKRESULT, QueryWetDiffraction)(
777  AkPortalID in_portal, ///< The ID of the game object that the client wishes to query.
778  AkReal32& out_wetDiffraction ///< The number of slots in \c out_aPaths, after returning the number of valid elements written.
779  );
780 
781  /// Query information about the diffraction state for a particular listener and emitter, which has been calculated using the data provided via the spatial audio emitter API. This function can be used for debugging purposes.
782  /// Returned in \c out_aPaths, this array contains the sound paths calculated from diffraction around a geometric edge and/or diffraction through portals connecting rooms.
783  /// No paths will be returned in any of the following conditions: (1) the emitter game object has a direct line of sight to the listener game object, (2) the emitter and listener are in the same room, and the listener is completely outside the radius of the emitter as
784  /// defined by <tt>AkEmitterSettings::diffractionMaxPathLength</tt>, or (3) The emitter and listener are in different rooms, but there are no paths found via portals between the emitter and the listener.
785  /// A single path with zero diffraction nodes is returned when all of the following conditions are met: (1) the emitter and listener are in the same room, (2) there is no direct line of sight, and (3) either \c AkEmitterSettings::diffractionMaxPathLength is exceeded or the accumulated diffraction coefficient exceeds 1.0.
786  /// This function must acquire the global sound engine lock and, therefore, may block waiting for the lock.
787  /// \sa
788  /// - \ref AkDiffractionPathInfo
789  AK_EXTERNAPIFUNC(AKRESULT, QueryDiffractionPaths)(
790  AkGameObjectID in_gameObjectID, ///< The ID of the game object that the client wishes to query.
791  AkVector& out_listenerPos, ///< Returns the position of the listener game object that is associated with the game object \c in_gameObjectID.
792  AkVector& out_emitterPos, ///< Returns the position of the emitter game object \c in_gameObjectID.
793  AkDiffractionPathInfo* out_aPaths, ///< Pointer to an array of \c AkDiffractionPathInfo's which will be filled on return.
794  AkUInt32& io_uArraySize ///< The number of slots in \c out_aPaths, after returning the number of valid elements written.
795  );
796 
797  //@}
798  }
799 };
AkDiffractionPathInfo::virtualPos
AkTransform virtualPos
Virtual emitter position. This is the position that is passed to the sound engine to render the audio...
Definition: AkSpatialAudio.h:321
AkRoomParams::RoomGameObj_KeepRegistered
bool RoomGameObj_KeepRegistered
Definition: AkSpatialAudio.h:459
AK::SpatialAudio::QueryWetDiffraction
AKSOUNDENGINE_API AKRESULT QueryWetDiffraction(AkPortalID in_portal, AkReal32 &out_wetDiffraction)
AK::SpatialAudio::UnregisterListener
AKSOUNDENGINE_API AKRESULT UnregisterListener(AkGameObjectID in_gameObjectID)
AkTriangle
Triangle for a spatial audio mesh.
Definition: AkSpatialAudio.h:212
AkReflectionPathInfo::numPathPoints
AkUInt32 numPathPoints
Number of valid elements in the pathPoint[], surfaces[], and diffraction[] arrays.
Definition: AkSpatialAudio.h:280
AkSpatialAudioInitSettings::uPoolSize
AkUInt32 uPoolSize
Desired memory pool size if a new pool should be created. A pool will be created if uPoolID is not se...
Definition: AkSpatialAudio.h:60
AkSpatialAudioInitSettings::fDiffractionShadowAttenFactor
AkReal32 fDiffractionShadowAttenFactor
Multiplier that is applied to the distance attenuation of diffracted sounds (sounds that are in the '...
Definition: AkSpatialAudio.h:63
AkVertex::AkVertex
AkVertex(AkReal32 in_X, AkReal32 in_Y, AkReal32 in_Z)
Constructor.
Definition: AkSpatialAudio.h:203
AkImageSourceSettings::params
AkImageSourceParams params
Image source parameters.
Definition: AkSpatialAudio.h:111
AK::SpatialAudio::QueryReflectionPaths
AKSOUNDENGINE_API AKRESULT QueryReflectionPaths(AkGameObjectID in_gameObjectID, AkVector &out_listenerPos, AkVector &out_emitterPos, AkReflectionPathInfo *out_aPaths, AkUInt32 &io_uArraySize)
AkPortalParams
Parameters passed to SetPortal.
Definition: AkSpatialAudio.h:354
AK
Audiokinetic namespace.
Definition: AkWwiseSDKVersion.cs:32
AkReflectionPathInfo::imageSource
AkVector imageSource
Apparent source of the reflected sound that follows this path.
Definition: AkSpatialAudio.h:269
AkAuxSendValue
Auxiliary bus sends information per game object per given auxiliary bus.
Definition: AkTypes.h:566
AK::SpatialAudio::RemovePortal
AKSOUNDENGINE_API AKRESULT RemovePortal(AkPortalID in_PortalID)
AkRoomParams::Front
AkVector Front
Definition: AkSpatialAudio.h:416
AkSpatialAudioInitSettings::uPoolID
AkMemPoolId uPoolID
User-provided pool ID (see AK::MemoryMgr::CreatePool).
Definition: AkSpatialAudio.h:59
AkGeometryParams::NumTriangles
AkTriIdx NumTriangles
Number of triangles in Triangles.
Definition: AkSpatialAudio.h:478
AkRoomParams::Up
AkVector Up
Definition: AkSpatialAudio.h:415
AkImageSourceSettings::name
AK::SpatialAudio::String name
Name given to image source, can be used to identify the image source in the AK Reflect plugin UI.
Definition: AkSpatialAudio.h:117
AkTriangle::point2
AkVertIdx point2
Index into the vertex table passed into AkGeometryParams that describes the third vertex of the trian...
Definition: AkSpatialAudio.h:235
AkRoomParams::RoomGameObj_AuxSendLevelToSelf
AkReal32 RoomGameObj_AuxSendLevelToSelf
Definition: AkSpatialAudio.h:448
AK::SpatialAudio::SetGameObjectInRoom
AKSOUNDENGINE_API AKRESULT SetGameObjectInRoom(AkGameObjectID in_gameObjectID, AkRoomID in_CurrentRoomID)
AkAcousticSurface::AkAcousticSurface
AkAcousticSurface()
Constructor.
Definition: AkSpatialAudio.h:249
AkTriangle::AkTriangle
AkTriangle(AkVertIdx in_pt0, AkVertIdx in_pt1, AkVertIdx in_pt2, AkSurfIdx in_surfaceInfo)
Constructor.
Definition: AkSpatialAudio.h:221
AkVertex::Z
AkReal32 Z
Z coordinate.
Definition: AkSpatialAudio.h:207
AK::SpatialAudio::Init
AKSOUNDENGINE_API AKRESULT Init(const AkSpatialAudioInitSettings &in_initSettings)
Initialize the SpatialAudio API.
AkPortalParams::AkPortalParams
AkPortalParams()
Constructor.
Definition: AkSpatialAudio.h:356
AkImageSourceSettings::AkImageSourceSettings
AkImageSourceSettings(AkVector in_sourcePosition, AkReal32 in_fDistanceScalingFactor, AkReal32 in_fLevel)
Definition: AkSpatialAudio.h:76
AkReflectionPathInfo::pathPoint
AkVector pathPoint[AK_MAX_REFLECTION_PATH_LENGTH]
Definition: AkSpatialAudio.h:273
AkRoomParams::ReverbAuxBus
AkAuxBusID ReverbAuxBus
Definition: AkSpatialAudio.h:426
AkAcousticSurface::textureID
AkUInt32 textureID
Definition: AkSpatialAudio.h:256
AkPortalParams::FrontRoom
AkRoomID FrontRoom
Definition: AkSpatialAudio.h:384
AK::SpatialAudio::GetPoolID
AKSOUNDENGINE_API AkMemPoolId GetPoolID()
Access the internal pool ID passed to Init.
AkRoomParams::AkRoomParams
AkRoomParams()
Constructor.
Definition: AkSpatialAudio.h:398
AkDiffractionPathInfo::nodeCount
AkUInt32 nodeCount
Total number of nodes in the path. Defines the number of valid entries in the nodes,...
Definition: AkSpatialAudio.h:324
AkPortalParams::strName
AK::SpatialAudio::OsString strName
Name used to identify portal (optional).
Definition: AkSpatialAudio.h:377
AkImageSourceTexture::uNumTexture
AkUInt32 uNumTexture
Number of valid textures in the texture array.
Definition: AkReflectGameData.h:69
AkAcousticSurface::strName
const char * strName
Name to describe this surface.
Definition: AkSpatialAudio.h:262
AkDiffractionPathInfo::nodes
AkVector nodes[kMaxNodes]
Definition: AkSpatialAudio.h:305
AkReflectionPathInfo::surfaces
AkAcousticSurface surfaces[AK_MAX_REFLECTION_PATH_LENGTH]
Definition: AkSpatialAudio.h:277
AkGeometryParams::Surfaces
AkAcousticSurface * Surfaces
Definition: AkSpatialAudio.h:495
AkVertex::X
AkReal32 X
X coordinate.
Definition: AkSpatialAudio.h:205
AkGeometryParams::NumVertices
AkVertIdx NumVertices
Definition: AkSpatialAudio.h:488
AK::SpatialAudio::UnregisterEmitter
AKSOUNDENGINE_API AKRESULT UnregisterEmitter(AkGameObjectID in_gameObjectID)
AkEmitterSettings::diffractionMaxPaths
AkUInt32 diffractionMaxPaths
Definition: AkSpatialAudio.h:181
AkRoomParams::ReverbLevel
AkReal32 ReverbLevel
Definition: AkSpatialAudio.h:430
AkEmitterSettings::reflectionMaxPathLength
AkReal32 reflectionMaxPathLength
Definition: AkSpatialAudio.h:148
AkEmitterSettings::reflectionsOrder
AkUInt32 reflectionsOrder
Definition: AkSpatialAudio.h:157
AkEmitterSettings::reflectorFilterMask
AkUInt32 reflectorFilterMask
Definition: AkSpatialAudio.h:162
AkRoomParams::strName
AK::SpatialAudio::OsString strName
Name used to identify room (optional)
Definition: AkSpatialAudio.h:437
AK::SpatialAudio::SetGeometry
AKSOUNDENGINE_API AKRESULT SetGeometry(AkGeometrySetID in_GeomSetID, const AkGeometryParams &in_params)
AkReflectionPathInfo
Structure for retrieving information about the indirect paths of a sound that have been calculated vi...
Definition: AkSpatialAudio.h:267
AkTriangle::surface
AkSurfIdx surface
Definition: AkSpatialAudio.h:239
AK::SpatialAudio::SetPortal
AKSOUNDENGINE_API AKRESULT SetPortal(AkPortalID in_PortalID, const AkPortalParams &in_Params)
AkGeometryParams::RoomID
AkRoomID RoomID
Definition: AkSpatialAudio.h:506
AkReflectionPathInfo::isOccluded
bool isOccluded
True if the sound path was occluded. Note that the spatial audio library must be recompiled with #def...
Definition: AkSpatialAudio.h:292
AK::SpatialAudio::RegisterEmitter
AKSOUNDENGINE_API AKRESULT RegisterEmitter(AkGameObjectID in_gameObjectID, const AkEmitterSettings &in_settings)
AkVector::Y
AkReal32 Y
Y Position.
Definition: AkTypes.h:300
AkImageSourceSettings::SetOneTexture
void SetOneTexture(AkUniqueID in_texture)
Definition: AkSpatialAudio.h:98
AkEmitterSettings::reflectAuxBusID
AkUniqueID reflectAuxBusID
Definition: AkSpatialAudio.h:142
AkDiffractionPathInfo::angles
AkReal32 angles[kMaxNodes]
Raw diffraction angles at each point, in radians.
Definition: AkSpatialAudio.h:308
AkVector::X
AkReal32 X
X Position.
Definition: AkTypes.h:299
AkVertex::Y
AkReal32 Y
Y coordinate.
Definition: AkSpatialAudio.h:206
AK::SpatialAudio::SetEmitterAuxSendValues
AKSOUNDENGINE_API AKRESULT SetEmitterAuxSendValues(AkGameObjectID in_gameObjectID, AkAuxSendValue *in_pAuxSends, AkUInt32 in_uNumAux)
AkPortalParams::BackRoom
AkRoomID BackRoom
Definition: AkSpatialAudio.h:391
AkDiffractionPathInfo::portals
AkPortalID portals[kMaxNodes]
Definition: AkSpatialAudio.h:313
AkGeometryParams::Triangles
AkTriangle * Triangles
Definition: AkSpatialAudio.h:475
AkAcousticSurface::reflectorChannelMask
AkUInt32 reflectorChannelMask
Bitfield of channels that this surface belongs to. When processing the reflections,...
Definition: AkSpatialAudio.h:259
AkVector::Z
AkReal32 Z
Z Position.
Definition: AkTypes.h:301
AK::SpatialAudio::SetEmitterObstructionAndOcclusion
AKSOUNDENGINE_API AKRESULT SetEmitterObstructionAndOcclusion(AkGameObjectID in_gameObjectID, AkReal32 in_fObstruction, AkReal32 in_fOcclusion)
AkTriangle::AkTriangle
AkTriangle()
Constructor.
Definition: AkSpatialAudio.h:214
AkImageSourceSettings::SetName
void SetName(const char *in_pName)
Definition: AkSpatialAudio.h:104
AkSpatialAudioInitSettings
Initialization settings of the spatial audio module.
Definition: AkSpatialAudio.h:49
AkVertex
Vertex for a spatial audio mesh.
Definition: AkSpatialAudio.h:198
AkReflectionPathInfo::diffraction
AkReal32 diffraction[AK_MAX_REFLECTION_PATH_LENGTH]
Diffraction amount, normalized to the range [0,1].
Definition: AkSpatialAudio.h:286
AkEmitterSettings::useImageSources
AkUInt8 useImageSources
Enable reflections from image sources that have been added via the AK::SpatialAudio::SetImageSource()...
Definition: AkSpatialAudio.h:193
AK::SpatialAudio::RemoveRoom
AKSOUNDENGINE_API AKRESULT RemoveRoom(AkRoomID in_RoomID)
AkVertex::AkVertex
AkVertex()
Constructor.
Definition: AkSpatialAudio.h:200
AkTriangle::point0
AkVertIdx point0
Index into the vertex table passed into AkGeometryParams that describes the first vertex of the trian...
Definition: AkSpatialAudio.h:229
AkSpatialAudioID
Base type for ID's used by Wwise spatial audio.
Definition: AkSpatialAudioTypes.h:95
AkReflectionPathInfo::numReflections
AkUInt32 numReflections
Number of reflections in the pathPoint[] array. Shadow zone diffraction does not count as a reflectio...
Definition: AkSpatialAudio.h:283
AkEmitterSettings::diffractionMaxEdges
AkUInt32 diffractionMaxEdges
Definition: AkSpatialAudio.h:175
AkGeometryParams::EnableDiffraction
bool EnableDiffraction
Switch to enable or disable geometric diffraction for this Geometry.
Definition: AkSpatialAudio.h:509
AkGeometryParams::NumSurfaces
AkSurfIdx NumSurfaces
Number of of AkTriangleInfo structures in in_pTriangleInfo and number of AkTriIdx's in in_infoMap.
Definition: AkSpatialAudio.h:498
AkReflectionPathInfo::level
AkReal32 level
Linear gain applied to image source.
Definition: AkSpatialAudio.h:289
AkRoomParams::WallOcclusion
AkReal32 WallOcclusion
Definition: AkSpatialAudio.h:434
AkEmitterSettings::name
AK::SpatialAudio::OsString name
Name given to this sound emitter.
Definition: AkSpatialAudio.h:138
AK::SpatialAudio::SetPosition
AKSOUNDENGINE_API AKRESULT SetPosition(AkGameObjectID in_gameObjectID, const AkTransform &in_sourcePosition)
AkDiffractionPathInfo::kMaxNodes
static const AkUInt32 kMaxNodes
Defines the maximum number of nodes that a user can retrieve information about. Longer paths will be ...
Definition: AkSpatialAudio.h:301
AK::SpatialAudio::SetImageSource
AKSOUNDENGINE_API AKRESULT SetImageSource(AkImageSourceID in_srcID, const AkImageSourceSettings &in_info, AkUniqueID in_AuxBusID, AkRoomID in_roomID, AkGameObjectID in_gameObjectID=AK_INVALID_GAME_OBJECT)
AkEmitterSettings::AkEmitterSettings
AkEmitterSettings()
Constructor.
Definition: AkSpatialAudio.h:124
AkSpatialAudioInitSettings::fMovementThreshold
AkReal32 fMovementThreshold
Amount that an emitter or listener has to move to trigger a recalculation of reflections/diffraction....
Definition: AkSpatialAudio.h:68
AkImageSourceSettings::operator=
AkImageSourceSettings & operator=(const AkImageSourceSettings &src)
Operator =.
Definition: AkSpatialAudio.h:89
AkDiffractionPathInfo::rooms
AkRoomID rooms[kMaxNodes+1]
Definition: AkSpatialAudio.h:318
AkEmitterSettings
Settings for a sound emitter.
Definition: AkSpatialAudio.h:122
AK::SpatialAudio::RemoveImageSource
AKSOUNDENGINE_API AKRESULT RemoveImageSource(AkImageSourceID in_srcID, AkUniqueID in_AuxBusID, AkGameObjectID in_gameObjectID=AK_INVALID_GAME_OBJECT)
AkGeometryParams::EnableDiffractionOnBoundaryEdges
bool EnableDiffractionOnBoundaryEdges
Switch to enable or disable geometric diffraction on boundary edges for this Geometry....
Definition: AkSpatialAudio.h:512
AkString::AllocCopy
AKRESULT AllocCopy()
Definition: AkString.h:79
AkImageSourceSettings::texture
AkImageSourceTexture texture
Acoustic texture that goes with this image source.
Definition: AkSpatialAudio.h:114
AkSpatialAudioInitSettings::uDiffractionFlags
AkUInt32 uDiffractionFlags
Enable or disable specific diffraction features. See AkDiffractionFlags.
Definition: AkSpatialAudio.h:62
AkGeometryParams::Vertices
AkVertex * Vertices
Number of vertices in Vertices.
Definition: AkSpatialAudio.h:485
AkSpatialAudioInitSettings::uMaxSoundPropagationDepth
AkUInt32 uMaxSoundPropagationDepth
Maximum number of portals that sound can propagate through; must be less than or equal to AK_MAX_SOUN...
Definition: AkSpatialAudio.h:61
AkVector
3D vector.
Definition: AkTypes.h:282
AkEmitterSettings::roomReverbAuxBusGain
AkReal32 roomReverbAuxBusGain
Definition: AkSpatialAudio.h:170
AK::SpatialAudio::QueryDiffractionPaths
AKSOUNDENGINE_API AKRESULT QueryDiffractionPaths(AkGameObjectID in_gameObjectID, AkVector &out_listenerPos, AkVector &out_emitterPos, AkDiffractionPathInfo *out_aPaths, AkUInt32 &io_uArraySize)
AkPortalParams::Transform
AkTransform Transform
Definition: AkSpatialAudio.h:364
AkPortalParams::Extent
AkVector Extent
Definition: AkSpatialAudio.h:369
AkGeometryParams::AkGeometryParams
AkGeometryParams()
Constructor.
Definition: AkSpatialAudio.h:468
AkDiffractionPathInfo::diffraction
AkReal32 diffraction
Definition: AkSpatialAudio.h:333
AkStringData::Term
void Term()
Definition: AkString.h:40
AK::SpatialAudio::SetPortalObstructionAndOcclusion
AKSOUNDENGINE_API AKRESULT SetPortalObstructionAndOcclusion(AkPortalID in_PortalID, AkReal32 in_fObstruction, AkReal32 in_fOcclusion)
AkSpatialAudioInitSettings::fDiffractionShadowDegrees
AkReal32 fDiffractionShadowDegrees
Definition: AkSpatialAudio.h:64
AkDiffractionPathInfo::obstructionValue
AkReal32 obstructionValue
Definition: AkSpatialAudio.h:349
AK::SpatialAudio::RemoveGeometry
AKSOUNDENGINE_API AKRESULT RemoveGeometry(AkGeometrySetID in_SetID)
AkImageSourceTexture::arTextureID
AkUniqueID arTextureID[AK_MAX_NUM_TEXTURE]
Unique IDs of the Acoustics Texture ShareSets used to filter this image source.
Definition: AkReflectGameData.h:70
AK::SpatialAudio::SetRoom
AKSOUNDENGINE_API AKRESULT SetRoom(AkRoomID in_RoomID, const AkRoomParams &in_Params)
AkEmitterSettings::reflectionsAuxBusGain
AkReal32 reflectionsAuxBusGain
Send gain (0.f-1.f) that is applied when sending to the bus that has the AkReflect plug-in....
Definition: AkSpatialAudio.h:151
AkRoomParams
Parameters passed to SetRoom.
Definition: AkSpatialAudio.h:396
AkTransform
Position and orientation of game objects.
Definition: AkTypes.h:306
AkGeometryParams
Parameters passed to SetGeometry.
Definition: AkSpatialAudio.h:466
AkTriangle::point1
AkVertIdx point1
Index into the vertex table passed into AkGeometryParams that describes the second vertex of the tria...
Definition: AkSpatialAudio.h:232
AkEmitterSettings::diffractionMaxPathLength
AkReal32 diffractionMaxPathLength
Definition: AkSpatialAudio.h:190
AK::SpatialAudio::RegisterListener
AKSOUNDENGINE_API AKRESULT RegisterListener(AkGameObjectID in_gameObjectID)

Cette page a-t-elle été utile ?

Besoin d'aide ?

Des questions ? Des problèmes ? Besoin de plus d'informations ? Contactez-nous, nous pouvons vous aider !

Visitez notre page d'Aide

Décrivez-nous de votre projet. Nous sommes là pour vous aider.

Enregistrez votre projet et nous vous aiderons à démarrer sans aucune obligation !

Partir du bon pied avec Wwise