Table of Contents

include/AK/SpatialAudio/Common/AkSpatialAudio.h

Go to the documentation of this file.
00001 /*******************************************************************************
00002 The content of this file includes portions of the AUDIOKINETIC Wwise Technology
00003 released in source code form as part of the SDK installer package.
00004 
00005 Commercial License Usage
00006 
00007 Licensees holding valid commercial licenses to the AUDIOKINETIC Wwise Technology
00008 may use this file in accordance with the end user license agreement provided
00009 with the software or, alternatively, in accordance with the terms contained in a
00010 written agreement between you and Audiokinetic Inc.
00011 
00012 Apache License Usage
00013 
00014 Alternatively, this file may be used under the Apache License, Version 2.0 (the
00015 "Apache License"); you may not use this file except in compliance with the
00016 Apache License. You may obtain a copy of the Apache License at
00017 http://www.apache.org/licenses/LICENSE-2.0.
00018 
00019 Unless required by applicable law or agreed to in writing, software distributed
00020 under the Apache License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES
00021 OR CONDITIONS OF ANY KIND, either express or implied. See the Apache License for
00022 the specific language governing permissions and limitations under the License.
00023 
00024 Version: <VERSION>  Build: <BUILDNUMBER>
00025 Copyright (c) <COPYRIGHTYEAR> Audiokinetic Inc.
00026 *******************************************************************************/
00027 
00028 /// \file 
00029 /// Spatial Audio interface.
00030 
00031 #pragma once
00032 
00033 #include <AK/SpatialAudio/Common/AkSpatialAudioTypes.h>
00034 #include <AK/Plugin/AkReflectGameData.h>
00035 
00036 /// AkDiffractionFlags determine if diffraction values for sound passing through portals will be calculated, and how to apply those calculations to Wwise parameters.
00037 enum AkDiffractionFlags
00038 {
00039     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.
00040     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.
00041     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.
00042 
00043     DefaultDiffractionFlags = DiffractionFlags_UseBuiltInParam | DiffractionFlags_UseObstruction | DiffractionFlags_CalcEmitterVirtualPosition
00044 };
00045 
00046 /// Initialization settings of the spatial audio module.
00047 struct AkSpatialAudioInitSettings
00048 {
00049     AkSpatialAudioInitSettings() : uPoolID(AK_INVALID_POOL_ID)
00050         , uPoolSize(4 * 1024 * 1024)
00051         , uMaxSoundPropagationDepth(AK_MAX_SOUND_PROPAGATION_DEPTH)
00052         , uDiffractionFlags((AkUInt32)DefaultDiffractionFlags)
00053         , fDiffractionShadowAttenFactor(AK_DEFAULT_DIFFR_SHADOW_ATTEN)
00054         , fDiffractionShadowDegrees(AK_DEFAULT_DIFFR_SHADOW_DEGREES)
00055     {}
00056 
00057     AkMemPoolId uPoolID;                    ///< User-provided pool ID (see AK::MemoryMgr::CreatePool).
00058     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).
00059     AkUInt32 uMaxSoundPropagationDepth;     ///< Maximum number of portals that sound can propagate through; must be less than or equal to AK_MAX_SOUND_PROPAGATION_DEPTH.
00060     AkUInt32 uDiffractionFlags;             ///< Enable or disable specific diffraction features. See AkDiffractionFlags.
00061     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. 
00062     AkReal32 fDiffractionShadowDegrees;     ///< Interpolation angle, in degrees, over which the fDiffractionShadowAttenFactor is applied.  
00063                                             ///< At a diffraction of 0, a multiplier of 1 (ie. none) is applied, and at an angle of fDiffractionShadowDegrees or greater, fDiffractionShadowAttenFactor is applied.
00064                                             ///< A linear interpolation between 1 and fDiffractionShadowAttenFactor is applied when the angle is between 0 and fDiffractionShadowDegrees.
00065 };
00066 
00067 // Settings for individual image sources.
00068 struct AkImageSourceSettings
00069 {
00070     AkImageSourceSettings() {}
00071 
00072     AkImageSourceSettings(AkVector in_sourcePosition, AkReal32 in_fDistanceScalingFactor, AkReal32 in_fLevel)
00073         : params(in_sourcePosition, in_fDistanceScalingFactor, in_fLevel)
00074         , texture()
00075         , name()
00076     {
00077     }
00078 
00079     ~AkImageSourceSettings()
00080     {
00081         name.Term();
00082     }
00083 
00084     /// Operator =
00085     AkImageSourceSettings& operator =(const AkImageSourceSettings & src)
00086     {
00087         params = src.params;
00088         texture = src.texture;
00089         name = src.name;
00090         name.AllocCopy();
00091         return *this;
00092     }
00093 
00094     void SetOneTexture(AkUniqueID in_texture)
00095     {
00096         texture.uNumTexture = 1;
00097         texture.arTextureID[0] = in_texture;
00098     }
00099 
00100     void SetName(const char* in_pName)
00101     {
00102         name = in_pName;
00103         name.AllocCopy();
00104     }
00105 
00106     /// Image source parameters.
00107     AkImageSourceParams params;
00108 
00109     /// Acoustic texture that goes with this image source.
00110     AkImageSourceTexture texture;
00111 
00112     /// Name given to image source, can be used to identify the image source in the AK Reflect plugin UI.
00113     AK::SpatialAudio::String name;
00114 };
00115 
00116 /// Settings for a sound emitter.
00117 struct AkEmitterSettings
00118 {
00119     /// Constructor
00120     AkEmitterSettings() : reflectAuxBusID(AK_INVALID_UNIQUE_ID)
00121                         , reflectionMaxPathLength(kDefaultMaxPathLength)
00122                         , reflectionsAuxBusGain(1.0f)
00123                         , reflectionsOrder(1)
00124                         , reflectorFilterMask(0xFFFFFFFF)
00125                         , roomReverbAuxBusGain(1.0f)
00126                         , diffractionMaxEdges(0)
00127                         , diffractionMaxPaths(8)
00128                         , diffractionMaxPathLength(kDefaultMaxPathLength)
00129     {
00130         useImageSources = true;
00131     }
00132 
00133     /// Name given to this sound emitter.
00134     AK::SpatialAudio::OsString name;
00135 
00136     /// 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.
00137     /// \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
00138     AkUniqueID reflectAuxBusID;
00139 
00140     /// A heuristic to stop the computation of reflections. Should be no longer (and possibly shorter for less CPU usage) than the maximum attenuation of
00141     /// the sound emitter.
00142     AkReal32 reflectionMaxPathLength;
00143 
00144     /// Send gain (0.f-1.f) that is applied when sending to the bus that has the AkReflect plug-in. (reflectAuxBusID)
00145     AkReal32 reflectionsAuxBusGain;
00146 
00147     /// Maximum number of reflections that will be processed when computing indirect paths via the geometric reflections API. Reflection processing grows
00148     /// exponentially with the order of reflections, so this number should be kept low.  Valid range: 1-4.
00149     AkUInt32 reflectionsOrder;
00150 
00151     /// 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 
00152     /// 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 
00153     /// 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.  
00154     AkUInt32 reflectorFilterMask;
00155 
00156     /// 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).
00157     /// 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(),
00158     /// and therefore may be used to scale and/or disable room reverb, either temporarily or permanently, for a specific emitter.
00159     /// \sa
00160     /// - \ref AkRoomParams
00161     /// - \ref AK::SpatialAudio::SetEmitterAuxSendValues
00162     AkReal32 roomReverbAuxBusGain;
00163 
00164     /// The maximum number of edges that the sound can diffract around between the emitter and the listener. Applies only to geometric diffraction, and not to sound propagation. 
00165     /// Setting \c diffractionMaxEdges to 0 effectively disables geometric diffraction for this sound emitter.
00166     AkUInt32 diffractionMaxEdges;
00167 
00168     /// The maximum number of paths to the listener that the sound can take around obstacles.  Applies only to geometric diffraction, and not sound propagation. 
00169     /// Diffraction paths map directly to virtual sound positions. Setting \c diffractionMaxPaths limits the number sound positions that are rendered for the game object. 
00170     /// Setting \c diffractionMaxPaths to 0 effectively disables geometric diffraction for this sound emitter.
00171     AkUInt32 diffractionMaxPaths;
00172 
00173     /// The maximum length that a diffracted sound can travel.  Should be no longer (and possibly shorter for less CPU usage) than the maximum attenuation of
00174     /// the sound emitter. Applies only to geometric diffraction, and not to sound propagation. 
00175     AkReal32 diffractionMaxPathLength;
00176 
00177     /// Enable reflections from image sources that have been added via the \c AK::SpatialAudio::SetImageSource() API. (Does not apply to geometric reflections.)
00178     AkUInt8 useImageSources : 1;
00179 };
00180 
00181 /// Vertex for a spatial audio mesh.
00182 struct AkVertex
00183 {
00184     /// Constructor
00185     AkVertex() : X(0.f), Y(0.f), Z(0.f) {}
00186     
00187     /// Constructor
00188     AkVertex(AkReal32 in_X, AkReal32 in_Y, AkReal32 in_Z) : X(in_X), Y(in_Y), Z(in_Z) {}
00189 
00190     AkReal32 X; ///< X coordinate
00191     AkReal32 Y; ///< Y coordinate
00192     AkReal32 Z; ///< Z coordinate
00193 };
00194 
00195 /// Triangle for a spatial audio mesh. 
00196 struct AkTriangle
00197 {
00198     /// Constructor
00199     AkTriangle()    : point0(AK_INVALID_VERTEX)
00200                     , point1(AK_INVALID_VERTEX)
00201                     , point2(AK_INVALID_VERTEX)
00202                     , surface(AK_INVALID_SURFACE)
00203     {}
00204 
00205     /// Constructor
00206     AkTriangle(AkVertIdx in_pt0, AkVertIdx in_pt1, AkVertIdx in_pt2, AkSurfIdx in_surfaceInfo) 
00207         : point0(in_pt0)
00208         , point1(in_pt1)
00209         , point2(in_pt2)
00210         , surface(in_surfaceInfo)
00211     {}
00212 
00213     /// 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.
00214     AkVertIdx point0; 
00215 
00216     /// 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.
00217     AkVertIdx point1;
00218 
00219     /// 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.
00220     AkVertIdx point2;
00221 
00222     /// Index into the surface table passed into \c AkGeometryParams that describes the surface properties of the triangle.  
00223     /// If this field is left as \c AK_INVALID_SURFACE, then a default-constructed \c AkAcousticSurface is used.
00224     AkSurfIdx surface;
00225 };
00226 
00227 /// Describes the acoustic surface properties of one or more triangles.
00228 /// 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 
00229 /// \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.
00230 /// 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.
00231 struct AkAcousticSurface
00232 {
00233     /// Constructor
00234     AkAcousticSurface(): textureID(AK_INVALID_UNIQUE_ID)
00235                 , reflectorChannelMask((AkUInt32)-1)
00236                 , strName(NULL)
00237     {}
00238 
00239     /// 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
00240     /// \sa <tt>\ref AK::SoundEngine::GetIDFromString()</tt>
00241     AkUInt32 textureID;
00242 
00243     /// 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.  
00244     AkUInt32 reflectorChannelMask;
00245 
00246     /// Name to describe this surface
00247     const char* strName;
00248 };
00249 
00250 /// 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.
00251 struct AkReflectionPathInfo
00252 {
00253     /// Apparent source of the reflected sound that follows this path.
00254     AkVector imageSource;
00255     
00256     /// Vertices of the indirect path.
00257     /// pathPoint[0] is closest to the emitter, pathPoint[numPathPoints-1] is closest to the listener.
00258     AkVector pathPoint[AK_MAX_REFLECTION_PATH_LENGTH];
00259 
00260     /// The surfaces that were hit in the path.
00261     /// surfaces[0] is closest to the emitter, surfaces[numPathPoints-1] is closest to the listener.
00262     AkAcousticSurface surfaces[AK_MAX_REFLECTION_PATH_LENGTH];
00263 
00264     /// Number of valid elements in the \c pathPoint[], \c surfaces[], and \c diffraction[] arrays.
00265     AkUInt32 numPathPoints;
00266 
00267     /// 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.
00268     AkUInt32 numReflections;
00269 
00270     /// Diffraction amount, normalized to the range [0,1]
00271     AkReal32 diffraction[AK_MAX_REFLECTION_PATH_LENGTH];
00272     
00273     /// The point that was hit to cause the path to be occluded. Note that the spatial audio library must be recompiled with \c \#define AK_DEBUG_OCCLUSION to enable generation of occluded paths.
00274     AkVector occlusionPoint;
00275 
00276     /// Linear gain applied to image source.
00277     AkReal32 level;
00278 
00279     /// 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.
00280     bool isOccluded;
00281 };
00282 
00283 /// Structure for retrieving information about diffraction paths for a given emitter. 
00284 /// Both the sound propagation (rooms and portals) system or the geometric diffraction system return infomation in this structure.
00285 struct AkDiffractionPathInfo
00286 {
00287     /// Defines the maximum number of nodes that a user can retrieve information about.  Longer paths will be truncated. 
00288     static const AkUInt32 kMaxNodes = AK_MAX_SOUND_PROPAGATION_DEPTH;
00289 
00290     /// Diffraction points
00291     AkVector nodes[kMaxNodes];
00292 
00293     /// Raw diffraction angles at each point, in radians.
00294     AkReal32 angles[kMaxNodes];
00295 
00296     /// Virtual emitter position.
00297     AkTransform virtualPos;
00298 
00299     /// Total number of nodes in the path.  Defines the number of valid entries in the \c nodes and \c angles arrays.
00300     AkUInt32 nodeCount;
00301 
00302     /// Calculated total diffraction from this path, normalize to the range [0,1]
00303     AkReal32 diffraction;
00304 
00305     /// Total path length
00306     AkReal32 totLength;
00307 
00308     /// Obstruction value for this path.
00309     AkReal32 obstructionValue;
00310 };
00311 
00312 /// Structure for retrieving information about the sound propagation paths that have been calculated via the rooms and portals API.  Useful for debug draw applications.
00313 struct AkPropagationPathInfo
00314 {
00315     /// Defines the maximum number of nodes that a user can retrieve information about.  Longer paths will be truncated. 
00316     static const AkUInt32 kMaxNodes = AK_MAX_SOUND_PROPAGATION_DEPTH;
00317 
00318     ///  Nodes in the path; they repreent vertices within the bounds of a portal's opening.  
00319     AkVector nodePoint[kMaxNodes];
00320 
00321     /// ID of the portal's that the path passes through.  portal[0] is the portal closest to the listener; portal[numNodes-1] is the portal closest to the emitter.
00322     AkPortalID portals[kMaxNodes];
00323 
00324     /// ID's of the rooms that the path passes through. There is always one more room than portal. room[0] is the listener's room; the emitters room is room[numNodes].
00325     AkRoomID rooms[kMaxNodes+1];
00326 
00327     /// Represents the number of valid nodes in nodePoint[] and the number of valid portals in portals[].  The number of rooms in rooms[] is numNodes+1. There is always one more room than portal.
00328     AkUInt32 numNodes;
00329 
00330     /// The sum of all straight line path segments, including the segment from the listener to nodePoint[0], between each subsequent nodePoint, and from nodePoint[numNodes-1] to the emitter.
00331     AkReal32 length;
00332     
00333     /// The cumulative gain (linear) of all portals traversed.  
00334     AkReal32 gain;
00335 
00336     /// The dry diffraction amount is normalized in the range [0,1], and calculated from the maximum deviation angle from a straight line, of all angles at each nodePoint.  Can be thought of as how
00337     //  far into the 'shadow region' the sound has to 'bend' to reach the listener.
00338     /// Depending on the spatial audio initialization settings, this value that is applied internally, by spatial audio, to the obstruction or built-in parameter of the emitter game object.
00339     /// \sa
00340     /// - \ref AkDiffractionFlags
00341     /// - \ref AkSpatialAudioInitSettings
00342     AkReal32 dryDiffraction;
00343 
00344     /// The wet diffraction amount for the portal closest to the listener, normalized in the range [0,1].  
00345     /// The wet diffraction is calculated from how far into the 'shadow region' the listener is from the closest portal.  Unlike dry diffraction, the 
00346     /// wet diffraction does not depend on the incident angle, but only the normal of the portal.
00347     /// Depending on the spatial audio initialization settings, this value that is applied internally, by spatial audio, to the obstruction/built-in parameter of the room game object that is
00348     /// on the other side of the portal closest to the listener.
00349     /// \sa
00350     /// - \ref AkDiffractionFlags
00351     /// - \ref AkSpatialAudioInitSettings
00352     AkReal32 wetDiffraction;
00353 };
00354 
00355 /// Parameters passed to \c SetPortal
00356 struct AkPortalParams
00357 {
00358     /// Constructor
00359     AkPortalParams() :
00360         bEnabled(false)
00361     {}
00362 
00363     /// Portal's position and orientation in the 3D world. 
00364     /// Position vector is the center of the opening.
00365     /// 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. 
00366     /// 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.
00367     AkTransform                     Transform;
00368 
00369     /// 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, 
00370     /// 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 
00371     /// that results in appropriately smooth transitions between rooms.
00372     AkVector                        Extent;
00373 
00374     /// Whether or not the portal is active/enabled. For example, this parameter may be used to simulate open/closed doors.
00375     /// Portal diffraction is simulated when at least one portal exists and is active between an emitter and the listener. Otherwise, transmission is simulated. 
00376     /// Diffraction uses obstruction or the diffraction built-in game parameter, while transmission uses occlusion.
00377     bool                            bEnabled;
00378 
00379     /// Name used to identify portal (optional).
00380     AK::SpatialAudio::OsString      strName;
00381 
00382     /// 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,
00383     /// 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.
00384     /// - \ref AK::SpatialAudio::SetRoom
00385     /// - \ref AK::SpatialAudio::RemoveRoom
00386     /// - \ref AkRoomParams
00387     AkRoomID FrontRoom;
00388 
00389     /// 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,
00390     /// 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.
00391     /// - \ref AK::SpatialAudio::SetRoom
00392     /// - \ref AK::SpatialAudio::RemoveRoom
00393     /// - \ref AkRoomParams
00394     AkRoomID BackRoom;
00395 };
00396 
00397 /// Parameters passed to \c SetRoom
00398 struct AkRoomParams
00399 {
00400     /// Constructor
00401     AkRoomParams() :  ReverbAuxBus(AK_INVALID_AUX_ID)
00402                     , ReverbLevel(1.f)
00403                     , WallOcclusion(1.f)
00404                     , RoomGameObj_AuxSendLevelToSelf(0.f)
00405                     , RoomGameObj_KeepRegistered(false)
00406                     
00407     {
00408         Up.X = 0.f;
00409         Up.Y = 1.f;
00410         Up.Z = 0.f;
00411         Front.X = 0.f;
00412         Front.Y = 0.f;
00413         Front.Z = 1.f;
00414     }
00415 
00416     /// Room Orientation. Up and Front must be orthonormal.
00417     /// 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.
00418     AkVector                        Up;
00419     AkVector                        Front;
00420 
00421     /// The reverb aux bus that is associated with this room.  
00422     /// 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.
00423     /// 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.  
00424     /// 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.
00425     /// 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.
00426     /// If more advanced control of reverb is desired, SetEmitterAuxSendValues can be used to add additional sends on to a game object.
00427     /// - \ref AK::SpatialAudio::SetGameObjectInRoom
00428     /// - \ref AK::SpatialAudio::SetEmitterAuxSendValues
00429     AkAuxBusID                      ReverbAuxBus;
00430 
00431     /// The reverb control value for the send to ReverbAuxBus. Valid range: (0.f-1.f)
00432     /// Can be used to implement multiple rooms that share the same aux bus, but have different reverb levels.
00433     AkReal32                        ReverbLevel;
00434 
00435     /// 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
00436     /// room and the emitter's room. Valid range: (0.f-1.f)
00437     AkReal32                        WallOcclusion;
00438     
00439     /// Name used to identify room (optional)
00440     AK::SpatialAudio::OsString      strName;
00441 
00442     /// 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, 
00443     /// 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 
00444     /// for spatial audio emitters sending to the room game object.
00445     /// \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 
00446     /// 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
00447     /// surround ambiance beds or room tones. Point source sounds should use separate game objects that are registered as spatial audio emitters.
00448     /// \sa
00449     /// - \ref AkRoomParams::RoomGameObj_KeepRegistered
00450     /// - \ref AkRoomID
00451     AkReal32                        RoomGameObj_AuxSendLevelToSelf;
00452 
00453     /// 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
00454     /// 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.
00455     /// 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.
00456     /// \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 
00457     /// 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
00458     /// surround ambiance beds or room tones. Point source sounds should use separate game objects that are registered as spatial audio emitters.
00459     /// \sa
00460     /// - \ref AkRoomParams::RoomGameObj_AuxSendLevelToSelf
00461     /// - \ref AkRoomID
00462     bool                            RoomGameObj_KeepRegistered;
00463 
00464 
00465 };
00466 
00467 /// Parameters passed to \c SetGeometry
00468 struct AkGeometryParams
00469 {
00470     /// Constructor
00471     AkGeometryParams() : Triangles(NULL), NumTriangles(0), Vertices(NULL), NumVertices(0), Surfaces(NULL), NumSurfaces(0), EnableDiffraction(false), EnableDiffractionOnBoundaryEdges(false) {}
00472 
00473     /// Pointer to an array of AkTriangle structures. 
00474     /// This array will be copied into the spatial audio memory pool and will not be accessed after \c SetGeometry returns.
00475     /// - \ref AkTriangle
00476     /// - \ref AK::SpatialAudio::SetGeometry
00477     /// - \ref AK::SpatialAudio::RemoveGeometry
00478     AkTriangle* Triangles;
00479 
00480     /// Number of triangles in Triangles.
00481     AkTriIdx NumTriangles;          
00482 
00483     /// Pointer to an array of AkVertex structures. 
00484     /// This array will be copied into the spatial audio memory pool and will not be accessed after \c SetGeometry returns.
00485     /// - \ref AkVertex
00486     /// - \ref AK::SpatialAudio::SetGeometry
00487     /// - \ref AK::SpatialAudio::RemoveGeometry
00488     AkVertex* Vertices;
00489 
00490     ///< Number of vertices in Vertices.
00491     AkVertIdx NumVertices;          
00492     
00493     ///< Pointer to an array of AkAcousticSurface structures.
00494     /// This array will be copied into the spatial audio memory pool and will not be accessed after \c SetGeometry returns.
00495     /// - \ref AkVertex
00496     /// - \ref AK::SpatialAudio::SetGeometry
00497     /// - \ref AK::SpatialAudio::RemoveGeometry
00498     AkAcousticSurface* Surfaces;
00499 
00500     /// Number of of AkTriangleInfo structures in in_pTriangleInfo and number of AkTriIdx's in in_infoMap.
00501     AkSurfIdx NumSurfaces;
00502 
00503     /// Switch to enable or disable geometric diffraction for this Geometry.
00504     bool EnableDiffraction;
00505     
00506     /// Switch to enable or disable geometric diffraction on boundary edges for this Geometry.  Boundary edges are edges that are connected to only one triangle.
00507     bool EnableDiffractionOnBoundaryEdges;
00508 };
00509 
00510 /// Audiokinetic namespace
00511 namespace AK
00512 {
00513     /// Audiokinetic spatial audio namespace
00514     namespace SpatialAudio
00515     {
00516         ////////////////////////////////////////////////////////////////////////
00517         /// @name Basic functions. 
00518         /// 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 
00519         /// 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 
00520         /// SetPosition and SetEmitterAuxSendValues instead of their AK::SoundEngine counterparts.
00521         ///\akwarning At the moment, there can be only one Spatial Audio listener registered at any given time.
00522         //@{
00523 
00524         /// Access the internal pool ID passed to Init.
00525         AK_EXTERNAPIFUNC(AkMemPoolId, GetPoolID)();
00526     
00527         /// Initialize the SpatialAudio API.  
00528         AK_EXTERNAPIFUNC(AKRESULT, Init)(const AkSpatialAudioInitSettings& in_initSettings);
00529         
00530         /// 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 
00531         /// registered in the sound engine via \c AK::SoundEngine::RegisterGameObj().  
00532         /// \sa 
00533         /// - \ref AkEmitterSettings
00534         AK_EXTERNAPIFUNC(AKRESULT, RegisterEmitter)(
00535             AkGameObjectID in_gameObjectID,             ///< Game object ID
00536             const AkEmitterSettings& in_settings        ///< Settings for the spatial audio emitter.
00537         );
00538 
00539         /// Unregister a game object as a sound emitter in the SpatialAudio API; clean up Spatial Audio listener data associated with in_gameObjectID.  
00540         /// This function is optional - emitters are automatically unregistered when their game object is deleted in the sound engine.
00541         /// \sa 
00542         /// - \ref AK::SpatialAudio::RegisterEmitter
00543         AK_EXTERNAPIFUNC(AKRESULT, UnregisterEmitter)(
00544             AkGameObjectID in_gameObjectID              ///< Game object ID
00545         );
00546 
00547         /// 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.
00548         /// 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.
00549         /// 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
00550         /// default listeners, then it is necessary to call RegisterListener() to specify which listener to use with Spatial Audio.
00551         AK_EXTERNAPIFUNC(AKRESULT, RegisterListener)(
00552             AkGameObjectID in_gameObjectID              ///< Game object ID
00553             );
00554 
00555         /// Unregister a game object as a listener in the SpatialAudio API; clean up Spatial Audio listener data associated with in_gameObjectID.  
00556         /// If in_gameObjectID is the current registered listener, calling this function will clear the Spatial Audio listener and
00557         /// Spatial Audio features will be disabled until another listener is registered.
00558         /// This function is optional - listener are automatically unregistered when their game object is deleted in the sound engine.
00559         /// \sa 
00560         /// - \ref AK::SpatialAudio::RegisterListener
00561         AK_EXTERNAPIFUNC(AKRESULT, UnregisterListener)(
00562             AkGameObjectID in_gameObjectID              ///< Game object ID
00563             );
00564 
00565         /// Set the position of an emitter game object that has been registered with the SpatialAudio API.  
00566         /// 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 
00567         /// for all spatial audio services, such as Rooms and GeometrySets (see SpatialAudio::SetRoom and SpatialAudio::SetGeometry).
00568         /// 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
00569         /// that are passed to the sound engine and used to render audio.
00570         /// 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().
00571         AK_EXTERNAPIFUNC(AKRESULT, SetPosition)(
00572             AkGameObjectID in_gameObjectID,         ///< Game object ID of the sound emitter.
00573             const AkTransform& in_sourcePosition    ///< Physical position of the emitter in the simulation.
00574             );
00575 
00576         /// Set the aux send values for an emitter game object that has been registered with the SpatialAudio API.  
00577         /// 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
00578         //  for early reflection processing.
00579         /// 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().
00580         /// \sa 
00581         /// - \ref AK::SoundEngine::SetGameObjectAuxSendValues
00582         AK_EXTERNAPIFUNC(AKRESULT, SetEmitterAuxSendValues)(
00583             AkGameObjectID in_gameObjectID, ///< Game object ID of the sound emitter.
00584             AkAuxSendValue* in_pAuxSends,   ///< Aux send values
00585             AkUInt32 in_uNumAux             ///< Number of elements in in_pAuxSends
00586             );
00587 
00588         //@}
00589 
00590         ////////////////////////////////////////////////////////////////////////
00591         /// @name Helper functions for passing game data to the Wwise Reflect plug-in. 
00592         /// Use this API for detailed placement of reflection image sources.
00593         /// \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.
00594         /// Functions of Geometry are preferred and easier to use with the Wwise Reflect plug-in. \endaknote
00595         //@{
00596 
00597         /// Add or update an individual image source for processing via the AkReflect plug-in.  Use this API for detailed placement of
00598         /// 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
00599         /// 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.
00600         /// 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. 
00601         /// The image source will apply to all registered spatial audio emitters, if \c AK_INVALID_GAME_OBJECT is passed for \c in_gameObjectID, 
00602         /// or to one particular game object, if \c in_gameObjectID contains the ID of a valid registered spatial audio emitter. 
00603         /// 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.  
00604         /// 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
00605         /// 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.
00606         /// \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.  
00607         /// 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.
00608         /// 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 
00609         /// 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
00610         /// \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
00611         /// \sa 
00612         /// - \ref AK::SpatialAudio::RegisterEmitter
00613         /// - \ref AK::SpatialAudio::RemoveImageSource
00614         /// - \ref AK::SpatialAudio::SetGameObjectInRoom
00615         AK_EXTERNAPIFUNC(AKRESULT, SetImageSource)(
00616             AkImageSourceID in_srcID,                               ///< The ID of the image source being added.
00617             const AkImageSourceSettings& in_info,                   ///< Image source information.
00618             AkUniqueID in_AuxBusID,                                 ///< Aux bus that has the AkReflect plug in for early reflection DSP.
00619             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.
00620             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.
00621         );
00622 
00623         /// Remove an individual reflection image source that was previously added via \c SetImageSource.
00624         /// \sa 
00625         /// - \ref AK::SpatialAudio::SetImageSource
00626         AK_EXTERNAPIFUNC(AKRESULT, RemoveImageSource)(
00627             AkImageSourceID in_srcID,                                   ///< The ID of the image source to remove.
00628             AkUniqueID in_AuxBusID,                                     ///< Aux bus that was passed to SetImageSource.
00629             AkGameObjectID in_gameObjectID = AK_INVALID_GAME_OBJECT     ///< Game object ID that was passed to SetImageSource.
00630         );
00631 
00632         //@}
00633 
00634         ////////////////////////////////////////////////////////////////////////
00635         /// @name Geometry 
00636         /// Geometry API for early reflection processing using Wwise Reflect.
00637         //@{
00638 
00639         /// 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,
00640         /// 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.
00641         /// \sa 
00642         /// - \ref AkGeometryParams
00643         /// - \ref AK::SpatialAudio::RemoveGeometry
00644         AK_EXTERNAPIFUNC(AKRESULT, SetGeometry)(
00645             AkGeometrySetID in_GeomSetID,       ///< Unique geometry set ID, chosen by client.
00646             const AkGeometryParams& in_params   ///< Geometry parameters to set.
00647         );
00648         
00649         /// Remove a set of geometry to the SpatialAudio API.
00650         /// \sa 
00651         /// - \ref AK::SpatialAudio::SetGeometry
00652         AK_EXTERNAPIFUNC(AKRESULT, RemoveGeometry)(
00653             AkGeometrySetID in_SetID        ///< ID of geometry set to be removed.
00654         );
00655 
00656         /// 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.
00657         /// This function must acquire the global sound engine lock and therefore, may block waiting for the lock.
00658         /// \sa
00659         /// - \ref AkReflectionPathInfo
00660         AK_EXTERNAPIFUNC(AKRESULT, QueryReflectionPaths)(
00661             AkGameObjectID in_gameObjectID, ///< The ID of the game object that the client wishes to query.
00662             AkVector& out_listenerPos,      ///< Returns the position of the listener game object that is associated with the game object \c in_gameObjectID.
00663             AkVector& out_emitterPos,       ///< Returns the position of the emitter game object \c in_gameObjectID.
00664             AkReflectionPathInfo* out_aPaths,   ///< Pointer to an array of \c AkReflectionPathInfo's which will be filled after returning.
00665             AkUInt32& io_uArraySize         ///< The number of slots in \c out_aPaths, after returning the number of valid elements written.
00666             );
00667 
00668         //@}
00669 
00670         ////////////////////////////////////////////////////////////////////////
00671         /// @name Rooms and Portals
00672         /// Sound Propagation API using rooms and portals.
00673         //@{
00674 
00675         /// 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.
00676         /// 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 
00677         /// registration/unregistration of internal game objects for rooms that use these IDs and, therefore, must not collide.
00678         /// \sa
00679         /// - \ref AkRoomID
00680         /// - \ref AkRoomParams
00681         /// - \ref AK::SpatialAudio::RemoveRoom
00682         AK_EXTERNAPIFUNC(AKRESULT, SetRoom)(
00683             AkRoomID in_RoomID,             ///< Unique room ID, chosen by the client.
00684             const AkRoomParams& in_Params   ///< Parameter for the room.
00685             );
00686 
00687         /// Remove a room.
00688         /// \sa
00689         /// - \ref AkRoomID
00690         /// - \ref AK::SpatialAudio::SetRoom
00691         AK_EXTERNAPIFUNC(AKRESULT, RemoveRoom)(
00692             AkRoomID in_RoomID  ///< Room ID that was passed to \c SetRoom.
00693             );
00694 
00695         /// 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. 
00696         /// 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, 
00697         /// 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.
00698         /// \sa
00699         /// - \ref AkPortalID
00700         /// - \ref AkPortalParams
00701         /// - \ref AK::SpatialAudio::RemovePortal
00702         AK_EXTERNAPIFUNC(AKRESULT, SetPortal)(
00703             AkPortalID in_PortalID,     ///< Unique portal ID, chosen by the client.
00704             const AkPortalParams& in_Params ///< Parameter for the portal.
00705             );
00706 
00707         /// Remove a portal.
00708         /// \sa
00709         /// - \ref AkPortalID
00710         /// - \ref AK::SpatialAudio::SetPortal
00711         AK_EXTERNAPIFUNC(AKRESULT, RemovePortal)(
00712             AkPortalID in_PortalID      ///< ID of portal to be removed, which was originally passed to SetPortal.
00713             );
00714 
00715         /// 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.
00716         /// 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
00717         /// 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
00718         /// audio.
00719         /// \sa 
00720         /// - \ref AK::SpatialAudio::SetRoom
00721         /// - \ref AK::SpatialAudio::RemoveRoom
00722         AK_EXTERNAPIFUNC(AKRESULT, SetGameObjectInRoom)(
00723             AkGameObjectID in_gameObjectID, ///< Game object ID 
00724             AkRoomID in_CurrentRoomID       ///< RoomID that was passed to \c AK::SpatialAudio::SetRoom
00725             );
00726 
00727         /// Set the obstruction and occlusion values of an emitter game object that has been registered with the SpatialAudio API.  
00728         /// 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.
00729         /// 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
00730         /// and listener are in different room.
00731         /// 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
00732         /// to simulate sound transmission through walls.
00733         /// 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.
00734         /// 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.
00735         /// \aknote The game is responsible to differentiate between obstruction between the emitter and the portal (where \c AK::SoundEngine::SetEmitterObstructionAndOcclusion() should be used), and occlusion from room boundaries, 
00736         /// 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 the opening of a portal, 
00737         /// 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 angle calculation which is probably much less than 180 degrees, 
00738         /// 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::SoundEngine::SetEmitterObstructionAndOcclusion(), 
00739         /// and then test for obstructing objects between the portal and the listener, passing the results with \c AK::SoundEngine::SetPortalObstructionAndOcclusion().
00740         /// \sa 
00741         /// - \ref AK::SpatialAudio::SetPortalObstructionAndOcclusion
00742         AK_EXTERNAPIFUNC(AKRESULT, SetEmitterObstructionAndOcclusion)(
00743             AkGameObjectID in_gameObjectID,         ///< Game object ID of the sound emitter.
00744             AkReal32 in_fObstruction,               ///< Obstruction value.  Valid range 0.f-1.f
00745             AkReal32 in_fOcclusion                  ///< Occlusion value.  Valid range 0.f-1.f
00746             );
00747 
00748         /// Set the obstruction and occlusion value for a portal that has been registered with Spatial Audio.
00749         /// Portal obstruction is used to simulate objects between the portal and the listener that are obstructing the sound coming from the portal.  
00750         /// The obstruction value affects only the portals dry path, and should relate to how much of the opening
00751         /// 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 
00752         /// which propagate from that room through this portal.
00753         /// 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.
00754         /// \sa 
00755         /// - \ref AK::SpatialAudio::SetEmitterObstructionAndOcclusion
00756         AK_EXTERNAPIFUNC(AKRESULT, SetPortalObstructionAndOcclusion)(
00757             AkPortalID in_PortalID,             ///< Portal ID.
00758             AkReal32 in_fObstruction,           ///< Obstruction value.  Valid range 0.f-1.f
00759             AkReal32 in_fOcclusion              ///< Occlusion value.  Valid range 0.f-1.f
00760             );
00761 
00762         /// Query information about the sound propagation state for a particular listener and emitter, which has been calculated using the data provided via the rooms and portals API. This function can be used for debugging purposes.
00763         /// This function must acquire the global sound engine lock and therefore, may block waiting for the lock.
00764         /// \sa
00765         /// - \ref AkPropagationPathInfo
00766         AK_EXTERNAPIFUNC(AKRESULT, QuerySoundPropagationPaths)(
00767             AkGameObjectID in_gameObjectID,     ///< The ID of the game object that the client wishes to query.
00768             AkVector& out_listenerPos,          ///< Returns the position of the listener game object that is associated with the game object \c in_gameObjectID.
00769             AkVector& out_emitterPos,           ///< Returns the position of the emitter game object \c in_gameObjectID.
00770             AkPropagationPathInfo* out_aPaths,  ///< Pointer to an array of \c AkPropagationPathInfo's which will be filled after returning.
00771             AkUInt32& io_uArraySize             ///< The number of slots in \c out_aPaths, after returning the number of valid elements written.
00772             );
00773 
00774         /// 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.
00775         /// This function must acquire the global sound engine lock and therefore, may block waiting for the lock.
00776         /// \sa
00777         /// - \ref AkDiffractionPathInfo
00778         AK_EXTERNAPIFUNC(AKRESULT, QueryDiffractionPaths)(
00779             AkGameObjectID in_gameObjectID,     ///< The ID of the game object that the client wishes to query.
00780             AkVector& out_listenerPos,          ///< Returns the position of the listener game object that is associated with the game object \c in_gameObjectID.
00781             AkVector& out_emitterPos,           ///< Returns the position of the emitter game object \c in_gameObjectID.
00782             AkDiffractionPathInfo* out_aPaths,  ///< Pointer to an array of \c AkPropagationPathInfo's which will be filled after returning.
00783             AkUInt32& io_uArraySize             ///< The number of slots in \c out_aPaths, after returning the number of valid elements written.
00784             );
00785 
00786         //@}
00787     }
00788 };