Version
Wwise SDK 2021.1.10
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: v2021.1.10 Build: 7883
25  Copyright (c) 2006-2022 Audiokinetic Inc.
26 *******************************************************************************/
27 
28 /// \file
29 /// Wwise SDK utilities.
30 
31 #ifndef _AK_WWISE_UTILITIES_H
32 #define _AK_WWISE_UTILITIES_H
33 
34 #include <AK/SoundEngine/Common/AkTypes.h>
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.
85  enum LicenseType
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.
93  enum LicenseStatus
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.
115  class IWriteString
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.
123  class IReadOnlyProperties
124  {
125  public:
126  virtual bool GetValue( LPCWSTR in_szPropertyName,
127  VARIANT& out_rValue ) const = 0;
128  };
129 
130  class IReadWriteProperties : public IReadOnlyProperties
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
167  struct PopulateTableItem
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  virtual void Destroy() = 0;
186  };
187 
188  /// Conversion error code.
189  enum ConversionResult
190  {
191  ConversionSuccess = 0,
192  ConversionWarning = 1,
193  ConversionFailed = 2,
194  };
195 
196  /// Interface used to write data that can be converted, if needed, for the target
197  /// platform.
198  /// \aknote
199  /// All functions perform the appropriate platform-specific byte reordering
200  /// except where noted otherwise.
201  /// \endaknote
202  /// \akwarning
203  /// The functions in this interface are not thread-safe, unless stated otherwise.
204  /// \endakwarning
205  /// \sa
206  /// - \ref wwiseplugin_bank
207  /// - AK::Wwise::IAudioPlugin::GetBankParameters()
208  class IWriteData
209  {
210  public:
211  /// Writes a block of data.
212  /// \akcaution This data will always be written as-is, with no
213  /// platform-specific conversion. \endakcaution
214  /// \return True if all the data could be written, False otherwise
215  virtual bool WriteData(
216  LPCVOID in_pData, ///< A pointer to the buffer containing the data to be written
217  UINT32 in_cBytes, ///< The number of bytes to write
218  UINT32 & out_cWritten ///< The number of bytes actually written
219  ) = 0;
220 
221  /// Writes a null-terminated utf-8 string (multibyte characters).
222  /// \return True if successful, False otherwise
223  virtual bool WriteUtf8String(
224  const char * in_szString ///< The string to be written (null-terminated).
225  ) = 0;
226 
227  /// Writes a boolean value.
228  /// \return True if successful, False otherwise
229  virtual bool WriteBool(
230  bool in_bBool ///< Value to be written
231  ) = 0;
232 
233  /// Writes a byte value.
234  /// \return True if successful, False otherwise
235  virtual bool WriteByte(
236  BYTE in_bByte ///< Value to be written
237  ) = 0;
238 
239  /// Writes a 16-bit integer.
240  /// \return True if successful, False otherwise
241  virtual bool WriteInt16(
242  UINT16 in_uiInt16 ///< Value to be written
243  ) = 0;
244 
245  /// Writes a 32-bit integer.
246  /// \return True if successful, False otherwise
247  virtual bool WriteInt32(
248  UINT32 in_uiInt32 ///< Value to be written
249  ) = 0;
250 
251  /// Writes a 64-bit integer.
252  /// \return True if successful, False otherwise
253  virtual bool WriteInt64(
254  UINT64 in_uiInt64 ///< Value to be written
255  ) = 0;
256 
257  /// Writes a 32-bit, single-precision floating point value.
258  /// \return True if successful, False otherwise
259  virtual bool WriteReal32(
260  float in_fReal32 ///< Value to be written
261  ) = 0;
262 
263  /// Writes a 64-bit, double-precision floating point value.
264  /// \return True if successful, False otherwise
265  virtual bool WriteReal64(
266  double in_dblReal64 ///< Value to be written
267  ) = 0;
268  };
269  }
270 }
271 
272 #endif // _WWISE_UTILITIES_H
AK
Audiokinetic namespace.
Definition: AkWwiseSDKVersion.cs:32
AK.Wwise::IPluginBase::Destroy
virtual void Destroy()=0
AK.Wwise::LicenseType_Purchased
@ LicenseType_Purchased
The license was purchased.
Definition: Utilities.h:88
AK.Wwise::ConversionWarning
@ ConversionWarning
Definition: Utilities.h:192
AK.Wwise::IProgress::ErrorMessage
virtual void ErrorMessage(const CStringW &in_rErrorText, Severity in_eSeverity=Severity_Warning)=0
AK.Wwise::PopulateTableItem::uiID
UINT uiID
The dialog control resource ID.
Definition: Utilities.h:169
AK.Wwise::Severity_FatalError
@ Severity_FatalError
impacting the completion of the current operation
Definition: Utilities.h:109
AK.Wwise::Severity_Message
@ Severity_Message
not impacting the integrity of the current operation
Definition: Utilities.h:106
AK.Wwise::ConversionFailed
@ ConversionFailed
Definition: Utilities.h:193
AK.Wwise::IProgress::IsCancelled
virtual bool IsCancelled()=0
Check if the user has cancelled the task.
AK.Wwise::IWriteData::WriteInt16
virtual bool WriteInt16(UINT16 in_uiInt16)=0
AK.Wwise::IWriteData::WriteUtf8String
virtual bool WriteUtf8String(const char *in_szString)=0
AK.Wwise::IWriteData::WriteData
virtual bool WriteData(LPCVOID in_pData, UINT32 in_cBytes, UINT32 &out_cWritten)=0
AK.Wwise::IProgress::NotifyProgress
virtual void NotifyProgress(DWORD in_dwProgress)=0
Notify of the advancement of the task.
AK.Wwise::LicenseType_Trial
@ LicenseType_Trial
Used for both Trial and Evaluation License handling.
Definition: Utilities.h:87
AK.Wwise::ConversionResult
ConversionResult
Conversion error code.
Definition: Utilities.h:190
AK.Wwise::LicenseStatus_Valid
@ LicenseStatus_Valid
A license is found and is valid.
Definition: Utilities.h:97
AK.Wwise::LicenseType
LicenseType
License type.
Definition: Utilities.h:86
AK.Wwise::PopulateTableItem::pszProp
LPCWSTR pszProp
The property name.
Definition: Utilities.h:170
AK.Wwise::Severity_Warning
@ Severity_Warning
potentially impacting the integrity of the current operation
Definition: Utilities.h:107
AK.Wwise::IReadWriteProperties::SetValue
virtual bool SetValue(LPCWSTR in_szPropertyName, const VARIANT &in_rValue)=0
AK.Wwise::Severity_Success
@ Severity_Success
operation was executed without errors or will not produce errors
Definition: Utilities.h:105
AK.Wwise::IWriteData::WriteByte
virtual bool WriteByte(BYTE in_bByte)=0
AK.Wwise::ConversionSuccess
@ ConversionSuccess
Definition: Utilities.h:191
AK.Wwise::IWriteString::WriteString
virtual void WriteString(LPCWSTR in_szString, int in_iStringLength)=0
AK.Wwise::IWriteData::WriteInt32
virtual bool WriteInt32(UINT32 in_uiInt32)=0
AK.Wwise::IProgress::SetRange
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.
AK.Wwise::LicenseType_Academic
@ LicenseType_Academic
The license is for academic.
Definition: Utilities.h:89
AK.Wwise::LicenseStatus
LicenseStatus
License status.
Definition: Utilities.h:94
AK.Wwise::LicenseStatus_Expired
@ LicenseStatus_Expired
A license is found, but is expired.
Definition: Utilities.h:96
AK.Wwise::IReadOnlyProperties
Interfaces used to set and get the properties from a plug in.
Definition: Utilities.h:124
AK.Wwise::IProgress::SetCurrentOperationName
virtual void SetCurrentOperationName(LPCWSTR in_szOperationName)=0
AK.Wwise::IWriteData::WriteReal64
virtual bool WriteReal64(double in_dblReal64)=0
AK.Wwise::IReadOnlyProperties::GetValue
virtual bool GetValue(LPCWSTR in_szPropertyName, VARIANT &out_rValue) const =0
AK.Wwise::IWriteData::WriteBool
virtual bool WriteBool(bool in_bBool)=0
AK.Wwise::IWriteData::WriteInt64
virtual bool WriteInt64(UINT64 in_uiInt64)=0
AK.Wwise::Severity_Error
@ Severity_Error
impacting the integrity of the current operation
Definition: Utilities.h:108
AK.Wwise::IWriteData::WriteReal32
virtual bool WriteReal32(float in_fReal32)=0
AK.Wwise::LicenseStatus_Incompatible
@ LicenseStatus_Incompatible
The plugin was made for an older version of Wwise.
Definition: Utilities.h:99
AK.Wwise::Severity
Severity
Log message severity.
Definition: Utilities.h:104
AK.Wwise::LicenseStatus_Unlicensed
@ LicenseStatus_Unlicensed
No license found.
Definition: Utilities.h:95