Version
menu_open
Wwise SDK 2023.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) 2024 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  */
49 #ifdef __cplusplus
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.
60 
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  */
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
111 {
112  namespace V1
113  {
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  */
133  {
134  public:
135  /**
136  * \copydoc CAudioPlugin::Instance
137  */
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  */
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  */
159  };
160 
161  /**
162  * \brief The C interface, fulfilled by your plug-in.
163  */
164  struct Interface : public CAudioPlugin
165  {
168  {
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 
182  static Interface g_interface;
183  return &g_interface;
184  }
186  return this;
187  }
189  return this;
190  }
191 
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.
237  /// Latest version of the C++ AudioPlugin interface.
239 
242 } // of namespace AK::Wwise::Plugin
243 
244 #endif
@ AK_WWISE_PLUGIN_INTERFACE_TYPE_AUDIO_PLUGIN
2021.1 Audio backend plug-in. ak_wwise_plugin_audio_plugin_v1
CAudioPlugin::Instance * GetInstancePointer()
Definition: AudioPlugin.h:185
ak_wwise_plugin_audio_plugin_v1 CAudioPlugin
Definition: AudioPlugin.h:114
Interface used to write data during sound bank generation.
Wwise Authoring Plug-ins - API to write data that can be converted for the target platform.
decltype(BaseInterface::m_version) InterfaceVersion
PluginInfoGenerator: Type for the m_version value in BaseInterface.
Wwise Authoring Plug-ins - Plug-in API for property sets.
The C interface, fulfilled by your plug-in.
Definition: AudioPlugin.h:165
Base host-provided instance type for ak_wwise_plugin_host_data_writer_v1.
Definition: PluginDef.h:633
Base instance type for providing audio plug-in backend services through ak_wwise_plugin_audio_plugin_...
Definition: PluginDef.h:708
ak_wwise_plugin_audio_plugin_instance_v1 Instance
Base instance type for providing audio plug-in backend services.
Definition: AudioPlugin.h:59
const CAudioPlugin::Instance * GetInstancePointer() const
Definition: AudioPlugin.h:188
CInterfacePtr InterfacePtr
Definition: PluginDef.h:995
Wwise API for general Audio Plug-in's backend.
Definition: AudioPlugin.h:133
std::underlying_type< InterfaceType >::type InterfaceTypeValue
PluginInfoGenerator: Underlying storage type for the m_interface value in BaseInterface.
@ k_interfaceVersion
The interface version, as provided by this plug-in.
Definition: AudioPlugin.h:158
@ k_interfaceType
The interface type, as provided by this plug-in.
Definition: AudioPlugin.h:148
AK_WWISE_PLUGIN_SPECIALIZE_INTERFACE_VERSION(AudioPlugin)
Wwise API for general Audio Plug-in's backend.
Definition: AudioPlugin.h:52
Interface description and base class for every Wwise Authoring plug-in interface.
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
virtual bool GetBankParameters(const GUID &in_guidPlatform, DataWriter &in_dataWriter) const
Obtains parameters that will be written to a bank.
Definition: AudioPlugin.h:228
V1::AudioPlugin AudioPlugin
Latest version of the C++ AudioPlugin interface.
Definition: AudioPlugin.h:238
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