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

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