Table of Contents

Wwise SDK 2019.2.3
IAkPlugin.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 /// \file
29 /// Software source plug-in and effect plug-in interfaces.
30 
31 #ifndef _IAK_PLUGIN_H_
32 #define _IAK_PLUGIN_H_
33 
34 #include <AK/SoundEngine/Common/AkCommonDefs.h>
35 #include <AK/SoundEngine/Common/IAkRTPCSubscriber.h>
36 #include <AK/SoundEngine/Common/IAkPluginMemAlloc.h>
37 #include <AK/SoundEngine/Common/AkFPUtilities.h>
38 #include <AK/Tools/Common/AkLock.h>
39 #include <AK/Tools/Common/AkPlatformFuncs.h>
40 #include <AK/Tools/Common/AkMonitorError.h>
41 #include <AK/SoundEngine/Common/AkSoundEngineExport.h>
42 #include <AK/SoundEngine/Common/IAkProcessorFeatures.h>
43 #include <AK/SoundEngine/Common/IAkPlatformContext.h>
44 #include <AK/SoundEngine/Common/AkMidiTypes.h>
45 #include <AK/SoundEngine/Common/AkCallback.h>
46 #include <AK/AkWwiseSDKVersion.h>
47 
48 #include <math.h>
49 
50 #if defined AK_CPU_X86 || defined AK_CPU_X86_64
51 #include <xmmintrin.h>
52 #endif
53 
54 /// Plug-in information structure.
55 /// \remarks The bIsInPlace field is only relevant for effect plug-ins.
56 /// \sa
57 /// - \ref iakeffect_geteffectinfo
58 struct AkPluginInfo
59 {
60  /// Constructor for default values
62  : eType(AkPluginTypeNone)
63  , uBuildVersion( 0 )
64  , bIsInPlace(true)
65  , bCanChangeRate(false)
66  , bReserved(false)
67  {}
68 
69  AkPluginType eType; ///< Plug-in type
70  AkUInt32 uBuildVersion; ///< Plugin build version, must match the AK_WWISESDK_VERSION_COMBINED macro from AkWwiseSDKVersion.h. Prevents usage of plugins compiled for other versions, avoiding crashes or data issues.
71  bool bIsInPlace; ///< Buffer usage (in-place or not)
72  bool bCanChangeRate; ///< True for effects whose sample throughput is different between input and output. Effects that can change rate need to be out-of-place (!bIsInPlace), and cannot exist on busses.
73  bool bReserved; ///< Legacy bIsAsynchronous plug-in flag, now unused. Preserved for plug-in backward compatibility. bReserved should be false for all plug-in.
74 };
75 
76 //Forward declarations.
77 namespace AK
78 {
79  class PluginRegistration;
80 }
81 extern "C" AK_DLLEXPORT AK::PluginRegistration * g_pAKPluginList;
82 
83 struct AkAcousticTexture;
84 
85 namespace AK
86 {
87  class IAkStreamMgr;
88  class IAkGlobalPluginContext;
89 
90  /// Game object information available to plugins.
92  {
93  protected:
94  /// Virtual destructor on interface to avoid warnings.
96 
97  public:
98 
99  /// Get the ID of the game object.
100  virtual AkGameObjectID GetGameObjectID() const = 0;
101 
102  /// Retrieve the number of emitter-listener pairs (rays) of the game object.
103  /// A game object may have more than one position, and be listened to more than one listener.
104  /// The returned value is the product of these two numbers. Use the returned value as a higher
105  /// bound for the index of GetEmitterListenerPair().
106  /// Note that rays whose listener is irrelevant to the current context are ignored. For example,
107  /// if the calling plug-in exists on a bus, only listeners that are routed to the end point's
108  /// device are considered.
109  /// \sa
110  /// - AK::SoundEngine::SetPosition()
111  /// - AK::SoundEngine::SetMultiplePositions()
112  /// - AK::SoundEngine::SetListeners()
113  /// - AK::IAkGameObjectPluginInfo::GetEmitterListenerPair()
114  virtual AkUInt32 GetNumEmitterListenerPairs() const = 0;
115 
116  /// Retrieve the emitter-listener pair (ray) of the game object at index in_uIndex.
117  /// Call GetNumEmitterListenerPairs() prior to this function to get the total number of
118  /// emitter-listener pairs of the game object.
119  /// The emitter-listener pair is expressed as the game object's position relative to the
120  /// listener, in spherical coordinates.
121  /// \note
122  /// - The distance takes game object and listener scaling factors into account.
123  /// - Returned distance and angles are those of the game object, and do not necessarily correspond
124  /// to any sound's positioning data.
125  /// \return AK_Fail if the index is invalid, AK_Success otherwise.
126  /// \sa
127  /// - AK::SoundEngine::SetScalingFactor()
128  /// - AK::IAkGameObjectPluginInfo::GetNumEmitterListenerPairs()
129  virtual AKRESULT GetEmitterListenerPair(
130  AkUInt32 in_uIndex, ///< Index of the pair, [0, GetNumEmitterListenerPairs()[
131  AkEmitterListenerPair & out_emitterListenerPair ///< Returned relative source position in spherical coordinates.
132  ) const = 0;
133 
134  /// Get the number of positions of the game object. Use this value to determine the indices to be
135  /// passed to GetGameObjectPosition().
136  /// \sa
137  /// - AK::SoundEngine::SetPosition()
138  /// - AK::SoundEngine::SetMultiplePositions()
139  /// - AK::IAkGameObjectPluginInfo::GetGameObjectPosition();
140  virtual AkUInt32 GetNumGameObjectPositions() const = 0;
141 
142  /// Get the raw position of the game object at index in_uIndex.
143  /// Use GetNumGameObjectPositions() prior to this function to get the total number of positions
144  /// of that game object.
145  /// \return AK_Fail if the index is out of bounds, AK_Success otherwise.
146  /// \sa
147  /// - AK::SoundEngine::SetPosition()
148  /// - AK::SoundEngine::SetMultiplePositions()
149  /// - AK::IAkGameObjectPluginInfo::GetNumGameObjectPositions()
150  virtual AKRESULT GetGameObjectPosition(
151  AkUInt32 in_uIndex, ///< Index of the position, [0, GetNumGameObjectPositions()[
152  AkSoundPosition & out_position ///< Returned raw position info.
153  ) const = 0;
154 
155  /// Get the multi-position type assigned to the game object.
156  /// \return MultiPositionType_MultiSources when the effect is instantiated on a bus.
157  /// \sa
158  /// - AK::SoundEngine::SetPosition()
159  /// - AK::SoundEngine::SetMultiplePositions()
161 
162  /// Get the distance scaling factor of the associated game object.
163  /// \sa
164  /// - AK::SoundEngine::SetScalingFactor()
165  virtual AkReal32 GetGameObjectScaling() const = 0;
166 
167  /// Get the game object IDs of listener game objects that are listening to the emitter game object.
168  /// Note that only listeners relevant to the current context are considered. For example,
169  /// if the calling plug-in exists on a bus, only listeners that are routed to the end point's
170  /// device are added to the returned array.
171  /// \return True if the call succeeded, false if all the listeners could not fit into the array,
172  /// \sa
173  /// - AK::SoundEngine::SetListeners()
174  virtual bool GetListeners(
175  AkGameObjectID* out_aListenerIDs, ///< Array of listener IDs to fill, or NULL to query the size needed.
176  AkUInt32& io_uSize ///< In: max size of the array, out: number of valid elements returned in out_aListenerIDs.
177  ) const = 0;
178 
179  /// Get information about a listener. Use GetListeners() prior to this function
180  /// in order to know which listeners are listening to the associated game object.
181  /// \return AK_Fail if the listener ID is invalid. AK_Success otherwise.
182  /// \sa
183  /// - AK::SoundEngine::SetListeners()
184  /// - AK::IAkGameObjectPluginInfo::GetListeners()
185  virtual AKRESULT GetListenerData(
186  AkGameObjectID in_uListener, ///< Bit field identifying the listener for which you desire information.
187  AkListener & out_listener ///< Returned listener info.
188  ) const = 0;
189  };
190 
191  /// Voice-specific information available to plug-ins. The associated game object's information is
192  /// available through the methods of the base class IAkGameObjectPluginInfo.
194  {
195  protected:
196  /// Virtual destructor on interface to avoid warnings.
198 
199  public:
200 
201  /// Retrieve the Playing ID of the event corresponding to this voice (if applicable).
202  virtual AkPlayingID GetPlayingID() const = 0;
203 
204  /// Get priority value associated to this voice. When priority voice is modified by distance, the minimum distance among emitter-listener pairs is used.
205  /// \return The priority between AK_MIN_PRIORITY and AK_MAX_PRIORITY inclusively.
206  virtual AkPriority GetPriority() const = 0;
207 
208  /// Get priority value associated to this voice, for a specified distance, which may differ from the minimum distance that is used by default.
209  /// \return The priority between AK_MIN_PRIORITY and AK_MAX_PRIORITY inclusively.
210  virtual AkPriority ComputePriorityWithDistance(
211  AkReal32 in_fDistance ///< Distance.
212  ) const = 0;
213  };
214 
215  /// Interface to retrieve contextual information available to all types of plugins.
217  {
218  protected:
219  /// Virtual destructor on interface to avoid warnings.
221 
222  public:
223 
224  /// \return The global sound engine context.
225  /// \sa IAkGlobalPluginContext
226  virtual IAkGlobalPluginContext* GlobalContext() const = 0;
227 
228  /// Obtain the interface to access the game object on which the plugin is instantiated.
229  /// \return The interface to GameObject info.
231 
232  /// Identify the output device into which the data processed by this plugin will end up.
233  /// Applicable to plug-ins instantiated as bus effects and to sink plugins.
234  /// Plug-ins instantiated in the Actor-Mixer hierarchy (i.e. on voices) return AK_NotCompatible.
235  /// \sa integrating_secondary_outputs
236  /// \return The device type and unique identifier. AK_Success if successful, AK_NotCompatible otherwise.
237  virtual AKRESULT GetOutputID(
238  AkUInt32 & out_uOutputID, ///< Device identifier, when multiple devices of the same type are possible.
239  AkPluginID & out_uDevicePlugin ///< Device plugin ID.
240  ) const = 0;
241 
242  /// Return the pointer and size of the plug-in media corresponding to the specified index.
243  /// The pointer returned will be NULL if the plug-in media is either not loaded or inexistant.
244  /// When this function is called and returns a valid data pointer, the data can only be used by this
245  /// instance of the plugin and is guaranteed to be valid only during the plug-in lifespan.
246  virtual void GetPluginMedia(
247  AkUInt32 in_dataIndex, ///< Index of the plug-in media to be returned.
248  AkUInt8* &out_rpData, ///< Pointer to the data
249  AkUInt32 &out_rDataSize ///< size of the data returned in bytes.
250  ) = 0;
251 
252  /// Return the pointer and size of the game data corresponding to the specified index, sent by the game using AK::SoundEngine::SendPluginCustomGameData().
253  /// The pointer returned will be NULL if the game data is inexistent.
254  /// When this function is called and returns a valid data pointer, the data can only be used by this
255  /// instance of the plugin and is guaranteed to be valid only during the frame.
256  virtual void GetPluginCustomGameData(
257  void* &out_rpData, ///< Pointer to the data
258  AkUInt32 &out_rDataSize ///< size of the data returned in bytes.
259  ) = 0;
260 
261  /// Post a custom blob of data to the UI counterpart of this effect plug-in.
262  /// Data is sent asynchronously through the profiling system.
263  /// Notes:
264  /// - It is only possible to post data when the instance of the plug-in is on a bus,
265  /// because there is a one-to-one relationship with its effect settings view.
266  /// You may call CanPostMonitorData() to determine if your plug-in can send data to the UI.
267  /// - Data is copied into the communication buffer within this method,
268  /// so you may discard it afterwards.
269  /// - You need to handle byte swapping on one side or the other when sending
270  /// data from a big-endian platform.
271  /// - Sending data to the UI is only possible in Debug and Profile. Thus, you should
272  /// enclose your calls to package and send that data within !AK_OPTIMIZED preprocessor flag.
273  /// \return AK_Success if the plug-in exists on a bus, AK_Fail otherwise.
274  virtual AKRESULT PostMonitorData(
275  void * in_pData, ///< Blob of data.
276  AkUInt32 in_uDataSize ///< Size of data.
277  ) = 0;
278 
279  /// Query the context to know if it is possible to send data to the UI counterpart of this effect plug-in.
280  /// It is only possible to post data when the instance of the plug-in is on a bus, because there is a
281  /// one-to-one relationship with its effect settings view.
282  /// \return True if the instance of the plug-in is on a bus, and the authoring tool is connected and
283  /// monitoring the game, false otherwise.
284  /// \sa PostMonitorData()
285  virtual bool CanPostMonitorData() = 0;
286 
287  /// Post a monitoring message or error string. This will be displayed in the Wwise capture
288  /// log.
289  /// \return AK_Success if successful, AK_Fail if there was a problem posting the message.
290  /// In optimized mode, this function returns AK_NotCompatible.
291  /// \remark This function is provided as a tracking tool only. It does nothing if it is
292  /// called in the optimized/release configuration and return AK_NotCompatible.
293  virtual AKRESULT PostMonitorMessage(
294  const char* in_pszError, ///< Message or error string to be displayed
295  AK::Monitor::ErrorLevel in_eErrorLevel ///< Specifies whether it should be displayed as a message or an error
296  ) = 0;
297 
298  /// Get the cumulative gain of all mixing stages, from the host audio node down to the device end point.
299  /// Returns 1.f when the node is an actor-mixer (voice), because a voice may be routed to several mix chains.
300  /// \return The cumulative downstream gain.
301  virtual AkReal32 GetDownstreamGain() = 0;
302 
303  /// Return the channel configuration of the parent node that this effect will mix into. GetParentChannelConfig() may be used to set the output configuration of an
304  /// out-of-place effect to avoid additional up/down mixing stages. Please note however that it is possible for out-of-place effects later in the chain to change
305  /// this configuration.
306  /// Returns not out_channelConfig.IsValid() when the node is an actor-mixer (voice), because a voice may be routed to several mix chains.
307  /// \return AK_Success if the channel config of the primary, direct parent bus could be determined, AK_Fail otherwise.
308  virtual AKRESULT GetParentChannelConfig(
309  AkChannelConfig& out_channelConfig ///< Channel configuration of parent node (downstream bus).
310  ) const = 0;
311 
312 #if (defined AK_CPU_X86 || defined AK_CPU_X86_64) && !(defined AK_IOS)
313  /// Return an interface to query processor specific features.
314  virtual IAkProcessorFeatures * GetProcessorFeatures() = 0;
315 #endif
316  };
317 
318  /// Interface to retrieve contextual information for an effect plug-in.
319  /// \sa
320  /// - \ref iakmonadiceffect_init
322  {
323  protected:
324  /// Virtual destructor on interface to avoid warnings.
326 
327  public:
328 
329  /// Determine whether the effect is to be used in Send Mode or not.
330  /// Effects used in auxiliary busses are always used in Send Mode.
331  /// \return True if the effect is in Send Mode, False otherwise
332  virtual bool IsSendModeEffect() const = 0;
333 
334  /// Obtain the interface to access the voice in which the plugin is inserted.
335  /// \return The interface to voice info. NULL if the plugin is instantiated on a bus.
336  virtual IAkVoicePluginInfo * GetVoiceInfo() = 0;
337 
338  /// Get internal ID of sound structure (sound object or bus) on which the plug-in is instantiated.
339  /// In the case of a voice, the ID is internal but corresponds to what you would get from the duration
340  /// callback (see AkDurationCallbackInfo::audioNodeID). In the case of a bus, it can be matched with the bus name converted
341  /// to a unique ID using AK::SoundEngine::GetIDFromString(). Returns AK_INVALID_UNIQUE_ID in the case of a sink/device.
342  /// \return ID of structure.
343  /// \sa
344  /// - AkDurationCallbackInfo
345  /// - AK::SoundEngine::PostEvent()
346  /// - AK::SoundEngine::GetIDFromString()
347  virtual AkUniqueID GetNodeID() const = 0;
348  };
349 
350  /// Interface to retrieve contextual information for a source plug-in.
351  /// \sa
352  /// - \ref iaksourceeffect_init
354  {
355  protected:
356  /// Virtual destructor on interface to avoid warnings.
358 
359  public:
360 
361  /// Retrieve the number of loops the source should produce.
362  /// \return The number of loop iterations the source should produce (0 if infinite looping)
363  virtual AkUInt16 GetNumLoops() const = 0;
364 
365  /// Obtain the interface to access the voice in which the plugin is inserted.
366  /// \return The interface to voice info.
367  virtual IAkVoicePluginInfo * GetVoiceInfo() = 0;
368 
369  /// Obtain the MIDI event info associated to the source.
370  /// \return The MIDI event info.
371  ///
372  virtual AkMIDIEvent GetMidiEvent() const = 0;
373 
374  /// Get internal ID of sound structure (sound object or bus) on which the plug-in is instantiated.
375  /// In the case of a voice, the ID is internal but corresponds to what you would get from the duration
376  /// callback (see AkDurationCallbackInfo::audioNodeID). In the case of a bus, it can be matched with the bus name converted
377  /// to a unique ID using AK::SoundEngine::GetIDFromString(). Returns AK_INVALID_UNIQUE_ID in the case of a sink/device.
378  /// \return ID of structure.
379  /// \sa
380  /// - AkDurationCallbackInfo
381  /// - AK::SoundEngine::PostEvent()
382  /// - AK::SoundEngine::GetIDFromString()
383  virtual AkUniqueID GetNodeID() const = 0;
384 
385  /// Retrieve Cookie information for a Source Plugin
386  /// \return the void pointer of the Cookie passed to the PostEvent
387  virtual void* GetCookie() const = 0;
388 
389  };
390 
391  /// Interface to retrieve contextual information for a mixer.
393  {
394  protected:
395  /// Virtual destructor on interface to avoid warnings.
397 
398  public:
399 
400  /// Get ID of bus on which the plugin is inserted. It can be matched with the bus name converted to a unique ID using AK::SoundEngine::GetIDFromString().
401  /// \return ID of bus.
402  /// \sa AK::SoundEngine::GetIDFromString()
403  virtual AkUniqueID GetBusID() = 0;
404 
405  /// DEPRECATED.
406  /// Get the type of the bus on which the mixer plugin is instantiated.
407  /// AkBusHierachyFlags is a bit field, indicating whether the bus is the master (top-level) bus or not,
408  /// and whether it is in the primary or secondary mixing graph.
409  /// \return The bus type.
410  virtual AkUInt32 GetBusType() = 0;
411 
412  /// Get speaker angles of the specified device.
413  /// The speaker angles are expressed as an array of loudspeaker pairs, in degrees, relative to azimuth ]0,180].
414  /// Supported loudspeaker setups are always symmetric; the center speaker is always in the middle and thus not specified by angles.
415  /// Angles must be set in ascending order.
416  /// You may call this function with io_pfSpeakerAngles set to NULL to get the expected number of angle values in io_uNumAngles,
417  /// in order to allocate your array correctly. You may also obtain this number by calling
418  /// AK::GetNumberOfAnglesForConfig( AK_SPEAKER_SETUP_DEFAULT_PLANE ).
419  /// If io_pfSpeakerAngles is not NULL, the array is filled with up to io_uNumAngles.
420  /// Typical usage:
421  /// - AkUInt32 uNumAngles;
422  /// - GetSpeakerAngles( NULL, uNumAngles );
423  /// - AkReal32 * pfSpeakerAngles = AkAlloca( uNumAngles * sizeof(AkReal32) );
424  /// - GetSpeakerAngles( pfSpeakerAngles, uNumAngles );
425  /// \warning Call this function only after the sound engine has been properly initialized.
426  /// \return AK_Success if the end point device is properly initialized, AK_Fail otherwise.
427  /// \sa AK::SoundEngine::GetSpeakerAngles()
428  virtual AKRESULT GetSpeakerAngles(
429  AkReal32 * io_pfSpeakerAngles, ///< Returned array of loudspeaker pair angles, in degrees relative to azimuth [0,180]. Pass NULL to get the required size of the array.
430  AkUInt32 & io_uNumAngles, ///< Returned number of angles in io_pfSpeakerAngles, which is the minimum between the value that you pass in, and the number of angles corresponding to the output configuration, or just the latter if io_pfSpeakerAngles is NULL.
431  AkReal32 & out_fHeightAngle ///< Elevation of the height layer, in degrees relative to the plane.
432  ) = 0;
433 
434  /// \name Services.
435  //@{
436 
437  /// Compute a direct speaker assignment volume matrix with proper downmixing rules between two channel configurations.
438  virtual AKRESULT ComputeSpeakerVolumesDirect(
439  AkChannelConfig in_inputConfig, ///< Channel configuration of the input.
440  AkChannelConfig in_outputConfig, ///< Channel configuration of the mixer output.
441  AkReal32 in_fCenterPerc, ///< Center percentage. Only applies to mono inputs with standard output configurations that have a center channel.
442  AK::SpeakerVolumes::MatrixPtr out_mxVolumes ///< Returned volumes matrix. Must be preallocated using AK::SpeakerVolumes::Matrix::GetRequiredSize() (see AK::SpeakerVolumes::Matrix services).
443  ) = 0;
444 
445  /// Compute a volume matrix given the position of the panner (Wwise 2D panner).
446  virtual AKRESULT ComputeSpeakerVolumesPanner(
447  const AkVector & in_position, ///< x,y,z panner position [-1,1]. Note that z has no effect at the moment.
448  AkReal32 in_fCenterPct, ///< Center percentage.
449  AkChannelConfig in_inputConfig, ///< Channel configuration of the input.
450  AkChannelConfig in_outputConfig, ///< Channel configuration of the mixer output.
451  AK::SpeakerVolumes::MatrixPtr out_mxVolumes ///< Returned volumes matrix. Must be preallocated using AK::SpeakerVolumes::Matrix::GetRequiredSize() (see AK::SpeakerVolumes::Matrix services).
452  ) = 0;
453 
454  /// Compute panning gains on the plane given an incidence angle and channel configuration.
455  /// \return AK_Success if successful, AK_Fail otherwise.
456  virtual AKRESULT ComputePlanarVBAPGains(
457  AkReal32 in_fAngle, ///< Incident angle, in radians [-pi,pi], where 0 is the azimuth (positive values are clockwise)
458  AkChannelConfig in_outputConfig, ///< Desired output configuration.
459  AkReal32 in_fCenterPerc, ///< Center percentage. Only applies to mono inputs to outputs that have no center.
460  AK::SpeakerVolumes::VectorPtr out_vVolumes ///< Returned volumes (see AK::SpeakerVolumes::Vector services). Must be allocated prior to calling this function with the size returned by AK::SpeakerVolumes::Vector::GetRequiredSize() for the desired configuration.
461  ) = 0;
462 
463  /// Initialize spherical VBAP
464  /// \return AK_Success if successful, AK_Fail otherwise.
465  virtual AKRESULT InitSphericalVBAP(
466  AK::IAkPluginMemAlloc* in_pAllocator, ///< Memory allocator
467  const AkSphericalCoord* in_SphericalPositions, ///< Array of points in spherical coordinate, representign the virtual position of each channels.
468  const AkUInt32 in_NbPoints, ///< Number of points in the position array
469  void *& out_pPannerData ///< Contains data relevant to the 3D panner that shoud be re-used accross plugin instances.
470  ) = 0;
471 
472  /// Compute panning gains on the plane given an incidence angle and channel configuration.
473  /// \return AK_Success if successful, AK_Fail otherwise.
474  virtual AKRESULT ComputeSphericalVBAPGains(
475  void* in_pPannerData, ///< Contains data relevant to the 3D panner that shoud be re-used accross plugin instances.
476  AkReal32 in_fAzimuth, ///< Incident angle, in radians [-pi,pi], where 0 is the azimuth (positive values are clockwise)
477  AkReal32 in_fElevation, ///< Incident angle, in radians [0,pi], where 0 is the elevation (positive values are clockwise)
478  AkUInt32 in_uNumChannels, ///< Number of output channels.
479  AK::SpeakerVolumes::VectorPtr out_vVolumes ///< Returned volumes (see AK::SpeakerVolumes::Vector services). Must be allocated prior to calling this function with the size returned by AK::SpeakerVolumes::Vector::GetRequiredSize() for the desired configuration.
480  ) = 0;
481 
482  /// Clear panner data obtained from InitSphericalVBAP().
483  /// \return AK_Success if successful, AK_Fail otherwise.
484  virtual AKRESULT TermSphericalVBAP(
485  AK::IAkPluginMemAlloc* in_pAllocator, ///< Memory allocator
486  void* in_pPannerData ///< Contains data relevant to the 3D panner that shoud be re-used accross plugin instances.
487  ) = 0;
488 
489  /// Compute standard 3D positioning.
490  /// \return AK_Success if successful.
491  /// \aknote The cartesian counterpart of Compute3DPositioning, that uses emitter and listener transforms, should be used instead of this function.
492  /// It is more complete and more efficient. \endaknote
493  virtual AKRESULT Compute3DPositioning(
494  AkReal32 in_fAngle, ///< Incident angle, in radians [-pi,pi], where 0 is the azimuth (positive values are clockwise).
495  AkReal32 in_fElevation, ///< Incident elevation angle, in radians [-pi/2,pi/2], where 0 is the horizon (positive values are above the horizon).
496  AkReal32 in_fSpread, ///< Spread ([0,100]).
497  AkReal32 in_fFocus, ///< Focus ([0,100]).
498  AkChannelConfig in_inputConfig, ///< Channel configuration of the input.
499  AkChannelMask in_uInputChanSel, ///< Mask of input channels selected for panning (excluded input channels don't contribute to the output).
500  AkChannelConfig in_outputConfig, ///< Desired output configuration.
501  AkReal32 in_fCenterPerc, ///< Center percentage. Only applies to mono inputs to outputs that have a center.
502  AK::SpeakerVolumes::MatrixPtr out_mxVolumes ///< Returned volumes matrix. Must be preallocated using AK::SpeakerVolumes::Matrix::GetRequiredSize() (see AK::SpeakerVolumes::Matrix services).
503  ) = 0;
504 
505  /// Compute standard 3D positioning.
506  /// \return AK_Success if successful.
507  /// \aknote This function is more complete and more efficient than the Compute3DPositioning service that uses spherical coordinates, and should be favored.\endaknote
508  virtual AKRESULT Compute3DPositioning(
509  const AkTransform & in_emitter, ///< Emitter transform.
510  const AkTransform & in_listener, ///< Listener transform.
511  AkReal32 in_fCenterPerc, ///< Center percentage. Only applies to mono inputs to outputs that have a center.
512  AkReal32 in_fSpread, ///< Spread.
513  AkReal32 in_fFocus, ///< Focus.
514  AkChannelConfig in_inputConfig, ///< Channel configuration of the input.
515  AkChannelMask in_uInputChanSel, ///< Mask of input channels selected for panning (excluded input channels don't contribute to the output).
516  AkChannelConfig in_outputConfig, ///< Desired output configuration.
517  AK::SpeakerVolumes::MatrixPtr out_mxVolumes ///< Returned volumes matrix. Must be preallocated using AK::SpeakerVolumes::Matrix::GetRequiredSize() (see AK::SpeakerVolumes::Matrix services).
518  ) = 0;
519 
520  //@}
521 
522  /// \name Metering.
523  //@{
524 
525  /// Set flags for controlling computation of metering values on the mix buffer.
526  /// Pass AK_NoMetering to disable metering.
527  /// \sa
528  /// - AK::IAkMetering
529  virtual void EnableMetering( AkMeteringFlags in_eFlags ) = 0;
530 
531  //@}
532  };
533 
534  /// Parameter node interface, managing access to an enclosed parameter structure.
535  /// \aknote The implementer of this interface should also expose a static creation function
536  /// that will return a new parameter node instance when required (see \ref se_plugins_overview). \endaknote
537  /// \sa
538  /// - \ref shared_parameter_interface
540  {
541  protected:
542  /// Virtual destructor on interface to avoid warnings.
543  virtual ~IAkPluginParam(){}
544 
545  public:
546  /// Create a duplicate of the parameter node instance in its current state.
547  /// \aknote The allocation of the new parameter node should be done through the AK_PLUGIN_NEW() macro. \endaknote
548  /// \return Pointer to a duplicated plug-in parameter node interface
549  /// \sa
550  /// - \ref iakeffectparam_clone
551  virtual IAkPluginParam * Clone(
552  IAkPluginMemAlloc * in_pAllocator ///< Interface to memory allocator to be used
553  ) = 0;
554 
555  /// Initialize the plug-in parameter node interface.
556  /// Initializes the internal parameter structure to default values or with the provided parameter
557  /// block if it is valid. \endaknote
558  /// \aknote If the provided parameter block is valid, use SetParamsBlock() to set all parameters at once. \endaknote
559  /// \return Possible return values are: AK_Success, AK_Fail, AK_InvalidParameter
560  /// \sa
561  /// - \ref iakeffectparam_init
562  virtual AKRESULT Init(
563  IAkPluginMemAlloc * in_pAllocator, ///< Interface to the memory allocator to be used
564  const void * in_pParamsBlock, ///< Pointer to a parameter structure block
565  AkUInt32 in_uBlockSize ///< Size of the parameter structure block
566  ) = 0;
567 
568  /// Called by the sound engine when a parameter node is terminated.
569  /// \aknote The self-destruction of the parameter node must be done using the AK_PLUGIN_DELETE() macro. \endaknote
570  /// \return AK_Success if successful, AK_Fail otherwise
571  /// \sa
572  /// - \ref iakeffectparam_term
573  virtual AKRESULT Term(
574  IAkPluginMemAlloc * in_pAllocator ///< Interface to memory allocator to be used
575  ) = 0;
576 
577  /// Set all plug-in parameters at once using a parameter block.
578  /// \return AK_Success if successful, AK_InvalidParameter otherwise
579  /// \sa
580  /// - \ref iakeffectparam_setparamsblock
581  virtual AKRESULT SetParamsBlock(
582  const void *in_pParamsBlock, ///< Pointer to a parameter structure block
583  AkUInt32 in_uBlockSize ///< Size of the parameter structure block
584  ) = 0;
585 
586  /// Update a single parameter at a time and perform the necessary actions on the parameter changes.
587  /// \aknote The parameter ID corresponds to the AudioEnginePropertyID in the plug-in XML description file. \endaknote
588  /// \return AK_Success if successful, AK_InvalidParameter otherwise
589  /// \sa
590  /// - \ref iakeffectparam_setparam
591  virtual AKRESULT SetParam(
592  AkPluginParamID in_paramID, ///< ID number of the parameter to set
593  const void * in_pValue, ///< Pointer to the value of the parameter to set
594  AkUInt32 in_uParamSize ///< Size of the value of the parameter to set
595  ) = 0;
596 
597  /// Use this constant with AK::Wwise::IPluginPropertySet::NotifyInternalDataChanged,
598  /// AK::Wwise::IAudioPlugin::GetPluginData and IAkPluginParam::SetParam. This tells
599  /// that the whole plugin data needs to be saved/transferred.
600  ///\sa
601  /// - AK::Wwise::IPluginPropertySet::NotifyInternalDataChanged
602  /// - AK::Wwise::IAudioPlugin::GetPluginData
603  /// - AK::IAkPluginParam::SetParam
604  static const AkPluginParamID ALL_PLUGIN_DATA_ID = 0x7FFF;
605  };
606 
607  /// Wwise sound engine plug-in interface. Shared functionality across different plug-in types.
608  /// \aknote The implementer of this interface should also expose a static creation function
609  /// that will return a new plug-in instance when required (see \ref soundengine_plugins). \endaknote
610  class IAkPlugin
611  {
612  protected:
613  /// Virtual destructor on interface to avoid warnings.
614  virtual ~IAkPlugin(){}
615 
616  public:
617  /// Release the resources upon termination of the plug-in.
618  /// \return AK_Success if successful, AK_Fail otherwise
619  /// \aknote The self-destruction of the plug-in must be done using AK_PLUGIN_DELETE() macro. \endaknote
620  /// \sa
621  /// - \ref iakeffect_term
622  virtual AKRESULT Term(
623  IAkPluginMemAlloc * in_pAllocator ///< Interface to memory allocator to be used by the plug-in
624  ) = 0;
625 
626  /// The reset action should perform any actions required to reinitialize the state of the plug-in
627  /// to its original state (e.g. after Init() or on effect bypass).
628  /// \return AK_Success if successful, AK_Fail otherwise.
629  /// \sa
630  /// - \ref iakeffect_reset
631  virtual AKRESULT Reset() = 0;
632 
633  /// Plug-in information query mechanism used when the sound engine requires information
634  /// about the plug-in to determine its behavior
635  /// \return AK_Success if successful.
636  /// \sa
637  /// - \ref iakeffect_geteffectinfo
638  virtual AKRESULT GetPluginInfo(
639  AkPluginInfo & out_rPluginInfo ///< Reference to the plug-in information structure to be retrieved
640  ) = 0;
641 
642  /// Some plug-ins are accessing Media from the Wwise sound bank system.
643  /// If the IAkPlugin object is not using media, this function will not be used and should simply return false.
644  /// If the IAkPlugin object is using media, the RelocateMedia feature can be optionally implemented.
645  /// To implement correctly the feature, the plugin must be able to "Hot swap" from a memory location to another one in a single blocking call (AK::IAkPlugin::RelocateMedia)
646  ///
647  /// \sa
648  /// - AK::IAkPlugin::RelocateMedia
649  virtual bool SupportMediaRelocation() const
650  {
651  return false;
652  }
653 
654  /// Some plug-ins are accessing Media from the Wwise sound bank system.
655  /// If the IAkPlugin object is not using media, this function will not be used.
656  /// If the IAkPlugin object is using media, the RelocateMedia feature can be optionally implemented.
657  /// When this function is being called, the IAkPlugin object must make the required changes to remove all
658  /// referenced from the old memory pointer (previously obtained by GetPluginMedia() (and offsets to) to not access anymore the content of the old memory data and start using the newly provided pointer instead.
659  /// The change must be done within the function RelocateMedia().
660  /// After this call, the memory space in in_pOldInMemoryData will be invalidated and cannot be used safely anymore.
661  ///
662  /// This function will not be called if SupportMediaRelocation returned false.
663  ///
664  /// \sa
665  /// - AK::IAkPlugin::SupportMediaRelocation
666  virtual AKRESULT RelocateMedia(
667  AkUInt8* /*in_pNewMedia*/,
668  AkUInt8* /*in_pOldMedia*/
669  )
670  {
671  return AK_NotImplemented;
672  }
673 
674  };
675 
676  /// Software effect plug-in interface (see \ref soundengine_plugins_effects).
677  class IAkEffectPlugin : public IAkPlugin
678  {
679  protected:
680  /// Virtual destructor on interface to avoid warnings.
681  virtual ~IAkEffectPlugin(){}
682 
683  public:
684  /// Software effect plug-in initialization. Prepares the effect for data processing, allocates memory and sets up the initial conditions.
685  /// \aknote Memory allocation should be done through appropriate macros (see \ref fx_memory_alloc). \endaknote
686  /// \sa
687  /// - \ref iakmonadiceffect_init
688  virtual AKRESULT Init(
689  IAkPluginMemAlloc * in_pAllocator, ///< Interface to memory allocator to be used by the effect
690  IAkEffectPluginContext * in_pEffectPluginContext, ///< Interface to effect plug-in's context
691  IAkPluginParam * in_pParams, ///< Interface to plug-in parameters
692  AkAudioFormat & io_rFormat ///< Audio data format of the input/output signal. Only an out-of-place plugin is allowed to change the channel configuration.
693  ) = 0;
694  };
695 
696  /// Software effect plug-in interface for in-place processing (see \ref soundengine_plugins_effects).
698  {
699  public:
700  /// Software effect plug-in DSP execution for in-place processing.
701  /// \aknote The effect should process all the input data (uValidFrames) as long as AK_DataReady is passed in the eState field.
702  /// When the input is finished (AK_NoMoreData), the effect can output more sample than uValidFrames up to MaxFrames() if desired.
703  /// All sample frames beyond uValidFrames are not initialized and it is the responsibility of the effect to do so when outputting an effect tail.
704  /// The effect must notify the pipeline by updating uValidFrames if more frames are produced during the effect tail.
705  /// \aknote The effect will stop being called by the pipeline when AK_NoMoreData is returned in the the eState field of the AkAudioBuffer structure.
706  /// See \ref iakmonadiceffect_execute_general.
707  virtual void Execute(
708  AkAudioBuffer * io_pBuffer ///< In/Out audio buffer data structure (in-place processing)
709  ) = 0;
710 
711  /// Skips execution of some frames, when the voice is virtual playing from elapsed time.
712  /// This can be used to simulate processing that would have taken place (e.g. update internal state).
713  /// Return AK_DataReady or AK_NoMoreData, depending if there would be audio output or not at that point.
714  virtual AKRESULT TimeSkip(
715  AkUInt32 in_uFrames ///< Number of frames the audio processing should advance.
716  ) = 0;
717  };
718 
719 
720  /// Software effect plug-in interface for out-of-place processing (see \ref soundengine_plugins_effects).
722  {
723  public:
724  /// Software effect plug-in for out-of-place processing.
725  /// \aknote An input buffer is provided and will be passed back to Execute() (with an advancing offset based on uValidFrames consumption by the plug-in).
726  /// The output buffer should be filled entirely by the effect (at which point it can report AK_DataReady) except on last execution where AK_NoMoreData should be used.
727  /// AK_DataNeeded should be used when more input data is necessary to continue processing.
728  /// \aknote Only the output buffer eState field is looked at by the pipeline to determine the effect state.
729  /// See \ref iakmonadiceffect_execute_outofplace.
730  virtual void Execute(
731  AkAudioBuffer * in_pBuffer, ///< Input audio buffer data structure
732  AkUInt32 in_uInOffset, ///< Offset position into input buffer data
733  AkAudioBuffer * out_pBuffer ///< Output audio buffer data structure
734  ) = 0;
735 
736  /// Skips execution of some frames, when the voice is virtual playing from elapsed time.
737  /// This can be used to simulate processing that would have taken place (e.g. update internal state).
738  /// Return AK_DataReady or AK_NoMoreData, depending if there would be audio output or not at that point.
739  virtual AKRESULT TimeSkip(
740  AkUInt32 &io_uFrames ///< Number of frames the audio processing should advance. The output value should be the number of frames that would be consumed to output the number of frames this parameter has at the input of the function.
741  ) = 0;
742  };
743 
744  /// Interface to retrieve information about an input of a mixer.
746  {
747  protected:
748  /// Virtual destructor on interface to avoid warnings.
750 
751  public:
752 
753  /// Obtain the parameter blob for the mixer plugin that were attached to this input.
754  /// \return The parameter blob, which can be safely cast into the plugin's implementation.
755  /// If all parameters are default value, NULL is returned. It is up to the plugin's implementation to know
756  /// what the default values are.
757  virtual IAkPluginParam * GetInputParam() = 0;
758 
759  /// Obtain the interface to access the voice info of this input.
760  /// \return The interface to voice info. NULL when the input is not a voice but the output of another bus instead.
761  virtual IAkVoicePluginInfo * GetVoiceInfo() = 0;
762 
763  /// Query the nature of the connection between this input and the mixer.
764  /// \return The connection type (direct/dry, user-defined auxiliary send, game-defined auxiliary send). Bus inputs are always "direct".
765  virtual AkConnectionType GetConnectionType() = 0;
766 
767  /// Get internal ID of sound associated to this input.
768  /// In the case of a voice, the ID is internal but corresponds to what you would get from the duration
769  /// callback (see AkDurationCallbackInfo::audioNodeID). In the case of a bus, it can be matched with the bus name converted
770  /// to a unique ID using AK::SoundEngine::GetIDFromString().
771  /// \return ID of input.
772  /// \sa
773  /// - AkDurationCallbackInfo
774  /// - AK::SoundEngine::PostEvent()
775  /// - AK::SoundEngine::GetIDFromString()
776  virtual AkUniqueID GetAudioNodeID() = 0;
777 
778  /// Use this method to retrieve user data to this context. It is always initialized to NULL until you decide to set it otherwise.
779  /// \return Attached user data.
780  /// \sa SetUserData()
781  virtual void * GetUserData() = 0;
782 
783  /// Use this method to attach user data to this context. It is always initialized to NULL until you decide to set it otherwise.
784  /// \return Attached user data.
785  /// \sa GetUserData()
786  virtual void SetUserData( void * in_pUserData ) = 0;
787 
788  /// \name Default positioning information.
789  /// \akwarning
790  /// The methods of this group are deprecated.
791  /// \endakwarning
792  //@{
793 
794  /// Retrieve center percentage of this input.
795  /// \return Center percentage, between 0 and 1.
796  virtual AkReal32 GetCenterPerc() = 0;
797 
798  /// Retrieve the speaker panning type: type of panning logic when object is not 3D spatialized.
799  /// Note that the returned value is only relevant when the object is not 3D spatialized,
800  /// that is Get3DSpatializationMode returns AK_SpatializationMode_None.
801  /// \sa
802  /// - Get3DSpatializationMode()
803  virtual AkSpeakerPanningType GetSpeakerPanningType() = 0;
804 
805  /// Speaker panning:
806  /// Retrieve the panner position (each vector component is between -1 and 1) of this input.
807  /// Note that the returned value is only relevant when the object is not 3D spatialized,
808  /// (Get3DSpatializationMode returns AK_SpatializationMode_None), and if speaker panning is not direct assignment
809  /// (GetSpeakerPanningType does not return AK_DirectSpeakerAssignment).
810  /// \sa
811  /// - GetSpeakerPanningType()
812  /// - Get3DSpatializationMode()
813  virtual void GetPannerPosition(
814  AkVector & out_position ///< Returned sound position.
815  ) = 0;
816 
817  /// Get the value of this input's Listener Relative Routing option, that is, if the emitter-listener relative
818  /// association is calculated at this node. Listener Relative Routing needs to be calculated in order for a node
819  /// to be spatialized or attenuated with respect to in-game emitter and listener positions. Otherwise it can only
820  /// be panned.
821  /// \sa
822  /// - Get3DSpatializationMode()
823  /// - Get3DPositionType()
824  /// - GetNum3DPositions()
825  virtual bool HasListenerRelativeRouting() = 0;
826 
827  /// Get whether the emitter position is defined by the game alone (AK_3DPositionType_Emitter), or if it is further automated
828  /// (AK_3DPositionType_EmitterWithAutomation, AK_3DPositionType_ListenerWithAutomation).
829  /// The resulting 3D position(s) may be obtained by Get3DPosition(), and used for 3D spatialization or attenuation.
830  /// \sa
831  /// - Get3DPosition()
832  /// - GetNum3DPositions()
833  /// - HasListenerRelativeRouting()
834  virtual Ak3DPositionType Get3DPositionType() = 0;
835 
836  /// 3D spatialization:
837  /// Retrieve the number of emitter-listener pairs (rays) of this input.
838  /// Note that the returned value is always 0 unless the input has listener relative routing (see HasListenerRelativeRouting()).
839  /// Use this function with Get3DPosition().
840  /// \sa
841  /// - Get3DPosition()
842  /// - HasListenerRelativeRouting()
843  virtual AkUInt32 GetNum3DPositions() = 0;
844 
845  /// 3D spatialization:
846  /// Retrieve the spherical coordinates of the desired emitter-listener pair (ray) corresponding to this
847  /// input, as automated by the engine. Applicable only when the input has listener relative routing (see HasListenerRelativeRouting()).
848  /// Returned rays are those that result from engine automation, if applicable.
849  /// \return AK_Success if the pair index is valid, AK_Fail otherwise.
850  /// \sa
851  /// - HasListenerRelativeRouting()
852  /// - GetNum3DPositions()
853  virtual AKRESULT Get3DPosition(
854  AkUInt32 in_uIndex, ///< Index of the pair, [0, GetNum3DPositions()[
855  AkEmitterListenerPair & out_soundPosition ///< Returned sound position, in spherical coordinates.
856  ) = 0;
857 
858  /// 3D spatialization:
859  /// Evaluate spread value at the distance of the desired emitter-listener pair for this input.
860  /// Applicable only when the input has listener relative routing (see HasListenerRelativeRouting()).
861  /// \return The spread value, between 0 and 100. 0 if the pair index is invalid.
862  /// \sa
863  /// - HasListenerRelativeRouting()
864  /// - GetNum3DPositions()
865  /// - Get3DPosition()
866  virtual AkReal32 GetSpread(
867  AkUInt32 in_uIndex ///< Index of the pair, [0, GetNum3DPositions()[
868  ) = 0;
869 
870  /// 3D spatialization:
871  /// Evaluate focus value at the distance of the desired emitter-listener pair for this input.
872  /// Applicable only when the input has listener relative routing (see HasListenerRelativeRouting()).
873  /// \return The focus value, between 0 and 100. 0 if the pair index is invalid.
874  /// \sa
875  /// - HasListenerRelativeRouting()
876  /// - GetNum3DPositions()
877  /// - Get3DPosition()
878  virtual AkReal32 GetFocus(
879  AkUInt32 in_uIndex ///< Index of the pair, [0, GetNum3DPositions()[
880  ) = 0;
881 
882  /// Get the max distance as defined in the attenuation editor.
883  /// Applicable only when the input has listener relative routing (see HasListenerRelativeRouting()).
884  /// \return True if this input has attenuation, false otherwise.
885  virtual bool GetMaxAttenuationDistance(
886  AkReal32 & out_fMaxAttenuationDistance ///< Returned max distance.
887  ) = 0;
888 
889  /// Get next volumes as computed by the sound engine for this input.
890  virtual void GetSpatializedVolumes(
891  AK::SpeakerVolumes::MatrixPtr out_mxPrevVolumes, ///< Returned in/out channel volume distribution corresponding to the beginning of the buffer. Must be preallocated (see AK::SpeakerVolumes::Matrix services).
892  AK::SpeakerVolumes::MatrixPtr out_mxNextVolumes ///< Returned in/out channel volume distribution corresponding to the end of the buffer. Must be preallocated (see AK::SpeakerVolumes::Matrix services).
893  ) = 0;
894 
895  /// Query the 3D spatialization mode used by this input.
896  /// Applicable only when the input has listener relative routing (see HasListenerRelativeRouting()).
897  /// \return The 3D spatialization mode (see Ak3DSpatializationMode). AK_SpatializationMode_None if not set, or if the input is not a node where the game object is evaluated against its listener.
898  /// \sa
899  /// - HasListenerRelativeRouting()
900  virtual Ak3DSpatializationMode Get3DSpatializationMode() = 0;
901 
902  //@}
903  };
904 
905  /// Interface to retrieve contextual information for a sink plugin.
906  /// \sa
907  /// - AK::IAkSinkPlugin
909  {
910  protected:
911  /// Virtual destructor on interface to avoid warnings.
913 
914  public:
915 
916  /// Query if the sink plugin is instantiated on the main output device (primary tree).
917  /// \return True if the sink plugin is instantiated on the main output device (primary tree), false otherwise.
918  /// \sa
919  /// - AK::IAkSinkPlugin::IsDataNeeded()
920  /// - AK::IAkSinkPlugin::Consume()
921  virtual bool IsPrimary() = 0;
922 
923  /// Sink plugins may need to call this function to notify the audio thread that it should wake up
924  /// in order to potentially process an audio frame. Note that the audio thread may wake up for other
925  /// reasons, for example following calls to AK::SoundEngine::RenderAudio().
926  /// Once the audio thread is awaken, it will ask the sink plugin how many audio frames need to be
927  /// processed and presented to the plugin. This is done through AK::IAkSinkPlugin::IsDataNeeded()
928  /// and AK::IAkSinkPlugin::Consume() respectively.
929  /// Note that only the sink plugin that is instantiated on the main output device (primary tree) may control
930  /// the audio thread synchronization.
931  /// \return AK_Success if the calling plugin is instantiated on the main output device (primary tree),
932  /// AK_Fail otherwise.
933  /// \sa
934  /// - AK::IAkSinkPluginContext::IsPrimary()
935  /// - AK::IAkSinkPlugin::IsDataNeeded()
936  /// - AK::IAkSinkPlugin::Consume()
937  virtual AKRESULT SignalAudioThread() = 0;
938 
939  /// Query engine's user-defined sink queue depth (AkPlatformInitSettings::uNumRefillsInVoice).
940  /// \return The engine's AkPlatformInitSettings::uNumRefillsInVoice value on platforms for which it exists, 0 otherwise.
941  virtual AkUInt16 GetNumRefillsInVoice() = 0;
942  };
943 
944  /// Software effect plug-in interface for sink (audio end point) plugins.
945  class IAkSinkPlugin : public IAkPlugin
946  {
947  protected:
948  /// Virtual destructor on interface to avoid warnings.
949  virtual ~IAkSinkPlugin(){}
950 
951  public:
952 
953  /// Initialization of the sink plugin.
954  ///
955  /// This method prepares the audio device plug-in for data processing, allocates memory, and sets up initial conditions.
956  /// The plug-in is passed in a pointer to a memory allocator interface (AK::IAkPluginMemAlloc).You should perform all dynamic memory allocation through this interface using the provided memory allocation macros(refer to \ref fx_memory_alloc).For the most common memory allocation needs, namely allocation at initialization and release at termination, the plug-in does not need to retain a pointer to the allocator.It will also be provided to the plug-in on termination.
957  /// The AK::IAkSinkPluginContext interface allows to retrieve information related to the context in which the audio device plug-in is operated.
958  /// The plug-in also receives a pointer to its associated parameter node interface (AK::IAkPluginParam).Most plug-ins will want to keep a reference to the associated parameter node to be able to retrieve parameters at runtime. Refer to \ref iakeffectparam_communication for more details.
959  /// All of these interfaces will remain valid throughout the plug-in's lifespan so it is safe to keep an internal reference to them when necessary.
960  /// Plug-ins also receive the output audio format(which stays the same during the lifespan of the plug-in) to be able to allocate memory and setup processing for a given channel configuration.
961  /// Note that the channel configuration is suggestive and may even be specified as not AkChannelConfig::IsValid().The plugin is free to determine the true channel configuration(this is an io parameter).
962  ///
963  /// \return AK_Success if successful.
964  /// \return AK_NotCompatible if the system doesn't support this sink type. Return this if you want to fall back to the default sinks. This sink will never be requested again. Do not return this code if the device is simply unplugged.
965  /// \return AK_DeviceNotCompatible if the requested output device doesn't support this sink type. Return this if you want to fall back to the dummy audio sink wich will result in no audio for the associated bus hierachy. This sink will never be requested again.
966  /// All other return codes will be treated as temporary failures conditions and the sink will be requested again later.
967 
968  virtual AKRESULT Init(
969  IAkPluginMemAlloc * in_pAllocator, ///< Interface to memory allocator to be used by the effect.
970  IAkSinkPluginContext * in_pSinkPluginContext, ///< Interface to sink plug-in's context.
971  IAkPluginParam * in_pParams, ///< Interface to plug-in parameters.
972  AkAudioFormat & io_rFormat ///< Audio data format of the input signal. Note that the channel configuration is suggestive and may even be specified as not AkChannelConfig::IsValid(). The plugin is free to determine the true channel configuration.
973  ) = 0;
974 
975  /// Obtain the number of audio frames that should be processed by the sound engine and presented
976  /// to this plugin via AK::IAkSinkPlugin::Consume(). The size of a frame is determined by the sound engine and
977  /// obtainable via AK::IAkPluginContextBase::GetMaxBufferLength().
978  /// \return AK_Success if successful, AK_Fail if there was a critical error.
979  /// \sa
980  /// - AK::IAkSinkPlugin::Consume()
981  /// - AK::IAkSinkPluginContext::SignalAudioThread()
982  virtual AKRESULT IsDataNeeded(
983  AkUInt32 & out_uNumFramesNeeded ///< Returned number of audio frames needed.
984  ) = 0;
985 
986  /// Present an audio buffer to the sink. The audio buffer is in the native format of the sound engine
987  /// (typically float, deinterleaved), as specified by io_rFormat passed to Init(). It is up to the
988  /// plugin to transform it into a format that is compatible with its output.
989  /// Note that Consume() is not called if the output for this frame consists of silence. Plugins should
990  /// detect this in OnFrameEnd().
991  /// \sa
992  /// - AK::IAkSinkPlugin::IsDataNeeded()
993  /// - AK::IAkSinkPlugin::OnFrameEnd()
994  virtual void Consume(
995  AkAudioBuffer * in_pInputBuffer, ///< Input audio buffer data structure. Plugins should avoid processing data in-place.
996  AkRamp in_gain ///< Volume gain to apply to this input (prev corresponds to the beginning, next corresponds to the end of the buffer).
997  ) = 0;
998 
999  /// Called at the end of the audio frame. If no Consume calls were made prior to OnFrameEnd, this means no audio was sent to the device. Assume silence.
1000  /// \sa
1001  /// - AK::IAkSinkPlugin::Consume()
1002  virtual void OnFrameEnd() = 0;
1003 
1004  /// Ask the plug-in whether starvation occurred.
1005  /// \return True if starvation occurred, false otherwise.
1006  virtual bool IsStarved() = 0;
1007 
1008  /// Reset the "starvation" flag after IsStarved() returned true.
1009  virtual void ResetStarved() = 0;
1010  };
1011 
1012  /// Wwise sound engine source plug-in interface (see \ref soundengine_plugins_source).
1013  class IAkSourcePlugin : public IAkPlugin
1014  {
1015  protected:
1016  /// Virtual destructor on interface to avoid warnings.
1017  virtual ~IAkSourcePlugin(){}
1018 
1019  public:
1020  /// Source plug-in initialization. Gets the plug-in ready for data processing, allocates memory and sets up the initial conditions.
1021  /// \aknote Memory allocation should be done through the appropriate macros (see \ref fx_memory_alloc). \endaknote
1022  /// \sa
1023  /// - \ref iaksourceeffect_init
1024  virtual AKRESULT Init(
1025  IAkPluginMemAlloc * in_pAllocator, ///< Interface to the memory allocator to be used by the plug-in
1026  IAkSourcePluginContext * in_pSourcePluginContext, ///< Interface to the source plug-in's context
1027  IAkPluginParam * in_pParams, ///< Interface to the plug-in parameters
1028  AkAudioFormat & io_rFormat ///< Audio format of the output data to be produced by the plug-in (mono native by default)
1029  ) = 0;
1030 
1031  /// This method is called to determine the approximate duration of the source.
1032  /// \return The duration of the source, in milliseconds.
1033  /// \sa
1034  /// - \ref iaksourceeffect_getduration
1035  virtual AkReal32 GetDuration() const = 0;
1036 
1037  /// This method is called to determine the estimated envelope of the source.
1038  /// \return The estimated envelope of the data that will be generated in the next call to
1039  /// Execute(). The envelope value should be normalized to the highest peak of the entire
1040  /// duration of the source. Expected range is [0,1]. If envelope and peak value cannot be
1041  /// predicted, the source should return 1 (no envelope).
1042  /// \sa
1043  /// - \ref iaksourceeffect_getenvelope
1044  virtual AkReal32 GetEnvelope() const
1045  {
1046  return 1.f;
1047  }
1048 
1049  /// This method is called to tell the source to stop looping.
1050  /// This will typically be called when an action of type "break" will be triggered on the playing source.
1051  /// Break (or StopLooping) means: terminate gracefully... if possible. In most situations it finishes the current loop and plays the sound release if there is one.
1052  ///
1053  /// \return
1054  /// - AK_Success if the source ignores the break command and plays normally till the end or if the source support to stop looping and terminates gracefully.
1055  /// - AK_Fail if the source cannot simply stop looping, in this situation, the break command will end up stopping this source.
1056  /// \sa
1057  /// - \ref iaksourceeffect_stoplooping
1058  virtual AKRESULT StopLooping(){ return AK_Success; }
1059 
1060  /// This method is called to tell the source to seek to an arbitrary sample.
1061  /// This will typically be called when the game calls AK::SoundEngine::SeekOnEvent() where the event plays
1062  /// a sound that wraps this source plug-in.
1063  /// If the plug-in does not handle seeks, it should return AK_Success. If it returns AK_Fail, it will
1064  /// be terminated by the sound engine.
1065  ///
1066  /// \return
1067  /// - AK_Success if the source handles or ignores seek command.
1068  /// - AK_Fail if the source considers that seeking requests should provoke termination, for example, if
1069  /// the desired position is greater than the prescribed source duration.
1070  /// \sa
1071  /// - AK::SoundEngine::SeekOnEvent()
1072  virtual AKRESULT Seek(
1073  AkUInt32 /* in_uPosition */ ///< Position to seek to, in samples, at the rate specified in AkAudioFormat (see AK::IAkSourcePlugin::Init()).
1074  ) { return AK_Success; }
1075 
1076  /// Skips execution when the voice is virtual playing from elapsed time to simulate processing that would have taken place (e.g. update internal state) while
1077  /// avoiding most of the CPU hit of plug-in execution.
1078  /// Given the number of frames requested adjust the number of frames that would have been produced by a call to Execute() in the io_uFrames parameter and return and
1079  /// return AK_DataReady or AK_NoMoreData, depending if there would be audio output or not at that point.
1080  /// Returning AK_NotImplemented will trigger a normal execution of the voice (as if it was not virtual) thus not enabling the CPU savings of a proper from elapsed time behavior.
1081  /// Note that returning AK_NotImplemeted for a source plug-ins that support asynchronous processing will produce a 'resume' virtual voice behavior instead.
1082  virtual AKRESULT TimeSkip(
1083  AkUInt32 & /*io_uFrames */ ///< (Input) Number of frames that the audio buffer processing can advance (equivalent to MaxFrames()). The output value should be the number of frames that would be produced this execution.
1084  ) { return AK_NotImplemented; }
1085 
1086  /// Software effect plug-in DSP execution.
1087  /// \aknote The effect can output as much as wanted up to MaxFrames(). All sample frames passed uValidFrames at input time are
1088  /// not initialized and it is the responsibility of the effect to do so. When modifying the number of valid frames within execution
1089  /// (e.g. to flush delay lines) the effect should notify the pipeline by updating uValidFrames accordingly.
1090  /// \aknote The effect will stop being called by the pipeline when AK_NoMoreData is returned in the the eState field of the AkAudioBuffer structure.
1091  virtual void Execute(
1092  AkAudioBuffer * io_pBuffer ///< In/Out audio buffer data structure (in-place processing)
1093  ) = 0;
1094  };
1095 
1096 
1097  /// This function can be useful to convert from normalized floating point audio samples to HW-pipeline format samples.
1098  #define AK_FLOAT_TO_SAMPLETYPE( __in__ ) (__in__)
1099  /// This function can be useful to convert from normalized floating point audio samples to HW-pipeline format samples when the input is not not to exceed (-1,1) range.
1100  #define AK_FLOAT_TO_SAMPLETYPE_NOCLIP( __in__ ) (__in__)
1101  /// This function can be useful to convert from HW-pipeline format samples to normalized floating point audio samples.
1102  #define AK_SAMPLETYPE_TO_FLOAT( __in__ ) (__in__)
1103 
1104  #define AK_DBTOLIN( __db__ ) (powf(10.f,(__db__) * 0.05f))
1105 }
1106 
1107 /// Registered plugin creation function prototype.
1108 AK_CALLBACK( AK::IAkPlugin*, AkCreatePluginCallback )( AK::IAkPluginMemAlloc * in_pAllocator );
1109 /// Registered plugin parameter node creation function prototype.
1110 AK_CALLBACK( AK::IAkPluginParam*, AkCreateParamCallback )( AK::IAkPluginMemAlloc * in_pAllocator );
1111 /// Registered plugin device enumeration function prototype
1112 AK_CALLBACK( AKRESULT, AkGetDeviceListCallback)(
1113  AkUInt32& io_maxNumDevices, ///< In: The maximum number of devices to read. Must match the memory allocated for AkDeviceDescription. Out: Returns the number of devices. Pass out_deviceDescriptions as NULL to have an idea of how many devices to expect.
1114  AkDeviceDescription* out_deviceDescriptions ///< The output array of device descriptions, one per device. Must be preallocated by the user with a size of at least io_maxNumDevices*sizeof(AkDeviceDescription).
1115  );
1116 
1117 struct AkPlatformInitSettings;
1118 struct AkInitSettings;
1119 
1120 namespace AK
1121 {
1122  /// Global plugin context used for plugin registration/initialization. Games query this interface from the sound engine.
1124  {
1125  protected:
1126  /// Virtual destructor on interface to avoid warnings.
1128 
1129  public:
1130 
1131  /// Retrieve the streaming manager access interface.
1132  virtual IAkStreamMgr * GetStreamMgr() const = 0;
1133 
1134  /// Retrieve the maximum number of frames that Execute() will be called with for this effect.
1135  /// Can be used by the effect to make memory allocation at initialization based on this worst case scenario.
1136  /// \return Maximum number of frames.
1137  virtual AkUInt16 GetMaxBufferLength() const = 0;
1138 
1139  /// Query whether sound engine is in real-time or offline (faster than real-time) mode.
1140  /// \return true when sound engine is in offline mode, false otherwise.
1141  virtual bool IsRenderingOffline() const = 0;
1142 
1143  /// Retrieve the core sample rate of the engine. This sample rate applies to all effects except source plugins, which declare their own sample rate.
1144  /// \return Core sample rate.
1145  virtual AkUInt32 GetSampleRate() const = 0;
1146 
1147  /// Post a monitoring message or error string. This will be displayed in the Wwise capture
1148  /// log.
1149  /// \return AK_Success if successful, AK_Fail if there was a problem posting the message.
1150  /// In optimized mode, this function returns AK_NotCompatible.
1151  /// \remark This function is provided as a tracking tool only. It does nothing if it is
1152  /// called in the optimized/release configuration and return AK_NotCompatible.
1153  virtual AKRESULT PostMonitorMessage(
1154  const char* in_pszError, ///< Message or error string to be displayed
1155  AK::Monitor::ErrorLevel in_eErrorLevel ///< Specifies whether it should be displayed as a message or an error
1156  ) = 0;
1157 
1158  /// Register a plug-in with the sound engine and set the callback functions to create the
1159  /// plug-in and its parameter node.
1160  /// \sa
1161  /// - \ref register_effects
1162  /// - \ref plugin_xml
1163  /// \return AK_Success if successful, AK_InvalidParameter if invalid parameters were provided or Ak_Fail otherwise. Possible reasons for an AK_Fail result are:
1164  /// - Insufficient memory to register the plug-in
1165  /// - Plug-in ID already registered
1166  /// \remarks
1167  /// Codecs and plug-ins must be registered before loading banks that use them.\n
1168  /// Loading a bank referencing an unregistered plug-in or codec will result in a load bank success,
1169  /// but the plug-ins will not be used. More specifically, playing a sound that uses an unregistered effect plug-in
1170  /// will result in audio playback without applying the said effect. If an unregistered source plug-in is used by an event's audio objects,
1171  /// posting the event will fail.
1172  virtual AKRESULT RegisterPlugin(
1173  AkPluginType in_eType, ///< Plug-in type (for example, source or effect)
1174  AkUInt32 in_ulCompanyID, ///< Company identifier (as declared in the plug-in description XML file)
1175  AkUInt32 in_ulPluginID, ///< Plug-in identifier (as declared in the plug-in description XML file)
1176  AkCreatePluginCallback in_pCreateFunc, ///< Pointer to the plug-in's creation function
1177  AkCreateParamCallback in_pCreateParamFunc ///< Pointer to the plug-in's parameter node creation function
1178  ) = 0;
1179 
1180  /// Register a codec type with the sound engine and set the callback functions to create the
1181  /// codec's file source and bank source nodes.
1182  /// \sa
1183  /// - \ref register_effects
1184  /// \return AK_Success if successful, AK_InvalidParameter if invalid parameters were provided, or Ak_Fail otherwise. Possible reasons for an AK_Fail result are:
1185  /// - Insufficient memory to register the codec
1186  /// - Codec ID already registered
1187  /// \remarks
1188  /// Codecs and plug-ins must be registered before loading banks that use them.\n
1189  /// Loading a bank referencing an unregistered plug-in or codec will result in a load bank success,
1190  /// but the plug-ins will not be used. More specifically, playing a sound that uses an unregistered effect plug-in
1191  /// will result in audio playback without applying the said effect. If an unregistered source plug-in is used by an event's audio objects,
1192  /// posting the event will fail.
1193  virtual AKRESULT RegisterCodec(
1194  AkUInt32 in_ulCompanyID, ///< Company identifier (as declared in XML)
1195  AkUInt32 in_ulPluginID, ///< Plugin identifier (as declared in XML)
1196  AkCreateFileSourceCallback in_pFileCreateFunc, ///< Factory for streaming sources.
1197  AkCreateBankSourceCallback in_pBankCreateFunc ///< Factory for in-memory sources.
1198  ) = 0;
1199 
1200  /// Register a global callback function. This function will be called from the audio rendering thread, at the
1201  /// location specified by in_eLocation. This function will also be called from the thread calling
1202  /// AK::SoundEngine::Term with in_eLocation set to AkGlobalCallbackLocation_Term.
1203  /// For example, in order to be called at every audio rendering pass, and once during teardown for releasing resources, you would call
1204  /// RegisterGlobalCallback(AkPluginTypeEffect, MY_COMPANY_ID , MY_PLUGIN_ID, myCallback, AkGlobalCallbackLocation_BeginRender | AkGlobalCallbackLocation_Term, myCookie);
1205  /// \remarks
1206  /// A valid (not AkPluginTypeNone) Plugin Type, Company ID and valid (non-zero) Plug-in ID of the plug-in registering the callback must be provided to this function.
1207  /// The timing of the callback function will contribute to the timing of the plug-in registered (Total Plug-in CPU and Advanced Profiler Plug-in tab).
1208  /// Timers will be registered to callbacks at all locations except for AkGlobalCallbackLocation_Register and AkGlobalCallbackLocation_Term.
1209  /// It is illegal to call this function while already inside of a global callback.
1210  /// This function might stall for several milliseconds before returning.
1211  /// \sa
1212  /// - AK::IAkGlobalPluginContext::UnregisterGlobalCallback()
1213  /// - AkGlobalCallbackFunc
1214  /// - AkGlobalCallbackLocation
1215  virtual AKRESULT RegisterGlobalCallback(
1216  AkPluginType in_eType, ///< A valid Plug-in type (for example, source or effect).
1217  AkUInt32 in_ulCompanyID, ///< Company identifier (as declared in the plug-in description XML file).
1218  AkUInt32 in_ulPluginID, ///< Plug-in identifier (as declared in the plug-in description XML file).
1219  AkGlobalCallbackFunc in_pCallback, ///< Function to register as a global callback.
1220  AkUInt32 in_eLocation = AkGlobalCallbackLocation_BeginRender, ///< Callback location defined in AkGlobalCallbackLocation. Bitwise OR multiple locations if needed.
1221  void * in_pCookie = NULL ///< User cookie.
1222  ) = 0;
1223 
1224  /// Unregister a global callback function, previously registered using RegisterGlobalCallback.
1225  /// \remarks
1226  /// It is legal to call this function while already inside of a global callback, If it is unregistering itself and not
1227  /// another callback.
1228  /// This function might stall for several milliseconds before returning.
1229  /// \sa
1230  /// - AK::IAkGlobalPluginContext::RegisterGlobalCallback()
1231  /// - AkGlobalCallbackFunc
1232  /// - AkGlobalCallbackLocation
1233  virtual AKRESULT UnregisterGlobalCallback(
1234  AkGlobalCallbackFunc in_pCallback, ///< Function to unregister as a global callback.
1235  AkUInt32 in_eLocation = AkGlobalCallbackLocation_BeginRender ///< Must match in_eLocation as passed to RegisterGlobalCallback for this callback.
1236  ) = 0;
1237 
1238  /// Get the default allocator for plugins. This is useful for performing global initialization tasks shared across multiple plugin instances.
1239  virtual AK::IAkPluginMemAlloc * GetAllocator() = 0;
1240 
1241  /// \sa SetRTPCValue
1242  virtual AKRESULT SetRTPCValue(
1243  AkRtpcID in_rtpcID, ///< ID of the game parameter
1244  AkRtpcValue in_value, ///< Value to set
1245  AkGameObjectID in_gameObjectID = AK_INVALID_GAME_OBJECT,///< Associated game object ID
1246  AkTimeMs in_uValueChangeDuration = 0, ///< Duration during which the game parameter is interpolated towards in_value
1247  AkCurveInterpolation in_eFadeCurve = AkCurveInterpolation_Linear, ///< Curve type to be used for the game parameter interpolation
1248  bool in_bBypassInternalValueInterpolation = false ///< True if you want to bypass the internal "slew rate" or "over time filtering" specified by the sound designer. This is meant to be used when for example loading a level and you dont want the values to interpolate.
1249  ) = 0;
1250 
1251  /// Send custom game data to a plugin that resides on a bus (insert effect or mixer plugin).
1252  /// Data will be copied and stored into a separate list.
1253  /// Previous entry is deleted when a new one is sent.
1254  /// Set the data pointer to NULL to clear item from the list.
1255  /// This means that you cannot send different data to various instances of the plugin on a same bus.\endaknote
1256  /// \return AK_Success if data was sent successfully.
1257  virtual AKRESULT SendPluginCustomGameData(
1258  AkUniqueID in_busID, ///< Bus ID
1259  AkGameObjectID in_busObjectID, ///< Bus Object ID
1260  AkPluginType in_eType, ///< Plug-in type (for example, source or effect)
1261  AkUInt32 in_uCompanyID, ///< Company identifier (as declared in the plug-in description XML file)
1262  AkUInt32 in_uPluginID, ///< Plug-in identifier (as declared in the plug-in description XML file)
1263  const void* in_pData, ///< The data blob
1264  AkUInt32 in_uSizeInBytes ///< Size of data
1265  ) = 0;
1266 
1267  /// N to N channels mix
1268  virtual void MixNinNChannels(
1269  AkAudioBuffer * in_pInputBuffer, ///< Input multichannel buffer.
1270  AkAudioBuffer * in_pMixBuffer, ///< Multichannel buffer with which the input buffer is mixed.
1271  AkReal32 in_fPrevGain, ///< Gain, corresponding to the beginning of the buffer, to apply uniformly to each mixed channel.
1272  AkReal32 in_fNextGain, ///< Gain, corresponding to the end of the buffer, to apply uniformly to each mixed channel.
1273  AK::SpeakerVolumes::ConstMatrixPtr in_mxPrevVolumes,///< In/out channel volume distribution corresponding to the beginning of the buffer (see AK::SpeakerVolumes::Matrix services).
1274  AK::SpeakerVolumes::ConstMatrixPtr in_mxNextVolumes ///< In/out channel volume distribution corresponding to the end of the buffer (see AK::SpeakerVolumes::Matrix services).
1275  ) = 0;
1276 
1277  /// 1 to N channels mix
1278  virtual void Mix1inNChannels(
1279  AkReal32 * AK_RESTRICT in_pInChannel, ///< Input channel buffer.
1280  AkAudioBuffer * in_pMixBuffer, ///< Multichannel buffer with which the input buffer is mixed.
1281  AkReal32 in_fPrevGain, ///< Gain, corresponding to the beginning of the input channel.
1282  AkReal32 in_fNextGain, ///< Gain, corresponding to the end of the input channel.
1283  AK::SpeakerVolumes::ConstVectorPtr in_vPrevVolumes, ///< Output channel volume distribution corresponding to the beginning of the buffer (see AK::SpeakerVolumes::Vector services).
1284  AK::SpeakerVolumes::ConstVectorPtr in_vNextVolumes ///< Output channel volume distribution corresponding to the end of the buffer (see AK::SpeakerVolumes::Vector services).
1285  ) = 0;
1286 
1287  /// Single channel mix
1288  virtual void MixChannel(
1289  AkReal32 * AK_RESTRICT in_pInBuffer, ///< Input channel buffer.
1290  AkReal32 * AK_RESTRICT in_pOutBuffer, ///< Output channel buffer.
1291  AkReal32 in_fPrevGain, ///< Gain, corresponding to the beginning of the input channel.
1292  AkReal32 in_fNextGain, ///< Gain, corresponding to the end of the input channel.
1293  AkUInt16 in_uNumFrames ///< Number of frames to mix.
1294  ) = 0;
1295 
1296  /// Computes gain vector for encoding a source with angles in_fAzimuth and in_fElevation to full-sphere ambisonics with order in_uOrder.
1297  /// Ambisonic channels are ordered by ACN and use the SN3D convention.
1298  virtual void ComputeAmbisonicsEncoding(
1299  AkReal32 in_fAzimuth, ///< Incident angle, in radians [-pi,pi], where 0 is the front (positive values are clockwise).
1300  AkReal32 in_fElevation, ///< Incident angle, in radians [-pi/2,pi/2], where 0 is the azimuthal plane.
1301  AkChannelConfig in_cfgAmbisonics, ///< Determines number of gains in vector out_vVolumes.
1302  AK::SpeakerVolumes::VectorPtr out_vVolumes ///< Returned volumes (see AK::SpeakerVolumes::Vector services). Must be allocated prior to calling this function with the size returned by AK::SpeakerVolumes::Vector::GetRequiredSize() for the desired number of channels.
1303  ) = 0;
1304 
1305  /// Computes gain matrix for decoding an SN3D-normalized ACN-ordered ambisonic signal of order sqrt(in_cfgAmbisonics.uNumChannels)-1, with max-RE weighting function, on a (regularly) sampled sphere whose samples in_samples are
1306  /// expressed in left-handed cartesian coordinates, with unitary norm.
1307  /// This decoding technique is optimal for regular sampling.
1308  /// The returned matrix has in_cfgAmbisonics.uNumChannels inputs (rows) and in_uNumSamples outputs (columns), and is normalized by the number of samples.
1309  /// Supported ambisonic configurations are full-sphere 1st to 5th order.
1310  /// \return AK_Fail when ambisonic configuration. AK_Success otherwise.
1312  const AkVector in_samples[], ///< Array of vector samples expressed in left-handed cartesian coordinates, where (1,0,0) points towards the right and (0,1,0) points towards the top. Vectors must be normalized.
1313  AkUInt32 in_uNumSamples, ///< Number of points in in_samples.
1314  AkChannelConfig in_cfgAmbisonics, ///< Ambisonic configuration. Supported configurations are 1st to 5th order. Determines number of rows (input channels) in matrix out_mxVolume.
1315  AK::SpeakerVolumes::MatrixPtr out_mxVolume ///< Returned volume matrix of in_cfgAmbisonics.uNumChannels rows x in_uNumSamples colums. Must be allocated prior to calling this function with the size returned by AK::SpeakerVolumes::Matrix::GetRequiredSize() for the desired number of channels.
1316  ) = 0;
1317 
1318  /// Return an acoustic texture.
1319  /// \return The pointer to an acoustic texture if successful, NULL otherwise.
1320  virtual const AkAcousticTexture* GetAcousticTexture(
1321  AkAcousticTextureID in_AcousticTextureID ///< Acoustic Texture's ID
1322  ) = 0;
1323 
1324  /// Given an emitter-listener pair, compute the azimuth and elevation angles of the emitter relative to the listener.
1325  /// \return AK_Success if the listener referenced in the emitter-listener pair was found; azimuth and elevation.
1326  virtual AKRESULT ComputeSphericalCoordinates(
1327  const AkEmitterListenerPair & in_pair, ///< Emitter-listener pair for which to compute azimuth and elevation angles.
1328  AkReal32 & out_fAzimuth, ///< Returned azimuthal angle, in radians.
1329  AkReal32 & out_fElevation ///< Returned elevation angle, in radians.
1330  ) const = 0;
1331 
1332  /// Get the platform init settings that the wwise sound engine has been initialized with.
1333  /// This function returns a null pointer if called with an instance of RenderFXGlobalContext.
1334  virtual const AkPlatformInitSettings* GetPlatformInitSettings() const = 0;
1335 
1336  /// Get the init settings that the wwise sound engine has been initialized with
1337  /// This function returns a null pointer if called with an instance of RenderFXGlobalContext.
1338  virtual const AkInitSettings* GetInitSettings() const = 0;
1339 
1340  /// Gets the configured audio settings.
1341  /// Call this function to get the configured audio settings.
1342  ///
1343  /// \warning This function is not thread-safe.
1344  /// \warning Call this function only after the sound engine has been properly initialized.
1345  virtual AKRESULT GetAudioSettings(
1346  AkAudioSettings & out_audioSettings ///< Returned audio settings
1347  ) const = 0;
1348 
1349  /// Universal converter from string to ID for the sound engine.
1350  /// Calls AK::SoundEngine::GetIDFromString.
1351  /// \sa
1352  /// - <tt>AK::SoundEngine::GetIDFromString</tt>
1353  virtual AkUInt32 GetIDFromString(const char* in_pszString) const = 0;
1354 
1355  /// Synchronously posts an Event to the sound engine (by event ID).
1356  /// The callback function can be used to be noticed when markers are reached or when the event is finished.
1357  /// An array of wave file sources can be provided to resolve External Sources triggered by the event.
1358  /// \return The playing ID of the event launched, or AK_INVALID_PLAYING_ID if posting the event failed
1359  /// \remarks
1360  /// This function executes the actions contained in the event without going through the message queue.
1361  /// In order to do so it acquires the global Wwise sound engine lock. It should therefore only be called from one of the
1362  /// global engine hooks (see AK::IAkGlobalPluginContext::RegisterGlobalCallback).
1363  /// Use AK::IAkGlobalPluginContext::GetIDFromString() if you use event names (strings).
1364  /// \sa
1365  /// - <tt>AK::SoundEngine::PostEvent</tt>
1366  /// - <tt>AK::IAkGlobalPluginContext::RegisterGlobalCallback</tt>
1367  /// - <tt>AK::IAkGlobalPluginContext::GetIDFromString</tt>
1368  virtual AkPlayingID PostEventSync(
1369  AkUniqueID in_eventID, ///< Unique ID of the event
1370  AkGameObjectID in_gameObjectID, ///< Associated game object ID
1371  AkUInt32 in_uFlags = 0, ///< Bitmask: see \ref AkCallbackType
1372  AkCallbackFunc in_pfnCallback = NULL, ///< Callback function
1373  void * in_pCookie = NULL, ///< Callback cookie that will be sent to the callback function along with additional information
1374  AkUInt32 in_cExternals = 0, ///< Optional count of external source structures
1375  AkExternalSourceInfo *in_pExternalSources = NULL,///< Optional array of external source resolution information
1376  AkPlayingID in_PlayingID = AK_INVALID_PLAYING_ID///< Optional (advanced users only) Specify the playing ID to target with the event. Will Cause active actions in this event to target an existing Playing ID. Let it be AK_INVALID_PLAYING_ID or do not specify any for normal playback.
1377  ) = 0;
1378 
1379  /// Executes a number of MIDI Events on all nodes that are referenced in the specified Event in an Action of type Play.
1380  /// Each MIDI event will be posted in AkMIDIPost::uOffset samples from the start of the current frame. The duration of
1381  /// a sample can be determined from the sound engine's audio settings, via a call to AK::IAkGlobalPluginContext::GetAudioSettings.
1382  /// \remarks
1383  /// This function executes the MIDI Events without going through the message queue.
1384  /// In order to do so it acquires the global Wwise sound engine lock. It should therefore only be called from one of the
1385  /// global engine hooks (see AK::IAkGlobalPluginContext::RegisterGlobalCallback).
1386  /// Use AK::IAkGlobalPluginContext::GetIDFromString() if you use event names (strings).
1387  /// \sa
1388  /// - <tt>AK::SoundEngine::PostMIDIOnEvent</tt>
1389  /// - <tt>AK::IAkGlobalPluginContext::GetAudioSettings</tt>
1390  /// - <tt>AK::IAkGlobalPluginContext::StopMIDIOnEventSync</tt>
1391  /// - <tt>AK::IAkGlobalPluginContext::RegisterGlobalCallback</tt>
1392  /// - <tt>AK::IAkGlobalPluginContext::GetIDFromString</tt>
1393  virtual AKRESULT PostMIDIOnEventSync(
1394  AkUniqueID in_eventID, ///< Unique ID of the Event
1395  AkGameObjectID in_gameObjectID, ///< Associated game object ID
1396  AkMIDIPost* in_pPosts, ///< MIDI Events to post
1397  AkUInt16 in_uNumPosts ///< Number of MIDI Events to post
1398  ) = 0;
1399 
1400  /// Stops MIDI notes on all nodes that are referenced in the specified event in an action of type play,
1401  /// with the specified Game Object. Invalid parameters are interpreted as wildcards. For example, calling
1402  /// this function with in_eventID set to AK_INVALID_UNIQUE_ID will stop all MIDI notes for Game Object
1403  /// in_gameObjectID.
1404  /// \remarks
1405  /// This function stops the MIDI notes without going through the message queue.
1406  /// In order to do so it acquires the global Wwise sound engine lock. It should therefore only be called from one of the
1407  /// global engine hooks (see AK::IAkGlobalPluginContext::RegisterGlobalCallback).
1408  /// Use AK::IAkGlobalPluginContext::GetIDFromString() if you use event names (strings).
1409  /// \sa
1410  /// - <tt>AK::IAkGlobalPluginContext::PostMIDIOnEvent</tt>
1411  /// - <tt>AK::IAkGlobalPluginContext::GetIDFromString</tt>
1412  virtual AKRESULT StopMIDIOnEventSync(
1413  AkUniqueID in_eventID = AK_INVALID_UNIQUE_ID, ///< Unique ID of the Event
1414  AkGameObjectID in_gameObjectID = AK_INVALID_GAME_OBJECT ///< Associated game object ID
1415  ) = 0;
1416 
1417  /// \return The gateway to platform-specific functionality
1418  /// \sa IAkPlatformContext
1419  virtual IAkPlatformContext * GetPlatformContext() const = 0;
1420 
1421  /// Given non-interleaved audio in the provided in_pInputBuffer, will apply a ramping gain over the number
1422  /// of frames specified, and store the result in in_pOutputBuffer. Channel data from in_pInputBuffer will also be
1423  /// interleaved in in_pOutputBuffer's results, and optionally converted from 32-bit floats to 16-bit integers.
1424  virtual void ApplyGainAndInterleave(
1425  AkAudioBuffer* in_pInputBuffer, ///< Input audioBuffer data
1426  AkAudioBuffer* in_pOutputBuffer, ///< Output audioBuffer data
1427  AkRamp in_gain, ///< Ramping gain to apply over duration of buffer
1428  bool in_convertToInt16 ///< Whether the input data should be converted to int16
1429  ) const = 0;
1430 
1431  /// Given non-interleaved audio in the provided in_pInputBuffer, will apply a ramping gain over the number
1432  /// of frames specified, and store the result in in_pOutputBuffer. Audio data in in_pOutputBuffer will have
1433  /// the same layout as in_pInputBuffer, and optionally converted from 32-bit floats to 16-bit integers.
1434  virtual void ApplyGain(
1435  AkAudioBuffer* in_pInputBuffer, ///< Input audioBuffer data
1436  AkAudioBuffer* in_pOutputBuffer, ///< Output audioBuffer data
1437  AkRamp in_gain, ///< Ramping gain to apply over duration of buffer
1438  bool in_convertToInt16 ///< Whether the input data should be converted to int16
1439  ) const = 0;
1440  };
1441 
1442  /// This class takes care of the registration of plug-ins in the Wwise engine. Plug-in developers must provide one instance of this class for each plug-in.
1443  /// \sa \ref soundengine_plugins
1445  {
1446  public:
1448  AkPluginType in_eType, ///< Plugin type.
1449  AkUInt32 in_ulCompanyID, ///< Plugin company ID.
1450  AkUInt32 in_ulPluginID, ///< Plugin ID.
1451  AkCreatePluginCallback in_pCreateFunc, ///< Plugin object factory.
1452  AkCreateParamCallback in_pCreateParamFunc, ///< Plugin parameter object factory.
1453  AkGlobalCallbackFunc in_pRegisterCallback = NULL, ///< Optional callback function called after successful plugin registration, with argument AkGlobalCallbackLocation_Register.
1454  void * in_pRegisterCallbackCookie = NULL ///< Optional cookie passed to register callback function above.
1455  )
1456  : pNext(g_pAKPluginList)
1457  , m_eType(in_eType)
1458  , m_ulCompanyID(in_ulCompanyID)
1459  , m_ulPluginID(in_ulPluginID)
1460  , m_pCreateFunc(in_pCreateFunc)
1461  , m_pCreateParamFunc(in_pCreateParamFunc)
1462  , m_pFileCreateFunc(NULL) // Legacy
1463  , m_pBankCreateFunc(NULL) // Legacy
1464  , m_pRegisterCallback(in_pRegisterCallback)
1465  , m_pRegisterCallbackCookie(in_pRegisterCallbackCookie)
1466  , m_pGetDeviceListFunc(NULL)
1467  , m_CodecDescriptor{ nullptr, nullptr, nullptr, nullptr }
1468  {
1469  g_pAKPluginList = this;
1470  }
1471 
1473  AkPluginType in_eType, ///< Plugin type.
1474  AkUInt32 in_ulCompanyID, ///< Plugin company ID.
1475  AkUInt32 in_ulPluginID, ///< Plugin ID.
1476  AkCreatePluginCallback in_pCreateFunc, ///< Plugin object factory.
1477  AkCreateParamCallback in_pCreateParamFunc, ///< Plugin parameter object factory.
1478  AkGetDeviceListCallback in_pGetDeviceListFunc, ///< Plugin parameter object factory.
1479  AkGlobalCallbackFunc in_pRegisterCallback = NULL, ///< Optional callback function called after successful plugin registration, with argument AkGlobalCallbackLocation_Register.
1480  void * in_pRegisterCallbackCookie = NULL ///< Optional cookie passed to register callback function above.
1481  )
1482  : pNext(g_pAKPluginList)
1483  , m_eType(in_eType)
1484  , m_ulCompanyID(in_ulCompanyID)
1485  , m_ulPluginID(in_ulPluginID)
1486  , m_pCreateFunc(in_pCreateFunc)
1487  , m_pCreateParamFunc(in_pCreateParamFunc)
1488  , m_pFileCreateFunc(NULL) // Legacy
1489  , m_pBankCreateFunc(NULL) // Legacy
1490  , m_pRegisterCallback(in_pRegisterCallback)
1491  , m_pRegisterCallbackCookie(in_pRegisterCallbackCookie)
1492  , m_pGetDeviceListFunc(in_pGetDeviceListFunc)
1493  , m_CodecDescriptor{ nullptr, nullptr, nullptr, nullptr }
1494  {
1495  g_pAKPluginList = this;
1496  }
1497 
1499  AkUInt32 in_ulCompanyID, ///< Plugin company ID.
1500  AkUInt32 in_ulPluginID, ///< Plugin ID.
1501  AkCreateFileSourceCallback in_pCreateFile, ///< Streamed source factory.
1502  AkCreateBankSourceCallback in_pCreateBank) ///< In-memory source factory.
1503  : pNext(g_pAKPluginList)
1504  , m_eType(AkPluginTypeCodec)
1505  , m_ulCompanyID(in_ulCompanyID)
1506  , m_ulPluginID(in_ulPluginID)
1507  , m_pCreateFunc(NULL)
1508  , m_pCreateParamFunc(NULL)
1509  , m_pFileCreateFunc(in_pCreateFile) // Legacy
1510  , m_pBankCreateFunc(in_pCreateBank) // Legacy
1511  , m_pRegisterCallback(NULL)
1513  , m_pGetDeviceListFunc(NULL)
1514  , m_CodecDescriptor{ in_pCreateFile, in_pCreateBank, nullptr, nullptr }
1515  {
1516  g_pAKPluginList = this;
1517  }
1518 
1520  AkUInt32 in_ulCompanyID, ///< Plugin company ID.
1521  AkUInt32 in_ulPluginID, ///< Plugin ID.
1522  const AkCodecDescriptor &in_Descriptor) ///< Codec descriptor.
1523  : pNext(g_pAKPluginList)
1524  , m_eType(AkPluginTypeCodec)
1525  , m_ulCompanyID(in_ulCompanyID)
1526  , m_ulPluginID(in_ulPluginID)
1527  , m_pCreateFunc(NULL)
1528  , m_pCreateParamFunc(NULL)
1529  , m_pFileCreateFunc(in_Descriptor.pFileSrcCreateFunc) // Legacy
1530  , m_pBankCreateFunc(in_Descriptor.pBankSrcCreateFunc) // Legacy
1531  , m_pRegisterCallback(NULL)
1533  , m_pGetDeviceListFunc(NULL)
1534  , m_CodecDescriptor(in_Descriptor)
1535  {
1536  g_pAKPluginList = this;
1537  }
1538 
1540  AkPluginType m_eType;
1541  AkUInt32 m_ulCompanyID;
1542  AkUInt32 m_ulPluginID;
1543  AkCreatePluginCallback m_pCreateFunc;
1544  AkCreateParamCallback m_pCreateParamFunc;
1545  AkCreateFileSourceCallback m_pFileCreateFunc; ///< LEGACY: Kept for compatibility with 2019.1. Unused in 2019.2 and up.
1546  AkCreateBankSourceCallback m_pBankCreateFunc; ///< LEGACY: Kept for compatibility with 2019.1. Unused in 2019.2 and up.
1547  AkGlobalCallbackFunc m_pRegisterCallback;
1549 
1550  // 2019.2 added parameters
1551  AkGetDeviceListCallback m_pGetDeviceListFunc;
1553  };
1554 }
1555 
1556 #define AK_IMPLEMENT_PLUGIN_FACTORY(_pluginName_, _plugintype_, _companyid_, _pluginid_) \
1557  AK::IAkPlugin* Create##_pluginName_(AK::IAkPluginMemAlloc * in_pAllocator); \
1558  AK::IAkPluginParam * Create##_pluginName_##Params(AK::IAkPluginMemAlloc * in_pAllocator); \
1559  AK::PluginRegistration _pluginName_##Registration(_plugintype_, _companyid_, _pluginid_, Create##_pluginName_, Create##_pluginName_##Params);
1560 
1561 #define AK_STATIC_LINK_PLUGIN(_pluginName_) \
1562  extern AK::PluginRegistration _pluginName_##Registration; \
1563  void *_pluginName_##_linkonceonly = (void*)&_pluginName_##Registration;
1564 
1565 #define DEFINE_PLUGIN_REGISTER_HOOK AK_DLLEXPORT AK::PluginRegistration * g_pAKPluginList = NULL;
1566 
1567 #define AK_GET_SINK_TYPE_FROM_DEVICE_KEY(_key) ((AkUInt32)(_key & 0xffffffff))
1568 #define AK_GET_DEVICE_ID_FROM_DEVICE_KEY(_key) ((AkUInt32)(_key >> 32))
1569 
1570 #endif // _IAK_PLUGIN_H_
virtual void Mix1inNChannels(AkReal32 *AK_RESTRICT in_pInChannel, AkAudioBuffer *in_pMixBuffer, AkReal32 in_fPrevGain, AkReal32 in_fNextGain, AK::SpeakerVolumes::ConstVectorPtr in_vPrevVolumes, AK::SpeakerVolumes::ConstVectorPtr in_vNextVolumes)=0
1 to N channels mix
virtual AKRESULT ComputeSpeakerVolumesPanner(const AkVector &in_position, AkReal32 in_fCenterPct, AkChannelConfig in_inputConfig, AkChannelConfig in_outputConfig, AK::SpeakerVolumes::MatrixPtr out_mxVolumes)=0
Compute a volume matrix given the position of the panner (Wwise 2D panner).
virtual IAkPluginParam * GetInputParam()=0
virtual AkUInt16 GetNumRefillsInVoice()=0
Interface to retrieve contextual information for a mixer.
Definition: IAkPlugin.h:392
MultiPositionType
Definition: AkTypes.h:727
virtual AKRESULT RegisterPlugin(AkPluginType in_eType, AkUInt32 in_ulCompanyID, AkUInt32 in_ulPluginID, AkCreatePluginCallback in_pCreateFunc, AkCreateParamCallback in_pCreateParamFunc)=0
AkCreateFileSourceCallback m_pFileCreateFunc
LEGACY: Kept for compatibility with 2019.1. Unused in 2019.2 and up.
Definition: IAkPlugin.h:1545
virtual AKRESULT SetRTPCValue(AkRtpcID in_rtpcID, AkRtpcValue in_value, AkGameObjectID in_gameObjectID=AK_INVALID_GAME_OBJECT, AkTimeMs in_uValueChangeDuration=0, AkCurveInterpolation in_eFadeCurve=AkCurveInterpolation_Linear, bool in_bBypassInternalValueInterpolation=false)=0
Audiokinetic namespace.
virtual ~IAkPluginParam()
Virtual destructor on interface to avoid warnings.
Definition: IAkPlugin.h:543
virtual AKRESULT TimeSkip(AkUInt32 in_uFrames)=0
virtual void * GetCookie() const =0
virtual AkPriority ComputePriorityWithDistance(AkReal32 in_fDistance) const =0
virtual IAkGlobalPluginContext * GlobalContext() const =0
virtual ~IAkGlobalPluginContext()
Virtual destructor on interface to avoid warnings.
Definition: IAkPlugin.h:1127
virtual AKRESULT Term(IAkPluginMemAlloc *in_pAllocator)=0
Software effect plug-in interface (see How to Create Wwise Sound Engine Effect Plug-ins).
Definition: IAkPlugin.h:677
virtual AKRESULT PostMonitorData(void *in_pData, AkUInt32 in_uDataSize)=0
virtual AKRESULT PostMIDIOnEventSync(AkUniqueID in_eventID, AkGameObjectID in_gameObjectID, AkMIDIPost *in_pPosts, AkUInt16 in_uNumPosts)=0
virtual AKRESULT Init(IAkPluginMemAlloc *in_pAllocator, IAkEffectPluginContext *in_pEffectPluginContext, IAkPluginParam *in_pParams, AkAudioFormat &io_rFormat)=0
Wwise sound engine source plug-in interface (see How to Create Wwise Sound Engine Source Plug-ins).
Definition: IAkPlugin.h:1013
virtual AkReal32 GetSpread(AkUInt32 in_uIndex)=0
virtual AkUniqueID GetNodeID() const =0
virtual AkUInt16 GetNumLoops() const =0
virtual void EnableMetering(AkMeteringFlags in_eFlags)=0
virtual ~IAkSinkPluginContext()
Virtual destructor on interface to avoid warnings.
Definition: IAkPlugin.h:912
virtual bool SupportMediaRelocation() const
Definition: IAkPlugin.h:649
AkCreateParamCallback m_pCreateParamFunc
Definition: IAkPlugin.h:1544
virtual AKRESULT SetParam(AkPluginParamID in_paramID, const void *in_pValue, AkUInt32 in_uParamSize)=0
virtual AkUInt32 GetSampleRate() const =0
virtual void GetPannerPosition(AkVector &out_position)=0
virtual AKRESULT SendPluginCustomGameData(AkUniqueID in_busID, AkGameObjectID in_busObjectID, AkPluginType in_eType, AkUInt32 in_uCompanyID, AkUInt32 in_uPluginID, const void *in_pData, AkUInt32 in_uSizeInBytes)=0
const typedef AkReal32 * ConstMatrixPtr
Constant volume matrix. Access each input channel vector with AK::SpeakerVolumes::Matrix::GetChannel(...
Definition: AkSpeakerVolumes.h:52
Interface to retrieve information about an input of a mixer.
Definition: IAkPlugin.h:745
virtual IAkVoicePluginInfo * GetVoiceInfo()=0
virtual void MixNinNChannels(AkAudioBuffer *in_pInputBuffer, AkAudioBuffer *in_pMixBuffer, AkReal32 in_fPrevGain, AkReal32 in_fNextGain, AK::SpeakerVolumes::ConstMatrixPtr in_mxPrevVolumes, AK::SpeakerVolumes::ConstMatrixPtr in_mxNextVolumes)=0
N to N channels mix.
virtual AKRESULT IsDataNeeded(AkUInt32 &out_uNumFramesNeeded)=0
bool bIsInPlace
Buffer usage (in-place or not)
Definition: IAkPlugin.h:71
virtual AkUInt32 GetIDFromString(const char *in_pszString) const =0
virtual AKRESULT ComputeWeightedAmbisonicsDecodingFromSampledSphere(const AkVector in_samples[], AkUInt32 in_uNumSamples, AkChannelConfig in_cfgAmbisonics, AK::SpeakerVolumes::MatrixPtr out_mxVolume)=0
AkCreatePluginCallback m_pCreateFunc
Definition: IAkPlugin.h:1543
virtual AkPriority GetPriority() const =0
virtual ~IAkGameObjectPluginInfo()
Virtual destructor on interface to avoid warnings.
Definition: IAkPlugin.h:95
virtual ~IAkPluginContextBase()
Virtual destructor on interface to avoid warnings.
Definition: IAkPlugin.h:220
PluginRegistration(AkUInt32 in_ulCompanyID, AkUInt32 in_ulPluginID, AkCreateFileSourceCallback in_pCreateFile, AkCreateBankSourceCallback in_pCreateBank)
Definition: IAkPlugin.h:1498
virtual AKRESULT ComputePlanarVBAPGains(AkReal32 in_fAngle, AkChannelConfig in_outputConfig, AkReal32 in_fCenterPerc, AK::SpeakerVolumes::VectorPtr out_vVolumes)=0
virtual void GetPluginMedia(AkUInt32 in_dataIndex, AkUInt8 *&out_rpData, AkUInt32 &out_rDataSize)=0
virtual void GetSpatializedVolumes(AK::SpeakerVolumes::MatrixPtr out_mxPrevVolumes, AK::SpeakerVolumes::MatrixPtr out_mxNextVolumes)=0
Get next volumes as computed by the sound engine for this input.
virtual AkUniqueID GetAudioNodeID()=0
virtual bool IsStarved()=0
virtual void Execute(AkAudioBuffer *io_pBuffer)=0
virtual AKRESULT StopMIDIOnEventSync(AkUniqueID in_eventID=AK_INVALID_UNIQUE_ID, AkGameObjectID in_gameObjectID=AK_INVALID_GAME_OBJECT)=0
PluginRegistration(AkPluginType in_eType, AkUInt32 in_ulCompanyID, AkUInt32 in_ulPluginID, AkCreatePluginCallback in_pCreateFunc, AkCreateParamCallback in_pCreateParamFunc, AkGlobalCallbackFunc in_pRegisterCallback=NULL, void *in_pRegisterCallbackCookie=NULL)
Definition: IAkPlugin.h:1447
PluginRegistration(AkPluginType in_eType, AkUInt32 in_ulCompanyID, AkUInt32 in_ulPluginID, AkCreatePluginCallback in_pCreateFunc, AkCreateParamCallback in_pCreateParamFunc, AkGetDeviceListCallback in_pGetDeviceListFunc, AkGlobalCallbackFunc in_pRegisterCallback=NULL, void *in_pRegisterCallbackCookie=NULL)
Definition: IAkPlugin.h:1472
virtual ~IAkMixerInputContext()
Virtual destructor on interface to avoid warnings.
Definition: IAkPlugin.h:749
virtual AkUInt16 GetMaxBufferLength() const =0
bool bCanChangeRate
True for effects whose sample throughput is different between input and output. Effects that can chan...
Definition: IAkPlugin.h:72
Emitter-listener pair: Positioning data pertaining to a single pair of emitter and listener.
Definition: AkTypes.h:474
virtual bool HasListenerRelativeRouting()=0
AkPluginInfo()
Constructor for default values.
Definition: IAkPlugin.h:61
virtual bool GetMaxAttenuationDistance(AkReal32 &out_fMaxAttenuationDistance)=0
virtual AKRESULT GetGameObjectPosition(AkUInt32 in_uIndex, AkSoundPosition &out_position) const =0
virtual AKRESULT GetPluginInfo(AkPluginInfo &out_rPluginInfo)=0
Software effect plug-in interface for sink (audio end point) plugins.
Definition: IAkPlugin.h:945
virtual void SetUserData(void *in_pUserData)=0
virtual bool IsSendModeEffect() const =0
virtual void OnFrameEnd()=0
virtual IAkVoicePluginInfo * GetVoiceInfo()=0
virtual AKRESULT PostMonitorMessage(const char *in_pszError, AK::Monitor::ErrorLevel in_eErrorLevel)=0
Software effect plug-in interface for out-of-place processing (see How to Create Wwise Sound Engine E...
Definition: IAkPlugin.h:721
virtual void ApplyGain(AkAudioBuffer *in_pInputBuffer, AkAudioBuffer *in_pOutputBuffer, AkRamp in_gain, bool in_convertToInt16) const =0
AkReal32 * VectorPtr
Volume vector. Access each element with the standard bracket [] operator.
Definition: AkSpeakerVolumes.h:49
virtual ~IAkMixerPluginContext()
Virtual destructor on interface to avoid warnings.
Definition: IAkPlugin.h:396
virtual Ak3DSpatializationMode Get3DSpatializationMode()=0
virtual AkPlayingID GetPlayingID() const =0
Retrieve the Playing ID of the event corresponding to this voice (if applicable).
virtual AkReal32 GetFocus(AkUInt32 in_uIndex)=0
Configured audio settings.
Definition: AkTypes.h:199
virtual AKRESULT SignalAudioThread()=0
virtual AkReal32 GetEnvelope() const
Definition: IAkPlugin.h:1044
virtual AKRESULT Init(IAkPluginMemAlloc *in_pAllocator, const void *in_pParamsBlock, AkUInt32 in_uBlockSize)=0
AkCodecDescriptor m_CodecDescriptor
Definition: IAkPlugin.h:1552
virtual bool CanPostMonitorData()=0
virtual AkSpeakerPanningType GetSpeakerPanningType()=0
virtual void Execute(AkAudioBuffer *in_pBuffer, AkUInt32 in_uInOffset, AkAudioBuffer *out_pBuffer)=0
virtual AkMIDIEvent GetMidiEvent() const =0
virtual AkUInt32 GetNum3DPositions()=0
AkPluginType eType
Plug-in type.
Definition: IAkPlugin.h:69
virtual ~IAkVoicePluginInfo()
Virtual destructor on interface to avoid warnings.
Definition: IAkPlugin.h:197
Spherical coordinates.
Definition: AkTypes.h:468
virtual void Consume(AkAudioBuffer *in_pInputBuffer, AkRamp in_gain)=0
virtual AkUInt32 GetBusType()=0
virtual AkConnectionType GetConnectionType()=0
virtual AKRESULT ComputeSphericalVBAPGains(void *in_pPannerData, AkReal32 in_fAzimuth, AkReal32 in_fElevation, AkUInt32 in_uNumChannels, AK::SpeakerVolumes::VectorPtr out_vVolumes)=0
virtual AKRESULT InitSphericalVBAP(AK::IAkPluginMemAlloc *in_pAllocator, const AkSphericalCoord *in_SphericalPositions, const AkUInt32 in_NbPoints, void *&out_pPannerData)=0
virtual IAkPluginParam * Clone(IAkPluginMemAlloc *in_pAllocator)=0
AkGetDeviceListCallback m_pGetDeviceListFunc
Definition: IAkPlugin.h:1551
Volume ramp specified by end points "previous" and "next".
Definition: AkTypes.h:591
virtual void ApplyGainAndInterleave(AkAudioBuffer *in_pInputBuffer, AkAudioBuffer *in_pOutputBuffer, AkRamp in_gain, bool in_convertToInt16) const =0
virtual const AkAcousticTexture * GetAcousticTexture(AkAcousticTextureID in_AcousticTextureID)=0
virtual AKRESULT Init(IAkPluginMemAlloc *in_pAllocator, IAkSinkPluginContext *in_pSinkPluginContext, IAkPluginParam *in_pParams, AkAudioFormat &io_rFormat)=0
virtual AKRESULT ComputeSphericalCoordinates(const AkEmitterListenerPair &in_pair, AkReal32 &out_fAzimuth, AkReal32 &out_fElevation) const =0
virtual AKRESULT GetOutputID(AkUInt32 &out_uOutputID, AkPluginID &out_uDevicePlugin) const =0
AkUInt32 m_ulPluginID
Definition: IAkPlugin.h:1542
virtual AKRESULT Term(IAkPluginMemAlloc *in_pAllocator)=0
virtual AKRESULT TimeSkip(AkUInt32 &)
Definition: IAkPlugin.h:1082
PluginRegistration(AkUInt32 in_ulCompanyID, AkUInt32 in_ulPluginID, const AkCodecDescriptor &in_Descriptor)
Definition: IAkPlugin.h:1519
virtual void Execute(AkAudioBuffer *io_pBuffer)=0
void * m_pRegisterCallbackCookie
Definition: IAkPlugin.h:1548
virtual ~IAkSourcePluginContext()
Virtual destructor on interface to avoid warnings.
Definition: IAkPlugin.h:357
virtual void * GetUserData()=0
virtual AkUniqueID GetNodeID() const =0
Global plugin context used for plugin registration/initialization. Games query this interface from th...
Definition: IAkPlugin.h:1123
virtual bool GetListeners(AkGameObjectID *out_aListenerIDs, AkUInt32 &io_uSize) const =0
virtual bool IsRenderingOffline() const =0
virtual AKRESULT Compute3DPositioning(AkReal32 in_fAngle, AkReal32 in_fElevation, AkReal32 in_fSpread, AkReal32 in_fFocus, AkChannelConfig in_inputConfig, AkChannelMask in_uInputChanSel, AkChannelConfig in_outputConfig, AkReal32 in_fCenterPerc, AK::SpeakerVolumes::MatrixPtr out_mxVolumes)=0
virtual AKRESULT GetParentChannelConfig(AkChannelConfig &out_channelConfig) const =0
virtual AKRESULT SetParamsBlock(const void *in_pParamsBlock, AkUInt32 in_uBlockSize)=0
Software effect plug-in interface for in-place processing (see How to Create Wwise Sound Engine Effec...
Definition: IAkPlugin.h:697
virtual AkReal32 GetGameObjectScaling() const =0
virtual AKRESULT RelocateMedia(AkUInt8 *, AkUInt8 *)
Definition: IAkPlugin.h:666
virtual AkUniqueID GetBusID()=0
virtual IAkVoicePluginInfo * GetVoiceInfo()=0
virtual AKRESULT ComputeSpeakerVolumesDirect(AkChannelConfig in_inputConfig, AkChannelConfig in_outputConfig, AkReal32 in_fCenterPerc, AK::SpeakerVolumes::MatrixPtr out_mxVolumes)=0
Compute a direct speaker assignment volume matrix with proper downmixing rules between two channel co...
virtual AkReal32 GetDownstreamGain()=0
bool bReserved
Legacy bIsAsynchronous plug-in flag, now unused. Preserved for plug-in backward compatibility....
Definition: IAkPlugin.h:73
virtual AKRESULT TimeSkip(AkUInt32 &io_uFrames)=0
virtual IAkGameObjectPluginInfo * GetGameObjectInfo()=0
virtual AKRESULT UnregisterGlobalCallback(AkGlobalCallbackFunc in_pCallback, AkUInt32 in_eLocation=AkGlobalCallbackLocation_BeginRender)=0
virtual void ResetStarved()=0
Reset the "starvation" flag after IsStarved() returned true.
AkUInt32 uBuildVersion
Plugin build version, must match the AK_WWISESDK_VERSION_COMBINED macro from AkWwiseSDKVersion....
Definition: IAkPlugin.h:70
AkReal32 * MatrixPtr
Volume matrix. Access each input channel vector with AK::SpeakerVolumes::Matrix::GetChannel().
Definition: AkSpeakerVolumes.h:50
virtual AKRESULT Reset()=0
virtual ~IAkEffectPlugin()
Virtual destructor on interface to avoid warnings.
Definition: IAkPlugin.h:681
virtual ~IAkSinkPlugin()
Virtual destructor on interface to avoid warnings.
Definition: IAkPlugin.h:949
virtual AKRESULT GetAudioSettings(AkAudioSettings &out_audioSettings) const =0
virtual IAkPlatformContext * GetPlatformContext() const =0
virtual AKRESULT StopLooping()
Definition: IAkPlugin.h:1058
virtual AkReal32 GetCenterPerc()=0
PluginRegistration * pNext
Definition: IAkPlugin.h:1539
virtual AkPlayingID PostEventSync(AkUniqueID in_eventID, AkGameObjectID in_gameObjectID, AkUInt32 in_uFlags=0, AkCallbackFunc in_pfnCallback=NULL, void *in_pCookie=NULL, AkUInt32 in_cExternals=0, AkExternalSourceInfo *in_pExternalSources=NULL, AkPlayingID in_PlayingID=AK_INVALID_PLAYING_ID)=0
virtual AKRESULT Get3DPosition(AkUInt32 in_uIndex, AkEmitterListenerPair &out_soundPosition)=0
virtual ~IAkSourcePlugin()
Virtual destructor on interface to avoid warnings.
Definition: IAkPlugin.h:1017
virtual ~IAkPlugin()
Virtual destructor on interface to avoid warnings.
Definition: IAkPlugin.h:614
virtual AKRESULT GetEmitterListenerPair(AkUInt32 in_uIndex, AkEmitterListenerPair &out_emitterListenerPair) const =0
Definition: AkMidiTypes.h:228
Game object information available to plugins.
Definition: IAkPlugin.h:91
virtual AK::IAkPluginMemAlloc * GetAllocator()=0
Get the default allocator for plugins. This is useful for performing global initialization tasks shar...
virtual AKRESULT Init(IAkPluginMemAlloc *in_pAllocator, IAkSourcePluginContext *in_pSourcePluginContext, IAkPluginParam *in_pParams, AkAudioFormat &io_rFormat)=0
3D vector.
Definition: AkTypes.h:297
virtual AKRESULT Seek(AkUInt32)
Definition: IAkPlugin.h:1072
virtual ~IAkEffectPluginContext()
Virtual destructor on interface to avoid warnings.
Definition: IAkPlugin.h:325
virtual AkGameObjectID GetGameObjectID() const =0
Get the ID of the game object.
virtual const AkPlatformInitSettings * GetPlatformInitSettings() const =0
AkGlobalCallbackFunc m_pRegisterCallback
Definition: IAkPlugin.h:1547
virtual bool IsPrimary()=0
Listener information.
Definition: AkTypes.h:546
virtual const AkInitSettings * GetInitSettings() const =0
virtual AKRESULT PostMonitorMessage(const char *in_pszError, AK::Monitor::ErrorLevel in_eErrorLevel)=0
virtual SoundEngine::MultiPositionType GetGameObjectMultiPositionType() const =0
const typedef AkReal32 * ConstVectorPtr
Constant volume vector. Access each element with the standard bracket [] operator.
Definition: AkSpeakerVolumes.h:51
static const AkPluginParamID ALL_PLUGIN_DATA_ID
Definition: IAkPlugin.h:604
AkPluginType m_eType
Definition: IAkPlugin.h:1540
ErrorLevel
ErrorLevel.
Definition: AkMonitorError.h:91
virtual AKRESULT TermSphericalVBAP(AK::IAkPluginMemAlloc *in_pAllocator, void *in_pPannerData)=0
virtual AkUInt32 GetNumEmitterListenerPairs() const =0
Defines the parameters of an audio buffer format.
Definition: AkCommonDefs.h:59
virtual Ak3DPositionType Get3DPositionType()=0
Position and orientation of game objects.
Definition: AkTypes.h:321
virtual AKRESULT RegisterCodec(AkUInt32 in_ulCompanyID, AkUInt32 in_ulPluginID, AkCreateFileSourceCallback in_pFileCreateFunc, AkCreateBankSourceCallback in_pBankCreateFunc)=0
AkUInt32 m_ulCompanyID
Definition: IAkPlugin.h:1541
virtual void ComputeAmbisonicsEncoding(AkReal32 in_fAzimuth, AkReal32 in_fElevation, AkChannelConfig in_cfgAmbisonics, AK::SpeakerVolumes::VectorPtr out_vVolumes)=0
virtual AkReal32 GetDuration() const =0
virtual AKRESULT GetSpeakerAngles(AkReal32 *io_pfSpeakerAngles, AkUInt32 &io_uNumAngles, AkReal32 &out_fHeightAngle)=0
virtual AKRESULT RegisterGlobalCallback(AkPluginType in_eType, AkUInt32 in_ulCompanyID, AkUInt32 in_ulPluginID, AkGlobalCallbackFunc in_pCallback, AkUInt32 in_eLocation=AkGlobalCallbackLocation_BeginRender, void *in_pCookie=NULL)=0
virtual void MixChannel(AkReal32 *AK_RESTRICT in_pInBuffer, AkReal32 *AK_RESTRICT in_pOutBuffer, AkReal32 in_fPrevGain, AkReal32 in_fNextGain, AkUInt16 in_uNumFrames)=0
Single channel mix.
virtual void GetPluginCustomGameData(void *&out_rpData, AkUInt32 &out_rDataSize)=0
Interface to retrieve contextual information available to all types of plugins.
Definition: IAkPlugin.h:216
AkCreateBankSourceCallback m_pBankCreateFunc
LEGACY: Kept for compatibility with 2019.1. Unused in 2019.2 and up.
Definition: IAkPlugin.h:1546
virtual AKRESULT GetListenerData(AkGameObjectID in_uListener, AkListener &out_listener) const =0
virtual AkUInt32 GetNumGameObjectPositions() const =0
virtual IAkStreamMgr * GetStreamMgr() const =0
Retrieve the streaming manager access interface.