Version
menu_open
Wwise SDK 2021.1.14
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.14 Build: 6590
25  Copyright (c) 2006-2023 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  */
51 struct ak_wwise_plugin_custom_data_v1
52 #ifdef __cplusplus
53  : public ak_wwise_plugin_base_interface
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.
62  using Instance = ak_wwise_plugin_custom_data_instance_v1;
63 
64  ak_wwise_plugin_custom_data_v1() :
65  ak_wwise_plugin_base_interface(AK_WWISE_PLUGIN_INTERFACE_TYPE_CUSTOM_DATA, 1)
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)(
77  struct ak_wwise_plugin_custom_data_instance_v1* in_this);
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  */
92  bool(*InitFromInstance)(
93  struct ak_wwise_plugin_custom_data_instance_v1* in_this,
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  */
108  bool(*InitFromWorkunit)(
109  struct ak_wwise_plugin_custom_data_instance_v1* in_this,
110  struct ak_wwise_plugin_host_xml_reader_instance_v1* in_pReader);
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)(
123  struct ak_wwise_plugin_custom_data_instance_v1* in_this,
124  struct ak_wwise_plugin_host_xml_writer_instance_v1* in_pWriter);
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  */
134  void(*OnDelete)(struct ak_wwise_plugin_custom_data_instance_v1* in_this);
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  */
160  bool(*GetPluginData)(
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  {
180  using CCustomData = ak_wwise_plugin_custom_data_v1;
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  */
195  class CustomData : public CCustomData::Instance,
196  public AK::Wwise::Plugin::RequestXml
197  {
198  public:
199  /**
200  * \copydoc CCustomData::Instance
201  */
202  using Instance = CCustomData::Instance;
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  */
212  k_interfaceType = AK_WWISE_PLUGIN_INTERFACE_TYPE_CUSTOM_DATA
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  */
222  k_interfaceVersion = 1
223  };
224 
225  struct Interface : public CCustomData
226  {
227  using Instance = CustomData;
228  Interface()
229  {
230  CCustomData::InitToDefault = [](
231  struct ak_wwise_plugin_custom_data_instance_v1* in_this)
232  {
233  static_cast<Instance*>(in_this)->InitToDefault();
234  };
235  CCustomData::InitFromInstance = [](
236  struct ak_wwise_plugin_custom_data_instance_v1* in_this,
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  };
242  CCustomData::InitFromWorkunit = [](
243  struct ak_wwise_plugin_custom_data_instance_v1* in_this,
244  struct ak_wwise_plugin_host_xml_reader_instance_v1* in_pReader)
245  {
246  return (bool)static_cast<Instance*>(in_this)->InitFromWorkunit(
247  *static_cast<XmlReader*>(in_pReader));
248  };
249  CCustomData::Save = [](
250  struct ak_wwise_plugin_custom_data_instance_v1* in_this,
251  struct ak_wwise_plugin_host_xml_writer_instance_v1* in_pWriter)
252  {
253  return (bool)static_cast<Instance*>(in_this)->Save(
254  *static_cast<XmlWriter*>(in_pWriter));
255  };
256  CCustomData::OnDelete = [](
257  struct ak_wwise_plugin_custom_data_instance_v1* in_this)
258  {
259  static_cast<Instance*>(in_this)->OnDelete();
260  };
261  CCustomData::GetPluginData = [](
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  */
278  InterfacePtr GetInterfacePointer() {
279  static Interface g_interface;
280  return &g_interface;
281  }
282  CCustomData::Instance* GetInstancePointer() {
283  return this;
284  }
285  const CCustomData::Instance* GetInstancePointer() const {
286  return this;
287  }
288 
289  CustomData() :
290  CCustomData::Instance()
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.
381  using CCustomData = V1::CCustomData;
382  /// Latest version of the C++ CustomData interface.
383  using CustomData = V1::CustomData;
384 
385  AK_WWISE_PLUGIN_SPECIALIZE_INTERFACE_CLASS(CustomData);
386  AK_WWISE_PLUGIN_SPECIALIZE_INTERFACE_VERSION(CustomData);
387 } // of namespace AK::Wwise::Plugin
388 
389 #endif
AK.Wwise::Plugin::CustomData
V1::CustomData CustomData
Latest version of the C++ CustomData interface.
Definition: CustomData.h:383
AK.Wwise::Plugin::V1::DataWriter
Interface used to write data during sound bank generation.
Definition: HostDataWriter.h:246
AK.Wwise::Plugin::V1::CustomData
Backend API to load and save custom data in XML format.
Definition: CustomData.h:197
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:92
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:328
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:134
AK.Wwise::Plugin::InterfaceVersion
decltype(BaseInterface::m_version) InterfaceVersion
PluginInfoGenerator: Type for the m_version value in BaseInterface.
Definition: PluginInfoGenerator.h:51
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:712
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:108
AK.Wwise::Plugin::V1::CustomData::GetInterfacePointer
InterfacePtr GetInterfacePointer()
The C interface, fulfilled by your plug-in.
Definition: CustomData.h:278
AK.Wwise::Plugin::V1::CustomData::GetInstancePointer
CCustomData::Instance * GetInstancePointer()
Definition: CustomData.h:282
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:315
AK.Wwise::Plugin::V1::CustomData::InitToDefault
virtual void InitToDefault()
Initializes the plug-in's custom data to its default values.
Definition: CustomData.h:301
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::V1::CustomData::k_interfaceVersion
@ k_interfaceVersion
The interface version, as provided by this plug-in.
Definition: CustomData.h:222
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:160
AK.Wwise::Plugin::V1::CustomData::Save
virtual bool Save(XmlWriter &in_writer)
Save custom data structure in the provided XML.
Definition: CustomData.h:339
AK.Wwise::Plugin::InterfacePtr
CInterfacePtr InterfacePtr
Definition: PluginDef.h:968
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:122
ak_wwise_plugin_custom_data_v1::ak_wwise_plugin_custom_data_v1
ak_wwise_plugin_custom_data_v1()
Definition: CustomData.h:64
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:372
AK.Wwise::Plugin::V1::XmlReader
API interface for XML-based plug-in persistence.
Definition: HostXml.h:531
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_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:62
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:76
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:117
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:662
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:59
AkPluginParamID
AkInt16 AkPluginParamID
Source or effect plug-in parameter ID.
Definition: AkTypes.h:76
AK.Wwise::Plugin::V1::CCustomData
ak_wwise_plugin_custom_data_v1 CCustomData
Definition: CustomData.h:180
AK.Wwise::Plugin::V1::XmlWriter
API interface for XML-based plug-in persistence.
Definition: HostXml.h:757
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:671
ak_wwise_plugin_custom_data_v1
Backend API to load and save custom data in XML format.
Definition: CustomData.h:55
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:347
AK.Wwise::Plugin::V1::CustomData::GetInstancePointer
const CCustomData::Instance * GetInstancePointer() const
Definition: CustomData.h:285
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:212
GUID
Definition: PluginHelpers.h:46

Cette page a-t-elle été utile ?

Besoin d'aide ?

Des questions ? Des problèmes ? Besoin de plus d'informations ? Contactez-nous, nous pouvons vous aider !

Visitez notre page d'Aide

Décrivez-nous de votre projet. Nous sommes là pour vous aider.

Enregistrez votre projet et nous vous aiderons à démarrer sans aucune obligation !

Partir du bon pied avec Wwise