summaryrefslogtreecommitdiff
path: root/3rdparty/portaudio/include/pa_win_wasapi.h
blob: c046afd709e26429540ab3a23aa5c4a37382c9db (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
#ifndef PA_WIN_WASAPI_H
#define PA_WIN_WASAPI_H
/*
 * $Id:  $
 * PortAudio Portable Real-Time Audio Library
 * WASAPI specific extensions
 *
 * Copyright (c) 1999-2018 Ross Bencina and Phil Burk
 * Copyright (c) 2006-2010 David Viens
 * Copyright (c) 2010-2018 Dmitry Kostjuchenko
 *
 * Permission is hereby granted, free of charge, to any person obtaining
 * a copy of this software and associated documentation files
 * (the "Software"), to deal in the Software without restriction,
 * including without limitation the rights to use, copy, modify, merge,
 * publish, distribute, sublicense, and/or sell copies of the Software,
 * and to permit persons to whom the Software is furnished to do so,
 * subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be
 * included in all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR
 * ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
 * CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
 * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 */

/*
 * The text above constitutes the entire PortAudio license; however,
 * the PortAudio community also makes the following non-binding requests:
 *
 * Any person wishing to distribute modifications to the Software is
 * requested to send the modifications to the original developer so that
 * they can be incorporated into the canonical version. It is also
 * requested that these non-binding requests be included along with the
 * license above.
 */

/** @file
 @ingroup public_header
 @brief WASAPI-specific PortAudio API extension header file.
*/

#include "portaudio.h"
#include "pa_win_waveformat.h"

#ifdef __cplusplus
extern "C"
{
#endif /* __cplusplus */


/* Stream setup flags. */
typedef enum PaWasapiFlags
{
    /* put WASAPI into exclusive mode */
    paWinWasapiExclusive                = (1 << 0),

    /* allow to skip internal PA processing completely */
    paWinWasapiRedirectHostProcessor    = (1 << 1),

    /* assign custom channel mask */
    paWinWasapiUseChannelMask           = (1 << 2),

    /* select non-Event driven method of data read/write
       Note: WASAPI Event driven core is capable of 2ms latency!!!, but Polling
             method can only provide 15-20ms latency. */
    paWinWasapiPolling                  = (1 << 3),

    /* force custom thread priority setting, must be used if PaWasapiStreamInfo::threadPriority
       is set to a custom value */
    paWinWasapiThreadPriority           = (1 << 4),

    /* force explicit sample format and do not allow PA to select suitable working format, API will
       fail if provided sample format is not supported by audio hardware in Exclusive mode
       or system mixer in Shared mode */
    paWinWasapiExplicitSampleFormat     = (1 << 5),

    /* allow API to insert system-level channel matrix mixer and sample rate converter to allow
       playback formats that do not match the current configured system settings.
       this is in particular required for streams not matching the system mixer sample rate.
       only applies in Shared mode. */
    paWinWasapiAutoConvert              = (1 << 6)
}
PaWasapiFlags;
#define paWinWasapiExclusive             (paWinWasapiExclusive)
#define paWinWasapiRedirectHostProcessor (paWinWasapiRedirectHostProcessor)
#define paWinWasapiUseChannelMask        (paWinWasapiUseChannelMask)
#define paWinWasapiPolling               (paWinWasapiPolling)
#define paWinWasapiThreadPriority        (paWinWasapiThreadPriority)
#define paWinWasapiExplicitSampleFormat  (paWinWasapiExplicitSampleFormat)
#define paWinWasapiAutoConvert           (paWinWasapiAutoConvert)


/* Stream state.

 @note Multiple states can be united into a bitmask.
 @see  PaWasapiStreamStateCallback, PaWasapi_SetStreamStateHandler
*/
typedef enum PaWasapiStreamState
{
    /* state change was caused by the error:

       Example:
       1) If thread execution stopped due to AUDCLNT_E_RESOURCES_INVALIDATED then state
          value will contain paWasapiStreamStateError|paWasapiStreamStateThreadStop.
    */
    paWasapiStreamStateError         = (1 << 0),

    /* processing thread is preparing to start execution */
    paWasapiStreamStateThreadPrepare = (1 << 1),

    /* processing thread started execution (enters its loop) */
    paWasapiStreamStateThreadStart   = (1 << 2),

    /* processing thread stopped execution */
    paWasapiStreamStateThreadStop    = (1 << 3)
}
PaWasapiStreamState;
#define paWasapiStreamStateError         (paWasapiStreamStateError)
#define paWasapiStreamStateThreadPrepare (paWasapiStreamStateThreadPrepare)
#define paWasapiStreamStateThreadStart   (paWasapiStreamStateThreadStart)
#define paWasapiStreamStateThreadStop    (paWasapiStreamStateThreadStop)


/* Host processor.

   Allows to skip internal PA processing completely. paWinWasapiRedirectHostProcessor flag
   must be set to the PaWasapiStreamInfo::flags member in order to have host processor
   redirected to this callback.

   Use with caution! inputFrames and outputFrames depend solely on final device setup.
   To query max values of inputFrames/outputFrames use PaWasapi_GetFramesPerHostBuffer.
*/
typedef void (*PaWasapiHostProcessorCallback) (void *inputBuffer, long inputFrames,
    void *outputBuffer, long outputFrames, void *userData);


/* Stream state handler.

 @param pStream    Pointer to PaStream object.
 @param stateFlags State flags, a collection of values from PaWasapiStreamState enum.
 @param errorId    Error id provided by system API (HRESULT).
 @param userData   Pointer to user data.

 @see   PaWasapiStreamState
*/
typedef void (*PaWasapiStreamStateCallback) (PaStream *pStream, unsigned int stateFlags,
    unsigned int errorId, void *pUserData);


/* Device role. */
typedef enum PaWasapiDeviceRole
{
    eRoleRemoteNetworkDevice = 0,
    eRoleSpeakers,
    eRoleLineLevel,
    eRoleHeadphones,
    eRoleMicrophone,
    eRoleHeadset,
    eRoleHandset,
    eRoleUnknownDigitalPassthrough,
    eRoleSPDIF,
    eRoleHDMI,
    eRoleUnknownFormFactor
}
PaWasapiDeviceRole;


/* Jack connection type. */
typedef enum PaWasapiJackConnectionType
{
    eJackConnTypeUnknown,
    eJackConnType3Point5mm,
    eJackConnTypeQuarter,
    eJackConnTypeAtapiInternal,
    eJackConnTypeRCA,
    eJackConnTypeOptical,
    eJackConnTypeOtherDigital,
    eJackConnTypeOtherAnalog,
    eJackConnTypeMultichannelAnalogDIN,
    eJackConnTypeXlrProfessional,
    eJackConnTypeRJ11Modem,
    eJackConnTypeCombination
}
PaWasapiJackConnectionType;


/* Jack geometric location. */
typedef enum PaWasapiJackGeoLocation
{
    eJackGeoLocUnk = 0,
    eJackGeoLocRear = 0x1, /* matches EPcxGeoLocation::eGeoLocRear */
    eJackGeoLocFront,
    eJackGeoLocLeft,
    eJackGeoLocRight,
    eJackGeoLocTop,
    eJackGeoLocBottom,
    eJackGeoLocRearPanel,
    eJackGeoLocRiser,
    eJackGeoLocInsideMobileLid,
    eJackGeoLocDrivebay,
    eJackGeoLocHDMI,
    eJackGeoLocOutsideMobileLid,
    eJackGeoLocATAPI,
    eJackGeoLocReserved5,
    eJackGeoLocReserved6,
}
PaWasapiJackGeoLocation;


/* Jack general location. */
typedef enum PaWasapiJackGenLocation
{
    eJackGenLocPrimaryBox = 0,
    eJackGenLocInternal,
    eJackGenLocSeparate,
    eJackGenLocOther
}
PaWasapiJackGenLocation;


/* Jack's type of port. */
typedef enum PaWasapiJackPortConnection
{
    eJackPortConnJack = 0,
    eJackPortConnIntegratedDevice,
    eJackPortConnBothIntegratedAndJack,
    eJackPortConnUnknown
}
PaWasapiJackPortConnection;


/* Thread priority. */
typedef enum PaWasapiThreadPriority
{
    eThreadPriorityNone = 0,
    eThreadPriorityAudio,           //!< Default for Shared mode.
    eThreadPriorityCapture,
    eThreadPriorityDistribution,
    eThreadPriorityGames,
    eThreadPriorityPlayback,
    eThreadPriorityProAudio,        //!< Default for Exclusive mode.
    eThreadPriorityWindowManager
}
PaWasapiThreadPriority;


/* Stream descriptor. */
typedef struct PaWasapiJackDescription
{
    unsigned long              channelMapping;
    unsigned long              color; /* derived from macro: #define RGB(r,g,b) ((COLORREF)(((BYTE)(r)|((WORD)((BYTE)(g))<<8))|(((DWORD)(BYTE)(b))<<16))) */
    PaWasapiJackConnectionType connectionType;
    PaWasapiJackGeoLocation    geoLocation;
    PaWasapiJackGenLocation    genLocation;
    PaWasapiJackPortConnection portConnection;
    unsigned int               isConnected;
}
PaWasapiJackDescription;


/** Stream category.
   Note:
    - values are equal to WASAPI AUDIO_STREAM_CATEGORY enum
    - supported since Windows 8.0, noop on earlier versions
    - values 1,2 are deprecated on Windows 10 and not included into enumeration

 @version Available as of 19.6.0
*/
typedef enum PaWasapiStreamCategory
{
    eAudioCategoryOther           = 0,
    eAudioCategoryCommunications  = 3,
    eAudioCategoryAlerts          = 4,
    eAudioCategorySoundEffects    = 5,
    eAudioCategoryGameEffects     = 6,
    eAudioCategoryGameMedia       = 7,
    eAudioCategoryGameChat        = 8,
    eAudioCategorySpeech          = 9,
    eAudioCategoryMovie           = 10,
    eAudioCategoryMedia           = 11
}
PaWasapiStreamCategory;


/** Stream option.
   Note:
    - values are equal to WASAPI AUDCLNT_STREAMOPTIONS enum
    - supported since Windows 8.1, noop on earlier versions

 @version Available as of 19.6.0
*/
typedef enum PaWasapiStreamOption
{
    eStreamOptionNone        = 0, //!< default
    eStreamOptionRaw         = 1, //!< bypass WASAPI Audio Engine DSP effects, supported since Windows 8.1
    eStreamOptionMatchFormat = 2  //!< force WASAPI Audio Engine into a stream format, supported since Windows 10
}
PaWasapiStreamOption;


/* Stream descriptor. */
typedef struct PaWasapiStreamInfo
{
    unsigned long size;             /**< sizeof(PaWasapiStreamInfo) */
    PaHostApiTypeId hostApiType;    /**< paWASAPI */
    unsigned long version;          /**< 1 */

    unsigned long flags;            /**< collection of PaWasapiFlags */

    /** Support for WAVEFORMATEXTENSIBLE channel masks. If flags contains
       paWinWasapiUseChannelMask this allows you to specify which speakers
       to address in a multichannel stream. Constants for channelMask
       are specified in pa_win_waveformat.h. Will be used only if
       paWinWasapiUseChannelMask flag is specified.
    */
    PaWinWaveFormatChannelMask channelMask;

    /** Delivers raw data to callback obtained from GetBuffer() methods skipping
       internal PortAudio processing inventory completely. userData parameter will
       be the same that was passed to Pa_OpenStream method. Will be used only if
       paWinWasapiRedirectHostProcessor flag is specified.
    */
    PaWasapiHostProcessorCallback hostProcessorOutput;
    PaWasapiHostProcessorCallback hostProcessorInput;

    /** Specifies thread priority explicitly. Will be used only if paWinWasapiThreadPriority flag
       is specified.

       Please note, if Input/Output streams are opened simultaneously (Full-Duplex mode)
       you shall specify same value for threadPriority or othervise one of the values will be used
       to setup thread priority.
    */
    PaWasapiThreadPriority threadPriority;

    /** Stream category.
     @see PaWasapiStreamCategory
     @version Available as of 19.6.0
    */
    PaWasapiStreamCategory streamCategory;

    /** Stream option.
     @see PaWasapiStreamOption
     @version Available as of 19.6.0
    */
    PaWasapiStreamOption streamOption;
}
PaWasapiStreamInfo;


/** Returns pointer to WASAPI's IAudioClient object of the stream.

 @param pStream      Pointer to PaStream object.
 @param pAudioClient Pointer to pointer of IAudioClient.
 @param bOutput      TRUE (1) for output stream, FALSE (0) for input stream.

 @return Error code indicating success or failure.
*/
PaError PaWasapi_GetAudioClient( PaStream *pStream, void **pAudioClient, int bOutput );


/** Update device list.

    This function is available if PA_WASAPI_MAX_CONST_DEVICE_COUNT is defined during compile time
    with maximum constant WASAPI device count (recommended value - 32).
    If PA_WASAPI_MAX_CONST_DEVICE_COUNT is set to 0 (or not defined) during compile time the implementation
    will not define PaWasapi_UpdateDeviceList() and thus updating device list can only be possible by calling
    Pa_Terminate() and then Pa_Initialize().

 @return Error code indicating success or failure.
*/
PaError PaWasapi_UpdateDeviceList();


/** Get current audio format of the device assigned to the opened stream.

    Format is represented by PaWinWaveFormat or WAVEFORMATEXTENSIBLE structure.
    Use this function to reconfirm format if PA's processor is overridden and
    paWinWasapiRedirectHostProcessor flag is specified.

 @param pStream    Pointer to PaStream object.
 @param pFormat    Pointer to PaWinWaveFormat or WAVEFORMATEXTENSIBLE structure.
 @param formatSize Size of PaWinWaveFormat or WAVEFORMATEXTENSIBLE structure in bytes.
 @param bOutput    TRUE (1) for output stream, FALSE (0) for input stream.

 @return Non-negative value indicating the number of bytes copied into format descriptor
         or, a PaErrorCode (which is always negative) if PortAudio is not initialized
         or an error is encountered.
*/
int PaWasapi_GetDeviceCurrentFormat( PaStream *pStream, void *pFormat, unsigned int formatSize, int bOutput );


/** Get default audio format for the device in Shared Mode.

    Format is represented by PaWinWaveFormat or WAVEFORMATEXTENSIBLE structure and obtained
    by getting the device property with a PKEY_AudioEngine_DeviceFormat key.

 @param  pFormat    Pointer to PaWinWaveFormat or WAVEFORMATEXTENSIBLE structure.
 @param  formatSize Size of PaWinWaveFormat or WAVEFORMATEXTENSIBLE structure in bytes.
 @param  device     Device index.

 @return Non-negative value indicating the number of bytes copied into format descriptor
         or, a PaErrorCode (which is always negative) if PortAudio is not initialized
         or an error is encountered.
*/
int PaWasapi_GetDeviceDefaultFormat( void *pFormat, unsigned int formatSize, PaDeviceIndex device );


/** Get mix audio format for the device in Shared Mode.

    Format is represented by PaWinWaveFormat or WAVEFORMATEXTENSIBLE structureand obtained by
    IAudioClient::GetMixFormat.

 @param  pFormat    Pointer to PaWinWaveFormat or WAVEFORMATEXTENSIBLE structure.
 @param  formatSize Size of PaWinWaveFormat or WAVEFORMATEXTENSIBLE structure in bytes.
 @param  device     Device index.

 @return Non-negative value indicating the number of bytes copied into format descriptor
         or, a PaErrorCode (which is always negative) if PortAudio is not initialized
         or an error is encountered.
*/
int PaWasapi_GetDeviceMixFormat( void *pFormat, unsigned int formatSize, PaDeviceIndex device );


/** Get device role (PaWasapiDeviceRole enum).

 @param  device Device index.

 @return Non-negative value indicating device role or, a PaErrorCode (which is always negative)
         if PortAudio is not initialized or an error is encountered.
*/
int/*PaWasapiDeviceRole*/ PaWasapi_GetDeviceRole( PaDeviceIndex device );


/** Get device IMMDevice pointer

 @param device Device index.
 @param pAudioClient Pointer to pointer of IMMDevice.

 @return Error code indicating success or failure.
*/
PaError PaWasapi_GetIMMDevice( PaDeviceIndex device, void **pIMMDevice );


/** Boost thread priority of calling thread (MMCSS).

    Use it for Blocking Interface only inside the thread which makes calls to Pa_WriteStream/Pa_ReadStream.

 @param  pTask          Handle to pointer to priority task. Must be used with PaWasapi_RevertThreadPriority
                        method to revert thread priority to initial state.

 @param  priorityClass  Id of thread priority of PaWasapiThreadPriority type. Specifying
                        eThreadPriorityNone does nothing.

 @return Error code indicating success or failure.
 @see    PaWasapi_RevertThreadPriority
*/
PaError PaWasapi_ThreadPriorityBoost( void **pTask, PaWasapiThreadPriority priorityClass );


/** Boost thread priority of calling thread (MMCSS).

    Use it for Blocking Interface only inside the thread which makes calls to Pa_WriteStream/Pa_ReadStream.

 @param  pTask Task handle obtained by PaWasapi_BoostThreadPriority method.

 @return Error code indicating success or failure.
 @see    PaWasapi_BoostThreadPriority
*/
PaError PaWasapi_ThreadPriorityRevert( void *pTask );


/** Get number of frames per host buffer.

    It is max value of frames of WASAPI buffer which can be locked for operations.
    Use this method as helper to find out max values of inputFrames/outputFrames
    of PaWasapiHostProcessorCallback.

 @param  pStream Pointer to PaStream object.
 @param  pInput  Pointer to variable to receive number of input frames. Can be NULL.
 @param  pOutput Pointer to variable to receive number of output frames. Can be NULL.

 @return Error code indicating success or failure.
 @see    PaWasapiHostProcessorCallback
*/
PaError PaWasapi_GetFramesPerHostBuffer( PaStream *pStream, unsigned int *pInput, unsigned int *pOutput );


/** Get number of jacks associated with a WASAPI device.

    Use this method to determine if there are any jacks associated with the provided WASAPI device.
    Not all audio devices will support this capability. This is valid for both input and output devices.

 @note   Not available on UWP platform.

 @param  device     Device index.
 @param  pJackCount Pointer to variable to receive number of jacks.

 @return Error code indicating success or failure.
 @see    PaWasapi_GetJackDescription
 */
PaError PaWasapi_GetJackCount( PaDeviceIndex device, int *pJackCount );


/** Get the jack description associated with a WASAPI device and jack number.

    Before this function is called, use PaWasapi_GetJackCount to determine the
    number of jacks associated with device.  If jcount is greater than zero, then
    each jack from 0 to jcount can be queried with this function to get the jack
    description.

 @note   Not available on UWP platform.

 @param  device           Device index.
 @param  jackIndex        Jack index.
 @param  pJackDescription Pointer to PaWasapiJackDescription.

 @return Error code indicating success or failure.
 @see PaWasapi_GetJackCount
 */
PaError PaWasapi_GetJackDescription( PaDeviceIndex device, int jackIndex, PaWasapiJackDescription *pJackDescription );


/** Set stream state handler.

 @param  pStream        Pointer to PaStream object.
 @param  fnStateHandler Pointer to state handling function.
 @param  pUserData      Pointer to user data.

 @return Error code indicating success or failure.
*/
PaError PaWasapi_SetStreamStateHandler( PaStream *pStream, PaWasapiStreamStateCallback fnStateHandler, void *pUserData );


/** Set default device Id.

    By default implementation will use the DEVINTERFACE_AUDIO_RENDER and
    DEVINTERFACE_AUDIO_CAPTURE Ids if device Id is not provided explicitly. These default Ids
    will not allow to use Exclusive mode on UWP/WinRT platform and thus you must provide
    device Id explicitly via this API before calling the Pa_OpenStream().

    Device Ids on UWP platform are obtainable via:
    Windows::Media::Devices::MediaDevice::GetDefaultAudioRenderId() or
    Windows::Media::Devices::MediaDevice::GetDefaultAudioCaptureId() API.

    After the call completes, memory referenced by pointers can be freed, as implementation keeps its own copy.

    Call this function before calling Pa_IsFormatSupported() when Exclusive mode is requested.

    See an example in the IMPORTANT notes.

 @note   UWP/WinRT platform only.

 @param  pId     Device Id, pointer to the 16-bit Unicode string (WCHAR). If NULL then device Id
                 will be reset to the default, e.g. DEVINTERFACE_AUDIO_RENDER or DEVINTERFACE_AUDIO_CAPTURE.
 @param  bOutput TRUE (1) for output (render), FALSE (0) for input (capture).

 @return Error code indicating success or failure. Will return paIncompatibleStreamHostApi if library is not compiled
         for UWP/WinRT platform. If Id is longer than PA_WASAPI_DEVICE_ID_LEN characters paBufferTooBig will
         be returned.
*/
PaError PaWasapiWinrt_SetDefaultDeviceId( const unsigned short *pId, int bOutput );


/** Populate the device list.

    By default the implementation will rely on DEVINTERFACE_AUDIO_RENDER and DEVINTERFACE_AUDIO_CAPTURE as
    default devices. If device Id is provided by PaWasapiWinrt_SetDefaultDeviceId() then those
    device Ids will be used as default and only devices for the device list.

    By populating the device list you can provide an additional available audio devices of the system to PA
    which are obtainable by:
    Windows::Devices::Enumeration::DeviceInformation::FindAllAsync(selector) where selector is obtainable by
    Windows::Media::Devices::MediaDevice::GetAudioRenderSelector() or
    Windows::Media::Devices::MediaDevice::GetAudioCaptureSelector() API.

    After the call completes, memory referenced by pointers can be freed, as implementation keeps its own copy.

    You must call PaWasapi_UpdateDeviceList() to update the internal device list of the implementation after
    calling this function.

    See an example in the IMPORTANT notes.

 @note   UWP/WinRT platform only.

 @param  pId     Array of device Ids, pointer to the array of pointers of 16-bit Unicode string (WCHAR). If NULL
                 and count is also 0 then device Ids will be reset to the default. Required.
 @param  pName   Array of device Names, pointer to the array of pointers of 16-bit Unicode string (WCHAR). Optional.
 @param  pRole   Array of device Roles, see PaWasapiDeviceRole and PaWasapi_GetDeviceRole() for more details. Optional.
 @param  count   Number of devices, the number of array elements (pId, pName, pRole). Maximum count of devices
                 is limited by PA_WASAPI_DEVICE_MAX_COUNT.
 @param  bOutput TRUE (1) for output (render), FALSE (0) for input (capture).

 @return Error code indicating success or failure. Will return paIncompatibleStreamHostApi if library is not compiled
         for UWP/WinRT platform. If Id is longer than PA_WASAPI_DEVICE_ID_LEN characters paBufferTooBig will
         be returned. If Name is longer than PA_WASAPI_DEVICE_NAME_LEN characters paBufferTooBig will
         be returned.
*/
PaError PaWasapiWinrt_PopulateDeviceList( const unsigned short **pId, const unsigned short **pName,
    const PaWasapiDeviceRole *pRole, unsigned int count, int bOutput );


/*
    IMPORTANT:

    WASAPI is implemented for Callback and Blocking interfaces. It supports Shared and Exclusive
    share modes.

    Exclusive Mode:

        Exclusive mode allows to deliver audio data directly to hardware bypassing
        software mixing.
        Exclusive mode is specified by 'paWinWasapiExclusive' flag.

    Callback Interface:

        Provides best audio quality with low latency. Callback interface is implemented in
        two versions:

        1) Event-Driven:
        This is the most powerful WASAPI implementation which provides glitch-free
        audio at around 3ms latency in Exclusive mode. Lowest possible latency for this mode is
        3 ms for HD Audio class audio chips. For the Shared mode latency can not be
        lower than 20 ms.

        2) Poll-Driven:
        Polling is another 2-nd method to operate with WASAPI. It is less efficient than Event-Driven
        and provides latency at around 10-13ms. Polling must be used to overcome a system bug
        under Windows Vista x64 when application is WOW64(32-bit) and Event-Driven method simply
        times out (event handle is never signalled on buffer completion). Please note, such WOW64 bug
        does not exist in Vista x86 or Windows 7.
        Polling can be setup by specifying 'paWinWasapiPolling' flag. Our WASAPI implementation detects
        WOW64 bug and sets 'paWinWasapiPolling' automatically.

    Thread priority:

        Normally thread priority is set automatically and does not require modification. Although
        if user wants some tweaking thread priority can be modified by setting 'paWinWasapiThreadPriority'
        flag and specifying 'PaWasapiStreamInfo::threadPriority' with value from PaWasapiThreadPriority
        enum.

    Blocking Interface:

        Blocking interface is implemented but due to above described Poll-Driven method can not
        deliver lowest possible latency. Specifying too low latency in Shared mode will result in
        distorted audio although Exclusive mode adds stability.

    8.24 format:

        If paCustomFormat is specified as sample format then the implementation will understand it
        as valid 24-bits inside 32-bit container (e.g. wBitsPerSample = 32, Samples.wValidBitsPerSample = 24).

        By using paCustomFormat there will be small optimization when samples are be copied
        with Copy_24_To_24 by PA processor instead of conversion from packed 3-byte (24-bit) data
        with Int24_To_Int32.

    Pa_IsFormatSupported:

        To check format with correct Share Mode (Exclusive/Shared) you must supply PaWasapiStreamInfo
        with flags paWinWasapiExclusive set through member of PaStreamParameters::hostApiSpecificStreamInfo
        structure.

        If paWinWasapiExplicitSampleFormat flag is provided then implementation will not try to select
        suitable close format and will return an error instead of paFormatIsSupported. By specifying
        paWinWasapiExplicitSampleFormat flag it is possible to find out what sample formats are
        supported by Exclusive or Shared modes.

    Pa_OpenStream:

        To set desired Share Mode (Exclusive/Shared) you must supply
        PaWasapiStreamInfo with flags paWinWasapiExclusive set through member of
        PaStreamParameters::hostApiSpecificStreamInfo structure.

    Coding style for parameters and structure members of the public API:

        1) bXXX - boolean, [1 (TRUE), 0 (FALSE)]
        2) pXXX - pointer
        3) fnXXX - pointer to function
        4) structure members are never prefixed with a type distinguisher


    UWP/WinRT:

        This platform has number of limitations which do not allow to enumerate audio devices without
        an additional external help. Enumeration is possible though from C++/CX, check the related API
        Windows::Devices::Enumeration::DeviceInformation::FindAllAsync().

        The main limitation is an absence of the device enumeration from inside the PA's implementation.
        This problem can be solved by using the following functions:

        PaWasapiWinrt_SetDefaultDeviceId() - to set default input/output device,
        PaWasapiWinrt_PopulateDeviceList() - to populate device list with devices.

        Here is an example of populating the device list which can also be updated dynamically depending on
        whether device was removed from or added to the system:

        ----------------

        std::vector<const UINT16 *> ids, names;
        std::vector<PaWasapiDeviceRole> role;

        ids.resize(count);
        names.resize(count);
        role.resize(count);

        for (UINT32 i = 0; i < count; ++i)
        {
            ids[i]   = (const UINT16 *)device_ids[i].c_str();
            names[i] = (const UINT16 *)device_names[i].c_str();
            role[i]  = eRoleUnknownFormFactor;
        }

        PaWasapiWinrt_SetDefaultDeviceId((const UINT16 *)default_device_id.c_str(), !capture);
        PaWasapiWinrt_PopulateDeviceList(ids.data(), names.data(), role.data(), count, !capture);
        PaWasapi_UpdateDeviceList();

        ----------------
*/

#ifdef __cplusplus
}
#endif /* __cplusplus */

#endif /* PA_WIN_WASAPI_H */