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