Table of Contents

include/AK/Wwise/AudioPlugin.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 /// Wwise audio plug-in interface, used to implement the Wwise side of a source or effect plug-in.
00030 
00031 #ifndef _AK_WWISE_AUDIOPLUGIN_H
00032 #define _AK_WWISE_AUDIOPLUGIN_H
00033 
00034 #include "Undo.h"
00035 
00036 #include <AK/Wwise/Utilities.h>
00037 #include <AK/SoundEngine/Common/AkSoundEngine.h> /// Dummy assert hook definition.
00038 #include <AK/SoundEngine/Common/IAkPluginMemAlloc.h>
00039 #include <AK/Wwise/PlatformID.h>
00040 
00041 #include <float.h>
00042 
00043 // Audiokinetic namespace
00044 namespace AK
00045 {
00046     class IXmlTextReader;
00047     class IXmlTextWriter;
00048 
00049     // Audiokinetic Wwise namespace
00050     namespace Wwise
00051     {
00052         class IPluginMediaConverter
00053         {
00054         public:
00055             /// If the conversion failed the function is responsible of deleting 
00056             /// any files that may have been created, even the destination file 
00057             /// in case of error. If the function return false we will use the 
00058             /// string put in io_pError to display an error message.
00059             virtual ConversionResult ConvertFile( 
00060                 const GUID & in_guidPlatform,                   ///< The unique ID of the custom platform being converted for.
00061                 const BasePlatformID & in_basePlatform,         ///< The unique ID of the base platform being converted for.
00062                 LPCWSTR in_szSourceFile,                        ///< Source File to convert data from.
00063                 LPCWSTR in_szDestFile,                          ///< DestinationFile, must be created by the plug-in.
00064                 AkUInt32 in_uSampleRate,                        ///< The target sample rate for the converted file, passing 0 will default to the platform default
00065                 AkUInt32 in_uBlockLength,                       ///< The block length, passing 0 will default to the platform default
00066                 AK::Wwise::IProgress* in_pProgress,             ///< Optional Progress Bar controller.
00067                 IWriteString* io_pError                         ///< Optional error string that can be displayed if ConversionResult is not successful
00068                 ) = 0;
00069 
00070             virtual ULONG GetCurrentConversionSettingsHash(
00071                 const GUID & in_guidPlatform,           ///< The unique ID of the platform being converted for.
00072                 AkUInt32 in_uSampleRate = 0,            ///< The target sample rate for the converted file, passing 0 will default to the platform default.
00073                 AkUInt32 in_uBlockLength = 0            ///< The block length, passing 0 will default to the platform default.
00074                 ) = 0;
00075         };
00076 
00077         /// Plug-in property set interface. An instance of this class is created and
00078         /// assigned to each plug-in, which in turn can use it to manage its properties.
00079         /// Whenever a property name is specified, it corresponds to the property
00080         /// name set in the plug-in's XML definition file.
00081         /// \warning The functions in this interface are not thread-safe, unless stated otherwise.
00082         /// \sa
00083         /// - \ref wwiseplugin_xml_properties_tag
00084         /// - AK::Wwise::IAudioPlugin::SetPluginPropertySet()
00085         /// - \ref wwiseplugin_propertyset
00086         class IPluginPropertySet
00087         {
00088         public:
00089             /// Get the value of a property for a specified platform.
00090             /// \return True if successful, False otherwise
00091             /// \sa
00092             /// - \ref wwiseplugin_bank
00093             virtual bool GetValue( 
00094                 const GUID & in_guidPlatform,   ///< The unique ID of the queried platform
00095                 LPCWSTR in_pszPropertyName,     ///< The name of the property
00096                 VARIANT & out_varProperty       ///< The returned value of the property
00097                 ) = 0;
00098             
00099             /// Set the value of a property for a specified platform.
00100             /// \return True if successful, False otherwise.
00101             virtual bool SetValue( 
00102                 const GUID & in_guidPlatform,   ///< The unique ID of the platform to modify
00103                 LPCWSTR in_pszPropertyName,     ///< The name of the property
00104                 const VARIANT & in_varProperty  ///< The value to set
00105                 ) = 0;
00106 
00107             /// Get the RTPC binding status for a specified property.
00108             /// \return True if property is bound to a RTPC, False otherwise.
00109             virtual bool PropertyHasRTPC(
00110                 LPCWSTR in_pszPropertyName      ///< The name of the property
00111                 ) = 0;
00112 
00113             /// This function is called by Wwise to get the current platform's identifier. 
00114             /// This can be passed to any function that has a parameter
00115             /// for a platform ID, such as GetValue() or SetValue(), when you want to make
00116             /// the call for the currently active platform.
00117             /// \return The unique ID of the current platform
00118             virtual GUID GetCurrentPlatform() = 0;
00119 
00120             /// This function is called by Wwise to get the current base platform
00121             /// \return The unique ID of the current base platform
00122             virtual BasePlatformID GetCurrentBasePlatform() = 0;
00123 
00124             /// This function is called To retrieve the base platforms of the authoring tool.
00125             virtual BasePlatformID GetDefaultNativeAuthoringPlaybackPlatform() = 0;
00126 
00127             /// This function is called To retrieve the custom platform being used to run while in authoring
00128             virtual GUID GetAuthoringPlaybackPlatform() = 0;
00129 
00130             /// Use this function to tell Wwise that something other than properties 
00131             /// has changed within the plugin.  This will set the plugin dirty (for save)
00132             /// and GetPluginData will be called when the plugin is about to play in Wwise, to
00133             /// transfer the internal data to the Sound Engine part of the plugin.
00134             /// Use ALL_PLUGIN_DATA_ID to tell that all the data has to be refreshed.
00135             virtual void NotifyInternalDataChanged(AkPluginParamID in_idData, bool in_bMakeProjectDirty = true) = 0;
00136 
00137             /// Call this function when you are about to log an undo event to know if Wwise is 
00138             /// in a state where undos are enabled.  Undo logging can be disabled for a particular
00139             /// plugin object if it already lives in the undo stack or in the clipboard.
00140             virtual bool CanLogUndos() = 0;
00141 
00142             /// Obtain the Undo Manager.  The Undo Manager can be used to group undo together or
00143             /// to check the status of the undo system.
00144             virtual AK::Wwise::IUndoManager * GetUndoManager() = 0;
00145 
00146             /// Obtain licensing status for the plug-in. Refer to \ref wwiseplugin_dll_license for more information.
00147             virtual void GetLicenseStatus(
00148                 const GUID & in_guidPlatform,           ///< GUID of the platform
00149                 AK::Wwise::LicenseType & out_eType,     ///< License Type
00150                 AK::Wwise::LicenseStatus & out_eStatus, ///< License Status
00151                 UINT32 & out_uDaysToExpiry              ///< Days until license expiry
00152                 ) = 0;
00153 
00154             /// Obtain licensing status for a plug-in-specific asset ID. Refer to \ref wwiseplugin_dll_license for more information.
00155             virtual void GetAssetLicenseStatus( 
00156                 const GUID & in_guidPlatform,           ///< GUID of the platform
00157                 AkUInt32 in_uAssetID,                   ///< ID of the asset
00158                 AK::Wwise::LicenseType & out_eType,     ///< License Type
00159                 AK::Wwise::LicenseStatus & out_eStatus, ///< License Status
00160                 UINT32 & out_uDaysToExpiry              ///< Days until license expiry
00161                 ) = 0;
00162 
00163             /// Obtain the unique identifier of the corresponding IWObject.
00164             virtual const GUID& GetID() const = 0;
00165 
00166             /// Find and call the specified procedure. Calls made using this function are always blocking.
00167             virtual void WaapiCall(
00168                 const char* in_szUri,        ///< URI of the procedure to call
00169                 const char* in_szArgs,       ///< JSON string (utf-8) of arguments to pass to the procedure or NULL for no arguments
00170                 const char* in_szOptions,    ///< JSON string (utf-8) of options to pass to the procedure or NULL for no options
00171                 AK::IAkPluginMemAlloc* in_pAlloc, ///< Allocator used to allocate memory for the results or the error
00172                 char*& out_szResults,        ///< JSON string (utf-8) containing the results (if any)
00173                 char*& out_szError           ///< JSON string (utf-8) containing the error (if any)
00174                 ) const = 0;
00175         };
00176 
00177         /// Plug-in object store interface. An instance of this class is created and
00178         /// assigned to each plug-in, which in turn can use it to manage its inner objects.
00179         /// Inner objects can be created from the inner types defined in the plug-in's XML 
00180         /// definition file.
00181         /// \warning The functions in this interface are not thread-safe, unless stated otherwise.
00182         /// \sa
00183         /// - AK::Wwise::IAudioPlugin::SetPluginObjectStore()
00184         /// - \ref wwiseplugin_objectstore
00185         /// - \ref wwiseplugin_xml_properties_tag
00186         class IPluginObjectStore
00187         {
00188         public:
00189             /// Inserts an object into the specified list at the specified position.  To create objects,
00190             /// use CreateObject.  Note that an object can only be inside one list.
00191             /// Pass (unsigned int)-1 as the index to insert at the end of the list
00192             virtual void InsertObject( 
00193                 LPCWSTR in_pszListName,
00194                 unsigned int in_uiIndex,
00195                 IPluginPropertySet* in_pPropertySet
00196                 ) = 0;
00197             
00198             /// Removes an object from its list.  The list is not specified and is automatically found.
00199             /// The function \c DeleteObject must be called if the object is no longer necessary.
00200             /// \return True if successful, False otherwise
00201             virtual bool RemoveObject( 
00202                 IPluginPropertySet* in_pPropertySet
00203                 ) = 0;
00204 
00205             /// Gets an object inside the specified list at the specified position.
00206             /// \return The object in the specified list at the specified position, NULL if list or index are invalid
00207             virtual IPluginPropertySet* GetObject( 
00208                 LPCWSTR in_pszListName,
00209                 unsigned int in_uiIndex
00210                 ) const = 0;
00211 
00212             /// Get the number of object inside the specified list.
00213             /// \return Number of object inside the specified list.
00214             virtual unsigned int GetObjectCount( 
00215                 LPCWSTR in_pszListName
00216                 ) const = 0;
00217 
00218             /// Create a new object instance of the specified type.  The type must be defined in the Plugin XML definition.
00219             /// See the \c InnerTypes section in the plug-in definition.
00220             /// \return The instance of the newly created object, NULL if not successful
00221             virtual IPluginPropertySet* CreateObject( 
00222                 LPCWSTR in_pszType
00223                 ) = 0;
00224 
00225             /// Frees the object.  It will also remove the object from its list if the object is still in a list.
00226             /// Do not use the object after calling this function.
00227             virtual void DeleteObject( 
00228                 IPluginPropertySet* in_pPropertySet
00229                 ) = 0;
00230 
00231             /// Gets the number of lists.
00232             /// \return The number of lists.
00233             virtual unsigned int GetListCount() const = 0;
00234 
00235             /// Get the name of the list at the specified position.  The buffer must be large enough to copy the list name.
00236             /// When the buffer is too small, the function do not write to the buffer and return zero.
00237             /// \return Number of characters written to the buffer, zero if failed.
00238             virtual unsigned int GetListName( 
00239                 unsigned int in_uiListIndex,
00240                 LPWSTR out_pszListName,
00241                 unsigned int in_uiBufferSize
00242                 ) const = 0;
00243         };
00244 
00245         /// Plug-in object media interface. An instance of this class is created and
00246         /// assigned to each plug-in that supports media file handling.
00247         /// \warning The functions in this interface are not thread-safe, unless stated otherwise.
00248         /// \sa
00249         /// - AK::Wwise::IAudioPlugin::SetPluginObjectMedia()
00250         class IPluginObjectMedia
00251         {
00252         public:
00253             
00254             /// Requests to set the specified file as a data input file.
00255             virtual bool SetMediaSource( 
00256                 LPCWSTR in_pszFilePathToImport, ///< File path: can be null in the case of plugin-generated data not requiring an original file
00257                 unsigned int in_Index = 0,      ///< Optional index
00258                 bool in_bReplace = false        ///< Optional: set to true to replace existing file if the name is already in used
00259                 ) = 0;
00260 
00261             /// Requests to remove the specified index file s a data input file.
00262             virtual void RemoveMediaSource( 
00263                 unsigned int in_Index = 0   ///< Optional index
00264                 ) = 0;
00265 
00266             /// Retrieve the number of dataSource, it will be then possible to
00267             /// call GetMediaFileName or RemoveMediaSource using the provided index
00268             virtual unsigned int GetMediaSourceCount() const = 0;
00269 
00270             /// Retrieve the file name of the source plug-in data relative to the 
00271             /// original directory at the specified index.
00272             /// Mostly used to allow the Plug-in to display this information.
00273             /// \return Number of characters written to the buffer, zero if failed.
00274             virtual unsigned int GetMediaSourceFileName(
00275                 LPWSTR out_pszFileName,         ///< Relative path of the associated file
00276                 unsigned int in_uiBufferSize,   ///< Size of the provided string buffer
00277                 unsigned int in_Index = 0       ///< Optional index
00278                 ) const = 0;
00279 
00280             /// Retrieve the file path of the source plug-in data at the specified index.
00281             /// \return Number of characters written to the buffer, zero if failed.
00282             virtual unsigned int GetMediaSourceOriginalFilePath(
00283                 LPWSTR out_pszFileName,         ///< Relative path of the associated file
00284                 unsigned int in_uiBufferSize,   ///< Size of the provided string buffer
00285                 unsigned int in_Index = 0       ///< Optional index
00286                 ) const = 0;
00287 
00288             /// Retrieve the file path of the converted plug-in data at the specified index.
00289             /// \return Number of characters written to the buffer, zero if failed.
00290             virtual unsigned int GetMediaSourceConvertedFilePath(
00291                 LPWSTR out_pszFileName,         ///< Relative path of the associated file
00292                 unsigned int in_uiBufferSize,   ///< Size of the provided string buffer
00293                 const GUID & in_guidPlatform,   ///< The GUID of the platform
00294                 unsigned int in_Index = 0       ///< Optional index
00295                 ) const = 0;
00296 
00297             /// Request Wwise to perform any required conversion on the data
00298             virtual void InvalidateMediaSource( unsigned int in_Index = 0 ) = 0;
00299 
00300             /// Obtain the Original directory for the plugin
00301             /// \return Number of characters written to the buffer, zero if failed.
00302             virtual unsigned int GetOriginalDirectory(
00303                 LPWSTR out_pszDirectory,        ///< Pointer to the buffer that will hold the directory string
00304                 unsigned int in_uiBufferSize    ///< Size of the buffer pointed by out_pszDirectory
00305                 ) const = 0;
00306 
00307             /// Obtain the Converted directory for the plugin and platform
00308             /// \return Number of characters written to the buffer, zero if failed.
00309             virtual unsigned int GetConvertedDirectory(
00310                 LPWSTR out_pszDirectory,        ///< Pointer to the buffer that will hold the directory string
00311                 unsigned int in_uiBufferSize,   ///< Size of the buffer pointed by out_pszDirectory
00312                 const GUID & in_guidPlatform    ///< The GUID of the platform
00313                 ) const = 0;
00314         };
00315 
00316         /// Wwise plug-in interface. This must be implemented for each source or
00317         /// effect plug-in that is exposed in Wwise.
00318         /// \warning The functions in this interface are not thread-safe, unless stated otherwise.
00319         /// \sa
00320         /// - \ref wwiseplugin_object
00321         class IAudioPlugin
00322             : public IPluginBase
00323         {
00324         public:
00325             /// Dialog type. Source plug-ins can be edited in the Property Editor or
00326             /// the Contents Editor, while effect plug-ins can only be edited in the
00327             /// Effect Editor.
00328             /// \sa
00329             /// - \ref wwiseplugin_dialogcode
00330             enum eDialog
00331             {
00332                 SettingsDialog,         ///< Main plug-in dialog. This is the dialog used in the Property
00333                                         ///< Editor for source plug-ins, and in the Effect Editor for
00334                                         ///< effect plug-ins.
00335                 ContentsEditorDialog    ///< Contents Editor dialog. This is the small dialog used in the
00336                                         ///< Contents Editor for source plug-ins.
00337             };
00338 
00339             /// Type of operation for the NotifyInnerObjectAddedRemoved function.
00340             enum NotifyInnerObjectOperation
00341             {
00342                 InnerObjectAdded,
00343                 InnerObjectRemoved
00344             };
00345 
00346             struct MonitorData
00347             {
00348                 AkUInt64 uGameObjectID;
00349                 void* pData;
00350                 unsigned int uDataSize;
00351             };
00352 
00353             /// The property set interface is given to the plug-in through this method. It is called by Wwise during
00354             /// initialization of the plug-in, before most other calls.
00355             /// \warning This function is guaranteed to be called by a single thread at a time.
00356             /// \sa
00357             /// - \ref wwiseplugin_propertyset
00358             virtual void SetPluginPropertySet( 
00359                 IPluginPropertySet * in_pPSet   ///< A pointer to the property set interface
00360                 ) = 0;
00361 
00362             /// The plugin object store interface is given to the plug-in through this method. 
00363             /// It is called by Wwise during initialization of the plug-in, before most other calls.
00364             /// Use this interface to manage plugin inner objects.
00365             /// \warning This function is guaranteed to be called by a single thread at a time.
00366             /// \sa
00367             /// - \ref wwiseplugin_objectstore
00368             virtual void SetPluginObjectStore( 
00369                 IPluginObjectStore * in_pObjectStore ///< A pointer to the plugin object store
00370                 ) = 0;
00371 
00372             /// The plugin object data file interface is given to the plug-in through this method. 
00373             /// Set plugin object media, that allows to create and manage media files
00374             /// Use this interface to manage plugin media objects.
00375             ///
00376             /// NOTE: If the plug-in does not handle plugin media, this function should be 
00377             /// implemented as a void function by the plug-in.
00378             ///
00379             /// \warning This function is guaranteed to be called by a single thread at a time.
00380             /// \sa
00381             /// - \ref effectplugin_media
00382             virtual void SetPluginObjectMedia( 
00383                 IPluginObjectMedia * in_pObjectMedia
00384                 ) = 0;
00385 
00386             /// This function is called by Wwise to determine if the plug-in is in a playable state.
00387             /// \warning This function is guaranteed to be called by a single thread at a time.
00388             /// \return True if the plug-in is in a playable state, False otherwise
00389             virtual bool IsPlayable() const = 0;
00390 
00391             /// Initialize custom data to default values. This is called by Wwise after SetPluginPropertySet() 
00392             /// when creating a new instance of the plug-in (i.e. not during a load). The properties on the
00393             /// PropertySet do not need to be initialized in this method.
00394             /// \warning This function is guaranteed to be called by a single thread at a time.
00395             virtual void InitToDefault() = 0;
00396 
00397             /// Delete function called when the user press "delete" button on a plugin. This entry point must 
00398             /// set the undo/redo action properly. 
00399             /// \warning This function is guaranteed to be called by a single thread at a time.
00400             virtual void Delete() = 0;
00401 
00402             /// Load file 
00403             /// \return \b true if load succeeded.
00404             virtual bool Load( IXmlTextReader* in_pReader ) = 0;
00405 
00406             /// Save file
00407             /// \return \b true if save succeeded.
00408             virtual bool Save( IXmlTextWriter* in_pWriter ) = 0;
00409 
00410             /// Copy the plugin's custom data into another instance of the same plugin. This is used
00411             /// during copy/paste and delete. The properties on the PropertySet do not need to
00412             /// be copied in this method.
00413             /// \warning This function is guaranteed to be called by a single thread at a time.
00414             virtual bool CopyInto(
00415                 IAudioPlugin* io_pWObject        // The object that will receive the custom data of this object.
00416                 ) const = 0;
00417 
00418             /// This function is called by Wwise when the current platform changes.
00419             /// \warning This function is guaranteed to be called by a single thread at a time.
00420             /// \sa
00421             /// - \ref wwiseplugin_platformchange
00422             virtual void NotifyCurrentPlatformChanged( 
00423                 const GUID & in_guidCurrentPlatform     ///< The unique ID of the new platform
00424                 ) = 0;
00425 
00426             /// This function is called by Wwise when a plug-in property changes (for example, 
00427             /// through interaction with a UI control bound to a property, or through undo/redo operations).
00428             /// This function is also called during undo or redo operations
00429             /// \warning This function is guaranteed to be called by a single thread at a time.
00430             /// \sa
00431             /// - \ref wwiseplugin_propertychange
00432             virtual void NotifyPropertyChanged( 
00433                 const GUID & in_guidPlatform,   ///< The unique ID of the queried platform
00434                 LPCWSTR in_pszPropertyName      ///< The name of the property
00435                 ) = 0;
00436 
00437             /// This function is called by Wwise when a inner object property changes (for example, 
00438             /// through interaction with a UI control bound to a property, or through undo/redo operations).
00439             /// See the Plugin Object Store for more information about inner objects.
00440             /// This function is also called during undo or redo operations
00441             /// \warning This function is guaranteed to be called by a single thread at a time.
00442             /// \sa
00443             /// - \ref wwiseplugin_propertychange
00444             virtual void NotifyInnerObjectPropertyChanged( 
00445                 IPluginPropertySet* in_pPSet,   ///< The inner object that changed
00446                 const GUID & in_guidPlatform,   ///< The unique ID of the queried platform
00447                 LPCWSTR in_pszPropertyName      ///< The name of the property
00448                 ) = 0;
00449 
00450             /// This function is called by Wwise when a inner object property changes (for example, 
00451             /// through interaction with a UI control bound to a property, or through undo/redo operations).
00452             /// See the Plugin Object Store for more information about inner objects.
00453             /// \warning This function is guaranteed to be called by a single thread at a time.
00454             /// \sa
00455             /// - \ref wwiseplugin_propertychange
00456             virtual void NotifyInnerObjectAddedRemoved( 
00457                 IPluginPropertySet* in_pPSet,   ///< The inner object that was added or removed
00458                 unsigned int in_uiIndex,        ///< The insertion/removal index
00459                 NotifyInnerObjectOperation in_eOperation    ///< InnerObjectAdded or InnerObjectRemoved
00460                 ) = 0;
00461 
00462             /// This function is called by Wwise when a the plugin media changes.
00463             /// It is called when plugin media is added, removed or changes.
00464             /// This function is also called during undo or redo operations
00465             /// Use AK::Wwise::IAudioPlugin::SetPluginObjectMedia and AK::Wwise::IPluginObjectMedia to
00466             /// set plugin media.
00467             /// \warning This function is guaranteed to be called by a single thread at a time.
00468             /// \sa
00469             /// - \ref wwiseplugin_propertychange
00470             virtual void NotifyPluginMediaChanged() = 0;
00471 
00472             /// This function is called by Wwise to obtain parameters that will be written to a bank. 
00473             /// Because these can be changed at run-time, the parameter block should stay relatively small. 
00474             /// Larger data should be put in the Data Block.
00475             /// \warning This function is guaranteed to be called by a single thread at a time.
00476             /// \return True if the plug-in put some parameters in the bank, False otherwise
00477             /// \sa
00478             /// - \ref wwiseplugin_bank
00479             /// - \ref wwiseplugin_propertyset
00480             virtual bool GetBankParameters( 
00481                 const GUID & in_guidPlatform,   ///< The unique ID of the queried platform
00482                 IWriteData* in_pDataWriter      ///< A pointer to the data writer interface
00483                 ) const = 0;
00484 
00485             /// This function is called by Wwise to obtain parameters that will be sent to the 
00486             /// sound engine when Wwise is connected.  This block should contain only data
00487             /// that is NOT a property defined in the plugin xml file.  The parameter ID
00488             /// should be something different than the ones used in the plugin xml.
00489             /// \warning This function is guaranteed to be called by a single thread at a time.
00490             /// \return True if the plug-in has some plugin-defined data.  False otherwise.
00491             /// \sa
00492             /// - AK::Wwise::IPluginPropertySet::NotifyInternalDataChanged
00493             /// - AK::IAkPluginParam::ALL_PLUGIN_DATA_ID
00494             /// - AK::IAkPluginParam::SetParam
00495             virtual bool GetPluginData(
00496                 const GUID & in_guidPlatform,       ///< The unique ID of the queried platform
00497                 AkPluginParamID in_idParam, ///< The plugin-defined parameter ID
00498                 IWriteData* in_pDataWriter          ///< A pointer to the data writer interface
00499                 ) const = 0;
00500 
00501             /// This function is called by Wwise to get the plug-in's HINSTANCE used for loading resources.
00502             /// \warning This function is guaranteed to be called by a single thread at a time.
00503             /// \return A handle to the instance of the plug-in DLL
00504             /// \sa
00505             /// - \ref wwiseplugin_dialogcode
00506             virtual HINSTANCE GetResourceHandle() const = 0;
00507 
00508             /// This function is called by Wwise to get the plug-in dialog parameters.
00509             /// \warning This function is guaranteed to be called by a single thread at a time.
00510             /// \return True if a dialog was returned, False otherwise
00511             /// \sa
00512             /// - \ref wwiseplugin_dialogcode
00513             /// - \ref wwiseplugin_dialog_guide
00514             virtual bool GetDialog( 
00515                 eDialog in_eDialog,             ///< The dialog type
00516                 UINT & out_uiDialogID,          ///< The returned resource ID of the dialog
00517                 PopulateTableItem *& out_pTable ///< The returned table of property-control bindings (can be NULL)
00518                 ) const = 0;
00519 
00520             /// Window message handler for dialogs. This is very similar to a standard WIN32 window procedure.
00521             /// \warning This function is guaranteed to be called by a single thread at a time.
00522             /// \return True if the message has been processed by the plug-in, False otherwise
00523             /// \sa
00524             /// - \ref wwiseplugin_dialogcode
00525             virtual bool WindowProc( 
00526                 eDialog in_eDialog,     ///< The dialog type
00527                 HWND in_hWnd,           ///< The window handle of the dialog
00528                 UINT in_message,        ///< The incoming message. This is a standard Windows message ID (ex. WM_PAINT).
00529                 WPARAM in_wParam,       ///< The WPARAM of the message (see MSDN)
00530                 LPARAM in_lParam,       ///< The LPARAM of the message (see MSDN)
00531                 LRESULT & out_lResult   ///< The returned value if the message has been processed (it is only considered if the method also returns True)
00532                 ) = 0;
00533 
00534             /// DEPRECATED: This function is called by Wwise to get the user-friendly name of the specified property.
00535             /// This function should write the user-friendly name of
00536             /// the specified property to the WCHAR buffer out_pszDisplayName,
00537             /// which is of length in_unCharCount.
00538             /// \warning This function is deprecated.  You need to define the property display names in the plug-in XML definition.  Refer to \ref wwiseplugin_xml_userinterface for more information.
00539             /// \warning This function is guaranteed to be called by a single thread at a time.
00540             /// \return True if the property has a user-friendly name, False otherwise
00541             /// \sa
00542             /// - \ref wwiseplugin_displaynames
00543             virtual bool DisplayNameForProp( 
00544                 LPCWSTR in_pszPropertyName,     ///< The internal name of the property
00545                 LPWSTR out_pszDisplayName,      ///< The returned user-friendly name
00546                 UINT in_unCharCount             ///< The number of WCHAR in the buffer, including the terminating NULL
00547                 ) const = 0;
00548 
00549             /// DEPRECATED: This function is called by Wwise to get the user-friendly names of possible values for the 
00550             /// specified property.
00551             /// This function should write pairs of value and text for the specified property to
00552             /// the WCHAR buffer out_pszDisplayName, which is of length in_unCharCount.
00553             /// Pairs are separated by commas, and each pair contains the value and the
00554             /// text, separated by a colon. Here are a few examples:
00555             /// - Numeric property: "-100:Left,0:Center,100:Right"
00556             /// - Boolean property: "0:Off,1:On"
00557             /// - Numeric property seen as an enumeration: "0:Low Pass,1:High Pass,2:Band Pass,3:Notch,4:Low Shelf,5:High Shelf,6:Peaking"
00558             ///
00559             /// \warning This function is deprecated.  You need to define the enumeration display names in the plug-in XML definition.  Refer to \ref wwiseplugin_xml_restrictions for more information.
00560             /// \warning This function is guaranteed to be called by a single thread at a time.
00561             /// \return True if the property has user-friendly names for some values, False otherwise
00562             /// \sa
00563             /// - \ref wwiseplugin_displaynames
00564             virtual bool DisplayNamesForPropValues( 
00565                 LPCWSTR in_pszPropertyName,     ///< The internal name of the property
00566                 LPWSTR out_pszValuesName,       ///< The returned property value names
00567                 UINT in_unCharCount             ///< The number of WCHAR in the buffer, including the terminating NULL character
00568                 ) const = 0;
00569 
00570             /// Called when the user clicks on the '?' icon.
00571             /// \warning This function is guaranteed to be called by a single thread at a time.
00572             /// \return True if the plug-in handled the help request, false otherwise
00573             /// \sa
00574             /// - \ref wwiseplugin_help
00575             virtual bool Help( 
00576                 HWND in_hWnd,                   ///< The handle of the dialog
00577                 eDialog in_eDialog,             ///< The dialog type
00578                 LPCWSTR in_szLanguageCode       ///< The language code in ISO639-1
00579                 ) const = 0;
00580 
00581             /// Called when an instance of the run-time component of the plug-in sends data 
00582             /// using \c AK::IAkEffectPluginContext::PostMonitorData(), and this plug-in's settings 
00583             /// are being displayed in a window. Because multiple run-time instances may exist for a single
00584             /// authoring tool plug-in, the data is batched together and passed at the end of the frame.
00585             virtual void NotifyMonitorData( 
00586                 const MonitorData * in_pDataArray,  ///< Array of blobs of data
00587                 unsigned int in_uCount,             ///< Number of elements in array 'in_pDataArray'
00588                 bool in_bNeedsByteSwap,             ///< True if data comes from platform with a different byte ordering (i.e. Big Endian)
00589                 bool in_bRealtime                   ///< True if monitoring in real-time, false if scrubbing through profiler history
00590                 ) = 0;
00591 
00592             /// Retrieve a pointer to the class implementing IPluginObjectMedia. Plug-ins using the media sources
00593             /// functionality can simply return a pointer to themselves while other not using the functionality should return NULL
00594             virtual IPluginMediaConverter* GetPluginMediaConverterInterface() = 0;
00595 
00596             /// Retrieve the licensing status of the plug-in for the given platform.
00597             /// \return Licensing status of the plug-in; LicenseStatus_Unlicensed or LicenseStatus_Expired will prevent the plug-in from being included in a SoundBank.
00598             /// \sa
00599             /// - \ref IPluginPropertySet::GetLicenseStatus
00600             /// - \ref IPluginPropertySet::GetAssetLicenseStatus
00601             /// - \ref wwiseplugin_dll_license
00602             virtual AK::Wwise::LicenseStatus GetLicenseStatus(
00603                 const GUID & in_guidPlatform,       ///< GUID of the platform
00604                 AK::Wwise::Severity& out_eSeverity, ///< (Optional) If set, the string placed in out_pszMessage will be shown in the log with the corresponding severity. 
00605                 LPWSTR out_pszMessage,              ///< Pointer to the buffer that will hold the message string
00606                 unsigned int in_uiBufferSize        ///< Size of the buffer pointed by out_pszMessage (in number of WCHAR, including null terminator)
00607                 ) = 0;
00608 
00609             /// Return the minimum and maximum duration, in seconds.  This function is only useful with source plug-ins.
00610             /// \return True if the duration values are valid, False otherwise.
00611             virtual bool GetSourceDuration(
00612                 double& out_dblMinDuration, ///< Minimum duration, in seconds
00613                 double& out_dblMaxDuration  ///< Maximum duration, in seconds
00614                 ) const = 0;
00615         };
00616 
00617         /// Use this base class to quickly implement most plugin functions empty
00618         class DefaultAudioPluginImplementation : public IAudioPlugin
00619         {
00620         public:
00621             virtual void SetPluginPropertySet( IPluginPropertySet * in_pPSet ){}
00622             virtual void SetPluginObjectStore( IPluginObjectStore * in_pObjectStore ){}
00623             virtual void SetPluginObjectMedia( IPluginObjectMedia * in_pObjectMedia ){}
00624             virtual bool IsPlayable() const { return true; }
00625             virtual void InitToDefault() {}
00626             virtual void Delete() {}
00627             virtual bool Load( IXmlTextReader* in_pReader ) { return false; }
00628             virtual bool Save( IXmlTextWriter* in_pWriter ) { return false; }
00629             virtual bool CopyInto( IAudioPlugin* io_pWObject ) const { return true; }
00630             virtual void NotifyCurrentPlatformChanged( const GUID & in_guidCurrentPlatform ) {}
00631             virtual void NotifyPropertyChanged( const GUID & in_guidPlatform, LPCWSTR in_pszPropertyName ) {}
00632             virtual void NotifyInnerObjectPropertyChanged( IPluginPropertySet* in_pPSet, const GUID & in_guidPlatform, LPCWSTR in_pszPropertyName ) {}
00633             virtual void NotifyInnerObjectAddedRemoved( IPluginPropertySet* in_pPSet, unsigned int in_uiIndex, NotifyInnerObjectOperation in_eOperation ) {}
00634             virtual void NotifyPluginMediaChanged() {}
00635             virtual bool GetBankParameters( const GUID & in_guidPlatform, IWriteData* in_pDataWriter ) const { return false; }
00636             virtual bool GetPluginData( const GUID & in_guidPlatform, AkPluginParamID in_idParam, IWriteData* in_pDataWriter ) const { return false; }
00637             virtual bool WindowProc( eDialog in_eDialog, HWND in_hWnd, UINT in_message, WPARAM in_wParam, LPARAM in_lParam, LRESULT & out_lResult ){ return false; }
00638             virtual bool DisplayNameForProp( LPCWSTR in_pszPropertyName, LPWSTR out_pszDisplayName, UINT in_unCharCount ) const { return false; }
00639             virtual bool DisplayNamesForPropValues( LPCWSTR in_pszPropertyName, LPWSTR out_pszValuesName, UINT in_unCharCount ) const { return false; }
00640             virtual bool Help( HWND in_hWnd, eDialog in_eDialog, LPCWSTR in_szLanguageCode ) const { return false; }
00641             virtual void NotifyMonitorData( const AK::Wwise::IAudioPlugin::MonitorData * in_pData, unsigned int in_uDataSize, bool in_bNeedsByteSwap, bool in_bRealtime){}
00642             virtual IPluginMediaConverter* GetPluginMediaConverterInterface() { return NULL; }
00643             virtual AK::Wwise::LicenseStatus GetLicenseStatus(const GUID &, AK::Wwise::Severity&, LPWSTR, unsigned int in_uiBufferSize){ return AK::Wwise::LicenseStatus_Valid; }
00644             virtual bool GetSourceDuration( double& out_dblMinDuration, double& out_dblMaxDuration ) const { out_dblMinDuration = 0.f; out_dblMaxDuration = FLT_MAX; return false; }
00645             virtual HINSTANCE GetResourceHandle() const { return NULL; }
00646             virtual bool GetDialog(eDialog in_eDialog, UINT& out_uiDialogID, PopulateTableItem*& out_pTable) const { return false; }
00647         };
00648 
00649         typedef AKRESULT(CALLBACK* RegisterWwisePluginFn)(AK::PluginRegistration *in_pList);
00650         inline AKRESULT RegisterWwisePlugin()
00651         {
00652             if (!g_pAKPluginList)
00653             {
00654                 AKASSERT(!"g_pAKPluginList is NULL. Did you use the AK_STATIC_LINK_PLUGIN macro in your DLL?"); // Should be populated by now.
00655                 return AK_Fail;
00656             }
00657 
00658             HMODULE hLib = ::LoadLibrary(L"WwiseSoundEngine.dll");
00659             if (hLib == NULL)
00660                 return AK_Fail;
00661 
00662             RegisterWwisePluginFn pReg = (RegisterWwisePluginFn)::GetProcAddress(hLib, "RegisterWwisePlugin");
00663             if (pReg == NULL)
00664                 return AK_Fail;
00665 
00666             return pReg(g_pAKPluginList);
00667         }
00668 
00669         /// Struct to be used with the function GetSinkPluginDevices to return devices.
00670 #define AK_MAX_OUTPUTDEVICEDESCRIPTOR 256
00671         struct OutputDeviceDescriptor
00672         {
00673             WCHAR name[AK_MAX_OUTPUTDEVICEDESCRIPTOR];  /// Display name of the device.  Null terminated.  Note that the name can't be more than 256 characters including the null.
00674             AkUInt32 idDevice;  /// ID of the device as used with AK::SoundEngine::AddOutput.  
00675             /// This will be passed back to the plugin through AK::IAkSinkPluginContext::GetOutputID.  
00676             /// Default device ID can be 0.
00677         };
00678     }
00679 }
00680 
00681 /// Private message sent to Wwise window to open a topic in the help file
00682 /// the WPARAM defines the help topic ID
00683 #define WM_AK_PRIVATE_SHOW_HELP_TOPIC   0x4981
00684 
00685 #endif // _AK_WWISE_AUDIOPLUGIN_H