Version
menu_open
Wwise SDK 2023.1.4
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) 2024 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  */
89 #ifdef __cplusplus
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.
100 
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,
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)(
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  {
197 
198  /// \copydoc ak_wwise_plugin_gui_windows_v1
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  */
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  */
221  };
222 
223  /**
224  * \brief The C interface, fulfilled by your plug-in.
225  */
226  struct Interface : public CGUIWindows
227  {
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 
239  static Interface g_interface;
240  return &g_interface;
241  }
243  return this;
244  }
246  return this;
247  }
248 
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.
333  /// Latest version of the C++ GUIWindows interface.
335 
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
const CGUIWindows::Instance * GetInstancePointer() const
Definition: GUIWindows.h:245
V1::GUIWindows GUIWindows
Latest version of the C++ GUIWindows interface.
Definition: GUIWindows.h:334
Wwise Authoring Plug-ins - API for general Audio Plug-in's backend (Source, Effect,...
virtual HINSTANCE GetResourceHandle() const
Retrieves the plug-in's HINSTANCE used for loading resources.
Definition: GUIWindows.h:263
virtual bool GetDialog(eDialog in_eDialog, uint32_t &out_uiDialogID, PopulateTableItem *&out_pTable) const
Retrieves the plug-in dialog parameters.
Definition: GUIWindows.h:280
decltype(BaseInterface::m_version) InterfaceVersion
PluginInfoGenerator: Type for the m_version value in BaseInterface.
Windows frontend plug-in API for Audio plug-ins.
Definition: GUIWindows.h:92
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_gui_windows_v1 CGUIWindows
Definition: GUIWindows.h:196
Windows frontend plug-in API for Audio plug-ins.
Definition: GUIWindows.h:200
CInterfacePtr InterfacePtr
Definition: PluginDef.h:995
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
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
std::underlying_type< InterfaceType >::type InterfaceTypeValue
PluginInfoGenerator: Underlying storage type for the m_interface value in BaseInterface.
CGUIWindows::Instance * GetInstancePointer()
Definition: GUIWindows.h:242
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_SPECIALIZE_INTERFACE_VERSION(AudioPlugin)
The C interface, fulfilled by your plug-in.
Definition: GUIWindows.h:227
Interface description and base class for every Wwise Authoring plug-in interface.
@ AK_WWISE_PLUGIN_INTERFACE_TYPE_GUI_WINDOWS
2021.1 Audio frontend plug-in for Windows. ak_wwise_plugin_gui_windows_v1
@ k_interfaceVersion
The interface version, as provided by this plug-in.
Definition: GUIWindows.h:220
IMAGE_DOS_HEADER __ImageBase
Definition: GUIWindows.h:39
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
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
@ k_interfaceType
The interface type, as provided by this plug-in.
Definition: GUIWindows.h:210
Base instance type for providing a Windows frontend for an audio plug-in through ak_wwise_plugin_gui_...
Definition: PluginDef.h:772
InterfacePtr GetInterfacePointer()
Definition: GUIWindows.h:238
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