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