Table of Contents

include/AK/SoundEngine/Common/IAkPlugin.h

Go to the documentation of this file.
00001 /*******************************************************************************
00002 The content of this file includes portions of the AUDIOKINETIC Wwise Technology
00003 released in source code form as part of the SDK installer package.
00004 
00005 Commercial License Usage
00006 
00007 Licensees holding valid commercial licenses to the AUDIOKINETIC Wwise Technology
00008 may use this file in accordance with the end user license agreement provided 
00009 with the software or, alternatively, in accordance with the terms contained in a
00010 written agreement between you and Audiokinetic Inc.
00011 
00012 Apache License Usage
00013 
00014 Alternatively, this file may be used under the Apache License, Version 2.0 (the 
00015 "Apache License"); you may not use this file except in compliance with the 
00016 Apache License. You may obtain a copy of the Apache License at 
00017 http://www.apache.org/licenses/LICENSE-2.0.
00018 
00019 Unless required by applicable law or agreed to in writing, software distributed
00020 under the Apache License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES
00021 OR CONDITIONS OF ANY KIND, either express or implied. See the Apache License for
00022 the specific language governing permissions and limitations under the License.
00023 
00024   Version: <VERSION>  Build: <BUILDNUMBER>
00025   Copyright (c) <COPYRIGHTYEAR> Audiokinetic Inc.
00026 *******************************************************************************/
00027 
00028 /// \file
00029 /// Software source plug-in and effect plug-in interfaces.
00030 
00031 #ifndef _IAK_PLUGIN_H_
00032 #define _IAK_PLUGIN_H_
00033 
00034 #include <AK/SoundEngine/Common/AkCommonDefs.h>
00035 #include <AK/SoundEngine/Common/IAkRTPCSubscriber.h>
00036 #include <AK/SoundEngine/Common/IAkPluginMemAlloc.h>
00037 #include <AK/SoundEngine/Common/AkFPUtilities.h>
00038 #include <AK/Tools/Common/AkLock.h>
00039 #include <AK/Tools/Common/AkPlatformFuncs.h>
00040 #include <AK/Tools/Common/AkMonitorError.h>
00041 #include <AK/SoundEngine/Common/AkSoundEngineExport.h>
00042 #include <AK/SoundEngine/Common/IAkProcessorFeatures.h>
00043 #include <AK/SoundEngine/Common/IAkPlatformContext.h>
00044 #include <AK/SoundEngine/Common/AkMidiTypes.h>
00045 #include <AK/SoundEngine/Common/AkCallback.h>
00046 #include <AK/AkWwiseSDKVersion.h>
00047 
00048 #include <math.h>
00049 
00050 #if defined AK_CPU_X86  || defined AK_CPU_X86_64
00051 #include <xmmintrin.h>
00052 #endif
00053 
00054 /// Plug-in information structure.
00055 /// \remarks The bIsInPlace field is only relevant for effect plug-ins.
00056 /// \sa
00057 /// - \ref iakeffect_geteffectinfo
00058 struct AkPluginInfo
00059 {
00060     /// Constructor for default values
00061     AkPluginInfo()
00062         : eType(AkPluginTypeNone)
00063         , uBuildVersion( 0 )
00064         , bIsInPlace(true)
00065         , bCanChangeRate(false)
00066         , bReserved(false)
00067     {}
00068 
00069     AkPluginType eType;            ///< Plug-in type
00070     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.
00071     bool         bIsInPlace;       ///< Buffer usage (in-place or not)
00072     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.
00073     bool         bReserved;        ///< Legacy bIsAsynchronous plug-in flag, now unused. Preserved for plug-in backward compatibility. bReserved should be false for all plug-in.
00074 };
00075 
00076 //Forward declarations.
00077 namespace AK
00078 {
00079     class PluginRegistration;
00080 }
00081 extern "C" AK_DLLEXPORT AK::PluginRegistration * g_pAKPluginList;
00082 
00083 struct AkAcousticTexture;
00084 
00085 namespace AK
00086 {
00087     class IAkStreamMgr;
00088     class IAkGlobalPluginContext;
00089 
00090     /// Game object information available to plugins.
00091     class IAkGameObjectPluginInfo
00092     {
00093     protected:
00094         /// Virtual destructor on interface to avoid warnings.
00095         virtual ~IAkGameObjectPluginInfo(){}
00096 
00097     public:
00098 
00099         /// Get the ID of the game object.
00100         virtual AkGameObjectID GetGameObjectID() const = 0;
00101 
00102         /// Retrieve the number of emitter-listener pairs (rays) of the game object.
00103         /// A game object may have more than one position, and be listened to more than one listener.
00104         /// The returned value is the product of these two numbers. Use the returned value as a higher
00105         /// bound for the index of GetEmitterListenerPair().
00106         /// Note that rays whose listener is irrelevant to the current context are ignored. For example,
00107         /// if the calling plug-in exists on a bus, only listeners that are routed to the end point's
00108         /// device are considered.
00109         /// \sa
00110         /// - AK::SoundEngine::SetPosition()
00111         /// - AK::SoundEngine::SetMultiplePositions()
00112         /// - AK::SoundEngine::SetListeners()
00113         /// - AK::IAkGameObjectPluginInfo::GetEmitterListenerPair()
00114         /// - AK::SoundEngine::AddSecondaryOutput()
00115         virtual AkUInt32 GetNumEmitterListenerPairs() const = 0;
00116 
00117         /// Retrieve the emitter-listener pair (ray) of the game object at index in_uIndex.
00118         /// Call GetNumEmitterListenerPairs() prior to this function to get the total number of
00119         /// emitter-listener pairs of the game object.
00120         /// The emitter-listener pair is expressed as the game object's position relative to the
00121         /// listener, in spherical coordinates.
00122         /// \note
00123         /// - The distance takes game object and listener scaling factors into account.
00124         /// - Returned distance and angles are those of the game object, and do not necessarily correspond
00125         /// to any sound's positioning data.
00126         /// \return AK_Fail if the index is invalid, AK_Success otherwise.
00127         /// \sa
00128         /// - AK::SoundEngine::SetScalingFactor()
00129         /// - AK::IAkGameObjectPluginInfo::GetNumEmitterListenerPairs()
00130         virtual AKRESULT GetEmitterListenerPair(
00131             AkUInt32 in_uIndex,             ///< Index of the pair, [0, GetNumEmitterListenerPairs()[
00132             AkEmitterListenerPair & out_emitterListenerPair ///< Returned relative source position in spherical coordinates.
00133             ) const = 0;
00134 
00135         /// Get the number of positions of the game object. Use this value to determine the indices to be
00136         /// passed to GetGameObjectPosition().
00137         /// \sa
00138         /// - AK::SoundEngine::SetPosition()
00139         /// - AK::SoundEngine::SetMultiplePositions()
00140         /// - AK::IAkGameObjectPluginInfo::GetGameObjectPosition();
00141         virtual AkUInt32 GetNumGameObjectPositions() const = 0;
00142 
00143         /// Get the raw position of the game object at index in_uIndex.
00144         /// Use GetNumGameObjectPositions() prior to this function to get the total number of positions
00145         /// of that game object.
00146         /// \return AK_Fail if the index is out of bounds, AK_Success otherwise.
00147         /// \sa
00148         /// - AK::SoundEngine::SetPosition()
00149         /// - AK::SoundEngine::SetMultiplePositions()
00150         /// - AK::IAkGameObjectPluginInfo::GetNumGameObjectPositions()
00151         virtual AKRESULT GetGameObjectPosition(
00152             AkUInt32 in_uIndex,             ///< Index of the position, [0, GetNumGameObjectPositions()[
00153             AkSoundPosition & out_position  ///< Returned raw position info.
00154             ) const = 0;
00155 
00156         /// Get the multi-position type assigned to the game object.
00157         /// \return MultiPositionType_MultiSources when the effect is instantiated on a bus.
00158         /// \sa
00159         /// - AK::SoundEngine::SetPosition()
00160         /// - AK::SoundEngine::SetMultiplePositions()
00161         virtual SoundEngine::MultiPositionType GetGameObjectMultiPositionType() const = 0;
00162 
00163         /// Get the distance scaling factor of the associated game object.
00164         /// \sa
00165         /// - AK::SoundEngine::SetScalingFactor()
00166         virtual AkReal32 GetGameObjectScaling() const = 0;
00167 
00168         /// Get the game object IDs of listener game objects that are listening to the emitter game object.
00169         /// Note that only listeners relevant to the current context are considered. For example,
00170         /// if the calling plug-in exists on a bus, only listeners that are routed to the end point's
00171         /// device are added to the returned array.
00172         /// \return True if the call succeeded, false if all the listeners could not fit into the array,
00173         /// \sa
00174         /// - AK::SoundEngine::SetListeners()
00175         virtual bool GetListeners( 
00176             AkGameObjectID* out_aListenerIDs,   ///< Array of listener IDs to fill, or NULL to query the size needed.
00177             AkUInt32& io_uSize                  ///< In: max size of the array, out: number of valid elements returned in out_aListenerIDs.
00178             ) const = 0;
00179 
00180         /// Get information about a listener. Use GetListeners() prior to this function
00181         /// in order to know which listeners are listening to the associated game object. 
00182         /// \return AK_Fail if the listener ID is invalid. AK_Success otherwise.
00183         /// \sa
00184         /// - AK::SoundEngine::SetListeners()
00185         /// - AK::IAkGameObjectPluginInfo::GetListeners()
00186         virtual AKRESULT GetListenerData(
00187             AkGameObjectID in_uListener,        ///< Bit field identifying the listener for which you desire information.
00188             AkListener & out_listener           ///< Returned listener info.
00189             ) const = 0;
00190     };
00191 
00192     /// Voice-specific information available to plug-ins. The associated game object's information is
00193     /// available through the methods of the base class IAkGameObjectPluginInfo.
00194     class IAkVoicePluginInfo : public IAkGameObjectPluginInfo
00195     {
00196     protected:
00197         /// Virtual destructor on interface to avoid warnings.
00198         virtual ~IAkVoicePluginInfo(){}
00199 
00200     public:
00201 
00202         /// Retrieve the Playing ID of the event corresponding to this voice (if applicable).
00203         virtual AkPlayingID GetPlayingID() const = 0;
00204 
00205         /// Get priority value associated to this voice. When priority voice is modified by distance, the minimum distance among emitter-listener pairs is used.
00206         /// \return The priority between AK_MIN_PRIORITY and AK_MAX_PRIORITY inclusively.
00207         virtual AkPriority GetPriority() const = 0;
00208 
00209         /// Get priority value associated to this voice, for a specified distance, which may differ from the minimum distance that is used by default.
00210         /// \return The priority between AK_MIN_PRIORITY and AK_MAX_PRIORITY inclusively.
00211         virtual AkPriority ComputePriorityWithDistance(
00212             AkReal32 in_fDistance               ///< Distance.
00213             ) const = 0;
00214     };
00215 
00216     /// Interface to retrieve contextual information available to all types of plugins.
00217     class IAkPluginContextBase
00218     {
00219     protected:
00220         /// Virtual destructor on interface to avoid warnings.
00221         virtual ~IAkPluginContextBase(){}
00222 
00223     public:
00224 
00225         /// \return The global sound engine context.
00226         /// \sa IAkGlobalPluginContext
00227         virtual IAkGlobalPluginContext* GlobalContext() const = 0;
00228 
00229         /// Obtain the interface to access the game object on which the plugin is instantiated.
00230         /// \return The interface to GameObject info.
00231         virtual IAkGameObjectPluginInfo * GetGameObjectInfo() = 0;
00232 
00233         /// Identify the output device into which the data processed by this plugin will end up.
00234         /// Applicable to plug-ins instantiated as bus effects and to sink plugins.
00235         /// Plug-ins instantiated in the Actor-Mixer hierarchy (i.e. on voices) return AK_NotCompatible.
00236         /// \sa integrating_secondary_outputs
00237         /// \return The device type and unique identifier. AK_Success if successful, AK_NotCompatible otherwise.
00238         virtual AKRESULT GetOutputID(
00239             AkUInt32 &          out_uOutputID,      ///< Device identifier, when multiple devices of the same type are possible.
00240             AkPluginID &        out_uDevicePlugin   ///< Device plugin ID.
00241             ) const = 0;
00242 
00243         /// Return the pointer and size of the plug-in media corresponding to the specified index.
00244         /// The pointer returned will be NULL if the plug-in media is either not loaded or inexistant.
00245         /// When this function is called and returns a valid data pointer, the data can only be used by this
00246         /// instance of the plugin and is guaranteed to be valid only during the plug-in lifespan.
00247         virtual void GetPluginMedia(
00248             AkUInt32 in_dataIndex,      ///< Index of the plug-in media to be returned.
00249             AkUInt8* &out_rpData,       ///< Pointer to the data
00250             AkUInt32 &out_rDataSize     ///< size of the data returned in bytes.
00251             ) = 0;
00252 
00253         /// Return the pointer and size of the game data corresponding to the specified index, sent by the game using AK::SoundEngine::SendPluginCustomGameData().
00254         /// The pointer returned will be NULL if the game data is inexistent.
00255         /// When this function is called and returns a valid data pointer, the data can only be used by this 
00256         /// instance of the plugin and is guaranteed to be valid only during the frame.
00257         virtual void GetPluginCustomGameData( 
00258             void* &out_rpData,          ///< Pointer to the data
00259             AkUInt32 &out_rDataSize     ///< size of the data returned in bytes.
00260             ) = 0;
00261 
00262         /// Post a custom blob of data to the UI counterpart of this effect plug-in.
00263         /// Data is sent asynchronously through the profiling system.
00264         /// Notes:
00265         /// - It is only possible to post data when the instance of the plug-in is on a bus,
00266         ///     because there is a one-to-one relationship with its effect settings view.
00267         ///     You may call CanPostMonitorData() to determine if your plug-in can send data to the UI.
00268         /// - Data is copied into the communication buffer within this method,
00269         ///     so you may discard it afterwards.
00270         /// - You need to handle byte swapping on one side or the other when sending
00271         ///     data from a big-endian platform.
00272         /// - Sending data to the UI is only possible in Debug and Profile. Thus, you should
00273         ///     enclose your calls to package and send that data within !AK_OPTIMIZED preprocessor flag.
00274         /// \return AK_Success if the plug-in exists on a bus, AK_Fail otherwise.
00275         virtual AKRESULT PostMonitorData(
00276             void *      in_pData,       ///< Blob of data.
00277             AkUInt32    in_uDataSize    ///< Size of data.
00278             ) = 0;
00279 
00280         /// Query the context to know if it is possible to send data to the UI counterpart of this effect plug-in.
00281         /// It is only possible to post data when the instance of the plug-in is on a bus, because there is a
00282         /// one-to-one relationship with its effect settings view.
00283         /// \return True if the instance of the plug-in is on a bus, and the authoring tool is connected and
00284         ///     monitoring the game, false otherwise.
00285         /// \sa PostMonitorData()
00286         virtual bool     CanPostMonitorData() = 0;
00287 
00288         /// Post a monitoring message or error string. This will be displayed in the Wwise capture
00289         /// log.
00290         /// \return AK_Success if successful, AK_Fail if there was a problem posting the message.
00291         ///         In optimized mode, this function returns AK_NotCompatible.
00292         /// \remark This function is provided as a tracking tool only. It does nothing if it is
00293         ///         called in the optimized/release configuration and return AK_NotCompatible.
00294         virtual AKRESULT PostMonitorMessage(
00295             const char* in_pszError,                ///< Message or error string to be displayed
00296             AK::Monitor::ErrorLevel in_eErrorLevel  ///< Specifies whether it should be displayed as a message or an error
00297             ) = 0;
00298 
00299         /// Get the cumulative gain of all mixing stages, from the host audio node down to the device end point.
00300         /// Returns 1.f when the node is an actor-mixer (voice), because a voice may be routed to several mix chains.
00301         /// \return The cumulative downstream gain.
00302         virtual AkReal32 GetDownstreamGain() = 0;
00303 
00304         /// 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
00305         /// 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
00306         /// this configuration.
00307         /// Returns !out_channelConfig.IsValid() when the node is an actor-mixer (voice), because a voice may be routed to several mix chains.
00308         /// \return AK_Success if the channel config of the primary, direct parent bus could be determined, AK_Fail otherwise.
00309         virtual AKRESULT GetParentChannelConfig(
00310             AkChannelConfig& out_channelConfig  ///< Channel configuration of parent node (downstream bus).
00311             ) const = 0;
00312 
00313 #if (defined AK_CPU_X86 || defined AK_CPU_X86_64) && !(defined AK_IOS)
00314         /// Return an interface to query processor specific features.
00315         virtual IAkProcessorFeatures * GetProcessorFeatures() = 0;
00316 #endif
00317     };
00318 
00319     /// Interface to retrieve contextual information for an effect plug-in.
00320     /// \sa
00321     /// - \ref iakmonadiceffect_init
00322     class IAkEffectPluginContext : public IAkPluginContextBase
00323     {
00324     protected:
00325         /// Virtual destructor on interface to avoid warnings.
00326         virtual ~IAkEffectPluginContext(){}
00327 
00328     public:
00329 
00330         /// Determine whether the effect is to be used in Send Mode or not.
00331         /// Effects used in auxiliary busses are always used in Send Mode.
00332         /// \return True if the effect is in Send Mode, False otherwise
00333         virtual bool IsSendModeEffect() const = 0;
00334 
00335         /// Obtain the interface to access the voice in which the plugin is inserted.
00336         /// \return The interface to voice info. NULL if the plugin is instantiated on a bus.
00337         virtual IAkVoicePluginInfo * GetVoiceInfo() = 0;
00338 
00339         /// Get internal ID of sound structure (sound object or bus) on which the plug-in is instantiated.
00340         /// In the case of a voice, the ID is internal but corresponds to what you would get from the duration 
00341         /// callback (see AkDurationCallbackInfo::audioNodeID). In the case of a bus, it can be matched with the bus name converted 
00342         /// to a unique ID using AK::SoundEngine::GetIDFromString(). Returns AK_INVALID_UNIQUE_ID in the case of a sink/device.
00343         /// \return ID of structure.
00344         /// \sa 
00345         /// - AkDurationCallbackInfo
00346         /// - AK::SoundEngine::PostEvent()
00347         /// - AK::SoundEngine::GetIDFromString()
00348         virtual AkUniqueID GetNodeID() const = 0;
00349     };
00350 
00351     /// Interface to retrieve contextual information for a source plug-in.
00352     /// \sa
00353     /// - \ref iaksourceeffect_init
00354     class IAkSourcePluginContext : public IAkPluginContextBase
00355     {
00356     protected:
00357         /// Virtual destructor on interface to avoid warnings.
00358         virtual ~IAkSourcePluginContext(){}
00359 
00360     public:
00361 
00362         /// Retrieve the number of loops the source should produce.
00363         /// \return The number of loop iterations the source should produce (0 if infinite looping)
00364         virtual AkUInt16 GetNumLoops() const = 0;
00365 
00366         /// Obtain the interface to access the voice in which the plugin is inserted.
00367         /// \return The interface to voice info.
00368         virtual IAkVoicePluginInfo * GetVoiceInfo() = 0;
00369 
00370         /// Obtain the MIDI event info associated to the source.
00371         /// \return The MIDI event info.
00372         /// 
00373         virtual AkMIDIEvent GetMidiEvent() const = 0;
00374 
00375         /// Get internal ID of sound structure (sound object or bus) on which the plug-in is instantiated.
00376         /// In the case of a voice, the ID is internal but corresponds to what you would get from the duration 
00377         /// callback (see AkDurationCallbackInfo::audioNodeID). In the case of a bus, it can be matched with the bus name converted 
00378         /// to a unique ID using AK::SoundEngine::GetIDFromString(). Returns AK_INVALID_UNIQUE_ID in the case of a sink/device.
00379         /// \return ID of structure.
00380         /// \sa 
00381         /// - AkDurationCallbackInfo
00382         /// - AK::SoundEngine::PostEvent()
00383         /// - AK::SoundEngine::GetIDFromString()
00384         virtual AkUniqueID GetNodeID() const = 0;
00385 
00386         /// Retrieve Cookie information for a Source Plugin
00387         /// \return the void pointer of the Cookie passed to the PostEvent 
00388         virtual void* GetCookie() const = 0;    
00389 
00390     };
00391 
00392     /// Interface to retrieve contextual information for a mixer.
00393     class IAkMixerPluginContext : public IAkPluginContextBase
00394     {
00395     protected:
00396         /// Virtual destructor on interface to avoid warnings.
00397         virtual ~IAkMixerPluginContext(){}
00398 
00399     public:
00400 
00401         /// 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().
00402         /// \return ID of bus.
00403         /// \sa AK::SoundEngine::GetIDFromString()
00404         virtual AkUniqueID GetBusID() = 0;
00405 
00406         /// DEPRECATED.  
00407         /// Get the type of the bus on which the mixer plugin is instantiated.
00408         /// AkBusHierachyFlags is a bit field, indicating whether the bus is the master (top-level) bus or not,
00409         /// and whether it is in the primary or secondary mixing graph.
00410         /// \return The bus type.
00411         virtual AkUInt32 GetBusType() = 0;
00412 
00413         /// Get speaker angles of the specified device.
00414         /// The speaker angles are expressed as an array of loudspeaker pairs, in degrees, relative to azimuth ]0,180].
00415         /// Supported loudspeaker setups are always symmetric; the center speaker is always in the middle and thus not specified by angles.
00416         /// Angles must be set in ascending order.
00417         /// You may call this function with io_pfSpeakerAngles set to NULL to get the expected number of angle values in io_uNumAngles,
00418         /// in order to allocate your array correctly. You may also obtain this number by calling
00419         /// AK::GetNumberOfAnglesForConfig( AK_SPEAKER_SETUP_DEFAULT_PLANE ).
00420         /// If io_pfSpeakerAngles is not NULL, the array is filled with up to io_uNumAngles.
00421         /// Typical usage:
00422         /// - AkUInt32 uNumAngles;
00423         /// - GetSpeakerAngles( NULL, uNumAngles );
00424         /// - AkReal32 * pfSpeakerAngles = AkAlloca( uNumAngles * sizeof(AkReal32) );
00425         /// - GetSpeakerAngles( pfSpeakerAngles, uNumAngles );
00426         /// \warning Call this function only after the sound engine has been properly initialized.
00427         /// \return AK_Success if the end point device is properly initialized, AK_Fail otherwise.
00428         /// \sa AK::SoundEngine::GetSpeakerAngles()
00429         virtual AKRESULT GetSpeakerAngles(
00430             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.
00431             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.
00432             AkReal32 &          out_fHeightAngle            ///< Elevation of the height layer, in degrees relative to the plane.
00433             ) = 0;
00434 
00435         /// \name Services.
00436         //@{
00437 
00438         /// Compute a direct speaker assignment volume matrix with proper downmixing rules between two channel configurations.
00439         virtual AKRESULT ComputeSpeakerVolumesDirect(
00440             AkChannelConfig     in_inputConfig,             ///< Channel configuration of the input.
00441             AkChannelConfig     in_outputConfig,            ///< Channel configuration of the mixer output.
00442             AkReal32            in_fCenterPerc,             ///< Center percentage. Only applies to mono inputs with standard output configurations that have a center channel.
00443             AK::SpeakerVolumes::MatrixPtr out_mxVolumes     ///< Returned volumes matrix. Must be preallocated using AK::SpeakerVolumes::Matrix::GetRequiredSize() (see AK::SpeakerVolumes::Matrix services).
00444             ) = 0;
00445 
00446         /// Compute a volume matrix given the position of the panner (Wwise 2D panner).
00447         virtual AKRESULT ComputeSpeakerVolumesPanner(
00448             const AkVector &    in_position,                ///< x,y,z panner position [-1,1]. Note that z has no effect at the moment.
00449             AkReal32            in_fCenterPct,              ///< Center percentage.
00450             AkChannelConfig     in_inputConfig,             ///< Channel configuration of the input.
00451             AkChannelConfig     in_outputConfig,            ///< Channel configuration of the mixer output.
00452             AK::SpeakerVolumes::MatrixPtr out_mxVolumes     ///< Returned volumes matrix. Must be preallocated using AK::SpeakerVolumes::Matrix::GetRequiredSize() (see AK::SpeakerVolumes::Matrix services).
00453             ) = 0;
00454 
00455         /// Compute panning gains on the plane given an incidence angle and channel configuration.
00456         /// \return AK_Success if successful, AK_Fail otherwise.
00457         virtual AKRESULT ComputePlanarVBAPGains(
00458             AkReal32            in_fAngle,                  ///< Incident angle, in radians [-pi,pi], where 0 is the azimuth (positive values are clockwise)
00459             AkChannelConfig     in_outputConfig,            ///< Desired output configuration.
00460             AkReal32            in_fCenterPerc,             ///< Center percentage. Only applies to mono inputs to outputs that have no center.
00461             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.
00462             ) = 0;
00463 
00464         /// Initialize spherical VBAP
00465         /// \return AK_Success if successful, AK_Fail otherwise.
00466         virtual AKRESULT InitSphericalVBAP(
00467             AK::IAkPluginMemAlloc* in_pAllocator,           ///< Memory allocator
00468             const AkSphericalCoord* in_SphericalPositions,  ///< Array of points in spherical coordinate, representign the virtual position of each channels.
00469             const AkUInt32 in_NbPoints,                     ///< Number of points in the position array
00470             void *& out_pPannerData                         ///< Contains data relevant to the 3D panner that shoud be re-used accross plugin instances.
00471             ) = 0;
00472 
00473         /// Compute panning gains on the plane given an incidence angle and channel configuration.
00474         /// \return AK_Success if successful, AK_Fail otherwise.
00475         virtual AKRESULT ComputeSphericalVBAPGains(
00476             void*               in_pPannerData,             ///< Contains data relevant to the 3D panner that shoud be re-used accross plugin instances.
00477             AkReal32            in_fAzimuth,                ///< Incident angle, in radians [-pi,pi], where 0 is the azimuth (positive values are clockwise)
00478             AkReal32            in_fElevation,              ///< Incident angle, in radians [0,pi], where 0 is the elevation (positive values are clockwise)
00479             AkUInt32            in_uNumChannels,            ///< Number of output channels.
00480             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.
00481             ) = 0;
00482 
00483         /// Clear panner data obtained from InitSphericalVBAP().
00484         /// \return AK_Success if successful, AK_Fail otherwise.
00485         virtual AKRESULT TermSphericalVBAP(
00486             AK::IAkPluginMemAlloc*  in_pAllocator,          ///< Memory allocator
00487             void*                   in_pPannerData          ///< Contains data relevant to the 3D panner that shoud be re-used accross plugin instances.
00488             ) = 0;
00489 
00490         /// Compute standard 3D positioning.
00491         /// \return AK_Success if successful.
00492         /// \aknote The cartesian counterpart of Compute3DPositioning, that uses emitter and listener transforms, should be used instead of this function.
00493         /// It is more complete and more efficient. \endaknote
00494         virtual AKRESULT Compute3DPositioning(
00495             AkReal32            in_fAngle,                  ///< Incident angle, in radians [-pi,pi], where 0 is the azimuth (positive values are clockwise).
00496             AkReal32            in_fElevation,              ///< Incident elevation angle, in radians [-pi/2,pi/2], where 0 is the horizon (positive values are above the horizon).
00497             AkReal32            in_fSpread,                 ///< Spread ([0,100]).
00498             AkReal32            in_fFocus,                  ///< Focus ([0,100]).
00499             AkChannelConfig     in_inputConfig,             ///< Channel configuration of the input.
00500             AkChannelMask       in_uInputChanSel,           ///< Mask of input channels selected for panning (excluded input channels don't contribute to the output).
00501             AkChannelConfig     in_outputConfig,            ///< Desired output configuration.
00502             AkReal32            in_fCenterPerc,             ///< Center percentage. Only applies to mono inputs to outputs that have a center.
00503             AK::SpeakerVolumes::MatrixPtr out_mxVolumes     ///< Returned volumes matrix. Must be preallocated using AK::SpeakerVolumes::Matrix::GetRequiredSize() (see AK::SpeakerVolumes::Matrix services).
00504             ) = 0;
00505 
00506         /// Compute standard 3D positioning.
00507         /// \return AK_Success if successful.
00508         /// \aknote This function is more complete and more efficient than the Compute3DPositioning service that uses spherical coordinates, and should be favored.\endaknote
00509         virtual AKRESULT Compute3DPositioning(
00510             const AkTransform & in_emitter,                 ///< Emitter transform.
00511             const AkTransform & in_listener,                ///< Listener transform.
00512             AkReal32            in_fCenterPerc,             ///< Center percentage. Only applies to mono inputs to outputs that have a center.
00513             AkReal32            in_fSpread,                 ///< Spread.
00514             AkReal32            in_fFocus,                  ///< Focus.
00515             AkChannelConfig     in_inputConfig,             ///< Channel configuration of the input.
00516             AkChannelMask       in_uInputChanSel,           ///< Mask of input channels selected for panning (excluded input channels don't contribute to the output).
00517             AkChannelConfig     in_outputConfig,            ///< Desired output configuration.
00518             AK::SpeakerVolumes::MatrixPtr out_mxVolumes     ///< Returned volumes matrix. Must be preallocated using AK::SpeakerVolumes::Matrix::GetRequiredSize() (see AK::SpeakerVolumes::Matrix services).
00519             ) = 0;
00520 
00521         //@}
00522 
00523         /// \name Metering.
00524         //@{
00525 
00526         /// Set flags for controlling computation of metering values on the mix buffer.
00527         /// Pass AK_NoMetering to disable metering.
00528         /// \sa
00529         /// - AK::IAkMetering
00530         virtual void EnableMetering( AkMeteringFlags in_eFlags ) = 0;
00531 
00532         //@}
00533     };
00534 
00535     /// Parameter node interface, managing access to an enclosed parameter structure.
00536     /// \aknote The implementer of this interface should also expose a static creation function
00537     /// that will return a new parameter node instance when required (see \ref se_plugins_overview). \endaknote
00538     /// \sa
00539     /// - \ref shared_parameter_interface
00540     class IAkPluginParam : public IAkRTPCSubscriber
00541     {
00542     protected:
00543         /// Virtual destructor on interface to avoid warnings.
00544         virtual ~IAkPluginParam(){}
00545 
00546     public:
00547         /// Create a duplicate of the parameter node instance in its current state.
00548         /// \aknote The allocation of the new parameter node should be done through the AK_PLUGIN_NEW() macro. \endaknote
00549         /// \return Pointer to a duplicated plug-in parameter node interface
00550         /// \sa
00551         /// - \ref iakeffectparam_clone
00552         virtual IAkPluginParam * Clone(
00553             IAkPluginMemAlloc * in_pAllocator   ///< Interface to memory allocator to be used
00554             ) = 0;
00555 
00556         /// Initialize the plug-in parameter node interface.
00557         /// Initializes the internal parameter structure to default values or with the provided parameter
00558         /// block if it is valid. \endaknote
00559         /// \aknote If the provided parameter block is valid, use SetParamsBlock() to set all parameters at once. \endaknote
00560         /// \return Possible return values are: AK_Success, AK_Fail, AK_InvalidParameter
00561         /// \sa
00562         /// - \ref iakeffectparam_init
00563         virtual AKRESULT Init(
00564             IAkPluginMemAlloc * in_pAllocator,      ///< Interface to the memory allocator to be used
00565             const void *        in_pParamsBlock,    ///< Pointer to a parameter structure block
00566             AkUInt32            in_uBlockSize       ///< Size of the parameter structure block
00567             ) = 0;
00568 
00569         /// Called by the sound engine when a parameter node is terminated.
00570         /// \aknote The self-destruction of the parameter node must be done using the AK_PLUGIN_DELETE() macro. \endaknote
00571         /// \return AK_Success if successful, AK_Fail otherwise
00572         /// \sa
00573         /// - \ref iakeffectparam_term
00574         virtual AKRESULT Term(
00575             IAkPluginMemAlloc * in_pAllocator       ///< Interface to memory allocator to be used
00576             ) = 0;
00577 
00578         /// Set all plug-in parameters at once using a parameter block.
00579         /// \return AK_Success if successful, AK_InvalidParameter otherwise
00580         /// \sa
00581         /// - \ref iakeffectparam_setparamsblock
00582         virtual AKRESULT SetParamsBlock(
00583             const void *in_pParamsBlock,    ///< Pointer to a parameter structure block
00584             AkUInt32    in_uBlockSize       ///< Size of the parameter structure block
00585             ) = 0;
00586 
00587         /// Update a single parameter at a time and perform the necessary actions on the parameter changes.
00588         /// \aknote The parameter ID corresponds to the AudioEnginePropertyID in the plug-in XML description file. \endaknote
00589         /// \return AK_Success if successful, AK_InvalidParameter otherwise
00590         /// \sa
00591         /// - \ref iakeffectparam_setparam
00592         virtual AKRESULT SetParam(
00593             AkPluginParamID in_paramID,     ///< ID number of the parameter to set
00594             const void *    in_pValue,      ///< Pointer to the value of the parameter to set
00595             AkUInt32        in_uParamSize   ///< Size of the value of the parameter to set
00596             ) = 0;
00597 
00598         /// Use this constant with AK::Wwise::IPluginPropertySet::NotifyInternalDataChanged,
00599         /// AK::Wwise::IAudioPlugin::GetPluginData and IAkPluginParam::SetParam. This tells
00600         /// that the whole plugin data needs to be saved/transferred.
00601         ///\sa
00602         /// - AK::Wwise::IPluginPropertySet::NotifyInternalDataChanged
00603         /// - AK::Wwise::IAudioPlugin::GetPluginData
00604         /// - AK::IAkPluginParam::SetParam
00605         static const AkPluginParamID ALL_PLUGIN_DATA_ID = 0x7FFF;
00606     };
00607 
00608     /// Wwise sound engine plug-in interface. Shared functionality across different plug-in types.
00609     /// \aknote The implementer of this interface should also expose a static creation function
00610     /// that will return a new plug-in instance when required (see \ref soundengine_plugins). \endaknote
00611     class IAkPlugin
00612     {
00613     protected:
00614         /// Virtual destructor on interface to avoid warnings.
00615         virtual ~IAkPlugin(){}
00616 
00617     public:
00618         /// Release the resources upon termination of the plug-in.
00619         /// \return AK_Success if successful, AK_Fail otherwise
00620         /// \aknote The self-destruction of the plug-in must be done using AK_PLUGIN_DELETE() macro. \endaknote
00621         /// \sa
00622         /// - \ref iakeffect_term
00623         virtual AKRESULT Term(
00624             IAkPluginMemAlloc * in_pAllocator   ///< Interface to memory allocator to be used by the plug-in
00625             ) = 0;
00626 
00627         /// The reset action should perform any actions required to reinitialize the state of the plug-in
00628         /// to its original state (e.g. after Init() or on effect bypass).
00629         /// \return AK_Success if successful, AK_Fail otherwise.
00630         /// \sa
00631         /// - \ref iakeffect_reset
00632         virtual AKRESULT Reset() = 0;
00633 
00634         /// Plug-in information query mechanism used when the sound engine requires information
00635         /// about the plug-in to determine its behavior
00636         /// \return AK_Success if successful.
00637         /// \sa
00638         /// - \ref iakeffect_geteffectinfo
00639         virtual AKRESULT GetPluginInfo(
00640             AkPluginInfo & out_rPluginInfo  ///< Reference to the plug-in information structure to be retrieved
00641             ) = 0;
00642 
00643         /// Some plug-ins are accessing Media from the Wwise sound bank system.
00644         /// If the IAkPlugin object is not using media, this function will not be used and should simply return false.
00645         /// If the IAkPlugin object is using media, the RelocateMedia feature can be optionally implemented.
00646         /// 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)
00647         ///
00648         /// \sa
00649         /// - AK::IAkPlugin::RelocateMedia
00650         virtual bool SupportMediaRelocation() const
00651         {
00652             return false;
00653         }
00654 
00655         /// Some plug-ins are accessing Media from the Wwise sound bank system.
00656         /// If the IAkPlugin object is not using media, this function will not be used.
00657         /// If the IAkPlugin object is using media, the RelocateMedia feature can be optionally implemented.
00658         /// When this function is being called, the IAkPlugin object must make the required changes to remove all
00659         /// 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.
00660         /// The change must be done within the function RelocateMedia().
00661         /// After this call, the memory space in in_pOldInMemoryData will be invalidated and cannot be used safely anymore.
00662         ///
00663         /// This function will not be called if SupportMediaRelocation returned false.
00664         ///
00665         /// \sa
00666         /// - AK::IAkPlugin::SupportMediaRelocation
00667         virtual AKRESULT RelocateMedia(
00668             AkUInt8* /*in_pNewMedia*/,
00669             AkUInt8* /*in_pOldMedia*/
00670             )
00671         {
00672             return AK_NotImplemented;
00673         }
00674 
00675     };
00676 
00677     /// Software effect plug-in interface (see \ref soundengine_plugins_effects).
00678     class IAkEffectPlugin : public IAkPlugin
00679     {
00680     protected:
00681         /// Virtual destructor on interface to avoid warnings.
00682         virtual ~IAkEffectPlugin(){}
00683 
00684     public:
00685         /// Software effect plug-in initialization. Prepares the effect for data processing, allocates memory and sets up the initial conditions.
00686         /// \aknote Memory allocation should be done through appropriate macros (see \ref fx_memory_alloc). \endaknote
00687         /// \sa
00688         /// - \ref iakmonadiceffect_init
00689         virtual AKRESULT Init(
00690             IAkPluginMemAlloc *         in_pAllocator,              ///< Interface to memory allocator to be used by the effect
00691             IAkEffectPluginContext *    in_pEffectPluginContext,    ///< Interface to effect plug-in's context
00692             IAkPluginParam *            in_pParams,                 ///< Interface to plug-in parameters
00693             AkAudioFormat &             io_rFormat                  ///< Audio data format of the input/output signal. Only an out-of-place plugin is allowed to change the channel configuration.
00694             ) = 0;
00695     };
00696 
00697     /// Software effect plug-in interface for in-place processing (see \ref soundengine_plugins_effects).
00698     class IAkInPlaceEffectPlugin : public IAkEffectPlugin
00699     {
00700     public:
00701         /// Software effect plug-in DSP execution for in-place processing.
00702         /// \aknote The effect should process all the input data (uValidFrames) as long as AK_DataReady is passed in the eState field.
00703         /// When the input is finished (AK_NoMoreData), the effect can output more sample than uValidFrames up to MaxFrames() if desired.
00704         /// All sample frames beyond uValidFrames are not initialized and it is the responsibility of the effect to do so when outputting an effect tail.
00705         /// The effect must notify the pipeline by updating uValidFrames if more frames are produced during the effect tail.
00706         /// \aknote The effect will stop being called by the pipeline when AK_NoMoreData is returned in the the eState field of the AkAudioBuffer structure.
00707         /// See \ref iakmonadiceffect_execute_general.
00708         virtual void Execute(
00709                 AkAudioBuffer *                         io_pBuffer      ///< In/Out audio buffer data structure (in-place processing)
00710                 ) = 0;
00711 
00712         /// Skips execution of some frames, when the voice is virtual playing from elapsed time.
00713         /// This can be used to simulate processing that would have taken place (e.g. update internal state).
00714         /// Return AK_DataReady or AK_NoMoreData, depending if there would be audio output or not at that point.
00715         virtual AKRESULT TimeSkip(
00716             AkUInt32 in_uFrames ///< Number of frames the audio processing should advance.
00717             ) = 0;
00718     };
00719 
00720 
00721     /// Software effect plug-in interface for out-of-place processing (see \ref soundengine_plugins_effects).
00722     class IAkOutOfPlaceEffectPlugin : public IAkEffectPlugin
00723     {
00724     public:
00725         /// Software effect plug-in for out-of-place processing.
00726         /// \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).
00727         /// 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.
00728         /// AK_DataNeeded should be used when more input data is necessary to continue processing.
00729         /// \aknote Only the output buffer eState field is looked at by the pipeline to determine the effect state.
00730         /// See \ref iakmonadiceffect_execute_outofplace.
00731         virtual void Execute(
00732                 AkAudioBuffer *                         in_pBuffer,     ///< Input audio buffer data structure
00733                 AkUInt32                                in_uInOffset,   ///< Offset position into input buffer data
00734                 AkAudioBuffer *                         out_pBuffer     ///< Output audio buffer data structure
00735                 ) = 0;
00736 
00737         /// Skips execution of some frames, when the voice is virtual playing from elapsed time.
00738         /// This can be used to simulate processing that would have taken place (e.g. update internal state).
00739         /// Return AK_DataReady or AK_NoMoreData, depending if there would be audio output or not at that point.
00740         virtual AKRESULT TimeSkip(
00741             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.
00742             ) = 0;
00743     };
00744 
00745     /// Interface to retrieve information about an input of a mixer.
00746     class IAkMixerInputContext
00747     {
00748     protected:
00749         /// Virtual destructor on interface to avoid warnings.
00750         virtual ~IAkMixerInputContext(){}
00751 
00752     public:
00753 
00754         /// Obtain the parameter blob for the mixer plugin that were attached to this input.
00755         /// \return The parameter blob, which can be safely cast into the plugin's implementation.
00756         /// If all parameters are default value, NULL is returned. It is up to the plugin's implementation to know
00757         /// what the default values are.
00758         virtual IAkPluginParam * GetInputParam() = 0;
00759 
00760         /// Obtain the interface to access the voice info of this input.
00761         /// \return The interface to voice info. NULL when the input is not a voice but the output of another bus instead.
00762         virtual IAkVoicePluginInfo * GetVoiceInfo() = 0;
00763 
00764         /// Query the nature of the connection between this input and the mixer.
00765         /// \return The connection type (direct/dry, user-defined auxiliary send, game-defined auxiliary send). Bus inputs are always "direct".
00766         virtual AkConnectionType GetConnectionType() = 0;
00767 
00768         /// Get internal ID of sound associated to this input.
00769         /// In the case of a voice, the ID is internal but corresponds to what you would get from the duration
00770         /// callback (see AkDurationCallbackInfo::audioNodeID). In the case of a bus, it can be matched with the bus name converted
00771         /// to a unique ID using AK::SoundEngine::GetIDFromString().
00772         /// \return ID of input.
00773         /// \sa
00774         /// - AkDurationCallbackInfo
00775         /// - AK::SoundEngine::PostEvent()
00776         /// - AK::SoundEngine::GetIDFromString()
00777         virtual AkUniqueID GetAudioNodeID() = 0;
00778 
00779         /// Use this method to retrieve user data to this context. It is always initialized to NULL until you decide to set it otherwise.
00780         /// \return Attached user data.
00781         /// \sa SetUserData()
00782         virtual void * GetUserData() = 0;
00783 
00784         /// Use this method to attach user data to this context. It is always initialized to NULL until you decide to set it otherwise.
00785         /// \return Attached user data.
00786         /// \sa GetUserData()
00787         virtual void SetUserData( void * in_pUserData ) = 0;
00788 
00789         /// \name Default positioning information.
00790         /// \warning The methods of this group are deprecated.
00791         //@{
00792 
00793         /// Retrieve center percentage of this input.
00794         /// \return Center percentage, between 0 and 1.
00795         virtual AkReal32 GetCenterPerc() = 0;
00796 
00797         /// Retrieve the speaker panning type: type of panning logic when object is not 3D spatialized.
00798         /// Note that the returned value is only relevant when the object is not 3D spatialized,
00799         /// that is Get3DSpatializationMode returns AK_SpatializationMode_None.
00800         /// \sa
00801         /// - Get3DSpatializationMode()
00802         virtual AkSpeakerPanningType GetSpeakerPanningType() = 0;
00803 
00804         /// Speaker panning:
00805         /// Retrieve the panner position (each vector component is between -1 and 1) of this input.
00806         /// Note that the returned value is only relevant when the object is not 3D spatialized,
00807         /// (Get3DSpatializationMode returns AK_SpatializationMode_None), and if speaker panning is not direct assignment
00808         /// (GetSpeakerPanningType does not return AK_DirectSpeakerAssignment).
00809         /// \sa
00810         /// - GetSpeakerPanningType()
00811         /// - Get3DSpatializationMode()
00812         virtual void GetPannerPosition(
00813             AkVector & out_position         ///< Returned sound position.
00814             ) = 0;
00815 
00816         /// Get the value of this input's Listener Relative Routing option, that is, if the emitter-listener relative 
00817         /// association is calculated at this node. Listener Relative Routing needs to be calculated in order for a node
00818         /// to be spatialized or attenuated with respect to in-game emitter and listener positions. Otherwise it can only
00819         /// be panned.
00820         /// \sa
00821         /// - Get3DSpatializationMode()
00822         /// - Get3DPositionType()
00823         /// - GetNum3DPositions()
00824         virtual bool HasListenerRelativeRouting() = 0;
00825 
00826         /// Get whether the emitter position is defined by the game alone (AK_3DPositionType_Emitter), or if it is further automated 
00827         /// (AK_3DPositionType_EmitterWithAutomation, AK_3DPositionType_ListenerWithAutomation).
00828         /// The resulting 3D position(s) may be obtained by Get3DPosition(), and used for 3D spatialization or attenuation.
00829         /// \sa
00830         /// - Get3DPosition()
00831         /// - GetNum3DPositions()
00832         /// - HasListenerRelativeRouting()
00833         virtual Ak3DPositionType Get3DPositionType() = 0;
00834 
00835         /// 3D spatialization:
00836         /// Retrieve the number of emitter-listener pairs (rays) of this input.
00837         /// Note that the returned value is always 0 unless the input has listener relative routing (see HasListenerRelativeRouting()).
00838         /// Use this function with Get3DPosition().
00839         /// \sa
00840         /// - Get3DPosition()
00841         /// - HasListenerRelativeRouting()
00842         virtual AkUInt32 GetNum3DPositions() = 0;
00843 
00844         /// 3D spatialization:
00845         /// Retrieve the spherical coordinates of the desired emitter-listener pair (ray) corresponding to this
00846         /// input, as automated by the engine. Applicable only when the input has listener relative routing (see HasListenerRelativeRouting()).
00847         /// Returned rays are those that result from engine automation, if applicable.
00848         /// \return AK_Success if the pair index is valid, AK_Fail otherwise.
00849         /// \sa
00850         /// - HasListenerRelativeRouting()
00851         /// - GetNum3DPositions()
00852         virtual AKRESULT Get3DPosition(
00853             AkUInt32 in_uIndex,                         ///< Index of the pair, [0, GetNum3DPositions()[
00854             AkEmitterListenerPair & out_soundPosition   ///< Returned sound position, in spherical coordinates.
00855             ) = 0;
00856 
00857         /// 3D spatialization:
00858         /// Evaluate spread value at the distance of the desired emitter-listener pair for this input.
00859         /// Applicable only when the input has listener relative routing (see HasListenerRelativeRouting()).
00860         /// \return The spread value, between 0 and 100. 0 if the pair index is invalid.
00861         /// \sa
00862         /// - HasListenerRelativeRouting()
00863         /// - GetNum3DPositions()
00864         /// - Get3DPosition()
00865         virtual AkReal32 GetSpread(
00866             AkUInt32 in_uIndex              ///< Index of the pair, [0, GetNum3DPositions()[
00867             ) = 0;
00868 
00869         /// 3D spatialization:
00870         /// Evaluate focus value at the distance of the desired emitter-listener pair for this input.
00871         /// Applicable only when the input has listener relative routing (see HasListenerRelativeRouting()).
00872         /// \return The focus value, between 0 and 100. 0 if the pair index is invalid.
00873         /// \sa
00874         /// - HasListenerRelativeRouting()
00875         /// - GetNum3DPositions()
00876         /// - Get3DPosition()
00877         virtual AkReal32 GetFocus(
00878             AkUInt32 in_uIndex              ///< Index of the pair, [0, GetNum3DPositions()[
00879             ) = 0;
00880 
00881         /// Get the max distance as defined in the attenuation editor.
00882         /// Applicable only when the input has listener relative routing (see HasListenerRelativeRouting()).
00883         /// \return True if this input has attenuation, false otherwise.
00884         virtual bool GetMaxAttenuationDistance(
00885             AkReal32 & out_fMaxAttenuationDistance  ///< Returned max distance.
00886             ) = 0;
00887 
00888         /// Get next volumes as computed by the sound engine for this input.
00889         virtual void GetSpatializedVolumes(
00890             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).
00891             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).
00892             ) = 0;
00893 
00894         /// Query the 3D spatialization mode used by this input.
00895         /// Applicable only when the input has listener relative routing (see HasListenerRelativeRouting()).
00896         /// \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.
00897         /// \sa
00898         /// - HasListenerRelativeRouting()
00899         virtual Ak3DSpatializationMode Get3DSpatializationMode() = 0;
00900 
00901         //@}
00902     };
00903 
00904     /// Interface to retrieve contextual information for a sink plugin.
00905     /// \sa
00906     /// - AK::IAkSinkPlugin
00907     class IAkSinkPluginContext : public IAkPluginContextBase
00908     {
00909     protected:
00910         /// Virtual destructor on interface to avoid warnings.
00911         virtual ~IAkSinkPluginContext(){}
00912 
00913     public:
00914 
00915         /// Query if the sink plugin is instantiated on the main output device (primary tree).
00916         /// \return True if the sink plugin is instantiated on the main output device (primary tree), false otherwise.
00917         /// \sa
00918         /// - AK::IAkSinkPlugin::IsDataNeeded()
00919         /// - AK::IAkSinkPlugin::Consume()
00920         virtual bool IsPrimary() = 0;
00921 
00922         /// Sink plugins may need to call this function to notify the audio thread that it should wake up
00923         /// in order to potentially process an audio frame. Note that the audio thread may wake up for other
00924         /// reasons, for example following calls to AK::SoundEngine::RenderAudio().
00925         /// Once the audio thread is awaken, it will ask the sink plugin how many audio frames need to be
00926         /// processed and presented to the plugin. This is done through AK::IAkSinkPlugin::IsDataNeeded()
00927         /// and AK::IAkSinkPlugin::Consume() respectively.
00928         /// Note that only the sink plugin that is instantiated on the main output device (primary tree) may control
00929         /// the audio thread synchronization.
00930         /// \return AK_Success if the calling plugin is instantiated on the main output device (primary tree),
00931         /// AK_Fail otherwise.
00932         /// \sa
00933         /// - AK::IAkSinkPluginContext::IsPrimary()
00934         /// - AK::IAkSinkPlugin::IsDataNeeded()
00935         /// - AK::IAkSinkPlugin::Consume()
00936         virtual AKRESULT SignalAudioThread() = 0;
00937 
00938         /// Query engine's user-defined sink queue depth (AkPlatformInitSettings::uNumRefillsInVoice).
00939         /// \return The engine's AkPlatformInitSettings::uNumRefillsInVoice value on platforms for which it exists, 0 otherwise.
00940         virtual AkUInt16 GetNumRefillsInVoice() = 0;
00941     };
00942 
00943     /// Software effect plug-in interface for sink (audio end point) plugins.
00944     class IAkSinkPlugin : public IAkPlugin
00945     {
00946     protected:
00947         /// Virtual destructor on interface to avoid warnings.
00948         virtual ~IAkSinkPlugin(){}
00949 
00950     public:
00951 
00952         /// Initialization of the sink plugin.
00953         ///
00954         /// This method prepares the audio device plug-in for data processing, allocates memory, and sets up initial conditions.
00955         /// 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.
00956         /// The AK::IAkSinkPluginContext interface allows to retrieve information related to the context in which the audio device plug-in is operated.
00957         /// 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.
00958         /// 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.
00959         /// 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.
00960         /// Note that the channel configuration is suggestive and may even be specified as !AkChannelConfig::IsValid().The plugin is free to determine the true channel configuration(this is an io parameter).
00961         ///
00962         /// \return AK_Success if successful.
00963         /// \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.
00964         /// \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.
00965         /// All other return codes will be treated as temporary failures conditions and the sink will be requested again later.
00966 
00967         virtual AKRESULT Init(
00968             IAkPluginMemAlloc *     in_pAllocator,          ///< Interface to memory allocator to be used by the effect.
00969             IAkSinkPluginContext *  in_pSinkPluginContext,  ///< Interface to sink plug-in's context.
00970             IAkPluginParam *        in_pParams,             ///< Interface to plug-in parameters.
00971             AkAudioFormat &         io_rFormat              ///< Audio data format of the input signal. Note that the channel configuration is suggestive and may even be specified as !AkChannelConfig::IsValid(). The plugin is free to determine the true channel configuration.
00972             ) = 0;
00973 
00974         /// Obtain the number of audio frames that should be processed by the sound engine and presented
00975         /// to this plugin via AK::IAkSinkPlugin::Consume(). The size of a frame is determined by the sound engine and
00976         /// obtainable via AK::IAkPluginContextBase::GetMaxBufferLength().
00977         /// \return AK_Success if successful, AK_Fail if there was a critical error.
00978         /// \sa
00979         /// - AK::IAkSinkPlugin::Consume()
00980         /// - AK::IAkSinkPluginContext::SignalAudioThread()
00981         virtual AKRESULT IsDataNeeded(
00982             AkUInt32 &              out_uNumFramesNeeded    ///< Returned number of audio frames needed.
00983             ) = 0;
00984 
00985         /// Present an audio buffer to the sink. The audio buffer is in the native format of the sound engine
00986         /// (typically float, deinterleaved), as specified by io_rFormat passed to Init(). It is up to the
00987         /// plugin to transform it into a format that is compatible with its output.
00988         /// Note that Consume() is not called if the output for this frame consists of silence. Plugins should
00989         /// detect this in OnFrameEnd().
00990         /// \sa
00991         /// - AK::IAkSinkPlugin::IsDataNeeded()
00992         /// - AK::IAkSinkPlugin::OnFrameEnd()
00993         virtual void Consume(
00994             AkAudioBuffer *         in_pInputBuffer,        ///< Input audio buffer data structure. Plugins should avoid processing data in-place.
00995             AkRamp                  in_gain                 ///< Volume gain to apply to this input (prev corresponds to the beginning, next corresponds to the end of the buffer).
00996             ) = 0;
00997 
00998         /// 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.  
00999         /// \sa
01000         /// - AK::IAkSinkPlugin::Consume()
01001         virtual void OnFrameEnd() = 0;
01002 
01003         /// Ask the plug-in whether starvation occurred.
01004         /// \return True if starvation occurred, false otherwise.
01005         virtual bool IsStarved() = 0;
01006 
01007         /// Reset the "starvation" flag after IsStarved() returned true.
01008         virtual void ResetStarved() = 0;        
01009     };
01010 
01011     /// Wwise sound engine source plug-in interface (see \ref soundengine_plugins_source).
01012     class IAkSourcePlugin : public IAkPlugin
01013     {
01014     protected:
01015         /// Virtual destructor on interface to avoid warnings.
01016         virtual ~IAkSourcePlugin(){}
01017 
01018     public:
01019         /// Source plug-in initialization. Gets the plug-in ready for data processing, allocates memory and sets up the initial conditions.
01020         /// \aknote Memory allocation should be done through the appropriate macros (see \ref fx_memory_alloc). \endaknote
01021         /// \sa
01022         /// - \ref iaksourceeffect_init
01023         virtual AKRESULT Init(
01024             IAkPluginMemAlloc *         in_pAllocator,                  ///< Interface to the memory allocator to be used by the plug-in
01025             IAkSourcePluginContext *    in_pSourcePluginContext,        ///< Interface to the source plug-in's context
01026             IAkPluginParam *            in_pParams,                     ///< Interface to the plug-in parameters
01027             AkAudioFormat &             io_rFormat                      ///< Audio format of the output data to be produced by the plug-in (mono native by default)
01028             ) = 0;
01029 
01030         /// This method is called to determine the approximate duration of the source.
01031         /// \return The duration of the source, in milliseconds.
01032         /// \sa
01033         /// - \ref iaksourceeffect_getduration
01034         virtual AkReal32 GetDuration() const = 0;
01035 
01036         /// This method is called to determine the estimated envelope of the source.
01037         /// \return The estimated envelope of the data that will be generated in the next call to
01038         /// Execute(). The envelope value should be normalized to the highest peak of the entire
01039         /// duration of the source. Expected range is [0,1]. If envelope and peak value cannot be
01040         /// predicted, the source should return 1 (no envelope).
01041         /// \sa
01042         /// - \ref iaksourceeffect_getenvelope
01043         virtual AkReal32 GetEnvelope() const
01044         {
01045             return 1.f;
01046         }
01047 
01048         /// This method is called to tell the source to stop looping.
01049         /// This will typically be called when an action of type "break" will be triggered on the playing source.
01050         /// 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.
01051         ///
01052         /// \return
01053         /// - 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.
01054         /// - AK_Fail if the source cannot simply stop looping, in this situation, the break command will end up stopping this source.
01055         /// \sa
01056         /// - \ref iaksourceeffect_stoplooping
01057         virtual AKRESULT StopLooping(){ return AK_Success; }
01058 
01059         /// This method is called to tell the source to seek to an arbitrary sample.
01060         /// This will typically be called when the game calls AK::SoundEngine::SeekOnEvent() where the event plays
01061         /// a sound that wraps this source plug-in.
01062         /// If the plug-in does not handle seeks, it should return AK_Success. If it returns AK_Fail, it will
01063         /// be terminated by the sound engine.
01064         ///
01065         /// \return
01066         /// - AK_Success if the source handles or ignores seek command.
01067         /// - AK_Fail if the source considers that seeking requests should provoke termination, for example, if
01068         ///     the desired position is greater than the prescribed source duration.
01069         /// \sa
01070         /// - AK::SoundEngine::SeekOnEvent()
01071         virtual AKRESULT Seek(
01072             AkUInt32 /* in_uPosition */ ///< Position to seek to, in samples, at the rate specified in AkAudioFormat (see AK::IAkSourcePlugin::Init()).
01073             ) { return AK_Success; }
01074 
01075         /// 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
01076         /// avoiding most of the CPU hit of plug-in execution.
01077         /// 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
01078         /// return AK_DataReady or AK_NoMoreData, depending if there would be audio output or not at that point.
01079         /// 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.
01080         /// Note that returning AK_NotImplemeted for a source plug-ins that support asynchronous processing will produce a 'resume' virtual voice behavior instead.
01081         virtual AKRESULT TimeSkip(
01082             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.
01083             ) { return AK_NotImplemented; }
01084 
01085         /// Software effect plug-in DSP execution.
01086         /// \aknote The effect can output as much as wanted up to MaxFrames(). All sample frames passed uValidFrames at input time are
01087         /// not initialized and it is the responsibility of the effect to do so. When modifying the number of valid frames within execution
01088         /// (e.g. to flush delay lines) the effect should notify the pipeline by updating uValidFrames accordingly.
01089         /// \aknote The effect will stop being called by the pipeline when AK_NoMoreData is returned in the the eState field of the AkAudioBuffer structure.
01090         virtual void Execute(
01091                 AkAudioBuffer *                         io_pBuffer      ///< In/Out audio buffer data structure (in-place processing)
01092                 ) = 0;
01093     };
01094 
01095 
01096     /// This function can be useful to convert from normalized floating point audio samples to HW-pipeline format samples.
01097     #define AK_FLOAT_TO_SAMPLETYPE( __in__ ) (__in__)
01098     /// 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.
01099     #define AK_FLOAT_TO_SAMPLETYPE_NOCLIP( __in__ ) (__in__)
01100     /// This function can be useful to convert from HW-pipeline format samples to normalized floating point audio samples.
01101     #define AK_SAMPLETYPE_TO_FLOAT( __in__ ) (__in__)
01102 
01103     #define AK_DBTOLIN( __db__ ) (powf(10.f,(__db__) * 0.05f))
01104 }
01105 
01106 /// Registered plugin creation function prototype.
01107 AK_CALLBACK( AK::IAkPlugin*, AkCreatePluginCallback )( AK::IAkPluginMemAlloc * in_pAllocator );
01108 /// Registered plugin parameter node creation function prototype.
01109 AK_CALLBACK( AK::IAkPluginParam*, AkCreateParamCallback )( AK::IAkPluginMemAlloc * in_pAllocator );
01110 
01111 struct AkPlatformInitSettings;
01112 struct AkInitSettings;
01113 
01114 namespace AK
01115 {
01116     /// Global plugin context used for plugin registration/initialization. Games query this interface from the sound engine.
01117     class IAkGlobalPluginContext
01118     {
01119     protected:
01120         /// Virtual destructor on interface to avoid warnings.
01121         virtual ~IAkGlobalPluginContext(){}
01122 
01123     public:
01124 
01125         /// Retrieve the streaming manager access interface.
01126         virtual IAkStreamMgr * GetStreamMgr() const = 0;
01127 
01128         /// Retrieve the maximum number of frames that Execute() will be called with for this effect.
01129         /// Can be used by the effect to make memory allocation at initialization based on this worst case scenario.
01130         /// \return Maximum number of frames.
01131         virtual AkUInt16 GetMaxBufferLength() const = 0;
01132 
01133         /// Query whether sound engine is in real-time or offline (faster than real-time) mode.
01134         /// \return true when sound engine is in offline mode, false otherwise.
01135         virtual bool IsRenderingOffline() const = 0;
01136 
01137         /// Retrieve the core sample rate of the engine. This sample rate applies to all effects except source plugins, which declare their own sample rate.
01138         /// \return Core sample rate.
01139         virtual AkUInt32 GetSampleRate() const = 0;
01140 
01141         /// Post a monitoring message or error string. This will be displayed in the Wwise capture
01142         /// log.
01143         /// \return AK_Success if successful, AK_Fail if there was a problem posting the message.
01144         ///         In optimized mode, this function returns AK_NotCompatible.
01145         /// \remark This function is provided as a tracking tool only. It does nothing if it is
01146         ///         called in the optimized/release configuration and return AK_NotCompatible.
01147         virtual AKRESULT PostMonitorMessage(
01148             const char* in_pszError,                ///< Message or error string to be displayed
01149             AK::Monitor::ErrorLevel in_eErrorLevel  ///< Specifies whether it should be displayed as a message or an error
01150             ) = 0;
01151 
01152         /// Register a plug-in with the sound engine and set the callback functions to create the
01153         /// plug-in and its parameter node.
01154         /// \sa
01155         /// - \ref register_effects
01156         /// - \ref plugin_xml
01157         /// \return AK_Success if successful, AK_InvalidParameter if invalid parameters were provided or Ak_Fail otherwise. Possible reasons for an AK_Fail result are:
01158         /// - Insufficient memory to register the plug-in
01159         /// - Plug-in ID already registered
01160         /// \remarks
01161         /// Codecs and plug-ins must be registered before loading banks that use them.\n
01162         /// Loading a bank referencing an unregistered plug-in or codec will result in a load bank success,
01163         /// but the plug-ins will not be used. More specifically, playing a sound that uses an unregistered effect plug-in
01164         /// will result in audio playback without applying the said effect. If an unregistered source plug-in is used by an event's audio objects,
01165         /// posting the event will fail.
01166         virtual AKRESULT RegisterPlugin(
01167             AkPluginType in_eType,                      ///< Plug-in type (for example, source or effect)
01168             AkUInt32 in_ulCompanyID,                    ///< Company identifier (as declared in the plug-in description XML file)
01169             AkUInt32 in_ulPluginID,                     ///< Plug-in identifier (as declared in the plug-in description XML file)
01170             AkCreatePluginCallback in_pCreateFunc,      ///< Pointer to the plug-in's creation function
01171             AkCreateParamCallback in_pCreateParamFunc   ///< Pointer to the plug-in's parameter node creation function
01172             ) = 0;
01173 
01174         /// Register a codec type with the sound engine and set the callback functions to create the
01175         /// codec's file source and bank source nodes.
01176         /// \sa
01177         /// - \ref register_effects
01178         /// \return AK_Success if successful, AK_InvalidParameter if invalid parameters were provided, or Ak_Fail otherwise. Possible reasons for an AK_Fail result are:
01179         /// - Insufficient memory to register the codec
01180         /// - Codec ID already registered
01181         /// \remarks
01182         /// Codecs and plug-ins must be registered before loading banks that use them.\n
01183         /// Loading a bank referencing an unregistered plug-in or codec will result in a load bank success,
01184         /// but the plug-ins will not be used. More specifically, playing a sound that uses an unregistered effect plug-in
01185         /// will result in audio playback without applying the said effect. If an unregistered source plug-in is used by an event's audio objects,
01186         /// posting the event will fail.
01187         virtual AKRESULT RegisterCodec(
01188             AkUInt32 in_ulCompanyID,                        ///< Company identifier (as declared in XML)
01189             AkUInt32 in_ulPluginID,                         ///< Plugin identifier (as declared in XML)
01190             AkCreateFileSourceCallback in_pFileCreateFunc,  ///< Factory for streaming sources.
01191             AkCreateBankSourceCallback in_pBankCreateFunc   ///< Factory for in-memory sources.
01192             ) = 0;
01193 
01194         /// Register a global callback function. This function will be called from the audio rendering thread, at the
01195         /// location specified by in_eLocation. This function will also be called from the thread calling
01196         /// AK::SoundEngine::Term with in_eLocation set to AkGlobalCallbackLocation_Term.
01197         /// For example, in order to be called at every audio rendering pass, and once during teardown for releasing resources, you would call
01198         /// RegisterGlobalCallback(AkPluginTypeEffect, MY_COMPANY_ID , MY_PLUGIN_ID, myCallback, AkGlobalCallbackLocation_BeginRender | AkGlobalCallbackLocation_Term, myCookie);
01199         /// \remarks
01200         /// 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.
01201         /// 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).
01202         /// Timers will be registered to callbacks at all locations except for AkGlobalCallbackLocation_Register and AkGlobalCallbackLocation_Term.
01203         /// It is illegal to call this function while already inside of a global callback.
01204         /// This function might stall for several milliseconds before returning.
01205         /// \sa
01206         /// - AK::IAkGlobalPluginContext::UnregisterGlobalCallback()
01207         /// - AkGlobalCallbackFunc
01208         /// - AkGlobalCallbackLocation
01209         virtual AKRESULT RegisterGlobalCallback(
01210             AkPluginType in_eType,                          ///< A valid Plug-in type (for example, source or effect).
01211             AkUInt32 in_ulCompanyID,                        ///< Company identifier (as declared in the plug-in description XML file). 
01212             AkUInt32 in_ulPluginID,                         ///< Plug-in identifier (as declared in the plug-in description XML file).
01213             AkGlobalCallbackFunc in_pCallback,              ///< Function to register as a global callback.
01214             AkUInt32 in_eLocation = AkGlobalCallbackLocation_BeginRender, ///< Callback location defined in AkGlobalCallbackLocation. Bitwise OR multiple locations if needed.
01215             void * in_pCookie = NULL                        ///< User cookie.
01216             ) = 0;
01217 
01218         /// Unregister a global callback function, previously registered using RegisterGlobalCallback.
01219         /// \remarks
01220         /// It is legal to call this function while already inside of a global callback, If it is unregistering itself and not
01221         /// another callback.
01222         /// This function might stall for several milliseconds before returning.
01223         /// \sa
01224         /// - AK::IAkGlobalPluginContext::RegisterGlobalCallback()
01225         /// - AkGlobalCallbackFunc
01226         /// - AkGlobalCallbackLocation
01227         virtual AKRESULT UnregisterGlobalCallback(
01228             AkGlobalCallbackFunc in_pCallback,              ///< Function to unregister as a global callback.
01229             AkUInt32 in_eLocation = AkGlobalCallbackLocation_BeginRender ///< Must match in_eLocation as passed to RegisterGlobalCallback for this callback.
01230             ) = 0;
01231 
01232         /// Get the default allocator for plugins. This is useful for performing global initialization tasks shared across multiple plugin instances.
01233         virtual AK::IAkPluginMemAlloc * GetAllocator() = 0;
01234 
01235         /// \sa SetRTPCValue
01236         virtual AKRESULT SetRTPCValue(
01237             AkRtpcID in_rtpcID,                                     ///< ID of the game parameter
01238             AkRtpcValue in_value,                                   ///< Value to set
01239             AkGameObjectID in_gameObjectID = AK_INVALID_GAME_OBJECT,///< Associated game object ID
01240             AkTimeMs in_uValueChangeDuration = 0,                   ///< Duration during which the game parameter is interpolated towards in_value
01241             AkCurveInterpolation in_eFadeCurve = AkCurveInterpolation_Linear,   ///< Curve type to be used for the game parameter interpolation
01242             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.
01243             ) = 0;
01244 
01245         /// Send custom game data to a plugin that resides on a bus (insert effect or mixer plugin).
01246         /// Data will be copied and stored into a separate list.
01247         /// Previous entry is deleted when a new one is sent.
01248         /// Set the data pointer to NULL to clear item from the list.
01249         /// This means that you cannot send different data to various instances of the plugin on a same bus.\endaknote
01250         /// \return AK_Success if data was sent successfully.
01251         virtual AKRESULT SendPluginCustomGameData(
01252             AkUniqueID in_busID,            ///< Bus ID
01253             AkGameObjectID in_busObjectID,  ///< Bus Object ID
01254             AkPluginType in_eType,          ///< Plug-in type (for example, source or effect)
01255             AkUInt32 in_uCompanyID,     ///< Company identifier (as declared in the plug-in description XML file)
01256             AkUInt32 in_uPluginID,          ///< Plug-in identifier (as declared in the plug-in description XML file)
01257             const void* in_pData,           ///< The data blob
01258             AkUInt32 in_uSizeInBytes        ///< Size of data
01259             ) = 0;
01260 
01261         /// N to N channels mix
01262         virtual void MixNinNChannels(
01263             AkAudioBuffer * in_pInputBuffer,                ///< Input multichannel buffer.
01264             AkAudioBuffer * in_pMixBuffer,                  ///< Multichannel buffer with which the input buffer is mixed.
01265             AkReal32        in_fPrevGain,                   ///< Gain, corresponding to the beginning of the buffer, to apply uniformly to each mixed channel.
01266             AkReal32        in_fNextGain,                   ///< Gain, corresponding to the end of the buffer, to apply uniformly to each mixed channel.
01267             AK::SpeakerVolumes::ConstMatrixPtr in_mxPrevVolumes,///< In/out channel volume distribution corresponding to the beginning of the buffer (see AK::SpeakerVolumes::Matrix services).
01268             AK::SpeakerVolumes::ConstMatrixPtr in_mxNextVolumes ///< In/out channel volume distribution corresponding to the end of the buffer (see AK::SpeakerVolumes::Matrix services).
01269             ) = 0;
01270 
01271         /// 1 to N channels mix
01272         virtual void Mix1inNChannels(
01273             AkReal32 * AK_RESTRICT in_pInChannel,           ///< Input channel buffer.
01274             AkAudioBuffer * in_pMixBuffer,                  ///< Multichannel buffer with which the input buffer is mixed.
01275             AkReal32        in_fPrevGain,                   ///< Gain, corresponding to the beginning of the input channel.
01276             AkReal32        in_fNextGain,                   ///< Gain, corresponding to the end of the input channel.
01277             AK::SpeakerVolumes::ConstVectorPtr in_vPrevVolumes, ///< Output channel volume distribution corresponding to the beginning of the buffer (see AK::SpeakerVolumes::Vector services).
01278             AK::SpeakerVolumes::ConstVectorPtr in_vNextVolumes  ///< Output channel volume distribution corresponding to the end of the buffer (see AK::SpeakerVolumes::Vector services).
01279             ) = 0;
01280 
01281         /// Single channel mix
01282         virtual void MixChannel(
01283             AkReal32 * AK_RESTRICT in_pInBuffer,            ///< Input channel buffer.
01284             AkReal32 * AK_RESTRICT in_pOutBuffer,           ///< Output channel buffer.
01285             AkReal32        in_fPrevGain,                   ///< Gain, corresponding to the beginning of the input channel.
01286             AkReal32        in_fNextGain,                   ///< Gain, corresponding to the end of the input channel.
01287             AkUInt16        in_uNumFrames                   ///< Number of frames to mix.
01288             ) = 0;
01289 
01290         /// Computes gain vector for encoding a source with angles in_fAzimuth and in_fElevation to full-sphere ambisonics with order in_uOrder.
01291         /// Ambisonic channels are ordered by ACN and use the SN3D convention.
01292         virtual void ComputeAmbisonicsEncoding(
01293             AkReal32            in_fAzimuth,                ///< Incident angle, in radians [-pi,pi], where 0 is the front (positive values are clockwise).
01294             AkReal32            in_fElevation,              ///< Incident angle, in radians [-pi/2,pi/2], where 0 is the azimuthal plane.
01295             AkChannelConfig     in_cfgAmbisonics,           ///< Determines number of gains in vector out_vVolumes.
01296             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. You may obtain the number of channels from the order using the helper AK::AmbisonicOrderToNumChannels().
01297             ) = 0;
01298 
01299         /// 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 
01300         /// expressed in left-handed cartesian coordinates, with unitary norm.
01301         /// This decoding technique is optimal for regular sampling.
01302         /// The returned matrix has in_cfgAmbisonics.uNumChannels inputs (rows) and in_uNumSamples outputs (columns), and is normalized by the number of samples. 
01303         /// Supported ambisonic configurations are full-sphere 1st, 2nd and 3rd order.
01304         /// \return AK_Fail when ambisonic configuration. AK_Success otherwise.
01305         virtual AKRESULT ComputeWeightedAmbisonicsDecodingFromSampledSphere(
01306             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.
01307             AkUInt32            in_uNumSamples,             ///< Number of points in in_samples.
01308             AkChannelConfig     in_cfgAmbisonics,           ///< Ambisonic configuration. Supported configurations are 1-1, 2-2 and 3-3. Determines number of rows (input channels) in matrix out_mxVolume.
01309             AK::SpeakerVolumes::MatrixPtr out_mxVolume      ///< Returned volume matrix (see AK::SpeakerVolumes::Matrix services). Must be allocated prior to calling this function with the size returned by AK::SpeakerVolumes::Matrix::GetRequiredSize() for the desired number of channels. You may obtain the number of channels from the order using the helper AK::AmbisonicOrderToNumChannels().
01310             ) = 0;
01311 
01312         /// Return an acoustic texture.
01313         /// \return The pointer to an acoustic texture if successful, NULL otherwise.
01314         virtual const AkAcousticTexture* GetAcousticTexture(
01315             AkAcousticTextureID in_AcousticTextureID        ///< Acoustic Texture's ID
01316             ) = 0;
01317 
01318         /// Given an emitter-listener pair, compute the azimuth and elevation angles of the emitter relative to the listener.
01319         /// \return AK_Success if the listener referenced in the emitter-listener pair was found; azimuth and elevation.
01320         virtual AKRESULT ComputeSphericalCoordinates(
01321             const AkEmitterListenerPair & in_pair,          ///< Emitter-listener pair for which to compute azimuth and elevation angles.
01322             AkReal32 & out_fAzimuth,                        ///< Returned azimuthal angle, in radians.
01323             AkReal32 & out_fElevation                       ///< Returned elevation angle, in radians.
01324             ) const = 0;
01325 
01326         /// Get the platform init settings that the wwise sound engine has been initialized with.
01327         /// This function returns a null pointer if called with an instance of RenderFXGlobalContext.
01328         virtual const AkPlatformInitSettings* GetPlatformInitSettings() const = 0;
01329         
01330         /// Get the init settings that the wwise sound engine has been initialized with
01331         /// This function returns a null pointer if called with an instance of RenderFXGlobalContext.
01332         virtual const AkInitSettings* GetInitSettings() const = 0;
01333 
01334         /// Gets the configured audio settings.
01335         /// Call this function to get the configured audio settings.
01336         /// 
01337         /// \warning This function is not thread-safe.
01338         /// \warning Call this function only after the sound engine has been properly initialized.
01339         virtual AKRESULT GetAudioSettings(
01340             AkAudioSettings &   out_audioSettings   ///< Returned audio settings
01341             ) const = 0;
01342 
01343         /// Universal converter from string to ID for the sound engine.
01344         /// Calls AK::SoundEngine::GetIDFromString.
01345         /// \sa
01346         /// - <tt>AK::SoundEngine::GetIDFromString</tt>
01347         virtual AkUInt32 GetIDFromString(const char* in_pszString) const = 0;
01348 
01349         /// Synchronously posts an Event to the sound engine (by event ID).
01350         /// The callback function can be used to be noticed when markers are reached or when the event is finished.
01351         /// An array of wave file sources can be provided to resolve External Sources triggered by the event. 
01352         /// \return The playing ID of the event launched, or AK_INVALID_PLAYING_ID if posting the event failed
01353         /// \remarks
01354         /// This function executes the actions contained in the event without going through the message queue.
01355         /// In order to do so it acquires the global Wwise sound engine lock. It should therefore only be called from one of the 
01356         /// global engine hooks (see AK::IAkGlobalPluginContext::RegisterGlobalCallback).
01357         /// Use AK::IAkGlobalPluginContext::GetIDFromString() if you use event names (strings).
01358         /// \sa 
01359         /// - <tt>AK::SoundEngine::PostEvent</tt>
01360         /// - <tt>AK::IAkGlobalPluginContext::RegisterGlobalCallback</tt>
01361         /// - <tt>AK::IAkGlobalPluginContext::GetIDFromString</tt>
01362         virtual AkPlayingID PostEventSync(
01363             AkUniqueID in_eventID,                          ///< Unique ID of the event
01364             AkGameObjectID in_gameObjectID,                 ///< Associated game object ID
01365             AkUInt32 in_uFlags = 0,                         ///< Bitmask: see \ref AkCallbackType
01366             AkCallbackFunc in_pfnCallback = NULL,           ///< Callback function
01367             void * in_pCookie = NULL,                       ///< Callback cookie that will be sent to the callback function along with additional information
01368             AkUInt32 in_cExternals = 0,                     ///< Optional count of external source structures
01369             AkExternalSourceInfo *in_pExternalSources = NULL,///< Optional array of external source resolution information
01370             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.
01371             ) = 0;
01372         
01373         /// Executes a number of MIDI Events on all nodes that are referenced in the specified Event in an Action of type Play.
01374         /// Each MIDI event will be posted in AkMIDIPost::uOffset samples from the start of the current frame. The duration of
01375         /// a sample can be determined from the sound engine's audio settings, via a call to AK::IAkGlobalPluginContext::GetAudioSettings.
01376         /// \remarks
01377         /// This function executes the MIDI Events without going through the message queue.
01378         /// In order to do so it acquires the global Wwise sound engine lock. It should therefore only be called from one of the 
01379         /// global engine hooks (see AK::IAkGlobalPluginContext::RegisterGlobalCallback).
01380         /// Use AK::IAkGlobalPluginContext::GetIDFromString() if you use event names (strings).
01381         /// \sa 
01382         /// - <tt>AK::SoundEngine::PostMIDIOnEvent</tt>
01383         /// - <tt>AK::IAkGlobalPluginContext::GetAudioSettings</tt>
01384         /// - <tt>AK::IAkGlobalPluginContext::StopMIDIOnEventSync</tt>
01385         /// - <tt>AK::IAkGlobalPluginContext::RegisterGlobalCallback</tt>
01386         /// - <tt>AK::IAkGlobalPluginContext::GetIDFromString</tt>
01387         virtual AKRESULT PostMIDIOnEventSync(
01388             AkUniqueID in_eventID,                                          ///< Unique ID of the Event
01389             AkGameObjectID in_gameObjectID,                                 ///< Associated game object ID
01390             AkMIDIPost* in_pPosts,                                          ///< MIDI Events to post
01391             AkUInt16 in_uNumPosts                                           ///< Number of MIDI Events to post
01392             ) = 0;
01393 
01394         /// Stops MIDI notes on all nodes that are referenced in the specified event in an action of type play,
01395         /// with the specified Game Object. Invalid parameters are interpreted as wildcards. For example, calling
01396         /// this function with in_eventID set to AK_INVALID_UNIQUE_ID will stop all MIDI notes for Game Object
01397         /// in_gameObjectID.
01398         /// \remarks
01399         /// This function stops the MIDI notes without going through the message queue.
01400         /// In order to do so it acquires the global Wwise sound engine lock. It should therefore only be called from one of the 
01401         /// global engine hooks (see AK::IAkGlobalPluginContext::RegisterGlobalCallback).
01402         /// Use AK::IAkGlobalPluginContext::GetIDFromString() if you use event names (strings).
01403         /// \sa
01404         /// - <tt>AK::IAkGlobalPluginContext::PostMIDIOnEvent</tt>
01405         /// - <tt>AK::IAkGlobalPluginContext::GetIDFromString</tt>
01406         virtual AKRESULT StopMIDIOnEventSync(
01407             AkUniqueID in_eventID = AK_INVALID_UNIQUE_ID,                   ///< Unique ID of the Event
01408             AkGameObjectID in_gameObjectID = AK_INVALID_GAME_OBJECT         ///< Associated game object ID
01409             ) = 0;
01410 
01411         /// \return The gateway to platform-specific functionality
01412         /// \sa IAkPlatformContext
01413         virtual IAkPlatformContext * GetPlatformContext() const = 0;
01414     };
01415 
01416     /// 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.
01417     /// \sa \ref soundengine_plugins
01418     class PluginRegistration
01419     {
01420     public:
01421         PluginRegistration(
01422             AkPluginType in_eType,                          ///< Plugin type.
01423             AkUInt32 in_ulCompanyID,                        ///< Plugin company ID.
01424             AkUInt32 in_ulPluginID,                         ///< Plugin ID.
01425             AkCreatePluginCallback in_pCreateFunc,          ///< Plugin object factory.
01426             AkCreateParamCallback in_pCreateParamFunc,      ///< Plugin parameter object factory.
01427             AkGlobalCallbackFunc in_pRegisterCallback = NULL,   ///< Optional callback function called after successful plugin registration, with argument AkGlobalCallbackLocation_Register.
01428             void * in_pRegisterCallbackCookie = NULL            ///< Optional cookie passed to register callback function above.
01429             )
01430             : pNext(g_pAKPluginList)
01431             , m_eType(in_eType)
01432             , m_ulCompanyID(in_ulCompanyID)
01433             , m_ulPluginID(in_ulPluginID)
01434             , m_pCreateFunc(in_pCreateFunc)
01435             , m_pCreateParamFunc(in_pCreateParamFunc)
01436             , m_pFileCreateFunc(NULL)
01437             , m_pBankCreateFunc(NULL)
01438             , m_pRegisterCallback(in_pRegisterCallback)
01439             , m_pRegisterCallbackCookie(in_pRegisterCallbackCookie)
01440         {
01441             g_pAKPluginList = this;
01442         }
01443 
01444         PluginRegistration(
01445             AkUInt32 in_ulCompanyID,                        ///< Plugin company ID.
01446             AkUInt32 in_ulPluginID,                         ///< Plugin ID.
01447             AkCreateFileSourceCallback in_pCreateFile,      ///< Streamed source factory.
01448             AkCreateBankSourceCallback in_pCreateBank)      ///< In-memory source factory.
01449             : pNext(g_pAKPluginList)
01450             , m_eType(AkPluginTypeCodec)
01451             , m_ulCompanyID(in_ulCompanyID)
01452             , m_ulPluginID(in_ulPluginID)
01453             , m_pCreateFunc(NULL)
01454             , m_pCreateParamFunc(NULL)
01455             , m_pFileCreateFunc(in_pCreateFile)
01456             , m_pBankCreateFunc(in_pCreateBank)
01457             , m_pRegisterCallback(NULL)
01458             , m_pRegisterCallbackCookie(NULL)
01459         {
01460             g_pAKPluginList = this;
01461         }
01462 
01463         PluginRegistration *pNext;
01464         AkPluginType m_eType;
01465         AkUInt32 m_ulCompanyID;
01466         AkUInt32 m_ulPluginID;
01467         AkCreatePluginCallback m_pCreateFunc;
01468         AkCreateParamCallback m_pCreateParamFunc;
01469         AkCreateFileSourceCallback m_pFileCreateFunc;
01470         AkCreateBankSourceCallback m_pBankCreateFunc;
01471         AkGlobalCallbackFunc m_pRegisterCallback;
01472         void * m_pRegisterCallbackCookie;
01473     };
01474 }
01475 
01476 #define AK_IMPLEMENT_PLUGIN_FACTORY(_pluginName_, _plugintype_, _companyid_, _pluginid_) \
01477     AK::IAkPlugin* Create##_pluginName_(AK::IAkPluginMemAlloc * in_pAllocator); \
01478     AK::IAkPluginParam * Create##_pluginName_##Params(AK::IAkPluginMemAlloc * in_pAllocator); \
01479     AK::PluginRegistration _pluginName_##Registration(_plugintype_, _companyid_, _pluginid_, Create##_pluginName_, Create##_pluginName_##Params);
01480 
01481 #define AK_STATIC_LINK_PLUGIN(_pluginName_) \
01482     extern AK::PluginRegistration _pluginName_##Registration; \
01483     void *_pluginName_##_linkonceonly = (void*)&_pluginName_##Registration;
01484 
01485 #define DEFINE_PLUGIN_REGISTER_HOOK AK_DLLEXPORT AK::PluginRegistration * g_pAKPluginList = NULL;
01486 
01487 #define AK_GET_SINK_TYPE_FROM_DEVICE_KEY(_key) ((AkUInt32)(_key & 0xffffffff))
01488 #define AK_GET_DEVICE_ID_FROM_DEVICE_KEY(_key) ((AkUInt32)(_key >> 32))
01489 
01490 #endif // _IAK_PLUGIN_H_