Version
menu_open
link
Wwise SDK 2022.1.11
Host.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 - API to request host's current state and services.
29  * \file AK/Wwise/Plugin/Host.h
30  */
31 
32 #pragma once
33 
34 #include "../PlatformID.h"
35 #include "PluginInfoGenerator.h"
36 
37 
38 /**
39  * \brief API to request host's current state and services.
40  *
41  * If requested, this contains information on the current state of the host as well as generic operations.
42  *
43  * For example, the currently selected platform, tools to post
44  * when internal plug-in data changed, or a way to make Waapi calls.
45  *
46  * In order to be reactive to host's state, you should consider implementing ak_wwise_plugin_notifications_host_v1
47  * notifications.
48  */
50 #ifdef __cplusplus
52 #endif
53 {
54 #ifndef __cplusplus
55  ak_wwise_plugin_base_interface m_baseInterface;
56 #endif
57 
58 #ifdef __cplusplus
59  /// Base host-provided instance type.
63  {}
64 #endif
65 
66  /**
67  * \brief Retrieves the current platform identifier.
68  *
69  * This can be passed to any function that has a parameter for a platform ID, such as GetValue() or
70  * SetValue(), when you want to make the call for the currently active platform.
71  *
72  * \param[in] in_this Current instance of this interface.
73  * \return The unique ID of the current platform.
74  */
76 
77  /**
78  * \brief Retrieves the current base platform identifier.
79  *
80  * \param[in] in_this Current instance of this interface.
81  * \return The unique ID of the current base platform.
82  */
84 
85  /**
86  * \brief Retrieves the requested playback base platform of the Authoring tool.
87  *
88  * \param[in] in_this Current instance of this interface.
89  * \return The unique base ID of the requested playback's platform.
90  */
92 
93  /**
94  * \brief Retrieves the requested playback platform of the Authoring tool.
95  *
96  * \param[in] in_this Current instance of this interface.
97  * \return The unique ID of the requested playback's platform.
98  */
100 
101  /**
102  * \brief Use this function to tell Wwise that something other than properties has changed within the plug-in.
103  *
104  * This will set the plugin dirty (indicating there are unsaved changes) and GetPluginData will be called when
105  * the plug-in is about to play in Wwise. This will transfer the internal data to the Sound Engine part of
106  * the plug-in.
107  *
108  * Use ALL_PLUGIN_DATA_ID to indicate that all the data has to be refreshed.
109  *
110  * \param[in] in_this Current instance of this interface.
111  * \param[in] in_idData Data needed to be updated.
112  * \param[in] in_bMakeProjectDirty Whether project needs saving.
113  */
115  struct ak_wwise_plugin_host_instance_v1* in_this,
116  AkPluginParamID in_idData,
117  bool in_bMakeProjectDirty
118  );
119 
120  /**
121  * \brief Obtain licensing status for the plug-in.
122  *
123  * Refer to \ref wwiseplugin_dll_license for more information.
124  *
125  * \param[in] in_this Current instance of this interface.
126  * \param[in] in_guidPlatform GUID of the platform.
127  * \param[out] out_eType License Type.
128  * \param[out] out_eStatus License Status.
129  * \param[out] out_uDaysToExpiry Days until license expiry.
130  */
132  const struct ak_wwise_plugin_host_instance_v1* in_this,
133  const GUID* in_guidPlatform,
136  uint32_t* out_uDaysToExpiry
137  );
138 
139  /**
140  * \brief Obtain licensing status for a plug-in-specific asset ID.
141  *
142  * Refer to \ref wwiseplugin_dll_license for more information.
143  *
144  * \param[in] in_this Current instance of this interface.
145  * \param[in] in_guidPlatform GUID of the platform.
146  * \param[in] in_uAssetID ID of the asset.
147  * \param[out] out_eType License Type.
148  * \param[out] out_eStatus License Status.
149  * \param[out] out_uDaysToExpiry Days until license expiry.
150  */
152  const struct ak_wwise_plugin_host_instance_v1* in_this,
153  const GUID* in_guidPlatform,
154  AkUInt32 in_uAssetID,
157  uint32_t* out_uDaysToExpiry
158  );
159 
160  /**
161  * \brief Find and call the specified procedure.
162  *
163  * Calls made using this function are always blocking.
164  *
165  * \param[in] in_this Current instance of this interface.
166  * \param[in] in_szUri URI of the procedure to call.
167  * \param[in] in_szArgs JSON string of arguments to pass to the procedure, or nullptr for no arguments.
168  * \param[in] in_szOptions JSON string of options to pass to the procedure, or nullptr for no options.
169  * \param[in] in_pAlloc Allocator used to allocate memory for the results or the error.
170  * \param[out] out_szResults JSON string (utf-8) containing the results, if any.
171  * \param[out] out_szError JSON string (utf-8) containing the error, if any.
172  */
173  void(*WaapiCall)(
174  const struct ak_wwise_plugin_host_v1* in_this,
175  const char* in_szUri,
176  const char* in_szArgs,
177  const char* in_szOptions,
178  AK::IAkPluginMemAlloc* in_pAlloc,
179  char** out_szResults,
180  char** out_szError
181  );
182 };
183 
184 
185 /**
186  * \brief API to receive host's update notifications.
187  */
189 #ifdef __cplusplus
191 #endif
192 {
193 #ifndef __cplusplus
194  ak_wwise_plugin_base_interface m_baseInterface;
195 #endif
196 
197 #ifdef __cplusplus
198  /// Base instance type for receiving notifications on host changes events.
200 
203  {}
204 #endif
205 
206  /**
207  * \brief Received when the current platform changes.
208  *
209  * \param[in] in_this Current instance of this interface.
210  * \param[in] in_guidCurrentPlatform The unique ID of the new platform.
211  *
212  * \sa
213  * - \ref wwiseplugin_platformchange
214  */
217  const GUID * in_guidCurrentPlatform ///< The unique ID of the new platform
218  );
219 };
220 
221 
222 #define AK_WWISE_PLUGIN_HOST_V1_ID() \
223  AK_WWISE_PLUGIN_BASE_INTERFACE_FROM_ID(AK_WWISE_PLUGIN_INTERFACE_TYPE_HOST, 1)
224 #define AK_WWISE_PLUGIN_HOST_V1_CTOR() \
225 { \
226  .m_baseInterface = AK_WWISE_PLUGIN_HOST_V1_ID() \
227 }
228 
229 #define AK_WWISE_PLUGIN_NOTIFICATIONS_HOST_V1_ID() \
230  AK_WWISE_PLUGIN_BASE_INTERFACE_FROM_ID(AK_WWISE_PLUGIN_INTERFACE_TYPE_NOTIFICATIONS_HOST, 1)
231 #define AK_WWISE_PLUGIN_NOTIFICATIONS_HOST_V1_CTOR(/* ak_wwise_plugin_info* */ in_pluginInfo, /* void* */ in_data) \
232 { \
233  .m_baseInterface = AK_WWISE_PLUGIN_BASE_INTERFACE_CTOR(AK_WWISE_PLUGIN_NOTIFICATIONS_HOST_V1_ID(), in_pluginInfo, in_data) \
234 }
235 
236 
237 #ifdef __cplusplus
238 namespace AK::Wwise::Plugin
239 {
240  namespace V1
241  {
243 
244  /// \copydoc ak_wwise_plugin_host_v1
245  class Host : public CBaseInstanceGlue<CHost>
246  {
247  public:
248  using Interface = CHost;
250 
251  /**
252  * \brief The interface type, as requested by this plug-in.
253  */
254  enum : InterfaceTypeValue
255  {
256  /**
257  * \brief The interface type, as requested by this plug-in.
258  */
260  };
261  /**
262  * \brief The interface version, as requested by this plug-in.
263  */
264  enum : InterfaceVersion
265  {
266  /**
267  * \brief The interface version, as requested by this plug-in.
268  */
270  };
271 
272  /**
273  * \brief Retrieves the current platform identifier.
274  *
275  * This can be passed to any function that has a parameter for a platform ID, such as GetValue() or
276  * SetValue(), when you want to make the call for the currently active platform.
277  *
278  * \return The unique ID of the current platform.
279  */
281 
282  /**
283  * \brief Retrieves the current base platform identifier.
284  *
285  * \return The unique ID of the current base platform.
286  */
288 
289  /**
290  * \brief Retrieves the requested playback base platform of the Authoring tool.
291  *
292  * \return The unique base ID of the requested playback's platform.
293  */
295 
296  /**
297  * \brief Retrieves the requested playback platform of the Authoring tool.
298  *
299  * \return The unique ID of the requested playback's platform.
300  */
302 
303  /**
304  * \brief Use this function to tell Wwise that something other than properties has changed within the plug-in.
305  *
306  * This will set the plugin dirty (indicating there are unsaved changes) and GetPluginData will be called when
307  * the plug-in is about to play in Wwise. This will transfer the internal data to the Sound Engine part of
308  * the plug-in.
309  *
310  * Use ALL_PLUGIN_DATA_ID to indicate that all the data has to be refreshed.
311  *
312  * \param[in] in_idData Data needed to be updated.
313  * \param[in] in_bMakeProjectDirty Whether project needs saving.
314  */
315  inline void NotifyInternalDataChanged(AkPluginParamID in_idData, bool in_bMakeProjectDirty) { g_cinterface->NotifyInternalDataChanged(this, in_idData, in_bMakeProjectDirty); }
316 
317  /**
318  * \brief Obtain licensing status for the plug-in.
319  *
320  * Refer to \ref wwiseplugin_dll_license for more information.
321  *
322  * \param[in] in_guidPlatform GUID of the platform.
323  * \param[out] out_eType License Type.
324  * \param[out] out_eStatus License Status.
325  * \param[out] out_uDaysToExpiry Days until license expiry.
326  */
327  inline void GetLicenseStatus(
328  const GUID& in_guidPlatform,
329  LicenseType& out_eType,
330  LicenseStatus& out_eStatus,
331  uint32_t& out_uDaysToExpiry
332  ) const
333  {
334  g_cinterface->GetLicenseStatus(this, &in_guidPlatform, &out_eType, &out_eStatus, &out_uDaysToExpiry);
335  }
336 
337  /**
338  * \brief Obtain licensing status for a plug-in-specific asset ID.
339  *
340  * Refer to \ref wwiseplugin_dll_license for more information.
341  *
342  * \param[in] in_guidPlatform GUID of the platform.
343  * \param[in] in_uAssetID ID of the asset.
344  * \param[out] out_eType License Type.
345  * \param[out] out_eStatus License Status.
346  * \param[out] out_uDaysToExpiry Days until license expiry.
347  */
349  const GUID& in_guidPlatform,
350  AkUInt32 in_uAssetID,
351  LicenseType& out_eType,
352  LicenseStatus& out_eStatus,
353  uint32_t& out_uDaysToExpiry
354  ) const
355  {
356  g_cinterface->GetAssetLicenseStatus(this, &in_guidPlatform, in_uAssetID, &out_eType, &out_eStatus, &out_uDaysToExpiry);
357  }
358 
359  /**
360  * \brief Find and call the specified procedure.
361  *
362  * Calls made using this function are always blocking.
363  *
364  * \param[in] in_szUri URI of the procedure to call.
365  * \param[in] in_szArgs JSON string of arguments to pass to the procedure, or nullptr for no arguments.
366  * \param[in] in_szOptions JSON string of options to pass to the procedure, or nullptr for no options.
367  * \param[in] in_alloc Allocator used to allocate memory for the results or the error.
368  * \param[out] out_szResults JSON string (utf-8) containing the results, if any.
369  * \param[out] out_szError JSON string (utf-8) containing the error, if any.
370  */
371  inline void WaapiCall(
372  const char* in_szUri,
373  const char* in_szArgs,
374  const char* in_szOptions,
375  AK::IAkPluginMemAlloc& in_alloc,
376  char*& out_szResults,
377  char*& out_szError
378  ) const
379  {
380  g_cinterface->WaapiCall(g_cinterface, in_szUri, in_szArgs, in_szOptions, &in_alloc, &out_szResults, &out_szError);
381  }
382  };
383 
384  /// Notifications namespace
385  namespace Notifications
386  {
388 
389  /// \copydoc ak_wwise_plugin_notifications_host_v1
390  class Host_ : public CHost_::Instance
391  {
392  public:
393  /**
394  * \copydoc CHost_::Instance
395  */
397 
398  /**
399  * \brief The interface type, as provided by this plug-in.
400  */
401  enum : InterfaceTypeValue
402  {
403  /**
404  * \brief The interface type, as provided by this plug-in.
405  */
407  };
408  /**
409  * \brief The interface version, as provided by this plug-in.
410  */
411  enum : InterfaceVersion
412  {
413  /**
414  * \brief The interface version, as provided by this plug-in.
415  */
417  };
418 
419  /**
420  * \brief The C interface, fulfilled by your plug-in.
421  */
422  struct Interface : public CHost_
423  {
424  using Instance = Host_;
426  {
429  const GUID * in_guidCurrentPlatform)
430  {
431  static_cast<Instance*>(in_this)->NotifyCurrentPlatformChanged(
432  *in_guidCurrentPlatform);
433  };
434  }
435  };
436 
438  static Interface g_interface;
439  return &g_interface;
440  }
442  return this;
443  }
445  return this;
446  }
447 
448  Host_() :
449  CHost_::Instance()
450  {
451  }
452 
453  virtual ~Host_() {}
454 
455  /// This function is called by Wwise when the current platform changes.
456  /// \warning This function is guaranteed to be called by a single thread at a time.
457  /// \sa
458  /// - \ref wwiseplugin_platformchange
460  const GUID & in_guidCurrentPlatform ///< The unique ID of the new platform
461  ) {}
462  };
463  } // of namespace Notifications
464 
465  /**
466  * \brief Requests a Host interface, provided as m_host variable.
467  *
468  * Deriving your plug-in class from RequestHost will automatically request both Host and
469  * Notifications::Host_ interfaces. From this point, you will be able to derive from the virtual
470  * functions as defined in Notifications::Host_, and access the host-provided functions in the
471  * \c m_host variable.
472  */
474 
475  } // of namespace V1
476 
477  /// Latest version of the C Host interface.
478  using CHost = V1::CHost;
479  /// Latest version of the C++ Host interface.
480  using Host = V1::Host;
481  /// Latest version of the requested C++ Host interface.
483 
484  namespace Notifications
485  {
486  /// Latest version of the C Host notification interface.
488  /// Latest version of the C++ Host notification interface.
490  }
491 
497 } // of namespace AK::Wwise::Plugin
498 
499 #endif
void(* GetLicenseStatus)(const struct ak_wwise_plugin_host_instance_v1 *in_this, const GUID *in_guidPlatform, AK::Wwise::Plugin::LicenseType *out_eType, AK::Wwise::Plugin::LicenseStatus *out_eStatus, uint32_t *out_uDaysToExpiry)
Obtain licensing status for the plug-in.
Definition: Host.h:131
API to receive host's update notifications.
Definition: Host.h:192
void NotifyInternalDataChanged(AkPluginParamID in_idData, bool in_bMakeProjectDirty)
Use this function to tell Wwise that something other than properties has changed within the plug-in.
Definition: Host.h:315
BasePlatformID(* GetCurrentBasePlatform)(const struct ak_wwise_plugin_host_v1 *in_this)
Retrieves the current base platform identifier.
Definition: Host.h:83
@ AK_WWISE_PLUGIN_INTERFACE_TYPE_HOST
2021.1 Host services. ak_wwise_plugin_host_v1
@ k_interfaceVersion
The interface version, as provided by this plug-in.
Definition: Host.h:416
ak_wwise_plugin_host_instance_v1 Instance
Base host-provided instance type.
Definition: Host.h:60
ak_wwise_plugin_host_v1 CHost
Definition: Host.h:242
void(* NotifyCurrentPlatformChanged)(struct ak_wwise_plugin_notifications_host_instance_v1 *in_this, const GUID *in_guidCurrentPlatform)
Received when the current platform changes.
Definition: Host.h:215
BasePlatformID GetCurrentBasePlatform() const
Retrieves the current base platform identifier.
Definition: Host.h:287
static GluedInterface * g_cinterface
The unique instance of the CInterface interface. Defined at nullptr first, overridden by the Host onc...
decltype(BaseInterface::m_version) InterfaceVersion
PluginInfoGenerator: Type for the m_version value in BaseInterface.
void(* GetAssetLicenseStatus)(const struct ak_wwise_plugin_host_instance_v1 *in_this, const GUID *in_guidPlatform, AkUInt32 in_uAssetID, AK::Wwise::Plugin::LicenseType *out_eType, AK::Wwise::Plugin::LicenseStatus *out_eStatus, uint32_t *out_uDaysToExpiry)
Obtain licensing status for a plug-in-specific asset ID.
Definition: Host.h:151
API to request host's current state and services.
Definition: Host.h:246
const CHost_::Instance * GetInstancePointer() const
Definition: Host.h:444
void(* NotifyInternalDataChanged)(struct ak_wwise_plugin_host_instance_v1 *in_this, AkPluginParamID in_idData, bool in_bMakeProjectDirty)
Use this function to tell Wwise that something other than properties has changed within the plug-in.
Definition: Host.h:114
void WaapiCall(const char *in_szUri, const char *in_szArgs, const char *in_szOptions, AK::IAkPluginMemAlloc &in_alloc, char *&out_szResults, char *&out_szError) const
Find and call the specified procedure.
Definition: Host.h:371
@ AK_WWISE_PLUGIN_INTERFACE_TYPE_NOTIFICATIONS_HOST
2021.1 Host modification notification. ak_wwise_plugin_notifications_host_v1
GUID GetCurrentPlatform() const
Retrieves the current platform identifier.
Definition: Host.h:280
void GetLicenseStatus(const GUID &in_guidPlatform, LicenseType &out_eType, LicenseStatus &out_eStatus, uint32_t &out_uDaysToExpiry) const
Obtain licensing status for the plug-in.
Definition: Host.h:327
LicenseType
License type.
Definition: PluginDef.h:59
CHost_::Instance * GetInstancePointer()
Definition: Host.h:441
Base host-provided instance type for ak_wwise_plugin_host_v1.
Definition: PluginDef.h:600
Wwise Authoring Plug-ins - C++ class helper to automatically determine the plug-in interfaces used in...
PluginInfoGenerator: Associates an existing C Interface with a variable that can be used....
CInterfacePtr InterfacePtr
Definition: PluginDef.h:980
GUID GetAuthoringPlaybackPlatform() const
Retrieves the requested playback platform of the Authoring tool.
Definition: Host.h:301
GUID(* GetAuthoringPlaybackPlatform)(const struct ak_wwise_plugin_host_v1 *in_this)
Retrieves the requested playback platform of the Authoring tool.
Definition: Host.h:99
Base instance type for receiving notifications on host changes events.
Definition: PluginDef.h:799
std::underlying_type< InterfaceType >::type InterfaceTypeValue
PluginInfoGenerator: Underlying storage type for the m_interface value in BaseInterface.
@ k_interfaceVersion
The interface version, as requested by this plug-in.
Definition: Host.h:269
@ k_interfaceType
The interface type, as provided by this plug-in.
Definition: Host.h:406
RequestedHostInterface< Host > RequestHost
Requests a Host interface, provided as m_host variable.
Definition: Host.h:473
AK_WWISE_PLUGIN_SPECIALIZE_INTERFACE_VERSION(AudioPlugin)
API to request host's current state and services.
Definition: Host.h:53
BasePlatformID(* GetDefaultNativeAuthoringPlaybackPlatform)(const struct ak_wwise_plugin_host_v1 *in_this)
Retrieves the requested playback base platform of the Authoring tool.
Definition: Host.h:91
void GetAssetLicenseStatus(const GUID &in_guidPlatform, AkUInt32 in_uAssetID, LicenseType &out_eType, LicenseStatus &out_eStatus, uint32_t &out_uDaysToExpiry) const
Obtain licensing status for a plug-in-specific asset ID.
Definition: Host.h:348
void(* WaapiCall)(const struct ak_wwise_plugin_host_v1 *in_this, const char *in_szUri, const char *in_szArgs, const char *in_szOptions, AK::IAkPluginMemAlloc *in_pAlloc, char **out_szResults, char **out_szError)
Find and call the specified procedure.
Definition: Host.h:173
Interface description and base class for every Wwise Authoring plug-in interface.
@ k_interfaceType
The interface type, as requested by this plug-in.
Definition: Host.h:259
The C interface, fulfilled by your plug-in.
Definition: Host.h:423
GUID(* GetCurrentPlatform)(const struct ak_wwise_plugin_host_v1 *in_this)
Retrieves the current platform identifier.
Definition: Host.h:75
uint32_t AkUInt32
Unsigned 32-bit integer.
AkInt16 AkPluginParamID
Source or effect plug-in parameter ID.
Definition: AkTypes.h:134
API to receive host's update notifications.
Definition: Host.h:391
V1::Notifications::Host_ Host
Latest version of the C++ Host notification interface.
Definition: Host.h:489
LicenseStatus
License status.
Definition: PluginDef.h:67
ak_wwise_plugin_notifications_host_instance_v1 Instance
Base instance type for receiving notifications on host changes events.
Definition: Host.h:199
#define AK_WWISE_PLUGIN_SPECIALIZE_HOST_INTERFACE(in_name, in_varname,...)
PluginInfoGenerator: Creates a C++ host specialization for interface class specified in in_name,...
AK_WWISE_PLUGIN_SPECIALIZE_INTERFACE_CLASS(AudioPlugin)
virtual void NotifyCurrentPlatformChanged(const GUID &in_guidCurrentPlatform)
Definition: Host.h:459
BasePlatformID GetDefaultNativeAuthoringPlaybackPlatform() const
Retrieves the requested playback base platform of the Authoring tool.
Definition: Host.h:294

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