Version
menu_open
Wwise SDK 2019.1.11
Utilities.h
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 
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  /// Import channel configuration options.
85  enum AudioFileChannel
86  {
87  Channel_mono = 0,
88  Channel_stereo = 1,
89  Channel_mono_drop = 2,
90  Channel_stereo_drop = 3,
91  Channel_as_input = 4,
92  Channel_mono_drop_right = 5,
93  Channel_stereo_balance = 6,
94  };
95 
96  /// License type.
97  enum LicenseType
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.
105  enum LicenseStatus
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.
127  class IWriteString
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.
135  class IReadOnlyProperties
136  {
137  public:
138  virtual bool GetValue( LPCWSTR in_szPropertyName,
139  VARIANT& out_rValue ) const = 0;
140  };
141 
142  class IReadWriteProperties : public IReadOnlyProperties
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
196  struct PopulateTableItem
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.
218  enum ConversionResult
219  {
220  ConversionSuccess = 0,
221  ConversionWarning = 1,
222  ConversionFailed = 2,
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
AK.Wwise::Channel_as_input
@ Channel_as_input
Definition: Utilities.h:91
AK
Audiokinetic namespace.
Definition: AkWwiseSDKVersion.cs:32
AK.Wwise::IWriteData::WriteUtf16String
virtual bool WriteUtf16String(LPCWSTR in_szString)=0
AK.Wwise::IPluginBase::Destroy
virtual void Destroy()=0
AK.Wwise::IDoubleProgress
Add support for a second progress bar to the IProgress interfaces.
Definition: Utilities.h:173
AK.Wwise::LicenseType_Purchased
@ LicenseType_Purchased
The license was purchased.
Definition: Utilities.h:100
AK.Wwise::ConversionWarning
@ ConversionWarning
Definition: Utilities.h:221
AK.Wwise::PopulateTableItem::uiID
UINT uiID
The dialog control resource ID.
Definition: Utilities.h:198
AK.Wwise::Severity_FatalError
@ Severity_FatalError
impacting the completion of the current operation
Definition: Utilities.h:121
AK.Wwise::Severity_Message
@ Severity_Message
not impacting the integrity of the current operation
Definition: Utilities.h:118
AK.Wwise::ConversionFailed
@ ConversionFailed
Definition: Utilities.h:222
AK.Wwise::Channel_mono_drop
@ Channel_mono_drop
Definition: Utilities.h:89
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:99
AK.Wwise::ConversionResult
ConversionResult
Conversion error code.
Definition: Utilities.h:219
AK.Wwise::LicenseStatus_Valid
@ LicenseStatus_Valid
A license is found and is valid.
Definition: Utilities.h:109
AK.Wwise::LicenseType
LicenseType
License type.
Definition: Utilities.h:98
AK.Wwise::PopulateTableItem::pszProp
LPCWSTR pszProp
The property name.
Definition: Utilities.h:199
AK.Wwise::Severity_Warning
@ Severity_Warning
potentially impacting the integrity of the current operation
Definition: Utilities.h:119
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:117
AK.Wwise::IWriteData::WriteByte
virtual bool WriteByte(BYTE in_bByte)=0
AK.Wwise::ConversionSuccess
@ ConversionSuccess
Definition: Utilities.h:220
AK.Wwise::IWriteString::WriteString
virtual void WriteString(LPCWSTR in_szString, int in_iStringLength)=0
AK.Wwise::Channel_mono
@ Channel_mono
Definition: Utilities.h:87
AK.Wwise::IWriteData::WritePascalString
virtual bool WritePascalString(LPCWSTR in_szString, UINT32 in_uiStringLength)=0
AK.Wwise::Channel_mono_drop_right
@ Channel_mono_drop_right
Definition: Utilities.h:92
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::IDoubleProgress::SetSecondOperationName
virtual void SetSecondOperationName(LPCWSTR in_szOperationName)=0
AK.Wwise::AudioFileChannel
AudioFileChannel
Import channel configuration options.
Definition: Utilities.h:86
AK.Wwise::LicenseType_Academic
@ LicenseType_Academic
The license is for academic.
Definition: Utilities.h:101
AK.Wwise::LicenseStatus
LicenseStatus
License status.
Definition: Utilities.h:106
AK.Wwise::Channel_stereo
@ Channel_stereo
Definition: Utilities.h:88
AK.Wwise::LicenseStatus_Expired
@ LicenseStatus_Expired
A license is found, but is expired.
Definition: Utilities.h:108
AK.Wwise::IReadOnlyProperties
Interfaces used to set and get the properties from a plug in.
Definition: Utilities.h:136
AK.Wwise::IProgress::SetCurrentOperationName
virtual void SetCurrentOperationName(LPCWSTR in_szOperationName)=0
AK.Wwise::IDoubleProgress::NotifySecondProgress
virtual void NotifySecondProgress(DWORD in_dwProgress)=0
Notify of the advancement of the task.
AK.Wwise::IDoubleProgress::SetSecondRange
virtual void SetSecondRange(DWORD in_dwMinValue, DWORD in_dwMaxValue)=0
AK.Wwise::IWriteData::WriteReal64
virtual bool WriteReal64(double in_dblReal64)=0
AK.Wwise::IProgress::ErrorMessage
virtual void ErrorMessage(const CString &in_rErrorText, Severity in_eSeverity=Severity_Warning)=0
AK.Wwise::IReadOnlyProperties::GetValue
virtual bool GetValue(LPCWSTR in_szPropertyName, VARIANT &out_rValue) const =0
AK.Wwise::Channel_stereo_balance
@ Channel_stereo_balance
Definition: Utilities.h:93
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:120
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:111
AK.Wwise::Severity
Severity
Log message severity.
Definition: Utilities.h:116
AK.Wwise::Channel_stereo_drop
@ Channel_stereo_drop
Definition: Utilities.h:90
AK.Wwise::LicenseStatus_Unlicensed
@ LicenseStatus_Unlicensed
No license found.
Definition: Utilities.h:107

Cette page a-t-elle été utile ?

Besoin d'aide ?

Des questions ? Des problèmes ? Besoin de plus d'informations ? Contactez-nous, nous pouvons vous aider !

Visitez notre page d'Aide

Décrivez-nous de votre projet. Nous sommes là pour vous aider.

Enregistrez votre projet et nous vous aiderons à démarrer sans aucune obligation !

Partir du bon pied avec Wwise