AkQueryParameters.h 29 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551
  1. /*******************************************************************************
  2. The content of this file includes portions of the AUDIOKINETIC Wwise Technology
  3. released in source code form as part of the SDK installer package.
  4. Commercial License Usage
  5. Licensees holding valid commercial licenses to the AUDIOKINETIC Wwise Technology
  6. may use this file in accordance with the end user license agreement provided
  7. with the software or, alternatively, in accordance with the terms contained in a
  8. written agreement between you and Audiokinetic Inc.
  9. Apache License Usage
  10. Alternatively, this file may be used under the Apache License, Version 2.0 (the
  11. "Apache License"); you may not use this file except in compliance with the
  12. Apache License. You may obtain a copy of the Apache License at
  13. http://www.apache.org/licenses/LICENSE-2.0.
  14. Unless required by applicable law or agreed to in writing, software distributed
  15. under the Apache License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES
  16. OR CONDITIONS OF ANY KIND, either express or implied. See the Apache License for
  17. the specific language governing permissions and limitations under the License.
  18. Copyright (c) 2023 Audiokinetic Inc.
  19. *******************************************************************************/
  20. // AkQueryParameters.h
  21. /// \file
  22. /// The sound engine parameter query interface.
  23. #ifndef _AK_QUERYPARAMS_H_
  24. #define _AK_QUERYPARAMS_H_
  25. #include <AK/SoundEngine/Common/AkSoundEngineExport.h>
  26. #include <AK/SoundEngine/Common/AkTypes.h>
  27. #include <AK/SoundEngine/Common/AkCommonDefs.h>
  28. #include <AK/Tools/Common/AkArray.h>
  29. /// Positioning information obtained from an object
  30. struct AkPositioningInfo
  31. {
  32. AkReal32 fCenterPct; ///< Center % [0..1]
  33. AkSpeakerPanningType pannerType; ///< Speaker panning type: type of panning logic when object is not 3D spatialized.
  34. Ak3DPositionType e3dPositioningType; ///< 3D position type: defines what acts as the emitter position for computing spatialization against the listener.
  35. bool bHoldEmitterPosAndOrient; ///< Hold emitter position and orientation values when starting playback.
  36. Ak3DSpatializationMode e3DSpatializationMode; ///< Spatialization mode
  37. bool bEnableAttenuation; ///< Attenuation parameter set is active.
  38. bool bUseConeAttenuation; ///< Use the cone attenuation
  39. AkReal32 fInnerAngle; ///< Inner angle
  40. AkReal32 fOuterAngle; ///< Outer angle
  41. AkReal32 fConeMaxAttenuation; ///< Cone max attenuation
  42. AkLPFType LPFCone; ///< Cone low pass filter value
  43. AkLPFType HPFCone; ///< Cone low pass filter value
  44. AkReal32 fMaxDistance; ///< Maximum distance
  45. AkReal32 fVolDryAtMaxDist; ///< Volume dry at maximum distance
  46. AkReal32 fVolAuxGameDefAtMaxDist; ///< Volume wet at maximum distance (if any) (based on the Game defined distance attenuation)
  47. AkReal32 fVolAuxUserDefAtMaxDist; ///< Volume wet at maximum distance (if any) (based on the User defined distance attenuation)
  48. AkLPFType LPFValueAtMaxDist; ///< Low pass filter value at max distance (if any)
  49. AkLPFType HPFValueAtMaxDist; ///< High pass filter value at max distance (if any)
  50. };
  51. /// Object information structure for QueryAudioObjectsIDs
  52. struct AkObjectInfo
  53. {
  54. AkUniqueID objID; ///< Object ID
  55. AkUniqueID parentID; ///< Object ID of the parent
  56. AkInt32 iDepth; ///< Depth in tree
  57. };
  58. // Audiokinetic namespace
  59. namespace AK
  60. {
  61. // Audiokinetic sound engine namespace
  62. namespace SoundEngine
  63. {
  64. /// Query namespace
  65. /// \remarks The functions in this namespace are thread-safe, unless stated otherwise. We recommend that you use these functions in development builds only, because they can cause CPU spikes.
  66. ///
  67. /// \akwarning
  68. /// The functions in this namespace might stall for several milliseconds before returning
  69. /// because they cannot execute while the main sound engine tick is running.
  70. /// They should therefore not be called from any game-critical thread, such as the main game loop.
  71. /// However, if the function definition states that it does not require the main audio lock, no delay should occur.
  72. ///
  73. /// There might be a significant delay between a Sound Engine call, such as PostEvent, and
  74. /// the information being returned in a Query, such as GetIsGameObjectActive.
  75. /// \endakwarning
  76. namespace Query
  77. {
  78. ////////////////////////////////////////////////////////////////////////
  79. /// @name Game Objects
  80. //@{
  81. /// Get the position of a game object.
  82. /// \return AK_Success if succeeded, or AK_IDNotFound if the game object was not registered
  83. /// \sa
  84. /// - \ref soundengine_3dpositions
  85. AK_EXTERNAPIFUNC( AKRESULT, GetPosition )(
  86. AkGameObjectID in_GameObjectID, ///< Game object identifier
  87. AkSoundPosition& out_rPosition ///< Position to get
  88. );
  89. //@}
  90. ////////////////////////////////////////////////////////////////////////
  91. /// @name Listeners
  92. //@{
  93. /// Get a game object's listeners.
  94. /// \return AK_Success if succeeded, or AK_IDNotFound if the game object was not registered
  95. /// \sa
  96. /// - \ref soundengine_listeners
  97. AK_EXTERNAPIFUNC( AKRESULT, GetListeners )(
  98. AkGameObjectID in_GameObjectID, ///< Source game object identifier
  99. 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.
  100. 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.
  101. );
  102. /// Get a listener's position.
  103. /// \return AK_Success if succeeded, or AK_InvalidParameter if the index is out of range
  104. /// \sa
  105. /// - \ref soundengine_listeners_settingpos
  106. AK_EXTERNAPIFUNC( AKRESULT, GetListenerPosition )(
  107. AkGameObjectID in_uListenerID, ///< Listener game object ID.
  108. AkListenerPosition& out_rPosition ///< Position set
  109. );
  110. /// Get a listener's spatialization parameters.
  111. /// \return AK_Success if succeeded, or AK_InvalidParameter if the index is out of range
  112. /// \sa
  113. /// - AK::SoundEngine::SetListenerSpatialization().
  114. /// - \ref soundengine_listeners_spatial
  115. AK_EXTERNAPIFUNC( AKRESULT, GetListenerSpatialization )(
  116. AkGameObjectID in_uListenerID, ///< Listener game object ID.
  117. bool& out_rbSpatialized, ///< Spatialization enabled
  118. AK::SpeakerVolumes::VectorPtr & out_pVolumeOffsets, ///< Per-speaker vector of volume offsets, in decibels. Use the functions of AK::SpeakerVolumes::Vector to interpret it.
  119. AkChannelConfig &out_channelConfig ///< Channel configuration associated with out_rpVolumeOffsets.
  120. );
  121. //@}
  122. ////////////////////////////////////////////////////////////////////////
  123. /// @name Game Syncs
  124. //@{
  125. /// Enum used to request a specific RTPC Value.
  126. /// Also used to inform the user of where the RTPC Value comes from.
  127. ///
  128. /// For example, the user may request the GameObject specific value by specifying RTPCValue_GameObject
  129. /// and can receive the Global Value if there was no GameObject specific value, and even the
  130. /// default value is there was no Global value either.
  131. /// \sa
  132. /// - GetRTPCValue
  133. enum RTPCValue_type
  134. {
  135. RTPCValue_Default, ///< The value is the Default RTPC.
  136. RTPCValue_Global, ///< The value is the Global RTPC.
  137. RTPCValue_GameObject, ///< The value is the game object specific RTPC.
  138. RTPCValue_PlayingID, ///< The value is the playing ID specific RTPC.
  139. RTPCValue_Unavailable ///< The value is not available for the RTPC specified.
  140. };
  141. /// Get the value of a real-time parameter control (by ID)
  142. /// 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.
  143. /// The value requested is determined by RTPCValue_type, in_gameObjectID and in_playingID.
  144. /// 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.
  145. /// \note
  146. /// 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.
  147. /// 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.
  148. /// 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.
  149. ///
  150. /// \return AK_Success if succeeded, AK_IDNotFound if the RTPC does not exist
  151. /// \sa
  152. /// - \ref soundengine_rtpc
  153. /// - RTPCValue_type
  154. AK_EXTERNAPIFUNC(AKRESULT, GetRTPCValue)(
  155. AkRtpcID in_rtpcID, ///< ID of the RTPC
  156. AkGameObjectID in_gameObjectID, ///< Associated game object ID, ignored if io_rValueType is RTPCValue_Global.
  157. AkPlayingID in_playingID, ///< Associated playing ID, ignored if io_rValueType is not RTPC_PlayingID.
  158. AkRtpcValue& out_rValue, ///< Value returned
  159. 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.
  160. );
  161. #ifdef AK_SUPPORT_WCHAR
  162. /// Get the value of a real-time parameter control (by ID)
  163. /// 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.
  164. /// The value requested is determined by RTPCValue_type, in_gameObjectID and in_playingID.
  165. /// 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.
  166. /// \note
  167. /// 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.
  168. /// 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.
  169. /// 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.
  170. ///
  171. /// \return AK_Success if succeeded, AK_IDNotFound if the RTPC does not exist
  172. /// \sa
  173. /// - \ref soundengine_rtpc
  174. /// - RTPCValue_type
  175. AK_EXTERNAPIFUNC(AKRESULT, GetRTPCValue)(
  176. const wchar_t* in_pszRtpcName, ///< String name of the RTPC
  177. AkGameObjectID in_gameObjectID, ///< Associated game object ID, ignored if io_rValueType is RTPCValue_Global.
  178. AkPlayingID in_playingID, ///< Associated playing ID, ignored if io_rValueType is not RTPC_PlayingID.
  179. AkRtpcValue& out_rValue, ///< Value returned
  180. 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. );
  181. );
  182. #endif //AK_SUPPORT_WCHAR
  183. /// Get the value of a real-time parameter control (by ID)
  184. /// 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.
  185. /// The value requested is determined by RTPCValue_type, in_gameObjectID and in_playingID.
  186. /// 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.
  187. /// \note
  188. /// 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.
  189. /// 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.
  190. /// 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.
  191. ///
  192. /// \return AK_Success if succeeded, AK_IDNotFound if the RTPC does not exist
  193. /// \sa
  194. /// - \ref soundengine_rtpc
  195. /// - RTPCValue_type
  196. AK_EXTERNAPIFUNC(AKRESULT, GetRTPCValue)(
  197. const char* in_pszRtpcName, ///< String name of the RTPC
  198. AkGameObjectID in_gameObjectID, ///< Associated game object ID, ignored if io_rValueType is RTPCValue_Global.
  199. AkPlayingID in_playingID, ///< Associated playing ID, ignored if io_rValueType is not RTPC_PlayingID.
  200. AkRtpcValue& out_rValue, ///< Value returned
  201. 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. );
  202. );
  203. /// Get the state of a switch group (by IDs).
  204. /// \return AK_Success if succeeded, or AK_IDNotFound if the game object was not registered
  205. /// \sa
  206. /// - \ref soundengine_switch
  207. AK_EXTERNAPIFUNC( AKRESULT, GetSwitch )(
  208. AkSwitchGroupID in_switchGroup, ///< ID of the switch group
  209. AkGameObjectID in_gameObjectID, ///< Associated game object ID
  210. AkSwitchStateID& out_rSwitchState ///< ID of the switch
  211. );
  212. #ifdef AK_SUPPORT_WCHAR
  213. /// Get the state of a switch group.
  214. /// \return AK_Success if succeeded, or AK_IDNotFound if the game object was not registered or the switch group name can not be found
  215. /// \sa
  216. /// - \ref soundengine_switch
  217. AK_EXTERNAPIFUNC( AKRESULT, GetSwitch )(
  218. const wchar_t* in_pstrSwitchGroupName, ///< String name of the switch group
  219. AkGameObjectID in_GameObj, ///< Associated game object ID
  220. AkSwitchStateID& out_rSwitchState ///< ID of the switch
  221. );
  222. #endif //AK_SUPPORT_WCHAR
  223. /// Get the state of a switch group.
  224. /// \return AK_Success if succeeded, or AK_IDNotFound if the game object was not registered or the switch group name can not be found
  225. /// \sa
  226. /// - \ref soundengine_switch
  227. AK_EXTERNAPIFUNC( AKRESULT, GetSwitch )(
  228. const char* in_pstrSwitchGroupName, ///< String name of the switch group
  229. AkGameObjectID in_GameObj, ///< Associated game object ID
  230. AkSwitchStateID& out_rSwitchState ///< ID of the switch
  231. );
  232. /// Get the state of a state group (by IDs).
  233. /// \return AK_Success if succeeded
  234. /// \sa
  235. /// - \ref soundengine_states
  236. AK_EXTERNAPIFUNC( AKRESULT, GetState )(
  237. AkStateGroupID in_stateGroup, ///< ID of the state group
  238. AkStateID& out_rState ///< ID of the state
  239. );
  240. #ifdef AK_SUPPORT_WCHAR
  241. /// Get the state of a state group.
  242. /// \return AK_Success if succeeded, or AK_IDNotFound if the state group name can not be found
  243. /// \sa
  244. /// - \ref soundengine_states
  245. AK_EXTERNAPIFUNC( AKRESULT, GetState )(
  246. const wchar_t* in_pstrStateGroupName, ///< String name of the state group
  247. AkStateID& out_rState ///< ID of the state
  248. );
  249. #endif //AK_SUPPORT_WCHAR
  250. /// Get the state of a state group.
  251. /// \return AK_Success if succeeded, or AK_IDNotFound if the state group name can not be found
  252. /// \sa
  253. /// - \ref soundengine_states
  254. AK_EXTERNAPIFUNC( AKRESULT, GetState )(
  255. const char* in_pstrStateGroupName, ///< String name of the state group
  256. AkStateID& out_rState ///< ID of the state
  257. );
  258. //@}
  259. ////////////////////////////////////////////////////////////////////////
  260. /// @name Environments
  261. //@{
  262. /// Get the environmental ratios used by the specified game object.
  263. /// \sa
  264. /// - \ref soundengine_environments
  265. /// - \ref soundengine_environments_dynamic_aux_bus_routing
  266. /// - \ref soundengine_environments_id_vs_string
  267. /// \return AK_Success if succeeded, or AK_InvalidParameter if io_ruNumSendValues is 0 or out_paEnvironmentValues is NULL, or AK_PartialSuccess if more environments exist than io_ruNumSendValues
  268. AK_EXTERNAPIFUNC( AKRESULT, GetGameObjectAuxSendValues )(
  269. AkGameObjectID in_gameObjectID, ///< Associated game object ID
  270. AkAuxSendValue* out_paAuxSendValues, ///< Variable-size array of AkAuxSendValue structures
  271. ///< (it may be NULL if no aux send must be set)
  272. AkUInt32& io_ruNumSendValues ///< The number of Auxilliary busses at the pointer's address
  273. ///< (it must be 0 if no aux bus is set)
  274. );
  275. /// Get the environmental dry level to be used for the specified game object
  276. /// The control value is a number ranging from 0.0f to 1.0f.
  277. /// 0.0f stands for 0% dry, while 1.0f stands for 100% dry.
  278. /// \aknote Reducing the dry level does not mean increasing the wet level. \endaknote
  279. /// \sa
  280. /// - \ref soundengine_environments
  281. /// - \ref soundengine_environments_setting_dry_environment
  282. /// - \ref soundengine_environments_id_vs_string
  283. /// \return AK_Success if succeeded, or AK_IDNotFound if the game object was not registered
  284. AK_EXTERNAPIFUNC( AKRESULT, GetGameObjectDryLevelValue )(
  285. AkGameObjectID in_EmitterID, ///< Associated emitter game object ID
  286. AkGameObjectID in_ListenerID, ///< Associated listener game object ID
  287. AkReal32& out_rfControlValue ///< Dry level control value, ranging from 0.0f to 1.0f
  288. ///< (0.0f stands for 0% dry, while 1.0f stands for 100% dry)
  289. );
  290. /// Get a game object's obstruction and occlusion levels.
  291. /// \sa
  292. /// - \ref soundengine_obsocc
  293. /// - \ref soundengine_environments
  294. /// \return AK_Success if succeeded, AK_IDNotFound if the game object was not registered
  295. AK_EXTERNAPIFUNC( AKRESULT, GetObjectObstructionAndOcclusion )(
  296. AkGameObjectID in_EmitterID, ///< Associated game object ID
  297. AkGameObjectID in_ListenerID, ///< Listener object ID
  298. AkReal32& out_rfObstructionLevel, ///< ObstructionLevel: [0.0f..1.0f]
  299. AkReal32& out_rfOcclusionLevel ///< OcclusionLevel: [0.0f..1.0f]
  300. );
  301. //@}
  302. /// Get the list of audio object IDs associated to an event.
  303. /// \aknote It is possible to call QueryAudioObjectIDs with io_ruNumItems = 0 to get the total size of the
  304. /// structure that should be allocated for out_aObjectInfos. \endaknote
  305. /// \return AK_Success if succeeded, AK_IDNotFound if the eventID cannot be found, AK_InvalidParameter if out_aObjectInfos is NULL while io_ruNumItems > 0
  306. /// or AK_PartialSuccess if io_ruNumItems was set to 0 to query the number of available items.
  307. AK_EXTERNAPIFUNC( AKRESULT, QueryAudioObjectIDs )(
  308. AkUniqueID in_eventID, ///< Event ID
  309. AkUInt32& io_ruNumItems, ///< Number of items in array provided / Number of items filled in array
  310. AkObjectInfo* out_aObjectInfos ///< Array of AkObjectInfo items to fill
  311. );
  312. #ifdef AK_SUPPORT_WCHAR
  313. /// Get the list of audio object IDs associated to a event name.
  314. /// \aknote It is possible to call QueryAudioObjectIDs with io_ruNumItems = 0 to get the total size of the
  315. /// structure that should be allocated for out_aObjectInfos. \endaknote
  316. /// \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
  317. /// or AK_PartialSuccess if io_ruNumItems was set to 0 to query the number of available items.
  318. AK_EXTERNAPIFUNC( AKRESULT, QueryAudioObjectIDs )(
  319. const wchar_t* in_pszEventName, ///< Event name
  320. AkUInt32& io_ruNumItems, ///< Number of items in array provided / Number of items filled in array
  321. AkObjectInfo* out_aObjectInfos ///< Array of AkObjectInfo items to fill
  322. );
  323. #endif //AK_SUPPORT_WCHAR
  324. /// Get the list of audio object IDs associated to an event name.
  325. /// \aknote It is possible to call QueryAudioObjectIDs with io_ruNumItems = 0 to get the total size of the
  326. /// structure that should be allocated for out_aObjectInfos. \endaknote
  327. /// \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
  328. /// or AK_PartialSuccess if io_ruNumItems was set to 0 to query the number of available items.
  329. AK_EXTERNAPIFUNC( AKRESULT, QueryAudioObjectIDs )(
  330. const char* in_pszEventName, ///< Event name
  331. AkUInt32& io_ruNumItems, ///< Number of items in array provided / Number of items filled in array
  332. AkObjectInfo* out_aObjectInfos ///< Array of AkObjectInfo items to fill
  333. );
  334. /// Get positioning information associated to an audio object.
  335. /// \return AK_Success if succeeded, AK_IDNotFound if the object ID cannot be found, AK_NotCompatible if the audio object cannot expose positioning
  336. AK_EXTERNAPIFUNC( AKRESULT, GetPositioningInfo )(
  337. AkUniqueID in_ObjectID, ///< Audio object ID
  338. AkPositioningInfo& out_rPositioningInfo ///< Positioning information structure to be filled
  339. );
  340. /// List passed to GetActiveGameObjects.
  341. /// After calling this function, the list will contain the list of all game objects that are currently active in the sound engine.
  342. /// Being active means that either a sound is playing or pending to be played using this game object.
  343. /// The caller is responsible for calling Term() on the list when the list is not required anymore
  344. /// \sa
  345. /// - GetActiveGameObjects
  346. typedef AkArray<AkGameObjectID, AkGameObjectID> AkGameObjectsList;
  347. /// Fill the provided list with all the game object IDs that are currently active in the sound engine.
  348. /// The function may be used to avoid updating game objects positions that are not required at the moment.
  349. /// After calling this function, the list will contain the list of all game objects that are currently active in the sound engine.
  350. /// Being active means that either a sound is playing or pending to be played using this game object.
  351. /// \sa
  352. /// - AkGameObjectsList
  353. AK_EXTERNAPIFUNC( AKRESULT, GetActiveGameObjects )(
  354. AkGameObjectsList& io_GameObjectList ///< returned list of active game objects.
  355. );
  356. /// Query if the specified game object is currently active.
  357. /// Being active means that either a sound is playing or pending to be played using this game object.
  358. AK_EXTERNAPIFUNC( bool, GetIsGameObjectActive )(
  359. AkGameObjectID in_GameObjId ///< Game object ID
  360. );
  361. /// Game object and max distance association.
  362. /// \sa
  363. /// - \ref AkRadiusList
  364. struct GameObjDst
  365. {
  366. /// Default constructor
  367. GameObjDst()
  368. : m_gameObjID( AK_INVALID_GAME_OBJECT )
  369. , m_dst( -1.0f )
  370. {}
  371. /// Easy constructor
  372. GameObjDst( AkGameObjectID in_gameObjID, AkReal32 in_dst )
  373. : m_gameObjID( in_gameObjID )
  374. , m_dst( in_dst )
  375. {}
  376. AkGameObjectID m_gameObjID; ///< Game object ID
  377. AkReal32 m_dst; ///< MaxDistance
  378. };
  379. /// List passed to GetMaxRadius.
  380. /// \sa
  381. /// - \ref AK::SoundEngine::Query::GetMaxRadius
  382. typedef AkArray<GameObjDst, const GameObjDst&> AkRadiusList;
  383. /// Returns the maximum distance used in attenuations associated to all sounds currently playing.
  384. /// 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
  385. /// if the object is out of reach anyway.
  386. ///
  387. /// Example usage:
  388. /// \code
  389. /// /*******************************************************/
  390. /// AkRadiusList RadLst; //creating the list( array ).
  391. /// // Do not reserve any size for the array,
  392. /// // the system will reserve the correct size.
  393. ///
  394. /// GetMaxRadius( RadLst );
  395. /// // Use the content of the list
  396. /// (...)
  397. ///
  398. /// RadLst.Term();// the user is responsible to free the memory allocated
  399. /// /*******************************************************/
  400. /// \endcode
  401. ///
  402. /// \aknote The returned value is NOT the distance from a listener to an object but
  403. /// the maximum attenuation distance of all sounds playing on this object. This is
  404. /// not related in any way to the curent 3D position of the object. \endaknote
  405. ///
  406. /// \return
  407. /// - AK_Success if succeeded
  408. /// - AK_InsuficientMemory if there was not enough memory
  409. ///
  410. /// \aknote
  411. /// The Scaling factor (if one was specified on the game object) is included in the return value.
  412. /// The Scaling factor is not updated once a sound starts playing since it
  413. /// is computed only when the playback starts with the initial scaling factor of this game object. Scaling factor will
  414. /// be re-computed for every playback instance, always using the scaling factor available at this time.
  415. /// \endaknote
  416. ///
  417. /// \sa
  418. /// - AkRadiusList
  419. AK_EXTERNAPIFUNC( AKRESULT, GetMaxRadius )(
  420. AkRadiusList & io_RadiusList ///< List that will be filled with AK::SoundEngine::Query::GameObjDst objects.
  421. );
  422. /// Returns the maximum distance used in attenuations associated to sounds playing using the specified game object.
  423. /// 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
  424. /// if the object is out of reach anyway.
  425. ///
  426. /// \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
  427. ///
  428. /// \return
  429. /// - A negative number if the game object specified is not playing.
  430. /// - 0, if the game object was only associated to sounds playing using no distance attenuation.
  431. /// - A positive number represents the maximum of all the distance attenuations playing on this game object.
  432. ///
  433. /// \aknote
  434. /// The Scaling factor (if one was specified on the game object) is included in the return value.
  435. /// The Scaling factor is not updated once a sound starts playing since it
  436. /// is computed only when the playback starts with the initial scaling factor of this game object. Scaling factor will
  437. /// be re-computed for every playback instance, always using the scaling factor available at this time.
  438. /// \endaknote
  439. ///
  440. /// \sa
  441. /// - \ref AK::SoundEngine::SetScalingFactor
  442. AK_EXTERNAPIFUNC( AkReal32, GetMaxRadius )(
  443. AkGameObjectID in_GameObjId ///< Game object ID
  444. );
  445. /// Get the Event ID associated to the specified PlayingID.
  446. /// This function does not acquire the main audio lock.
  447. ///
  448. /// \return AK_INVALID_UNIQUE_ID on failure.
  449. AK_EXTERNAPIFUNC( AkUniqueID, GetEventIDFromPlayingID )(
  450. AkPlayingID in_playingID ///< Associated PlayingID
  451. );
  452. /// Get the ObjectID associated to the specified PlayingID.
  453. /// This function does not acquire the main audio lock.
  454. ///
  455. /// \return AK_INVALID_GAME_OBJECT on failure.
  456. AK_EXTERNAPIFUNC( AkGameObjectID, GetGameObjectFromPlayingID )(
  457. AkPlayingID in_playingID ///< Associated PlayingID
  458. );
  459. /// Get the list PlayingIDs associated with the given game object.
  460. /// This function does not acquire the main audio lock.
  461. ///
  462. /// \aknote It is possible to call GetPlayingIDsFromGameObject with io_ruNumItems = 0 to get the total size of the
  463. /// structure that should be allocated for out_aPlayingIDs. \endaknote
  464. /// \return AK_Success if succeeded, AK_InvalidParameter if out_aPlayingIDs is NULL while io_ruNumItems > 0
  465. AK_EXTERNAPIFUNC( AKRESULT, GetPlayingIDsFromGameObject )(
  466. AkGameObjectID in_GameObjId, ///< Game object ID
  467. AkUInt32& io_ruNumIDs, ///< Number of items in array provided / Number of items filled in array
  468. AkPlayingID* out_aPlayingIDs ///< Array of AkPlayingID items to fill
  469. );
  470. /// Get the value of a custom property of integer or boolean type.
  471. /// \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.
  472. AK_EXTERNAPIFUNC( AKRESULT, GetCustomPropertyValue )(
  473. 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.
  474. AkUInt32 in_uPropID, ///< Property ID of your custom property found under the Custom Properties tab of the Wwise project settings.
  475. AkInt32& out_iValue ///< Property Value
  476. );
  477. /// Get the value of a custom property of real type.
  478. /// \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.
  479. AK_EXTERNAPIFUNC( AKRESULT, GetCustomPropertyValue )(
  480. 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.
  481. AkUInt32 in_uPropID, ///< Property ID of your custom property found under the Custom Properties tab of the Wwise project settings.
  482. AkReal32& out_fValue ///< Property Value
  483. );
  484. } //namespace Query
  485. } //namespace SoundEngine
  486. } //namespace AK
  487. #endif // _AK_QUERYPARAMS_H_