Table of Contents

include/AK/SoundEngine/Common/AkQueryParameters.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 // AkQueryParameters.h
00029 
00030 /// \file 
00031 /// The sound engine parameter query interface.
00032 
00033 
00034 #ifndef _AK_QUERYPARAMS_H_
00035 #define _AK_QUERYPARAMS_H_
00036 
00037 #include <AK/SoundEngine/Common/AkSoundEngineExport.h>
00038 #include <AK/SoundEngine/Common/AkTypes.h>
00039 #include <AK/SoundEngine/Common/AkCommonDefs.h>
00040 #include <AK/Tools/Common/AkArray.h>
00041 
00042 /// Positioning information obtained from an object
00043 struct AkPositioningInfo
00044 {
00045     AkReal32            fCenterPct;         ///< Center % [0..1]
00046     AkSpeakerPanningType    pannerType;     ///< Speaker panning type: type of panning logic when object is not 3D spatialized.
00047     Ak3DPositionType    e3dPositioningType; ///< 3D position type: defines what acts as the emitter position for computing spatialization against the listener. 
00048     bool                bHoldEmitterPosAndOrient;   ///< Hold emitter position and orientation values when starting playback.
00049     Ak3DSpatializationMode e3DSpatializationMode; ///< Spatialization mode
00050     bool                bUseAttenuation;    ///< Use attenuation parameter set
00051 
00052     bool                bUseConeAttenuation; ///< Use the cone attenuation
00053     AkReal32            fInnerAngle;        ///< Inner angle
00054     AkReal32            fOuterAngle;        ///< Outer angle
00055     AkReal32            fConeMaxAttenuation; ///< Cone max attenuation
00056     AkLPFType           LPFCone;            ///< Cone low pass filter value
00057     AkLPFType           HPFCone;            ///< Cone low pass filter value
00058 
00059     AkReal32            fMaxDistance;       ///< Maximum distance
00060     AkReal32            fVolDryAtMaxDist;   ///< Volume dry at maximum distance
00061     AkReal32            fVolAuxGameDefAtMaxDist;    ///< Volume wet at maximum distance (if any) (based on the Game defined distance attenuation)
00062     AkReal32            fVolAuxUserDefAtMaxDist;    ///< Volume wet at maximum distance (if any) (based on the User defined distance attenuation)
00063     AkLPFType           LPFValueAtMaxDist;  ///< Low pass filter value at max distance (if any)
00064     AkLPFType           HPFValueAtMaxDist;  ///< High pass filter value at max distance (if any)
00065 };
00066 
00067 /// Object information structure for QueryAudioObjectsIDs
00068 struct AkObjectInfo
00069 {
00070     AkUniqueID  objID;      ///< Object ID
00071     AkUniqueID  parentID;   ///< Object ID of the parent 
00072     AkInt32     iDepth;     ///< Depth in tree
00073 };
00074 
00075 // Audiokinetic namespace
00076 namespace AK
00077 {
00078     // Audiokinetic sound engine namespace
00079     namespace SoundEngine
00080     {
00081         /// Query namespace
00082         /// \remarks The functions in this namespace are thread-safe, unless stated otherwise.
00083         ///
00084         /// \warning Unless noted otherwise in the function definition that it will not acquire the main audio lock, the functions in this namespace 
00085         /// might stall for several milliseconds before returning (as they cannot execute while the 
00086         /// main sound engine thread is busy). They should therefore not be called from any 
00087         /// game critical thread, such as the main game loop.
00088         ///
00089         /// \warning There might be a significant delay between a Sound Engine call (such as PostEvent) and
00090         /// the information being reflected in a Query (such as GetIsGameObjectActive). 
00091 
00092         namespace Query
00093         {
00094             ////////////////////////////////////////////////////////////////////////
00095             /// @name Game Objects
00096             //@{
00097 
00098             /// Get the position of a game object.
00099             /// \return AK_Success if succeeded, or AK_IDNotFound if the game object was not registered
00100             /// \sa 
00101             /// - \ref soundengine_3dpositions
00102             AK_EXTERNAPIFUNC( AKRESULT, GetPosition )( 
00103                 AkGameObjectID in_GameObjectID,             ///< Game object identifier
00104                 AkSoundPosition& out_rPosition              ///< Position to get
00105                 );
00106 
00107             //@}
00108 
00109             ////////////////////////////////////////////////////////////////////////
00110             /// @name Listeners
00111             //@{
00112 
00113             /// Get a game object's listeners.  
00114             /// \return AK_Success if succeeded, or AK_IDNotFound if the game object was not registered
00115             /// \sa 
00116             /// - \ref soundengine_listeners
00117             AK_EXTERNAPIFUNC( AKRESULT, GetListeners )(
00118                 AkGameObjectID in_GameObjectID,             ///< Source game object identifier
00119                 AkGameObjectID* out_ListenerObjectIDs,      ///< Pointer to an array of AkGameObjectID's.  Will be populated with the IDs of the listeners of in_GameObjectID. Pass NULL to querry the size required.
00120                 AkUInt32& oi_uNumListeners                  ///< Pass in the the available number of elements in the array 'out_ListenerObjectIDs'. After return, the number of valid elements filled in the array.
00121                 );
00122 
00123             /// Get a listener's position.
00124             /// \return AK_Success if succeeded, or AK_InvalidParameter if the index is out of range
00125             /// \sa 
00126             /// - \ref soundengine_listeners_settingpos
00127             AK_EXTERNAPIFUNC( AKRESULT, GetListenerPosition )( 
00128                 AkGameObjectID in_uIndex,                       ///< Listener index (0: first listener, 7: 8th listener)
00129                 AkListenerPosition& out_rPosition           ///< Position set
00130                 );
00131 
00132             /// Get a listener's spatialization parameters. 
00133             /// \return AK_Success if succeeded, or AK_InvalidParameter if the index is out of range
00134             /// \sa 
00135             /// - AK::SoundEngine::SetListenerSpatialization().
00136             /// - \ref soundengine_listeners_spatial
00137             AK_EXTERNAPIFUNC( AKRESULT, GetListenerSpatialization )(
00138                 AkUInt32 in_uIndex,                         ///< Listener index (0: first listener, 7: 8th listener)
00139                 bool& out_rbSpatialized,                    ///< Spatialization enabled
00140                 AK::SpeakerVolumes::VectorPtr & out_pVolumeOffsets, ///< Per-speaker vector of volume offsets, in decibels. Use the functions of AK::SpeakerVolumes::Vector to interpret it.
00141                 AkChannelConfig &out_channelConfig          ///< Channel configuration associated with out_rpVolumeOffsets. 
00142                 );
00143             
00144             //@}
00145 
00146 
00147             ////////////////////////////////////////////////////////////////////////
00148             /// @name Game Syncs
00149             //@{
00150 
00151             /// Enum used to request a specific RTPC Value.
00152             /// Also used to inform the user of where the RTPC Value comes from.
00153             ///
00154             /// For example, the user may request the GameObject specific value by specifying RTPCValue_GameObject
00155             /// and can receive the Global Value if there was no GameObject specific value, and even the 
00156             /// default value is there was no Global value either.
00157             /// \sa 
00158             /// - \ref GetRTPCValue
00159             enum RTPCValue_type
00160             {
00161                 RTPCValue_Default,      ///< The value is the Default RTPC.
00162                 RTPCValue_Global,       ///< The value is the Global RTPC.
00163                 RTPCValue_GameObject,   ///< The value is the game object specific RTPC.
00164                 RTPCValue_PlayingID,    ///< The value is the playing ID specific RTPC.
00165                 RTPCValue_Unavailable   ///< The value is not available for the RTPC specified.
00166             };
00167 
00168             /// Get the value of a real-time parameter control (by ID)
00169             /// An RTPC can have a any combination of a global value, a unique value for each game object, or a unique value for each playing ID.  
00170             /// The value requested is determined by RTPCValue_type, in_gameObjectID and in_playingID.  
00171             /// If a value at the requested scope (determined by RTPCValue_type) is not found, the value that is available at the the next broadest scope will be returned, and io_rValueType will be changed to indicate this.
00172             /// \note
00173             ///     When looking up RTPC values via playing ID (ie. io_rValueType is RTPC_PlayingID), in_gameObjectID can be set to a specific game object (if it is available to the caller) to use as a fall back value.
00174             ///     If the game object is unknown or unavailable, AK_INVALID_GAME_OBJECT can be passed in in_gameObjectID, and the game object will be looked up via in_playingID.  
00175             ///     However in this case, it is not possible to retrieve a game object value as a fall back value if the playing id does not exist.  It is best to pass in the game object if possible.
00176             ///     
00177             /// \return AK_Success if succeeded, AK_IDNotFound if the game object was not registered, or AK_Fail if the RTPC value could not be obtained
00178             /// \sa 
00179             /// - \ref soundengine_rtpc
00180             /// - \ref RTPCValue_type
00181             AK_EXTERNAPIFUNC(AKRESULT, GetRTPCValue)(
00182                 AkRtpcID in_rtpcID,                 ///< ID of the RTPC
00183                 AkGameObjectID in_gameObjectID,     ///< Associated game object ID, ignored if io_rValueType is RTPCValue_Global.
00184                 AkPlayingID in_playingID,           ///< Associated playing ID, ignored if io_rValueType is not RTPC_PlayingID.
00185                 AkRtpcValue& out_rValue,            ///< Value returned
00186                 RTPCValue_type& io_rValueType       ///< In/Out value, the user must specify the requested type. The function will return in this variable the type of the returned value.
00187                 );
00188 
00189 #ifdef AK_SUPPORT_WCHAR
00190 
00191             /// Get the value of a real-time parameter control (by ID)
00192             /// An RTPC can have a any combination of a global value, a unique value for each game object, or a unique value for each playing ID.  
00193             /// The value requested is determined by RTPCValue_type, in_gameObjectID and in_playingID.  
00194             /// If a value at the requested scope (determined by RTPCValue_type) is not found, the value that is available at the the next broadest scope will be returned, and io_rValueType will be changed to indicate this.
00195             /// \note
00196             ///     When looking up RTPC values via playing ID (ie. io_rValueType is RTPC_PlayingID), in_gameObjectID can be set to a specific game object (if it is available to the caller) to use as a fall back value.
00197             ///     If the game object is unknown or unavailable, AK_INVALID_GAME_OBJECT can be passed in in_gameObjectID, and the game object will be looked up via in_playingID.  
00198             ///     However in this case, it is not possible to retrieve a game object value as a fall back value if the playing id does not exist.  It is best to pass in the game object if possible.
00199             ///     
00200             /// \return AK_Success if succeeded, AK_IDNotFound if the game object was not registered or the rtpc name could not be found, or AK_Fail if the RTPC value could not be obtained
00201             /// \sa 
00202             /// - \ref soundengine_rtpc
00203             /// - \ref RTPCValue_type
00204             AK_EXTERNAPIFUNC(AKRESULT, GetRTPCValue)(
00205                 const wchar_t* in_pszRtpcName,      ///< String name of the RTPC
00206                 AkGameObjectID in_gameObjectID,     ///< Associated game object ID, ignored if io_rValueType is RTPCValue_Global.
00207                 AkPlayingID in_playingID,           ///< Associated playing ID, ignored if io_rValueType is not RTPC_PlayingID.
00208                 AkRtpcValue& out_rValue,            ///< Value returned
00209                 RTPCValue_type& io_rValueType       ///< In/Out value, the user must specify the requested type. The function will return in this variable the type of the returned value.              );
00210                 );
00211 
00212 #endif //AK_SUPPORT_WCHAR
00213 
00214             /// Get the value of a real-time parameter control (by ID)
00215             /// An RTPC can have a any combination of a global value, a unique value for each game object, or a unique value for each playing ID.  
00216             /// The value requested is determined by RTPCValue_type, in_gameObjectID and in_playingID.  
00217             /// If a value at the requested scope (determined by RTPCValue_type) is not found, the value that is available at the the next broadest scope will be returned, and io_rValueType will be changed to indicate this.
00218             /// \note
00219             ///     When looking up RTPC values via playing ID (ie. io_rValueType is RTPC_PlayingID), in_gameObjectID can be set to a specific game object (if it is available to the caller) to use as a fall back value.
00220             ///     If the game object is unknown or unavailable, AK_INVALID_GAME_OBJECT can be passed in in_gameObjectID, and the game object will be looked up via in_playingID.  
00221             ///     However in this case, it is not possible to retrieve a game object value as a fall back value if the playing id does not exist.  It is best to pass in the game object if possible.
00222             ///     
00223             /// \return AK_Success if succeeded, AK_IDNotFound if the game object was not registered or the rtpc name could not be found, or AK_Fail if the RTPC value could not be obtained
00224             /// \sa 
00225             /// - \ref soundengine_rtpc
00226             /// - \ref RTPCValue_type
00227             AK_EXTERNAPIFUNC(AKRESULT, GetRTPCValue)(
00228                 const char* in_pszRtpcName,         ///< String name of the RTPC
00229                 AkGameObjectID in_gameObjectID,     ///< Associated game object ID, ignored if io_rValueType is RTPCValue_Global.
00230                 AkPlayingID in_playingID,           ///< Associated playing ID, ignored if io_rValueType is not RTPC_PlayingID.
00231                 AkRtpcValue& out_rValue,            ///< Value returned
00232                 RTPCValue_type& io_rValueType       ///< In/Out value, the user must specify the requested type. The function will return in this variable the type of the returned value.              );
00233                 );
00234 
00235             /// Get the state of a switch group (by IDs).
00236             /// \return AK_Success if succeeded, or AK_IDNotFound if the game object was not registered
00237             /// \sa 
00238             /// - \ref soundengine_switch
00239             AK_EXTERNAPIFUNC( AKRESULT, GetSwitch )( 
00240                 AkSwitchGroupID in_switchGroup,             ///< ID of the switch group
00241                 AkGameObjectID  in_gameObjectID,            ///< Associated game object ID
00242                 AkSwitchStateID& out_rSwitchState           ///< ID of the switch
00243                 );
00244 
00245 #ifdef AK_SUPPORT_WCHAR
00246             /// Get the state of a switch group.
00247             /// \return AK_Success if succeeded, or AK_IDNotFound if the game object was not registered or the switch group name can not be found
00248             /// \sa 
00249             /// - \ref soundengine_switch
00250             AK_EXTERNAPIFUNC( AKRESULT, GetSwitch )( 
00251                 const wchar_t* in_pstrSwitchGroupName,          ///< String name of the switch group
00252                 AkGameObjectID in_GameObj,                  ///< Associated game object ID
00253                 AkSwitchStateID& out_rSwitchState           ///< ID of the switch
00254                 );
00255 #endif //AK_SUPPORT_WCHAR
00256 
00257             /// Get the state of a switch group.
00258             /// \return AK_Success if succeeded, or AK_IDNotFound if the game object was not registered or the switch group name can not be found
00259             /// \sa 
00260             /// - \ref soundengine_switch
00261             AK_EXTERNAPIFUNC( AKRESULT, GetSwitch )( 
00262                 const char* in_pstrSwitchGroupName,         ///< String name of the switch group
00263                 AkGameObjectID in_GameObj,                  ///< Associated game object ID
00264                 AkSwitchStateID& out_rSwitchState           ///< ID of the switch
00265                 );
00266 
00267             /// Get the state of a state group (by IDs).
00268             /// \return AK_Success if succeeded
00269             /// \sa 
00270             /// - \ref soundengine_states
00271             AK_EXTERNAPIFUNC( AKRESULT, GetState )( 
00272                 AkStateGroupID in_stateGroup,               ///< ID of the state group
00273                 AkStateID& out_rState                       ///< ID of the state
00274                 );
00275 
00276 #ifdef AK_SUPPORT_WCHAR
00277             /// Get the state of a state group.
00278             /// \return AK_Success if succeeded, or AK_IDNotFound if the state group name can not be found
00279             /// \sa 
00280             /// - \ref soundengine_states
00281             AK_EXTERNAPIFUNC( AKRESULT, GetState )( 
00282                 const wchar_t* in_pstrStateGroupName,           ///< String name of the state group
00283                 AkStateID& out_rState                       ///< ID of the state
00284                 );
00285 #endif //AK_SUPPORT_WCHAR
00286 
00287             /// Get the state of a state group.
00288             /// \return AK_Success if succeeded, or AK_IDNotFound if the state group name can not be found
00289             /// \sa 
00290             /// - \ref soundengine_states
00291             AK_EXTERNAPIFUNC( AKRESULT, GetState )( 
00292                 const char* in_pstrStateGroupName,              ///< String name of the state group
00293                 AkStateID& out_rState                       ///< ID of the state
00294                 );
00295 
00296             //@}
00297 
00298             ////////////////////////////////////////////////////////////////////////
00299             /// @name Environments
00300             //@{
00301 
00302             /// Get the environmental ratios used by the specified game object.
00303             /// To clear the game object's environments, in_uNumEnvValues must be 0.
00304             /// \sa 
00305             /// - \ref soundengine_environments
00306             /// - \ref soundengine_environments_dynamic_aux_bus_routing
00307             /// - \ref soundengine_environments_id_vs_string
00308             /// \return AK_Success if succeeded, or AK_InvalidParameter if io_ruNumEnvValues is 0 or out_paEnvironmentValues is NULL, or AK_PartialSuccess if more environments exist than io_ruNumEnvValues
00309             /// AK_InvalidParameter
00310             AK_EXTERNAPIFUNC( AKRESULT, GetGameObjectAuxSendValues )( 
00311                 AkGameObjectID      in_gameObjectID,        ///< Associated game object ID
00312                 AkAuxSendValue*     out_paAuxSendValues,    ///< Variable-size array of AkAuxSendValue structures
00313                                                                 ///< (it may be NULL if no aux send must be set)
00314                 AkUInt32&           io_ruNumSendValues      ///< The number of Auxilliary busses at the pointer's address
00315                                                             ///< (it must be 0 if no aux bus is set)
00316                 );
00317 
00318             /// Get the environmental dry level to be used for the specified game object
00319             /// The control value is a number ranging from 0.0f to 1.0f.
00320             /// 0.0f stands for 0% dry, while 1.0f stands for 100% dry.
00321             /// \aknote Reducing the dry level does not mean increasing the wet level. \endaknote
00322             /// \sa 
00323             /// - \ref soundengine_environments
00324             /// - \ref soundengine_environments_setting_dry_environment
00325             /// - \ref soundengine_environments_id_vs_string
00326             /// \return AK_Success if succeeded, or AK_IDNotFound if the game object was not registered
00327             AK_EXTERNAPIFUNC( AKRESULT, GetGameObjectDryLevelValue )( 
00328                 AkGameObjectID      in_EmitterID,           ///< Associated emitter game object ID
00329                 AkGameObjectID      in_ListenerID,          ///< Associated listener game object ID
00330                 AkReal32&           out_rfControlValue      ///< Dry level control value, ranging from 0.0f to 1.0f
00331                                                             ///< (0.0f stands for 0% dry, while 1.0f stands for 100% dry)
00332                 );
00333 
00334             /// Get a game object's obstruction and occlusion levels.
00335             /// \sa 
00336             /// - \ref soundengine_obsocc
00337             /// - \ref soundengine_environments
00338             /// \return AK_Success if succeeded, AK_IDNotFound if the game object was not registered
00339             AK_EXTERNAPIFUNC( AKRESULT, GetObjectObstructionAndOcclusion )(  
00340                 AkGameObjectID in_EmitterID,            ///< Associated game object ID
00341                 AkGameObjectID in_ListenerID,           ///< Listener object ID
00342                 AkReal32& out_rfObstructionLevel,       ///< ObstructionLevel: [0.0f..1.0f]
00343                 AkReal32& out_rfOcclusionLevel          ///< OcclusionLevel: [0.0f..1.0f]
00344                 );
00345 
00346             //@}
00347 
00348             /// Get the list of audio object IDs associated to an event.
00349             /// \aknote It is possible to call QueryAudioObjectIDs with io_ruNumItems = 0 to get the total size of the
00350             /// structure that should be allocated for out_aObjectInfos. \endaknote
00351             /// \return AK_Success if succeeded, AK_IDNotFound if the eventID cannot be found, AK_InvalidParameter if out_aObjectInfos is NULL while io_ruNumItems > 0
00352             /// or AK_UnknownObject if the event contains an unknown audio object, 
00353             /// or AK_PartialSuccess if io_ruNumItems was set to 0 to query the number of available items.
00354             AK_EXTERNAPIFUNC( AKRESULT, QueryAudioObjectIDs )(
00355                 AkUniqueID in_eventID,              ///< Event ID
00356                 AkUInt32& io_ruNumItems,            ///< Number of items in array provided / Number of items filled in array
00357                 AkObjectInfo* out_aObjectInfos      ///< Array of AkObjectInfo items to fill
00358                 );
00359 
00360 #ifdef AK_SUPPORT_WCHAR
00361             /// Get the list of audio object IDs associated to a event name.
00362             /// \aknote It is possible to call QueryAudioObjectIDs with io_ruNumItems = 0 to get the total size of the
00363             /// structure that should be allocated for out_aObjectInfos. \endaknote
00364             /// \return AK_Success if succeeded, AK_IDNotFound if the event name cannot be found, AK_InvalidParameter if out_aObjectInfos is NULL while io_ruNumItems > 0
00365             /// or AK_UnknownObject if the event contains an unknown audio object, 
00366             /// or AK_PartialSuccess if io_ruNumItems was set to 0 to query the number of available items.
00367             AK_EXTERNAPIFUNC( AKRESULT, QueryAudioObjectIDs )(
00368                 const wchar_t* in_pszEventName,     ///< Event name
00369                 AkUInt32& io_ruNumItems,            ///< Number of items in array provided / Number of items filled in array
00370                 AkObjectInfo* out_aObjectInfos      ///< Array of AkObjectInfo items to fill
00371                 );
00372 #endif //AK_SUPPORT_WCHAR
00373 
00374             /// Get the list of audio object IDs associated to an event name.
00375             /// \aknote It is possible to call QueryAudioObjectIDs with io_ruNumItems = 0 to get the total size of the
00376             /// structure that should be allocated for out_aObjectInfos. \endaknote
00377             /// \return AK_Success if succeeded, AK_IDNotFound if the event name cannot be found, AK_InvalidParameter if out_aObjectInfos is NULL while io_ruNumItems > 0
00378             /// or AK_UnknownObject if the event contains an unknown audio object, 
00379             /// or AK_PartialSuccess if io_ruNumItems was set to 0 to query the number of available items.
00380             AK_EXTERNAPIFUNC( AKRESULT, QueryAudioObjectIDs )(
00381                 const char* in_pszEventName,        ///< Event name
00382                 AkUInt32& io_ruNumItems,            ///< Number of items in array provided / Number of items filled in array
00383                 AkObjectInfo* out_aObjectInfos      ///< Array of AkObjectInfo items to fill
00384                 );
00385 
00386             /// Get positioning information associated to an audio object.
00387             /// \return AK_Success if succeeded, AK_IDNotFound if the object ID cannot be found, AK_NotCompatible if the audio object cannot expose positioning
00388             AK_EXTERNAPIFUNC( AKRESULT, GetPositioningInfo )( 
00389                 AkUniqueID in_ObjectID,                     ///< Audio object ID
00390                 AkPositioningInfo& out_rPositioningInfo     ///< Positioning information structure to be filled
00391                 );
00392 
00393             /// List passed to GetActiveGameObjects.
00394             /// After calling this function, the list will contain the list of all game objects that are currently active in the sound engine.
00395             /// Being active means that either a sound is playing or pending to be played using this game object.
00396             /// The caller is responsible for calling Term() on the list when the list is not required anymore
00397             /// \sa 
00398             /// - \ref GetActiveGameObjects
00399             typedef AkArray<AkGameObjectID, AkGameObjectID, ArrayPoolDefault, 32> AkGameObjectsList;
00400 
00401             /// Fill the provided list with all the game object IDs that are currently active in the sound engine.
00402             /// The function may be used to avoid updating game objects positions that are not required at the moment.
00403             /// After calling this function, the list will contain the list of all game objects that are currently active in the sound engine.
00404             /// Being active means that either a sound is playing or pending to be played using this game object.
00405             /// \sa 
00406             /// - \ref AkGameObjectsList
00407             AK_EXTERNAPIFUNC( AKRESULT, GetActiveGameObjects )( 
00408                 AkGameObjectsList& io_GameObjectList    ///< returned list of active game objects.
00409                 );
00410 
00411             /// Query if the specified game object is currently active.
00412             /// Being active means that either a sound is playing or pending to be played using this game object.
00413             AK_EXTERNAPIFUNC( bool, GetIsGameObjectActive )( 
00414                 AkGameObjectID in_GameObjId ///< Game object ID
00415                 );
00416 
00417             /// Game object and max distance association.
00418             /// \sa 
00419             /// - \ref AkRadiusList
00420             struct GameObjDst
00421             {
00422                 /// Default constructor
00423                 GameObjDst()
00424                     : m_gameObjID( AK_INVALID_GAME_OBJECT )
00425                     , m_dst( -1.0f )
00426                 {}
00427 
00428                 /// Easy constructor
00429                 GameObjDst( AkGameObjectID in_gameObjID, AkReal32 in_dst )
00430                     : m_gameObjID( in_gameObjID )
00431                     , m_dst( in_dst )
00432                 {}
00433 
00434                 AkGameObjectID  m_gameObjID;    ///< Game object ID
00435                 AkReal32        m_dst;          ///< MaxDistance
00436             };
00437 
00438             /// List passed to GetMaxRadius.
00439             /// \sa 
00440             /// - \ref AK::SoundEngine::Query::GetMaxRadius
00441             typedef AkArray<GameObjDst, const GameObjDst&, ArrayPoolDefault, 32> AkRadiusList;
00442 
00443             /// Returns the maximum distance used in attenuations associated to all sounds currently playing.
00444             /// This may be used for example by the game to know if some processing need to be performed on the game side, that would not be required
00445             /// if the object is out of reach anyway.
00446             ///
00447             /// Example usage:
00448             /// \code
00449             /// /*******************************************************/
00450             /// AkRadiusList RadLst; //creating the list( array ).
00451             /// // Do not reserve any size for the array, 
00452             /// // the system will reserve the correct size.
00453             ///
00454             /// GetMaxRadius( RadLst );
00455             /// // Use the content of the list
00456             /// (...)
00457             ///
00458             /// RadLst.Term();// the user is responsible to free the memory allocated
00459             /// /*******************************************************/
00460             /// \endcode
00461             ///
00462             /// \aknote The returned value is NOT the distance from a listener to an object but
00463             /// the maximum attenuation distance of all sounds playing on this object. This is
00464             /// not related in any way to the curent 3D position of the object. \endaknote
00465             ///
00466             /// \return 
00467             /// - AK_Success if succeeded
00468             /// - AK_InsuficientMemory if there was not enough memory
00469             ///
00470             /// \aknote 
00471             /// The Scaling factor (if one was specified on the game object) is included in the return value.
00472             /// The Scaling factor is not updated once a sound starts playing since it 
00473             /// is computed only when the playback starts with the initial scaling factor of this game object. Scaling factor will 
00474             /// be re-computed for every playback instance, always using the scaling factor available at this time.
00475             /// \endaknote
00476             ///
00477             /// \sa 
00478             /// - \ref AkRadiusList
00479             AK_EXTERNAPIFUNC( AKRESULT, GetMaxRadius )(
00480                 AkRadiusList & io_RadiusList    ///< List that will be filled with AK::SoundEngine::Query::GameObjDst objects.
00481                 );
00482 
00483             /// Returns the maximum distance used in attenuations associated to sounds playing using the specified game object.
00484             /// This may be used for example by the game to know if some processing need to be performed on the game side, that would not be required
00485             /// if the object is out of reach anyway.
00486             /// 
00487             /// \aknote The returned value is NOT the distance from a listener to an object but the maximum attenuation distance of all sounds playing on this object. \endaknote
00488             ///
00489             /// \return
00490             /// - A negative number if the game object specified is not playing.
00491             /// - 0, if the game object was only associated to sounds playing using no distance attenuation.
00492             /// - A positive number represents the maximum of all the distance attenuations playing on this game object.
00493             ///
00494             /// \aknote 
00495             /// The Scaling factor (if one was specified on the game object) is included in the return value.
00496             /// The Scaling factor is not updated once a sound starts playing since it 
00497             /// is computed only when the playback starts with the initial scaling factor of this game object. Scaling factor will 
00498             /// be re-computed for every playback instance, always using the scaling factor available at this time.
00499             /// \endaknote
00500             ///
00501             /// \sa 
00502             /// - \ref AK::SoundEngine::SetScalingFactor
00503             AK_EXTERNAPIFUNC( AkReal32, GetMaxRadius )(
00504                 AkGameObjectID in_GameObjId ///< Game object ID
00505                 );
00506 
00507             /// Get the Event ID associated to the specified PlayingID.
00508             /// This function does not acquire the main audio lock.
00509             ///
00510             /// \return AK_INVALID_UNIQUE_ID on failure.
00511             AK_EXTERNAPIFUNC( AkUniqueID, GetEventIDFromPlayingID )(
00512                 AkPlayingID in_playingID ///< Associated PlayingID
00513                 );
00514 
00515             /// Get the ObjectID associated to the specified PlayingID.
00516             /// This function does not acquire the main audio lock.
00517             ///
00518             /// \return AK_INVALID_GAME_OBJECT on failure.
00519             AK_EXTERNAPIFUNC( AkGameObjectID, GetGameObjectFromPlayingID )(
00520                 AkPlayingID in_playingID ///< Associated PlayingID
00521                 );
00522 
00523             /// Get the list PlayingIDs associated with the given game object.
00524             /// This function does not acquire the main audio lock.
00525             ///
00526             /// \aknote It is possible to call GetPlayingIDsFromGameObject with io_ruNumItems = 0 to get the total size of the
00527             /// structure that should be allocated for out_aPlayingIDs. \endaknote
00528             /// \return AK_Success if succeeded, AK_InvalidParameter if out_aPlayingIDs is NULL while io_ruNumItems > 0
00529             AK_EXTERNAPIFUNC( AKRESULT, GetPlayingIDsFromGameObject )(
00530                 AkGameObjectID in_GameObjId,        ///< Game object ID
00531                 AkUInt32& io_ruNumIDs,              ///< Number of items in array provided / Number of items filled in array
00532                 AkPlayingID* out_aPlayingIDs        ///< Array of AkPlayingID items to fill
00533                 );
00534 
00535             /// Get the value of a custom property of integer or boolean type.
00536             /// \return AK_PartialSuccess if the object was found but no matching custom property was found on this object. Note that it could mean this value is the default value. 
00537             AK_EXTERNAPIFUNC( AKRESULT, GetCustomPropertyValue )(
00538                 AkUniqueID in_ObjectID,         ///< Object ID, this is the 32bit ShortID of the AudioFileSource or Sound object found in the .wwu XML file. At runtime it can only be retrieved by the AK_Duration callback when registered with PostEvent(), or by calling Query::QueryAudioObjectIDs() to get all the shortIDs associated with an event.
00539                 AkUInt32 in_uPropID,            ///< Property ID of your custom property found under the Custom Properties tab of the Wwise project settings.
00540                 AkInt32& out_iValue             ///< Property Value
00541                 );
00542 
00543             /// Get the value of a custom property of real type.
00544             /// \return AK_PartialSuccess if the object was found but no matching custom property was found on this object. Note that it could mean this value is the default value.
00545             AK_EXTERNAPIFUNC( AKRESULT, GetCustomPropertyValue )(
00546                 AkUniqueID in_ObjectID,         ///< Object ID, this is the 32bit ShortID of the AudioFileSource or Sound object found in the .wwu XML file. At runtime it can only be retrieved by the AK_Duration callback when registered with PostEvent(), or by calling Query::QueryAudioObjectIDs() to get all the shortIDs associated with an event.
00547                 AkUInt32 in_uPropID,            ///< Property ID of your custom property found under the Custom Properties tab of the Wwise project settings.
00548                 AkReal32& out_fValue            ///< Property Value
00549                 );
00550 
00551         } //namespace Query
00552     } //namespace SoundEngine
00553 } //namespace AK
00554 
00555 #endif // _AK_QUERYPARAMS_H_