Table of Contents

Wwise SDK 2019.1.6
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  /// Import channel configuration options.
86  {
94  };
95 
96  /// License type.
98  {
99  LicenseType_Trial = 1, ///< Used for both Trial and Evaluation License handling
100  LicenseType_Purchased, ///< The license was purchased
101  LicenseType_Academic ///< The license is for academic
102  };
103 
104  /// License status.
106  {
107  LicenseStatus_Unlicensed, ///< No license found
108  LicenseStatus_Expired, ///< A license is found, but is expired
109  LicenseStatus_Valid, ///< A license is found and is valid
110 
111  LicenseStatus_Incompatible ///< The plugin was made for an older version of Wwise
112  };
113 
114  /// Log message severity.
115  enum Severity
116  {
117  Severity_Success = -1, ///< operation was executed without errors or will not produce errors
118  Severity_Message, ///< not impacting the integrity of the current operation
119  Severity_Warning, ///< potentially impacting the integrity of the current operation
120  Severity_Error, ///< impacting the integrity of the current operation
121  Severity_FatalError, ///< impacting the completion of the current operation
122 
123  };
124 
125  /// Interface to let the plug in give us a string of any size.
126  /// The pointer to the interface should not be kept.
128  {
129  public:
130  virtual void WriteString( LPCWSTR in_szString,
131  int in_iStringLength ) = 0;
132  };
133 
134  /// Interfaces used to set and get the properties from a plug in.
136  {
137  public:
138  virtual bool GetValue( LPCWSTR in_szPropertyName,
139  VARIANT& out_rValue ) const = 0;
140  };
141 
143  {
144  public:
145  virtual bool SetValue( LPCWSTR in_szPropertyName,
146  const VARIANT& in_rValue ) = 0;
147  };
148 
149  class IProgress
150  {
151  public:
152  /// Call this to set the name of the operation currently done.
153  /// If not called the operation will have an empty name in the UI.
154  /// The name should be on a single line.
155  virtual void SetCurrentOperationName( LPCWSTR in_szOperationName ) = 0;
156 
157  /// Should be called at the beginning of the operation to set the min and max value
158  virtual void SetRange( DWORD in_dwMinValue, DWORD in_dwMaxValue ) = 0;
159 
160  /// Notify of the advancement of the task.
161  virtual void NotifyProgress( DWORD in_dwProgress ) = 0;
162 
163  /// Check if the user has cancelled the task
164  virtual bool IsCancelled() = 0;
165 
166  /// Display an error message to the user.
167  /// The message should be on a single line.
168  virtual void ErrorMessage( const CString& in_rErrorText, Severity in_eSeverity = Severity_Warning ) = 0;
169  };
170 
171  /// Add support for a second progress bar to the IProgress interfaces
172  class IDoubleProgress : public IProgress
173  {
174  public:
175  /// Call this to set the name of the second operation currently done.
176  /// If not called the operation will have an empty name in the UI.
177  /// The name should be on a single line.
178  virtual void SetSecondOperationName( LPCWSTR in_szOperationName ) = 0;
179 
180  /// Should be called at the beginning of the operation to set the min and max value
181  /// of the second progress bar.
182  virtual void SetSecondRange( DWORD in_dwMinValue, DWORD in_dwMaxValue ) = 0;
183 
184  /// Notify of the advancement of the task.
185  virtual void NotifySecondProgress( DWORD in_dwProgress ) = 0;
186  };
187 
188  /// Represents the association between a dialog control (such as
189  /// a checkbox or radio button) and a plug-in property.
190  /// \aknote
191  /// You should not need to use this structure directly. Instead, use the
192  /// AK_BEGIN_POPULATE_TABLE(), AK_POP_ITEM(), and AK_END_POPULATE_TABLE() macros.
193  /// \endaknote
194  /// \sa
195  /// - \ref wwiseplugin_dialog_guide_poptable
197  {
198  UINT uiID; ///< The dialog control resource ID
199  LPCWSTR pszProp; ///< The property name
200  };
201 
202  /// Base interface for all Wwise plug-ins.
203  /// \warning The functions in this interface are not thread-safe, unless stated otherwise.
204  /// \sa
205  /// - \ref AK::Wwise::IAudioPlugin
206  class IPluginBase
207  {
208  public:
209  /// This will be called to delete the plug-in. The object
210  /// is responsible for deleting itself when this method
211  /// is called.
212  /// \sa
213  /// - \ref wwiseplugin_destroy
214  virtual void Destroy() = 0;
215  };
216 
217  /// Conversion error code.
219  {
223  };
224 
225  /// Interface used to write data that can be converted, if needed, for the target
226  /// platform.
227  /// \aknote
228  /// All functions perform the appropriate platform-specific byte reordering
229  /// except where noted otherwise.
230  /// \endaknote
231  /// \warning The functions in this interface are not thread-safe, unless stated otherwise.
232  /// \sa
233  /// - \ref wwiseplugin_bank
234  /// - AK::Wwise::IAudioPlugin::GetBankParameters()
235  class IWriteData
236  {
237  public:
238  /// Writes a block of data.
239  /// \akcaution This data will always be written as-is, with no
240  /// platform-specific conversion. \endakcaution
241  /// \return True if all the data could be written, False otherwise
242  virtual bool WriteData(
243  LPCVOID in_pData, ///< A pointer to the buffer containing the data to be written
244  UINT32 in_cBytes, ///< The number of bytes to write
245  UINT32 & out_cWritten ///< The number of bytes actually written
246  ) = 0;
247 
248  /// Writes a single-byte character string which does not need to be null-terminated.
249  /// Strings are limited to 256 characters, and are stored as described below.
250  /// Your run-time plug-in receives a blob of data (AK::IAkPluginParam::Init() and AK::IAkPluginParam::SetParamsBlock())
251  /// which you need to interpret.
252  /// - BYTE: size_of_string
253  /// - char[]: array_of_characters.
254  ///
255  /// \aknote
256  /// "String" properties (as defined in the plugin's XML Description File - refer to \ref plugin_xml
257  /// for more details) are utf-16 encoded. While you are free to store this string in soundbanks as
258  /// as an ansi string, AK::IAkPluginParam::SetParam() will be passed an utf-16 string when you
259  /// connect the authoring tool to the sound engine. Thus, WriteUtf16String() is the preferred method
260  /// for sending strings to a plug-in.
261  /// \endaknote
262  /// \return True if successful, False otherwise
263  virtual bool WritePascalString(
264  LPCWSTR in_szString, ///< The string to be written; conversion is made internally
265  UINT32 in_uiStringLength ///< The string length, in number of characters
266  ) = 0;
267 
268  /// Writes a null-terminated utf-16 string (characters are 2 bytes wide).
269  /// Handles endianness according to destination platform.
270  /// \aknote
271  /// "String" properties (as defined in the plugin's XML Description File - refer to \ref plugin_xml
272  /// for more details) are utf-16 encoded. While you are free to store this string in soundbanks as
273  /// as an ansi string (using WritePascalString()), AK::IAkPluginParam::SetParam() will be passed
274  /// an utf-16 string when you connect the authoring tool to the sound engine. Thus, WriteUtf16String()
275  /// is the preferred method for sending strings to a plug-in.
276  /// \endaknote
277  /// \return True if successful, False otherwise
278  virtual bool WriteUtf16String(
279  LPCWSTR in_szString ///< The string to be written (null-terminated).
280  ) = 0;
281 
282  /// Writes a null-terminated utf-8 string (multibyte characters).
283  /// \return True if successful, False otherwise
284  virtual bool WriteUtf8String(
285  const char * in_szString ///< The string to be written (null-terminated).
286  ) = 0;
287 
288  /// Writes a boolean value.
289  /// \return True if successful, False otherwise
290  virtual bool WriteBool(
291  bool in_bBool ///< Value to be written
292  ) = 0;
293 
294  /// Writes a byte value.
295  /// \return True if successful, False otherwise
296  virtual bool WriteByte(
297  BYTE in_bByte ///< Value to be written
298  ) = 0;
299 
300  /// Writes a 16-bit integer.
301  /// \return True if successful, False otherwise
302  virtual bool WriteInt16(
303  UINT16 in_uiInt16 ///< Value to be written
304  ) = 0;
305 
306  /// Writes a 32-bit integer.
307  /// \return True if successful, False otherwise
308  virtual bool WriteInt32(
309  UINT32 in_uiInt32 ///< Value to be written
310  ) = 0;
311 
312  /// Writes a 64-bit integer.
313  /// \return True if successful, False otherwise
314  virtual bool WriteInt64(
315  UINT64 in_uiInt64 ///< Value to be written
316  ) = 0;
317 
318  /// Writes a 32-bit, single-precision floating point value.
319  /// \return True if successful, False otherwise
320  virtual bool WriteReal32(
321  float in_fReal32 ///< Value to be written
322  ) = 0;
323 
324  /// Writes a 64-bit, double-precision floating point value.
325  /// \return True if successful, False otherwise
326  virtual bool WriteReal64(
327  double in_dblReal64 ///< Value to be written
328  ) = 0;
329  };
330  }
331 }
332 
333 #endif // _WWISE_UTILITIES_H
UINT uiID
The dialog control resource ID.
Definition: Utilities.h:198
virtual void ErrorMessage(const CString &in_rErrorText, Severity in_eSeverity=Severity_Warning)=0
virtual bool WriteReal32(float in_fReal32)=0
virtual bool WriteData(LPCVOID in_pData, UINT32 in_cBytes, UINT32 &out_cWritten)=0
virtual void Destroy()=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.
virtual bool GetValue(LPCWSTR in_szPropertyName, VARIANT &out_rValue) const =0
virtual bool WritePascalString(LPCWSTR in_szString, UINT32 in_uiStringLength)=0
The license was purchased.
Definition: Utilities.h:100
Audiokinetic namespace.
Interfaces used to set and get the properties from a plug in.
Definition: Utilities.h:135
virtual bool WriteByte(BYTE in_bByte)=0
virtual void SetSecondOperationName(LPCWSTR in_szOperationName)=0
not impacting the integrity of the current operation
Definition: Utilities.h:118
virtual void SetCurrentOperationName(LPCWSTR in_szOperationName)=0
virtual void SetSecondRange(DWORD in_dwMinValue, DWORD in_dwMaxValue)=0
A license is found, but is expired.
Definition: Utilities.h:108
A license is found and is valid.
Definition: Utilities.h:109
AudioFileChannel
Import channel configuration options.
Definition: Utilities.h:85
virtual bool WriteReal64(double in_dblReal64)=0
operation was executed without errors or will not produce errors
Definition: Utilities.h:117
virtual void NotifyProgress(DWORD in_dwProgress)=0
Notify of the advancement of the task.
LicenseStatus
License status.
Definition: Utilities.h:105
virtual bool IsCancelled()=0
Check if the user has cancelled the task.
The license is for academic.
Definition: Utilities.h:101
virtual bool WriteUtf16String(LPCWSTR in_szString)=0
virtual bool WriteUtf8String(const char *in_szString)=0
virtual bool WriteInt64(UINT64 in_uiInt64)=0
virtual void NotifySecondProgress(DWORD in_dwProgress)=0
Notify of the advancement of the task.
No license found.
Definition: Utilities.h:107
virtual bool SetValue(LPCWSTR in_szPropertyName, const VARIANT &in_rValue)=0
LPCWSTR pszProp
The property name.
Definition: Utilities.h:199
ConversionResult
Conversion error code.
Definition: Utilities.h:218
Add support for a second progress bar to the IProgress interfaces.
Definition: Utilities.h:172
LicenseType
License type.
Definition: Utilities.h:97
The plugin was made for an older version of Wwise.
Definition: Utilities.h:111
virtual bool WriteInt32(UINT32 in_uiInt32)=0
Used for both Trial and Evaluation License handling.
Definition: Utilities.h:99
virtual void WriteString(LPCWSTR in_szString, int in_iStringLength)=0
impacting the integrity of the current operation
Definition: Utilities.h:120
virtual bool WriteInt16(UINT16 in_uiInt16)=0
impacting the completion of the current operation
Definition: Utilities.h:121
potentially impacting the integrity of the current operation
Definition: Utilities.h:119
virtual bool WriteBool(bool in_bBool)=0
Severity
Log message severity.
Definition: Utilities.h:115