バージョン
menu

Wwise SDK 2025.1.0
Host.h
[詳解]
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) 2025 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/V1/Host.h
30  */
31 
32 #pragma once
33 
34 #include "../PlatformID.h"
35 #include "../PluginInfoGenerator.h"
36 
37 /**
38  * \brief API to request host's current state and services.
39  *
40  * If requested, this contains information on the current state of the host as well as generic operations.
41  *
42  * For example, the currently selected platform, tools to post
43  * when internal plug-in data changed, or a way to make Waapi calls.
44  *
45  * In order to be reactive to host's state, you should consider implementing ak_wwise_plugin_notifications_host_v1
46  * notifications.
47  */
49 #ifdef __cplusplus
51 #endif
52 {
53 #ifndef __cplusplus
54  ak_wwise_plugin_base_interface m_baseInterface;
55 #endif
56 
57 #ifdef __cplusplus
58  /// Base host-provided instance type.
60  ak_wwise_plugin_host_v1(int in_version = 1) :
62  {}
63 #endif
64 
65  /**
66  * \brief Retrieves the current platform identifier.
67  *
68  * This can be passed to any function that has a parameter for a platform ID, such as GetValue() or
69  * SetValue(), when you want to make the call for the currently active platform.
70  *
71  * \param[in] in_this Current instance of this interface.
72  * \return The unique ID of the current platform.
73  */
74  GUID(*GetCurrentPlatform)(const struct ak_wwise_plugin_host_v1* in_this);
75 
76  /**
77  * \brief Retrieves the current base platform identifier.
78  *
79  * \param[in] in_this Current instance of this interface.
80  * \return The unique ID of the current base platform.
81  */
83 
84  /**
85  * \brief Retrieves the requested playback base platform of the Authoring tool.
86  *
87  * \param[in] in_this Current instance of this interface.
88  * \return The unique base ID of the requested playback's platform.
89  */
91 
92  /**
93  * \brief Retrieves the requested playback platform of the Authoring tool.
94  *
95  * \param[in] in_this Current instance of this interface.
96  * \return The unique ID of the requested playback's platform.
97  */
99 
100  /**
101  * \brief Use this function to tell Wwise that something other than properties has changed within the plug-in.
102  *
103  * This will set the plugin dirty (indicating there are unsaved changes) and GetPluginData will be called when
104  * the plug-in is about to play in Wwise. This will transfer the internal data to the Sound Engine part of
105  * the plug-in.
106  *
107  * Use ALL_PLUGIN_DATA_ID to indicate that all the data has to be refreshed.
108  *
109  * \param[in] in_this Current instance of this interface.
110  * \param[in] in_idData Data needed to be updated.
111  * \param[in] in_bMakeProjectDirty Whether project needs saving.
112  */
114  struct ak_wwise_plugin_host_instance_v1* in_this,
115  AkPluginParamID in_idData,
116  bool in_bMakeProjectDirty
117  );
118 
119  /**
120  * \brief Obtain licensing status for the plug-in.
121  *
122  * See \ref wwiseplugin_dll_license for more information.
123  *
124  * \param[in] in_this Current instance of this interface.
125  * \param[in] in_guidPlatform GUID of the platform.
126  * \param[out] out_eType License Type.
127  * \param[out] out_eStatus License Status.
128  * \param[out] out_uDaysToExpiry Days until license expiry.
129  */
131  const struct ak_wwise_plugin_host_instance_v1* in_this,
132  const GUID* in_guidPlatform,
135  uint32_t* out_uDaysToExpiry
136  );
137 
138  /**
139  * \brief Obtain licensing status for a plug-in-specific asset ID.
140  *
141  * See \ref wwiseplugin_dll_license for more information.
142  *
143  * \param[in] in_this Current instance of this interface.
144  * \param[in] in_guidPlatform GUID of the platform.
145  * \param[in] in_uAssetID ID of the asset.
146  * \param[out] out_eType License Type.
147  * \param[out] out_eStatus License Status.
148  * \param[out] out_uDaysToExpiry Days until license expiry.
149  */
151  const struct ak_wwise_plugin_host_instance_v1* in_this,
152  const GUID* in_guidPlatform,
153  AkUInt32 in_uAssetID,
156  uint32_t* out_uDaysToExpiry
157  );
158 
159  /**
160  * \brief Find and call the specified procedure.
161  *
162  * Calls made using this function are always blocking.
163  *
164  * \param[in] in_this Current instance of this interface.
165  * \param[in] in_szUri URI of the procedure to call.
166  * \param[in] in_szArgs JSON string of arguments to pass to the procedure, or nullptr for no arguments.
167  * \param[in] in_szOptions JSON string of options to pass to the procedure, or nullptr for no options.
168  * \param[in] in_pAlloc Allocator used to allocate memory for the results or the error.
169  * \param[out] out_szResults JSON string (utf-8) containing the results, if any.
170  * \param[out] out_szError JSON string (utf-8) containing the error, if any.
171  */
172  void(*WaapiCall)(
173  const struct ak_wwise_plugin_host_v1* in_this,
174  const char* in_szUri,
175  const char* in_szArgs,
176  const char* in_szOptions,
177  AK::IAkPluginMemAlloc* in_pAlloc,
178  char** out_szResults,
179  char** out_szError
180  );
181 };
182 
183 /**
184  * \brief API to receive host's update notifications.
185  */
187 #ifdef __cplusplus
189 #endif
190 {
191 #ifndef __cplusplus
192  ak_wwise_plugin_base_interface m_baseInterface;
193 #endif
194 
195 #ifdef __cplusplus
196  /// Base instance type for receiving notifications on host changes events.
198 
201  {}
202 #endif
203 
204  /**
205  * \brief Received when the current platform changes.
206  *
207  * \param[in] in_this Current instance of this interface.
208  * \param[in] in_guidCurrentPlatform The unique ID of the new platform.
209  *
210  * \sa
211  * - \ref wwiseplugin_platformchange
212  */
215  const GUID * in_guidCurrentPlatform ///< The unique ID of the new platform
216  );
217 };
218 
219 
220 #define AK_WWISE_PLUGIN_HOST_V1_ID() \
221  AK_WWISE_PLUGIN_BASE_INTERFACE_FROM_ID(AK_WWISE_PLUGIN_INTERFACE_TYPE_HOST, 1)
222 #define AK_WWISE_PLUGIN_HOST_V1_CTOR() \
223 { \
224  .m_baseInterface = AK_WWISE_PLUGIN_HOST_V1_ID() \
225 }
226 
227 #define AK_WWISE_PLUGIN_NOTIFICATIONS_HOST_V1_ID() \
228  AK_WWISE_PLUGIN_BASE_INTERFACE_FROM_ID(AK_WWISE_PLUGIN_INTERFACE_TYPE_NOTIFICATIONS_HOST, 1)
229 #define AK_WWISE_PLUGIN_NOTIFICATIONS_HOST_V1_CTOR(/* ak_wwise_plugin_info* */ in_pluginInfo, /* void* */ in_data) \
230 { \
231  .m_baseInterface = AK_WWISE_PLUGIN_BASE_INTERFACE_CTOR(AK_WWISE_PLUGIN_NOTIFICATIONS_HOST_V1_ID(), in_pluginInfo, in_data) \
232 }
233 
234 
235 #ifdef __cplusplus
236 namespace AK::Wwise::Plugin
237 {
238  namespace V1
239  {
241 
242  /// \copydoc ak_wwise_plugin_host_v1
243  template<typename CHostT = CHost, int interface_version = 1>
244  class HostBase : public CBaseInstanceGlue<CHostT>
245  {
246  public:
247  using Interface = CHostT;
248  using Instance = typename CHostT::Instance;
249 
250  /**
251  * \brief The interface type, as requested by this plug-in.
252  */
253  enum : InterfaceTypeValue
254  {
255  /**
256  * \brief The interface type, as requested by this plug-in.
257  */
259  };
260  /**
261  * \brief The interface version, as requested by this plug-in.
262  */
263  enum : InterfaceVersion
264  {
265  /**
266  * \brief The interface version, as requested by this plug-in.
267  */
268  k_interfaceVersion = interface_version
269  };
270 
271  /**
272  * \brief Retrieves the current platform identifier.
273  *
274  * This can be passed to any function that has a parameter for a platform ID, such as GetValue() or
275  * SetValue(), when you want to make the call for the currently active platform.
276  *
277  * \return The unique ID of the current platform.
278  */
279  inline GUID GetCurrentPlatform() const { return this->g_cinterface->GetCurrentPlatform(this->g_cinterface); }
280 
281  /**
282  * \brief Retrieves the current base platform identifier.
283  *
284  * \return The unique ID of the current base platform.
285  */
287 
288  /**
289  * \brief Retrieves the requested playback base platform of the Authoring tool.
290  *
291  * \return The unique base ID of the requested playback's platform.
292  */
294 
295  /**
296  * \brief Retrieves the requested playback platform of the Authoring tool.
297  *
298  * \return The unique ID of the requested playback's platform.
299  */
301 
302  /**
303  * \brief Use this function to tell Wwise that something other than properties has changed within the plug-in.
304  *
305  * This will set the plugin dirty (indicating there are unsaved changes) and GetPluginData will be called when
306  * the plug-in is about to play in Wwise. This will transfer the internal data to the Sound Engine part of
307  * the plug-in.
308  *
309  * Use ALL_PLUGIN_DATA_ID to indicate that all the data has to be refreshed.
310  *
311  * \param[in] in_idData Data needed to be updated.
312  * \param[in] in_bMakeProjectDirty Whether project needs saving.
313  */
314  inline void NotifyInternalDataChanged(AkPluginParamID in_idData, bool in_bMakeProjectDirty) { this->g_cinterface->NotifyInternalDataChanged(this, in_idData, in_bMakeProjectDirty); }
315 
316  /**
317  * \brief Obtain licensing status for the plug-in.
318  *
319  * See \ref wwiseplugin_dll_license for more information.
320  *
321  * \param[in] in_guidPlatform GUID of the platform.
322  * \param[out] out_eType License Type.
323  * \param[out] out_eStatus License Status.
324  * \param[out] out_uDaysToExpiry Days until license expiry.
325  */
326  inline void GetLicenseStatus(
327  const GUID& in_guidPlatform,
328  LicenseType& out_eType,
329  LicenseStatus& out_eStatus,
330  uint32_t& out_uDaysToExpiry
331  ) const
332  {
333  this->g_cinterface->GetLicenseStatus(this, &in_guidPlatform, &out_eType, &out_eStatus, &out_uDaysToExpiry);
334  }
335 
336  /**
337  * \brief Obtain licensing status for a plug-in-specific asset ID.
338  *
339  * See \ref wwiseplugin_dll_license for more information.
340  *
341  * \param[in] in_guidPlatform GUID of the platform.
342  * \param[in] in_uAssetID ID of the asset.
343  * \param[out] out_eType License Type.
344  * \param[out] out_eStatus License Status.
345  * \param[out] out_uDaysToExpiry Days until license expiry.
346  */
348  const GUID& in_guidPlatform,
349  AkUInt32 in_uAssetID,
350  LicenseType& out_eType,
351  LicenseStatus& out_eStatus,
352  uint32_t& out_uDaysToExpiry
353  ) const
354  {
355  this->g_cinterface->GetAssetLicenseStatus(this, &in_guidPlatform, in_uAssetID, &out_eType, &out_eStatus, &out_uDaysToExpiry);
356  }
357 
358  /**
359  * \brief Find and call the specified procedure.
360  *
361  * Calls made using this function are always blocking.
362  *
363  * \param[in] in_szUri URI of the procedure to call.
364  * \param[in] in_szArgs JSON string of arguments to pass to the procedure, or nullptr for no arguments.
365  * \param[in] in_szOptions JSON string of options to pass to the procedure, or nullptr for no options.
366  * \param[in] in_alloc Allocator used to allocate memory for the results or the error.
367  * \param[out] out_szResults JSON string (utf-8) containing the results, if any.
368  * \param[out] out_szError JSON string (utf-8) containing the error, if any.
369  */
370  inline void WaapiCall(
371  const char* in_szUri,
372  const char* in_szArgs,
373  const char* in_szOptions,
374  AK::IAkPluginMemAlloc& in_alloc,
375  char*& out_szResults,
376  char*& out_szError
377  ) const
378  {
379  this->g_cinterface->WaapiCall(this->g_cinterface, in_szUri, in_szArgs, in_szOptions, &in_alloc, &out_szResults, &out_szError);
380  }
381  };
382 
383  using Host = HostBase<>;
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  namespace Notifications
479  {
480  /// Latest version of the C Host notification interface.
482  /// Latest version of the C++ Host notification interface.
484  }
485 
490 } // of namespace AK::Wwise::Plugin
491 
492 #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:130
API to receive host's update notifications.
Definition: Host.h:190
API to request host's current state and services.
Definition: Host.h:245
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:326
BasePlatformID(* GetCurrentBasePlatform)(const struct ak_wwise_plugin_host_v1 *in_this)
Retrieves the current base platform identifier.
Definition: Host.h:82
@ 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
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:213
GUID GetAuthoringPlaybackPlatform() const
Retrieves the requested playback platform of the Authoring tool.
Definition: Host.h:300
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 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:370
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:150
ak_wwise_plugin_host_v1(int in_version=1)
Definition: Host.h:60
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:113
@ k_interfaceVersion
The interface version, as requested by this plug-in.
Definition: Host.h:268
@ AK_WWISE_PLUGIN_INTERFACE_TYPE_NOTIFICATIONS_HOST
2021.1 Host modification notification. ak_wwise_plugin_notifications_host_v1
AkInt16 AkPluginParamID
Source or effect plug-in parameter ID
Definition: AkTypedefs.h:53
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.
PluginInfoGenerator: Associates an existing C Interface with a variable that can be used....
CInterfacePtr InterfacePtr
@ k_interfaceType
The interface type, as requested by this plug-in.
Definition: Host.h:258
BasePlatformID GetCurrentBasePlatform() const
Retrieves the current base platform identifier.
Definition: Host.h:286
GUID(* GetAuthoringPlaybackPlatform)(const struct ak_wwise_plugin_host_v1 *in_this)
Retrieves the requested playback platform of the Authoring tool.
Definition: Host.h:98
Base instance type for receiving notifications on host changes events.
BasePlatformID GetDefaultNativeAuthoringPlaybackPlatform() const
Retrieves the requested playback base platform of the Authoring tool.
Definition: Host.h:293
std::underlying_type< InterfaceType >::type InterfaceTypeValue
PluginInfoGenerator: Underlying storage type for the m_interface value in BaseInterface
@ k_interfaceType
The interface type, as provided by this plug-in.
Definition: Host.h:407
AK_WWISE_PLUGIN_SPECIALIZE_INTERFACE_VERSION(AudioPlugin)
API to request host's current state and services.
Definition: Host.h:52
BasePlatformID(* GetDefaultNativeAuthoringPlaybackPlatform)(const struct ak_wwise_plugin_host_v1 *in_this)
Retrieves the requested playback base platform of the Authoring tool.
Definition: Host.h:90
GUID GetCurrentPlatform() const
Retrieves the current platform identifier.
Definition: Host.h:279
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:172
Interface description and base class for every Wwise Authoring plug-in interface.
The C interface, fulfilled by your plug-in.
Definition: Host.h:424
GUID(* GetCurrentPlatform)(const struct ak_wwise_plugin_host_v1 *in_this)
Retrieves the current platform identifier.
Definition: Host.h:74
uint32_t AkUInt32
Unsigned 32-bit integer
API to receive host's update notifications.
Definition: Host.h:392
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:197
#define AK_WWISE_PLUGIN_SPECIALIZE_HOST_INTERFACE(in_name, in_varname,...)
PluginInfoGenerator: Creates a C++ host specialization for interface class specified in in_name,...
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:347
AK_WWISE_PLUGIN_SPECIALIZE_INTERFACE_CLASS(AudioPlugin)
virtual void NotifyCurrentPlatformChanged(const GUID &in_guidCurrentPlatform)
Definition: Host.h:460
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:314

このページはお役に立ちましたか?

サポートは必要ですか?

ご質問や問題、ご不明点はございますか?お気軽にお問い合わせください。

サポートページをご確認ください

あなたのプロジェクトについて教えてください。ご不明な点はありませんか。

プロジェクトを登録していただくことで、ご利用開始のサポートをいたします。

Wwiseからはじめよう