Version
menu_open
link
Wwise SDK 2022.1.7
GUIWindows.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 - Windows frontend plug-in API for Audio plug-ins.
29  * \file AK/Wwise/Plugin/GUIWindows.h
30  */
31 
32 #pragma once
33 
34 #include "AudioPlugin.h"
35 
36 #if defined(AK_WIN) || defined(DOXYGEN_INCLUDE)
37 
38 // Acquire the module instance from the Microsoft linker
39 extern "C" IMAGE_DOS_HEADER __ImageBase;
40 
41 /**
42  * \brief Starts a new property-control bindings table.
43  *
44  * Starts the declaration of a new property-control bindings table, used in controls such as checkboxes and
45  * radio buttons. These can be bound to properties of your plug-in by using AK_WWISE_PLUGIN_GUI_WINDOWS_POP_ITEM().
46  *
47  * \param theName The name of the populate table. It must be unique within the current scope.
48  *
49  * \sa
50  * - \ref wwiseplugin_dialog_guide_poptable
51  * - AK_WWISE_PLUGIN_GUI_WINDOWS_POP_ITEM()
52  * - AK_WWISE_PLUGIN_GUI_WINDOWS_END_POPULATE_TABLE()
53  */
54 #define AK_WWISE_PLUGIN_GUI_WINDOWS_BEGIN_POPULATE_TABLE(theName) AK::Wwise::Plugin::PopulateTableItem theName[] = {
55 
56 /**
57  * \brief Declares an association between a control and a property within a property-control bindings table.
58  *
59  * \param theID The resource ID of the control (checkbox or radio button)
60  * \param theProp The name of the property, as defined in your plug-in's
61  * XML definition file (refer to \ref wwiseplugin_xml_properties_tag)
62  * \sa
63  * - \ref wwiseplugin_dialog_guide_poptable
64  * - \ref wwiseplugin_xml_properties_tag
65  * - AK_WWISE_PLUGIN_GUI_WINDOWS_BEGIN_POPULATE_TABLE()
66  * - AK_WWISE_PLUGIN_GUI_WINDOWS_END_POPULATE_TABLE()
67  */
68 #define AK_WWISE_PLUGIN_GUI_WINDOWS_POP_ITEM(theID, theProp) {theID, theProp },
69 
70 /**
71  * \brief Ends the declaration of a property-control bindings table.
72  *
73  * \sa
74  * - \ref wwiseplugin_dialog_guide_poptable
75  * - AK_WWISE_PLUGIN_GUI_WINDOWS_BEGIN_POPULATE_TABLE()
76  * - AK_WWISE_PLUGIN_GUI_WINDOWS_POP_ITEM()
77  */
78 #define AK_WWISE_PLUGIN_GUI_WINDOWS_END_POPULATE_TABLE() AK_WWISE_PLUGIN_GUI_WINDOWS_POP_ITEM(0, NULL) };
79 
80 /**
81  * \brief Windows frontend plug-in API for Audio plug-ins.
82  *
83  * You must create this interface in order to support the GUI part of the user interface.
84  *
85  * \sa
86  * - \ref plugin_frontend_windows
87  */
88 struct ak_wwise_plugin_gui_windows_v1
89 #ifdef __cplusplus
90  : public ak_wwise_plugin_base_interface
91 #endif
92 {
93 #ifndef __cplusplus
94  ak_wwise_plugin_base_interface m_baseInterface;
95 #endif
96 
97 #ifdef __cplusplus
98  /// Base instance type for providing a Windows frontend for an audio plug-in.
99  using Instance = ak_wwise_plugin_gui_windows_instance_v1;
100 
101  ak_wwise_plugin_gui_windows_v1() :
102  ak_wwise_plugin_base_interface(AK_WWISE_PLUGIN_INTERFACE_TYPE_GUI_WINDOWS, 1)
103  {}
104 #endif
105 
106  /**
107  * \brief Retrieves the plug-in's HINSTANCE used for loading resources.
108  *
109  * \param[in] in_this Current instance of this interface.
110  * \return A handle to the instance of the plug-in DLL
111  * \sa
112  * - \ref wwiseplugin_dialogcode
113  */
114  HINSTANCE(*GetResourceHandle)(const struct ak_wwise_plugin_gui_windows_instance_v1* in_this);
115 
116  /**
117  * \brief Retrieves the plug-in dialog parameters.
118  *
119  * \param[in] in_this Current instance of this interface.
120  * \param[in] in_eDialog The dialog type.
121  * \param[out] out_uiDialogID The returned resource ID of the dialog
122  * \param[out] out_pTable The returned table of property-control bindings (can be nullptr if no properties are to be bound).
123  * \return true if a dialog was returned, false otherwise.
124  *
125  * \sa
126  * - \ref wwiseplugin_dialogcode
127  * - \ref wwiseplugin_dialog_guide
128  */
129  bool(*GetDialog)(
130  const struct ak_wwise_plugin_gui_windows_instance_v1* in_this,
131  AK::Wwise::Plugin::eDialog in_eDialog,
132  uint32_t* out_uiDialogID,
133  AK::Wwise::Plugin::PopulateTableItem ** out_pTable
134  );
135 
136  /**
137  * \brief Window message handler for dialogs.
138  *
139  * This is very similar to a standard WIN32 window procedure.
140  *
141  * \param[in] in_this Current instance of this interface.
142  * \param[in] in_eDialog The dialog type.
143  * \param[in] in_hWnd The window handle of the dialog.
144  * \param[in] in_message The incoming message. This is a standard Windows message ID (ex. WM_PAINT).
145  * \param[in] in_wParam The WPARAM of the message (see MSDN).
146  * \param[in] in_lParam The LPARAM of the message (see MSDN).
147  * \param[out] out_lResult The returned value if the message has been processed
148  * (it is only considered if the method also returns true).
149  * \return True if the message has been processed by the plug-in, False otherwise
150  *
151  * \sa
152  * - \ref wwiseplugin_dialogcode
153  */
154  bool(*WindowProc)(
155  struct ak_wwise_plugin_gui_windows_instance_v1* in_this,
156  AK::Wwise::Plugin::eDialog in_eDialog,
157  HWND in_hWnd,
158  uint32_t in_message,
159  WPARAM in_wParam,
160  LPARAM in_lParam,
161  LRESULT* out_lResult
162  );
163 
164  /**
165  * \brief Called when the user clicks on the '?' icon.
166  *
167  * \param[in] in_this Current instance of this interface.
168  * \param[in] in_hWnd The window handle of the dialog.
169  * \param[in] in_eDialog The dialog type.
170  * \param[in] in_szLanguageCode The language code in ISO639-1.
171  * \return true if the plug-in handled the help request, false otherwise
172  *
173  * \sa
174  * - \ref wwiseplugin_help
175  */
176  bool(*Help)(
177  const struct ak_wwise_plugin_gui_windows_instance_v1* in_this,
178  HWND in_hWnd,
179  AK::Wwise::Plugin::eDialog in_eDialog,
180  const char * in_szLanguageCode
181  );
182 };
183 #define AK_WWISE_PLUGIN_GUI_WINDOWS_ID() \
184  AK_WWISE_PLUGIN_BASE_INTERFACE_FROM_ID(AK_WWISE_PLUGIN_INTERFACE_TYPE_GUI_WINDOWS, 1)
185 #define AK_WWISE_PLUGIN_GUI_WINDOWS_CTOR(/* ak_wwise_plugin_info* */ in_pluginInfo, /* void* */ in_data) \
186 { \
187  .m_baseInterface = AK_WWISE_PLUGIN_BASE_INTERFACE_CTOR(AK_WWISE_PLUGIN_GUI_WINDOWS_ID(), in_pluginInfo, in_data) \
188 }
189 
190 
191 #ifdef __cplusplus
192 namespace AK::Wwise::Plugin
193 {
194  namespace V1
195  {
196  using CGUIWindows = ak_wwise_plugin_gui_windows_v1;
197 
198  /// \copydoc ak_wwise_plugin_gui_windows_v1
199  class GUIWindows : public CGUIWindows::Instance
200  {
201  public:
202  /**
203  * \brief The interface type, as provided by this plug-in.
204  */
205  enum : InterfaceTypeValue
206  {
207  /**
208  * \brief The interface type, as provided by this plug-in.
209  */
210  k_interfaceType = AK_WWISE_PLUGIN_INTERFACE_TYPE_GUI_WINDOWS
211  };
212  /**
213  * \brief The interface version, as provided by this plug-in.
214  */
215  enum : InterfaceVersion
216  {
217  /**
218  * \brief The interface version, as provided by this plug-in.
219  */
220  k_interfaceVersion = 1
221  };
222 
223  /**
224  * \brief The C interface, fulfilled by your plug-in.
225  */
226  struct Interface : public CGUIWindows
227  {
228  using Instance = GUIWindows;
229  Interface()
230  {
231  CGUIWindows::GetResourceHandle = [](const struct ak_wwise_plugin_gui_windows_instance_v1* in_this) { return (HINSTANCE)static_cast<const Instance*>(in_this)->GetResourceHandle(); };
232  CGUIWindows::GetDialog = [](const struct ak_wwise_plugin_gui_windows_instance_v1* in_this, eDialog in_eDialog, uint32_t* out_uiDialogID, PopulateTableItem ** out_pTable) { return (bool)static_cast<const Instance*>(in_this)->GetDialog(in_eDialog, *out_uiDialogID, *out_pTable); };
233  CGUIWindows::WindowProc = [](struct ak_wwise_plugin_gui_windows_instance_v1* in_this, eDialog in_eDialog, HWND in_hWnd, uint32_t in_message, WPARAM in_wParam, LPARAM in_lParam, LRESULT* out_lResult) { return (bool)static_cast<Instance*>(in_this)->WindowProc(in_eDialog, in_hWnd, in_message, in_wParam, in_lParam, *out_lResult); };
234  CGUIWindows::Help = [](const struct ak_wwise_plugin_gui_windows_instance_v1* in_this, HWND in_hWnd, eDialog in_eDialog, const char * in_szLanguageCode) { return (bool)static_cast<const Instance*>(in_this)->Help(in_hWnd, in_eDialog, in_szLanguageCode); };
235  }
236  };
237 
238  InterfacePtr GetInterfacePointer() {
239  static Interface g_interface;
240  return &g_interface;
241  }
242  CGUIWindows::Instance* GetInstancePointer() {
243  return this;
244  }
245  const CGUIWindows::Instance* GetInstancePointer() const {
246  return this;
247  }
248 
249  GUIWindows() :
250  CGUIWindows::Instance()
251  {
252  }
253 
254  virtual ~GUIWindows() {}
255 
256  /**
257  * \brief Retrieves the plug-in's HINSTANCE used for loading resources.
258  *
259  * \return A handle to the instance of the plug-in DLL
260  * \sa
261  * - \ref wwiseplugin_dialogcode
262  */
263  virtual HINSTANCE GetResourceHandle() const {
264  return ((HINSTANCE)&__ImageBase);
265  }
266 
267  /**
268  * \brief Retrieves the plug-in dialog parameters.
269  *
270  * \param[in] in_eDialog The dialog type.
271  * \param[out] out_uiDialogID The returned resource ID of the dialog
272  * \param[out] out_pTable The returned table of property-control bindings (can be nullptr if no properties are to be bound).
273  * \return True if out_uiDialogID was set. If nothing was set and true is returned, an empty dialog will be created
274  * (non-MFC code will then have a window handle to hook to). False otherwise (no frontend).
275  *
276  * \sa
277  * - \ref wwiseplugin_dialogcode
278  * - \ref wwiseplugin_dialog_guide
279  */
280  virtual bool GetDialog(
281  eDialog in_eDialog,
282  uint32_t & out_uiDialogID,
283  PopulateTableItem *& out_pTable
284  ) const { return false; }
285 
286  /**
287  * \brief Window message handler for dialogs.
288  *
289  * This is very similar to a standard WIN32 window procedure.
290  *
291  * \param[in] in_eDialog The dialog type.
292  * \param[in] in_hWnd The window handle of the dialog.
293  * \param[in] in_message The incoming message. This is a standard Windows message ID (ex. WM_PAINT).
294  * \param[in] in_wParam The WPARAM of the message (see MSDN).
295  * \param[in] in_lParam The LPARAM of the message (see MSDN).
296  * \param[out] out_lResult The returned value if the message has been processed
297  * (it is only considered if the method also returns true).
298  * \return True if the message has been processed by the plug-in, False otherwise
299  *
300  * \sa
301  * - \ref wwiseplugin_dialogcode
302  */
303  virtual bool WindowProc(
304  eDialog in_eDialog,
305  HWND in_hWnd,
306  uint32_t in_message,
307  WPARAM in_wParam,
308  LPARAM in_lParam,
309  LRESULT& out_lResult
310  ) { return false; }
311 
312  /**
313  * \brief Called when the user clicks on the '?' icon.
314  *
315  * \param[in] in_hWnd The window handle of the dialog.
316  * \param[in] in_eDialog The dialog type.
317  * \param[in] in_szLanguageCode The language code in ISO639-1.
318  * \return true if the plug-in handled the help request, false otherwise
319  *
320  * \sa
321  * - \ref wwiseplugin_help
322  */
323  virtual bool Help(
324  HWND in_hWnd,
325  eDialog in_eDialog,
326  const char * in_szLanguageCode
327  ) const { return false; }
328  };
329  } // of namespace V1
330 
331  /// Latest version of the C GUIWindows interface.
332  using CGUIWindows = V1::CGUIWindows;
333  /// Latest version of the C++ GUIWindows interface.
334  using GUIWindows = V1::GUIWindows;
335 
336  AK_WWISE_PLUGIN_SPECIALIZE_INTERFACE_CLASS(GUIWindows);
337  AK_WWISE_PLUGIN_SPECIALIZE_INTERFACE_VERSION(GUIWindows);
338 } // of namespace AK::Wwise::Plugin
339 #endif // of __cplusplus
340 
341 #ifndef WM_AK_PRIVATE_SHOW_HELP_TOPIC
342 #define WM_AK_PRIVATE_SHOW_HELP_TOPIC 0x4981
343 #endif
344 
345 #endif // of AK_WIN
AK.Wwise::Plugin::V1::GUIWindows::GetInstancePointer
const CGUIWindows::Instance * GetInstancePointer() const
Definition: GUIWindows.h:245
AK.Wwise::Plugin::GUIWindows
V1::GUIWindows GUIWindows
Latest version of the C++ GUIWindows interface.
Definition: GUIWindows.h:334
AudioPlugin.h
Wwise Authoring Plug-ins - API for general Audio Plug-in's backend (Source, Effect,...
AK.Wwise::Plugin::V1::GUIWindows::GetResourceHandle
virtual HINSTANCE GetResourceHandle() const
Retrieves the plug-in's HINSTANCE used for loading resources.
Definition: GUIWindows.h:263
AK.Wwise::Plugin::V1::GUIWindows::GetDialog
virtual bool GetDialog(eDialog in_eDialog, uint32_t &out_uiDialogID, PopulateTableItem *&out_pTable) const
Retrieves the plug-in dialog parameters.
Definition: GUIWindows.h:280
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_gui_windows_v1
Windows frontend plug-in API for Audio plug-ins.
Definition: GUIWindows.h:92
AK.Wwise::Plugin::V1::GUIWindows::Help
virtual bool Help(HWND in_hWnd, eDialog in_eDialog, const char *in_szLanguageCode) const
Called when the user clicks on the '?' icon.
Definition: GUIWindows.h:323
AK.Wwise::Plugin::V1::CGUIWindows
ak_wwise_plugin_gui_windows_v1 CGUIWindows
Definition: GUIWindows.h:196
AK.Wwise::Plugin::V1::GUIWindows
Windows frontend plug-in API for Audio plug-ins.
Definition: GUIWindows.h:200
AK.Wwise::Plugin::InterfacePtr
CInterfacePtr InterfacePtr
Definition: PluginDef.h:980
ak_wwise_plugin_gui_windows_v1::GetDialog
bool(* GetDialog)(const struct ak_wwise_plugin_gui_windows_instance_v1 *in_this, AK::Wwise::Plugin::eDialog in_eDialog, uint32_t *out_uiDialogID, AK::Wwise::Plugin::PopulateTableItem **out_pTable)
Retrieves the plug-in dialog parameters.
Definition: GUIWindows.h:129
AK.Wwise::Plugin::V1::GUIWindows::WindowProc
virtual bool WindowProc(eDialog in_eDialog, HWND in_hWnd, uint32_t in_message, WPARAM in_wParam, LPARAM in_lParam, LRESULT &out_lResult)
Window message handler for dialogs.
Definition: GUIWindows.h:303
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::GUIWindows::GetInstancePointer
CGUIWindows::Instance * GetInstancePointer()
Definition: GUIWindows.h:242
ak_wwise_plugin_gui_windows_v1::GetResourceHandle
HINSTANCE(* GetResourceHandle)(const struct ak_wwise_plugin_gui_windows_instance_v1 *in_this)
Retrieves the plug-in's HINSTANCE used for loading resources.
Definition: GUIWindows.h:114
AK.Wwise::Plugin::AK_WWISE_PLUGIN_SPECIALIZE_INTERFACE_VERSION
AK_WWISE_PLUGIN_SPECIALIZE_INTERFACE_VERSION(AudioPlugin)
ak_wwise_plugin_gui_windows_v1::ak_wwise_plugin_gui_windows_v1
ak_wwise_plugin_gui_windows_v1()
Definition: GUIWindows.h:101
AK.Wwise::Plugin::V1::GUIWindows::Interface
The C interface, fulfilled by your plug-in.
Definition: GUIWindows.h:227
ak_wwise_plugin_base_interface
Interface description and base class for every Wwise Authoring plug-in interface.
Definition: PluginBaseInterface.h:120
AK_WWISE_PLUGIN_INTERFACE_TYPE_GUI_WINDOWS
@ AK_WWISE_PLUGIN_INTERFACE_TYPE_GUI_WINDOWS
2021.1 Audio frontend plug-in for Windows. ak_wwise_plugin_gui_windows_v1
Definition: PluginBaseInterface.h:74
AK.Wwise::Plugin::V1::GUIWindows::k_interfaceVersion
@ k_interfaceVersion
The interface version, as provided by this plug-in.
Definition: GUIWindows.h:220
__ImageBase
IMAGE_DOS_HEADER __ImageBase
Definition: GUIWindows.h:39
ak_wwise_plugin_gui_windows_v1::WindowProc
bool(* WindowProc)(struct ak_wwise_plugin_gui_windows_instance_v1 *in_this, AK::Wwise::Plugin::eDialog in_eDialog, HWND in_hWnd, uint32_t in_message, WPARAM in_wParam, LPARAM in_lParam, LRESULT *out_lResult)
Window message handler for dialogs.
Definition: GUIWindows.h:154
ak_wwise_plugin_gui_windows_v1::Help
bool(* Help)(const struct ak_wwise_plugin_gui_windows_instance_v1 *in_this, HWND in_hWnd, AK::Wwise::Plugin::eDialog in_eDialog, const char *in_szLanguageCode)
Called when the user clicks on the '?' icon.
Definition: GUIWindows.h:176
AK.Wwise::Plugin::V1::GUIWindows::k_interfaceType
@ k_interfaceType
The interface type, as provided by this plug-in.
Definition: GUIWindows.h:210
ak_wwise_plugin_gui_windows_instance_v1
Base instance type for providing a Windows frontend for an audio plug-in through ak_wwise_plugin_gui_...
Definition: PluginDef.h:757
AK.Wwise::Plugin::V1::GUIWindows::GetInterfacePointer
InterfacePtr GetInterfacePointer()
Definition: GUIWindows.h:238
AK.Wwise::Plugin::AK_WWISE_PLUGIN_SPECIALIZE_INTERFACE_CLASS
AK_WWISE_PLUGIN_SPECIALIZE_INTERFACE_CLASS(AudioPlugin)

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