Table of Contents

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