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 };