Table of Contents
include/AK/Wwise/Utilities.h
Go to the documentation of this file.00001 /******************************************************************************* 00002 The content of this file includes portions of the AUDIOKINETIC Wwise Technology 00003 released in source code form as part of the SDK installer package. 00004 00005 Commercial License Usage 00006 00007 Licensees holding valid commercial licenses to the AUDIOKINETIC Wwise Technology 00008 may use this file in accordance with the end user license agreement provided 00009 with the software or, alternatively, in accordance with the terms contained in a 00010 written agreement between you and Audiokinetic Inc. 00011 00012 Apache License Usage 00013 00014 Alternatively, this file may be used under the Apache License, Version 2.0 (the 00015 "Apache License"); you may not use this file except in compliance with the 00016 Apache License. You may obtain a copy of the Apache License at 00017 http://www.apache.org/licenses/LICENSE-2.0. 00018 00019 Unless required by applicable law or agreed to in writing, software distributed 00020 under the Apache License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES 00021 OR CONDITIONS OF ANY KIND, either express or implied. See the Apache License for 00022 the specific language governing permissions and limitations under the License. 00023 00024 Version: <VERSION> Build: <BUILDNUMBER> 00025 Copyright (c) <COPYRIGHTYEAR> Audiokinetic Inc. 00026 *******************************************************************************/ 00027 00028 /// \file 00029 /// Wwise SDK utilities. 00030 00031 #ifndef _AK_WWISE_UTILITIES_H 00032 #define _AK_WWISE_UTILITIES_H 00033 00034 #include <AK/SoundEngine/Common/AkTypes.h> 00035 00036 ////////////////////////////////////////////////////////////////////////// 00037 // Populate Table macros 00038 ////////////////////////////////////////////////////////////////////////// 00039 00040 /// Starts the declaration of a "populate table" which is used 00041 /// to bind controls such as checkboxes and radio buttons to 00042 /// properties of your plug-in. 00043 /// 00044 /// \param theName The name of the populate table. It must be unique within the current scope. 00045 /// 00046 /// \sa 00047 /// - \ref wwiseplugin_dialog_guide_poptable 00048 /// - AK_POP_ITEM() 00049 /// - AK_END_POPULATE_TABLE() 00050 #define AK_BEGIN_POPULATE_TABLE(theName) AK::Wwise::PopulateTableItem theName[] = { 00051 00052 /// Declares an association between a dialog control and a plug-in 00053 /// property within a "populate table". 00054 /// 00055 /// \param theID The resource ID of the control (checkbox or radio button) 00056 /// \param theProp The name of the property, as defined in your plug-in's 00057 /// XML definition file (refer to \ref wwiseplugin_xml_properties_tag) 00058 /// 00059 /// \sa 00060 /// - \ref wwiseplugin_dialog_guide_poptable 00061 /// - \ref wwiseplugin_xml_properties_tag 00062 /// - AK_BEGIN_POPULATE_TABLE() 00063 /// - AK_END_POPULATE_TABLE() 00064 #define AK_POP_ITEM(theID, theProp) {theID, theProp }, 00065 00066 /// Ends the declaration of a "populate table". 00067 /// 00068 /// \sa 00069 /// - \ref wwiseplugin_dialog_guide_poptable 00070 /// - AK_BEGIN_POPULATE_TABLE() 00071 /// - AK_POP_ITEM() 00072 #define AK_END_POPULATE_TABLE() AK_POP_ITEM(0, NULL) }; 00073 00074 ////////////////////////////////////////////////////////////////////////// 00075 // Utilities 00076 ////////////////////////////////////////////////////////////////////////// 00077 00078 // Audiokinetic namespace 00079 namespace AK 00080 { 00081 // Audiokinetic Wwise namespace 00082 namespace Wwise 00083 { 00084 /// Import channel configuration options. 00085 enum AudioFileChannel 00086 { 00087 Channel_mono = 0, 00088 Channel_stereo = 1, 00089 Channel_mono_drop = 2, 00090 Channel_stereo_drop = 3, 00091 Channel_as_input = 4, 00092 Channel_mono_drop_right = 5, 00093 Channel_stereo_balance = 6, 00094 }; 00095 00096 /// License type. 00097 enum LicenseType 00098 { 00099 LicenseType_Trial = 1, ///< Used for both Trial and Evaluation License handling 00100 LicenseType_Purchased, ///< The license was purchased 00101 LicenseType_Academic ///< The license is for academic 00102 }; 00103 00104 /// License status. 00105 enum LicenseStatus 00106 { 00107 LicenseStatus_Unlicensed, ///< No license found 00108 LicenseStatus_Expired, ///< A license is found, but is expired 00109 LicenseStatus_Valid, ///< A license is found and is valid 00110 00111 LicenseStatus_Incompatible ///< The plugin was made for an older version of Wwise 00112 }; 00113 00114 /// Log message severity. 00115 enum Severity 00116 { 00117 Severity_Success = -1, ///< operation was executed without errors or will not produce errors 00118 Severity_Message, ///< not impacting the integrity of the current operation 00119 Severity_Warning, ///< potentially impacting the integrity of the current operation 00120 Severity_Error, ///< impacting the integrity of the current operation 00121 Severity_FatalError, ///< impacting the completion of the current operation 00122 00123 }; 00124 00125 /// Interface to let the plug in give us a string of any size. 00126 /// The pointer to the interface should not be kept. 00127 class IWriteString 00128 { 00129 public: 00130 virtual void WriteString( LPCWSTR in_szString, 00131 int in_iStringLength ) = 0; 00132 }; 00133 00134 /// Interfaces used to set and get the properties from a plug in. 00135 class IReadOnlyProperties 00136 { 00137 public: 00138 virtual bool GetValue( LPCWSTR in_szPropertyName, 00139 VARIANT& out_rValue ) const = 0; 00140 }; 00141 00142 class IReadWriteProperties : public IReadOnlyProperties 00143 { 00144 public: 00145 virtual bool SetValue( LPCWSTR in_szPropertyName, 00146 const VARIANT& in_rValue ) = 0; 00147 }; 00148 00149 class IProgress 00150 { 00151 public: 00152 /// Call this to set the name of the operation currently done. 00153 /// If not called the operation will have an empty name in the UI. 00154 /// The name should be on a single line. 00155 virtual void SetCurrentOperationName( LPCWSTR in_szOperationName ) = 0; 00156 00157 /// Should be called at the beginning of the operation to set the min and max value 00158 virtual void SetRange( DWORD in_dwMinValue, DWORD in_dwMaxValue ) = 0; 00159 00160 /// Notify of the advancement of the task. 00161 virtual void NotifyProgress( DWORD in_dwProgress ) = 0; 00162 00163 /// Check if the user has cancelled the task 00164 virtual bool IsCancelled() = 0; 00165 00166 /// Display an error message to the user. 00167 /// The message should be on a single line. 00168 virtual void ErrorMessage( const CString& in_rErrorText, Severity in_eSeverity = Severity_Warning ) = 0; 00169 }; 00170 00171 /// Add support for a second progress bar to the IProgress interfaces 00172 class IDoubleProgress : public IProgress 00173 { 00174 public: 00175 /// Call this to set the name of the second operation currently done. 00176 /// If not called the operation will have an empty name in the UI. 00177 /// The name should be on a single line. 00178 virtual void SetSecondOperationName( LPCWSTR in_szOperationName ) = 0; 00179 00180 /// Should be called at the beginning of the operation to set the min and max value 00181 /// of the second progress bar. 00182 virtual void SetSecondRange( DWORD in_dwMinValue, DWORD in_dwMaxValue ) = 0; 00183 00184 /// Notify of the advancement of the task. 00185 virtual void NotifySecondProgress( DWORD in_dwProgress ) = 0; 00186 }; 00187 00188 /// Represents the association between a dialog control (such as 00189 /// a checkbox or radio button) and a plug-in property. 00190 /// \aknote 00191 /// You should not need to use this structure directly. Instead, use the 00192 /// AK_BEGIN_POPULATE_TABLE(), AK_POP_ITEM(), and AK_END_POPULATE_TABLE() macros. 00193 /// \endaknote 00194 /// \sa 00195 /// - \ref wwiseplugin_dialog_guide_poptable 00196 struct PopulateTableItem 00197 { 00198 UINT uiID; ///< The dialog control resource ID 00199 LPCWSTR pszProp; ///< The property name 00200 }; 00201 00202 /// Base interface for all Wwise plug-ins. 00203 /// \warning The functions in this interface are not thread-safe, unless stated otherwise. 00204 /// \sa 00205 /// - \ref AK::Wwise::IAudioPlugin 00206 class IPluginBase 00207 { 00208 public: 00209 /// This will be called to delete the plug-in. The object 00210 /// is responsible for deleting itself when this method 00211 /// is called. 00212 /// \sa 00213 /// - \ref wwiseplugin_destroy 00214 virtual void Destroy() = 0; 00215 }; 00216 00217 /// Conversion error code. 00218 enum ConversionResult 00219 { 00220 ConversionSuccess = 0, 00221 ConversionWarning = 1, 00222 ConversionFailed = 2, 00223 }; 00224 00225 /// Interface used to write data that can be converted, if needed, for the target 00226 /// platform. 00227 /// \aknote 00228 /// All functions perform the appropriate platform-specific byte reordering 00229 /// except where noted otherwise. 00230 /// \endaknote 00231 /// \warning The functions in this interface are not thread-safe, unless stated otherwise. 00232 /// \sa 00233 /// - \ref wwiseplugin_bank 00234 /// - AK::Wwise::IAudioPlugin::GetBankParameters() 00235 class IWriteData 00236 { 00237 public: 00238 /// Writes a block of data. 00239 /// \akcaution This data will always be written as-is, with no 00240 /// platform-specific conversion. \endakcaution 00241 /// \return True if all the data could be written, False otherwise 00242 virtual bool WriteData( 00243 LPCVOID in_pData, ///< A pointer to the buffer containing the data to be written 00244 UINT32 in_cBytes, ///< The number of bytes to write 00245 UINT32 & out_cWritten ///< The number of bytes actually written 00246 ) = 0; 00247 00248 /// Writes a single-byte character string which does not need to be null-terminated. 00249 /// Strings are limited to 256 characters, and are stored as described below. 00250 /// Your run-time plug-in receives a blob of data (AK::IAkPluginParam::Init() and AK::IAkPluginParam::SetParamsBlock()) 00251 /// which you need to interpret. 00252 /// - BYTE: size_of_string 00253 /// - char[]: array_of_characters. 00254 /// 00255 /// \aknote 00256 /// "String" properties (as defined in the plugin's XML Description File - refer to \ref plugin_xml 00257 /// for more details) are utf-16 encoded. While you are free to store this string in soundbanks as 00258 /// as an ansi string, AK::IAkPluginParam::SetParam() will be passed an utf-16 string when you 00259 /// connect the authoring tool to the sound engine. Thus, WriteUtf16String() is the preferred method 00260 /// for sending strings to a plug-in. 00261 /// \endaknote 00262 /// \return True if successful, False otherwise 00263 virtual bool WritePascalString( 00264 LPCWSTR in_szString, ///< The string to be written; conversion is made internally 00265 UINT32 in_uiStringLength ///< The string length, in number of characters 00266 ) = 0; 00267 00268 /// Writes a null-terminated utf-16 string (characters are 2 bytes wide). 00269 /// Handles endianness according to destination platform. 00270 /// \aknote 00271 /// "String" properties (as defined in the plugin's XML Description File - refer to \ref plugin_xml 00272 /// for more details) are utf-16 encoded. While you are free to store this string in soundbanks as 00273 /// as an ansi string (using WritePascalString()), AK::IAkPluginParam::SetParam() will be passed 00274 /// an utf-16 string when you connect the authoring tool to the sound engine. Thus, WriteUtf16String() 00275 /// is the preferred method for sending strings to a plug-in. 00276 /// \endaknote 00277 /// \return True if successful, False otherwise 00278 virtual bool WriteUtf16String( 00279 LPCWSTR in_szString ///< The string to be written (null-terminated). 00280 ) = 0; 00281 00282 /// Writes a null-terminated utf-8 string (multibyte characters). 00283 /// \return True if successful, False otherwise 00284 virtual bool WriteUtf8String( 00285 const char * in_szString ///< The string to be written (null-terminated). 00286 ) = 0; 00287 00288 /// Writes a boolean value. 00289 /// \return True if successful, False otherwise 00290 virtual bool WriteBool( 00291 bool in_bBool ///< Value to be written 00292 ) = 0; 00293 00294 /// Writes a byte value. 00295 /// \return True if successful, False otherwise 00296 virtual bool WriteByte( 00297 BYTE in_bByte ///< Value to be written 00298 ) = 0; 00299 00300 /// Writes a 16-bit integer. 00301 /// \return True if successful, False otherwise 00302 virtual bool WriteInt16( 00303 UINT16 in_uiInt16 ///< Value to be written 00304 ) = 0; 00305 00306 /// Writes a 32-bit integer. 00307 /// \return True if successful, False otherwise 00308 virtual bool WriteInt32( 00309 UINT32 in_uiInt32 ///< Value to be written 00310 ) = 0; 00311 00312 /// Writes a 64-bit integer. 00313 /// \return True if successful, False otherwise 00314 virtual bool WriteInt64( 00315 UINT64 in_uiInt64 ///< Value to be written 00316 ) = 0; 00317 00318 /// Writes a 32-bit, single-precision floating point value. 00319 /// \return True if successful, False otherwise 00320 virtual bool WriteReal32( 00321 float in_fReal32 ///< Value to be written 00322 ) = 0; 00323 00324 /// Writes a 64-bit, double-precision floating point value. 00325 /// \return True if successful, False otherwise 00326 virtual bool WriteReal64( 00327 double in_dblReal64 ///< Value to be written 00328 ) = 0; 00329 }; 00330 } 00331 } 00332 00333 #endif // _WWISE_UTILITIES_H
