Version
menu_open
link
Wwise SDK 2022.1.4
CustomData.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 /**
28  * \brief Wwise Authoring Plug-ins - Backend API to load and save custom data in XML format.
29  * \file AK/Wwise/Plugin/CustomData.h
30  */
31 
32 #pragma once
33 
34 #include "HostXml.h"
35 #include "HostDataWriter.h"
36 
37 /**
38  * \brief Backend API to load and save custom data in XML format.
39  *
40  * The initialization of custom-data-aware plug-ins is done using one of three mutually
41  * exclusive possibilities:
42  * - \b InitToDefault : Initializes a new instance using the default values
43  * - \b InitFromInstance : Initializes a new instance using the values provided by the
44  * original instance.
45  * - \b InitFromWorkunit : Initializes a new instance using the values provided in the Save method.
46  *
47  * \aknote In order to use the XML reader and writer instance, your plug-in must request the XML
48  * interface: ak_wwise_plugin_host_xml_v1. \endaknote
49  */
50 struct ak_wwise_plugin_custom_data_v1
51 #ifdef __cplusplus
52  : public ak_wwise_plugin_base_interface
53 #endif
54 {
55 #ifndef __cplusplus
56  ak_wwise_plugin_base_interface m_baseInterface;
57 #endif
58 
59 #ifdef __cplusplus
60  /// Base instance type for providing custom data loading and saving.
61  using Instance = ak_wwise_plugin_custom_data_instance_v1;
62 
63  ak_wwise_plugin_custom_data_v1() :
64  ak_wwise_plugin_base_interface(AK_WWISE_PLUGIN_INTERFACE_TYPE_CUSTOM_DATA, 1)
65  {}
66 #endif
67 
68  /**
69  * \brief Initializes the plug-in's custom data to its default values.
70  *
71  * This method is mutually exclusive with the other Init methods.
72  *
73  * \param[in] in_this Current instance of this interface.
74  */
75  void(*InitToDefault)(
76  struct ak_wwise_plugin_custom_data_instance_v1* in_this);
77 
78  /**
79  * \brief Copy the plug-in's custom data from another instance of the same plug-in.
80  *
81  * This is used during copy/paste and delete for Undo purposes. The properties on
82  * the PropertySet do not need to be copied in this method.
83  *
84  * This method is mutually exclusive with the other Init methods.
85  *
86  * \param[in] in_this Current instance of this interface (Destination).
87  * \param[in] in_source The object that will provide the data used in initializing
88  * this instance.
89  * \return true if successful.
90  */
91  bool(*InitFromInstance)(
92  struct ak_wwise_plugin_custom_data_instance_v1* in_this,
93  const struct ak_wwise_plugin_custom_data_instance_v1* in_source);
94 
95  /**
96  * \brief Load the custom data structure from the provided Work Unit's XML.
97  *
98  * This method is mutually exclusive with the other Init methods.
99  *
100  * \aknote In order to use the in_pReader instance, your plug-in must request the XML
101  * interface: ak_wwise_plugin_host_xml_v1. \endaknote
102  *
103  * \param[in] in_this Current instance of this interface.
104  * \param[in] in_pReader XML Reader instance.
105  * \return true if load succeeded.
106  */
107  bool(*InitFromWorkunit)(
108  struct ak_wwise_plugin_custom_data_instance_v1* in_this,
109  struct ak_wwise_plugin_host_xml_reader_instance_v1* in_pReader);
110 
111  /**
112  * \brief Save custom data structure in the provided Work Unit's XML.
113  *
114  * \aknote In order to use the in_pWriter instance, your plug-in must request the XML
115  * interface: ak_wwise_plugin_host_xml_v1. \endaknote
116  *
117  * \param[in] in_this Current instance of this interface.
118  * \param[in] in_pWriter XML Writer instance.
119  * \return true if save succeeded.
120  */
121  bool(*Save)(
122  struct ak_wwise_plugin_custom_data_instance_v1* in_this,
123  struct ak_wwise_plugin_host_xml_writer_instance_v1* in_pWriter);
124 
125  /**
126  * \brief OnDelete function is called when the user presses the "delete" button on a plug-in.
127  *
128  * This handler function should properly clean custom data and set undo/redo action properly
129  * to allow recreation on undo.
130  *
131  * \param[in] in_this Current instance of this interface.
132  */
133  void(*OnDelete)(struct ak_wwise_plugin_custom_data_instance_v1* in_this);
134 
135  /**
136  * \brief Obtains parameters that will be sent to the sound engine when Wwise is connected.
137  *
138  * This block should contain only data that is NOT a property defined in the plug-in xml file. The
139  * parameter ID should be different than the ones used in the plug-in xml.
140  *
141  * This is used when there are Object Store, large binary data sections, or properties not usually
142  * residing in the XML. \sa \ref AK::Wwise::Plugin::AudioPlugin::GetBankParameters for a discussion
143  * on parameter passing to the Sound Engine.
144  *
145  * \aknote In order to use the in_pDataWriter instance, your plug-in must request the data writer
146  * interface: ak_wwise_plugin_host_data_writer_v1. \endaknote
147  *
148  * \param[in] in_this Current instance of this interface.
149  * \param[in] in_guidPlatform The unique ID of the queried platform
150  * \param[in] in_idParam The plug-in defined parameter ID
151  * \param[in] in_pDataWriter A pointer to the data writer instance being used.
152  * \return true if the plug-in has some plug-in defined data.
153  *
154  * \sa
155  * - \ref AK::Wwise::Plugin::Host::NotifyInternalDataChanged
156  * - \ref AK::IAkPluginParam::ALL_PLUGIN_DATA_ID
157  * - \ref AK::IAkPluginParam::SetParam
158  */
159  bool(*GetPluginData)(
160  const struct ak_wwise_plugin_custom_data_instance_v1* in_this,
161  const GUID* in_guidPlatform,
162  AkPluginParamID in_idParam,
163  struct ak_wwise_plugin_host_data_writer_instance_v1* in_pDataWriter);
164 
165 };
166 #define AK_WWISE_PLUGIN_CUSTOM_DATA_V1_ID() \
167  AK_WWISE_PLUGIN_BASE_INTERFACE_FROM_ID(AK_WWISE_PLUGIN_INTERFACE_TYPE_CUSTOM_DATA, 1)
168 #define AK_WWISE_PLUGIN_CUSTOM_DATA_V1_CTOR(/* ak_wwise_plugin_info* */ in_pluginInfo, /* void* */ in_data) \
169 { \
170  .m_baseInterface = AK_WWISE_PLUGIN_BASE_INTERFACE_CTOR(AK_WWISE_PLUGIN_CUSTOM_DATA_V1_ID(), in_pluginInfo, in_data) \
171 }
172 
173 
174 #ifdef __cplusplus
175 namespace AK::Wwise::Plugin
176 {
177  namespace V1
178  {
179  using CCustomData = ak_wwise_plugin_custom_data_v1;
180 
181  /**
182  * \brief Backend API to load and save custom data in XML format.
183  *
184  * The initialization of custom-data-aware plug-ins is done using one of three mutually
185  * exclusive possibilities:
186  * - \b InitToDefault : Initializes a new instance using the default values
187  * - \b InitFromInstance : Initializes a new instance using the values provided by the
188  * original instance.
189  * - \b InitFromWorkunit : Initializes a new instance using the values provided in the Save method.
190  *
191  * \aknote AK::Wwise::Plugin::The RequestXml class is automatically derived when providing
192  * \ref CustomData in C++. \endaknote
193  */
194  class CustomData : public CCustomData::Instance,
195  public AK::Wwise::Plugin::RequestXml
196  {
197  public:
198  /**
199  * \copydoc CCustomData::Instance
200  */
201  using Instance = CCustomData::Instance;
202 
203  /**
204  * \brief The interface type, as provided by this plug-in.
205  */
206  enum : InterfaceTypeValue
207  {
208  /**
209  * \brief The interface type, as provided by this plug-in.
210  */
211  k_interfaceType = AK_WWISE_PLUGIN_INTERFACE_TYPE_CUSTOM_DATA
212  };
213  /**
214  * \brief The interface version, as provided by this plug-in.
215  */
216  enum : InterfaceVersion
217  {
218  /**
219  * \brief The interface version, as provided by this plug-in.
220  */
221  k_interfaceVersion = 1
222  };
223 
224  struct Interface : public CCustomData
225  {
226  using Instance = CustomData;
227  Interface()
228  {
229  CCustomData::InitToDefault = [](
230  struct ak_wwise_plugin_custom_data_instance_v1* in_this)
231  {
232  static_cast<Instance*>(in_this)->InitToDefault();
233  };
234  CCustomData::InitFromInstance = [](
235  struct ak_wwise_plugin_custom_data_instance_v1* in_this,
236  const struct ak_wwise_plugin_custom_data_instance_v1* in_source)
237  {
238  return (bool)static_cast<Instance*>(in_this)->InitFromInstance(
239  *static_cast<const CustomData*>(in_source));
240  };
241  CCustomData::InitFromWorkunit = [](
242  struct ak_wwise_plugin_custom_data_instance_v1* in_this,
243  struct ak_wwise_plugin_host_xml_reader_instance_v1* in_pReader)
244  {
245  return (bool)static_cast<Instance*>(in_this)->InitFromWorkunit(
246  *static_cast<XmlReader*>(in_pReader));
247  };
248  CCustomData::Save = [](
249  struct ak_wwise_plugin_custom_data_instance_v1* in_this,
250  struct ak_wwise_plugin_host_xml_writer_instance_v1* in_pWriter)
251  {
252  return (bool)static_cast<Instance*>(in_this)->Save(
253  *static_cast<XmlWriter*>(in_pWriter));
254  };
255  CCustomData::OnDelete = [](
256  struct ak_wwise_plugin_custom_data_instance_v1* in_this)
257  {
258  static_cast<Instance*>(in_this)->OnDelete();
259  };
260  CCustomData::GetPluginData = [](
261  const struct ak_wwise_plugin_custom_data_instance_v1* in_this,
262  const GUID* in_guidPlatform,
263  AkPluginParamID in_idParam,
264  struct ak_wwise_plugin_host_data_writer_instance_v1* in_pDataWriter)
265  {
266  return (bool)static_cast<const Instance*>(in_this)->GetPluginData(
267  *in_guidPlatform,
268  in_idParam,
269  *static_cast<DataWriter*>(in_pDataWriter));
270  };
271  }
272  };
273 
274  /**
275  * \brief The C interface, fulfilled by your plug-in.
276  */
277  InterfacePtr GetInterfacePointer() {
278  static Interface g_interface;
279  return &g_interface;
280  }
281  CCustomData::Instance* GetInstancePointer() {
282  return this;
283  }
284  const CCustomData::Instance* GetInstancePointer() const {
285  return this;
286  }
287 
288  CustomData() :
289  CCustomData::Instance()
290  {
291  }
292 
293  virtual ~CustomData() {}
294 
295  /**
296  * \brief Initializes the plug-in's custom data to its default values.
297  *
298  * This method is mutually exclusive with the other Init methods.
299  */
300  virtual void InitToDefault() { }
301 
302  /**
303  * \brief Copy the plug-in's custom data from another instance of the same plug-in.
304  *
305  * This is used during copy/paste and delete for Undo purposes. The properties on
306  * the PropertySet do not need to be copied in this method.
307  *
308  * This method is mutually exclusive with the other Init methods.
309  *
310  * \param[in] in_source The object that will provide the data used in initializing
311  * this instance.
312  * \return true if successful.
313  */
314  virtual bool InitFromInstance(const CustomData& in_source) { return true; }
315 
316  /**
317  * \brief Load the custom data structure from the provided Work Unit's XML.
318  *
319  * This method is mutually exclusive with the other Init methods.
320  *
321  * \aknote In order to use the in_pReader instance, your plug-in must request the XML
322  * interface: ak_wwise_plugin_host_xml_v1. \endaknote
323  *
324  * \param[in] in_reader XML Reader instance.
325  * \return true if load succeeded.
326  */
327  virtual bool InitFromWorkunit(XmlReader& in_reader) { return true; }
328 
329  /**
330  * \brief Save custom data structure in the provided XML.
331  *
332  * \aknote In order to use the in_pWriter instance, your plug-in must request the XML
333  * interface: AK::Wwise::Plugin::RequestXml. \endaknote
334  *
335  * \param[in] in_writer XML Writer instance.
336  * \return true if save succeeded.
337  */
338  virtual bool Save(XmlWriter& in_writer) { return true; }
339 
340  /**
341  * \brief OnDelete function is called when the user presses the "delete" button on a plug-in.
342  *
343  * This handler function should properly clean custom data and set undo/redo action properly
344  * to allow recreation on undo.
345  */
346  virtual void OnDelete() { }
347 
348  /**
349  * \brief Obtains parameters that will be sent to the sound engine when Wwise is connected.
350  *
351  * This block should contain only data that is NOT a property defined in the plug-in xml file. The
352  * parameter ID should be different than the ones used in the plug-in xml.
353  *
354  * This is used when there are Object Store, large binary data sections, or properties not usually
355  * residing in the XML. \sa \ref AudioPlugin::GetBankParameters "GetBankParameters"
356  * for a discussion on parameter passing to the Sound Engine.
357  *
358  * \aknote In order to use the in_pDataWriter instance, your plug-in must request the data writer
359  * interface: AK::Wwise::Plugin::RequestWrite. \endaknote
360  *
361  * \param[in] in_guidPlatform The unique ID of the queried platform
362  * \param[in] in_idParam The plug-in defined parameter ID
363  * \param[in] in_dataWriter A pointer to the data writer instance being used.
364  * \return true if the plug-in has some plug-in defined data.
365  *
366  * \sa
367  * - \ref AK::Wwise::Plugin::Host::NotifyInternalDataChanged
368  * - \ref AK::IAkPluginParam::ALL_PLUGIN_DATA_ID
369  * - \ref AK::IAkPluginParam::SetParam
370  */
371  virtual bool GetPluginData(
372  const GUID& in_guidPlatform,
373  AkPluginParamID in_idParam,
374  DataWriter& in_dataWriter
375  ) const { return false; }
376  };
377  } // of namespace V1
378 
379  /// Latest version of the C CustomData interface.
380  using CCustomData = V1::CCustomData;
381  /// Latest version of the C++ CustomData interface.
382  using CustomData = V1::CustomData;
383 
384  AK_WWISE_PLUGIN_SPECIALIZE_INTERFACE_CLASS(CustomData);
385  AK_WWISE_PLUGIN_SPECIALIZE_INTERFACE_VERSION(CustomData);
386 } // of namespace AK::Wwise::Plugin
387 
388 #endif
AK.Wwise::Plugin::CustomData
V1::CustomData CustomData
Latest version of the C++ CustomData interface.
Definition: CustomData.h:382
AK.Wwise::Plugin::V1::DataWriter
Interface used to write data during sound bank generation.
Definition: HostDataWriter.h:245
AK.Wwise::Plugin::V1::CustomData
Backend API to load and save custom data in XML format.
Definition: CustomData.h:196
HostDataWriter.h
Wwise Authoring Plug-ins - API to write data that can be converted for the target platform.
ak_wwise_plugin_custom_data_v1::InitFromInstance
bool(* InitFromInstance)(struct ak_wwise_plugin_custom_data_instance_v1 *in_this, const struct ak_wwise_plugin_custom_data_instance_v1 *in_source)
Copy the plug-in's custom data from another instance of the same plug-in.
Definition: CustomData.h:91
AK.Wwise::Plugin::V1::CustomData::InitFromWorkunit
virtual bool InitFromWorkunit(XmlReader &in_reader)
Load the custom data structure from the provided Work Unit's XML.
Definition: CustomData.h:327
ak_wwise_plugin_custom_data_v1::OnDelete
void(* OnDelete)(struct ak_wwise_plugin_custom_data_instance_v1 *in_this)
OnDelete function is called when the user presses the "delete" button on a plug-in.
Definition: CustomData.h:133
AK.Wwise::Plugin::InterfaceVersion
decltype(BaseInterface::m_version) InterfaceVersion
PluginInfoGenerator: Type for the m_version value in BaseInterface.
Definition: PluginInfoGenerator.h:50
ak_wwise_plugin_custom_data_instance_v1
Base instance type for providing custom data loading and saving through ak_wwise_plugin_custom_data_v...
Definition: PluginDef.h:713
ak_wwise_plugin_custom_data_v1::InitFromWorkunit
bool(* InitFromWorkunit)(struct ak_wwise_plugin_custom_data_instance_v1 *in_this, struct ak_wwise_plugin_host_xml_reader_instance_v1 *in_pReader)
Load the custom data structure from the provided Work Unit's XML.
Definition: CustomData.h:107
AK.Wwise::Plugin::V1::CustomData::GetInterfacePointer
InterfacePtr GetInterfacePointer()
The C interface, fulfilled by your plug-in.
Definition: CustomData.h:277
AK.Wwise::Plugin::V1::CustomData::GetInstancePointer
CCustomData::Instance * GetInstancePointer()
Definition: CustomData.h:281
AK.Wwise::Plugin::V1::CustomData::InitFromInstance
virtual bool InitFromInstance(const CustomData &in_source)
Copy the plug-in's custom data from another instance of the same plug-in.
Definition: CustomData.h:314
AK.Wwise::Plugin::V1::CustomData::InitToDefault
virtual void InitToDefault()
Initializes the plug-in's custom data to its default values.
Definition: CustomData.h:300
ak_wwise_plugin_host_data_writer_instance_v1
Base host-provided instance type for ak_wwise_plugin_host_data_writer_v1.
Definition: PluginDef.h:618
AK.Wwise::Plugin::V1::CustomData::k_interfaceVersion
@ k_interfaceVersion
The interface version, as provided by this plug-in.
Definition: CustomData.h:221
ak_wwise_plugin_custom_data_v1::GetPluginData
bool(* GetPluginData)(const struct ak_wwise_plugin_custom_data_instance_v1 *in_this, const GUID *in_guidPlatform, AkPluginParamID in_idParam, struct ak_wwise_plugin_host_data_writer_instance_v1 *in_pDataWriter)
Obtains parameters that will be sent to the sound engine when Wwise is connected.
Definition: CustomData.h:159
AK.Wwise::Plugin::V1::CustomData::Save
virtual bool Save(XmlWriter &in_writer)
Save custom data structure in the provided XML.
Definition: CustomData.h:338
AK.Wwise::Plugin::InterfacePtr
CInterfacePtr InterfacePtr
Definition: PluginDef.h:980
ak_wwise_plugin_custom_data_v1::Save
bool(* Save)(struct ak_wwise_plugin_custom_data_instance_v1 *in_this, struct ak_wwise_plugin_host_xml_writer_instance_v1 *in_pWriter)
Save custom data structure in the provided Work Unit's XML.
Definition: CustomData.h:121
ak_wwise_plugin_custom_data_v1::ak_wwise_plugin_custom_data_v1
ak_wwise_plugin_custom_data_v1()
Definition: CustomData.h:63
AK.Wwise::Plugin::V1::CustomData::GetPluginData
virtual bool GetPluginData(const GUID &in_guidPlatform, AkPluginParamID in_idParam, DataWriter &in_dataWriter) const
Obtains parameters that will be sent to the sound engine when Wwise is connected.
Definition: CustomData.h:371
AK.Wwise::Plugin::V1::XmlReader
API interface for XML-based plug-in persistence.
Definition: HostXml.h:530
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_custom_data_v1::Instance
ak_wwise_plugin_custom_data_instance_v1 Instance
Base instance type for providing custom data loading and saving.
Definition: CustomData.h:61
ak_wwise_plugin_custom_data_v1::InitToDefault
void(* InitToDefault)(struct ak_wwise_plugin_custom_data_instance_v1 *in_this)
Initializes the plug-in's custom data to its default values.
Definition: CustomData.h:75
AK.Wwise::Plugin::AK_WWISE_PLUGIN_SPECIALIZE_INTERFACE_VERSION
AK_WWISE_PLUGIN_SPECIALIZE_INTERFACE_VERSION(AudioPlugin)
HostXml.h
Wwise Authoring Plug-ins - API for XML-based persistence, as used in CustomData.
ak_wwise_plugin_base_interface
Interface description and base class for every Wwise Authoring plug-in interface.
Definition: PluginBaseInterface.h:120
ak_wwise_plugin_host_xml_reader_instance_v1
Base host-provided instance type for reading XML files through ak_wwise_plugin_host_xml_v1.
Definition: PluginDef.h:663
AK_WWISE_PLUGIN_INTERFACE_TYPE_CUSTOM_DATA
@ AK_WWISE_PLUGIN_INTERFACE_TYPE_CUSTOM_DATA
2021.1 Custom Data reader backend part. ak_wwise_plugin_custom_data_v1
Definition: PluginBaseInterface.h:58
AkPluginParamID
AkInt16 AkPluginParamID
Source or effect plug-in parameter ID.
Definition: AkTypes.h:128
AK.Wwise::Plugin::V1::CCustomData
ak_wwise_plugin_custom_data_v1 CCustomData
Definition: CustomData.h:179
AK.Wwise::Plugin::V1::XmlWriter
API interface for XML-based plug-in persistence.
Definition: HostXml.h:756
ak_wwise_plugin_host_xml_writer_instance_v1
Base host-provided instance type for writing XML files through ak_wwise_plugin_host_xml_v1.
Definition: PluginDef.h:672
ak_wwise_plugin_custom_data_v1
Backend API to load and save custom data in XML format.
Definition: CustomData.h:54
AK.Wwise::Plugin::V1::CustomData::OnDelete
virtual void OnDelete()
OnDelete function is called when the user presses the "delete" button on a plug-in.
Definition: CustomData.h:346
AK.Wwise::Plugin::V1::CustomData::GetInstancePointer
const CCustomData::Instance * GetInstancePointer() const
Definition: CustomData.h:284
AK.Wwise::Plugin::AK_WWISE_PLUGIN_SPECIALIZE_INTERFACE_CLASS
AK_WWISE_PLUGIN_SPECIALIZE_INTERFACE_CLASS(AudioPlugin)
AK.Wwise::Plugin::V1::CustomData::k_interfaceType
@ k_interfaceType
The interface type, as provided by this plug-in.
Definition: CustomData.h:211
GUID
Definition: PluginHelpers.h:45

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