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 { 00127 useImageSources = true; 00128 } 00129 00130 /// Operator = 00131 AkEmitterSettings& operator =(const AkEmitterSettings & src) 00132 { 00133 name = src.name; 00134 reflectAuxBusID = src.reflectAuxBusID; 00135 reflectionMaxPathLength = src.reflectionMaxPathLength; 00136 reflectionsAuxBusGain = src.reflectionsAuxBusGain; 00137 reflectionsOrder = src.reflectionsOrder; 00138 reflectorFilterMask = src.reflectorFilterMask; 00139 roomReverbAuxBusGain = src.roomReverbAuxBusGain; 00140 useImageSources = src.useImageSources; 00141 return *this; 00142 } 00143 00144 /// Name given to this sound emitter. 00145 AK::SpatialAudio::OsString name; 00146 00147 /// 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. 00148 /// \aknote For proper operation with AkReflect and the SpatialAudio API, any aux bus using AkReflect should have 'Enable Positioning' checked and the positioning type should be set to 2D in the Wwise authoring tool. See the Wwise Reflect documentation for more details. \endaknote 00149 AkUniqueID reflectAuxBusID; 00150 00151 /// A heuristic to stop the computation of reflections. Should be no longer (and possibly shorter for less CPU usage) than the maximum attenuation of 00152 /// the sound emitter. 00153 AkReal32 reflectionMaxPathLength; 00154 00155 /// Send gain (0.f-1.f) that is applied when sending to the bus that has the AkReflect plug-in. (reflectAuxBusID) 00156 AkReal32 reflectionsAuxBusGain; 00157 00158 /// Maximum number of reflections that will be processed when computing indirect paths via the geometric reflections API. Reflection processing grows 00159 /// exponentially with the order of reflections, so this number should be kept low. Valid range: 1-4. 00160 AkUInt32 reflectionsOrder; 00161 00162 /// 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 00163 /// 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 00164 /// 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. 00165 AkUInt32 reflectorFilterMask; 00166 00167 /// 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). 00168 /// 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(), 00169 /// and therefore may be used to scale and/or disable room reverb, either temporarily or permanently, for a specific emitter. 00170 /// \sa 00171 /// - \ref AkRoomParams 00172 /// - \ref AK::SpatialAudio::SetEmitterAuxSendValues 00173 AkReal32 roomReverbAuxBusGain; 00174 00175 /// Enable reflections from image sources that have been added via the \c AK::SpatialAudio::SetImageSource() API. (Does not apply to geometric reflections.) 00176 AkUInt8 useImageSources : 1; 00177 }; 00178 00179 /// Structure for describing information about individual triangles 00180 struct AkTriangle 00181 { 00182 /// Constructor 00183 AkTriangle(): textureID(AK_INVALID_UNIQUE_ID) 00184 , reflectorChannelMask((AkUInt32)-1) 00185 , strName(NULL) 00186 {} 00187 00188 /// Vertices 00189 AkVector point0; 00190 AkVector point1; 00191 AkVector point2; 00192 00193 /// Acoustic texture ShareSet ID 00194 AkUInt32 textureID; 00195 00196 /// Bitfield of channels that this triangle 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. 00197 AkUInt32 reflectorChannelMask; 00198 00199 /// Name to describe this triangle. When passing into \c SetGeometry, this string is copied internally and may be freed as soon as the function returns. 00200 const char* strName; 00201 }; 00202 00203 /// 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. 00204 struct AkSoundPathInfo 00205 { 00206 /// Apparent source of the reflected sound that follows this path. 00207 AkVector imageSource; 00208 00209 /// Vertices of the indirect path. 00210 /// reflectionPoint[0] is closest to the emitter, reflectionPoint[numReflections-1] is closest to the listener. 00211 AkVector reflectionPoint[AK_MAX_REFLECT_ORDER]; 00212 00213 /// The triangles that were hit in the path. The vertices in \c reflectionPoint[] correspond to points on these triangles. 00214 /// triangles[0] is closest to the emitter, triangles[numReflections-1] is closest to the listener. 00215 AkTriangle triangles[AK_MAX_REFLECT_ORDER]; 00216 00217 /// Number of reflections and valid elements in the \c reflectionPoint[] and \c triangles[] arrays. 00218 AkUInt32 numReflections; 00219 00220 /// 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. 00221 AkVector occlusionPoint; 00222 00223 /// 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. 00224 bool isOccluded; 00225 }; 00226 00227 /// Structure for retrieving information about the sound propagation paths that have been calculated via the rooms and portals API. Useful for debug draw applications. 00228 struct AkPropagationPathInfo 00229 { 00230 /// Defines the maximum number of nodes that a user can retrieve information about. Longer paths will be truncated. 00231 static const AkUInt32 kMaxNodes = AK_MAX_SOUND_PROPAGATION_DEPTH; 00232 00233 /// Nodes in the path; they repreent vertices within the bounds of a portal's opening. 00234 AkVector nodePoint[kMaxNodes]; 00235 00236 /// 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. 00237 AkPortalID portals[kMaxNodes]; 00238 00239 /// 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]. 00240 AkRoomID rooms[kMaxNodes+1]; 00241 00242 /// 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. 00243 AkUInt32 numNodes; 00244 00245 /// 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. 00246 AkReal32 length; 00247 00248 /// The cumulative gain (linear) of all portals traversed. 00249 AkReal32 gain; 00250 00251 /// The dry diffraction angle is measured in radians, and calculated from the maximum deviation from a straight line, of all angles at each nodePoint. Can be thought of as how 00252 // far into the 'shadow region' the sound has to 'bend' to reach the listener. Valid range: 0 - PI radians. 00253 /// 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. 00254 /// \sa 00255 /// - \ref AkDiffractionFlags 00256 /// - \ref AkSpatialAudioInitSettings 00257 AkReal32 dryDiffractionAngle; 00258 00259 /// The wet diffraction for the portal closest to the listener. 00260 /// The wet diffraction angle is measured in radians and calculated from how far into the 'shadow region' the listener is from the closest portal. Unlike dry diffraction, the 00261 /// wet diffraction does not depend on the incident angle, but only the normal of the portal. Valid range: 0 - PI radians. 00262 /// 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 00263 /// on the other side of the portal closest to the listener. 00264 /// \sa 00265 /// - \ref AkDiffractionFlags 00266 /// - \ref AkSpatialAudioInitSettings 00267 AkReal32 wetDiffractionAngle; 00268 }; 00269 00270 /// Parameters passed to \c SetPortal 00271 struct AkPortalParams 00272 { 00273 /// Constructor 00274 AkPortalParams() : 00275 bEnabled(false) 00276 {} 00277 00278 /// Portal's position and orientation in the 3D world. 00279 /// Position vector is the center of the opening. 00280 /// 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. 00281 /// 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. 00282 AkTransform Transform; 00283 00284 /// 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, 00285 /// 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 00286 /// that results in appropriately smooth transitions between rooms. 00287 AkVector Extent; 00288 00289 /// Whether or not the portal is active/enabled. For example, this parameter may be used to simulate open/closed doors. 00290 /// Portal diffraction is simulated when at least one portal exists and is active between an emitter and the listener. Otherwise, transmission is simulated. 00291 /// Diffraction uses obstruction or the diffraction built-in game parameter, while transmission uses occlusion. 00292 bool bEnabled; 00293 00294 /// Name used to identify portal (optional). 00295 AK::SpatialAudio::OsString strName; 00296 00297 /// 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, 00298 /// 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. 00299 /// - \ref AK::SpatialAudio::SetRoom 00300 /// - \ref AK::SpatialAudio::RemoveRoom 00301 /// - \ref AkRoomParams 00302 AkRoomID FrontRoom; 00303 00304 /// 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, 00305 /// 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. 00306 /// - \ref AK::SpatialAudio::SetRoom 00307 /// - \ref AK::SpatialAudio::RemoveRoom 00308 /// - \ref AkRoomParams 00309 AkRoomID BackRoom; 00310 }; 00311 00312 /// Parameters passed to \c SetRoom 00313 struct AkRoomParams 00314 { 00315 /// Constructor 00316 AkRoomParams() : ReverbAuxBus(AK_INVALID_AUX_ID) 00317 , ReverbLevel(1.f) 00318 , WallOcclusion(1.f) 00319 , RoomGameObj_AuxSendLevelToSelf(0.f) 00320 , RoomGameObj_KeepRegistered(false) 00321 00322 { 00323 Up.X = 0.f; 00324 Up.Y = 1.f; 00325 Up.Z = 0.f; 00326 Front.X = 0.f; 00327 Front.Y = 0.f; 00328 Front.Z = 1.f; 00329 } 00330 00331 /// Room Orientation. Up and Front must be orthonormal. 00332 /// Room orientation has an effect when the associated aux bus (see ReverbAuxBus) is set with 3D positioning in Wwise, as 3D positioning implements relative rotation of the emitter (room) and listener. 00333 AkVector Up; 00334 AkVector Front; 00335 00336 /// The reverb aux bus that is associated with this room. 00337 /// 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. 00338 /// 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. 00339 /// 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. 00340 /// 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. 00341 /// If more advanced control of reverb is desired, SetEmitterAuxSendValues can be used to add additional sends on to a game object. 00342 /// - \ref AK::SpatialAudio::SetGameObjectInRoom 00343 /// - \ref AK::SpatialAudio::SetEmitterAuxSendValues 00344 AkAuxBusID ReverbAuxBus; 00345 00346 /// The reverb control value for the send to ReverbAuxBus. Valid range: (0.f-1.f) 00347 /// Can be used to implement multiple rooms that share the same aux bus, but have different reverb levels. 00348 AkReal32 ReverbLevel; 00349 00350 /// Occlusion level to set when modeling transmission through walls. Transmission is modeled only when no paths to the listener are found, meaning that there are no active portals between the listener's 00351 /// room and the emitter's room. Valid range: (0.f-1.f) 00352 AkReal32 WallOcclusion; 00353 00354 /// Unused 00355 AkInt32 Priority; 00356 00357 /// Name used to identify room (optional) 00358 AK::SpatialAudio::OsString strName; 00359 00360 /// 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, 00361 /// 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 00362 /// for spatial audio emitters sending to the room game object. 00363 /// \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 00364 /// 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 00365 /// surround ambiance beds or room tones. Point source sounds should use separate game objects that are registered as spatial audio emitters. 00366 /// \sa 00367 /// - \ref AkRoomParams::RoomGameObj_KeepRegistered 00368 /// - \ref AkRoomID 00369 AkReal32 RoomGameObj_AuxSendLevelToSelf; 00370 00371 /// 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 00372 /// 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. 00373 /// 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. 00374 /// \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 00375 /// 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 00376 /// surround ambiance beds or room tones. Point source sounds should use separate game objects that are registered as spatial audio emitters. 00377 /// \sa 00378 /// - \ref AkRoomParams::RoomGameObj_AuxSendLevelToSelf 00379 /// - \ref AkRoomID 00380 bool RoomGameObj_KeepRegistered; 00381 00382 00383 }; 00384 00385 /// Audiokinetic namespace 00386 namespace AK 00387 { 00388 /// Audiokinetic spatial audio namespace 00389 namespace SpatialAudio 00390 { 00391 //////////////////////////////////////////////////////////////////////// 00392 /// @name Basic functions. 00393 /// 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 00394 /// 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 00395 /// SetPosition and SetEmitterAuxSendValues instead of their AK::SoundEngine counterparts. 00396 ///\akwarning At the moment, there can be only one Spatial Audio listener registered at any given time. 00397 //@{ 00398 00399 /// Access the internal pool ID passed to Init. 00400 AK_EXTERNAPIFUNC(AkMemPoolId, GetPoolID)(); 00401 00402 /// Initialize the SpatialAudio API. 00403 AK_EXTERNAPIFUNC(AKRESULT, Init)(const AkSpatialAudioInitSettings& in_initSettings); 00404 00405 /// 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 00406 /// registered in the sound engine via \c AK::SoundEngine::RegisterGameObj(). 00407 /// \sa 00408 /// - \ref AkEmitterSettings 00409 AK_EXTERNAPIFUNC(AKRESULT, RegisterEmitter)( 00410 AkGameObjectID in_gameObjectID, ///< Game object ID 00411 const AkEmitterSettings& in_settings ///< Settings for the spatial audio emitter. 00412 ); 00413 00414 /// Unregister a game object as a sound emitter in the SpatialAudio API; clean up Spatial Audio listener data associated with in_gameObjectID. 00415 /// This function is optional - emitters are automatically unregistered when their game object is deleted in the sound engine. 00416 /// \sa 00417 /// - \ref AK::SpatialAudio::RegisterEmitter 00418 AK_EXTERNAPIFUNC(AKRESULT, UnregisterEmitter)( 00419 AkGameObjectID in_gameObjectID ///< Game object ID 00420 ); 00421 00422 /// 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. 00423 /// 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. 00424 /// 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 00425 /// default listeners, then it is necessary to call RegisterListener() to specify which listener to use with Spatial Audio. 00426 AK_EXTERNAPIFUNC(AKRESULT, RegisterListener)( 00427 AkGameObjectID in_gameObjectID ///< Game object ID 00428 ); 00429 00430 /// Unregister a game object as a listener in the SpatialAudio API; clean up Spatial Audio listener data associated with in_gameObjectID. 00431 /// If in_gameObjectID is the current registered listener, calling this function will clear the Spatial Audio listener and 00432 /// Spatial Audio features will be disabled until another listener is registered. 00433 /// This function is optional - listener are automatically unregistered when their game object is deleted in the sound engine. 00434 /// \sa 00435 /// - \ref AK::SpatialAudio::RegisterListener 00436 AK_EXTERNAPIFUNC(AKRESULT, UnregisterListener)( 00437 AkGameObjectID in_gameObjectID ///< Game object ID 00438 ); 00439 00440 /// Set the position of an emitter game object that has been registered with the SpatialAudio API. 00441 /// 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 00442 /// for all spatial audio services, such as Rooms and GeometrySets (see SpatialAudio::SetRoom and SpatialAudio::SetGeometry). 00443 /// 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 00444 /// that are passed to the sound engine and used to render audio. 00445 /// 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(). 00446 AK_EXTERNAPIFUNC(AKRESULT, SetPosition)( 00447 AkGameObjectID in_gameObjectID, ///< Game object ID of the sound emitter. 00448 const AkTransform& in_sourcePosition ///< Physical position of the emitter in the simulation. 00449 ); 00450 00451 /// Set the aux send values for an emitter game object that has been registered with the SpatialAudio API. 00452 /// 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 00453 // for early reflection processing. 00454 /// 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(). 00455 /// \sa 00456 /// - \ref AK::SoundEngine::SetGameObjectAuxSendValues 00457 AK_EXTERNAPIFUNC(AKRESULT, SetEmitterAuxSendValues)( 00458 AkGameObjectID in_gameObjectID, ///< Game object ID of the sound emitter. 00459 AkAuxSendValue* in_pAuxSends, ///< Aux send values 00460 AkUInt32 in_uNumAux ///< Number of elements in in_pAuxSends 00461 ); 00462 00463 //@} 00464 00465 //////////////////////////////////////////////////////////////////////// 00466 /// @name Helper functions for passing game data to the Wwise Reflect plug-in. 00467 /// Use this API for detailed placement of reflection image sources. 00468 /// \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. 00469 /// Functions of Geometry are preferred and easier to use with the Wwise Reflect plug-in. \endaknote 00470 //@{ 00471 00472 /// Add or update an individual image source for processing via the AkReflect plug-in. Use this API for detailed placement of 00473 /// 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 00474 /// 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. 00475 /// 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. 00476 /// The image source will apply to all registered spatial audio emitters, if \c AK_INVALID_GAME_OBJECT is passed for \c in_gameObjectID, 00477 /// or to one particular game object, if \c in_gameObjectID contains the ID of a valid registered spatial audio emitter. 00478 /// 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. 00479 /// 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 00480 /// 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. 00481 /// \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. 00482 /// 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. 00483 /// 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 00484 /// 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 00485 /// \aknote For proper operation with AkReflect and the SpatialAudio API, any aux bus using AkReflect should have 'Enable Positioning' checked and the positioning type should be set to 2D in the Wwise authoring tool. See the Wwise Reflect documentation for more details. \endaknote 00486 /// \sa 00487 /// - \ref AK::SpatialAudio::RegisterEmitter 00488 /// - \ref AK::SpatialAudio::RemoveImageSource 00489 /// - \ref AK::SpatialAudio::SetGameObjectInRoom 00490 AK_EXTERNAPIFUNC(AKRESULT, SetImageSource)( 00491 AkImageSourceID in_srcID, ///< The ID of the image source being added. 00492 const AkImageSourceSettings& in_info, ///< Image source information. 00493 AkUniqueID in_AuxBusID, ///< Aux bus that has the AkReflect plug in for early reflection DSP. 00494 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. 00495 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. 00496 ); 00497 00498 /// Remove an individual reflection image source that was previously added via \c SetImageSource. 00499 /// \sa 00500 /// - \ref AK::SpatialAudio::SetImageSource 00501 AK_EXTERNAPIFUNC(AKRESULT, RemoveImageSource)( 00502 AkImageSourceID in_srcID, ///< The ID of the image source to remove. 00503 AkUniqueID in_AuxBusID, ///< Aux bus that was passed to SetImageSource. 00504 AkGameObjectID in_gameObjectID = AK_INVALID_GAME_OBJECT ///< Game object ID that was passed to SetImageSource. 00505 ); 00506 00507 //@} 00508 00509 //////////////////////////////////////////////////////////////////////// 00510 /// @name Geometry 00511 /// Geometry API for early reflection processing using Wwise Reflect. 00512 //@{ 00513 00514 /// Add or update a set of geometry from the \c SpatialAudio module for geometric reflection processing. A geometry set is a logical set of triangles, formed by any criteria that suits the client, 00515 /// which will be referenced by the same ID. The ID (\c in_GeomSetID) must be unique and is also chosen by the client in a manner similar to \c AkGameObjectID's. 00516 /// The data pointed to by \c in_pTriangles will be copied internally and may be released after this function returns. 00517 /// \sa 00518 /// - \ref AkTriangle 00519 /// - \ref AK::SpatialAudio::RemoveGeometry 00520 AK_EXTERNAPIFUNC(AKRESULT, SetGeometry)( 00521 AkGeometrySetID in_GeomSetID, ///< Unique geometry set ID, chosen by client. 00522 AkTriangle* in_pTriangles, ///< Pointer to an array of AkTriangle structures. 00523 AkUInt32 in_uNumTriangles ///< Number of triangles in in_pTriangles. 00524 ); 00525 00526 /// Remove a set of geometry to the SpatialAudio API. 00527 /// \sa 00528 /// - \ref AK::SpatialAudio::SetGeometry 00529 AK_EXTERNAPIFUNC(AKRESULT, RemoveGeometry)( 00530 AkGeometrySetID in_SetID ///< ID of geometry set to be removed. 00531 ); 00532 00533 /// Query information about the indirect paths that have been calculated via geometric reflection processing in the SpatialAudio API. This function can be used for debugging purposes. 00534 /// This function must acquire the global sound engine lock and therefore, may block waiting for the lock. 00535 /// \sa 00536 /// - \ref AkSoundPathInfo 00537 AK_EXTERNAPIFUNC(AKRESULT, QueryIndirectPaths)( 00538 AkGameObjectID in_gameObjectID, ///< The ID of the game object that the client wishes to query. 00539 AkVector& out_listenerPos, ///< Returns the position of the listener game object that is associated with the game object \c in_gameObjectID. 00540 AkVector& out_emitterPos, ///< Returns the position of the emitter game object \c in_gameObjectID. 00541 AkSoundPathInfo* out_aPaths, ///< Pointer to an array of \c AkSoundPathInfo's which will be filled after returning. 00542 AkUInt32& io_uArraySize ///< The number of slots in \c out_aPaths, after returning the number of valid elements written. 00543 ); 00544 00545 //@} 00546 00547 //////////////////////////////////////////////////////////////////////// 00548 /// @name Rooms and Portals 00549 /// Sound Propagation API using rooms and portals. 00550 //@{ 00551 00552 /// 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. 00553 /// 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 00554 /// registration/unregistration of internal game objects for rooms that use these IDs and, therefore, must not collide. 00555 /// \sa 00556 /// - \ref AkRoomID 00557 /// - \ref AkRoomParams 00558 /// - \ref AK::SpatialAudio::RemoveRoom 00559 AK_EXTERNAPIFUNC(AKRESULT, SetRoom)( 00560 AkRoomID in_RoomID, ///< Unique room ID, chosen by the client. 00561 const AkRoomParams& in_Params ///< Parameter for the room. 00562 ); 00563 00564 /// Remove a room. 00565 /// \sa 00566 /// - \ref AkRoomID 00567 /// - \ref AK::SpatialAudio::SetRoom 00568 AK_EXTERNAPIFUNC(AKRESULT, RemoveRoom)( 00569 AkRoomID in_RoomID ///< Room ID that was passed to \c SetRoom. 00570 ); 00571 00572 /// 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. 00573 /// 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, 00574 /// 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. 00575 /// \sa 00576 /// - \ref AkPortalID 00577 /// - \ref AkPortalParams 00578 /// - \ref AK::SpatialAudio::RemovePortal 00579 AK_EXTERNAPIFUNC(AKRESULT, SetPortal)( 00580 AkPortalID in_PortalID, ///< Unique portal ID, chosen by the client. 00581 const AkPortalParams& in_Params ///< Parameter for the portal. 00582 ); 00583 00584 /// Remove a portal. 00585 /// \sa 00586 /// - \ref AkPortalID 00587 /// - \ref AK::SpatialAudio::SetPortal 00588 AK_EXTERNAPIFUNC(AKRESULT, RemovePortal)( 00589 AkPortalID in_PortalID ///< ID of portal to be removed, which was originally passed to SetPortal. 00590 ); 00591 00592 /// 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. 00593 /// 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 00594 /// 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 00595 /// audio. 00596 /// \sa 00597 /// - \ref AK::SpatialAudio::SetRoom 00598 /// - \ref AK::SpatialAudio::RemoveRoom 00599 AK_EXTERNAPIFUNC(AKRESULT, SetGameObjectInRoom)( 00600 AkGameObjectID in_gameObjectID, ///< Game object ID 00601 AkRoomID in_CurrentRoomID ///< RoomID that was passed to \c AK::SpatialAudio::SetRoom 00602 ); 00603 00604 /// Set the obstruction value of an emitter game object that has been registered with the SpatialAudio API. 00605 /// This function should be called instead of \c AK::SoundEngine::SetObjectObstructionAndOcclusion(), and can be used for setting the obstruction value on a Spatial Audio emitter. 00606 /// SetEmitterObstruction() 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 00607 /// and listener are in different room. 00608 /// If the listener and the emitter are in different rooms, the maximum of the value passed into SetEmitterObstruction() and the the obstruction value calculated from the diffraction angle is passed to the sound engine. 00609 /// 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. 00610 /// \aknote The game is responsible to differentiate between obstruction between the emitter and the portal (where \c AK::SoundEngine::SetEmitterObstruction() should be used), and occlusion from room boundaries, 00611 /// 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, 00612 /// 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, 00613 /// 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::SetEmitterObstruction(), 00614 /// and then test for obstructing objects between the portal and the listener, passing the results with \c AK::SoundEngine::SetPortalObstruction(). 00615 /// \sa 00616 /// - \ref AK::SpatialAudio::SetPortalObstruction 00617 AK_EXTERNAPIFUNC(AKRESULT, SetEmitterObstruction)( 00618 AkGameObjectID in_gameObjectID, ///< Game object ID of the sound emitter. 00619 AkReal32 in_fObstruction ///< Obstruction value. Valid range 0.f-1.f 00620 ); 00621 00622 /// Set the obstruction value for a portal that has been registered with Spatial Audio. 00623 /// Portal obstruction is used to simulate objects between the portal and the listener that are obstructing the sound coming from the portal. The obstruction value should relate to how much of the opening 00624 /// is obstructed, and must be calculated by the client. Only portals connecting directly to the listeners current room need to have their obstruction value updated. If the listener moves to a new room, 00625 /// the new set of portals must be updated. 00626 AK_EXTERNAPIFUNC(AKRESULT, SetPortalObstruction)( 00627 AkPortalID in_PortalID, ///< Portal ID. 00628 AkReal32 in_fObstruction ///< Obstruction value. Valid range 0.f-1.f 00629 ); 00630 00631 /// 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. 00632 /// This function must acquire the global sound engine lock and therefore, may block waiting for the lock. 00633 /// \sa 00634 /// - \ref AkPropagationPathInfo 00635 AK_EXTERNAPIFUNC(AKRESULT, QuerySoundPropagationPaths)( 00636 AkGameObjectID in_gameObjectID, ///< The ID of the game object that the client wishes to query. 00637 AkVector& out_listenerPos, ///< Returns the position of the listener game object that is associated with the game object \c in_gameObjectID. 00638 AkVector& out_emitterPos, ///< Returns the position of the emitter game object \c in_gameObjectID. 00639 AkPropagationPathInfo* out_aPaths, ///< Pointer to an array of \c AkPropagationPathInfo's which will be filled after returning. 00640 AkUInt32& io_uArraySize ///< The number of slots in \c out_aPaths, after returning the number of valid elements written. 00641 ); 00642 00643 //@} 00644 } 00645 };