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 00035 /// Initialization settings of the spatial audio module. 00036 struct AkSpatialAudioInitSettings 00037 { 00038 AkSpatialAudioInitSettings() : uPoolID(AK_INVALID_POOL_ID) 00039 , uPoolSize(4 * 1024 * 1024) 00040 {} 00041 00042 AkMemPoolId uPoolID; ///< User-provided pool ID (see AK::MemoryMgr::CreatePool). 00043 AkUInt32 uPoolSize; ///< Desired memory pool size. 00044 }; 00045 00046 struct AkReflectImageSource; 00047 00048 /// Settings for a sound emitter. 00049 struct AkEmitterSettings 00050 { 00051 /// Constructor 00052 AkEmitterSettings() : reflectAuxBusID(AK_INVALID_UNIQUE_ID) 00053 , reflectionMaxPathLength(kDefaultMaxPathLength) 00054 , reflectionsAuxBusGain(1.0f) 00055 , reflectionsOrder(1) 00056 , reflectorFilterMask(0xFFFFFFFF) 00057 { 00058 useImageSources = true; 00059 } 00060 00061 /// Operator = 00062 AkEmitterSettings& operator =(const AkEmitterSettings & src) 00063 { 00064 name = src.name; 00065 reflectAuxBusID = src.reflectAuxBusID; 00066 reflectionMaxPathLength = src.reflectionMaxPathLength; 00067 reflectionsAuxBusGain = src.reflectionsAuxBusGain; 00068 reflectionsOrder = src.reflectionsOrder; 00069 reflectorFilterMask = src.reflectorFilterMask; 00070 useImageSources = src.useImageSources; 00071 return *this; 00072 } 00073 00074 /// Name given to this sound emitter. 00075 AK::SpatialAudio::OsString name; 00076 00077 /// 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. 00078 /// \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 00079 AkUniqueID reflectAuxBusID; 00080 00081 /// A heuristic to stop the computation of reflections. Should be no longer (and possibly shorter for less CPU usage) than the maximum attenuation of 00082 /// the sound emitter. 00083 AkReal32 reflectionMaxPathLength; 00084 00085 /// Send gain (0.f-1.f) that is applied when sending to the bus that has the AkReflect plug-in. (reflectAuxBusID) 00086 AkReal32 reflectionsAuxBusGain; 00087 00088 /// Maximum number of reflections that will be processed when computing indirect paths via the geometric reflections API. Reflection processing grows 00089 /// exponentially with the order of reflections, so this number should be kept low. Valid range: 1-4. 00090 AkUInt32 reflectionsOrder; 00091 00092 /// 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 00093 /// 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 00094 /// 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. 00095 AkUInt32 reflectorFilterMask; 00096 00097 /// Enable reflections from image sources that have been added via the \c AK::SpatialAudio::AddImageSource() API. (Does not apply to geometric reflections.) 00098 AkUInt8 useImageSources : 1; 00099 }; 00100 00101 /// Structure for describing information about individual triangles 00102 struct AkTriangle 00103 { 00104 /// Constructor 00105 AkTriangle(): textureID(AK_INVALID_UNIQUE_ID) 00106 , reflectorChannelMask((AkUInt32)-1) 00107 , strName(NULL) 00108 {} 00109 00110 /// Vertices 00111 AkVector point0; 00112 AkVector point1; 00113 AkVector point2; 00114 00115 /// Acoustic texture ShareSet ID 00116 AkUInt32 textureID; 00117 00118 /// 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. 00119 AkUInt32 reflectorChannelMask; 00120 00121 /// Name to describe this triangle. When passing into \c AddGeometrySet, this string is copied internally and may be freed as soon as the function returns. 00122 const char* strName; 00123 }; 00124 00125 /// Structure for retrieving information about the indirect paths of a sound that have been calculated via the geometric reflections API. 00126 struct AkSoundPathInfo 00127 { 00128 /// Apparent source of the reflected sound that follows this path. 00129 AkVector imageSource; 00130 00131 /// Vertices of the indirect path. 00132 AkVector reflectionPoint[AK_MAX_REFLECT_ORDER]; 00133 00134 /// The triangles that were hit in the path. The vertices in \c reflectionPoint[] correspond to points on these triangles. 00135 AkTriangle triangles[AK_MAX_REFLECT_ORDER]; 00136 00137 /// Number of reflections and valid elements in the \c reflectionPoint[] and \c triangles[] arrays. 00138 AkUInt32 numReflections; 00139 00140 /// 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. 00141 AkVector occlusionPoint; 00142 00143 /// 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. 00144 bool isOccluded; 00145 }; 00146 00147 /// Parameters passed to \c AddPortal 00148 struct AkPortalParams 00149 { 00150 /// Constructor 00151 AkPortalParams() : 00152 fGain(1.f), 00153 bEnabled(false) 00154 {} 00155 00156 /// Portal opening position 00157 AkVector Center; 00158 00159 /// Portal orientation front vector 00160 AkVector Front; 00161 00162 /// Portal orientation up vector 00163 AkVector Up; 00164 00165 /// Gain applied to indirect send value when the portal is active. 00166 AkReal32 fGain; 00167 00168 /// Whether or not the portal is active/enabled. For example, this parameter may be used to simulate open/closed doors. 00169 bool bEnabled; 00170 00171 /// Name used to identify portal (optional). 00172 AK::SpatialAudio::OsString strName; 00173 }; 00174 00175 /// Parameters passed to \c AddRoom 00176 struct AkRoomParams 00177 { 00178 AkRoomParams() : pConnectedPortals(NULL), uNumPortals(0) 00179 {} 00180 00181 /// Room Orientation 00182 AkVector Up; 00183 AkVector Front; 00184 00185 /// Pointer to an array of ID's of connected portals. If the portal has not yet been added with \c AK::SpatialAudio::AddPortal, then a default, disabled portal will be created, 00186 /// so that the correct internal associations can be made. The user must then call \c AK::SpatialAudio::AddPortal to update the portal with the correct parameters. 00187 AkPortalID* pConnectedPortals; 00188 00189 /// Number of connected portals in the pConnectedPortals array 00190 AkUInt32 uNumPortals; 00191 00192 /// Name used to identify room (optional) 00193 AK::SpatialAudio::OsString strName; 00194 }; 00195 00196 /// Audiokinetic namespace 00197 namespace AK 00198 { 00199 /// Audiokinetic spatial audio namespace 00200 namespace SpatialAudio 00201 { 00202 /// Access the internal pool ID passed to Init. 00203 AK_EXTERNAPIFUNC(AkMemPoolId, GetPoolID)(); 00204 00205 /// Initialize the SpatialAudio API. 00206 AK_EXTERNAPIFUNC(AKRESULT, Init)(const AkSpatialAudioInitSettings& in_initSettings); 00207 00208 /// Terminate the SpatialAudio API. 00209 AK_EXTERNAPIFUNC(void, Term)(); 00210 00211 /// 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 00212 /// registered in the sound engine via \c AK::SoundEngine::RegisterGameObj(). 00213 /// \sa 00214 /// - \ref AkEmitterSettings 00215 AK_EXTERNAPIFUNC(AKRESULT, RegisterEmitter)( 00216 AkGameObjectID in_gameObjectID, ///< Game object ID 00217 const AkEmitterSettings& in_roomSettings ///< Settings for the spatial audio emitter. 00218 ); 00219 00220 /// Unregister a game object as a sound emitter in the SpatialAudio API. 00221 /// \sa 00222 /// - \ref AK::SpatialAudio::RegisterEmitter 00223 AK_EXTERNAPIFUNC(AKRESULT, UnregisterEmitter)( 00224 AkGameObjectID in_gameObjectID ///< Game object ID 00225 ); 00226 00227 /// Add or update an individual image source for processing via the AkReflect plug-in. Use this API for detailed placement of 00228 /// 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 00229 /// 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. 00230 /// The SpatialAudio API manages image sources added via AddImageSource() and sends them to the AkReflect plug-in that is on the aux bus with ID \c in_AuxBusID. 00231 /// The image source will apply to all registered spatial audio emitters, if \c AK_INVALID_GAME_OBJECT is passed for \c in_gameObjectID, 00232 /// or to one particular game object, if \c in_gameObjectID contains the ID of a valid registered spatial audio emitter. 00233 /// AddImageSource 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. 00234 /// 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 00235 /// 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. 00236 /// \aknote The \c AkReflectImageSource 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. 00237 /// Each instance of AkReflect has its own set of data, so you may reuse ID, if desired, a long as \c in_gameObjectID and \c in_AuxBusID are different. 00238 /// 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 00239 /// 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 00240 /// \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 00241 /// \sa 00242 /// - \ref AK::SpatialAudio::RegisterEmitter 00243 /// - \ref AK::SpatialAudio::RemoveImageSource 00244 /// - \ref AK::SpatialAudio::SetGameObjectInRoom 00245 AK_EXTERNAPIFUNC(AKRESULT, AddImageSource)( 00246 const AkReflectImageSource& in_info, ///< Image source information. 00247 AkUniqueID in_AuxBusID, ///< Aux bus that has the AkReflect plug in for early reflection DSP. 00248 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 a room, or not using rooms. 00249 AkGameObjectID in_gameObjectID = AK_INVALID_GAME_OBJECT,///< GameObjectID, or AK_INVALID_GAME_OBJECT to apply to all game objects. 00250 const String& in_name = "" ///< Name used to identify the image source. 00251 ); 00252 00253 /// Remove an individual reflection image source that was previously added via \c AddImageSource. 00254 /// \sa 00255 /// - \ref AK::SpatialAudio::AddImageSource 00256 AK_EXTERNAPIFUNC(AKRESULT, RemoveImageSource)( 00257 AkImageSourceID in_srcID, ///< The ID of the image source passed to AddImageSource, within the \c AkReflectImageSource struct. 00258 AkUniqueID in_AuxBusID, ///< Aux bus that was passed to AddImageSource. 00259 AkGameObjectID in_gameObjectID = AK_INVALID_GAME_OBJECT ///< Game object ID that was passed to AddImageSource. 00260 ); 00261 00262 /// Set the aux send values for an emitter game object that has been registered with the SpatialAudio API. 00263 /// This function should be called instead of \c AK::SoundEngine::SetGameObjectAuxSendValues() because the spatial audio API adds additional sends to busses for reflection processing. 00264 /// 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(). 00265 /// \sa 00266 /// - \ref AK::SoundEngine::SetGameObjectAuxSendValues 00267 AK_EXTERNAPIFUNC(AKRESULT, SetEmitterAuxSendValues)( 00268 AkGameObjectID in_gameObjectID, ///< Game object ID 00269 AkAuxSendValue* in_pAuxSends, ///< Aux send values 00270 AkUInt32 in_uNumAux ///< Number of elements in in_pAuxSends 00271 ); 00272 00273 /// 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 AddRoom. 00274 /// \sa 00275 /// - \ref AK::SpatialAudio::AddRoom 00276 /// - \ref AK::SpatialAudio::RemoveRoom 00277 AK_EXTERNAPIFUNC(AKRESULT, SetGameObjectInRoom)( 00278 AkGameObjectID in_gameObjectID, ///< Game object ID 00279 AkRoomID in_CurrentRoomID ///< RoomID that was passed to \c AK::SpatialAudio::AddRoom 00280 ); 00281 00282 /// Set the position of an emitter game object that has been registered with the SpatialAudio API. 00283 /// 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 00284 /// for all spatial audio services, such as Rooms and GeometrySets (see SpatialAudio::AddRoom and SpatialAudio::AddGeometrySet). If the user wishes to have apparent or "virtual" positions sent to the sound engine 00285 /// (for example if the object is occluded and sounds as if it is coming from a different place), then \c in_virtualPositions can be used: 00286 /// This array of virtual positions is passed internally to Wwise for computing 3D positioning between the emitter and its listener(s). 00287 /// If the array has more than one position, they are interpreted as multiple positions in \c MultiPositionType_MultiDirections mode. See AK::SoundEngine::SetMultiplePositions for more details on multi-position modes. 00288 /// If you pass 0 virtual positions (default), then \c in_sourcePosition is passed to the Wwise sound engine and further used for spatialization. 00289 /// 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(). 00290 AK_EXTERNAPIFUNC(AKRESULT, SetEmitterPosition)( 00291 AkGameObjectID in_gameObjectID, ///< Game object ID of the sound emitter. 00292 const AkTransform& in_sourcePosition, ///< Physical position of the emitter in the simulation. 00293 const AkTransform* in_virtualPositions = NULL, ///< Virtual/apparent positions of the sound, in case of occlusion. Ignored if \c in_uNumVirtualPositions is 0. 00294 AkUInt16 in_uNumVirtualPositions = 0 ///< Number of \c AkTransform structures in \c in_virtualPositions. If 0, \c in_sourcePosition is used for spatialization. 00295 ); 00296 00297 /// 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, 00298 /// 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. 00299 /// The data pointed to by \c in_pTriangles will be copied internally and may be released after this function returns. 00300 /// \sa 00301 /// - \ref AkTriangle 00302 /// - \ref AK::SpatialAudio::RemoveGeometrySet 00303 AK_EXTERNAPIFUNC(AKRESULT, AddGeometrySet)( 00304 AkGeometrySetID in_GeomSetID, ///< Unique geometry set ID, choosen by client. 00305 AkTriangle* in_pTriangles, ///< Pointer to an array of AkTriangle structures. 00306 AkUInt32 in_uNumTriangles ///< Number of triangles in in_pTriangles. 00307 ); 00308 00309 /// Remove a set of geometry to the SpatialAudio API. 00310 /// \sa 00311 /// - \ref AK::SpatialAudio::AddGeometrySet 00312 AK_EXTERNAPIFUNC(AKRESULT, RemoveGeometrySet)( 00313 AkGeometrySetID in_SetID ///< ID of geometry set to be removed. 00314 ); 00315 00316 /// 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. 00317 /// 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 00318 /// registration/unregistration of internal game objects for rooms that use these IDs and, therefore, must not collide. 00319 /// \sa 00320 /// - \ref AkRoomID 00321 /// - \ref AkRoomParams 00322 /// - \ref AK::SpatialAudio::RemoveRoom 00323 AK_EXTERNAPIFUNC(AKRESULT, AddRoom)( 00324 AkRoomID in_RoomID, ///< Unique room ID, chosen by the client. 00325 const AkRoomParams& in_Params ///< Parameter for the room. 00326 ); 00327 00328 /// Remove a room. 00329 /// \sa 00330 /// - \ref AkRoomID 00331 /// - \ref AK::SpatialAudio::AddRoom 00332 AK_EXTERNAPIFUNC(AKRESULT, RemoveRoom)( 00333 AkRoomID in_RoomID ///< Room ID that was passed to \c AddRoom. 00334 ); 00335 00336 /// 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. 00337 /// 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, 00338 /// 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. 00339 /// \sa 00340 /// - \ref AkPortalID 00341 /// - \ref AkPortalParams 00342 /// - \ref AK::SpatialAudio::RemovePortal 00343 AK_EXTERNAPIFUNC(AKRESULT, AddPortal)( 00344 AkPortalID in_PortalID, ///< Unique portal ID, chosen by the client. 00345 const AkPortalParams& in_Params ///< Parameter for the portal. 00346 ); 00347 00348 /// Remove a portal. 00349 /// \sa 00350 /// - \ref AkPortalID 00351 /// - \ref AK::SpatialAudio::AddPortal 00352 AK_EXTERNAPIFUNC(AKRESULT, RemovePortal)( 00353 AkPortalID in_PortalID ///< ID of portal to be removed, which was originally passed to AddPortal. 00354 ); 00355 00356 /// 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. 00357 /// This function must acquire the global sound engine lock and, therefore, may block waiting for the lock. 00358 /// \sa 00359 /// - \ref AkSoundPathInfo 00360 AK_EXTERNAPIFUNC(AKRESULT, QueryIndirectPaths)( 00361 AkGameObjectID in_gameObjectID, ///< The ID of the game object that the client wishes to query. 00362 AkVector& out_listenerPos, ///< The position of the listener game object that is associated with the game object \c in_gameObjectID. 00363 AkVector& out_emitterPos, ///< The position of the emitter game object \c in_gameObjectID. 00364 AkSoundPathInfo* out_aPaths, ///< Pointer to an array of \c AkSoundPathInfo's which will be filled after returning. 00365 AkUInt32& io_uArraySize ///< The number of slots in \c out_aPaths, after returning the number of valid elements written. 00366 ); 00367 00368 /// Helper function. 00369 /// If the sound is occluded (the listener and emitter are in different rooms with no line of sight), then this function may be used to calculate virtual positions of the sound 00370 /// emitter. The virtual positions represent the 'apparent' source position, because we assume that very little energy is transmitted through the solid wall, 00371 /// the sound appears to come from the portal. The virtual positions may then be passed to the sound engine via \c AK::SpatialAudio::SetEmitterPosition. 00372 /// \sa 00373 /// - \ref AK::SpatialAudio::SetEmitterPosition 00374 AK_EXTERNAPIFUNC(bool, CalcOcclusionAndVirtualPositions)( 00375 const AkVector& in_EmitterPos, ///< Position of sound emitter. 00376 AkRoomID in_EmitterRoomID, ///< ID of the room that the sound emitter is within. 00377 const AkVector& in_ListenerPos, ///< Position of listener. 00378 AkRoomID in_listenerRoomID, ///< ID of the room that the listener is within. 00379 AkReal32& out_fOcclusionFactor, ///< After returning, contains the occlusion value for the emitter, to be passed to Wwise. 00380 AkReal32& out_fObstructionFactor, ///< After returning, contains the obstruction value for the emitter, to be passed to Wwise. 00381 AkTransform* io_aVirtualPositions, ///< An array of size \c io_uArraySize. After returning true, contains the virtual positions of the sound emitter. 00382 AkUInt32& io_uArraySize ///< Number of elements in \c io_aVirtualPositions. After returning, contains the number of valid virtual positions. 00383 ); 00384 } 00385 };