Version
menu_open
link
Wwise SDK 2021.1.14
AkSpatialAudio.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 Version: v2021.1.14 Build: 6590
25 Copyright (c) 2006-2023 Audiokinetic Inc.
26 *******************************************************************************/
27 
28 /// \file
29 /// Spatial Audio interface.
30 
31 #pragma once
32 
36 
37 template<AkUInt32 TSize>
39 {
40  static AkUInt32 GrowBy(AkUInt32 /*in_CurrentArraySize*/) { return TSize; }
41 };
42 
43 /// Initialization settings of the spatial audio module.
45 {
51  , fMaxPathLength(10000.0f)
52  , fCPULimitPercentage(0.0f)
56  , bUseObstruction(true)
57  , bUseOcclusion(true)
58 
59  {}
60 
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  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.
63  AkUInt32 uNumberOfPrimaryRays; ///< The number of primary rays used in the ray tracing engine. A larger number of rays will increase the chances of finding reflection and diffraction paths, but will result in higher CPU usage. When CPU limit is active (see \ref AkSpatialAudioInitSettings::fCPULimitPercentage), this setting represents the maximum allowed number of primary rays.
64  AkUInt32 uMaxReflectionOrder; ///< Maximum reflection order [1, 4] - the number of 'bounces' in a reflection path. A higher reflection order renders more details at the expense of higher CPU usage.
65  AkReal32 fMaxPathLength; ///< The length of rays that are cast inside Spatial Audio. This effectively caps the maximum length of individual segments in reflection or diffraction paths.
66  ///< Each individual sound is also affected by its maximum attenuation distance, specified in the Authoring tool. Reflection or diffraction paths, calculated inside Spatial Audio, will never exceed a sound's maximum attenuation distance.
67  ///< Note, however, that attenuation is considered infinite if the furthest point is above the audibility threshold.
68  AkReal32 fCPULimitPercentage; ///< Defines the targeted computation time allocated for the ray tracing engine. Defined as a percentage [0, 100] of the current audio frame. The ray tracing engine dynamically adapts the number of primary rays to target the specified computation time value. In all circumstances, the computed number of primary rays cannot exceed the number of primary rays specified by AkSpatialAudioInitSettings::uNumberOfPrimaryRays.
69  ///< A value of 0 indicates no target has been set. In this case, the number of primary rays is fixed and is set by AkSpatialAudioInitSettings::uNumberOfPrimaryRays.
70  bool bEnableDiffractionOnReflection; ///< Enable diffraction at the end/beginning of reflection paths. Diffraction on reflection causes reflections to fade in and out smoothly as the listener or emitter move in and out of the reflection's shadow zone.
71  bool bEnableGeometricDiffractionAndTransmission;///< Enable computation of geometric diffraction and transmission paths for all sources that have the <b>Enable Diffraction and Transmission</b> box checked in the Positioning tab of the Wwise Property Editor.
72  ///< This flag enables sound paths around (diffraction) and through (transmission) geometry (see \c AK::SpatialAudio::SetGeometry).
73  ///< Setting \c bEnableGeometricDiffractionAndTransmission to false implies that geometry is only to be used for reflection calculation.
74  ///< Diffraction edges must be enabled on geometry for diffraction calculation (see \c AkGeometryParams).
75  ///< If \c bEnableGeometricDiffractionAndTransmission is false but a sound has <b>Enable Diffraction and Transmission</b> selected in the Positioning tab of the authoring tool, the sound will diffract through portals but will pass through geometry as if it is not there.
76  ///< One would typically disable this setting in the case that the game intends to perform its own obstruction calculation, but geometry is still passed to spatial audio for reflection calculation.
77  bool bCalcEmitterVirtualPosition; ///< An emitter that is diffracted through a portal or around geometry will have its apparent or virtual position calculated by Wwise Spatial Audio and passed on to the sound engine.
78  bool bUseObstruction; ///< Use the Wwise obstruction curve for modeling the effect of diffraction on a sound.
79  ///< Diffraction is only applied to sounds that have the <b>Enable Diffraction and Transmission</b> box checked in the Positioning tab of the Wwise Property Editor.
80  ///< Diffraction can also be applied using the diffraction built-in parameter, mapped to an RTPC (the built-in parameter is populated whether AkSpatialAudioInitSettings::bUseObstruction is true or false).
81  ///< While the obstruction curve is a global setting for all sounds, using it to simulate diffraction is preferred over an RTPC, because it provides greater accuracy when modeling multiple diffraction paths, or a combination of diffraction and transmission paths.
82  ///< This is due to the fact that RTPCs cannot be applied separately to individual sound paths. Only the path with the least amount of diffraction is sent to the RTPC.
83  bool bUseOcclusion; ///< Use the Wwise occlusion curve for modeling the effect of transmission loss on a sound.
84  ///< The transmission loss factor is applied using the occlusion curve defined in the wwise project settings.
85  ///< Transmission loss is only applied to sounds that have the <b>Enable Diffraction and Transmission</b> box checked in the Positioning tab of the Wwise Property Editor.
86  ///< Transmission loss can also be applied using the transmission loss built-in parameter, mapped to an RTPC (the built-in parameter is populated whether AkSpatialAudioInitSettings::bUseOcclusion is true or false).
87  ///< While the occlusion curve is a global setting for all sounds, using it to simulate transmission loss is preferred over an RTPC, because it provides greater accuracy when modeling both transmission and diffraction.
88  ///< This is due to the fact that RTPCs cannot be applied to individual sound paths, therefore any parameter mapped to a transmission loss RTPC will also
89  ///< affect any potential diffraction paths originating from an emitter.
90 
91 };
92 
93 // Settings for individual image sources.
95 {
97 
98  AkImageSourceSettings(AkVector in_sourcePosition, AkReal32 in_fDistanceScalingFactor, AkReal32 in_fLevel)
99  : params(in_sourcePosition, in_fDistanceScalingFactor, in_fLevel)
100  , texture()
101  , name()
102  {
103  }
104 
106  {
107  name.Term();
108  }
109 
110  /// Operator =
112  {
113  params = src.params;
114  texture = src.texture;
115  name = src.name;
116  name.AllocCopy();
117  return *this;
118  }
119 
120  void SetOneTexture(AkUniqueID in_texture)
121  {
122  texture.uNumTexture = 1;
123  texture.arTextureID[0] = in_texture;
124  }
125 
126  void SetName(const char* in_pName)
127  {
128  name = in_pName;
129  name.AllocCopy();
130  }
131 
132  /// Image source parameters.
134 
135  /// Acoustic texture that goes with this image source.
137 
138  /// Name given to image source, can be used to identify the image source in the AK Reflect plugin UI.
140 };
141 
142 /// Vertex for a spatial audio mesh.
143 struct AkVertex
144 {
145  /// Constructor
146  AkVertex() : X(0.f), Y(0.f), Z(0.f) {}
147 
148  /// Constructor
149  AkVertex(AkReal32 in_X, AkReal32 in_Y, AkReal32 in_Z) : X(in_X), Y(in_Y), Z(in_Z) {}
150 
151  AkReal32 X; ///< X coordinate
152  AkReal32 Y; ///< Y coordinate
153  AkReal32 Z; ///< Z coordinate
154 };
155 
156 class Ak3DVector;
157 
158 /// AkExtent describes an extent with width, height and depth. halfWidth, halfHeight and halfDepth should form a vector from the centre of the volume to the positive corner.
159 /// For portals, negative values in the extent will cause an error. For rooms, negative values can be used to opt out of room transmission.
160 struct AkExtent
161 {
162  AkExtent() {}
163 
164  AkExtent(AkReal32 in_halfWidth, AkReal32 in_halfHeight, AkReal32 in_halfDepth)
165  : halfWidth(in_halfWidth)
166  , halfHeight(in_halfHeight)
167  , halfDepth(in_halfDepth)
168  {}
169 
173 };
174 
175 /// Triangle for a spatial audio mesh.
176 struct AkTriangle
177 {
178  /// Constructor
183  {}
184 
185  /// Constructor
186  AkTriangle(AkVertIdx in_pt0, AkVertIdx in_pt1, AkVertIdx in_pt2, AkSurfIdx in_surfaceInfo)
187  : point0(in_pt0)
188  , point1(in_pt1)
189  , point2(in_pt2)
190  , surface(in_surfaceInfo)
191  {}
192 
193  /// 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.
195 
196  /// 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.
198 
199  /// 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.
201 
202  /// Index into the surface table passed into \c AkGeometryParams that describes the surface properties of the triangle.
203  /// If this field is left as \c AK_INVALID_SURFACE, then a default-constructed \c AkAcousticSurface is used.
205 };
206 
207 /// Describes the acoustic surface properties of one or more triangles.
208 /// 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
209 /// \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.
210 /// 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.
212 {
213  /// Constructor
215  , transmissionLoss(1.0f)
216  , strName(NULL)
217  {}
218 
219  /// 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
220  /// \sa <tt>\ref AK::SoundEngine::GetIDFromString()</tt>
222 
223  /// Value to set when modeling sound transmission through geometry. Transmission is modeled only when the sound emitted enables diffraction and there is no direct line of sight from the emitter to the listener.
224  /// If more that one surface is between the emitter and the listener, the maximum of each surface's transmission loss value is used. If the emitter and listener are in different rooms, then the rooms' transmission loss is taken into account.
225  /// The maximum of all the surfaces' transmission loss value, and the transmission loss value (see \c AkRoomParams) is used to render the transmission path.
226  /// Valid range: (0.f-1.f)
227  /// - \ref AkRoomParams
229 
230  /// Name to describe this surface
231  const char* strName;
232 };
233 
234 /// 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.
236 {
237  /// Apparent source of the reflected sound that follows this path.
239 
240  /// Vertices of the indirect path.
241  /// pathPoint[0] is closest to the emitter, pathPoint[numPathPoints-1] is closest to the listener.
243 
244  /// The surfaces that were hit in the path.
245  /// surfaces[0] is closest to the emitter, surfaces[numPathPoints-1] is closest to the listener.
247 
248  /// Number of valid elements in the \c pathPoint[], \c surfaces[], and \c diffraction[] arrays.
250 
251  /// 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.
253 
254  /// Diffraction amount, normalized to the range [0,1]
256 
257  /// Linear gain applied to image source.
259 
260  /// Deprecated - always false. Occluded paths are not generated.
262 };
263 
264 /// Structure for retrieving information about paths for a given emitter.
265 /// The diffraction paths represent indirect sound paths from the emitter to the listener, whether they go through portals
266 /// (via the rooms and portals API) or are diffracted around edges (via the geometric diffraction API).
267 /// The direct path is included here and can be identified by checking \c nodeCount == 0. The direct path may have a non-zero transmission loss
268 /// if it passes through geometry or between rooms.
270 {
271  /// Defines the maximum number of nodes that a user can retrieve information about. Longer paths will be truncated.
273 
274  /// Diffraction points along the path. nodes[0] is the point closest to the listener; nodes[numNodes-1] is the point closest to the emitter.
275  /// Neither the emitter position nor the listener position are represented in this array.
277 
278  /// Emitter position. This is the source position for an emitter. In all cases, except for radial emitters, it is the same position as the game object position.
279  /// For radial emitters, it is the calculated position at the edge of the volume.
281 
282  /// Raw diffraction angles at each point, in radians.
284 
285  /// 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).
286  /// Otherwise, if the path diffracts through a portal at position i, then portals[i] will be the ID of that portal.
287  /// portal[0] represents the node closest to the listener; portal[numNodes-1] represents the node closest to the emitter.
289 
290  /// 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,
291  /// then rooms[i] is on the listener's side of the portal, and rooms[i+1] is on the emitters side of the portal.
292  /// 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).
294 
295  /// 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.
297 
298  /// 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.
300 
301  /// Calculated total diffraction from this path, normalized to the range [0,1]
302  /// The diffraction amount is calculated from the sum of the deviation angles from a straight line, of all angles at each nodePoint.
303  // Can be thought of as how far into the 'shadow region' the sound has to 'bend' to reach the listener.
304  /// 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.
305  /// \sa
306  /// - \ref AkSpatialAudioInitSettings
308 
309  /// Calculated total transmission loss from this path, normalized to the range [0,1]
310  /// This field will be 0 for diffraction paths where \c nodeCount > 0. It may be non-zero for the direct path where \c nodeCount == 0.
311  /// The path's transmission loss value is the combination of the geometric transmission loss and the room transmission loss, by taking the greater of the two.
312  /// The geometric transmission loss is calculated from the transmission loss values assigned to the geometry that this path transmits through.
313  /// If a path transmits through multiple geometries with different transmission loss values, the largest value is taken.
314  /// The room transmission loss is taken from the emitter and listener rooms' transmission loss values, and likewise,
315  /// if the listener's room and the emitter's room have different transmission loss values, the greater of the two is used.
316  /// \sa
317  /// - \ref AkSpatialAudioInitSettings
318  /// - \ref AkRoomParams
319  /// - \ref AkAcousticSurface
321 
322  /// Total path length
323  /// Represents the sum of the length of the individual segments between nodes, with a correction factor applied for diffraction.
324  /// 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.
325  /// \sa
326  /// - \ref AkSpatialAudioInitSettings
328 
329  /// Obstruction value for this path
330  /// This value includes the accumulated portal obstruction for all portals along the path.
332 };
333 
334 /// Parameters passed to \c SetPortal
336 {
337  /// Constructor
339  bEnabled(false)
340  {}
341 
342  /// Copy Constructor
344  : Transform(in_rhs.Transform)
345  , Extent(in_rhs.Extent)
346  , bEnabled(in_rhs.bEnabled)
347  , strName(in_rhs.strName)
348  , FrontRoom(in_rhs.FrontRoom)
349  , BackRoom(in_rhs.BackRoom)
350  {
351  strName.AllocCopy();
352  }
353 
354  /// Assignment operator</span>
356  {
357  Transform = in_rhs.Transform;
358  Extent = in_rhs.Extent;
359  bEnabled = in_rhs.bEnabled;
360 
361  strName = in_rhs.strName;
362  strName.AllocCopy();
363 
364  FrontRoom = in_rhs.FrontRoom;
365  BackRoom = in_rhs.BackRoom;
366 
367  return *this;
368  }
369 
370  /// Portal's position and orientation in the 3D world.
371  /// Position vector is the center of the opening.
372  /// 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.
373  /// 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.
375 
376  /// Portal extent. Defines the dimensions of the portal relative to its center; all components must be positive numbers. The local right and up dimensions are used in diffraction calculations,
377  /// whereas the front dimension 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
378  /// that results in appropriately smooth transitions between rooms. Extent dimensions must be positive.
380 
381  /// Whether or not the portal is active/enabled. For example, this parameter may be used to simulate open/closed doors.
382  /// Portal diffraction is simulated when at least one portal exists and is active between an emitter and the listener.
383  bool bEnabled;
384 
385  /// Name used to identify portal (optional).
387 
388  /// 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,
389  /// 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.
390  /// - \ref AK::SpatialAudio::SetRoom
391  /// - \ref AK::SpatialAudio::RemoveRoom
392  /// - \ref AkRoomParams
394 
395  /// 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,
396  /// 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.
397  /// - \ref AK::SpatialAudio::SetRoom
398  /// - \ref AK::SpatialAudio::RemoveRoom
399  /// - \ref AkRoomParams
401 };
402 
403 /// Parameters passed to \c SetRoom
405 {
406  /// Constructor
408  , ReverbLevel(1.f)
409  , TransmissionLoss(1.f)
412  {
413  // default invalid values
414  Up.X = 0.f;
415  Up.Y = 1.f;
416  Up.Z = 0.f;
417  Front.X = 0.f;
418  Front.Y = 0.f;
419  Front.Z = 1.f;
420  }
421 
422  /// Copy Constructor
423  AkRoomParams(const AkRoomParams& in_rhs)
424  : Front(in_rhs.Front)
425  , Up(in_rhs.Up)
426  , ReverbAuxBus(in_rhs.ReverbAuxBus)
427  , ReverbLevel(in_rhs.ReverbLevel)
429  , strName(in_rhs.strName)
432  , GeometryID(in_rhs.GeometryID)
433  {
434  strName.AllocCopy();
435  }
436 
437  /// Assignment operator</span>
439  {
440  Front = in_rhs.Front;
441  Up = in_rhs.Up;
442  ReverbAuxBus = in_rhs.ReverbAuxBus;
443  ReverbLevel = in_rhs.ReverbLevel;
445 
446  strName = in_rhs.strName;
447  strName.AllocCopy();
448 
451 
452  GeometryID = in_rhs.GeometryID;
453 
454  return *this;
455  }
456 
457  /// Room Orientation. Up and Front must be orthonormal.
458  /// 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.
460 
461  /// Room Orientation. Up and Front must be orthonormal.
462  /// 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.
464 
465  /// The reverb aux bus that is associated with this room.
466  /// 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.
467  /// 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.
468  /// 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.
469  /// 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.
470  /// If more advanced control of reverb is desired, SetGameObjectAuxSendValues can be used to add additional sends on to a game object.
471  /// - \ref AK::SpatialAudio::SetGameObjectInRoom
472  /// - \ref AK::SoundEngine::SetGameObjectAuxSendValues
474 
475  /// The reverb control value for the send to ReverbAuxBus. Valid range: (0.f-1.f)
476  /// Can be used to implement multiple rooms that share the same aux bus, but have different reverb levels.
478 
479  /// Level to set when modeling transmission through walls. Transmission is modeled only when the sound emitted enables diffraction and there is no direct line of sight from the emitter to the listener.
480  /// This transmission loss value is only applied when the listener and the emitter are in different rooms; it is taken as the maximum between the emitter's room's transmission loss value and the listener's room's transmission loss value.
481  /// If there is geometry in between the listener and the emitter, then the transmission loss value assigned to surfaces hit by the ray between the emitter and listener is also taken into account.
482  /// The maximum of all the surfaces' transmission loss value (see \c AkAcousticSurface), and the room's transmission loss value is used to render the transmission path.
483  /// Valid range: (0.f-1.f)
484  /// - \ref AkAcousticSurface
486 
487  /// Name used to identify room (optional)
489 
490  /// 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,
491  /// 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
492  /// for spatial audio emitters sending to the room game object.
493  /// \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
494  /// 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
495  /// surround ambiance beds or room tones. Point source sounds should use separate game objects that are registered as spatial audio emitters.
496  /// \sa
497  /// - \ref AkRoomParams::RoomGameObj_KeepRegistered
498  /// - \ref AkRoomID
500 
501  /// 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
502  /// 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.
503  /// 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.
504  /// \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
505  /// 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
506  /// surround ambiance beds or room tones. Point source sounds should use separate game objects that are registered as spatial audio emitters.
507  /// \sa
508  /// - \ref AkRoomParams::RoomGameObj_AuxSendLevelToSelf
509  /// - \ref AkRoomID
511 
512  /// Associate this room with the geometry set \c GeometryID, describing the shape of the room. When a room is associated with a geometry set, the vertices are used to compute the spread value for room transmission.
513  /// The vertices are used for computing an oriented bounding box for the room where the orientation of the bounding box is given by the Up and Front vectors. The center of the room is defined as the oriented bounding box center.
514  /// The extent of the bounding box is computed from the geometry set's vertices projected on to the orientation axes.
515  /// \aknote If the geometry set is only to be used for the room and not for reflection and diffraction calculation, then make sure to set \c AkGeometryParams::EnableTriangles to false.
516  /// \sa
517  /// - \ref spatial_audio_roomsportals_apiconfigroomgeometry
518  /// - \ref AkGeometryParams
520 };
521 
522 /// Parameters passed to \c SetGeometry
524 {
525  /// Constructor
527 
528  /// Pointer to an array of AkTriangle structures.
529  /// This array will be copied into spatial audio memory and will not be accessed after \c SetGeometry returns.
530  /// - \ref AkTriangle
531  /// - \ref AK::SpatialAudio::SetGeometry
532  /// - \ref AK::SpatialAudio::RemoveGeometry
534 
535  /// Number of triangles in Triangles.
537 
538  /// Pointer to an array of AkVertex structures.
539  /// This array will be copied into spatial audio memory and will not be accessed after \c SetGeometry returns.
540  /// - \ref AkVertex
541  /// - \ref AK::SpatialAudio::SetGeometry
542  /// - \ref AK::SpatialAudio::RemoveGeometry
544 
545  ///< Number of vertices in Vertices.
547 
548  ///< Pointer to an array of AkAcousticSurface structures.
549  /// This array will be copied into spatial audio memory and will not be accessed after \c SetGeometry returns.
550  /// - \ref AkVertex
551  /// - \ref AK::SpatialAudio::SetGeometry
552  /// - \ref AK::SpatialAudio::RemoveGeometry
554 
555  /// Number of of AkTriangleInfo structures in in_pTriangleInfo and number of AkTriIdx's in in_infoMap.
557 
558  /// 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
559  /// 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),
560  /// 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
561  /// are associated with a room, that room will no longer be able to access geometry that is in the global scope.
562  /// - \ref AK::SpatialAudio::SetRoom
563  /// - \ref AkRoomParams
565 
566  /// Switch to enable or disable geometric diffraction for this Geometry.
568 
569  /// Switch to enable or disable geometric diffraction on boundary edges for this Geometry. Boundary edges are edges that are connected to only one triangle.
571 
572  /// Switch to enable or disable the use of the triangles for this Geometry. When enabled, the geometry triangles are indexed for ray computation and used to computed reflection and diffraction.
573  /// Set EnableTriangles to false when using a geometry set only to describe a room, and not for reflection and diffraction calculation.
574  /// \sa
575  /// - \ref AkRoomParams
577 };
578 
579 /// Audiokinetic namespace
580 namespace AK
581 {
582  /// Audiokinetic spatial audio namespace
583  namespace SpatialAudio
584  {
585  ////////////////////////////////////////////////////////////////////////
586  /// @name Basic functions.
587  /// In order to use SpatialAudio, you need to initalize it using Init, and register the listeners that you plan on using with any of the services offered by SpatialAudio, using
588  /// RegisterListener respectively, _after_ having registered their corresponding game object to the sound engine.
589  /// \akwarning At the moment, there can be only one Spatial Audio listener registered at any given time.
590  //@{
591 
592  /// Initialize the SpatialAudio API.
594 
595  /// 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.
596  /// 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.
597  /// 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
598  /// default listeners, then it is necessary to call RegisterListener() to specify which listener to use with Spatial Audio.
600  AkGameObjectID in_gameObjectID ///< Game object ID
601  );
602 
603  /// Unregister a game object as a listener in the SpatialAudio API; clean up Spatial Audio listener data associated with in_gameObjectID.
604  /// If in_gameObjectID is the current registered listener, calling this function will clear the Spatial Audio listener and
605  /// Spatial Audio features will be disabled until another listener is registered.
606  /// This function is optional - listener are automatically unregistered when their game object is deleted in the sound engine.
607  /// \sa
608  /// - \ref AK::SpatialAudio::RegisterListener
610  AkGameObjectID in_gameObjectID ///< Game object ID
611  );
612 
613  /// Define a inner and outer radius around each sound position for a specified game object.
614  /// The radii are used in spread and distance calculations, simulating a radial sound source.
615  /// When applying attenuation curves, the distance between the listener and the inner sphere (defined by the sound position and \c in_innerRadius) is used.
616  /// The spread for each sound position is calculated as follows:
617  /// - If the listener is outside the outer radius, then the spread is defined by the area that the sphere takes in the listener field of view. Specifically, this angle is calculated as 2.0*asinf( \c in_outerRadius / distance ), where distance is the distance between the listener and the sound position.
618  /// - When the listener intersects the outer radius (the listener is exactly \c in_outerRadius units away from the sound position), the spread is exactly 50%.
619  /// - When the listener is in between the inner and outer radius, the spread interpolates linearly from 50% to 100% as the listener transitions from the outer radius towards the inner radius.
620  /// - If the listener is inside the inner radius, the spread is 100%.
621  /// \aknote Transmission and diffraction calculations in Spatial Audio always use the center of the sphere (the position(s) passed into \c AK::SoundEngine::SetPosition or \c AK::SoundEngine::SetMultiplePositions) for raycasting.
622  /// To obtain accurate diffraction and transmission calculations for radial sources, where different parts of the volume may take different paths through or around geometry,
623  /// it is necessary to pass multiple sound positions into \c AK::SoundEngine::SetMultiplePositions to allow the engine to 'sample' the area at different points.
624  /// - \ref AK::SoundEngine::SetPosition
625  /// - \ref AK::SoundEngine::SetMultiplePositions
627  AkGameObjectID in_gameObjectID, ///< Game object ID
628  AkReal32 in_outerRadius, ///< Outer radius around each sound position, defining 50% spread. Must satisfy \c in_innerRadius <= \c in outerRadius.
629  AkReal32 in_innerRadius ///< Inner radius around each sound position, defining 100% spread and 0 attenuation distance. Must satisfy \c in_innerRadius <= \c in outerRadius.
630  );
631 
632  //@}
633 
634  ////////////////////////////////////////////////////////////////////////
635  /// @name Helper functions for passing game data to the Wwise Reflect plug-in.
636  /// Use this API for detailed placement of reflection image sources.
637  /// \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.
638  /// Functions of Geometry are preferred and easier to use with the Wwise Reflect plug-in. \endaknote
639  //@{
640 
641  /// Add or update an individual image source for processing via the AkReflect plug-in. Use this API for detailed placement of
642  /// 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
643  /// 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.
644  /// 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.
645  /// The image source will apply only to the the game object specified by \c in_gameObjectID.
646  /// 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.
647  /// This ID is used as a filter, so that it is not possible to hear reflections for rooms that the emitter and listener are not both inside. To use this feature, the emitter's and listener's rooms must also be
648  /// 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.
649  /// \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.
650  /// 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.
651  /// \endaknote
652  /// \aknote Early reflection send level and bus in the authoring tool do not apply to image sources set with \c SetImageSource(). When using this function, the Reflect bus and send level
653  /// may only be set programmatically. Also, it is not possible to use the geometric reflections API on the same aux bus and game object. If using the geometric reflections API and the SetImageSource API in conjunction, be sure to specify an
654  /// aux bus to \c SetImageSource that is unique from the aux bus(es) defined in the authoring tool, and from those passed to \c SetEarlyReflectionsAuxSend.
655  /// \endaknote
656  /// \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
657  /// \sa
658  /// - \ref AK::SpatialAudio::RemoveImageSource
659  /// - \ref AK::SpatialAudio::ClearImageSources
660  /// - \ref AK::SpatialAudio::SetGameObjectInRoom
661  /// - \ref AK::SpatialAudio::SetEarlyReflectionsAuxSend
663  AkImageSourceID in_srcID, ///< The ID of the image source being added.
664  const AkImageSourceSettings& in_info, ///< Image source information.
665  AkUniqueID in_AuxBusID, ///< Aux bus that has the AkReflect plug in for early reflection DSP.
666  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.
667  AkGameObjectID in_gameObjectID ///< The ID of the emitter game object to which the image source applies. Must be a valid and registered game object.
668  );
669 
670  /// Remove an individual reflection image source that was previously added via \c SetImageSource.
671  /// \sa
672  /// - \ref AK::SpatialAudio::SetImageSource
673  /// - \ref AK::SpatialAudio::ClearImageSources
675  AkImageSourceID in_srcID, ///< The ID of the image source to remove.
676  AkUniqueID in_AuxBusID, ///< Aux bus that was passed to SetImageSource.
677  AkGameObjectID in_gameObjectID ///< Game object ID that was passed to SetImageSource.
678  );
679 
680  /// Remove all image sources matching \c in_AuxBusID and \c in_gameObjectID that were previously added via \c SetImageSource.
681  /// Both \c in_AuxBusID and \c in_gameObjectID can be treated as wild cards matching all aux buses and/or all game object, by passing \c AK_INVALID_AUX_ID and/or \c AK_INVALID_GAME_OBJECT, respectively.
682  /// \sa
683  /// - \ref AK::SpatialAudio::SetImageSource
684  /// - \ref AK::SpatialAudio::RemoveImageSource
686  AkUniqueID in_AuxBusID = AK_INVALID_AUX_ID, ///< Aux bus that was passed to SetImageSource, or AK_INVALID_AUX_ID to match all aux buses.
687  AkGameObjectID in_gameObjectID = AK_INVALID_GAME_OBJECT ///< Game object ID that was passed to SetImageSource, or AK_INVALID_GAME_OBJECT to match all game objects.
688  );
689 
690  //@}
691 
692  ////////////////////////////////////////////////////////////////////////
693  /// @name Geometry
694  /// Geometry API for early reflection processing using Wwise Reflect.
695  //@{
696 
697  /// 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,
698  /// 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.
699  /// \sa
700  /// - \ref AkGeometryParams
701  /// - \ref AK::SpatialAudio::RemoveGeometry
703  AkGeometrySetID in_GeomSetID, ///< Unique geometry set ID, chosen by client.
704  const AkGeometryParams& in_params ///< Geometry parameters to set.
705  );
706 
707  /// Remove a set of geometry to the SpatialAudio API.
708  /// \sa
709  /// - \ref AK::SpatialAudio::SetGeometry
711  AkGeometrySetID in_SetID ///< ID of geometry set to be removed.
712  );
713 
714  /// 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.
715  /// This function must acquire the global sound engine lock and therefore, may block waiting for the lock.
716  /// \sa
717  /// - \ref AkReflectionPathInfo
719  AkGameObjectID in_gameObjectID, ///< The ID of the game object that the client wishes to query.
720  AkUInt32 in_positionIndex, ///< The index of the associated game object position.
721  AkVector& out_listenerPos, ///< Returns the position of the listener game object that is associated with the game object \c in_gameObjectID.
722  AkVector& out_emitterPos, ///< Returns the position of the emitter game object \c in_gameObjectID.
723  AkReflectionPathInfo* out_aPaths, ///< Pointer to an array of \c AkReflectionPathInfo's which will be filled after returning.
724  AkUInt32& io_uArraySize ///< The number of slots in \c out_aPaths, after returning the number of valid elements written.
725  );
726 
727  //@}
728 
729  ////////////////////////////////////////////////////////////////////////
730  /// @name Rooms and Portals
731  /// Sound Propagation API using rooms and portals.
732  //@{
733 
734  /// 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.
735  /// \akwarning 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
736  /// registration/unregistration of internal game objects for rooms that use these IDs and, therefore, must not collide.
737  /// Also, the room ID must not be in the reserved range (AkUInt64)(-32) to (AkUInt64)(-2) inclusively. You may, however, explicitly add the default room ID AK::SpatialAudio::kOutdoorRoomID (-1)
738  /// in order to customize its AkRoomParams, to provide a valid auxiliary bus, for example.\endakwarning
739  /// \sa
740  /// - \ref AkRoomID
741  /// - \ref AkRoomParams
742  /// - \ref AK::SpatialAudio::RemoveRoom
744  AkRoomID in_RoomID, ///< Unique room ID, chosen by the client.
745  const AkRoomParams& in_Params ///< Parameter for the room.
746  );
747 
748  /// Remove a room.
749  /// \sa
750  /// - \ref AkRoomID
751  /// - \ref AK::SpatialAudio::SetRoom
753  AkRoomID in_RoomID ///< Room ID that was passed to \c SetRoom.
754  );
755 
756  /// 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.
757  /// 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,
758  /// 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.
759  /// \sa
760  /// - \ref AkPortalID
761  /// - \ref AkPortalParams
762  /// - \ref AK::SpatialAudio::RemovePortal
764  AkPortalID in_PortalID, ///< Unique portal ID, chosen by the client.
765  const AkPortalParams& in_Params ///< Parameter for the portal.
766  );
767 
768  /// Remove a portal.
769  /// \sa
770  /// - \ref AkPortalID
771  /// - \ref AK::SpatialAudio::SetPortal
773  AkPortalID in_PortalID ///< ID of portal to be removed, which was originally passed to SetPortal.
774  );
775 
776  /// 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.
777  /// 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
778  /// 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
779  /// audio.
780  /// \sa
781  /// - \ref AK::SpatialAudio::SetRoom
782  /// - \ref AK::SpatialAudio::RemoveRoom
784  AkGameObjectID in_gameObjectID, ///< Game object ID
785  AkRoomID in_CurrentRoomID ///< RoomID that was passed to \c AK::SpatialAudio::SetRoom
786  );
787 
788  /// Set the early reflections order for reflection calculation. The reflections order indicates the number of times sound can bounce off of a surface.
789  /// A higher number requires more CPU resources but results in denser early reflections. Set to 0 to globally disable reflections processing.
791  AkUInt32 in_uReflectionsOrder, ///< Number of reflections to calculate. Valid range [0,4]
792  bool in_bUpdatePaths ///< Set to true to clear existing higher-order paths and to force the re-computation of new paths. If false, existing paths will remain and new paths will be computed when the emitter or listener moves.
793  );
794 
795  /// Set the number of rays cast from the listener by the stochastic ray casting engine.
796  /// A higher number requires more CPU resources but provides more accurate results. Default value (100) should be good for most applications.
797  ///
799  AkUInt32 in_uNbPrimaryRays ///< Number of rays cast from the listener
800  );
801 
802  /// Set an early reflections auxiliary bus for a particular game object.
803  /// Geometrical reflection calculation inside spatial audio is enabled for a game object if any sound playing on the game object has a valid early reflections aux bus specified in the authoring tool,
804  /// or if an aux bus is specified via \c SetEarlyReflectionsAuxSend.
805  /// The \c in_auxBusID parameter of SetEarlyReflectionsAuxSend applies to sounds playing on the game object \c in_gameObjectID which have not specified an early reflection bus in the authoring tool -
806  /// the parameter specified on individual sounds' reflection bus takes priority over the value passed in to \c SetEarlyReflectionsAuxSend.
807  /// \aknote
808  /// Users may apply this function to avoid duplicating sounds in the actor-mixer hierarchy solely for the sake of specifying a unique early reflection bus, or in any situation where the same
809  /// sound should be played on different game objects with different early reflection aux buses (the early reflection bus must be left blank in the authoring tool if the user intends to specify it through the API). \endaknote
811  AkGameObjectID in_gameObjectID, ///< Game object ID
812  AkAuxBusID in_auxBusID ///< Auxiliary bus ID. Applies only to sounds which have not specified an early reflection bus in the authoring tool. Pass \c AK_INVALID_AUX_ID to set only the send volume.
813  );
814 
815  /// Set an early reflections send volume for a particular game object.
816  /// The \c in_fSendVolume parameter is used to control the volume of the early reflections send. It is combined with the early reflections volume specified in the authoring tool, and is applied to all sounds
817  /// playing on the game object.
818  /// Setting \c in_fSendVolume to 0.f will disable all reflection processing for this game object.
820  AkGameObjectID in_gameObjectID, ///< Game object ID
821  AkReal32 in_fSendVolume ///< Send volume (linear) for auxiliary send. Set 0.f to disable reflection processing. Valid range 0.f-1.f.
822  );
823 
824  /// Set the obstruction and occlusion value for a portal that has been registered with Spatial Audio.
825  /// Portal obstruction is used to simulate objects between the portal and the listener that are obstructing the sound coming from the portal.
826  /// The obstruction value affects only the portals dry path, and should relate to how much of the opening
827  /// 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
828  /// which propagate from that room through this portal.
829  /// 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.
831  AkPortalID in_PortalID, ///< Portal ID.
832  AkReal32 in_fObstruction, ///< Obstruction value. Valid range 0.f-1.f
833  AkReal32 in_fOcclusion ///< Occlusion value. Valid range 0.f-1.f
834  );
835 
836  /// Set the obstruction value of the path between a game object and a portal that has been created by Spatial Audio.
837  /// The obstruction value is applied on one of the path segments of the sound between the emitter and the listener.
838  /// Diffraction must be enabled on the sound for a diffraction path to be created.
839  /// Also, there should not be any portals between the provided game object and portal ID parameters.
840  /// The obstruction value is used to simulate objects between the portal and the game object that are obstructing the sound.
841  /// Send an obstruction value of 0 to ensure the value is removed from the internal data structure.
843  AkGameObjectID in_gameObjectID, ///< Game object ID
844  AkPortalID in_PortalID, ///< Portal ID
845  AkReal32 in_fObstruction ///< Obstruction value. Valid range 0.f-1.f
846  );
847 
848  /// Set the obstruction value of the path between two portals that has been created by Spatial Audio.
849  /// The obstruction value is applied on one of the path segments of the sound between the emitter and the listener.
850  /// Diffraction must be enabled on the sound for a diffraction path to be created.
851  /// Also, there should not be any portals between the two provided ID parameters.
852  /// The obstruction value is used to simulate objects between the portals that are obstructing the sound.
853  /// Send an obstruction value of 0 to ensure the value is removed from the internal data structure.
855  AkPortalID in_PortalID0, ///< Portal ID
856  AkPortalID in_PortalID1, ///< Portal ID
857  AkReal32 in_fObstruction ///< Obstruction value. Valid range 0.f-1.f
858  );
859 
860  /// 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].
861  /// The wet diffraction is calculated from how far into the 'shadow region' the listener is from the portal. Unlike dry diffraction, the
862  /// wet diffraction does not depend on the incident angle, but only the normal of the portal.
863  /// 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
864  /// on the other side of the portal (relative to the listener).
865  /// This function must acquire the global sound engine lock and therefore, may block waiting for the lock.
866  /// \sa
867  /// - \ref AkSpatialAudioInitSettings
869  AkPortalID in_portal, ///< The ID of the game object that the client wishes to query.
870  AkReal32& out_wetDiffraction ///< The number of slots in \c out_aPaths, after returning the number of valid elements written.
871  );
872 
873  /// 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.
874  /// 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.
875  /// 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,
876  /// or (3) The emitter and listener are in different rooms, but there are no paths found via portals between the emitter and the listener.
877  /// 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 the Voice's Attenuation's curve max distance is exceeded or the accumulated diffraction coefficient exceeds 1.0.
878  /// This function must acquire the global sound engine lock and, therefore, may block waiting for the lock.
879  /// \sa
880  /// - \ref AkDiffractionPathInfo
882  AkGameObjectID in_gameObjectID, ///< The ID of the game object that the client wishes to query.
883  AkUInt32 in_positionIndex, ///< The index of the associated game object position.
884  AkVector& out_listenerPos, ///< Returns the position of the listener game object that is associated with the game object \c in_gameObjectID.
885  AkVector& out_emitterPos, ///< Returns the position of the emitter game object \c in_gameObjectID.
886  AkDiffractionPathInfo* out_aPaths, ///< Pointer to an array of \c AkDiffractionPathInfo's which will be filled on return.
887  AkUInt32& io_uArraySize ///< The number of slots in \c out_aPaths, after returning the number of valid elements written.
888  );
889 
890  /// Reset the stochastic engine state by re-initializing the random seeds.
891  ///
893 
894  //@}
895  }
896 };
AkTransform virtualPos
Virtual emitter position. This is the position that is passed to the sound engine to render the audio...
Definition: AkSpatialAudio.h:296
float AkReal32
32-bit floating point
Definition: AkTypes.h:70
bool RoomGameObj_KeepRegistered
Definition: AkSpatialAudio.h:510
AKSOUNDENGINE_API AKRESULT QueryWetDiffraction(AkPortalID in_portal, AkReal32 &out_wetDiffraction)
AkRoomParams(const AkRoomParams &in_rhs)
Copy Constructor.
Definition: AkSpatialAudio.h:423
AkUInt16 AkTriIdx
AKSOUNDENGINE_API AKRESULT UnregisterListener(AkGameObjectID in_gameObjectID)
Triangle for a spatial audio mesh.
Definition: AkSpatialAudio.h:177
AkUInt32 numPathPoints
Number of valid elements in the pathPoint[], surfaces[], and diffraction[] arrays.
Definition: AkSpatialAudio.h:249
AkVertex(AkReal32 in_X, AkReal32 in_Y, AkReal32 in_Z)
Constructor.
Definition: AkSpatialAudio.h:149
AkImageSourceParams params
Image source parameters.
Definition: AkSpatialAudio.h:133
Parameters passed to SetPortal.
Definition: AkSpatialAudio.h:336
Audiokinetic namespace.
AkVector imageSource
Apparent source of the reflected sound that follows this path.
Definition: AkSpatialAudio.h:238
AkReal32 TransmissionLoss
Definition: AkSpatialAudio.h:485
AKSOUNDENGINE_API AKRESULT RemovePortal(AkPortalID in_PortalID)
AkVector Front
Definition: AkSpatialAudio.h:459
bool EnableTriangles
Definition: AkSpatialAudio.h:576
AkTriIdx NumTriangles
Number of triangles in Triangles.
Definition: AkSpatialAudio.h:536
AkVector Up
Definition: AkSpatialAudio.h:463
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:139
bool bEnableGeometricDiffractionAndTransmission
Definition: AkSpatialAudio.h:71
AkPortalParams & operator=(const AkPortalParams &in_rhs)
Assignment operator.
Definition: AkSpatialAudio.h:355
AkReal32 transmissionLoss
Definition: AkSpatialAudio.h:228
AkVertIdx point2
Index into the vertex table passed into AkGeometryParams that describes the third vertex of the trian...
Definition: AkSpatialAudio.h:200
AkReal32 RoomGameObj_AuxSendLevelToSelf
Definition: AkSpatialAudio.h:499
AKSOUNDENGINE_API AKRESULT SetGameObjectInRoom(AkGameObjectID in_gameObjectID, AkRoomID in_CurrentRoomID)
AkAcousticSurface()
Constructor.
Definition: AkSpatialAudio.h:214
AkTriangle(AkVertIdx in_pt0, AkVertIdx in_pt1, AkVertIdx in_pt2, AkSurfIdx in_surfaceInfo)
Constructor.
Definition: AkSpatialAudio.h:186
AkReal32 Z
Z coordinate.
Definition: AkSpatialAudio.h:153
AkReal32 halfDepth
Definition: AkSpatialAudio.h:172
AKSOUNDENGINE_API AKRESULT Init(const AkSpatialAudioInitSettings &in_initSettings)
Initialize the SpatialAudio API.
AkPortalParams()
Constructor.
Definition: AkSpatialAudio.h:338
AkImageSourceSettings(AkVector in_sourcePosition, AkReal32 in_fDistanceScalingFactor, AkReal32 in_fLevel)
Definition: AkSpatialAudio.h:98
AkVector pathPoint[AK_MAX_REFLECTION_PATH_LENGTH]
Definition: AkSpatialAudio.h:242
AkAuxBusID ReverbAuxBus
Definition: AkSpatialAudio.h:473
#define AK_INVALID_VERTEX
AkUInt32 textureID
Definition: AkSpatialAudio.h:221
AkRoomID FrontRoom
Definition: AkSpatialAudio.h:393
AkRoomParams()
Constructor.
Definition: AkSpatialAudio.h:407
AkUInt32 nodeCount
Total number of nodes in the path. Defines the number of valid entries in the nodes,...
Definition: AkSpatialAudio.h:299
AkUInt64 AkGameObjectID
Game object ID.
Definition: AkTypes.h:70
AkPortalParams(const AkPortalParams &in_rhs)
Copy Constructor.
Definition: AkSpatialAudio.h:343
#define AK_EXTERNAPIFUNC(_type, _name)
AKSOUNDENGINE_API AKRESULT SetEarlyReflectionsAuxSend(AkGameObjectID in_gameObjectID, AkAuxBusID in_auxBusID)
AK::SpatialAudio::OsString strName
Name used to identify portal (optional).
Definition: AkSpatialAudio.h:386
AkUInt32 uNumTexture
Number of valid textures in the texture array.
AKRESULT
Standard function call result.
Definition: AkTypes.h:132
const char * strName
Name to describe this surface.
Definition: AkSpatialAudio.h:231
AkVector nodes[kMaxNodes]
Definition: AkSpatialAudio.h:276
AkAcousticSurface surfaces[AK_MAX_REFLECTION_PATH_LENGTH]
Definition: AkSpatialAudio.h:246
AkUInt32 AkImageSourceID
Image Source ID.
Definition: AkTypes.h:93
AkAcousticSurface * Surfaces
Definition: AkSpatialAudio.h:553
AkReal32 X
X coordinate.
Definition: AkSpatialAudio.h:151
AkReal32 fCPULimitPercentage
Definition: AkSpatialAudio.h:68
AKSOUNDENGINE_API AKRESULT RemoveImageSource(AkImageSourceID in_srcID, AkUniqueID in_AuxBusID, AkGameObjectID in_gameObjectID)
AkVertIdx NumVertices
Definition: AkSpatialAudio.h:546
#define NULL
Definition: AkTypes.h:47
AkReal32 ReverbLevel
Definition: AkSpatialAudio.h:477
AkUInt16 AkSurfIdx
AkReal32 halfHeight
Definition: AkSpatialAudio.h:171
AK::SpatialAudio::OsString strName
Name used to identify room (optional)
Definition: AkSpatialAudio.h:488
AKSOUNDENGINE_API AKRESULT SetGeometry(AkGeometrySetID in_GeomSetID, const AkGeometryParams &in_params)
Structure for retrieving information about the indirect paths of a sound that have been calculated vi...
Definition: AkSpatialAudio.h:236
AkGeometrySetID GeometryID
Definition: AkSpatialAudio.h:519
AkSurfIdx surface
Definition: AkSpatialAudio.h:204
AKSOUNDENGINE_API AKRESULT SetPortalToPortalObstruction(AkPortalID in_PortalID0, AkPortalID in_PortalID1, AkReal32 in_fObstruction)
AKSOUNDENGINE_API AKRESULT SetPortal(AkPortalID in_PortalID, const AkPortalParams &in_Params)
AkRoomID RoomID
Definition: AkSpatialAudio.h:564
bool isOccluded
Deprecated - always false. Occluded paths are not generated.
Definition: AkSpatialAudio.h:261
AkReal32 Y
Y Position.
Definition: AkTypes.h:340
bool bCalcEmitterVirtualPosition
An emitter that is diffracted through a portal or around geometry will have its apparent or virtual p...
Definition: AkSpatialAudio.h:77
AkUInt32 AkUniqueID
Unique 32-bit ID.
Definition: AkTypes.h:62
AkRoomParams & operator=(const AkRoomParams &in_rhs)
Assignment operator.
Definition: AkSpatialAudio.h:438
void SetOneTexture(AkUniqueID in_texture)
Definition: AkSpatialAudio.h:120
AkReal32 angles[kMaxNodes]
Raw diffraction angles at each point, in radians.
Definition: AkSpatialAudio.h:283
AkReal32 X
X Position.
Definition: AkTypes.h:339
AkReal32 Y
Y coordinate.
Definition: AkSpatialAudio.h:152
AKSOUNDENGINE_API AKRESULT ClearImageSources(AkUniqueID in_AuxBusID=AK_INVALID_AUX_ID, AkGameObjectID in_gameObjectID=AK_INVALID_GAME_OBJECT)
AkRoomID BackRoom
Definition: AkSpatialAudio.h:400
AkPortalID portals[kMaxNodes]
Definition: AkSpatialAudio.h:288
AkTriangle * Triangles
Definition: AkSpatialAudio.h:533
AkExtent Extent
Definition: AkSpatialAudio.h:379
AKSOUNDENGINE_API AKRESULT QueryReflectionPaths(AkGameObjectID in_gameObjectID, AkUInt32 in_positionIndex, AkVector &out_listenerPos, AkVector &out_emitterPos, AkReflectionPathInfo *out_aPaths, AkUInt32 &io_uArraySize)
AkReal32 transmissionLoss
Definition: AkSpatialAudio.h:320
AkUInt32 uNumberOfPrimaryRays
The number of primary rays used in the ray tracing engine. A larger number of rays will increase the ...
Definition: AkSpatialAudio.h:63
AkReal32 Z
Z Position.
Definition: AkTypes.h:341
AkUInt32 uMaxReflectionOrder
Maximum reflection order [1, 4] - the number of 'bounces' in a reflection path. A higher reflection o...
Definition: AkSpatialAudio.h:64
AkTriangle()
Constructor.
Definition: AkSpatialAudio.h:179
void SetName(const char *in_pName)
Definition: AkSpatialAudio.h:126
Initialization settings of the spatial audio module.
Definition: AkSpatialAudio.h:45
Vertex for a spatial audio mesh.
Definition: AkSpatialAudio.h:144
AkReal32 diffraction[AK_MAX_REFLECTION_PATH_LENGTH]
Diffraction amount, normalized to the range [0,1].
Definition: AkSpatialAudio.h:255
#define AK_MAX_REFLECTION_PATH_LENGTH
AKSOUNDENGINE_API AKRESULT RemoveRoom(AkRoomID in_RoomID)
AkVertex()
Constructor.
Definition: AkSpatialAudio.h:146
AKSOUNDENGINE_API AKRESULT SetReflectionsOrder(AkUInt32 in_uReflectionsOrder, bool in_bUpdatePaths)
AkVertIdx point0
Index into the vertex table passed into AkGeometryParams that describes the first vertex of the trian...
Definition: AkSpatialAudio.h:194
Base type for ID's used by Wwise spatial audio.
AkUInt32 numReflections
Number of reflections in the pathPoint[] array. Shadow zone diffraction does not count as a reflectio...
Definition: AkSpatialAudio.h:252
static const AkUniqueID AK_INVALID_UNIQUE_ID
Invalid unique 32-bit ID.
Definition: AkTypes.h:102
AKSOUNDENGINE_API AKRESULT ResetStochasticEngine()
bool EnableDiffraction
Switch to enable or disable geometric diffraction for this Geometry.
Definition: AkSpatialAudio.h:567
AkSurfIdx NumSurfaces
Number of of AkTriangleInfo structures in in_pTriangleInfo and number of AkTriIdx's in in_infoMap.
Definition: AkSpatialAudio.h:556
AkReal32 level
Linear gain applied to image source.
Definition: AkSpatialAudio.h:258
static const AkUInt32 kMaxNodes
Defines the maximum number of nodes that a user can retrieve information about. Longer paths will be ...
Definition: AkSpatialAudio.h:272
AKSOUNDENGINE_API AKRESULT SetGameObjectToPortalObstruction(AkGameObjectID in_gameObjectID, AkPortalID in_PortalID, AkReal32 in_fObstruction)
AkReal32 fMovementThreshold
Amount that an emitter or listener has to move to trigger a recalculation of reflections/diffraction....
Definition: AkSpatialAudio.h:62
static AkUInt32 GrowBy(AkUInt32)
Definition: AkSpatialAudio.h:40
AkImageSourceSettings & operator=(const AkImageSourceSettings &src)
Operator =.
Definition: AkSpatialAudio.h:111
AKSOUNDENGINE_API AKRESULT QueryDiffractionPaths(AkGameObjectID in_gameObjectID, AkUInt32 in_positionIndex, AkVector &out_listenerPos, AkVector &out_emitterPos, AkDiffractionPathInfo *out_aPaths, AkUInt32 &io_uArraySize)
AkRoomID rooms[kMaxNodes+1]
Definition: AkSpatialAudio.h:293
AkReal32 halfWidth
Definition: AkSpatialAudio.h:170
bool EnableDiffractionOnBoundaryEdges
Switch to enable or disable geometric diffraction on boundary edges for this Geometry....
Definition: AkSpatialAudio.h:570
static const AkGameObjectID AK_INVALID_GAME_OBJECT
Invalid game object (may also mean all game objects)
Definition: AkTypes.h:101
AKRESULT AllocCopy()
Definition: AkString.h:85
AKSOUNDENGINE_API AKRESULT SetImageSource(AkImageSourceID in_srcID, const AkImageSourceSettings &in_info, AkUniqueID in_AuxBusID, AkRoomID in_roomID, AkGameObjectID in_gameObjectID)
AkExtent(AkReal32 in_halfWidth, AkReal32 in_halfHeight, AkReal32 in_halfDepth)
Definition: AkSpatialAudio.h:164
AkImageSourceTexture texture
Acoustic texture that goes with this image source.
Definition: AkSpatialAudio.h:136
uint32_t AkUInt32
Unsigned 32-bit integer.
Definition: AkTypes.h:59
#define AK_INVALID_SURFACE
static const AkAuxBusID AK_INVALID_AUX_ID
Invalid auxiliary bus ID (or no Aux bus ID)
Definition: AkTypes.h:108
AkVertex * Vertices
Number of vertices in Vertices.
Definition: AkSpatialAudio.h:543
AkUInt32 AkAuxBusID
Auxilliary bus ID.
Definition: AkTypes.h:75
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
AkUInt16 AkVertIdx
3D vector.
Definition: AkTypes.h:311
AkExtent()
Definition: AkSpatialAudio.h:162
bool bEnableDiffractionOnReflection
Enable diffraction at the end/beginning of reflection paths. Diffraction on reflection causes reflect...
Definition: AkSpatialAudio.h:70
AkTransform Transform
Definition: AkSpatialAudio.h:374
AKSOUNDENGINE_API AKRESULT SetEarlyReflectionsVolume(AkGameObjectID in_gameObjectID, AkReal32 in_fSendVolume)
AkGeometryParams()
Constructor.
Definition: AkSpatialAudio.h:526
AkReal32 diffraction
Definition: AkSpatialAudio.h:307
void Term()
Definition: AkString.h:40
AKSOUNDENGINE_API AKRESULT SetPortalObstructionAndOcclusion(AkPortalID in_PortalID, AkReal32 in_fObstruction, AkReal32 in_fOcclusion)
AkReal32 obstructionValue
Definition: AkSpatialAudio.h:331
AKSOUNDENGINE_API AKRESULT RemoveGeometry(AkGeometrySetID in_SetID)
AkUniqueID arTextureID[AK_MAX_NUM_TEXTURE]
Unique IDs of the Acoustics Texture ShareSets used to filter this image source.
AKSOUNDENGINE_API AKRESULT SetRoom(AkRoomID in_RoomID, const AkRoomParams &in_Params)
Parameters passed to SetRoom.
Definition: AkSpatialAudio.h:405
#define AK_MAX_SOUND_PROPAGATION_DEPTH
Position and orientation of game objects.
Definition: AkTypes.h:346
Parameters passed to SetGeometry.
Definition: AkSpatialAudio.h:524
AkVertIdx point1
Index into the vertex table passed into AkGeometryParams that describes the second vertex of the tria...
Definition: AkSpatialAudio.h:197
AKSOUNDENGINE_API AKRESULT RegisterListener(AkGameObjectID in_gameObjectID)
AKSOUNDENGINE_API AKRESULT SetGameObjectRadius(AkGameObjectID in_gameObjectID, AkReal32 in_outerRadius, AkReal32 in_innerRadius)
AKSOUNDENGINE_API AKRESULT SetNumberOfPrimaryRays(AkUInt32 in_uNbPrimaryRays)
#define AK_DEFAULT_MOVEMENT_THRESHOLD

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