Wwise SDK 2017.2.10
버전
menu_open
link
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 AkPannerType pannerType; ///< Positioning Type (2D, 3D) 00047 AkPositionSourceType posSourceType; ///< Positioning source (GameDef or UserDef) 00048 bool bUpdateEachFrame; ///< Update at each frame (valid only with game-defined) 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_multi_assignobjects 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 ( like 2D sounds ). 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::SetAttenuationScalingFactor 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_
이 페이지가 도움이 되었나요?
작업하는 프로젝트에 대해 알려주세요. 언제든지 도와드릴 준비가 되어 있습니다.
프로젝트를 등록하세요. 아무런 조건이나 의무 사항 없이 빠른 시작을 도와드리겠습니다.
Wwise를 시작해 보세요