Version
menu_open
link
Wwise SDK 2019.2.15
AudioPlugin.h
Go to the documentation of this file.
1 /*******************************************************************************
2 The content of this file includes portions of the AUDIOKINETIC Wwise Technology
3 released in source code form as part of the SDK installer package.
4 
5 Commercial License Usage
6 
7 Licensees holding valid commercial licenses to the AUDIOKINETIC Wwise Technology
8 may use this file in accordance with the end user license agreement provided
9 with the software or, alternatively, in accordance with the terms contained in a
10 written agreement between you and Audiokinetic Inc.
11 
12 Apache License Usage
13 
14 Alternatively, this file may be used under the Apache License, Version 2.0 (the
15 "Apache License"); you may not use this file except in compliance with the
16 Apache License. You may obtain a copy of the Apache License at
17 http://www.apache.org/licenses/LICENSE-2.0.
18 
19 Unless required by applicable law or agreed to in writing, software distributed
20 under the Apache License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES
21 OR CONDITIONS OF ANY KIND, either express or implied. See the Apache License for
22 the specific language governing permissions and limitations under the License.
23 
24  Version: <VERSION> Build: <BUILDNUMBER>
25  Copyright (c) <COPYRIGHTYEAR> Audiokinetic Inc.
26 *******************************************************************************/
27 
28 /// \file
29 /// Wwise audio plug-in interface, used to implement the Wwise side of a source or effect plug-in.
30 
31 #ifndef _AK_WWISE_AUDIOPLUGIN_H
32 #define _AK_WWISE_AUDIOPLUGIN_H
33 
34 #include "Undo.h"
35 
36 #include <AK/Wwise/Utilities.h>
37 #include <AK/SoundEngine/Common/AkSoundEngine.h> /// Dummy assert hook definition.
39 #include <AK/Wwise/PlatformID.h>
40 
41 #include <float.h>
42 
43 // Audiokinetic namespace
44 namespace AK
45 {
46  class IXmlTextReader;
47  class IXmlTextWriter;
48 
49  // Audiokinetic Wwise namespace
50  namespace Wwise
51  {
53  {
54  public:
55  /// If the conversion failed the function is responsible of deleting
56  /// any files that may have been created, even the destination file
57  /// in case of error. If the function return false we will use the
58  /// string put in io_pError to display an error message.
60  const GUID & in_guidPlatform, ///< The unique ID of the custom platform being converted for.
61  const BasePlatformID & in_basePlatform, ///< The unique ID of the base platform being converted for.
62  LPCWSTR in_szSourceFile, ///< Source File to convert data from.
63  LPCWSTR in_szDestFile, ///< DestinationFile, must be created by the plug-in.
64  AkUInt32 in_uSampleRate, ///< The target sample rate for the converted file, passing 0 will default to the platform default
65  AkUInt32 in_uBlockLength, ///< The block length, passing 0 will default to the platform default
66  AK::Wwise::IProgress* in_pProgress, ///< Optional Progress Bar controller.
67  IWriteString* io_pError ///< Optional error string that can be displayed if ConversionResult is not successful
68  ) = 0;
69 
71  const GUID & in_guidPlatform, ///< The unique ID of the platform being converted for.
72  AkUInt32 in_uSampleRate = 0, ///< The target sample rate for the converted file, passing 0 will default to the platform default.
73  AkUInt32 in_uBlockLength = 0 ///< The block length, passing 0 will default to the platform default.
74  ) = 0;
75  };
76 
77  /// Plug-in property set interface. An instance of this class is created and
78  /// assigned to each plug-in, which in turn can use it to manage its properties.
79  /// Whenever a property name is specified, it corresponds to the property
80  /// name set in the plug-in's XML definition file.
81  /// \akwarning
82  /// The functions in this interface are not thread-safe, unless stated otherwise.
83  /// \endakwarning
84  /// \sa
85  /// - \ref wwiseplugin_xml_properties_tag
86  /// - AK::Wwise::IAudioPlugin::SetPluginPropertySet()
87  /// - \ref wwiseplugin_propertyset
89  {
90  public:
91  /// Get the value of a property for a specified platform.
92  /// \return True if successful, False otherwise
93  /// \sa
94  /// - \ref wwiseplugin_bank
95  virtual bool GetValue(
96  const GUID & in_guidPlatform, ///< The unique ID of the queried platform
97  LPCWSTR in_pszPropertyName, ///< The name of the property
98  VARIANT & out_varProperty ///< The returned value of the property
99  ) = 0;
100 
101  /// Set the value of a property for a specified platform.
102  /// \return True if successful, False otherwise.
103  virtual bool SetValue(
104  const GUID & in_guidPlatform, ///< The unique ID of the platform to modify
105  LPCWSTR in_pszPropertyName, ///< The name of the property
106  const VARIANT & in_varProperty ///< The value to set
107  ) = 0;
108 
109  /// Get the RTPC binding status for a specified property.
110  /// \return True if property is bound to a RTPC, False otherwise.
111  virtual bool PropertyHasRTPC(
112  LPCWSTR in_pszPropertyName ///< The name of the property
113  ) = 0;
114 
115  /// This function is called by Wwise to get the current platform's identifier.
116  /// This can be passed to any function that has a parameter
117  /// for a platform ID, such as GetValue() or SetValue(), when you want to make
118  /// the call for the currently active platform.
119  /// \return The unique ID of the current platform
120  virtual GUID GetCurrentPlatform() = 0;
121 
122  /// This function is called by Wwise to get the current base platform
123  /// \return The unique ID of the current base platform
125 
126  /// This function is called To retrieve the base platforms of the authoring tool.
128 
129  /// This function is called To retrieve the custom platform being used to run while in authoring
130  virtual GUID GetAuthoringPlaybackPlatform() = 0;
131 
132  /// Use this function to tell Wwise that something other than properties
133  /// has changed within the plugin. This will set the plugin dirty (for save)
134  /// and GetPluginData will be called when the plugin is about to play in Wwise, to
135  /// transfer the internal data to the Sound Engine part of the plugin.
136  /// Use ALL_PLUGIN_DATA_ID to tell that all the data has to be refreshed.
137  virtual void NotifyInternalDataChanged(AkPluginParamID in_idData, bool in_bMakeProjectDirty = true) = 0;
138 
139  /// Call this function when you are about to log an undo event to know if Wwise is
140  /// in a state where undos are enabled. Undo logging can be disabled for a particular
141  /// plugin object if it already lives in the undo stack or in the clipboard.
142  virtual bool CanLogUndos() = 0;
143 
144  /// Obtain the Undo Manager. The Undo Manager can be used to group undo together or
145  /// to check the status of the undo system.
146  virtual AK::Wwise::IUndoManager * GetUndoManager() = 0;
147 
148  /// Obtain licensing status for the plug-in. Refer to \ref wwiseplugin_dll_license for more information.
149  virtual void GetLicenseStatus(
150  const GUID & in_guidPlatform, ///< GUID of the platform
151  AK::Wwise::LicenseType & out_eType, ///< License Type
152  AK::Wwise::LicenseStatus & out_eStatus, ///< License Status
153  UINT32 & out_uDaysToExpiry ///< Days until license expiry
154  ) = 0;
155 
156  /// Obtain licensing status for a plug-in-specific asset ID. Refer to \ref wwiseplugin_dll_license for more information.
157  virtual void GetAssetLicenseStatus(
158  const GUID & in_guidPlatform, ///< GUID of the platform
159  AkUInt32 in_uAssetID, ///< ID of the asset
160  AK::Wwise::LicenseType & out_eType, ///< License Type
161  AK::Wwise::LicenseStatus & out_eStatus, ///< License Status
162  UINT32 & out_uDaysToExpiry ///< Days until license expiry
163  ) = 0;
164 
165  /// Obtain the unique identifier of the corresponding IWObject.
166  virtual const GUID& GetID() const = 0;
167 
168  /// Find and call the specified procedure. Calls made using this function are always blocking.
169  virtual void WaapiCall(
170  const char* in_szUri, ///< URI of the procedure to call
171  const char* in_szArgs, ///< JSON string (utf-8) of arguments to pass to the procedure or NULL for no arguments
172  const char* in_szOptions, ///< JSON string (utf-8) of options to pass to the procedure or NULL for no options
173  AK::IAkPluginMemAlloc* in_pAlloc, ///< Allocator used to allocate memory for the results or the error
174  char*& out_szResults, ///< JSON string (utf-8) containing the results (if any)
175  char*& out_szError ///< JSON string (utf-8) containing the error (if any)
176  ) const = 0;
177  };
178 
179  /// Plug-in object store interface. An instance of this class is created and
180  /// assigned to each plug-in, which in turn can use it to manage its inner objects.
181  /// Inner objects can be created from the inner types defined in the plug-in's XML
182  /// definition file.
183  /// \akwarning
184  /// The functions in this interface are not thread-safe, unless stated otherwise.
185  /// \endakwarning
186  /// \sa
187  /// - AK::Wwise::IAudioPlugin::SetPluginObjectStore()
188  /// - \ref wwiseplugin_objectstore
189  /// - \ref wwiseplugin_xml_properties_tag
191  {
192  public:
193  /// Inserts an object into the specified list at the specified position. To create objects,
194  /// use CreateObject. Note that an object can only be inside one list.
195  /// Pass (unsigned int)-1 as the index to insert at the end of the list
196  virtual void InsertObject(
197  LPCWSTR in_pszListName,
198  unsigned int in_uiIndex,
199  IPluginPropertySet* in_pPropertySet
200  ) = 0;
201 
202  /// Removes an object from its list. The list is not specified and is automatically found.
203  /// The function \c DeleteObject must be called if the object is no longer necessary.
204  /// \return True if successful, False otherwise
205  virtual bool RemoveObject(
206  IPluginPropertySet* in_pPropertySet
207  ) = 0;
208 
209  /// Gets an object inside the specified list at the specified position.
210  /// \return The object in the specified list at the specified position, NULL if list or index are invalid
212  LPCWSTR in_pszListName,
213  unsigned int in_uiIndex
214  ) const = 0;
215 
216  /// Get the number of object inside the specified list.
217  /// \return Number of object inside the specified list.
218  virtual unsigned int GetObjectCount(
219  LPCWSTR in_pszListName
220  ) const = 0;
221 
222  /// Create a new object instance of the specified type. The type must be defined in the Plugin XML definition.
223  /// See the \c InnerTypes section in the plug-in definition.
224  /// \return The instance of the newly created object, NULL if not successful
226  LPCWSTR in_pszType
227  ) = 0;
228 
229  /// Frees the object. It will also remove the object from its list if the object is still in a list.
230  /// Do not use the object after calling this function.
231  virtual void DeleteObject(
232  IPluginPropertySet* in_pPropertySet
233  ) = 0;
234 
235  /// Gets the number of lists.
236  /// \return The number of lists.
237  virtual unsigned int GetListCount() const = 0;
238 
239  /// Get the name of the list at the specified position. The buffer must be large enough to copy the list name.
240  /// When the buffer is too small, the function do not write to the buffer and return zero.
241  /// \return Number of characters written to the buffer, zero if failed.
242  virtual unsigned int GetListName(
243  unsigned int in_uiListIndex,
244  LPWSTR out_pszListName,
245  unsigned int in_uiBufferSize
246  ) const = 0;
247  };
248 
249  /// Plug-in object media interface. An instance of this class is created and
250  /// assigned to each plug-in that supports media file handling.
251  /// \akwarning
252  /// The functions in this interface are not thread-safe, unless stated otherwise.
253  /// \endakwarning
254  /// \sa
255  /// - AK::Wwise::IAudioPlugin::SetPluginObjectMedia()
257  {
258  public:
259 
260  /// Requests to set the specified file as a data input file.
261  virtual bool SetMediaSource(
262  LPCWSTR in_pszFilePathToImport, ///< File path: can be null in the case of plugin-generated data not requiring an original file
263  unsigned int in_Index = 0, ///< Optional index
264  bool in_bReplace = false ///< Optional: set to true to replace existing file if the name is already in used
265  ) = 0;
266 
267  /// Requests to remove the specified index file s a data input file.
268  virtual void RemoveMediaSource(
269  unsigned int in_Index = 0 ///< Optional index
270  ) = 0;
271 
272  /// Retrieve the number of dataSource, it will be then possible to
273  /// call GetMediaFileName or RemoveMediaSource using the provided index
274  virtual unsigned int GetMediaSourceCount() const = 0;
275 
276  /// Retrieve the file name of the source plug-in data relative to the
277  /// original directory at the specified index.
278  /// Mostly used to allow the Plug-in to display this information.
279  /// \return Number of characters written to the buffer, zero if failed.
280  virtual unsigned int GetMediaSourceFileName(
281  LPWSTR out_pszFileName, ///< Relative path of the associated file
282  unsigned int in_uiBufferSize, ///< Size of the provided string buffer
283  unsigned int in_Index = 0 ///< Optional index
284  ) const = 0;
285 
286  /// Retrieve the file path of the source plug-in data at the specified index.
287  /// \return Number of characters written to the buffer, zero if failed.
288  virtual unsigned int GetMediaSourceOriginalFilePath(
289  LPWSTR out_pszFileName, ///< Relative path of the associated file
290  unsigned int in_uiBufferSize, ///< Size of the provided string buffer
291  unsigned int in_Index = 0 ///< Optional index
292  ) const = 0;
293 
294  /// Retrieve the file path of the converted plug-in data at the specified index.
295  /// \return Number of characters written to the buffer, zero if failed.
296  virtual unsigned int GetMediaSourceConvertedFilePath(
297  LPWSTR out_pszFileName, ///< Relative path of the associated file
298  unsigned int in_uiBufferSize, ///< Size of the provided string buffer
299  const GUID & in_guidPlatform, ///< The GUID of the platform
300  unsigned int in_Index = 0 ///< Optional index
301  ) const = 0;
302 
303  /// Request Wwise to perform any required conversion on the data
304  virtual void InvalidateMediaSource( unsigned int in_Index = 0 ) = 0;
305 
306  /// Obtain the Original directory for the plugin
307  /// \return Number of characters written to the buffer, zero if failed.
308  virtual unsigned int GetOriginalDirectory(
309  LPWSTR out_pszDirectory, ///< Pointer to the buffer that will hold the directory string
310  unsigned int in_uiBufferSize ///< Size of the buffer pointed by out_pszDirectory
311  ) const = 0;
312 
313  /// Obtain the Converted directory for the plugin and platform
314  /// \return Number of characters written to the buffer, zero if failed.
315  virtual unsigned int GetConvertedDirectory(
316  LPWSTR out_pszDirectory, ///< Pointer to the buffer that will hold the directory string
317  unsigned int in_uiBufferSize, ///< Size of the buffer pointed by out_pszDirectory
318  const GUID & in_guidPlatform ///< The GUID of the platform
319  ) const = 0;
320  };
321 
322  /// Wwise plug-in interface. This must be implemented for each source or
323  /// effect plug-in that is exposed in Wwise.
324  /// \akwarning
325  /// The functions in this interface are not thread-safe, unless stated otherwise.
326  /// \endakwarning
327  /// \sa
328  /// - \ref wwiseplugin_object
330  : public IPluginBase
331  {
332  public:
333  /// Dialog type. Source plug-ins can be edited in the Property Editor or
334  /// the Contents Editor, while effect plug-ins can only be edited in the
335  /// Effect Editor.
336  /// \sa
337  /// - \ref wwiseplugin_dialogcode
338  enum eDialog
339  {
340  SettingsDialog, ///< Main plug-in dialog. This is the dialog used in the Property
341  ///< Editor for source plug-ins, and in the Effect Editor for
342  ///< effect plug-ins.
343  ContentsEditorDialog ///< Contents Editor dialog. This is the small dialog used in the
344  ///< Contents Editor for source plug-ins.
345  };
346 
347  /// Type of operation for the NotifyInnerObjectAddedRemoved function.
349  {
352  };
353 
354  struct MonitorData
355  {
357  void* pData;
358  unsigned int uDataSize;
359  };
360 
361  /// The property set interface is given to the plug-in through this method. It is called by Wwise during
362  /// initialization of the plug-in, before most other calls.
363  /// \warning This function is guaranteed to be called by a single thread at a time.
364  /// \sa
365  /// - \ref wwiseplugin_propertyset
366  virtual void SetPluginPropertySet(
367  IPluginPropertySet * in_pPSet ///< A pointer to the property set interface
368  ) = 0;
369 
370  /// The plugin object store interface is given to the plug-in through this method.
371  /// It is called by Wwise during initialization of the plug-in, before most other calls.
372  /// Use this interface to manage plugin inner objects.
373  /// \warning This function is guaranteed to be called by a single thread at a time.
374  /// \sa
375  /// - \ref wwiseplugin_objectstore
376  virtual void SetPluginObjectStore(
377  IPluginObjectStore * in_pObjectStore ///< A pointer to the plugin object store
378  ) = 0;
379 
380  /// The plugin object data file interface is given to the plug-in through this method.
381  /// Set plugin object media, that allows to create and manage media files
382  /// Use this interface to manage plugin media objects.
383  ///
384  /// NOTE: If the plug-in does not handle plugin media, this function should be
385  /// implemented as a void function by the plug-in.
386  ///
387  /// \warning This function is guaranteed to be called by a single thread at a time.
388  /// \sa
389  /// - \ref effectplugin_media
390  virtual void SetPluginObjectMedia(
391  IPluginObjectMedia * in_pObjectMedia
392  ) = 0;
393 
394  /// This function is called by Wwise to determine if the plug-in is in a playable state.
395  /// \warning This function is guaranteed to be called by a single thread at a time.
396  /// \return True if the plug-in is in a playable state, False otherwise
397  virtual bool IsPlayable() const = 0;
398 
399  /// Initialize custom data to default values. This is called by Wwise after SetPluginPropertySet()
400  /// when creating a new instance of the plug-in (i.e. not during a load). The properties on the
401  /// PropertySet do not need to be initialized in this method.
402  /// \warning This function is guaranteed to be called by a single thread at a time.
403  virtual void InitToDefault() = 0;
404 
405  /// Delete function called when the user press "delete" button on a plugin. This entry point must
406  /// set the undo/redo action properly.
407  /// \warning This function is guaranteed to be called by a single thread at a time.
408  virtual void Delete() = 0;
409 
410  /// Load file
411  /// \return \b true if load succeeded.
412  virtual bool Load( AK::IXmlTextReader* in_pReader ) = 0;
413 
414  /// Save file
415  /// \return \b true if save succeeded.
416  virtual bool Save( AK::IXmlTextWriter* in_pWriter ) = 0;
417 
418  /// Copy the plugin's custom data into another instance of the same plugin. This is used
419  /// during copy/paste and delete. The properties on the PropertySet do not need to
420  /// be copied in this method.
421  /// \warning This function is guaranteed to be called by a single thread at a time.
422  virtual bool CopyInto(
423  IAudioPlugin* io_pWObject // The object that will receive the custom data of this object.
424  ) const = 0;
425 
426  /// This function is called by Wwise when the current platform changes.
427  /// \warning This function is guaranteed to be called by a single thread at a time.
428  /// \sa
429  /// - \ref wwiseplugin_platformchange
431  const GUID & in_guidCurrentPlatform ///< The unique ID of the new platform
432  ) = 0;
433 
434  /// This function is called by Wwise when a plug-in property changes (for example,
435  /// through interaction with a UI control bound to a property, or through undo/redo operations).
436  /// This function is also called during undo or redo operations
437  /// \warning This function is guaranteed to be called by a single thread at a time.
438  /// \sa
439  /// - \ref wwiseplugin_propertychange
440  virtual void NotifyPropertyChanged(
441  const GUID & in_guidPlatform, ///< The unique ID of the queried platform
442  LPCWSTR in_pszPropertyName ///< The name of the property
443  ) = 0;
444 
445  /// This function is called by Wwise when a inner object property changes (for example,
446  /// through interaction with a UI control bound to a property, or through undo/redo operations).
447  /// See the Plugin Object Store for more information about inner objects.
448  /// This function is also called during undo or redo operations
449  /// \warning This function is guaranteed to be called by a single thread at a time.
450  /// \sa
451  /// - \ref wwiseplugin_propertychange
453  IPluginPropertySet* in_pPSet, ///< The inner object that changed
454  const GUID & in_guidPlatform, ///< The unique ID of the queried platform
455  LPCWSTR in_pszPropertyName ///< The name of the property
456  ) = 0;
457 
458  /// This function is called by Wwise when a inner object property changes (for example,
459  /// through interaction with a UI control bound to a property, or through undo/redo operations).
460  /// See the Plugin Object Store for more information about inner objects.
461  /// \warning This function is guaranteed to be called by a single thread at a time.
462  /// \sa
463  /// - \ref wwiseplugin_propertychange
465  IPluginPropertySet* in_pPSet, ///< The inner object that was added or removed
466  unsigned int in_uiIndex, ///< The insertion/removal index
467  NotifyInnerObjectOperation in_eOperation ///< InnerObjectAdded or InnerObjectRemoved
468  ) = 0;
469 
470  /// This function is called by Wwise when a the plugin media changes.
471  /// It is called when plugin media is added, removed or changes.
472  /// This function is also called during undo or redo operations
473  /// Use AK::Wwise::IAudioPlugin::SetPluginObjectMedia and AK::Wwise::IPluginObjectMedia to
474  /// set plugin media.
475  /// \warning This function is guaranteed to be called by a single thread at a time.
476  /// \sa
477  /// - \ref wwiseplugin_propertychange
478  virtual void NotifyPluginMediaChanged() = 0;
479 
480  /// This function is called by Wwise to obtain parameters that will be written to a bank.
481  /// Because these can be changed at run-time, the parameter block should stay relatively small.
482  /// Larger data should be put in the Data Block.
483  /// \warning This function is guaranteed to be called by a single thread at a time.
484  /// \return True if the plug-in put some parameters in the bank, False otherwise
485  /// \sa
486  /// - \ref wwiseplugin_bank
487  /// - \ref wwiseplugin_propertyset
488  virtual bool GetBankParameters(
489  const GUID & in_guidPlatform, ///< The unique ID of the queried platform
490  IWriteData* in_pDataWriter ///< A pointer to the data writer interface
491  ) const = 0;
492 
493  /// This function is called by Wwise to obtain parameters that will be sent to the
494  /// sound engine when Wwise is connected. This block should contain only data
495  /// that is NOT a property defined in the plugin xml file. The parameter ID
496  /// should be something different than the ones used in the plugin xml.
497  /// \warning This function is guaranteed to be called by a single thread at a time.
498  /// \return True if the plug-in has some plugin-defined data. False otherwise.
499  /// \sa
500  /// - AK::Wwise::IPluginPropertySet::NotifyInternalDataChanged
501  /// - AK::IAkPluginParam::ALL_PLUGIN_DATA_ID
502  /// - AK::IAkPluginParam::SetParam
503  virtual bool GetPluginData(
504  const GUID & in_guidPlatform, ///< The unique ID of the queried platform
505  AkPluginParamID in_idParam, ///< The plugin-defined parameter ID
506  IWriteData* in_pDataWriter ///< A pointer to the data writer interface
507  ) const = 0;
508 
509  /// This function is called by Wwise to get the plug-in's HINSTANCE used for loading resources.
510  /// \warning This function is guaranteed to be called by a single thread at a time.
511  /// \return A handle to the instance of the plug-in DLL
512  /// \sa
513  /// - \ref wwiseplugin_dialogcode
514  virtual HINSTANCE GetResourceHandle() const = 0;
515 
516  /// This function is called by Wwise to get the plug-in dialog parameters.
517  /// \warning This function is guaranteed to be called by a single thread at a time.
518  /// \return True if a dialog was returned, False otherwise
519  /// \sa
520  /// - \ref wwiseplugin_dialogcode
521  /// - \ref wwiseplugin_dialog_guide
522  virtual bool GetDialog(
523  eDialog in_eDialog, ///< The dialog type
524  UINT & out_uiDialogID, ///< The returned resource ID of the dialog
525  PopulateTableItem *& out_pTable ///< The returned table of property-control bindings (can be NULL)
526  ) const = 0;
527 
528  /// Window message handler for dialogs. This is very similar to a standard WIN32 window procedure.
529  /// \warning This function is guaranteed to be called by a single thread at a time.
530  /// \return True if the message has been processed by the plug-in, False otherwise
531  /// \sa
532  /// - \ref wwiseplugin_dialogcode
533  virtual bool WindowProc(
534  eDialog in_eDialog, ///< The dialog type
535  HWND in_hWnd, ///< The window handle of the dialog
536  UINT in_message, ///< The incoming message. This is a standard Windows message ID (ex. WM_PAINT).
537  WPARAM in_wParam, ///< The WPARAM of the message (see MSDN)
538  LPARAM in_lParam, ///< The LPARAM of the message (see MSDN)
539  LRESULT & out_lResult ///< The returned value if the message has been processed (it is only considered if the method also returns True)
540  ) = 0;
541 
542  /// DEPRECATED: This function is called by Wwise to get the user-friendly name of the specified property.
543  /// This function should write the user-friendly name of
544  /// the specified property to the WCHAR buffer out_pszDisplayName,
545  /// which is of length in_unCharCount.
546  /// \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.
547  /// \warning This function is guaranteed to be called by a single thread at a time.
548  /// \return True if the property has a user-friendly name, False otherwise
549  /// \sa
550  /// - \ref wwiseplugin_displaynames
551  virtual bool DisplayNameForProp(
552  LPCWSTR in_pszPropertyName, ///< The internal name of the property
553  LPWSTR out_pszDisplayName, ///< The returned user-friendly name
554  UINT in_unCharCount ///< The number of WCHAR in the buffer, including the terminating NULL
555  ) const = 0;
556 
557  /// DEPRECATED: This function is called by Wwise to get the user-friendly names of possible values for the
558  /// specified property.
559  /// This function should write pairs of value and text for the specified property to
560  /// the WCHAR buffer out_pszDisplayName, which is of length in_unCharCount.
561  /// Pairs are separated by commas, and each pair contains the value and the
562  /// text, separated by a colon. Here are a few examples:
563  /// - Numeric property: "-100:Left,0:Center,100:Right"
564  /// - Boolean property: "0:Off,1:On"
565  /// - 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"
566  ///
567  /// \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.
568  /// \warning This function is guaranteed to be called by a single thread at a time.
569  /// \return True if the property has user-friendly names for some values, False otherwise
570  /// \sa
571  /// - \ref wwiseplugin_displaynames
573  LPCWSTR in_pszPropertyName, ///< The internal name of the property
574  LPWSTR out_pszValuesName, ///< The returned property value names
575  UINT in_unCharCount ///< The number of WCHAR in the buffer, including the terminating NULL character
576  ) const = 0;
577 
578  /// Called when the user clicks on the '?' icon.
579  /// \warning This function is guaranteed to be called by a single thread at a time.
580  /// \return True if the plug-in handled the help request, false otherwise
581  /// \sa
582  /// - \ref wwiseplugin_help
583  virtual bool Help(
584  HWND in_hWnd, ///< The handle of the dialog
585  eDialog in_eDialog, ///< The dialog type
586  LPCWSTR in_szLanguageCode ///< The language code in ISO639-1
587  ) const = 0;
588 
589  /// Called when an instance of the run-time component of the plug-in sends data
590  /// using \c AK::IAkEffectPluginContext::PostMonitorData(), and this plug-in's settings
591  /// are being displayed in a window. Because multiple run-time instances may exist for a single
592  /// authoring tool plug-in, the data is batched together and passed at the end of the frame.
593  virtual void NotifyMonitorData(
594  const MonitorData * in_pDataArray, ///< Array of blobs of data
595  unsigned int in_uCount, ///< Number of elements in array 'in_pDataArray'
596  bool in_bNeedsByteSwap, ///< True if data comes from platform with a different byte ordering (i.e. Big Endian)
597  bool in_bRealtime ///< True if monitoring in real-time, false if scrubbing through profiler history
598  ) = 0;
599 
600  /// Retrieve a pointer to the class implementing IPluginObjectMedia. Plug-ins using the media sources
601  /// functionality can simply return a pointer to themselves while other not using the functionality should return NULL
603 
604  /// Retrieve the licensing status of the plug-in for the given platform.
605  /// \return Licensing status of the plug-in; LicenseStatus_Unlicensed or LicenseStatus_Expired will prevent the plug-in from being included in a SoundBank.
606  /// \sa
607  /// - \ref IPluginPropertySet::GetLicenseStatus
608  /// - \ref IPluginPropertySet::GetAssetLicenseStatus
609  /// - \ref wwiseplugin_dll_license
611  const GUID & in_guidPlatform, ///< GUID of the platform
612  AK::Wwise::Severity& out_eSeverity, ///< (Optional) If set, the string placed in out_pszMessage will be shown in the log with the corresponding severity.
613  LPWSTR out_pszMessage, ///< Pointer to the buffer that will hold the message string
614  unsigned int in_uiBufferSize ///< Size of the buffer pointed by out_pszMessage (in number of WCHAR, including null terminator)
615  ) = 0;
616 
617  /// Return the minimum and maximum duration, in seconds. This function is only useful with source plug-ins.
618  /// \return True if the duration values are valid, False otherwise.
619  virtual bool GetSourceDuration(
620  double& out_dblMinDuration, ///< Minimum duration, in seconds
621  double& out_dblMaxDuration ///< Maximum duration, in seconds
622  ) const = 0;
623  };
624 
625  /// Use this base class to quickly implement most plugin functions empty
627  {
628  public:
629  virtual void SetPluginPropertySet( IPluginPropertySet * in_pPSet ){}
630  virtual void SetPluginObjectStore( IPluginObjectStore * in_pObjectStore ){}
631  virtual void SetPluginObjectMedia( IPluginObjectMedia * in_pObjectMedia ){}
632  virtual bool IsPlayable() const { return true; }
633  virtual void InitToDefault() {}
634  virtual void Delete() {}
635  virtual bool Load( AK::IXmlTextReader* in_pReader ) { return false; }
636  virtual bool Save( AK::IXmlTextWriter* in_pWriter ) { return false; }
637  virtual bool CopyInto( IAudioPlugin* io_pWObject ) const { return true; }
638  virtual void NotifyCurrentPlatformChanged( const GUID & in_guidCurrentPlatform ) {}
639  virtual void NotifyPropertyChanged( const GUID & in_guidPlatform, LPCWSTR in_pszPropertyName ) {}
640  virtual void NotifyInnerObjectPropertyChanged( IPluginPropertySet* in_pPSet, const GUID & in_guidPlatform, LPCWSTR in_pszPropertyName ) {}
641  virtual void NotifyInnerObjectAddedRemoved( IPluginPropertySet* in_pPSet, unsigned int in_uiIndex, NotifyInnerObjectOperation in_eOperation ) {}
642  virtual void NotifyPluginMediaChanged() {}
643  virtual bool GetBankParameters( const GUID & in_guidPlatform, IWriteData* in_pDataWriter ) const { return false; }
644  virtual bool GetPluginData( const GUID & in_guidPlatform, AkPluginParamID in_idParam, IWriteData* in_pDataWriter ) const { return false; }
645  virtual bool WindowProc( eDialog in_eDialog, HWND in_hWnd, UINT in_message, WPARAM in_wParam, LPARAM in_lParam, LRESULT & out_lResult ){ return false; }
646  virtual bool DisplayNameForProp( LPCWSTR in_pszPropertyName, LPWSTR out_pszDisplayName, UINT in_unCharCount ) const { return false; }
647  virtual bool DisplayNamesForPropValues( LPCWSTR in_pszPropertyName, LPWSTR out_pszValuesName, UINT in_unCharCount ) const { return false; }
648  virtual bool Help( HWND in_hWnd, eDialog in_eDialog, LPCWSTR in_szLanguageCode ) const { return false; }
649  virtual void NotifyMonitorData( const AK::Wwise::IAudioPlugin::MonitorData * in_pData, unsigned int in_uDataSize, bool in_bNeedsByteSwap, bool in_bRealtime){}
651  virtual AK::Wwise::LicenseStatus GetLicenseStatus(const GUID &, AK::Wwise::Severity&, LPWSTR, unsigned int in_uiBufferSize){ return AK::Wwise::LicenseStatus_Valid; }
652  virtual bool GetSourceDuration( double& out_dblMinDuration, double& out_dblMaxDuration ) const { out_dblMinDuration = 0.f; out_dblMaxDuration = FLT_MAX; return false; }
653  virtual HINSTANCE GetResourceHandle() const { return NULL; }
654  virtual bool GetDialog(eDialog in_eDialog, UINT& out_uiDialogID, PopulateTableItem*& out_pTable) const { return false; }
655  };
656 
657  #ifdef AK_WIN
660  {
661  if (!g_pAKPluginList)
662  {
663  AKASSERT(!"g_pAKPluginList is NULL. Did you use the AK_STATIC_LINK_PLUGIN macro in your DLL?"); // Should be populated by now.
664  return AK_Fail;
665  }
666 
667  HMODULE hLib = ::LoadLibrary(L"WwiseSoundEngine.dll");
668  if (hLib == NULL)
669  return AK_Fail;
670 
671  RegisterWwisePluginFn pReg = (RegisterWwisePluginFn)::GetProcAddress(hLib, "RegisterWwisePlugin20192");
672  if (pReg == NULL)
673  return AK_Fail;
674 
675  return pReg(g_pAKPluginList);
676  }
677  #endif
678 
679  /// Struct to be used with the function GetSinkPluginDevices to return devices.
680 #define AK_MAX_OUTPUTDEVICEDESCRIPTOR 256
682  {
683  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.
684  AkUInt32 idDevice; /// ID of the device as used with AK::SoundEngine::AddOutput.
685  /// This will be passed back to the plugin through AK::IAkSinkPluginContext::GetOutputID.
686  /// Default device ID can be 0.
687  };
688  }
689 }
690 
691 /// Private message sent to Wwise window to open a topic in the help file
692 /// the WPARAM defines the help topic ID
693 #ifndef WM_AK_PRIVATE_SHOW_HELP_TOPIC
694 #define WM_AK_PRIVATE_SHOW_HELP_TOPIC 0x4981
695 #endif
696 
697 #endif // _AK_WWISE_AUDIOPLUGIN_H
virtual bool Load(AK::IXmlTextReader *in_pReader)
Definition: AudioPlugin.h:635
virtual IPluginPropertySet * CreateObject(LPCWSTR in_pszType)=0
virtual bool GetBankParameters(const GUID &in_guidPlatform, IWriteData *in_pDataWriter) const =0
uint64_t AkUInt64
Unsigned 64-bit integer.
Definition: AkTypes.h:86
virtual bool WindowProc(eDialog in_eDialog, HWND in_hWnd, UINT in_message, WPARAM in_wParam, LPARAM in_lParam, LRESULT &out_lResult)
Definition: AudioPlugin.h:645
virtual bool DisplayNamesForPropValues(LPCWSTR in_pszPropertyName, LPWSTR out_pszValuesName, UINT in_unCharCount) const =0
virtual AK::Wwise::LicenseStatus GetLicenseStatus(const GUID &in_guidPlatform, AK::Wwise::Severity &out_eSeverity, LPWSTR out_pszMessage, unsigned int in_uiBufferSize)=0
Audiokinetic namespace.
@ AK_Fail
The operation failed.
Definition: AkTypes.h:125
virtual bool RemoveObject(IPluginPropertySet *in_pPropertySet)=0
virtual const GUID & GetID() const =0
Obtain the unique identifier of the corresponding IWObject.
virtual void SetPluginPropertySet(IPluginPropertySet *in_pPSet)=0
AKRESULT RegisterWwisePlugin()
Definition: AudioPlugin.h:659
AK_DLLEXPORT AK::PluginRegistration * g_pAKPluginList
Definition: IAkPlugin.h:81
virtual IPluginMediaConverter * GetPluginMediaConverterInterface()
Definition: AudioPlugin.h:650
virtual ULONG GetCurrentConversionSettingsHash(const GUID &in_guidPlatform, AkUInt32 in_uSampleRate=0, AkUInt32 in_uBlockLength=0)=0
virtual HINSTANCE GetResourceHandle() const
Definition: AudioPlugin.h:653
virtual bool GetBankParameters(const GUID &in_guidPlatform, IWriteData *in_pDataWriter) const
Definition: AudioPlugin.h:643
AKRESULT
Standard function call result.
Definition: AkTypes.h:122
virtual bool DisplayNameForProp(LPCWSTR in_pszPropertyName, LPWSTR out_pszDisplayName, UINT in_unCharCount) const
Definition: AudioPlugin.h:646
virtual bool Help(HWND in_hWnd, eDialog in_eDialog, LPCWSTR in_szLanguageCode) const =0
virtual unsigned int GetConvertedDirectory(LPWSTR out_pszDirectory, unsigned int in_uiBufferSize, const GUID &in_guidPlatform) const =0
virtual bool CanLogUndos()=0
virtual unsigned int GetListName(unsigned int in_uiListIndex, LPWSTR out_pszListName, unsigned int in_uiBufferSize) const =0
virtual bool CopyInto(IAudioPlugin *io_pWObject) const =0
virtual bool WindowProc(eDialog in_eDialog, HWND in_hWnd, UINT in_message, WPARAM in_wParam, LPARAM in_lParam, LRESULT &out_lResult)=0
ConversionResult
Conversion error code.
Definition: Utilities.h:192
virtual IPluginMediaConverter * GetPluginMediaConverterInterface()=0
@ LicenseStatus_Valid
A license is found and is valid.
Definition: Utilities.h:97
LicenseType
License type.
Definition: Utilities.h:86
virtual void NotifyMonitorData(const MonitorData *in_pDataArray, unsigned int in_uCount, bool in_bNeedsByteSwap, bool in_bRealtime)=0
#define NULL
Definition: AkTypes.h:49
virtual unsigned int GetMediaSourceCount() const =0
virtual AK::Wwise::LicenseStatus GetLicenseStatus(const GUID &, AK::Wwise::Severity &, LPWSTR, unsigned int in_uiBufferSize)
Definition: AudioPlugin.h:651
AkUInt32 idDevice
Display name of the device. Null terminated. Note that the name can't be more than 256 characters inc...
Definition: AudioPlugin.h:684
virtual bool PropertyHasRTPC(LPCWSTR in_pszPropertyName)=0
virtual void NotifyPropertyChanged(const GUID &in_guidPlatform, LPCWSTR in_pszPropertyName)=0
virtual ConversionResult ConvertFile(const GUID &in_guidPlatform, const BasePlatformID &in_basePlatform, LPCWSTR in_szSourceFile, LPCWSTR in_szDestFile, AkUInt32 in_uSampleRate, AkUInt32 in_uBlockLength, AK::Wwise::IProgress *in_pProgress, IWriteString *io_pError)=0
Use this base class to quickly implement most plugin functions empty.
Definition: AudioPlugin.h:627
virtual bool GetValue(const GUID &in_guidPlatform, LPCWSTR in_pszPropertyName, VARIANT &out_varProperty)=0
NotifyInnerObjectOperation
Type of operation for the NotifyInnerObjectAddedRemoved function.
Definition: AudioPlugin.h:349
AKRESULT(CALLBACK * RegisterWwisePluginFn)(AK::PluginRegistration *in_pList)
Definition: AudioPlugin.h:658
virtual void NotifyInnerObjectAddedRemoved(IPluginPropertySet *in_pPSet, unsigned int in_uiIndex, NotifyInnerObjectOperation in_eOperation)=0
virtual IPluginPropertySet * GetObject(LPCWSTR in_pszListName, unsigned int in_uiIndex) const =0
virtual unsigned int GetOriginalDirectory(LPWSTR out_pszDirectory, unsigned int in_uiBufferSize) const =0
virtual void WaapiCall(const char *in_szUri, const char *in_szArgs, const char *in_szOptions, AK::IAkPluginMemAlloc *in_pAlloc, char *&out_szResults, char *&out_szError) const =0
Find and call the specified procedure. Calls made using this function are always blocking.
virtual unsigned int GetMediaSourceConvertedFilePath(LPWSTR out_pszFileName, unsigned int in_uiBufferSize, const GUID &in_guidPlatform, unsigned int in_Index=0) const =0
#define AKASSERT(Condition)
Definition: AkAssert.h:76
virtual bool GetSourceDuration(double &out_dblMinDuration, double &out_dblMaxDuration) const =0
virtual void NotifyInnerObjectPropertyChanged(IPluginPropertySet *in_pPSet, const GUID &in_guidPlatform, LPCWSTR in_pszPropertyName)=0
virtual void NotifyMonitorData(const AK::Wwise::IAudioPlugin::MonitorData *in_pData, unsigned int in_uDataSize, bool in_bNeedsByteSwap, bool in_bRealtime)
Definition: AudioPlugin.h:649
virtual HINSTANCE GetResourceHandle() const =0
virtual bool GetDialog(eDialog in_eDialog, UINT &out_uiDialogID, PopulateTableItem *&out_pTable) const =0
virtual void InsertObject(LPCWSTR in_pszListName, unsigned int in_uiIndex, IPluginPropertySet *in_pPropertySet)=0
virtual void NotifyInternalDataChanged(AkPluginParamID in_idData, bool in_bMakeProjectDirty=true)=0
virtual BasePlatformID GetCurrentBasePlatform()=0
virtual void SetPluginPropertySet(IPluginPropertySet *in_pPSet)
Definition: AudioPlugin.h:629
virtual bool Load(AK::IXmlTextReader *in_pReader)=0
virtual GUID GetCurrentPlatform()=0
virtual void InvalidateMediaSource(unsigned int in_Index=0)=0
Request Wwise to perform any required conversion on the data.
WCHAR name[AK_MAX_OUTPUTDEVICEDESCRIPTOR]
Definition: AudioPlugin.h:683
virtual bool DisplayNameForProp(LPCWSTR in_pszPropertyName, LPWSTR out_pszDisplayName, UINT in_unCharCount) const =0
virtual void NotifyCurrentPlatformChanged(const GUID &in_guidCurrentPlatform)=0
virtual bool SetValue(const GUID &in_guidPlatform, LPCWSTR in_pszPropertyName, const VARIANT &in_varProperty)=0
virtual bool Save(AK::IXmlTextWriter *in_pWriter)=0
virtual bool DisplayNamesForPropValues(LPCWSTR in_pszPropertyName, LPWSTR out_pszValuesName, UINT in_unCharCount) const
Definition: AudioPlugin.h:647
virtual GUID GetAuthoringPlaybackPlatform()=0
This function is called To retrieve the custom platform being used to run while in authoring.
virtual void SetPluginObjectStore(IPluginObjectStore *in_pObjectStore)
Definition: AudioPlugin.h:630
virtual void InitToDefault()=0
virtual bool Help(HWND in_hWnd, eDialog in_eDialog, LPCWSTR in_szLanguageCode) const
Definition: AudioPlugin.h:648
LicenseStatus
License status.
Definition: Utilities.h:94
virtual bool GetSourceDuration(double &out_dblMinDuration, double &out_dblMaxDuration) const
Definition: AudioPlugin.h:652
virtual void NotifyPluginMediaChanged()=0
virtual AK::Wwise::IUndoManager * GetUndoManager()=0
virtual bool GetPluginData(const GUID &in_guidPlatform, AkPluginParamID in_idParam, IWriteData *in_pDataWriter) const =0
virtual void Delete()=0
virtual bool IsPlayable() const =0
virtual void NotifyInnerObjectAddedRemoved(IPluginPropertySet *in_pPSet, unsigned int in_uiIndex, NotifyInnerObjectOperation in_eOperation)
Definition: AudioPlugin.h:641
virtual bool CopyInto(IAudioPlugin *io_pWObject) const
Definition: AudioPlugin.h:637
virtual bool Save(AK::IXmlTextWriter *in_pWriter)
Definition: AudioPlugin.h:636
virtual unsigned int GetListCount() const =0
virtual void GetAssetLicenseStatus(const GUID &in_guidPlatform, AkUInt32 in_uAssetID, AK::Wwise::LicenseType &out_eType, AK::Wwise::LicenseStatus &out_eStatus, UINT32 &out_uDaysToExpiry)=0
Obtain licensing status for a plug-in-specific asset ID. Refer to Managing Licenses for more informat...
virtual unsigned int GetMediaSourceOriginalFilePath(LPWSTR out_pszFileName, unsigned int in_uiBufferSize, unsigned int in_Index=0) const =0
#define AK_MAX_OUTPUTDEVICEDESCRIPTOR
Struct to be used with the function GetSinkPluginDevices to return devices.
Definition: AudioPlugin.h:680
virtual void NotifyPropertyChanged(const GUID &in_guidPlatform, LPCWSTR in_pszPropertyName)
Definition: AudioPlugin.h:639
AkInt16 AkPluginParamID
Source or effect plug-in parameter ID.
Definition: AkTypes.h:71
virtual void NotifyInnerObjectPropertyChanged(IPluginPropertySet *in_pPSet, const GUID &in_guidPlatform, LPCWSTR in_pszPropertyName)
Definition: AudioPlugin.h:640
virtual void DeleteObject(IPluginPropertySet *in_pPropertySet)=0
virtual void SetPluginObjectStore(IPluginObjectStore *in_pObjectStore)=0
virtual unsigned int GetMediaSourceFileName(LPWSTR out_pszFileName, unsigned int in_uiBufferSize, unsigned int in_Index=0) const =0
virtual bool GetPluginData(const GUID &in_guidPlatform, AkPluginParamID in_idParam, IWriteData *in_pDataWriter) const
Definition: AudioPlugin.h:644
virtual unsigned int GetObjectCount(LPCWSTR in_pszListName) const =0
virtual void RemoveMediaSource(unsigned int in_Index=0)=0
Requests to remove the specified index file s a data input file.
uint32_t AkUInt32
Unsigned 32-bit integer.
Definition: AkTypes.h:85
virtual bool GetDialog(eDialog in_eDialog, UINT &out_uiDialogID, PopulateTableItem *&out_pTable) const
Definition: AudioPlugin.h:654
virtual void GetLicenseStatus(const GUID &in_guidPlatform, AK::Wwise::LicenseType &out_eType, AK::Wwise::LicenseStatus &out_eStatus, UINT32 &out_uDaysToExpiry)=0
Obtain licensing status for the plug-in. Refer to Managing Licenses for more information.
virtual void SetPluginObjectMedia(IPluginObjectMedia *in_pObjectMedia)
Definition: AudioPlugin.h:631
virtual bool SetMediaSource(LPCWSTR in_pszFilePathToImport, unsigned int in_Index=0, bool in_bReplace=false)=0
Requests to set the specified file as a data input file.
virtual void SetPluginObjectMedia(IPluginObjectMedia *in_pObjectMedia)=0
virtual BasePlatformID GetDefaultNativeAuthoringPlaybackPlatform()=0
This function is called To retrieve the base platforms of the authoring tool.
Severity
Log message severity.
Definition: Utilities.h:104
virtual void NotifyCurrentPlatformChanged(const GUID &in_guidCurrentPlatform)
Definition: AudioPlugin.h:638

Was this page helpful?

Need Support?

Questions? Problems? Need more info? Contact us, and we can help!

Visit our Support page

Tell us about your project. We're here to help.

Register your project and we'll help you get started with no strings attached!

Get started with Wwise