Version
menu_open
Wwise SDK 2024.1.4
AudioPlugin.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) 2025 Audiokinetic Inc.
25 *******************************************************************************/
26 
27 /**
28  * \brief Wwise Authoring Plug-ins - API for general Audio Plug-in's backend (Source, Effect, Mixer).
29  * \file AK/Wwise/Plugin/AudioPlugin.h
30  */
31 
32 #pragma once
33 
34 #include "HostPropertySet.h"
35 #include "HostDataWriter.h"
36 
37 
38 /**
39  * \brief Wwise API for general Audio Plug-in's backend.
40  *
41  * \sa
42  * - \ref ak_wwise_plugin_audio_plugin_instance_v1 instance type
43  * - \ref AK::Wwise::Plugin::AudioPlugin C++ Interface
44  * - \ref AK_WWISE_PLUGIN_AUDIO_PLUGIN_V1_ID Current ID for interface
45  * - \ref AK_WWISE_PLUGIN_INTERFACE_TYPE_AUDIO_PLUGIN
46  * - \ref wwiseplugin_backend
47  */
48 struct ak_wwise_plugin_audio_plugin_v1
49 #ifdef __cplusplus
50  : public ak_wwise_plugin_base_interface
51 #endif
52 {
53 #ifndef __cplusplus
54  ak_wwise_plugin_base_interface m_baseInterface;
55 #endif
56 
57 #ifdef __cplusplus
58  /// Base instance type for providing audio plug-in backend services.
59  using Instance = ak_wwise_plugin_audio_plugin_instance_v1;
60 
61  ak_wwise_plugin_audio_plugin_v1() :
62  ak_wwise_plugin_base_interface(AK_WWISE_PLUGIN_INTERFACE_TYPE_AUDIO_PLUGIN, 1)
63  {}
64 #endif
65 
66  /**
67  * \brief Obtains parameters that will be written to a bank.
68  *
69  * This is the usual function that gets overridden to provide data from the Authoring plug-in to the
70  * Sound Engine plug-in. Its goal is to retrieve data (usually from the PropertySet) and write it
71  * in the proper format and order, so the Sound Engine part can retrieve it and use it.
72  *
73  * By design, this function is called to store data, as provided in the plug-in definition XML.
74  *
75  * Because these can be changed at run-time, the parameter block should stay relatively small. For example, it
76  * should only provide basic members. Array sets, full sections, binary data or Object Stores might be
77  * better sent using the GetPluginData function, as the system can then ask to update only a portion
78  * of the parameters.
79  *
80  * The design pattern, in that case, is to call GetPluginData at the end of GetBankParameters with some unique
81  * in_idParam (AK::IAkPluginParam::ALL_PLUGIN_DATA_ID) indicating that you want to send all the parameters
82  * to the data writer.
83  *
84  * \aknote In order to use the in_pDataWriter instance, your plugin must request the data writer
85  * interface: ak_wwise_plugin_host_data_writer_v1. \endaknote
86  *
87  * \param[in] in_this Current instance of this interface.
88  * \param[in] in_guidPlatform The unique ID of the queried platform
89  * \param[in] in_pDataWriter A pointer to the data writer instance being used.
90  * \return true if successfully putting some parameters in the bank
91  *
92  * \sa
93  * - \ref wwiseplugin_bank
94  * - \ref wwiseplugin_propertyset
95  */
96  bool(*GetBankParameters)(
97  const struct ak_wwise_plugin_audio_plugin_instance_v1* in_this,
98  const GUID * in_guidPlatform,
99  struct ak_wwise_plugin_host_data_writer_instance_v1* in_pDataWriter);
100 };
101 
102 #define AK_WWISE_PLUGIN_AUDIO_PLUGIN_V1_ID() \
103  AK_WWISE_PLUGIN_BASE_INTERFACE_FROM_ID(AK_WWISE_PLUGIN_INTERFACE_TYPE_AUDIO_PLUGIN, 1)
104 #define AK_WWISE_PLUGIN_AUDIO_PLUGIN_V1_CTOR(/* ak_wwise_plugin_info* */ in_pluginInfo, /* void* */ in_data) \
105 { \
106  .m_baseInterface = AK_WWISE_PLUGIN_BASE_INTERFACE_CTOR(AK_WWISE_PLUGIN_AUDIO_PLUGIN_V1_ID(), in_pluginInfo, in_data) \
107 }
108 
109 #ifdef __cplusplus
110 namespace AK::Wwise::Plugin
111 {
112  namespace V1
113  {
114  using CAudioPlugin = ak_wwise_plugin_audio_plugin_v1;
115 
116  /**
117  * \brief Wwise API for general Audio Plug-in's backend.
118  *
119  * \sa
120  * - \ref ak_wwise_plugin_audio_plugin_instance_v1 instance type
121  * - \ref ak_wwise_plugin_audio_plugin_v1 C Interface
122  * - \ref AK_WWISE_PLUGIN_AUDIO_PLUGIN_V1_ID Current ID for interface
123  * - \ref AK_WWISE_PLUGIN_INTERFACE_TYPE_AUDIO_PLUGIN
124  * - \ref wwiseplugin_backend
125  *
126  * \aknote The \ref AK::Wwise::Plugin::RequestPropertySet and
127  * \ref AK::Wwise::Plugin::RequestWrite classes are automatically derived when
128  * providing \ref AK::Wwise::Plugin::AudioPlugin in C++. \endaknote
129  */
130  class AudioPlugin : public CAudioPlugin::Instance,
131  public AK::Wwise::Plugin::RequestPropertySet,
132  public AK::Wwise::Plugin::RequestWrite
133  {
134  public:
135  /**
136  * \copydoc CAudioPlugin::Instance
137  */
138  using Instance = CAudioPlugin::Instance;
139 
140  /**
141  * \brief The interface type, as provided by this plug-in.
142  */
143  enum : InterfaceTypeValue
144  {
145  /**
146  * \brief The interface type, as provided by this plug-in.
147  */
148  k_interfaceType = AK_WWISE_PLUGIN_INTERFACE_TYPE_AUDIO_PLUGIN
149  };
150  /**
151  * \brief The interface version, as provided by this plug-in.
152  */
153  enum : InterfaceVersion
154  {
155  /**
156  * \brief The interface version, as provided by this plug-in.
157  */
158  k_interfaceVersion = 1
159  };
160 
161  /**
162  * \brief The C interface, fulfilled by your plug-in.
163  */
164  struct Interface : public CAudioPlugin
165  {
166  using Instance = AudioPlugin;
167  Interface()
168  {
169  CAudioPlugin::GetBankParameters = [](
170  const struct ak_wwise_plugin_audio_plugin_instance_v1* in_this,
171  const GUID * in_guidPlatform,
172  struct ak_wwise_plugin_host_data_writer_instance_v1* in_pDataWriter)
173  {
174  return (bool)static_cast<const Instance*>(in_this)->GetBankParameters(
175  *in_guidPlatform,
176  *static_cast<DataWriter*>(in_pDataWriter));
177  };
178  }
179  };
180 
181  InterfacePtr GetInterfacePointer() {
182  static Interface g_interface;
183  return &g_interface;
184  }
185  CAudioPlugin::Instance* GetInstancePointer() {
186  return this;
187  }
188  const CAudioPlugin::Instance* GetInstancePointer() const {
189  return this;
190  }
191 
192  AudioPlugin() :
193  CAudioPlugin::Instance()
194  {
195  }
196 
197  virtual ~AudioPlugin() {}
198 
199  /**
200  * \brief Obtains parameters that will be written to a bank.
201  *
202  * This is the usual function that gets overridden to provide data from the Authoring plug-in to the
203  * Sound Engine plug-in. Its goal is to retrieve data (usually from the PropertySet) and write it
204  * in the proper format and order, so the Sound Engine part can retrieve it and use it.
205  *
206  * By design, this function is called to store data, as provided in the plug-in definition XML.
207  *
208  * Because these can be changed at run-time, the parameter block should stay relatively small. For example, it
209  * should only provide basic members. Array sets, full sections, binary data or Object Stores might be
210  * better sent using the GetPluginData function, as the system can then ask to update only a portion
211  * of the parameters.
212  *
213  * The design pattern, in that case, is to call GetPluginData at the end of GetBankParameters with some unique
214  * in_idParam (AK::IAkPluginParam::ALL_PLUGIN_DATA_ID) indicating that you want to send all the parameters
215  * to the data writer.
216  *
217  * \aknote In order to use the in_pDataWriter instance, your plugin must request the data writer
218  * interface: AK::Wwise::Plugin::RequestWrite. \endaknote
219  *
220  * \param[in] in_guidPlatform The unique ID of the queried platform
221  * \param[in] in_dataWriter A reference to the data writer instance being used.
222  * \return true if successfully putting some parameters in the bank
223  *
224  * \sa
225  * - \ref wwiseplugin_bank
226  * - \ref wwiseplugin_propertyset
227  */
228  virtual bool GetBankParameters(
229  const GUID & in_guidPlatform,
230  DataWriter & in_dataWriter
231  ) const { return false; }
232  };
233  } // of namespace V1
234 
235  /// Latest version of the C AudioPlugin interface.
236  using CAudioPlugin = V1::CAudioPlugin;
237  /// Latest version of the C++ AudioPlugin interface.
238  using AudioPlugin = V1::AudioPlugin;
239 
240  AK_WWISE_PLUGIN_SPECIALIZE_INTERFACE_CLASS(AudioPlugin);
241  AK_WWISE_PLUGIN_SPECIALIZE_INTERFACE_VERSION(AudioPlugin);
242 } // of namespace AK::Wwise::Plugin
243 
244 #endif
AK_WWISE_PLUGIN_INTERFACE_TYPE_AUDIO_PLUGIN
@ AK_WWISE_PLUGIN_INTERFACE_TYPE_AUDIO_PLUGIN
2021.1 Audio backend plug-in. ak_wwise_plugin_audio_plugin_v1
Definition: PluginBaseInterface.h:56
AK.Wwise::Plugin::V1::AudioPlugin::GetInstancePointer
CAudioPlugin::Instance * GetInstancePointer()
Definition: AudioPlugin.h:185
AK.Wwise::Plugin::V1::CAudioPlugin
ak_wwise_plugin_audio_plugin_v1 CAudioPlugin
Definition: AudioPlugin.h:114
AK.Wwise::Plugin::V1::DataWriter
Interface used to write data during sound bank generation.
Definition: HostDataWriter.h:245
HostDataWriter.h
Wwise Authoring Plug-ins - API to write data that can be converted for the target platform.
AK.Wwise::Plugin::InterfaceVersion
decltype(BaseInterface::m_version) InterfaceVersion
PluginInfoGenerator: Type for the m_version value in BaseInterface.
Definition: PluginInfoGenerator.h:50
HostPropertySet.h
Wwise Authoring Plug-ins - Plug-in API for property sets.
AK.Wwise::Plugin::V1::AudioPlugin::Interface
The C interface, fulfilled by your plug-in.
Definition: AudioPlugin.h:165
ak_wwise_plugin_audio_plugin_v1::ak_wwise_plugin_audio_plugin_v1
ak_wwise_plugin_audio_plugin_v1()
Definition: AudioPlugin.h:61
ak_wwise_plugin_host_data_writer_instance_v1
Base host-provided instance type for ak_wwise_plugin_host_data_writer_v1.
Definition: PluginDef.h:651
ak_wwise_plugin_audio_plugin_instance_v1
Base instance type for providing audio plug-in backend services through ak_wwise_plugin_audio_plugin_...
Definition: PluginDef.h:730
ak_wwise_plugin_audio_plugin_v1::Instance
ak_wwise_plugin_audio_plugin_instance_v1 Instance
Base instance type for providing audio plug-in backend services.
Definition: AudioPlugin.h:59
AK.Wwise::Plugin::V1::AudioPlugin::GetInstancePointer
const CAudioPlugin::Instance * GetInstancePointer() const
Definition: AudioPlugin.h:188
AK.Wwise::Plugin::InterfacePtr
CInterfacePtr InterfacePtr
Definition: PluginDef.h:1057
AK.Wwise::Plugin::V1::AudioPlugin
Wwise API for general Audio Plug-in's backend.
Definition: AudioPlugin.h:133
AK.Wwise::Plugin::InterfaceTypeValue
std::underlying_type< InterfaceType >::type InterfaceTypeValue
PluginInfoGenerator: Underlying storage type for the m_interface value in BaseInterface.
Definition: PluginInfoGenerator.h:49
AK.Wwise::Plugin::V1::AudioPlugin::k_interfaceVersion
@ k_interfaceVersion
The interface version, as provided by this plug-in.
Definition: AudioPlugin.h:158
AK.Wwise::Plugin::V1::AudioPlugin::k_interfaceType
@ k_interfaceType
The interface type, as provided by this plug-in.
Definition: AudioPlugin.h:148
AK.Wwise::Plugin::AK_WWISE_PLUGIN_SPECIALIZE_INTERFACE_VERSION
AK_WWISE_PLUGIN_SPECIALIZE_INTERFACE_VERSION(AudioPlugin)
ak_wwise_plugin_audio_plugin_v1
Wwise API for general Audio Plug-in's backend.
Definition: AudioPlugin.h:52
ak_wwise_plugin_base_interface
Interface description and base class for every Wwise Authoring plug-in interface.
Definition: PluginBaseInterface.h:120
ak_wwise_plugin_audio_plugin_v1::GetBankParameters
bool(* GetBankParameters)(const struct ak_wwise_plugin_audio_plugin_instance_v1 *in_this, const GUID *in_guidPlatform, struct ak_wwise_plugin_host_data_writer_instance_v1 *in_pDataWriter)
Obtains parameters that will be written to a bank.
Definition: AudioPlugin.h:96
AK.Wwise::Plugin::V1::AudioPlugin::GetBankParameters
virtual bool GetBankParameters(const GUID &in_guidPlatform, DataWriter &in_dataWriter) const
Obtains parameters that will be written to a bank.
Definition: AudioPlugin.h:228
AK.Wwise::Plugin::AudioPlugin
V1::AudioPlugin AudioPlugin
Latest version of the C++ AudioPlugin interface.
Definition: AudioPlugin.h:238
AK.Wwise::Plugin::AK_WWISE_PLUGIN_SPECIALIZE_INTERFACE_CLASS
AK_WWISE_PLUGIN_SPECIALIZE_INTERFACE_CLASS(AudioPlugin)

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