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