Wwise Version
Wwise SDK 2019.2.13
Utilities.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 SDK utilities.
30 
31 #ifndef _AK_WWISE_UTILITIES_H
32 #define _AK_WWISE_UTILITIES_H
33 
35 
36 //////////////////////////////////////////////////////////////////////////
37 // Populate Table macros
38 //////////////////////////////////////////////////////////////////////////
39 
40 /// Starts the declaration of a "populate table" which is used
41 /// to bind controls such as checkboxes and radio buttons to
42 /// properties of your plug-in.
43 ///
44 /// \param theName The name of the populate table. It must be unique within the current scope.
45 ///
46 /// \sa
47 /// - \ref wwiseplugin_dialog_guide_poptable
48 /// - AK_POP_ITEM()
49 /// - AK_END_POPULATE_TABLE()
50 #define AK_BEGIN_POPULATE_TABLE(theName) AK::Wwise::PopulateTableItem theName[] = {
51 
52 /// Declares an association between a dialog control and a plug-in
53 /// property within a "populate table".
54 ///
55 /// \param theID The resource ID of the control (checkbox or radio button)
56 /// \param theProp The name of the property, as defined in your plug-in's
57 /// XML definition file (refer to \ref wwiseplugin_xml_properties_tag)
58 ///
59 /// \sa
60 /// - \ref wwiseplugin_dialog_guide_poptable
61 /// - \ref wwiseplugin_xml_properties_tag
62 /// - AK_BEGIN_POPULATE_TABLE()
63 /// - AK_END_POPULATE_TABLE()
64 #define AK_POP_ITEM(theID, theProp) {theID, theProp },
65 
66 /// Ends the declaration of a "populate table".
67 ///
68 /// \sa
69 /// - \ref wwiseplugin_dialog_guide_poptable
70 /// - AK_BEGIN_POPULATE_TABLE()
71 /// - AK_POP_ITEM()
72 #define AK_END_POPULATE_TABLE() AK_POP_ITEM(0, NULL) };
73 
74 //////////////////////////////////////////////////////////////////////////
75 // Utilities
76 //////////////////////////////////////////////////////////////////////////
77 
78 // Audiokinetic namespace
79 namespace AK
80 {
81  // Audiokinetic Wwise namespace
82  namespace Wwise
83  {
84  /// License type.
86  {
87  LicenseType_Trial = 1, ///< Used for both Trial and Evaluation License handling
88  LicenseType_Purchased, ///< The license was purchased
89  LicenseType_Academic ///< The license is for academic
90  };
91 
92  /// License status.
94  {
95  LicenseStatus_Unlicensed, ///< No license found
96  LicenseStatus_Expired, ///< A license is found, but is expired
97  LicenseStatus_Valid, ///< A license is found and is valid
98 
99  LicenseStatus_Incompatible ///< The plugin was made for an older version of Wwise
100  };
101 
102  /// Log message severity.
103  enum Severity
104  {
105  Severity_Success = -1, ///< operation was executed without errors or will not produce errors
106  Severity_Message, ///< not impacting the integrity of the current operation
107  Severity_Warning, ///< potentially impacting the integrity of the current operation
108  Severity_Error, ///< impacting the integrity of the current operation
109  Severity_FatalError, ///< impacting the completion of the current operation
110 
111  };
112 
113  /// Interface to let the plug in give us a string of any size.
114  /// The pointer to the interface should not be kept.
116  {
117  public:
118  virtual void WriteString( LPCWSTR in_szString,
119  int in_iStringLength ) = 0;
120  };
121 
122  /// Interfaces used to set and get the properties from a plug in.
124  {
125  public:
126  virtual bool GetValue( LPCWSTR in_szPropertyName,
127  VARIANT& out_rValue ) const = 0;
128  };
129 
131  {
132  public:
133  virtual bool SetValue( LPCWSTR in_szPropertyName,
134  const VARIANT& in_rValue ) = 0;
135  };
136 
137  class IProgress
138  {
139  public:
140  /// Call this to set the name of the operation currently done.
141  /// If not called the operation will have an empty name in the UI.
142  /// The name should be on a single line.
143  virtual void SetCurrentOperationName( LPCWSTR in_szOperationName ) = 0;
144 
145  /// Should be called at the beginning of the operation to set the min and max value
146  virtual void SetRange( DWORD in_dwMinValue, DWORD in_dwMaxValue ) = 0;
147 
148  /// Notify of the advancement of the task.
149  virtual void NotifyProgress( DWORD in_dwProgress ) = 0;
150 
151  /// Check if the user has cancelled the task
152  virtual bool IsCancelled() = 0;
153 
154  /// Display an error message to the user.
155  /// The message should be on a single line.
156  virtual void ErrorMessage( const CStringW& in_rErrorText, Severity in_eSeverity = Severity_Warning ) = 0;
157  };
158 
159  /// Represents the association between a dialog control (such as
160  /// a checkbox or radio button) and a plug-in property.
161  /// \aknote
162  /// You should not need to use this structure directly. Instead, use the
163  /// AK_BEGIN_POPULATE_TABLE(), AK_POP_ITEM(), and AK_END_POPULATE_TABLE() macros.
164  /// \endaknote
165  /// \sa
166  /// - \ref wwiseplugin_dialog_guide_poptable
168  {
169  UINT uiID; ///< The dialog control resource ID
170  LPCWSTR pszProp; ///< The property name
171  };
172 
173  /// Base interface for all Wwise plug-ins.
174  /// \akwarning
175  /// The functions in this interface are not thread-safe, unless stated otherwise.
176  /// \endakwarning
177  /// \sa
178  /// - \ref AK::Wwise::IAudioPlugin
179  class IPluginBase
180  {
181  public:
182  /// This will be called to delete the plug-in. The object
183  /// is responsible for deleting itself when this method
184  /// is called.
185  /// \sa
186  /// - \ref wwiseplugin_destroy
187  virtual void Destroy() = 0;
188  };
189 
190  /// Conversion error code.
192  {
196  };
197 
198  /// Interface used to write data that can be converted, if needed, for the target
199  /// platform.
200  /// \aknote
201  /// All functions perform the appropriate platform-specific byte reordering
202  /// except where noted otherwise.
203  /// \endaknote
204  /// \akwarning
205  /// The functions in this interface are not thread-safe, unless stated otherwise.
206  /// \endakwarning
207  /// \sa
208  /// - \ref wwiseplugin_bank
209  /// - AK::Wwise::IAudioPlugin::GetBankParameters()
210  class IWriteData
211  {
212  public:
213  /// Writes a block of data.
214  /// \akcaution This data will always be written as-is, with no
215  /// platform-specific conversion. \endakcaution
216  /// \return True if all the data could be written, False otherwise
217  virtual bool WriteData(
218  LPCVOID in_pData, ///< A pointer to the buffer containing the data to be written
219  UINT32 in_cBytes, ///< The number of bytes to write
220  UINT32 & out_cWritten ///< The number of bytes actually written
221  ) = 0;
222 
223  [[deprecated("Not supported anymore. Please use WriteUtf16String or WriteUtf8String")]]
224  virtual bool WritePascalString(
225  LPCWSTR in_szString, ///< The string to be written; conversion is made internally
226  UINT32 in_uiStringLength ///< The string length, in number of characters
227  )
228  {
229  return false;
230  }
231 
232  /// Writes a null-terminated utf-16 string (characters are 2 bytes wide).
233  /// Handles endianness according to destination platform.
234  /// \aknote
235  /// "String" properties (as defined in the plugin's XML Description File - refer to \ref plugin_xml
236  /// for more details) are utf-16 encoded. While you are free to store this string in soundbanks as
237  /// as an ansi string (using WritePascalString()), AK::IAkPluginParam::SetParam() will be passed
238  /// an utf-16 string when you connect the authoring tool to the sound engine. Thus, WriteUtf16String()
239  /// is the preferred method for sending strings to a plug-in.
240  /// \endaknote
241  /// \return True if successful, False otherwise
242  virtual bool WriteUtf16String(
243  const wchar_t * in_szString ///< The string to be written (null-terminated).
244  ) = 0;
245 
246  /// Writes a null-terminated utf-8 string (multibyte characters).
247  /// \return True if successful, False otherwise
248  virtual bool WriteUtf8String(
249  const char * in_szString ///< The string to be written (null-terminated).
250  ) = 0;
251 
252  /// Writes a boolean value.
253  /// \return True if successful, False otherwise
254  virtual bool WriteBool(
255  bool in_bBool ///< Value to be written
256  ) = 0;
257 
258  /// Writes a byte value.
259  /// \return True if successful, False otherwise
260  virtual bool WriteByte(
261  BYTE in_bByte ///< Value to be written
262  ) = 0;
263 
264  /// Writes a 16-bit integer.
265  /// \return True if successful, False otherwise
266  virtual bool WriteInt16(
267  UINT16 in_uiInt16 ///< Value to be written
268  ) = 0;
269 
270  /// Writes a 32-bit integer.
271  /// \return True if successful, False otherwise
272  virtual bool WriteInt32(
273  UINT32 in_uiInt32 ///< Value to be written
274  ) = 0;
275 
276  /// Writes a 64-bit integer.
277  /// \return True if successful, False otherwise
278  virtual bool WriteInt64(
279  UINT64 in_uiInt64 ///< Value to be written
280  ) = 0;
281 
282  /// Writes a 32-bit, single-precision floating point value.
283  /// \return True if successful, False otherwise
284  virtual bool WriteReal32(
285  float in_fReal32 ///< Value to be written
286  ) = 0;
287 
288  /// Writes a 64-bit, double-precision floating point value.
289  /// \return True if successful, False otherwise
290  virtual bool WriteReal64(
291  double in_dblReal64 ///< Value to be written
292  ) = 0;
293  };
294  }
295 }
296 
297 #endif // _WWISE_UTILITIES_H
Audiokinetic namespace.
virtual void Destroy()=0
@ LicenseType_Purchased
The license was purchased.
Definition: Utilities.h:88
@ ConversionWarning
Definition: Utilities.h:194
virtual void ErrorMessage(const CStringW &in_rErrorText, Severity in_eSeverity=Severity_Warning)=0
UINT uiID
The dialog control resource ID.
Definition: Utilities.h:169
@ Severity_FatalError
impacting the completion of the current operation
Definition: Utilities.h:109
@ Severity_Message
not impacting the integrity of the current operation
Definition: Utilities.h:106
@ ConversionFailed
Definition: Utilities.h:195
virtual bool IsCancelled()=0
Check if the user has cancelled the task.
virtual bool WriteInt16(UINT16 in_uiInt16)=0
virtual bool WriteUtf8String(const char *in_szString)=0
virtual bool WriteData(LPCVOID in_pData, UINT32 in_cBytes, UINT32 &out_cWritten)=0
virtual void NotifyProgress(DWORD in_dwProgress)=0
Notify of the advancement of the task.
@ LicenseType_Trial
Used for both Trial and Evaluation License handling.
Definition: Utilities.h:87
ConversionResult
Conversion error code.
Definition: Utilities.h:192
@ LicenseStatus_Valid
A license is found and is valid.
Definition: Utilities.h:97
LicenseType
License type.
Definition: Utilities.h:86
LPCWSTR pszProp
The property name.
Definition: Utilities.h:170
@ Severity_Warning
potentially impacting the integrity of the current operation
Definition: Utilities.h:107
virtual bool SetValue(LPCWSTR in_szPropertyName, const VARIANT &in_rValue)=0
@ Severity_Success
operation was executed without errors or will not produce errors
Definition: Utilities.h:105
virtual bool WriteByte(BYTE in_bByte)=0
@ ConversionSuccess
Definition: Utilities.h:193
virtual void WriteString(LPCWSTR in_szString, int in_iStringLength)=0
virtual bool WriteInt32(UINT32 in_uiInt32)=0
virtual void SetRange(DWORD in_dwMinValue, DWORD in_dwMaxValue)=0
Should be called at the beginning of the operation to set the min and max value.
@ LicenseType_Academic
The license is for academic.
Definition: Utilities.h:89
LicenseStatus
License status.
Definition: Utilities.h:94
@ LicenseStatus_Expired
A license is found, but is expired.
Definition: Utilities.h:96
Interfaces used to set and get the properties from a plug in.
Definition: Utilities.h:124
virtual void SetCurrentOperationName(LPCWSTR in_szOperationName)=0
virtual bool WriteReal64(double in_dblReal64)=0
virtual bool WritePascalString(LPCWSTR in_szString, UINT32 in_uiStringLength)
Definition: Utilities.h:224
virtual bool GetValue(LPCWSTR in_szPropertyName, VARIANT &out_rValue) const =0
virtual bool WriteBool(bool in_bBool)=0
virtual bool WriteInt64(UINT64 in_uiInt64)=0
@ Severity_Error
impacting the integrity of the current operation
Definition: Utilities.h:108
virtual bool WriteReal32(float in_fReal32)=0
@ LicenseStatus_Incompatible
The plugin was made for an older version of Wwise.
Definition: Utilities.h:99
virtual bool WriteUtf16String(const wchar_t *in_szString)=0
Severity
Log message severity.
Definition: Utilities.h:104
@ LicenseStatus_Unlicensed
No license found.
Definition: Utilities.h:95