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