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. 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. 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 virtual AK::Wwise::LicenseStatus GetLicenseStatus( 00602 const GUID & in_guidPlatform, ///< GUID of the platform 00603 AK::Wwise::Severity& out_eSeverity, ///< (Optional) If set, the string placed in out_pszMessage will be shown in the log with the corresponding severity. 00604 LPWSTR out_pszMessage, ///< Pointer to the buffer that will hold the message string 00605 unsigned int in_uiBufferSize ///< Size of the buffer pointed by out_pszMessage (in number of WCHAR, including null terminator) 00606 ) = 0; 00607 00608 /// Return the minimum and maximum duration, in seconds. This function is only useful with source plug-ins. 00609 /// \return True if the duration values are valid, False otherwise. 00610 virtual bool GetSourceDuration( 00611 double& out_dblMinDuration, ///< Minimum duration, in seconds 00612 double& out_dblMaxDuration ///< Maximum duration, in seconds 00613 ) const = 0; 00614 }; 00615 00616 /// Use this base class to quickly implement most plugin functions empty 00617 class DefaultAudioPluginImplementation : public IAudioPlugin 00618 { 00619 public: 00620 virtual void SetPluginPropertySet( IPluginPropertySet * in_pPSet ){} 00621 virtual void SetPluginObjectStore( IPluginObjectStore * in_pObjectStore ){} 00622 virtual void SetPluginObjectMedia( IPluginObjectMedia * in_pObjectMedia ){} 00623 virtual bool IsPlayable() const { return true; } 00624 virtual void InitToDefault() {} 00625 virtual void Delete() {} 00626 virtual bool Load( IXmlTextReader* in_pReader ) { return false; } 00627 virtual bool Save( IXmlTextWriter* in_pWriter ) { return false; } 00628 virtual bool CopyInto( IAudioPlugin* io_pWObject ) const { return true; } 00629 virtual void NotifyCurrentPlatformChanged( const GUID & in_guidCurrentPlatform ) {} 00630 virtual void NotifyPropertyChanged( const GUID & in_guidPlatform, LPCWSTR in_pszPropertyName ) {} 00631 virtual void NotifyInnerObjectPropertyChanged( IPluginPropertySet* in_pPSet, const GUID & in_guidPlatform, LPCWSTR in_pszPropertyName ) {} 00632 virtual void NotifyInnerObjectAddedRemoved( IPluginPropertySet* in_pPSet, unsigned int in_uiIndex, NotifyInnerObjectOperation in_eOperation ) {} 00633 virtual void NotifyPluginMediaChanged() {} 00634 virtual bool GetBankParameters( const GUID & in_guidPlatform, IWriteData* in_pDataWriter ) const { return false; } 00635 virtual bool GetPluginData( const GUID & in_guidPlatform, AkPluginParamID in_idParam, IWriteData* in_pDataWriter ) const { return false; } 00636 virtual bool WindowProc( eDialog in_eDialog, HWND in_hWnd, UINT in_message, WPARAM in_wParam, LPARAM in_lParam, LRESULT & out_lResult ){ return false; } 00637 virtual bool DisplayNameForProp( LPCWSTR in_pszPropertyName, LPWSTR out_pszDisplayName, UINT in_unCharCount ) const { return false; } 00638 virtual bool DisplayNamesForPropValues( LPCWSTR in_pszPropertyName, LPWSTR out_pszValuesName, UINT in_unCharCount ) const { return false; } 00639 virtual bool Help( HWND in_hWnd, eDialog in_eDialog, LPCWSTR in_szLanguageCode ) const { return false; } 00640 virtual void NotifyMonitorData( const AK::Wwise::IAudioPlugin::MonitorData * in_pData, unsigned int in_uDataSize, bool in_bNeedsByteSwap, bool in_bRealtime){} 00641 virtual IPluginMediaConverter* GetPluginMediaConverterInterface() { return NULL; } 00642 virtual AK::Wwise::LicenseStatus GetLicenseStatus(const GUID &, AK::Wwise::Severity&, LPWSTR, unsigned int in_uiBufferSize){ return AK::Wwise::LicenseStatus_Valid; } 00643 virtual bool GetSourceDuration( double& out_dblMinDuration, double& out_dblMaxDuration ) const { out_dblMinDuration = 0.f; out_dblMaxDuration = FLT_MAX; return false; } 00644 }; 00645 00646 typedef AKRESULT(CALLBACK* RegisterWwisePluginFn)(AK::PluginRegistration *in_pList); 00647 inline AKRESULT RegisterWwisePlugin() 00648 { 00649 if (!g_pAKPluginList) 00650 { 00651 AKASSERT(!"g_pAKPluginList is NULL. Did you use the AK_STATIC_LINK_PLUGIN macro in your DLL?"); // Should be populated by now. 00652 return AK_Fail; 00653 } 00654 00655 HMODULE hLib = ::LoadLibrary(L"WwiseSoundEngine.dll"); 00656 if (hLib == NULL) 00657 return AK_Fail; 00658 00659 RegisterWwisePluginFn pReg = (RegisterWwisePluginFn)::GetProcAddress(hLib, "RegisterWwisePlugin"); 00660 if (pReg == NULL) 00661 return AK_Fail; 00662 00663 return pReg(g_pAKPluginList); 00664 } 00665 } 00666 } 00667 00668 /// Private message sent to Wwise window to open a topic in the help file 00669 /// the WPARAM defines the help topic ID 00670 #define WM_AK_PRIVATE_SHOW_HELP_TOPIC 0x4981 00671 00672 #endif // _AK_WWISE_AUDIOPLUGIN_H
Questions? Problems? Need more info? Contact us, and we can help!
Visit our Support pageRegister your project and we'll help you get started with no strings attached!
Get started with Wwise