Version
menu_open
link
Wwise SDK 2023.1.4
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) 2024 Audiokinetic Inc.
25 *******************************************************************************/
26 
27 /// \file
28 /// Wwise SDK utilities.
29 
30 #ifndef _AK_WWISE_UTILITIES_H
31 #define _AK_WWISE_UTILITIES_H
32 
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.
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.
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.
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.
123  {
124  public:
125  virtual bool GetValue( LPCWSTR in_szPropertyName,
126  VARIANT& out_rValue ) const = 0;
127  };
128 
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
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
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.
189  {
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()
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
Audiokinetic namespace.
virtual void Destroy()=0
@ LicenseType_Purchased
The license was purchased.
Definition: Utilities.h:87
@ ConversionWarning
Definition: Utilities.h:191
virtual void ErrorMessage(const CStringW &in_rErrorText, Severity in_eSeverity=Severity_Warning)=0
UINT uiID
The dialog control resource ID.
Definition: Utilities.h:168
@ Severity_FatalError
impacting the completion of the current operation
Definition: Utilities.h:108
@ Severity_Message
not impacting the integrity of the current operation
Definition: Utilities.h:105
@ ConversionFailed
Definition: Utilities.h:192
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:86
ConversionResult
Conversion error code.
Definition: Utilities.h:189
@ LicenseStatus_Valid
A license is found and is valid.
Definition: Utilities.h:96
LicenseType
License type.
Definition: Utilities.h:85
LPCWSTR pszProp
The property name.
Definition: Utilities.h:169
@ Severity_Warning
potentially impacting the integrity of the current operation
Definition: Utilities.h:106
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:104
virtual bool WriteByte(BYTE in_bByte)=0
@ ConversionSuccess
Definition: Utilities.h:190
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:88
LicenseStatus
License status.
Definition: Utilities.h:93
@ LicenseStatus_Expired
A license is found, but is expired.
Definition: Utilities.h:95
Interfaces used to set and get the properties from a plug in.
Definition: Utilities.h:123
virtual void SetCurrentOperationName(LPCWSTR in_szOperationName)=0
virtual bool WriteReal64(double in_dblReal64)=0
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:107
virtual bool WriteReal32(float in_fReal32)=0
@ LicenseStatus_Incompatible
The plugin was made for an older version of Wwise.
Definition: Utilities.h:98
Severity
Log message severity.
Definition: Utilities.h:103
@ 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