Table of Contents

include/AK/SoundEngine/Common/IAkMixerPlugin.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_MIXER_PLUGIN_H_
00032 #define _IAK_MIXER_PLUGIN_H_
00033 
00034 #include <AK/SoundEngine/Common/IAkPlugin.h>
00035 
00036 namespace AK
00037 {
00038     /// Software effect plug-in interface for panner/mixer effects (see \ref soundengine_plugins_effects).
00039     class IAkMixerEffectPlugin : public IAkPlugin
00040     {
00041     public:
00042 
00043         /// Software effect plug-in initialization. Prepares the effect for data processing, allocates memory and sets up the initial conditions. 
00044         /// \aknote Memory allocation should be done through appropriate macros (see \ref fx_memory_alloc). \endaknote
00045         virtual AKRESULT Init( 
00046             IAkPluginMemAlloc *         in_pAllocator,              ///< Interface to memory allocator to be used by the effect.
00047             IAkMixerPluginContext *     in_pMixerPluginContext,     ///< Interface to mixer plug-in's context.
00048             IAkPluginParam *            in_pParams,                 ///< Interface to plug-in parameters.
00049             AkAudioFormat &             in_rFormat                  ///< Audio data format of the requested output signal.
00050             ) = 0;
00051 
00052         /// This function is called whenever a new input is connected to the underlying mixing bus.
00053         virtual void OnInputConnected( 
00054             IAkMixerInputContext * in_pInput            ///< Input that is being connected.
00055             ) = 0;
00056         
00057         /// This function is called whenever a new input is disconnected to the underlying mixing bus.
00058         /// \aknote OnInputDisconnected() may be called between calls to ConsumeInput() and OnMixDone().\endaknote
00059         virtual void OnInputDisconnected( 
00060             IAkMixerInputContext * in_pInput            ///< Input that is being disconnected.
00061             ) = 0;
00062 
00063         /// This function is called whenever an input (voice or bus) needs to be mixed.
00064         /// During an audio frame, ConsumeInput() will be called for each input that need to be mixed.
00065         /// \aknote io_pInputBuffer->eState will be set as AK_NoMoreData the last time the given input is processed by ConsumeInput(). Otherwise it is set to AK_DataReady.
00066         /// Mixers cannot make an input remain alive by changing their state.\endaknote
00067         /// \aknote ConsumeInput() will not be called for frames during which a voice is not audible.\endaknote
00068         /// \sa
00069         /// - OnMixDone
00070         /// - OnEffectsProcessed
00071         virtual void ConsumeInput( 
00072             IAkMixerInputContext *  in_pInputContext,   ///< Context for this input. Carries non-audio data.
00073             AkRamp                  in_baseVolume,      ///< Base volume to apply to this input (prev corresponds to the beginning, next corresponds to the end of the buffer). This gain is agnostic of emitter-listener pair-specific contributions (such as distance level attenuation).
00074             AkRamp                  in_emitListVolume,  ///< Emitter-listener pair-specific gain. When there are multiple emitter-listener pairs, this volume equals 1, and pair gains are applied directly on the channel volume matrix (accessible via IAkMixerInputContext::GetSpatializedVolumes()). For custom processing of emitter-listener pairs, one should query each pair volume using IAkMixerInputContext::Get3DPosition(), then AkEmitterListenerPair::GetGainForConnectionType().
00075             AkAudioBuffer *         io_pInputBuffer,    ///< Input audio buffer data structure. Plugins should avoid processing data in-place.
00076             AkAudioBuffer *         io_pMixBuffer       ///< Output audio buffer data structure. Stored until call to OnEffectsProcessed().
00077             ) = 0;
00078 
00079         /// This function is called once every audio frame, when all inputs have been mixed in 
00080         /// with ConsumeInput(). It is the time when the plugin may perform final DSP/bookkeeping.
00081         /// After the bus buffer io_pMixBuffer has been pushed to the bus downstream (or the output device),
00082         /// it is cleared out for the next frame.
00083         /// \aknote io_pMixBuffer->eState is passed as AK_DataReady for the whole existence of the bus, until the last frame where it will be set to AK_NoMoreData.
00084         /// However, mixer plugins are capable of forcing the bus to remain alive for a longer time by changing io_pMixBuffer->eState back to AK_DataReady.
00085         /// You may do this in OnMixDone() or in OnEffectsProcessed(). The difference is that effects inserted on the bus will enter their "tail mode" if you
00086         /// wait until OnEffectsProcessed() to flip the state to AK_DataReady. This is usually undesirable, so handling this inside OnMixDone() is usually preferred.\endaknote
00087         /// \sa
00088         /// - ConsumeInput
00089         /// - OnEffectsProcessed
00090         virtual void OnMixDone( 
00091             AkAudioBuffer *         io_pMixBuffer       ///< Output audio buffer data structure. Stored across calls to ConsumeInput().
00092             ) = 0;
00093 
00094         /// This function is called once every audio frame, after all insert effects on the bus have been processed, 
00095         /// which occur after the post mix pass of OnMixDone().
00096         /// After the bus buffer io_pMixBuffer has been pushed to the bus downstream (or the output device),
00097         /// it is cleared out for the next frame.
00098         /// \aknote io_pMixBuffer->eState is passed as AK_DataReady for the whole existence of the bus, until the last frame where it will be set to AK_NoMoreData.
00099         /// However, mixer plugins are capable of forcing the bus to remain alive for a longer time by changing io_pMixBuffer->eState back to AK_DataReady.
00100         /// You may do this in OnMixDone(), in OnEffectsProcessed() or in OnFrameEnd(). The difference is that effects inserted on the bus will enter their "tail mode" if you
00101         /// wait until OnEffectsProcessed() or OnFrameEnd() to flip the state to AK_DataReady. This is usually undesirable, so handling this inside OnMixDone() is usually preferred.\endaknote
00102         /// \sa
00103         /// - OnMixDone
00104         /// - AK::IAkMetering
00105         /// - AK::IAkMixerPluginContext::EnableMetering()
00106         virtual void OnEffectsProcessed( 
00107             AkAudioBuffer *         io_pMixBuffer       ///< Output audio buffer data structure.
00108             ) = 0;
00109 
00110         /// This function is called once every audio frame, after all insert effects on the bus have been processed, and after metering has been processed (if applicable),
00111         /// which occur after OnEffectsProcessed().
00112         /// After the bus buffer io_pMixBuffer has been pushed to the bus downstream (or the output device), it is cleared out for the next frame.
00113         /// Mixer plugins may use this hook for processing the signal after it has been metered.
00114         /// \aknote io_pMixBuffer->eState is passed as AK_DataReady for the whole existence of the bus, until the last frame where it will be set to AK_NoMoreData.
00115         /// However, mixer plugins are capable of forcing the bus to remain alive for a longer time by changing io_pMixBuffer->eState back to AK_DataReady.
00116         /// You may do this in OnMixDone(), in OnEffectsProcessed() or in OnFrameEnd(). The difference is that effects inserted on the bus will enter their "tail mode" if you
00117         /// wait until OnEffectsProcessed() or OnFrameEnd() to flip the state to AK_DataReady. This is usually undesirable, so handling this inside OnMixDone() is usually preferred.\endaknote
00118         /// \aknote This function is called after metering gets computed on io_pMixBuffer. You may access the result in in_pMetering. Metering has to be enabled with AK::IAkMixerPluginContext::EnableMetering().
00119         /// It may also be enabled by the Wwise authoring tool when connected.\endaknote
00120         /// \sa
00121         /// - OnMixDone
00122         /// - AK::IAkMetering
00123         /// - AK::IAkMixerPluginContext::EnableMetering()
00124         virtual void OnFrameEnd(
00125             AkAudioBuffer *         io_pMixBuffer,      ///< Output audio buffer data structure.
00126             IAkMetering *           in_pMetering        ///< Interface for retrieving metering data computed on io_pMixBuffer. May be NULL if metering is not enabled.
00127             ) = 0;
00128     };
00129 }
00130 #endif // _IAK_MIXER_PLUGIN_H_