Version
menu_open
link
Wwise SDK 2022.1.8
IAkMixerPlugin.h
Go to the documentation of this file.
1 /*******************************************************************************
2 The content of this file includes portions of the AUDIOKINETIC Wwise Technology
3 released in source code form as part of the SDK installer package.
4 
5 Commercial License Usage
6 
7 Licensees holding valid commercial licenses to the AUDIOKINETIC Wwise Technology
8 may use this file in accordance with the end user license agreement provided
9 with the software or, alternatively, in accordance with the terms contained in a
10 written agreement between you and Audiokinetic Inc.
11 
12 Apache License Usage
13 
14 Alternatively, this file may be used under the Apache License, Version 2.0 (the
15 "Apache License"); you may not use this file except in compliance with the
16 Apache License. You may obtain a copy of the Apache License at
17 http://www.apache.org/licenses/LICENSE-2.0.
18 
19 Unless required by applicable law or agreed to in writing, software distributed
20 under the Apache License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES
21 OR CONDITIONS OF ANY KIND, either express or implied. See the Apache License for
22 the specific language governing permissions and limitations under the License.
23 
24  Copyright (c) 2023 Audiokinetic Inc.
25 *******************************************************************************/
26 
27 /// \file
28 /// Software source plug-in and effect plug-in interfaces.
29 
30 #ifndef _IAK_MIXER_PLUGIN_H_
31 #define _IAK_MIXER_PLUGIN_H_
32 
33 #include <AK/SoundEngine/Common/IAkPlugin.h>
34 
35 namespace AK
36 {
37  /// Software effect plug-in interface for panner/mixer effects (see \ref soundengine_plugins_effects).
38  class IAkMixerEffectPlugin : public IAkPlugin
39  {
40  public:
41 
42  /// Software effect plug-in initialization. Prepares the effect for data processing, allocates memory and sets up the initial conditions.
43  /// \aknote Memory allocation should be done through appropriate macros (see \ref fx_memory_alloc). \endaknote
44  virtual AKRESULT Init(
45  IAkPluginMemAlloc * in_pAllocator, ///< Interface to memory allocator to be used by the effect.
46  IAkMixerPluginContext * in_pMixerPluginContext, ///< Interface to mixer plug-in's context.
47  IAkPluginParam * in_pParams, ///< Interface to plug-in parameters.
48  AkAudioFormat & in_rFormat ///< Audio data format of the requested output signal.
49  ) = 0;
50 
51  /// This function is called whenever a new input is connected to the underlying mixing bus.
52  virtual void OnInputConnected(
53  IAkMixerInputContext * in_pInput ///< Input that is being connected.
54  ) = 0;
55 
56  /// This function is called whenever a new input is disconnected to the underlying mixing bus.
57  /// \aknote OnInputDisconnected() may be called between calls to ConsumeInput() and OnMixDone().\endaknote
58  virtual void OnInputDisconnected(
59  IAkMixerInputContext * in_pInput ///< Input that is being disconnected.
60  ) = 0;
61 
62  /// This function is called whenever an input (voice or bus) needs to be mixed.
63  /// During an audio frame, ConsumeInput() will be called for each input that need to be mixed.
64  /// \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.
65  /// Mixers cannot make an input remain alive by changing their state.\endaknote
66  /// \aknote ConsumeInput() will not be called for frames during which a voice is not audible.\endaknote
67  /// \sa
68  /// - OnMixDone
69  /// - OnEffectsProcessed
70  virtual void ConsumeInput(
71  IAkMixerInputContext * in_pInputContext, ///< Context for this input. Carries non-audio data.
72  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).
73  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().
74  AkAudioBuffer * io_pInputBuffer, ///< Input audio buffer data structure. Plugins should avoid processing data in-place.
75  AkAudioBuffer * io_pMixBuffer ///< Output audio buffer data structure. Stored until call to OnEffectsProcessed().
76  ) = 0;
77 
78  /// This function is called once every audio frame, when all inputs have been mixed in
79  /// with ConsumeInput(). It is the time when the plugin may perform final DSP/bookkeeping.
80  /// After the bus buffer io_pMixBuffer has been pushed to the bus downstream (or the output device),
81  /// it is cleared out for the next frame.
82  /// \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.
83  /// 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.
84  /// 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
85  /// wait until OnEffectsProcessed() to flip the state to AK_DataReady. This is usually undesirable, so handling this inside OnMixDone() is usually preferred.\endaknote
86  /// \sa
87  /// - ConsumeInput
88  /// - OnEffectsProcessed
89  virtual void OnMixDone(
90  AkAudioBuffer * io_pMixBuffer ///< Output audio buffer data structure. Stored across calls to ConsumeInput().
91  ) = 0;
92 
93  /// This function is called once every audio frame, after all insert effects on the bus have been processed,
94  /// which occur after the post mix pass of OnMixDone().
95  /// After the bus buffer io_pMixBuffer has been pushed to the bus downstream (or the output device),
96  /// it is cleared out for the next frame.
97  /// \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.
98  /// 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.
99  /// 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
100  /// 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
101  /// \sa
102  /// - OnMixDone
103  /// - AK::AkMetering
104  /// - AK::IAkMixerPluginContext::EnableMetering()
105  virtual void OnEffectsProcessed(
106  AkAudioBuffer * io_pMixBuffer ///< Output audio buffer data structure.
107  ) = 0;
108 
109  /// 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),
110  /// which occur after OnEffectsProcessed().
111  /// 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.
112  /// Mixer plugins may use this hook for processing the signal after it has been metered.
113  /// \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.
114  /// 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.
115  /// 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
116  /// 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
117  /// \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().
118  /// It may also be enabled by the Wwise authoring tool when connected.\endaknote
119  /// \sa
120  /// - OnMixDone
121  /// - AK::AkMetering
122  /// - AK::IAkMixerPluginContext::EnableMetering()
123  virtual void OnFrameEnd(
124  AkAudioBuffer * io_pMixBuffer, ///< Output audio buffer data structure.
125  AkMetering * in_pMetering ///< Struct containing metering data computed on io_pMixBuffer. May be NULL if metering is not enabled.
126  ) = 0;
127  };
128 }
129 #endif // _IAK_MIXER_PLUGIN_H_
AK::IAkMixerPluginContext
Interface to retrieve contextual information for a mixer.
Definition: IAkPlugin.h:442
AK
Audiokinetic namespace.
Definition: AkWwiseSDKVersion.cs:31
AK::IAkMixerEffectPlugin::ConsumeInput
virtual void ConsumeInput(IAkMixerInputContext *in_pInputContext, AkRamp in_baseVolume, AkRamp in_emitListVolume, AkAudioBuffer *io_pInputBuffer, AkAudioBuffer *io_pMixBuffer)=0
AKRESULT
AKRESULT
Standard function call result.
Definition: AkTypes.h:199
AK::IAkMixerEffectPlugin
Software effect plug-in interface for panner/mixer effects (see Creating Sound Engine Effect Plug-ins...
Definition: IAkMixerPlugin.h:39
AK::IAkMixerEffectPlugin::OnEffectsProcessed
virtual void OnEffectsProcessed(AkAudioBuffer *io_pMixBuffer)=0
AK::IAkMixerEffectPlugin::OnFrameEnd
virtual void OnFrameEnd(AkAudioBuffer *io_pMixBuffer, AkMetering *in_pMetering)=0
AK::IAkMixerEffectPlugin::OnMixDone
virtual void OnMixDone(AkAudioBuffer *io_pMixBuffer)=0
AkRamp
Volume ramp specified by end points "previous" and "next".
Definition: AkTypes.h:933
AK::IAkMixerEffectPlugin::Init
virtual AKRESULT Init(IAkPluginMemAlloc *in_pAllocator, IAkMixerPluginContext *in_pMixerPluginContext, IAkPluginParam *in_pParams, AkAudioFormat &in_rFormat)=0
AK::AkMetering
Struct containing metering information about a buffer. Depending on when this struct is generated,...
Definition: AkCommonDefs.h:203
AK::IAkMixerEffectPlugin::OnInputConnected
virtual void OnInputConnected(IAkMixerInputContext *in_pInput)=0
This function is called whenever a new input is connected to the underlying mixing bus.
AkAudioFormat
Defines the parameters of an audio buffer format.
Definition: AkCommonDefs.h:62
AK::IAkMixerEffectPlugin::OnInputDisconnected
virtual void OnInputDisconnected(IAkMixerInputContext *in_pInput)=0

Was this page helpful?

Need Support?

Questions? Problems? Need more info? Contact us, and we can help!

Visit our Support page

Tell 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