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