Version
menu_open
Wwise SDK 2024.1.0
SinkDevices.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 - Plug-in that lists supported output devices.
29  * \file AK/Wwise/Plugin/SinkDevices.h
30  *
31  * Provides a list of up-to-date device IDs that can be used to instantiate a new Sound Engine sink.
32  *
33  * \sa C interfaces
34  * - \ref ak_wwise_plugin_sink_devices_v1
35  *
36  * \sa C++ interfaces
37  * - \ref AK::Wwise::Plugin::SinkDevices
38  */
39 
40 #pragma once
41 
42 #include "PluginInfoGenerator.h"
43 
44 /**
45  * \brief Device enumerator for sink plug-ins.
46  *
47  * Allows your plug-in to provide a list of up-to-date device IDs that can be used to instantiate a new
48  * Sound Engine sink.
49  *
50  * This plug-in interface cannot be linked to a backend or a frontend plug-in, it must be standalone.
51  *
52  * \sa
53  * - \ref ak_wwise_plugin_sink_devices_instance_v1 instance type
54  * - \ref AK::Wwise::Plugin::SinkDevices C++ Interface
55  * - \ref AK_WWISE_PLUGIN_SINK_DEVICES_V1_ID Current ID for interface
56  * - \ref AK_WWISE_PLUGIN_INTERFACE_TYPE_SINK_DEVICES
57  */
58 struct ak_wwise_plugin_sink_devices_v1
59 #ifdef __cplusplus
60  : public ak_wwise_plugin_base_interface
61 #endif
62 {
63 #ifndef __cplusplus
64  ak_wwise_plugin_base_interface m_baseInterface;
65 #endif
66 
67 #ifdef __cplusplus
68  using Instance = ak_wwise_plugin_sink_devices_instance_v1; ///< \copydoc ak_wwise_plugin_sink_devices_instance_v1
69 
70  ak_wwise_plugin_sink_devices_v1() :
71  ak_wwise_plugin_base_interface(AK_WWISE_PLUGIN_INTERFACE_TYPE_SINK_DEVICES, 1)
72  {}
73 #endif
74 
75  /**
76  * \brief Get a count of the number of interfaces currently available.
77  *
78  * Provided by your plug-in, this should return a count.
79  *
80  * \aknote
81  * Due to the unpredictable nature of hardware configuration changes, an unpadded, basic system would return
82  * a configuration that can change between a GetCount and subsequent objects retrieval.
83  *
84  * As a plug-in designer, you are responsible to address this by returning adequate values that make sense as a whole.
85  *
86  * To guide you, Sink Devices interface is used for retrieval and data copy in a tight loop over a single thread
87  * at once. Host will retrieve the count, followed by the Name (GetName) and DeviceID (GetDeviceID), in the
88  * order the compiler sees fit. Data is expected to survive for the amount of time this tight loop exists.
89  *
90  * \code
91  * int count = m_interface->GetCount(m_instance);
92  * for (int i = 0; i < count; ++i)
93  * {
94  * result.emplace_back(
95  * m_interface->GetName(m_instance, i),
96  * m_interface->GetDeviceID(m_instance, i)
97  * );
98  * }
99  * \endcode
100  *
101  * A proposal is to use GetCount to internally retrieve the device names and IDs, make a static internal
102  * cache, and then return name and device ID based on this cache.
103  *
104  * You can also spawn an event listener or an update thread, and ensure the data is up to date when the calls
105  * come in, and block updates until all calls are accounted for.
106  * \endaknote
107  *
108  * \param[in] in_this Current instance of this interface.
109  * \return int Count of the number of interfaces available.
110  */
111  int(*GetCount)(const struct ak_wwise_plugin_sink_devices_instance_v1* in_this);
112 
113  /**
114  * \brief Get a user-presentable name for the device number in_num.
115  *
116  * Provided by your plug-in, this should return a const char* in UTF-8, valid at least until the next
117  * function call, and must not return duplicates or nullptr.
118  *
119  * It should return names that can be understood by an end user in the context of your plug-in.
120  *
121  * \param[in] in_this Current instance of this interface.
122  * \param[in] in_num Device number, from zero to the value, as retrieved by GetCount.
123  * \return const char* UTF-8 Name of the interface in_num.
124  *
125  * \sa \ref GetCount for a discussion on providing data in a multithread-aware environment.
126  */
127  const char*(*GetName)(const struct ak_wwise_plugin_sink_devices_instance_v1* in_this, int in_num);
128 
129  /**
130  * \brief Get a device ID for the device number in_num.
131  *
132  * Provided by your plug-in, this should return a uint32_t that can be understood by the Sound Engine part of
133  * your sink plug-in. It must not return duplicates or pointers, and the value should be applicable to the
134  * GetName call based on the same in_num.
135  *
136  * \param[in] in_this Current instance of this interface.
137  * \param[in] in_num Device number, from zero to the value, as retrieved by GetCount.
138  * \return uint32_t Device ID for the interface in_num.
139  *
140  * \sa \ref GetCount for a discussion on providing data in a multithread-aware environment.
141  */
142  uint32_t(*GetDeviceID)(const struct ak_wwise_plugin_sink_devices_instance_v1* in_this, int in_num);
143 };
144 #define AK_WWISE_PLUGIN_SINK_DEVICES_V1_ID() \
145  AK_WWISE_PLUGIN_BASE_INTERFACE_FROM_ID(AK_WWISE_PLUGIN_INTERFACE_TYPE_SINK_DEVICES, 1)
146 #define AK_WWISE_PLUGIN_SINK_DEVICES_V1_CTOR(/* ak_wwise_plugin_info* */ in_pluginInfo, /* void* */ in_data) \
147 { \
148  .m_baseInterface = AK_WWISE_PLUGIN_BASE_INTERFACE_CTOR(AK_WWISE_PLUGIN_SINK_DEVICES_V1_ID(), in_pluginInfo, in_data) \
149 }
150 
151 
152 #ifdef __cplusplus
153 namespace AK::Wwise::Plugin
154 {
155  namespace V1
156  {
157  using CSinkDevices = ak_wwise_plugin_sink_devices_v1; ///< \copydoc ak_wwise_plugin_sink_devices_v1
158 
159  /**
160  * \brief C++ API to provide device enumeration for sink plug-ins.
161  *
162  * Allows your plug-in to provide a list of up-to-date device IDs that can be used to instantiate a new Sound
163  * Engine sink.
164  *
165  * This plug-in interface cannot be linked to a backend or a frontend plug-in, it must be standalone.
166  *
167  * \sa
168  * - \ref ak_wwise_plugin_sink_devices_v1 C interface
169  * - \ref AK_WWISE_PLUGIN_INTERFACE_TYPE_SINK_DEVICES
170  */
171  class SinkDevices : public CSinkDevices::Instance
172  {
173  public:
174  /**
175  * \copydoc CSinkDevices::Instance
176  */
177  using Instance = CSinkDevices::Instance;
178 
179  /**
180  * \brief The interface type, as provided by this plug-in.
181  */
182  enum : InterfaceTypeValue
183  {
184  /**
185  * \brief The interface type, as provided by this plug-in.
186  */
187  k_interfaceType = AK_WWISE_PLUGIN_INTERFACE_TYPE_SINK_DEVICES
188  };
189  /**
190  * \brief The interface version, as provided by this plug-in.
191  */
192  enum : InterfaceVersion
193  {
194  /**
195  * \brief The interface version, as provided by this plug-in.
196  */
197  k_interfaceVersion = 1
198  };
199 
200  /**
201  * \brief The C interface, fulfilled by your plug-in.
202  */
203  struct Interface : public CSinkDevices
204  {
205  using Instance = SinkDevices; ///< \copydoc SinkDevices
206  Interface()
207  {
208  CSinkDevices::GetCount = [](const struct ak_wwise_plugin_sink_devices_instance_v1* in_this) { return static_cast<const Instance*>(in_this)->GetCount(); };
209  CSinkDevices::GetName = [](const struct ak_wwise_plugin_sink_devices_instance_v1* in_this, int in_num) { return static_cast<const Instance*>(in_this)->GetName(in_num); };
210  CSinkDevices::GetDeviceID = [](const struct ak_wwise_plugin_sink_devices_instance_v1* in_this, int in_num) { return static_cast<const Instance*>(in_this)->GetDeviceID(in_num); };
211  }
212  };
213 
214  /**
215  * \internal
216  * \brief Get the static Interface object, as used internally in AK::Wwise::Plugin::PluginInfoGenerator.
217  */
218  InterfacePtr GetInterfacePointer() {
219  static Interface g_interface;
220  return &g_interface;
221  }
222 
223  /**
224  * \internal
225  * \brief Get the static Instance object, as used internally in AK::Wwise::Plugin::PluginInfoGenerator.
226  */
227  CSinkDevices::Instance* GetInstancePointer() {
228  return this;
229  }
230 
231  /**
232  * \internal
233  * \brief Get the static Instance object, as used internally in AK::Wwise::Plugin::PluginInfoGenerator.
234  */
235  const CSinkDevices::Instance* GetInstancePointer() const {
236  return this;
237  }
238 
239  SinkDevices() :
240  CSinkDevices::Instance()
241  {
242  }
243 
244  virtual ~SinkDevices() {}
245 
246  /**
247  * \brief Get a count of the number of interfaces currently available.
248  *
249  * Provided by your plug-in, this should return a count.
250  *
251  * \aknote
252  * Due to the unpredictable nature of hardware configuration changes, an unpadded, basic system would return
253  * a configuration that can change between a GetCount and subsequent objects retrieval.
254  *
255  * As a plug-in designer, you are responsible to address this by returning adequate values that make sense as a whole.
256  *
257  * To guide you, Sink Devices interface is used for retrieval and data copy in a tight loop over a single thread
258  * at once. Host will retrieve the count, followed by the Name (GetName) and DeviceID (GetDeviceID), in the
259  * order the compiler sees fit. Data is expected to survive for the amount of time this tight loop exists.
260  *
261  * \code
262  * int count = m_interface->GetCount(m_instance);
263  * for (int i = 0; i < count; ++i)
264  * {
265  * result.emplace_back(
266  * m_interface->GetName(m_instance, i),
267  * m_interface->GetDeviceID(m_instance, i)
268  * );
269  * }
270  * \endcode
271  *
272  * A proposal is to use GetCount to internally retrieve the device names and IDs, make a static internal
273  * cache, and then return name and device ID based on this cache.
274  *
275  * You can also spawn an event listener or an update thread, and ensure the data is up to date when the calls
276  * come in, and block updates until all calls are accounted for.
277  * \endaknote
278  *
279  * \return int Count of the number of interfaces available.
280  */
281  virtual int GetCount() const = 0;
282 
283  /**
284  * \brief Get a user-presentable name for the device number in_num.
285  *
286  * Provided by your plug-in, this should return a const char* in UTF-8, valid at least until the next
287  * function call, and must not return duplicates or nullptr.
288  *
289  * It should return names that can be understood by an end user in the context of your plug-in.
290  *
291  * \param[in] in_num Device number, from zero to the value, as retrieved by GetCount.
292  * \return const char* UTF-8 Name of the interface in_num.
293  *
294  * \sa \ref GetCount for a discussion on providing data in a multithread-aware environment.
295  */
296  virtual const char* GetName(int in_num) const = 0;
297 
298  /**
299  * \brief Get a device ID for the device number in_num.
300  *
301  * Provided by your plug-in, this should return a uint32_t that can be understood by the Sound Engine part of
302  * your sink plug-in. It must not return duplicates or pointers, and the value should be applicable to the
303  * GetName call based on the same in_num.
304  *
305  * \param[in] in_num Device number, from zero to the value, as retrieved by GetCount.
306  * \return uint32_t Device ID for the interface in_num.
307  *
308  * \sa \ref GetCount for a discussion on providing data in a multithread-aware environment.
309  */
310  virtual uint32_t GetDeviceID(int in_num) const = 0;
311  };
312  } // of namespace V1
313 
314  /// Latest version of the C SinkDevices interface.
315  using CSinkDevices = V1::CSinkDevices;
316  /// Latest version of the C++ SinkDevices interface.
317  using SinkDevices = V1::SinkDevices;
318 
319  AK_WWISE_PLUGIN_SPECIALIZE_INTERFACE_CLASS(SinkDevices);
320  AK_WWISE_PLUGIN_SPECIALIZE_INTERFACE_VERSION(SinkDevices);
321 } // of namespace AK::Wwise::Plugin
322 
323 #endif // of __cplusplus
AK.Wwise::Plugin::V1::SinkDevices
C++ API to provide device enumeration for sink plug-ins.
Definition: SinkDevices.h:172
ak_wwise_plugin_sink_devices_v1::ak_wwise_plugin_sink_devices_v1
ak_wwise_plugin_sink_devices_v1()
Definition: SinkDevices.h:70
ak_wwise_plugin_sink_devices_v1::GetCount
int(* GetCount)(const struct ak_wwise_plugin_sink_devices_instance_v1 *in_this)
Get a count of the number of interfaces currently available.
Definition: SinkDevices.h:111
AK.Wwise::Plugin::V1::SinkDevices::GetCount
virtual int GetCount() const =0
Get a count of the number of interfaces currently available.
AK.Wwise::Plugin::V1::CSinkDevices
ak_wwise_plugin_sink_devices_v1 CSinkDevices
Device enumerator for sink plug-ins.
Definition: SinkDevices.h:157
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_sink_devices_v1
Device enumerator for sink plug-ins.
Definition: SinkDevices.h:62
AK.Wwise::Plugin::V1::SinkDevices::k_interfaceVersion
@ k_interfaceVersion
The interface version, as provided by this plug-in.
Definition: SinkDevices.h:197
AK_WWISE_PLUGIN_INTERFACE_TYPE_SINK_DEVICES
@ AK_WWISE_PLUGIN_INTERFACE_TYPE_SINK_DEVICES
2021.1 Sink Devices enumeration plug-in. ak_wwise_plugin_sink_devices_v1
Definition: PluginBaseInterface.h:69
AK.Wwise::Plugin::V1::SinkDevices::GetInstancePointer
const CSinkDevices::Instance * GetInstancePointer() const
Definition: SinkDevices.h:235
PluginInfoGenerator.h
Wwise Authoring Plug-ins - C++ class helper to automatically determine the plug-in interfaces used in...
AK.Wwise::Plugin::InterfacePtr
CInterfacePtr InterfacePtr
Definition: PluginDef.h:1057
AK.Wwise::Plugin::V1::SinkDevices::Interface
The C interface, fulfilled by your plug-in.
Definition: SinkDevices.h:204
ak_wwise_plugin_sink_devices_v1::GetDeviceID
uint32_t(* GetDeviceID)(const struct ak_wwise_plugin_sink_devices_instance_v1 *in_this, int in_num)
Get a device ID for the device number in_num.
Definition: SinkDevices.h:142
ak_wwise_plugin_sink_devices_instance_v1
Base instance type for providing a device list for your custom sink through ak_wwise_plugin_sink_devi...
Definition: PluginDef.h:934
AK.Wwise::Plugin::V1::SinkDevices::k_interfaceType
@ k_interfaceType
The interface type, as provided by this plug-in.
Definition: SinkDevices.h:187
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::SinkDevices::GetInstancePointer
CSinkDevices::Instance * GetInstancePointer()
Definition: SinkDevices.h:227
AK.Wwise::Plugin::AK_WWISE_PLUGIN_SPECIALIZE_INTERFACE_VERSION
AK_WWISE_PLUGIN_SPECIALIZE_INTERFACE_VERSION(AudioPlugin)
ak_wwise_plugin_sink_devices_v1::GetName
const char *(* GetName)(const struct ak_wwise_plugin_sink_devices_instance_v1 *in_this, int in_num)
Get a user-presentable name for the device number in_num.
Definition: SinkDevices.h:127
AK.Wwise::Plugin::V1::SinkDevices::GetName
virtual const char * GetName(int in_num) const =0
Get a user-presentable name for the device number in_num.
ak_wwise_plugin_base_interface
Interface description and base class for every Wwise Authoring plug-in interface.
Definition: PluginBaseInterface.h:120
ak_wwise_plugin_sink_devices_v1::Instance
ak_wwise_plugin_sink_devices_instance_v1 Instance
Base instance type for providing a device list for your custom sink through ak_wwise_plugin_sink_devi...
Definition: SinkDevices.h:68
AK.Wwise::Plugin::V1::SinkDevices::GetDeviceID
virtual uint32_t GetDeviceID(int in_num) const =0
Get a device ID for the device number in_num.
AK.Wwise::Plugin::SinkDevices
V1::SinkDevices SinkDevices
Latest version of the C++ SinkDevices interface.
Definition: SinkDevices.h:317
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