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

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