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

Cette page a-t-elle été utile ?

Besoin d'aide ?

Des questions ? Des problèmes ? Besoin de plus d'informations ? Contactez-nous, nous pouvons vous aider !

Visitez notre page d'Aide

Décrivez-nous de votre projet. Nous sommes là pour vous aider.

Enregistrez votre projet et nous vous aiderons à démarrer sans aucune obligation !

Partir du bon pied avec Wwise