Version
menu_open
link
Wwise SDK 2022.1.9
PluginLinks.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 - Provides links to the related backend and frontend instances.
29  * \file AK/Wwise/Plugin/PluginLinks.h
30  */
31 
32 #pragma once
33 
34 #include "PluginInfoGenerator.h"
35 
36 /**
37  * \brief Host API to retrieve a link to the plug-in's backend instance.
38  *
39  * Useful for the Frontend (GUI) when a special function must be called to get a value, or update elements.
40  */
41 struct ak_wwise_plugin_link_backend_v1
42 #ifdef __cplusplus
43  : public ak_wwise_plugin_base_interface
44 #endif
45 {
46 #ifndef __cplusplus
47  ak_wwise_plugin_base_interface m_baseInterface;
48 #endif
49 
50 #ifdef __cplusplus
51  /// Base host-provided instance to retrieve the related backend instance, as shown in the frontend.
52  using Instance = ak_wwise_plugin_link_backend_instance_v1;
53  ak_wwise_plugin_link_backend_v1() :
54  ak_wwise_plugin_base_interface(AK_WWISE_PLUGIN_INTERFACE_TYPE_LINK_BACKEND, 1)
55  {}
56 #endif
57 
58  /**
59  * \brief Retrieves a link to the plug-in's backend instance.
60  *
61  * \aknote The returned pointer might be modified in the frontend lifetime. For example, a plug-in that would undo
62  * and redo a plug-in creation might return a different value. As such, you should not store the backend
63  * pointer in a class member, but query it at every operation. \endaknote
64  *
65  * \param[in] in_this Current instance of this interface.
66  * \return Base pointer of the backend instance.
67  */
68  ak_wwise_plugin_backend_instance* (*Get)(
69  const ak_wwise_plugin_link_backend_instance_v1* in_this
70  );
71 };
72 
73 /**
74  * \brief Host API to retrieve a link to the plug-in's frontend interfaces.
75  *
76  * Useful for the Backend when there are special properties that don't use property sets.
77  */
78 struct ak_wwise_plugin_link_frontend_v1
79 #ifdef __cplusplus
80  : public ak_wwise_plugin_base_interface
81 #endif
82 {
83 #ifndef __cplusplus
84  ak_wwise_plugin_base_interface m_baseInterface;
85 #endif
86 
87 #ifdef __cplusplus
88  /// Base host-provided instance to retrieve the related frontend instances related to the current backend.
89  using Instance = ak_wwise_plugin_link_frontend_instance_v1;
90  ak_wwise_plugin_link_frontend_v1() :
91  ak_wwise_plugin_base_interface(AK_WWISE_PLUGIN_INTERFACE_TYPE_LINK_FRONTEND, 1)
92  {}
93 #endif
94 
95  /**
96  * \brief Retrieves an array of the plug-in's frontend instances.
97  *
98  * \aknote The returned array is a temporary TLS pointer that is meant to be retrieved and processed immediately to
99  * execute commands. You should not store this data. \endaknote
100  *
101  * \param[in] in_this Current instance of this interface.
102  * \param[out] out_count How many frontend instances are in the array.
103  * \return Temporary pointer to the array of frontend instances.
104  */
105  ak_wwise_plugin_frontend_instance** (*GetArray)(
106  const ak_wwise_plugin_link_frontend_instance_v1* in_this,
107  int* out_count
108  );
109 };
110 
111 #define AK_WWISE_PLUGIN_LINK_BACKEND_ID() \
112  AK_WWISE_PLUGIN_BASE_INTERFACE_FROM_ID(AK_WWISE_PLUGIN_INTERFACE_TYPE_LINK_BACKEND, 1)
113 #define AK_WWISE_PLUGIN_LINK_BACKEND_CTOR(/* ak_wwise_plugin_info* */ in_pluginInfo, /* void* */ in_data) \
114 { \
115  .m_baseInterface = AK_WWISE_PLUGIN_BASE_INTERFACE_CTOR(AK_WWISE_PLUGIN_LINK_BACKEND_ID(), in_pluginInfo, in_data) \
116 }
117 
118 #define AK_WWISE_PLUGIN_LINK_FRONTEND_ID() \
119  AK_WWISE_PLUGIN_BASE_INTERFACE_FROM_ID(AK_WWISE_PLUGIN_INTERFACE_TYPE_LINK_FRONTEND, 1)
120 #define AK_WWISE_PLUGIN_LINK_FRONTEND_CTOR(/* ak_wwise_plugin_info* */ in_pluginInfo, /* void* */ in_data) \
121 { \
122  .m_baseInterface = AK_WWISE_PLUGIN_BASE_INTERFACE_CTOR(AK_WWISE_PLUGIN_LINK_FRONTEND_ID(), in_pluginInfo, in_data) \
123 }
124 
125 
126 #ifdef __cplusplus
127 namespace AK::Wwise::Plugin
128 {
129  namespace V1
130  {
131  using CLinkBackend = ak_wwise_plugin_link_backend_v1;
132  using CLinkFrontend = ak_wwise_plugin_link_frontend_v1;
133 
134  /// \copydoc ak_wwise_plugin_link_backend_v1
135  class LinkBackend : public CBaseInstanceGlue<CLinkBackend>
136  {
137  public:
138  using Interface = CLinkBackend;
139  using Instance = CLinkBackend::Instance;
140 
141  /**
142  * \brief The interface type, as requested by this plug-in.
143  */
144  enum : InterfaceTypeValue
145  {
146  /**
147  * \brief The interface type, as requested by this plug-in.
148  */
149  k_interfaceType = AK_WWISE_PLUGIN_INTERFACE_TYPE_LINK_BACKEND
150  };
151  /**
152  * \brief The interface version, as requested by this plug-in.
153  */
154  enum : InterfaceVersion
155  {
156  /**
157  * \brief The interface version, as requested by this plug-in.
158  */
159  k_interfaceVersion = 1
160  };
161 
162  /**
163  * \brief Retrieves a link to the plug-in's backend instance.
164  *
165  * \aknote The returned pointer might be modified in the frontend lifetime. For example, a plug-in that would undo
166  * and redo a plug-in creation might return a different value. As such, you should not store the backend
167  * pointer in a class member, but query it at every operation. \endaknote
168  *
169  * \return Base pointer of the backend instance.
170  */
171  inline ak_wwise_plugin_backend_instance* Get() const
172  {
173  return g_cinterface->Get(this);
174  }
175 
176  /**
177  * \brief Retrieves a link to the plug-in's backend instance, casted as your C++ Backend class type.
178  *
179  * \aknote The returned pointer might be modified in the frontend lifetime. For example, a plug-in that would undo
180  * and redo a plug-in creation might return a different value. As such, you should not store the backend
181  * pointer in a class member, but query it at every operation. \endaknote
182  *
183  * \tparam Backend Expected type of the backend instance. An unexpected type yields to an undefined result.
184  * \return Pointer of the backend class instance.
185  */
186  template<typename Backend>
187  inline Backend* As()
188  {
189  return static_cast<Backend*>(Get());
190  }
191  };
192 
193  /// \copydoc ak_wwise_plugin_link_frontend_v1
194  class LinkFrontend : public CBaseInstanceGlue<CLinkFrontend>
195  {
196  public:
197  using Interface = CLinkFrontend;
198  using Instance = CLinkFrontend::Instance;
199 
200  /**
201  * \brief The interface type, as requested by this plug-in.
202  */
203  enum : InterfaceTypeValue
204  {
205  /**
206  * \brief The interface type, as requested by this plug-in.
207  */
208  k_interfaceType = AK_WWISE_PLUGIN_INTERFACE_TYPE_LINK_FRONTEND
209  };
210  /**
211  * \brief The interface version, as requested by this plug-in.
212  */
213  enum : InterfaceVersion
214  {
215  /**
216  * \brief The interface version, as requested by this plug-in.
217  */
218  k_interfaceVersion = 1
219  };
220 
221  /**
222  * \brief Retrieves an array of the plug-in's frontend instances.
223  *
224  * \aknote The returned array is a temporary TLS pointer that is meant to be retrieved and processed immediately to
225  * execute commands. You should not store this data. \endaknote
226  *
227  * \param[out] out_count How many frontend instances are in the array.
228  * \return Temporary pointer to the array of frontend instances.
229  */
230  inline ak_wwise_plugin_frontend_instance** GetArray(int* out_count) const
231  {
232  return g_cinterface->GetArray(this, out_count);
233  }
234 
235  /**
236  * \brief Applies a function on each plug-in's frontend instances.
237  *
238  * \aknote The frontend instances passed to the function are temporary TLS pointers that are meant to be retrieved
239  * and processed immediately to execute commands. You should not store this data. \endaknote
240  *
241  * \tparam Frontend Expected type of the frontend instances (optional). If no explicit type is provided, the caller
242  * needs to manually perform the cast to the expected frontend instance type. If an explicit type is
243  * provided, the frontend instances will automatically be casted to the provided type and then forwarded
244  * to in_operation if the cast was successful.
245  * \param[in] in_operation Function, functor or lambda taking a pointer of Frontend as parameter.
246  */
247  template<typename Frontend = ak_wwise_plugin_frontend_instance, typename Functor>
248  inline void ForEach(Functor in_operation) const
249  {
250  int count = 0;
251  auto frontends = GetArray(&count);
252  for (int index = 0; index < count; ++index)
253  {
254  if constexpr (std::is_same_v<Frontend, ak_wwise_plugin_frontend_instance>)
255  {
256  in_operation(frontends[index]);
257  }
258  else if (auto* frontend = dynamic_cast<Frontend*>(frontends[index]))
259  {
260  in_operation(frontend);
261  }
262  }
263  }
264  };
265 
266  using RequestLinkBackend = RequestedHostInterface<LinkBackend>;
267  using RequestLinkFrontend = RequestedHostInterface<LinkFrontend>;
268 
269  } // of namespace V1
270 
271  /// Latest version of the C LinkBackend interface.
272  using CLinkBackend = V1::CLinkBackend;
273  /// Latest version of the C++ LinkBackend interface.
274  using LinkBackend = V1::LinkBackend;
275  /// Latest version of the requested C++ LinkBackend interface.
276  using RequestLinkBackend = V1::RequestLinkBackend;
277 
278  /// Latest version of the C LinkFrontend interface.
279  using CLinkFrontend = V1::CLinkFrontend;
280  /// Latest version of the C++ LinkFrontend interface.
281  using LinkFrontend = V1::LinkFrontend;
282  /// Latest version of the requested C++ LinkFrontend interface.
283  using RequestLinkFrontend = V1::RequestLinkFrontend;
284 
285  AK_WWISE_PLUGIN_SPECIALIZE_HOST_INTERFACE(LinkBackend, backend);
286  AK_WWISE_PLUGIN_SPECIALIZE_HOST_INTERFACE(LinkFrontend, frontend);
287 
288  AK_WWISE_PLUGIN_SPECIALIZE_INTERFACE_CLASS(LinkBackend);
289  AK_WWISE_PLUGIN_SPECIALIZE_INTERFACE_VERSION(LinkBackend);
290 
291  AK_WWISE_PLUGIN_SPECIALIZE_INTERFACE_CLASS(LinkFrontend);
292  AK_WWISE_PLUGIN_SPECIALIZE_INTERFACE_VERSION(LinkFrontend);
293 } // of namespace AK::Wwise::Plugin
294 
295 #endif
ak_wwise_plugin_link_frontend_v1::GetArray
ak_wwise_plugin_frontend_instance **(* GetArray)(const ak_wwise_plugin_link_frontend_instance_v1 *in_this, int *out_count)
Retrieves an array of the plug-in's frontend instances.
Definition: PluginLinks.h:105
ak_wwise_plugin_frontend_instance
Plug-in frontend instance.
Definition: PluginDef.h:550
AK.Wwise::Plugin::LinkBackend
V1::LinkBackend LinkBackend
Latest version of the C++ LinkBackend interface.
Definition: PluginLinks.h:274
AK.Wwise::Plugin::V1::CLinkFrontend
ak_wwise_plugin_link_frontend_v1 CLinkFrontend
Definition: PluginLinks.h:132
AK.Wwise::Plugin::CBaseInterfaceGlue< CLinkBackend >::g_cinterface
static GluedInterface * g_cinterface
The unique instance of the CInterface interface. Defined at nullptr first, overridden by the Host onc...
Definition: PluginInfoGenerator.h:89
ak_wwise_plugin_link_backend_v1::ak_wwise_plugin_link_backend_v1
ak_wwise_plugin_link_backend_v1()
Definition: PluginLinks.h:53
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_link_frontend_v1::ak_wwise_plugin_link_frontend_v1
ak_wwise_plugin_link_frontend_v1()
Definition: PluginLinks.h:90
ak_wwise_plugin_link_backend_instance_v1
Base host-provided instance to retrieve the related backend instance, as shown in the frontend.
Definition: PluginDef.h:767
PluginInfoGenerator.h
Wwise Authoring Plug-ins - C++ class helper to automatically determine the plug-in interfaces used in...
AK.Wwise::Plugin::CBaseInstanceGlue
PluginInfoGenerator: Associates an existing C Interface with a variable that can be used....
Definition: PluginInfoGenerator.h:104
ak_wwise_plugin_backend_instance
Plug-in backend instance.
Definition: PluginDef.h:535
AK.Wwise::Plugin::V1::RequestLinkFrontend
RequestedHostInterface< LinkFrontend > RequestLinkFrontend
Definition: PluginLinks.h:267
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::V1::Frontend
Frontend plug-in API for Audio plug-ins.
Definition: Frontend.h:80
ak_wwise_plugin_link_backend_v1::Get
ak_wwise_plugin_backend_instance *(* Get)(const ak_wwise_plugin_link_backend_instance_v1 *in_this)
Retrieves a link to the plug-in's backend instance.
Definition: PluginLinks.h:68
AK.Wwise::Plugin::V1::CLinkBackend
ak_wwise_plugin_link_backend_v1 CLinkBackend
Definition: PluginLinks.h:131
AK.Wwise::Plugin::AK_WWISE_PLUGIN_SPECIALIZE_INTERFACE_VERSION
AK_WWISE_PLUGIN_SPECIALIZE_INTERFACE_VERSION(AudioPlugin)
ak_wwise_plugin_link_frontend_v1
Host API to retrieve a link to the plug-in's frontend interfaces.
Definition: PluginLinks.h:82
ak_wwise_plugin_link_backend_v1
Host API to retrieve a link to the plug-in's backend instance.
Definition: PluginLinks.h:45
ak_wwise_plugin_link_frontend_instance_v1
Base host-provided instance to retrieve the related frontend instances related to the current backend...
Definition: PluginDef.h:777
ak_wwise_plugin_base_interface
Interface description and base class for every Wwise Authoring plug-in interface.
Definition: PluginBaseInterface.h:120
ak_wwise_plugin_link_frontend_v1::Instance
ak_wwise_plugin_link_frontend_instance_v1 Instance
Base host-provided instance to retrieve the related frontend instances related to the current backend...
Definition: PluginLinks.h:89
AK.Wwise::Plugin::LinkFrontend
V1::LinkFrontend LinkFrontend
Latest version of the C++ LinkFrontend interface.
Definition: PluginLinks.h:281
AK_WWISE_PLUGIN_SPECIALIZE_HOST_INTERFACE
#define AK_WWISE_PLUGIN_SPECIALIZE_HOST_INTERFACE(in_name, in_varname,...)
PluginInfoGenerator: Creates a C++ host specialization for interface class specified in in_name,...
Definition: PluginInfoGenerator.h:237
ak_wwise_plugin_link_backend_v1::Instance
ak_wwise_plugin_link_backend_instance_v1 Instance
Base host-provided instance to retrieve the related backend instance, as shown in the frontend.
Definition: PluginLinks.h:52
AK.Wwise::Plugin::V1::RequestLinkBackend
RequestedHostInterface< LinkBackend > RequestLinkBackend
Definition: PluginLinks.h:266
AK_WWISE_PLUGIN_INTERFACE_TYPE_LINK_FRONTEND
@ AK_WWISE_PLUGIN_INTERFACE_TYPE_LINK_FRONTEND
2021.1 Link to the frontend plug-ins. ak_wwise_plugin_link_frontend_v1
Definition: PluginBaseInterface.h:86
AK.Wwise::Plugin::AK_WWISE_PLUGIN_SPECIALIZE_INTERFACE_CLASS
AK_WWISE_PLUGIN_SPECIALIZE_INTERFACE_CLASS(AudioPlugin)
AK_WWISE_PLUGIN_INTERFACE_TYPE_LINK_BACKEND
@ AK_WWISE_PLUGIN_INTERFACE_TYPE_LINK_BACKEND
2021.1 Link to the backend plug-in. ak_wwise_plugin_link_backend_v1
Definition: PluginBaseInterface.h:85

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