Wwise SDK 2017.1.9
_i_ak_plugin_8h_source
Version
menu_open
link
include/AK/SoundEngine/Common/IAkPlugin.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 /// Software source plug-in and effect plug-in interfaces. 00030 00031 #ifndef _IAK_PLUGIN_H_ 00032 #define _IAK_PLUGIN_H_ 00033 00034 #include <AK/SoundEngine/Common/AkCommonDefs.h> 00035 #include <AK/SoundEngine/Common/IAkRTPCSubscriber.h> 00036 #include <AK/SoundEngine/Common/IAkPluginMemAlloc.h> 00037 #include <AK/SoundEngine/Common/AkFPUtilities.h> 00038 #include <AK/Tools/Common/AkLock.h> 00039 #include <AK/Tools/Common/AkPlatformFuncs.h> 00040 #include <AK/Tools/Common/AkMonitorError.h> 00041 #include <AK/SoundEngine/Common/AkSoundEngineExport.h> 00042 #include <AK/SoundEngine/Common/IAkProcessorFeatures.h> 00043 #include <AK/SoundEngine/Common/AkMidiTypes.h> 00044 #include <AK/SoundEngine/Common/AkCallback.h> 00045 #include <AK/AkWwiseSDKVersion.h> 00046 00047 #include <math.h> 00048 00049 #if defined AK_CPU_X86 || defined AK_CPU_X86_64 00050 #include <xmmintrin.h> 00051 #endif 00052 00053 #ifdef AK_VITA_HW 00054 #include <ngs.h> 00055 #endif 00056 00057 00058 #define AK_OLDEST_SUPPORTED_WWISESDK_VERSION ((2017<<8) | 1) 00059 00060 /// Plug-in information structure. 00061 /// \remarks The bIsInPlace field is only relevant for effect plug-ins. 00062 /// \sa 00063 /// - \ref iakeffect_geteffectinfo 00064 struct AkPluginInfo 00065 { 00066 /// Constructor for default values 00067 AkPluginInfo() 00068 : eType(AkPluginTypeNone) 00069 , uBuildVersion( 0 ) 00070 , bIsInPlace(true) 00071 , bCanChangeRate(false) 00072 , bReserved(false) 00073 {} 00074 00075 AkPluginType eType; ///< Plug-in type 00076 AkUInt32 uBuildVersion; ///< Plugin build version, must match the AK_WWISESDK_VERSION_COMBINED macro from AkWwiseSDKVersion.h. Prevents usage of plugins compiled for other versions, avoiding crashes or data issues. 00077 bool bIsInPlace; ///< Buffer usage (in-place or not) 00078 bool bCanChangeRate; ///< True for effects whose sample throughput is different between input and output. Effects that can change rate need to be out-of-place (!bIsInPlace), and cannot exist on busses. 00079 bool bReserved; ///< Legacy bIsAsynchronous plug-in flag, now unused. Preserved for plug-in backward compatibility. bReserved should be false for all plug-in. 00080 }; 00081 00082 //Forward declarations. 00083 namespace AK 00084 { 00085 class PluginRegistration; 00086 } 00087 extern "C" AK_DLLEXPORT AK::PluginRegistration * g_pAKPluginList; 00088 00089 struct AkAcousticTexture; 00090 00091 namespace AK 00092 { 00093 class IAkStreamMgr; 00094 class IAkGlobalPluginContext; 00095 00096 /// Game object information available to plugins. 00097 class IAkGameObjectPluginInfo 00098 { 00099 protected: 00100 /// Virtual destructor on interface to avoid warnings. 00101 virtual ~IAkGameObjectPluginInfo(){} 00102 00103 public: 00104 00105 /// Get the ID of the game object. 00106 virtual AkGameObjectID GetGameObjectID() const = 0; 00107 00108 /// Retrieve the number of emitter-listener pairs (rays) of the game object. 00109 /// A game object may have more than one position, and be listened to more than one listener. 00110 /// The returned value is the product of these two numbers. Use the returned value as a higher 00111 /// bound for the index of GetEmitterListenerPair(). 00112 /// Note that rays whose listener is irrelevant to the current context are ignored. For example, 00113 /// if the calling plug-in exists on a bus, only listeners that are routed to the end point's 00114 /// device are considered. 00115 /// \sa 00116 /// - AK::SoundEngine::SetPosition() 00117 /// - AK::SoundEngine::SetMultiplePositions() 00118 /// - AK::SoundEngine::SetListeners() 00119 /// - AK::IAkGameObjectPluginInfo::GetEmitterListenerPair() 00120 /// - AK::SoundEngine::AddSecondaryOutput() 00121 virtual AkUInt32 GetNumEmitterListenerPairs() const = 0; 00122 00123 /// Retrieve the emitter-listener pair (ray) of the game object at index in_uIndex. 00124 /// Call GetNumEmitterListenerPairs() prior to this function to get the total number of 00125 /// emitter-listener pairs of the game object. 00126 /// The emitter-listener pair is expressed as the game object's position relative to the 00127 /// listener, in spherical coordinates. 00128 /// \note 00129 /// - The distance takes game object and listener scaling factors into account. 00130 /// - Returned distance and angles are those of the game object, and do not necessarily correspond 00131 /// to any sound's positioning data. 00132 /// \return AK_Fail if the index is invalid, AK_Success otherwise. 00133 /// \sa 00134 /// - AK::SoundEngine::SetAttenuationScalingFactor() 00135 /// - AK::SoundEngine::SetScalingFactor() 00136 /// - AK::IAkGameObjectPluginInfo::GetNumEmitterListenerPairs() 00137 virtual AKRESULT GetEmitterListenerPair( 00138 AkUInt32 in_uIndex, ///< Index of the pair, [0, GetNumEmitterListenerPairs()[ 00139 AkEmitterListenerPair & out_emitterListenerPair ///< Returned relative source position in spherical coordinates. 00140 ) const = 0; 00141 00142 /// Get the number of positions of the game object. Use this value to determine the indices to be 00143 /// passed to GetGameObjectPosition(). 00144 /// \sa 00145 /// - AK::SoundEngine::SetPosition() 00146 /// - AK::SoundEngine::SetMultiplePositions() 00147 /// - AK::IAkGameObjectPluginInfo::GetGameObjectPosition(); 00148 virtual AkUInt32 GetNumGameObjectPositions() const = 0; 00149 00150 /// Get the raw position of the game object at index in_uIndex. 00151 /// Use GetNumGameObjectPositions() prior to this function to get the total number of positions 00152 /// of that game object. 00153 /// \return AK_Fail if the index is out of bounds, AK_Success otherwise. 00154 /// \sa 00155 /// - AK::SoundEngine::SetPosition() 00156 /// - AK::SoundEngine::SetMultiplePositions() 00157 /// - AK::IAkGameObjectPluginInfo::GetNumGameObjectPositions() 00158 virtual AKRESULT GetGameObjectPosition( 00159 AkUInt32 in_uIndex, ///< Index of the position, [0, GetNumGameObjectPositions()[ 00160 AkSoundPosition & out_position ///< Returned raw position info. 00161 ) const = 0; 00162 00163 /// Get the multi-position type assigned to the game object. 00164 /// \return MultiPositionType_MultiSources when the effect is instantiated on a bus. 00165 /// \sa 00166 /// - AK::SoundEngine::SetPosition() 00167 /// - AK::SoundEngine::SetMultiplePositions() 00168 virtual SoundEngine::MultiPositionType GetGameObjectMultiPositionType() const = 0; 00169 00170 /// Get the distance scaling factor of the associated game object. 00171 /// \sa 00172 /// - AK::SoundEngine::SetAttenuationScalingFactor() 00173 virtual AkReal32 GetGameObjectScaling() const = 0; 00174 00175 /// Get the game object IDs of listener game objects that are listening to the emitter game object. 00176 /// Note that only listeners relevant to the current context are considered. For example, 00177 /// if the calling plug-in exists on a bus, only listeners that are routed to the end point's 00178 /// device are added to the returned array. 00179 /// \return True if the call succeeded, false if all the listeners could not fit into the array, 00180 /// \sa 00181 /// - AK::SoundEngine::SetListeners() 00182 virtual bool GetListeners( 00183 AkGameObjectID* out_aListenerIDs, ///< Array of listener IDs to fill, or NULL to query the size needed. 00184 AkUInt32& io_uSize ///< In: max size of the array, out: number of valid elements returned in out_aListenerIDs. 00185 ) const = 0; 00186 00187 /// Get information about a listener. Use GetListeners() prior to this function 00188 /// in order to know which listeners are listening to the associated game object. 00189 /// \return AK_Fail if the listener ID is invalid. AK_Success otherwise. 00190 /// \sa 00191 /// - AK::SoundEngine::SetListeners() 00192 /// - AK::IAkGameObjectPluginInfo::GetListeners() 00193 virtual AKRESULT GetListenerData( 00194 AkGameObjectID in_uListener, ///< Bit field identifying the listener for which you desire information. 00195 AkListener & out_listener ///< Returned listener info. 00196 ) const = 0; 00197 }; 00198 00199 /// Voice-specific information available to plug-ins. The associated game object's information is 00200 /// available through the methods of the base class IAkGameObjectPluginInfo. 00201 class IAkVoicePluginInfo : public IAkGameObjectPluginInfo 00202 { 00203 protected: 00204 /// Virtual destructor on interface to avoid warnings. 00205 virtual ~IAkVoicePluginInfo(){} 00206 00207 public: 00208 00209 /// Retrieve the Playing ID of the event corresponding to this voice (if applicable). 00210 virtual AkPlayingID GetPlayingID() const = 0; 00211 00212 /// Get priority value associated to this voice. When priority voice is modified by distance, the minimum distance among emitter-listener pairs is used. 00213 /// \return The priority between AK_MIN_PRIORITY and AK_MAX_PRIORITY inclusively. 00214 virtual AkPriority GetPriority() const = 0; 00215 00216 /// Get priority value associated to this voice, for a specified distance, which may differ from the minimum distance that is used by default. 00217 /// \return The priority between AK_MIN_PRIORITY and AK_MAX_PRIORITY inclusively. 00218 virtual AkPriority ComputePriorityWithDistance( 00219 AkReal32 in_fDistance ///< Distance. 00220 ) const = 0; 00221 }; 00222 00223 /// Interface to retrieve contextual information available to all types of plugins. 00224 class IAkPluginContextBase 00225 { 00226 protected: 00227 /// Virtual destructor on interface to avoid warnings. 00228 virtual ~IAkPluginContextBase(){} 00229 00230 public: 00231 00232 /// \return The global sound engine context. 00233 /// \sa IAkGlobalPluginContext 00234 virtual IAkGlobalPluginContext* GlobalContext() const = 0; 00235 00236 /// Obtain the interface to access the game object on which the plugin is instantiated. 00237 /// \return The interface to GameObject info. 00238 virtual IAkGameObjectPluginInfo * GetGameObjectInfo() = 0; 00239 00240 /// Identify the mixing graph where the plug-in is instantiated by getting the end-point's 00241 /// output ID and device type that were given to AddSecondaryOutput(). Primary output graph 00242 /// returns out_uOutputID = 0 and out_uDeviceType = (AkUInt32)AkOutput_Main. 00243 /// Applicable to plug-ins instantiated in the Master-Mixer hierarchy only (bus insert, mixer, sink). 00244 /// Plug-ins instantiated in the Actor-Mixer hierarchy (i.e. on voices) return AK_NotCompatible. 00245 /// \sa integrating_secondary_outputs 00246 /// \return The device type and unique identifier. AK_Success if successful, AK_NotCompatible otherwise. 00247 virtual AKRESULT GetOutputID( 00248 AkUInt32 & out_uOutputID, ///< Device identifier, when multiple devices of the same type are possible. 00249 AkUInt32 & out_uDeviceType ///< Device type, must be one of the currently supported devices types. Can be casted to platforms-specific AkAudioOutputType. 00250 ) const = 0; 00251 00252 /// Return the pointer and size of the plug-in media corresponding to the specified index. 00253 /// The pointer returned will be NULL if the plug-in media is either not loaded or inexistant. 00254 /// When this function is called and returns a valid data pointer, the data can only be used by this 00255 /// instance of the plugin and is guaranteed to be valid only during the plug-in lifespan. 00256 virtual void GetPluginMedia( 00257 AkUInt32 in_dataIndex, ///< Index of the plug-in media to be returned. 00258 AkUInt8* &out_rpData, ///< Pointer to the data 00259 AkUInt32 &out_rDataSize ///< size of the data returned in bytes. 00260 ) = 0; 00261 00262 /// Return the pointer and size of the game data corresponding to the specified index, sent by the game using AK::SoundEngine::SendPluginCustomGameData(). 00263 /// The pointer returned will be NULL if the game data is inexistent. 00264 /// When this function is called and returns a valid data pointer, the data can only be used by this 00265 /// instance of the plugin and is guaranteed to be valid only during the frame. 00266 virtual void GetPluginCustomGameData( 00267 void* &out_rpData, ///< Pointer to the data 00268 AkUInt32 &out_rDataSize ///< size of the data returned in bytes. 00269 ) = 0; 00270 00271 /// Post a custom blob of data to the UI counterpart of this effect plug-in. 00272 /// Data is sent asynchronously through the profiling system. 00273 /// Notes: 00274 /// - It is only possible to post data when the instance of the plug-in is on a bus, 00275 /// because there is a one-to-one relationship with its effect settings view. 00276 /// You may call CanPostMonitorData() to determine if your plug-in can send data to the UI. 00277 /// - Data is copied into the communication buffer within this method, 00278 /// so you may discard it afterwards. 00279 /// - You need to handle byte swapping on one side or the other when sending 00280 /// data from a big-endian platform. 00281 /// - Sending data to the UI is only possible in Debug and Profile. Thus, you should 00282 /// enclose your calls to package and send that data within !AK_OPTIMIZED preprocessor flag. 00283 /// \return AK_Success if the plug-in exists on a bus, AK_Fail otherwise. 00284 virtual AKRESULT PostMonitorData( 00285 void * in_pData, ///< Blob of data. 00286 AkUInt32 in_uDataSize ///< Size of data. 00287 ) = 0; 00288 00289 /// Query the context to know if it is possible to send data to the UI counterpart of this effect plug-in. 00290 /// It is only possible to post data when the instance of the plug-in is on a bus, because there is a 00291 /// one-to-one relationship with its effect settings view. 00292 /// \return True if the instance of the plug-in is on a bus, and the authoring tool is connected and 00293 /// monitoring the game, false otherwise. 00294 /// \sa PostMonitorData() 00295 virtual bool CanPostMonitorData() = 0; 00296 00297 /// Post a monitoring message or error string. This will be displayed in the Wwise capture 00298 /// log. 00299 /// \return AK_Success if successful, AK_Fail if there was a problem posting the message. 00300 /// In optimized mode, this function returns AK_NotCompatible. 00301 /// \remark This function is provided as a tracking tool only. It does nothing if it is 00302 /// called in the optimized/release configuration and return AK_NotCompatible. 00303 virtual AKRESULT PostMonitorMessage( 00304 const char* in_pszError, ///< Message or error string to be displayed 00305 AK::Monitor::ErrorLevel in_eErrorLevel ///< Specifies whether it should be displayed as a message or an error 00306 ) = 0; 00307 00308 /// Get the cumulative gain of all mixing stages, from the host audio node down to the device end point. 00309 /// Returns 1.f when the node is an actor-mixer (voice), because a voice may be routed to several mix chains. 00310 /// \return The cumulative downstream gain. 00311 virtual AkReal32 GetDownstreamGain() = 0; 00312 00313 /// Return the channel configuration of the parent node that this effect will mix into. GetParentChannelConfig() may be used to set the output configuration of an 00314 /// out-of-place effect to avoid additional up/down mixing stages. Please note however that it is possible for out-of-place effects later in the chain to change 00315 /// this configuration. 00316 /// Returns !out_channelConfig.IsValid() when the node is an actor-mixer (voice), because a voice may be routed to several mix chains. 00317 /// \return AK_Success if the channel config of the primary, direct parent bus could be determined, AK_Fail otherwise. 00318 virtual AKRESULT GetParentChannelConfig( 00319 AkChannelConfig& out_channelConfig ///< Channel configuration of parent node (downstream bus). 00320 ) const = 0; 00321 00322 #if (defined AK_CPU_X86 || defined AK_CPU_X86_64) && !(defined AK_IOS) 00323 /// Return an interface to query processor specific features. 00324 virtual IAkProcessorFeatures * GetProcessorFeatures() = 0; 00325 #endif 00326 }; 00327 00328 /// Interface to retrieve contextual information for an effect plug-in. 00329 /// \sa 00330 /// - \ref iakmonadiceffect_init 00331 class IAkEffectPluginContext : public IAkPluginContextBase 00332 { 00333 protected: 00334 /// Virtual destructor on interface to avoid warnings. 00335 virtual ~IAkEffectPluginContext(){} 00336 00337 public: 00338 00339 /// Determine whether the effect is to be used in Send Mode or not. 00340 /// Effects used in auxiliary busses are always used in Send Mode. 00341 /// \return True if the effect is in Send Mode, False otherwise 00342 virtual bool IsSendModeEffect() const = 0; 00343 00344 /// Obtain the interface to access the voice in which the plugin is inserted. 00345 /// \return The interface to voice info. NULL if the plugin is instantiated on a bus. 00346 virtual IAkVoicePluginInfo * GetVoiceInfo() = 0; 00347 00348 /// Get internal ID of sound structure (sound object or bus) on which the plug-in is instantiated. 00349 /// In the case of a voice, the ID is internal but corresponds to what you would get from the duration 00350 /// callback (see AkDurationCallbackInfo::audioNodeID). In the case of a bus, it can be matched with the bus name converted 00351 /// to a unique ID using AK::SoundEngine::GetIDFromString(). Returns AK_INVALID_UNIQUE_ID in the case of a sink/device. 00352 /// \return ID of structure. 00353 /// \sa 00354 /// - AkDurationCallbackInfo 00355 /// - AK::SoundEngine::PostEvent() 00356 /// - AK::SoundEngine::GetIDFromString() 00357 virtual AkUniqueID GetNodeID() const = 0; 00358 }; 00359 00360 /// Interface to retrieve contextual information for a source plug-in. 00361 /// \sa 00362 /// - \ref iaksourceeffect_init 00363 class IAkSourcePluginContext : public IAkPluginContextBase 00364 { 00365 protected: 00366 /// Virtual destructor on interface to avoid warnings. 00367 virtual ~IAkSourcePluginContext(){} 00368 00369 public: 00370 00371 /// Retrieve the number of loops the source should produce. 00372 /// \return The number of loop iterations the source should produce (0 if infinite looping) 00373 virtual AkUInt16 GetNumLoops() const = 0; 00374 00375 /// Obtain the interface to access the voice in which the plugin is inserted. 00376 /// \return The interface to voice info. 00377 virtual IAkVoicePluginInfo * GetVoiceInfo() = 0; 00378 00379 /// Obtain the MIDI event info associated to the source. 00380 /// \return The MIDI event info. 00381 /// 00382 virtual AkMIDIEvent GetMidiEvent() const = 0; 00383 00384 /// Get internal ID of sound structure (sound object or bus) on which the plug-in is instantiated. 00385 /// In the case of a voice, the ID is internal but corresponds to what you would get from the duration 00386 /// callback (see AkDurationCallbackInfo::audioNodeID). In the case of a bus, it can be matched with the bus name converted 00387 /// to a unique ID using AK::SoundEngine::GetIDFromString(). Returns AK_INVALID_UNIQUE_ID in the case of a sink/device. 00388 /// \return ID of structure. 00389 /// \sa 00390 /// - AkDurationCallbackInfo 00391 /// - AK::SoundEngine::PostEvent() 00392 /// - AK::SoundEngine::GetIDFromString() 00393 virtual AkUniqueID GetNodeID() const = 0; 00394 00395 /// Retrieve Cookie information for a Source Plugin 00396 /// \return the void pointer of the Cookie passed to the PostEvent 00397 virtual void* GetCookie() const = 0; 00398 00399 }; 00400 00401 /// Interface to retrieve contextual information for a mixer. 00402 class IAkMixerPluginContext : public IAkPluginContextBase 00403 { 00404 protected: 00405 /// Virtual destructor on interface to avoid warnings. 00406 virtual ~IAkMixerPluginContext(){} 00407 00408 public: 00409 00410 /// Get ID of bus on which the plugin is inserted. It can be matched with the bus name converted to a unique ID using AK::SoundEngine::GetIDFromString(). 00411 /// \return ID of bus. 00412 /// \sa AK::SoundEngine::GetIDFromString() 00413 virtual AkUniqueID GetBusID() = 0; 00414 00415 /// Get the type of the bus on which the mixer plugin is instantiated. 00416 /// AkBusHierachyFlags is a bit field, indicating whether the bus is the master (top-level) bus or not, 00417 /// and whether it is in the primary or secondary mixing graph. 00418 /// \return The bus type. 00419 virtual AkBusHierarchyFlags GetBusType() = 0; 00420 00421 /// Get speaker angles of the specified device. 00422 /// The speaker angles are expressed as an array of loudspeaker pairs, in degrees, relative to azimuth ]0,180]. 00423 /// Supported loudspeaker setups are always symmetric; the center speaker is always in the middle and thus not specified by angles. 00424 /// Angles must be set in ascending order. 00425 /// You may call this function with io_pfSpeakerAngles set to NULL to get the expected number of angle values in io_uNumAngles, 00426 /// in order to allocate your array correctly. You may also obtain this number by calling 00427 /// AK::GetNumberOfAnglesForConfig( AK_SPEAKER_SETUP_DEFAULT_PLANE ). 00428 /// If io_pfSpeakerAngles is not NULL, the array is filled with up to io_uNumAngles. 00429 /// Typical usage: 00430 /// - AkUInt32 uNumAngles; 00431 /// - GetSpeakerAngles( NULL, uNumAngles ); 00432 /// - AkReal32 * pfSpeakerAngles = AkAlloca( uNumAngles * sizeof(AkReal32) ); 00433 /// - GetSpeakerAngles( pfSpeakerAngles, uNumAngles ); 00434 /// \warning Call this function only after the sound engine has been properly initialized. 00435 /// \return AK_Success if the end point device is properly initialized, AK_Fail otherwise. 00436 /// \sa AK::SoundEngine::GetSpeakerAngles() 00437 virtual AKRESULT GetSpeakerAngles( 00438 AkReal32 * io_pfSpeakerAngles, ///< Returned array of loudspeaker pair angles, in degrees relative to azimuth [0,180]. Pass NULL to get the required size of the array. 00439 AkUInt32 & io_uNumAngles, ///< Returned number of angles in io_pfSpeakerAngles, which is the minimum between the value that you pass in, and the number of angles corresponding to the output configuration, or just the latter if io_pfSpeakerAngles is NULL. 00440 AkReal32 & out_fHeightAngle ///< Elevation of the height layer, in degrees relative to the plane. 00441 ) = 0; 00442 00443 /// \name Services. 00444 //@{ 00445 00446 /// Compute a direct speaker assignment volume matrix with proper downmixing rules between two channel configurations. 00447 virtual AKRESULT ComputeSpeakerVolumesDirect( 00448 AkChannelConfig in_inputConfig, ///< Channel configuration of the input. 00449 AkChannelConfig in_outputConfig, ///< Channel configuration of the mixer output. 00450 AkReal32 in_fCenterPerc, ///< Center percentage. Only applies to mono inputs with standard output configurations that have a center channel. 00451 AK::SpeakerVolumes::MatrixPtr out_mxVolumes ///< Returned volumes matrix. Must be preallocated using AK::SpeakerVolumes::Matrix::GetRequiredSize() (see AK::SpeakerVolumes::Matrix services). 00452 ) = 0; 00453 00454 /// Compute a volume matrix given the position of the panner (Wwise 2D panner). 00455 virtual AKRESULT ComputeSpeakerVolumesPanner( 00456 const AkVector & in_position, ///< x,y,z panner position [-1,1]. Note that z has no effect at the moment. 00457 AkReal32 in_fCenterPct, ///< Center percentage. 00458 AkChannelConfig in_inputConfig, ///< Channel configuration of the input. 00459 AkChannelConfig in_outputConfig, ///< Channel configuration of the mixer output. 00460 AK::SpeakerVolumes::MatrixPtr out_mxVolumes ///< Returned volumes matrix. Must be preallocated using AK::SpeakerVolumes::Matrix::GetRequiredSize() (see AK::SpeakerVolumes::Matrix services). 00461 ) = 0; 00462 00463 /// Compute panning gains on the plane given an incidence angle and channel configuration. 00464 /// \return AK_Success if successful, AK_Fail otherwise. 00465 virtual AKRESULT ComputePlanarVBAPGains( 00466 AkReal32 in_fAngle, ///< Incident angle, in radians [-pi,pi], where 0 is the azimuth (positive values are clockwise) 00467 AkChannelConfig in_outputConfig, ///< Desired output configuration. 00468 AkReal32 in_fCenterPerc, ///< Center percentage. Only applies to mono inputs to outputs that have no center. 00469 AK::SpeakerVolumes::VectorPtr out_vVolumes ///< Returned volumes (see AK::SpeakerVolumes::Vector services). Must be allocated prior to calling this function with the size returned by AK::SpeakerVolumes::Vector::GetRequiredSize() for the desired configuration. 00470 ) = 0; 00471 00472 /// Initialize spherical VBAP 00473 /// \return AK_Success if successful, AK_Fail otherwise. 00474 virtual AKRESULT InitSphericalVBAP( 00475 AK::IAkPluginMemAlloc* in_pAllocator, ///< Memory allocator 00476 const AkSphericalCoord* in_SphericalPositions, ///< Array of points in spherical coordinate, representign the virtual position of each channels. 00477 const AkUInt32 in_NbPoints, ///< Number of points in the position array 00478 void *& out_pPannerData ///< Contains data relevant to the 3D panner that shoud be re-used accross plugin instances. 00479 ) = 0; 00480 00481 /// Compute panning gains on the plane given an incidence angle and channel configuration. 00482 /// \return AK_Success if successful, AK_Fail otherwise. 00483 virtual AKRESULT ComputeSphericalVBAPGains( 00484 void* in_pPannerData, ///< Contains data relevant to the 3D panner that shoud be re-used accross plugin instances. 00485 AkReal32 in_fAzimuth, ///< Incident angle, in radians [-pi,pi], where 0 is the azimuth (positive values are clockwise) 00486 AkReal32 in_fElevation, ///< Incident angle, in radians [0,pi], where 0 is the elevation (positive values are clockwise) 00487 AkUInt32 in_uNumChannels, ///< Number of output channels. 00488 AK::SpeakerVolumes::VectorPtr out_vVolumes ///< Returned volumes (see AK::SpeakerVolumes::Vector services). Must be allocated prior to calling this function with the size returned by AK::SpeakerVolumes::Vector::GetRequiredSize() for the desired configuration. 00489 ) = 0; 00490 00491 /// Clear panner data obtained from InitSphericalVBAP(). 00492 /// \return AK_Success if successful, AK_Fail otherwise. 00493 virtual AKRESULT TermSphericalVBAP( 00494 AK::IAkPluginMemAlloc* in_pAllocator, ///< Memory allocator 00495 void* in_pPannerData ///< Contains data relevant to the 3D panner that shoud be re-used accross plugin instances. 00496 ) = 0; 00497 00498 /// Compute standard 3D positioning. 00499 /// \return AK_Success if successful. 00500 /// \aknote The cartesian counterpart of Compute3DPositioning, that uses emitter and listener transforms, should be used instead of this function. 00501 /// It is more complete and more efficient. \endaknote 00502 virtual AKRESULT Compute3DPositioning( 00503 AkReal32 in_fAngle, ///< Incident angle, in radians [-pi,pi], where 0 is the azimuth (positive values are clockwise). 00504 AkReal32 in_fElevation, ///< Incident elevation angle, in radians [-pi/2,pi/2], where 0 is the horizon (positive values are above the horizon). 00505 AkReal32 in_fSpread, ///< Spread ([0,100]). 00506 AkReal32 in_fFocus, ///< Focus ([0,100]). 00507 AkChannelConfig in_inputConfig, ///< Channel configuration of the input. 00508 AkChannelMask in_uInputChanSel, ///< Mask of input channels selected for panning (excluded input channels don't contribute to the output). 00509 AkChannelConfig in_outputConfig, ///< Desired output configuration. 00510 AkReal32 in_fCenterPerc, ///< Center percentage. Only applies to mono inputs to outputs that have a center. 00511 AK::SpeakerVolumes::MatrixPtr out_mxVolumes ///< Returned volumes matrix. Must be preallocated using AK::SpeakerVolumes::Matrix::GetRequiredSize() (see AK::SpeakerVolumes::Matrix services). 00512 ) = 0; 00513 00514 /// Compute standard 3D positioning. 00515 /// \return AK_Success if successful. 00516 /// \aknote This function is more complete and more efficient than the Compute3DPositioning service that uses spherical coordinates, and should be favored.\endaknote 00517 virtual AKRESULT Compute3DPositioning( 00518 const AkTransform & in_emitter, ///< Emitter transform. 00519 const AkTransform & in_listener, ///< Listener transform. 00520 AkReal32 in_fCenterPerc, ///< Center percentage. Only applies to mono inputs to outputs that have a center. 00521 AkReal32 in_fSpread, ///< Spread. 00522 AkReal32 in_fFocus, ///< Focus. 00523 AkChannelConfig in_inputConfig, ///< Channel configuration of the input. 00524 AkChannelMask in_uInputChanSel, ///< Mask of input channels selected for panning (excluded input channels don't contribute to the output). 00525 AkChannelConfig in_outputConfig, ///< Desired output configuration. 00526 AK::SpeakerVolumes::MatrixPtr out_mxVolumes ///< Returned volumes matrix. Must be preallocated using AK::SpeakerVolumes::Matrix::GetRequiredSize() (see AK::SpeakerVolumes::Matrix services). 00527 ) = 0; 00528 00529 //@} 00530 00531 /// \name Metering. 00532 //@{ 00533 00534 /// Set flags for controlling computation of metering values on the mix buffer. 00535 /// Pass AK_NoMetering to disable metering. 00536 /// \sa 00537 /// - AK::IAkMetering 00538 virtual void EnableMetering( AkMeteringFlags in_eFlags ) = 0; 00539 00540 //@} 00541 }; 00542 00543 /// Parameter node interface, managing access to an enclosed parameter structure. 00544 /// \aknote The implementer of this interface should also expose a static creation function 00545 /// that will return a new parameter node instance when required (see \ref se_plugins_overview). \endaknote 00546 /// \sa 00547 /// - \ref shared_parameter_interface 00548 class IAkPluginParam : public IAkRTPCSubscriber 00549 { 00550 protected: 00551 /// Virtual destructor on interface to avoid warnings. 00552 virtual ~IAkPluginParam(){} 00553 00554 public: 00555 /// Create a duplicate of the parameter node instance in its current state. 00556 /// \aknote The allocation of the new parameter node should be done through the AK_PLUGIN_NEW() macro. \endaknote 00557 /// \return Pointer to a duplicated plug-in parameter node interface 00558 /// \sa 00559 /// - \ref iakeffectparam_clone 00560 virtual IAkPluginParam * Clone( 00561 IAkPluginMemAlloc * in_pAllocator ///< Interface to memory allocator to be used 00562 ) = 0; 00563 00564 /// Initialize the plug-in parameter node interface. 00565 /// Initializes the internal parameter structure to default values or with the provided parameter 00566 /// block if it is valid. \endaknote 00567 /// \aknote If the provided parameter block is valid, use SetParamsBlock() to set all parameters at once. \endaknote 00568 /// \return Possible return values are: AK_Success, AK_Fail, AK_InvalidParameter 00569 /// \sa 00570 /// - \ref iakeffectparam_init 00571 virtual AKRESULT Init( 00572 IAkPluginMemAlloc * in_pAllocator, ///< Interface to the memory allocator to be used 00573 const void * in_pParamsBlock, ///< Pointer to a parameter structure block 00574 AkUInt32 in_uBlockSize ///< Size of the parameter structure block 00575 ) = 0; 00576 00577 /// Called by the sound engine when a parameter node is terminated. 00578 /// \aknote The self-destruction of the parameter node must be done using the AK_PLUGIN_DELETE() macro. \endaknote 00579 /// \return AK_Success if successful, AK_Fail otherwise 00580 /// \sa 00581 /// - \ref iakeffectparam_term 00582 virtual AKRESULT Term( 00583 IAkPluginMemAlloc * in_pAllocator ///< Interface to memory allocator to be used 00584 ) = 0; 00585 00586 /// Set all plug-in parameters at once using a parameter block. 00587 /// \return AK_Success if successful, AK_InvalidParameter otherwise 00588 /// \sa 00589 /// - \ref iakeffectparam_setparamsblock 00590 virtual AKRESULT SetParamsBlock( 00591 const void *in_pParamsBlock, ///< Pointer to a parameter structure block 00592 AkUInt32 in_uBlockSize ///< Size of the parameter structure block 00593 ) = 0; 00594 00595 /// Update a single parameter at a time and perform the necessary actions on the parameter changes. 00596 /// \aknote The parameter ID corresponds to the AudioEnginePropertyID in the plug-in XML description file. \endaknote 00597 /// \return AK_Success if successful, AK_InvalidParameter otherwise 00598 /// \sa 00599 /// - \ref iakeffectparam_setparam 00600 virtual AKRESULT SetParam( 00601 AkPluginParamID in_paramID, ///< ID number of the parameter to set 00602 const void * in_pValue, ///< Pointer to the value of the parameter to set 00603 AkUInt32 in_uParamSize ///< Size of the value of the parameter to set 00604 ) = 0; 00605 00606 /// Use this constant with AK::Wwise::IPluginPropertySet::NotifyInternalDataChanged, 00607 /// AK::Wwise::IAudioPlugin::GetPluginData and IAkPluginParam::SetParam. This tells 00608 /// that the whole plugin data needs to be saved/transferred. 00609 ///\sa 00610 /// - AK::Wwise::IPluginPropertySet::NotifyInternalDataChanged 00611 /// - AK::Wwise::IAudioPlugin::GetPluginData 00612 /// - AK::IAkPluginParam::SetParam 00613 static const AkPluginParamID ALL_PLUGIN_DATA_ID = 0x7FFF; 00614 }; 00615 00616 /// Wwise sound engine plug-in interface. Shared functionality across different plug-in types. 00617 /// \aknote The implementer of this interface should also expose a static creation function 00618 /// that will return a new plug-in instance when required (see \ref soundengine_plugins). \endaknote 00619 class IAkPlugin 00620 { 00621 protected: 00622 /// Virtual destructor on interface to avoid warnings. 00623 virtual ~IAkPlugin(){} 00624 00625 public: 00626 /// Release the resources upon termination of the plug-in. 00627 /// \return AK_Success if successful, AK_Fail otherwise 00628 /// \aknote The self-destruction of the plug-in must be done using AK_PLUGIN_DELETE() macro. \endaknote 00629 /// \sa 00630 /// - \ref iakeffect_term 00631 virtual AKRESULT Term( 00632 IAkPluginMemAlloc * in_pAllocator ///< Interface to memory allocator to be used by the plug-in 00633 ) = 0; 00634 00635 /// The reset action should perform any actions required to reinitialize the state of the plug-in 00636 /// to its original state (e.g. after Init() or on effect bypass). 00637 /// \return AK_Success if successful, AK_Fail otherwise. 00638 /// \sa 00639 /// - \ref iakeffect_reset 00640 virtual AKRESULT Reset() = 0; 00641 00642 /// Plug-in information query mechanism used when the sound engine requires information 00643 /// about the plug-in to determine its behavior 00644 /// \return AK_Success if successful. 00645 /// \sa 00646 /// - \ref iakeffect_geteffectinfo 00647 virtual AKRESULT GetPluginInfo( 00648 AkPluginInfo & out_rPluginInfo ///< Reference to the plug-in information structure to be retrieved 00649 ) = 0; 00650 00651 /// Some plug-ins are accessing Media from the Wwise sound bank system. 00652 /// If the IAkPlugin object is not using media, this function will not be used and should simply return false. 00653 /// If the IAkPlugin object is using media, the RelocateMedia feature can be optionally implemented. 00654 /// To implement correctly the feature, the plugin must be able to "Hot swap" from a memory location to another one in a single blocking call (AK::IAkPlugin::RelocateMedia) 00655 /// 00656 /// \sa 00657 /// - AK::IAkPlugin::RelocateMedia 00658 virtual bool SupportMediaRelocation() const 00659 { 00660 return false; 00661 } 00662 00663 /// Some plug-ins are accessing Media from the Wwise sound bank system. 00664 /// If the IAkPlugin object is not using media, this function will not be used. 00665 /// If the IAkPlugin object is using media, the RelocateMedia feature can be optionally implemented. 00666 /// When this function is being called, the IAkPlugin object must make the required changes to remove all 00667 /// referenced from the old memory pointer (previously obtained by GetPluginMedia() (and offsets to) to not access anymore the content of the old memory data and start using the newly provided pointer instead. 00668 /// The change must be done within the function RelocateMedia(). 00669 /// After this call, the memory space in in_pOldInMemoryData will be invalidated and cannot be used safely anymore. 00670 /// 00671 /// This function will not be called if SupportMediaRelocation returned false. 00672 /// 00673 /// \sa 00674 /// - AK::IAkPlugin::SupportMediaRelocation 00675 virtual AKRESULT RelocateMedia( 00676 AkUInt8* /*in_pNewMedia*/, 00677 AkUInt8* /*in_pOldMedia*/ 00678 ) 00679 { 00680 return AK_NotImplemented; 00681 } 00682 00683 }; 00684 00685 /// Software effect plug-in interface (see \ref soundengine_plugins_effects). 00686 class IAkEffectPlugin : public IAkPlugin 00687 { 00688 protected: 00689 /// Virtual destructor on interface to avoid warnings. 00690 virtual ~IAkEffectPlugin(){} 00691 00692 public: 00693 /// Software effect plug-in initialization. Prepares the effect for data processing, allocates memory and sets up the initial conditions. 00694 /// \aknote Memory allocation should be done through appropriate macros (see \ref fx_memory_alloc). \endaknote 00695 /// \sa 00696 /// - \ref iakmonadiceffect_init 00697 virtual AKRESULT Init( 00698 IAkPluginMemAlloc * in_pAllocator, ///< Interface to memory allocator to be used by the effect 00699 IAkEffectPluginContext * in_pEffectPluginContext, ///< Interface to effect plug-in's context 00700 IAkPluginParam * in_pParams, ///< Interface to plug-in parameters 00701 AkAudioFormat & io_rFormat ///< Audio data format of the input/output signal. Only an out-of-place plugin is allowed to change the channel configuration. 00702 ) = 0; 00703 00704 #ifdef AK_VITA_HW 00705 virtual const SceNgsVoiceDefinition * GetVoiceDefinition(){ AKASSERT( false && "Non hardware plugin called on Vita HW" ); return NULL; } 00706 virtual AKRESULT AttachVoice( SceNgsHVoice in_hVoice){ AKASSERT( false && "Non hardware plugin called on Vita HW" ); return AK_Fail; } 00707 virtual AkReal32 GetTailTime() const { AKASSERT( false && "Non hardware plugin called on Vita HW" ); return 0; } 00708 virtual AKRESULT SetBypass( SceUInt32 in_uBypassFlag ) { AKASSERT( false && "Non hardware plugin called on Vita HW" ); return AK_Fail; } 00709 #endif 00710 }; 00711 00712 /// Software effect plug-in interface for in-place processing (see \ref soundengine_plugins_effects). 00713 class IAkInPlaceEffectPlugin : public IAkEffectPlugin 00714 { 00715 public: 00716 /// Software effect plug-in DSP execution for in-place processing. 00717 /// \aknote The effect should process all the input data (uValidFrames) as long as AK_DataReady is passed in the eState field. 00718 /// When the input is finished (AK_NoMoreData), the effect can output more sample than uValidFrames up to MaxFrames() if desired. 00719 /// All sample frames beyond uValidFrames are not initialized and it is the responsibility of the effect to do so when outputting an effect tail. 00720 /// The effect must notify the pipeline by updating uValidFrames if more frames are produced during the effect tail. 00721 /// \aknote The effect will stop being called by the pipeline when AK_NoMoreData is returned in the the eState field of the AkAudioBuffer structure. 00722 /// See \ref iakmonadiceffect_execute_general. 00723 virtual void Execute( 00724 AkAudioBuffer * io_pBuffer ///< In/Out audio buffer data structure (in-place processing) 00725 ) = 0; 00726 00727 /// Skips execution of some frames, when the voice is virtual playing from elapsed time. 00728 /// This can be used to simulate processing that would have taken place (e.g. update internal state). 00729 /// Return AK_DataReady or AK_NoMoreData, depending if there would be audio output or not at that point. 00730 virtual AKRESULT TimeSkip( 00731 AkUInt32 in_uFrames ///< Number of frames the audio processing should advance. 00732 ) = 0; 00733 }; 00734 00735 00736 /// Software effect plug-in interface for out-of-place processing (see \ref soundengine_plugins_effects). 00737 class IAkOutOfPlaceEffectPlugin : public IAkEffectPlugin 00738 { 00739 public: 00740 /// Software effect plug-in for out-of-place processing. 00741 /// \aknote An input buffer is provided and will be passed back to Execute() (with an advancing offset based on uValidFrames consumption by the plug-in). 00742 /// The output buffer should be filled entirely by the effect (at which point it can report AK_DataReady) except on last execution where AK_NoMoreData should be used. 00743 /// AK_DataNeeded should be used when more input data is necessary to continue processing. 00744 /// \aknote Only the output buffer eState field is looked at by the pipeline to determine the effect state. 00745 /// See \ref iakmonadiceffect_execute_outofplace. 00746 virtual void Execute( 00747 AkAudioBuffer * in_pBuffer, ///< Input audio buffer data structure 00748 AkUInt32 in_uInOffset, ///< Offset position into input buffer data 00749 AkAudioBuffer * out_pBuffer ///< Output audio buffer data structure 00750 ) = 0; 00751 00752 /// Skips execution of some frames, when the voice is virtual playing from elapsed time. 00753 /// This can be used to simulate processing that would have taken place (e.g. update internal state). 00754 /// Return AK_DataReady or AK_NoMoreData, depending if there would be audio output or not at that point. 00755 virtual AKRESULT TimeSkip( 00756 AkUInt32 &io_uFrames ///< Number of frames the audio processing should advance. The output value should be the number of frames that would be consumed to output the number of frames this parameter has at the input of the function. 00757 ) = 0; 00758 }; 00759 00760 /// Interface to retrieve information about an input of a mixer. 00761 class IAkMixerInputContext 00762 { 00763 protected: 00764 /// Virtual destructor on interface to avoid warnings. 00765 virtual ~IAkMixerInputContext(){} 00766 00767 public: 00768 00769 /// Obtain the parameter blob for the mixer plugin that were attached to this input. 00770 /// \return The parameter blob, which can be safely cast into the plugin's implementation. 00771 /// If all parameters are default value, NULL is returned. It is up to the plugin's implementation to know 00772 /// what the default values are. 00773 virtual IAkPluginParam * GetInputParam() = 0; 00774 00775 /// Obtain the interface to access the voice info of this input. 00776 /// \return The interface to voice info. NULL when the input is not a voice but the output of another bus instead. 00777 virtual IAkVoicePluginInfo * GetVoiceInfo() = 0; 00778 00779 /// Query the nature of the connection between this input and the mixer. 00780 /// \return The connection type (direct/dry, user-defined auxiliary send, game-defined auxiliary send). Bus inputs are always "direct". 00781 virtual AkConnectionType GetConnectionType() = 0; 00782 00783 /// Get internal ID of sound associated to this input. 00784 /// In the case of a voice, the ID is internal but corresponds to what you would get from the duration 00785 /// callback (see AkDurationCallbackInfo::audioNodeID). In the case of a bus, it can be matched with the bus name converted 00786 /// to a unique ID using AK::SoundEngine::GetIDFromString(). 00787 /// \return ID of input. 00788 /// \sa 00789 /// - AkDurationCallbackInfo 00790 /// - AK::SoundEngine::PostEvent() 00791 /// - AK::SoundEngine::GetIDFromString() 00792 virtual AkUniqueID GetAudioNodeID() = 0; 00793 00794 /// Use this method to retrieve user data to this context. It is always initialized to NULL until you decide to set it otherwise. 00795 /// \return Attached user data. 00796 /// \sa SetUserData() 00797 virtual void * GetUserData() = 0; 00798 00799 /// Use this method to attach user data to this context. It is always initialized to NULL until you decide to set it otherwise. 00800 /// \return Attached user data. 00801 /// \sa GetUserData() 00802 virtual void SetUserData( void * in_pUserData ) = 0; 00803 00804 /// \name Default positioning information. 00805 /// \warning The methods of this group are deprecated. 00806 //@{ 00807 00808 /// Query whether the object corresponding to this input is spatialized or is instead assigned 00809 /// directly to output channels. When the object's panner type is "2D", IsSpatializationEnabled returns true if the panner is enabled. 00810 /// When the object's panner type is "3D", IsSpatializationEnabled returns true if option "Enable Spatialization" is ticked. 00811 /// \return True if spatialization is enabled, false otherwise. 00812 /// \sa GetPannerType() 00813 virtual bool IsSpatializationEnabled() = 0; 00814 00815 /// Retrieve center percentage of this input. 00816 /// Note that the returned value is always 1 unless positioning is enabled. 00817 /// \return Center percentage, between 0 and 1. 00818 /// \sa 00819 /// - IsSpatializationEnabled() 00820 virtual AkReal32 GetCenterPerc() = 0; 00821 00822 /// Retrieve the panner type of this input ("2D" versus "3D"). 00823 /// Note that the returned value is only relevant if positioning is enabled. 00824 /// \sa 00825 /// - IsSpatializationEnabled() 00826 virtual AkPannerType GetPannerType() = 0; 00827 00828 /// Get whether positioning is driven by the game (when positioning type is 3D game defined) or by the 00829 /// user through the use of an automatable panner (such as 2D or 3D user defined). 00830 /// \sa 00831 /// - GetPannerType() 00832 virtual AkPositionSourceType GetPositionSourceType() = 0; 00833 00834 /// Default 2D positioning: 00835 /// Retrieve the 2D panner position (each vector component is between -1 and 1) of this input. 00836 /// Note that the returned value is only relevant if positioning is enabled, and panner type is "2D". 00837 /// \sa 00838 /// - IsSpatializationEnabled() 00839 /// - GetPannerType() 00840 virtual void GetPannerPosition( 00841 AkVector & out_position ///< Returned sound position. 00842 ) = 0; 00843 00844 /// Default 3D positioning: 00845 /// Retrieve the number of emitter-listener pairs (rays) of this input. 00846 /// Note that the returned value is always 0 unless the input is in 3D panner mode. 00847 virtual AkUInt32 GetNum3DPositions() = 0; 00848 00849 /// Default 3D positioning: 00850 /// Retrieve the spherical coordinates of the desired emitter-listener pair (ray) corresponding to this 00851 /// input, as automated by the engine. When in 3D game-defined positioning mode, the returned position 00852 /// corresponds to the game object position (also obtainable via the AK::IAkGameObjectPluginInfo interface). 00853 /// In 3D user-defined positioning mode, returned rays are those that result from engine automation. 00854 /// \return AK_Success if the pair index is valid, AK_Fail otherwise. 00855 /// \sa 00856 /// - GetNum3DPositions() 00857 virtual AKRESULT Get3DPosition( 00858 AkUInt32 in_uIndex, ///< Index of the pair, [0, GetNum3DPositions()[ 00859 AkEmitterListenerPair & out_soundPosition ///< Returned sound position, in spherical coordinates. 00860 ) = 0; 00861 00862 /// Default 3D positioning: 00863 /// Evaluate spread value at the distance of the desired emitter-listener pair for this input. 00864 /// \return The spread value, between 0 and 100. 0 if the pair index is invalid. 00865 /// \sa 00866 /// - GetNum3DPositions() 00867 /// - Get3DPosition() 00868 virtual AkReal32 GetSpread( 00869 AkUInt32 in_uIndex ///< Index of the pair, [0, GetNum3DPositions()[ 00870 ) = 0; 00871 00872 /// Default 3D positioning: 00873 /// Evaluate focus value at the distance of the desired emitter-listener pair for this input. 00874 /// \return The focus value, between 0 and 100. 0 if the pair index is invalid. 00875 /// \sa 00876 /// - GetNum3DPositions() 00877 /// - Get3DPosition() 00878 virtual AkReal32 GetFocus( 00879 AkUInt32 in_uIndex ///< Index of the pair, [0, GetNum3DPositions()[ 00880 ) = 0; 00881 00882 /// Get the max distance as defined in the attenuation editor. 00883 /// \return True if this input has attenuation, false otherwise. 00884 virtual bool GetMaxAttenuationDistance( 00885 AkReal32 & out_fMaxAttenuationDistance ///< Returned max distance. 00886 ) = 0; 00887 00888 /// Get next volumes as computed by the sound engine for this input. 00889 virtual void GetSpatializedVolumes( 00890 AK::SpeakerVolumes::MatrixPtr out_mxPrevVolumes, ///< Returned in/out channel volume distribution corresponding to the beginning of the buffer. Must be preallocated (see AK::SpeakerVolumes::Matrix services). 00891 AK::SpeakerVolumes::MatrixPtr out_mxNextVolumes ///< Returned in/out channel volume distribution corresponding to the end of the buffer. Must be preallocated (see AK::SpeakerVolumes::Matrix services). 00892 ) = 0; 00893 00894 //@} 00895 }; 00896 00897 /// Interface to retrieve contextual information for a sink plugin. 00898 /// \sa 00899 /// - AK::IAkSinkPlugin 00900 class IAkSinkPluginContext : public IAkPluginContextBase 00901 { 00902 protected: 00903 /// Virtual destructor on interface to avoid warnings. 00904 virtual ~IAkSinkPluginContext(){} 00905 00906 public: 00907 00908 /// Query if the sink plugin is instantiated on the main output device (primary tree). 00909 /// \return True if the sink plugin is instantiated on the main output device (primary tree), false otherwise. 00910 /// \sa 00911 /// - AK::IAkSinkPlugin::IsDataNeeded() 00912 /// - AK::IAkSinkPlugin::Consume() 00913 virtual bool IsPrimary() = 0; 00914 00915 /// Sink plugins may need to call this function to notify the audio thread that it should wake up 00916 /// in order to potentially process an audio frame. Note that the audio thread may wake up for other 00917 /// reasons, for example following calls to AK::SoundEngine::RenderAudio(). 00918 /// Once the audio thread is awaken, it will ask the sink plugin how many audio frames need to be 00919 /// processed and presented to the plugin. This is done through AK::IAkSinkPlugin::IsDataNeeded() 00920 /// and AK::IAkSinkPlugin::Consume() respectively. 00921 /// Note that only the sink plugin that is instantiated on the main output device (primary tree) may control 00922 /// the audio thread synchronization. 00923 /// \return AK_Success if the calling plugin is instantiated on the main output device (primary tree), 00924 /// AK_Fail otherwise. 00925 /// \sa 00926 /// - AK::IAkSinkPluginContext::IsPrimary() 00927 /// - AK::IAkSinkPlugin::IsDataNeeded() 00928 /// - AK::IAkSinkPlugin::Consume() 00929 virtual AKRESULT SignalAudioThread() = 0; 00930 00931 /// Query engine's user-defined sink queue depth (AkPlatformInitSettings::uNumRefillsInVoice). 00932 /// \return The engine's AkPlatformInitSettings::uNumRefillsInVoice value on platforms for which it exists, 0 otherwise. 00933 virtual AkUInt16 GetNumRefillsInVoice() = 0; 00934 }; 00935 00936 /// Software effect plug-in interface for sink (audio end point) plugins. 00937 class IAkSinkPlugin : public IAkPlugin 00938 { 00939 protected: 00940 /// Virtual destructor on interface to avoid warnings. 00941 virtual ~IAkSinkPlugin(){} 00942 00943 public: 00944 00945 /// Initialization of the sink plugin. 00946 /// 00947 /// This method prepares the audio device plug-in for data processing, allocates memory, and sets up initial conditions. 00948 /// The plug-in is passed in a pointer to a memory allocator interface (AK::IAkPluginMemAlloc).You should perform all dynamic memory allocation through this interface using the provided memory allocation macros(refer to \ref fx_memory_alloc).For the most common memory allocation needs, namely allocation at initialization and release at termination, the plug-in does not need to retain a pointer to the allocator.It will also be provided to the plug-in on termination. 00949 /// The AK::IAkSinkPluginContext interface allows to retrieve information related to the context in which the audio device plug-in is operated. 00950 /// The plug-in also receives a pointer to its associated parameter node interface (AK::IAkPluginParam).Most plug-ins will want to keep a reference to the associated parameter node to be able to retrieve parameters at runtime. Refer to \ref iakeffectparam_communication for more details. 00951 /// All of these interfaces will remain valid throughout the plug-in's lifespan so it is safe to keep an internal reference to them when necessary. 00952 /// Plug-ins also receive the output audio format(which stays the same during the lifespan of the plug-in) to be able to allocate memory and setup processing for a given channel configuration. 00953 /// Note that the channel configuration is suggestive and may even be specified as !AkChannelConfig::IsValid().The plugin is free to determine the true channel configuration(this is an io parameter). 00954 /// 00955 /// \return AK_Success if successful. 00956 /// \return AK_NotCompatible if the system doesn't support this sink type. Return this if you want to fall back to the default sinks. This sink will never be requested again. Do not return this code if the device is simply unplugged. 00957 /// All other return codes will be treated as temporary failures conditions and the sink will be requested again later. 00958 00959 virtual AKRESULT Init( 00960 IAkPluginMemAlloc * in_pAllocator, ///< Interface to memory allocator to be used by the effect. 00961 IAkSinkPluginContext * in_pSinkPluginContext, ///< Interface to sink plug-in's context. 00962 IAkPluginParam * in_pParams, ///< Interface to plug-in parameters. 00963 AkAudioFormat & io_rFormat ///< Audio data format of the input signal. Note that the channel configuration is suggestive and may even be specified as !AkChannelConfig::IsValid(). The plugin is free to determine the true channel configuration. 00964 ) = 0; 00965 00966 /// Obtain the number of audio frames that should be processed by the sound engine and presented 00967 /// to this plugin via AK::IAkSinkPlugin::Consume(). The size of a frame is determined by the sound engine and 00968 /// obtainable via AK::IAkPluginContextBase::GetMaxBufferLength(). 00969 /// \return AK_Success if successful, AK_Fail if there was a critical error. 00970 /// \sa 00971 /// - AK::IAkSinkPlugin::Consume() 00972 /// - AK::IAkSinkPluginContext::SignalAudioThread() 00973 virtual AKRESULT IsDataNeeded( 00974 AkUInt32 & out_uNumFramesNeeded ///< Returned number of audio frames needed. 00975 ) = 0; 00976 00977 /// Present an audio buffer to the sink. The audio buffer is in the native format of the sound engine 00978 /// (typically float, deinterleaved), as specified by io_rFormat passed to Init(). It is up to the 00979 /// plugin to transform it into a format that is compatible with its output. 00980 /// Note that Consume() is not called if the output for this frame consists of silence. Plugins should 00981 /// detect this in OnFrameEnd(). 00982 /// \sa 00983 /// - AK::IAkSinkPlugin::IsDataNeeded() 00984 /// - AK::IAkSinkPlugin::OnFrameEnd() 00985 virtual void Consume( 00986 AkAudioBuffer * in_pInputBuffer, ///< Input audio buffer data structure. Plugins should avoid processing data in-place. 00987 AkRamp in_gain ///< Volume gain to apply to this input (prev corresponds to the beginning, next corresponds to the end of the buffer). 00988 ) = 0; 00989 00990 /// Called at the end of the audio frame. Plugins do whatever bookkeeping needed. 00991 /// \sa 00992 /// - AK::IAkSinkPlugin::Consume() 00993 virtual void OnFrameEnd() = 0; 00994 00995 /// Ask the plugin whether starvation occurred. 00996 /// \return True if starvation occurred, false otherwise. 00997 virtual bool IsStarved() = 0; 00998 00999 /// Reset the "starvation" flag after IsStarved() returned true. 01000 virtual void ResetStarved() = 0; 01001 }; 01002 01003 /// Wwise sound engine source plug-in interface (see \ref soundengine_plugins_source). 01004 class IAkSourcePlugin : public IAkPlugin 01005 { 01006 protected: 01007 /// Virtual destructor on interface to avoid warnings. 01008 virtual ~IAkSourcePlugin(){} 01009 01010 public: 01011 /// Source plug-in initialization. Gets the plug-in ready for data processing, allocates memory and sets up the initial conditions. 01012 /// \aknote Memory allocation should be done through the appropriate macros (see \ref fx_memory_alloc). \endaknote 01013 /// \sa 01014 /// - \ref iaksourceeffect_init 01015 virtual AKRESULT Init( 01016 IAkPluginMemAlloc * in_pAllocator, ///< Interface to the memory allocator to be used by the plug-in 01017 IAkSourcePluginContext * in_pSourcePluginContext, ///< Interface to the source plug-in's context 01018 IAkPluginParam * in_pParams, ///< Interface to the plug-in parameters 01019 AkAudioFormat & io_rFormat ///< Audio format of the output data to be produced by the plug-in (mono native by default) 01020 ) = 0; 01021 01022 /// This method is called to determine the approximate duration of the source. 01023 /// \return The duration of the source, in milliseconds. 01024 /// \sa 01025 /// - \ref iaksourceeffect_getduration 01026 virtual AkReal32 GetDuration() const = 0; 01027 01028 /// This method is called to determine the estimated envelope of the source. 01029 /// \return The estimated envelope of the data that will be generated in the next call to 01030 /// Execute(). The envelope value should be normalized to the highest peak of the entire 01031 /// duration of the source. Expected range is [0,1]. If envelope and peak value cannot be 01032 /// predicted, the source should return 1 (no envelope). 01033 /// \sa 01034 /// - \ref iaksourceeffect_getenvelope 01035 virtual AkReal32 GetEnvelope() const 01036 { 01037 return 1.f; 01038 } 01039 01040 /// This method is called to tell the source to stop looping. 01041 /// This will typically be called when an action of type "break" will be triggered on the playing source. 01042 /// Break (or StopLooping) means: terminate gracefully... if possible. In most situations it finishes the current loop and plays the sound release if there is one. 01043 /// 01044 /// \return 01045 /// - AK_Success if the source ignores the break command and plays normally till the end or if the source support to stop looping and terminates gracefully. 01046 /// - AK_Fail if the source cannot simply stop looping, in this situation, the break command will end up stopping this source. 01047 /// \sa 01048 /// - \ref iaksourceeffect_stoplooping 01049 virtual AKRESULT StopLooping(){ return AK_Success; } 01050 01051 /// This method is called to tell the source to seek to an arbitrary sample. 01052 /// This will typically be called when the game calls AK::SoundEngine::SeekOnEvent() where the event plays 01053 /// a sound that wraps this source plug-in. 01054 /// If the plug-in does not handle seeks, it should return AK_Success. If it returns AK_Fail, it will 01055 /// be terminated by the sound engine. 01056 /// 01057 /// \return 01058 /// - AK_Success if the source handles or ignores seek command. 01059 /// - AK_Fail if the source considers that seeking requests should provoke termination, for example, if 01060 /// the desired position is greater than the prescribed source duration. 01061 /// \sa 01062 /// - AK::SoundEngine::SeekOnEvent() 01063 virtual AKRESULT Seek( 01064 AkUInt32 /* in_uPosition */ ///< Position to seek to, in samples, at the rate specified in AkAudioFormat (see AK::IAkSourcePlugin::Init()). 01065 ) { return AK_Success; } 01066 01067 /// Skips execution when the voice is virtual playing from elapsed time to simulate processing that would have taken place (e.g. update internal state) while 01068 /// avoiding most of the CPU hit of plug-in execution. 01069 /// Given the number of frames requested adjust the number of frames that would have been produced by a call to Execute() in the io_uFrames parameter and return and 01070 /// return AK_DataReady or AK_NoMoreData, depending if there would be audio output or not at that point. 01071 /// Returning AK_NotImplemented will trigger a normal execution of the voice (as if it was not virtual) thus not enabling the CPU savings of a proper from elapsed time behavior. 01072 /// Note that returning AK_NotImplemeted for a source plug-ins that support asynchronous processing will produce a 'resume' virtual voice behavior instead. 01073 virtual AKRESULT TimeSkip( 01074 AkUInt32 & /*io_uFrames */ ///< (Input) Number of frames that the audio buffer processing can advance (equivalent to MaxFrames()). The output value should be the number of frames that would be produced this execution. 01075 ) { return AK_NotImplemented; } 01076 01077 /// Software effect plug-in DSP execution. 01078 /// \aknote The effect can output as much as wanted up to MaxFrames(). All sample frames passed uValidFrames at input time are 01079 /// not initialized and it is the responsibility of the effect to do so. When modifying the number of valid frames within execution 01080 /// (e.g. to flush delay lines) the effect should notify the pipeline by updating uValidFrames accordingly. 01081 /// \aknote The effect will stop being called by the pipeline when AK_NoMoreData is returned in the the eState field of the AkAudioBuffer structure. 01082 virtual void Execute( 01083 AkAudioBuffer * io_pBuffer ///< In/Out audio buffer data structure (in-place processing) 01084 ) = 0; 01085 }; 01086 01087 01088 /// This function can be useful to convert from normalized floating point audio samples to HW-pipeline format samples. 01089 #define AK_FLOAT_TO_SAMPLETYPE( __in__ ) (__in__) 01090 /// This function can be useful to convert from normalized floating point audio samples to HW-pipeline format samples when the input is not not to exceed (-1,1) range. 01091 #define AK_FLOAT_TO_SAMPLETYPE_NOCLIP( __in__ ) (__in__) 01092 /// This function can be useful to convert from HW-pipeline format samples to normalized floating point audio samples. 01093 #define AK_SAMPLETYPE_TO_FLOAT( __in__ ) (__in__) 01094 01095 #define AK_DBTOLIN( __db__ ) (powf(10.f,(__db__) * 0.05f)) 01096 } 01097 01098 /// Registered plugin creation function prototype. 01099 AK_CALLBACK( AK::IAkPlugin*, AkCreatePluginCallback )( AK::IAkPluginMemAlloc * in_pAllocator ); 01100 /// Registered plugin parameter node creation function prototype. 01101 AK_CALLBACK( AK::IAkPluginParam*, AkCreateParamCallback )( AK::IAkPluginMemAlloc * in_pAllocator ); 01102 01103 namespace AK 01104 { 01105 /// Global plugin context used for plugin registration/initialization. Games query this interface from the sound engine. 01106 class IAkGlobalPluginContext 01107 { 01108 protected: 01109 /// Virtual destructor on interface to avoid warnings. 01110 virtual ~IAkGlobalPluginContext(){} 01111 01112 public: 01113 01114 /// Retrieve the streaming manager access interface. 01115 virtual IAkStreamMgr * GetStreamMgr() const = 0; 01116 01117 /// Retrieve the maximum number of frames that Execute() will be called with for this effect. 01118 /// Can be used by the effect to make memory allocation at initialization based on this worst case scenario. 01119 /// \return Maximum number of frames. 01120 virtual AkUInt16 GetMaxBufferLength() const = 0; 01121 01122 /// Query whether sound engine is in real-time or offline (faster than real-time) mode. 01123 /// \return true when sound engine is in offline mode, false otherwise. 01124 virtual bool IsRenderingOffline() const = 0; 01125 01126 /// Retrieve the core sample rate of the engine. This sample rate applies to all effects except source plugins, which declare their own sample rate. 01127 /// \return Core sample rate. 01128 virtual AkUInt32 GetSampleRate() const = 0; 01129 01130 /// Post a monitoring message or error string. This will be displayed in the Wwise capture 01131 /// log. 01132 /// \return AK_Success if successful, AK_Fail if there was a problem posting the message. 01133 /// In optimized mode, this function returns AK_NotCompatible. 01134 /// \remark This function is provided as a tracking tool only. It does nothing if it is 01135 /// called in the optimized/release configuration and return AK_NotCompatible. 01136 virtual AKRESULT PostMonitorMessage( 01137 const char* in_pszError, ///< Message or error string to be displayed 01138 AK::Monitor::ErrorLevel in_eErrorLevel ///< Specifies whether it should be displayed as a message or an error 01139 ) = 0; 01140 01141 /// Register a plug-in with the sound engine and set the callback functions to create the 01142 /// plug-in and its parameter node. 01143 /// \sa 01144 /// - \ref register_effects 01145 /// - \ref plugin_xml 01146 /// \return AK_Success if successful, AK_InvalidParameter if invalid parameters were provided or Ak_Fail otherwise. Possible reasons for an AK_Fail result are: 01147 /// - Insufficient memory to register the plug-in 01148 /// - Plug-in ID already registered 01149 /// \remarks 01150 /// Codecs and plug-ins must be registered before loading banks that use them.\n 01151 /// Loading a bank referencing an unregistered plug-in or codec will result in a load bank success, 01152 /// but the plug-ins will not be used. More specifically, playing a sound that uses an unregistered effect plug-in 01153 /// will result in audio playback without applying the said effect. If an unregistered source plug-in is used by an event's audio objects, 01154 /// posting the event will fail. 01155 virtual AKRESULT RegisterPlugin( 01156 AkPluginType in_eType, ///< Plug-in type (for example, source or effect) 01157 AkUInt32 in_ulCompanyID, ///< Company identifier (as declared in the plug-in description XML file) 01158 AkUInt32 in_ulPluginID, ///< Plug-in identifier (as declared in the plug-in description XML file) 01159 AkCreatePluginCallback in_pCreateFunc, ///< Pointer to the plug-in's creation function 01160 AkCreateParamCallback in_pCreateParamFunc ///< Pointer to the plug-in's parameter node creation function 01161 ) = 0; 01162 01163 /// Register a codec type with the sound engine and set the callback functions to create the 01164 /// codec's file source and bank source nodes. 01165 /// \sa 01166 /// - \ref register_effects 01167 /// \return AK_Success if successful, AK_InvalidParameter if invalid parameters were provided, or Ak_Fail otherwise. Possible reasons for an AK_Fail result are: 01168 /// - Insufficient memory to register the codec 01169 /// - Codec ID already registered 01170 /// \remarks 01171 /// Codecs and plug-ins must be registered before loading banks that use them.\n 01172 /// Loading a bank referencing an unregistered plug-in or codec will result in a load bank success, 01173 /// but the plug-ins will not be used. More specifically, playing a sound that uses an unregistered effect plug-in 01174 /// will result in audio playback without applying the said effect. If an unregistered source plug-in is used by an event's audio objects, 01175 /// posting the event will fail. 01176 virtual AKRESULT RegisterCodec( 01177 AkUInt32 in_ulCompanyID, ///< Company identifier (as declared in XML) 01178 AkUInt32 in_ulPluginID, ///< Plugin identifier (as declared in XML) 01179 AkCreateFileSourceCallback in_pFileCreateFunc, ///< Factory for streaming sources. 01180 AkCreateBankSourceCallback in_pBankCreateFunc ///< Factory for in-memory sources. 01181 ) = 0; 01182 01183 /// Register a global callback function. This function will be called from the audio rendering thread, at the 01184 /// location specified by in_eLocation. This function will also be called from the thread calling 01185 /// AK::SoundEngine::Term with in_eLocation set to AkGlobalCallbackLocation_Term. 01186 /// For example, in order to be called at every audio rendering pass, and once during teardown for releasing resources, you would call 01187 /// RegisterGlobalCallback(myCallback, AkGlobalCallbackLocation_BeginRender | AkGlobalCallbackLocation_Term, myCookie); 01188 /// \remarks 01189 /// It is illegal to call this function while already inside of a global callback. 01190 /// This function might stall for several milliseconds before returning. 01191 /// \sa 01192 /// - AK::IAkGlobalPluginContext::UnregisterGlobalCallback() 01193 /// - AkGlobalCallbackFunc 01194 /// - AkGlobalCallbackLocation 01195 virtual AKRESULT RegisterGlobalCallback( 01196 AkGlobalCallbackFunc in_pCallback, ///< Function to register as a global callback. 01197 AkUInt32 in_eLocation = AkGlobalCallbackLocation_BeginRender, ///< Callback location defined in AkGlobalCallbackLocation. Bitwise OR multiple locations if needed. 01198 void * in_pCookie = NULL ///< User cookie. 01199 ) = 0; 01200 01201 /// Unregister a global callback function, previously registered using RegisterGlobalCallback. 01202 /// \remarks 01203 /// It is legal to call this function while already inside of a global callback, If it is unregistering itself and not 01204 /// another callback. 01205 /// This function might stall for several milliseconds before returning. 01206 /// \sa 01207 /// - AK::IAkGlobalPluginContext::RegisterGlobalCallback() 01208 /// - AkGlobalCallbackFunc 01209 /// - AkGlobalCallbackLocation 01210 virtual AKRESULT UnregisterGlobalCallback( 01211 AkGlobalCallbackFunc in_pCallback, ///< Function to unregister as a global callback. 01212 AkUInt32 in_eLocation = AkGlobalCallbackLocation_BeginRender ///< Must match in_eLocation as passed to RegisterGlobalCallback for this callback. 01213 ) = 0; 01214 01215 /// Get the default allocator for plugins. This is useful for performing global initialization tasks shared across multiple plugin instances. 01216 virtual AK::IAkPluginMemAlloc * GetAllocator() = 0; 01217 01218 /// \sa SetRTPCValue 01219 virtual AKRESULT SetRTPCValue( 01220 AkRtpcID in_rtpcID, ///< ID of the game parameter 01221 AkRtpcValue in_value, ///< Value to set 01222 AkGameObjectID in_gameObjectID = AK_INVALID_GAME_OBJECT,///< Associated game object ID 01223 AkTimeMs in_uValueChangeDuration = 0, ///< Duration during which the game parameter is interpolated towards in_value 01224 AkCurveInterpolation in_eFadeCurve = AkCurveInterpolation_Linear, ///< Curve type to be used for the game parameter interpolation 01225 bool in_bBypassInternalValueInterpolation = false ///< True if you want to bypass the internal "slew rate" or "over time filtering" specified by the sound designer. This is meant to be used when for example loading a level and you dont want the values to interpolate. 01226 ) = 0; 01227 01228 /// Send custom game data to a plugin that resides on a bus (insert effect or mixer plugin). 01229 /// Data will be copied and stored into a separate list. 01230 /// Previous entry is deleted when a new one is sent. 01231 /// Set the data pointer to NULL to clear item from the list. 01232 /// This means that you cannot send different data to various instances of the plugin on a same bus.\endaknote 01233 /// \return AK_Success if data was sent successfully. 01234 virtual AKRESULT SendPluginCustomGameData( 01235 AkUniqueID in_busID, ///< Bus ID 01236 AkGameObjectID in_busObjectID, ///< Bus Object ID 01237 AkPluginType in_eType, ///< Plug-in type (for example, source or effect) 01238 AkUInt32 in_uCompanyID, ///< Company identifier (as declared in the plug-in description XML file) 01239 AkUInt32 in_uPluginID, ///< Plug-in identifier (as declared in the plug-in description XML file) 01240 const void* in_pData, ///< The data blob 01241 AkUInt32 in_uSizeInBytes ///< Size of data 01242 ) = 0; 01243 01244 /// N to N channels mix 01245 virtual void MixNinNChannels( 01246 AkAudioBuffer * in_pInputBuffer, ///< Input multichannel buffer. 01247 AkAudioBuffer * in_pMixBuffer, ///< Multichannel buffer with which the input buffer is mixed. 01248 AkReal32 in_fPrevGain, ///< Gain, corresponding to the beginning of the buffer, to apply uniformly to each mixed channel. 01249 AkReal32 in_fNextGain, ///< Gain, corresponding to the end of the buffer, to apply uniformly to each mixed channel. 01250 AK::SpeakerVolumes::ConstMatrixPtr in_mxPrevVolumes,///< In/out channel volume distribution corresponding to the beginning of the buffer (see AK::SpeakerVolumes::Matrix services). 01251 AK::SpeakerVolumes::ConstMatrixPtr in_mxNextVolumes ///< In/out channel volume distribution corresponding to the end of the buffer (see AK::SpeakerVolumes::Matrix services). 01252 ) = 0; 01253 01254 /// 1 to N channels mix 01255 virtual void Mix1inNChannels( 01256 AkReal32 * AK_RESTRICT in_pInChannel, ///< Input channel buffer. 01257 AkAudioBuffer * in_pMixBuffer, ///< Multichannel buffer with which the input buffer is mixed. 01258 AkReal32 in_fPrevGain, ///< Gain, corresponding to the beginning of the input channel. 01259 AkReal32 in_fNextGain, ///< Gain, corresponding to the end of the input channel. 01260 AK::SpeakerVolumes::ConstVectorPtr in_vPrevVolumes, ///< Output channel volume distribution corresponding to the beginning of the buffer (see AK::SpeakerVolumes::Vector services). 01261 AK::SpeakerVolumes::ConstVectorPtr in_vNextVolumes ///< Output channel volume distribution corresponding to the end of the buffer (see AK::SpeakerVolumes::Vector services). 01262 ) = 0; 01263 01264 /// Single channel mix 01265 virtual void MixChannel( 01266 AkReal32 * AK_RESTRICT in_pInBuffer, ///< Input channel buffer. 01267 AkReal32 * AK_RESTRICT in_pOutBuffer, ///< Output channel buffer. 01268 AkReal32 in_fPrevGain, ///< Gain, corresponding to the beginning of the input channel. 01269 AkReal32 in_fNextGain, ///< Gain, corresponding to the end of the input channel. 01270 AkUInt16 in_uNumFrames ///< Number of frames to mix. 01271 ) = 0; 01272 01273 /// Computes gain vector for encoding a source with angles in_fAzimuth and in_fElevation to full-sphere ambisonics with order in_uOrder. 01274 /// Ambisonic channels are ordered by ACN and use the SN3D convention. 01275 virtual void ComputeAmbisonicsEncoding( 01276 AkReal32 in_fAzimuth, ///< Incident angle, in radians [-pi,pi], where 0 is the front (positive values are clockwise). 01277 AkReal32 in_fElevation, ///< Incident angle, in radians [-pi/2,pi/2], where 0 is the azimuthal plane. 01278 AkChannelConfig in_cfgAmbisonics, ///< Determines number of gains in vector out_vVolumes. 01279 AK::SpeakerVolumes::VectorPtr out_vVolumes ///< Returned volumes (see AK::SpeakerVolumes::Vector services). Must be allocated prior to calling this function with the size returned by AK::SpeakerVolumes::Vector::GetRequiredSize() for the desired number of channels. You may obtain the number of channels from the order using the helper AK::AmbisonicOrderToNumChannels(). 01280 ) = 0; 01281 01282 /// Computes gain matrix for decoding an SN3D-normalized ACN-ordered ambisonic signal of order sqrt(in_cfgAmbisonics.uNumChannels)-1, with max-RE weighting function, on a (regularly) sampled sphere whose samples in_samples are 01283 /// expressed in left-handed cartesian coordinates, with unitary norm. 01284 /// This decoding technique is optimal for regular sampling. 01285 /// The returned matrix has in_cfgAmbisonics.uNumChannels inputs (rows) and in_uNumSamples outputs (columns), and is normalized by the number of samples. 01286 /// Supported ambisonic configurations are full-sphere 1st, 2nd and 3rd order. 01287 /// \return AK_Fail when ambisonic configuration. AK_Success otherwise. 01288 virtual AKRESULT ComputeWeightedAmbisonicsDecodingFromSampledSphere( 01289 const AkVector in_samples[], ///< Array of vector samples expressed in left-handed cartesian coordinates, where (1,0,0) points towards the right and (0,1,0) points towards the top. Vectors must be normalized. 01290 AkUInt32 in_uNumSamples, ///< Number of points in in_samples. 01291 AkChannelConfig in_cfgAmbisonics, ///< Ambisonic configuration. Supported configurations are 1-1, 2-2 and 3-3. Determines number of rows (input channels) in matrix out_mxVolume. 01292 AK::SpeakerVolumes::MatrixPtr out_mxVolume ///< Returned volume matrix (see AK::SpeakerVolumes::Matrix services). Must be allocated prior to calling this function with the size returned by AK::SpeakerVolumes::Matrix::GetRequiredSize() for the desired number of channels. You may obtain the number of channels from the order using the helper AK::AmbisonicOrderToNumChannels(). 01293 ) = 0; 01294 01295 /// Return an acoustic texture. 01296 /// \return The pointer to an acoustic texture if successful, NULL otherwise. 01297 virtual const AkAcousticTexture* GetAcousticTexture( 01298 AkAcousticTextureID in_AcousticTextureID ///< Acoustic Texture's ID 01299 ) = 0; 01300 01301 /// Given an emitter-listener pair, compute the azimuth and elevation angles of the emitter relative to the listener. 01302 /// \return AK_Success if the listener referenced in the emitter-listener pair was found; azimuth and elevation. 01303 virtual AKRESULT ComputeSphericalCoordinates( 01304 const AkEmitterListenerPair & in_pair, ///< Emitter-listener pair for which to compute azimuth and elevation angles. 01305 AkReal32 & out_fAzimuth, ///< Returned azimuthal angle, in radians. 01306 AkReal32 & out_fElevation ///< Returned elevation angle, in radians. 01307 ) const = 0; 01308 }; 01309 01310 /// This class takes care of the registration of plug-ins in the Wwise engine. Plug-in developers must provide one instance of this class for each plug-in. 01311 /// \sa \ref soundengine_plugins 01312 class PluginRegistration 01313 { 01314 public: 01315 PluginRegistration( 01316 AkPluginType in_eType, ///< Plugin type. 01317 AkUInt32 in_ulCompanyID, ///< Plugin company ID. 01318 AkUInt32 in_ulPluginID, ///< Plugin ID. 01319 AkCreatePluginCallback in_pCreateFunc, ///< Plugin object factory. 01320 AkCreateParamCallback in_pCreateParamFunc, ///< Plugin parameter object factory. 01321 AkGlobalCallbackFunc in_pRegisterCallback = NULL, ///< Optional callback function called after successful plugin registration, with argument AkGlobalCallbackLocation_Register. 01322 void * in_pRegisterCallbackCookie = NULL ///< Optional cookie passed to register callback function above. 01323 ) 01324 : pNext(g_pAKPluginList) 01325 , m_eType(in_eType) 01326 , m_ulCompanyID(in_ulCompanyID) 01327 , m_ulPluginID(in_ulPluginID) 01328 , m_pCreateFunc(in_pCreateFunc) 01329 , m_pCreateParamFunc(in_pCreateParamFunc) 01330 , m_pFileCreateFunc(NULL) 01331 , m_pBankCreateFunc(NULL) 01332 , m_pRegisterCallback(in_pRegisterCallback) 01333 , m_pRegisterCallbackCookie(in_pRegisterCallbackCookie) 01334 { 01335 g_pAKPluginList = this; 01336 } 01337 01338 PluginRegistration( 01339 AkUInt32 in_ulCompanyID, ///< Plugin company ID. 01340 AkUInt32 in_ulPluginID, ///< Plugin ID. 01341 AkCreateFileSourceCallback in_pCreateFile, ///< Streamed source factory. 01342 AkCreateBankSourceCallback in_pCreateBank) ///< In-memory source factory. 01343 : pNext(g_pAKPluginList) 01344 , m_eType(AkPluginTypeCodec) 01345 , m_ulCompanyID(in_ulCompanyID) 01346 , m_ulPluginID(in_ulPluginID) 01347 , m_pCreateFunc(NULL) 01348 , m_pCreateParamFunc(NULL) 01349 , m_pFileCreateFunc(in_pCreateFile) 01350 , m_pBankCreateFunc(in_pCreateBank) 01351 , m_pRegisterCallback(NULL) 01352 , m_pRegisterCallbackCookie(NULL) 01353 { 01354 g_pAKPluginList = this; 01355 } 01356 01357 PluginRegistration *pNext; 01358 AkPluginType m_eType; 01359 AkUInt32 m_ulCompanyID; 01360 AkUInt32 m_ulPluginID; 01361 AkCreatePluginCallback m_pCreateFunc; 01362 AkCreateParamCallback m_pCreateParamFunc; 01363 AkCreateFileSourceCallback m_pFileCreateFunc; 01364 AkCreateBankSourceCallback m_pBankCreateFunc; 01365 AkGlobalCallbackFunc m_pRegisterCallback; 01366 void * m_pRegisterCallbackCookie; 01367 }; 01368 } 01369 01370 #define AK_IMPLEMENT_PLUGIN_FACTORY(_pluginName_, _plugintype_, _companyid_, _pluginid_) \ 01371 AK::IAkPlugin* Create##_pluginName_(AK::IAkPluginMemAlloc * in_pAllocator); \ 01372 AK::IAkPluginParam * Create##_pluginName_##Params(AK::IAkPluginMemAlloc * in_pAllocator); \ 01373 AK::PluginRegistration _pluginName_##Registration(_plugintype_, _companyid_, _pluginid_, Create##_pluginName_, Create##_pluginName_##Params); 01374 01375 #define AK_STATIC_LINK_PLUGIN(_pluginName_) \ 01376 extern AK::PluginRegistration _pluginName_##Registration; \ 01377 void *_pluginName_##_linkonceonly = (void*)&_pluginName_##Registration; 01378 01379 #define DEFINE_PLUGIN_REGISTER_HOOK AK_DLLEXPORT AK::PluginRegistration * g_pAKPluginList = NULL; 01380 01381 #endif // _IAK_PLUGIN_H_
Was this page helpful?
Need Support?
Questions? Problems? Need more info? Contact us, and we can help!
Visit our Support pageTell 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