Version
menu_open
Wwise SDK 2023.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) 2024 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  */
51 #ifdef __cplusplus
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.
62 
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)(
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  */
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  */
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)(
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  */
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  */
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  {
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  */
196  {
197  public:
198  /**
199  * \copydoc CCustomData::Instance
200  */
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  */
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  */
222  };
223 
224  struct Interface : public CCustomData
225  {
228  {
231  {
232  static_cast<Instance*>(in_this)->InitToDefault();
233  };
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  };
244  {
245  return (bool)static_cast<Instance*>(in_this)->InitFromWorkunit(
246  *static_cast<XmlReader*>(in_pReader));
247  };
248  CCustomData::Save = [](
251  {
252  return (bool)static_cast<Instance*>(in_this)->Save(
253  *static_cast<XmlWriter*>(in_pWriter));
254  };
257  {
258  static_cast<Instance*>(in_this)->OnDelete();
259  };
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  */
278  static Interface g_interface;
279  return &g_interface;
280  }
282  return this;
283  }
285  return this;
286  }
287 
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.
381  /// Latest version of the C++ CustomData interface.
383 
386 } // of namespace AK::Wwise::Plugin
387 
388 #endif
V1::CustomData CustomData
Latest version of the C++ CustomData interface.
Definition: CustomData.h:382
Interface used to write data during sound bank generation.
Backend API to load and save custom data in XML format.
Definition: CustomData.h:196
Wwise Authoring Plug-ins - API to write data that can be converted for the target platform.
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
virtual bool InitFromWorkunit(XmlReader &in_reader)
Load the custom data structure from the provided Work Unit's XML.
Definition: CustomData.h:327
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
decltype(BaseInterface::m_version) InterfaceVersion
PluginInfoGenerator: Type for the m_version value in BaseInterface.
Base instance type for providing custom data loading and saving through ak_wwise_plugin_custom_data_v...
Definition: PluginDef.h:728
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
InterfacePtr GetInterfacePointer()
The C interface, fulfilled by your plug-in.
Definition: CustomData.h:277
CCustomData::Instance * GetInstancePointer()
Definition: CustomData.h:281
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
virtual void InitToDefault()
Initializes the plug-in's custom data to its default values.
Definition: CustomData.h:300
Base host-provided instance type for ak_wwise_plugin_host_data_writer_v1.
Definition: PluginDef.h:633
@ k_interfaceVersion
The interface version, as provided by this plug-in.
Definition: CustomData.h:221
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
virtual bool Save(XmlWriter &in_writer)
Save custom data structure in the provided XML.
Definition: CustomData.h:338
CInterfacePtr InterfacePtr
Definition: PluginDef.h:995
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
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
API interface for XML-based plug-in persistence.
Definition: HostXml.h:530
std::underlying_type< InterfaceType >::type InterfaceTypeValue
PluginInfoGenerator: Underlying storage type for the m_interface value in BaseInterface.
ak_wwise_plugin_custom_data_instance_v1 Instance
Base instance type for providing custom data loading and saving.
Definition: CustomData.h:61
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_SPECIALIZE_INTERFACE_VERSION(AudioPlugin)
Wwise Authoring Plug-ins - API for XML-based persistence, as used in CustomData.
Interface description and base class for every Wwise Authoring plug-in interface.
Base host-provided instance type for reading XML files through ak_wwise_plugin_host_xml_v1.
Definition: PluginDef.h:678
@ AK_WWISE_PLUGIN_INTERFACE_TYPE_CUSTOM_DATA
2021.1 Custom Data reader backend part. ak_wwise_plugin_custom_data_v1
AkInt16 AkPluginParamID
Source or effect plug-in parameter ID.
Definition: AkTypes.h:66
ak_wwise_plugin_custom_data_v1 CCustomData
Definition: CustomData.h:179
API interface for XML-based plug-in persistence.
Definition: HostXml.h:756
Base host-provided instance type for writing XML files through ak_wwise_plugin_host_xml_v1.
Definition: PluginDef.h:687
Backend API to load and save custom data in XML format.
Definition: CustomData.h:54
virtual void OnDelete()
OnDelete function is called when the user presses the "delete" button on a plug-in.
Definition: CustomData.h:346
const CCustomData::Instance * GetInstancePointer() const
Definition: CustomData.h:284
AK_WWISE_PLUGIN_SPECIALIZE_INTERFACE_CLASS(AudioPlugin)
@ k_interfaceType
The interface type, as provided by this plug-in.
Definition: CustomData.h:211

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