PortAudio  2.0
pa_win_wasapi.h
Go to the documentation of this file.
1 #ifndef PA_WIN_WASAPI_H
2 #define PA_WIN_WASAPI_H
3 /*
4  * $Id: $
5  * PortAudio Portable Real-Time Audio Library
6  * DirectSound specific extensions
7  *
8  * Copyright (c) 1999-2007 Ross Bencina and Phil Burk
9  *
10  * Permission is hereby granted, free of charge, to any person obtaining
11  * a copy of this software and associated documentation files
12  * (the "Software"), to deal in the Software without restriction,
13  * including without limitation the rights to use, copy, modify, merge,
14  * publish, distribute, sublicense, and/or sell copies of the Software,
15  * and to permit persons to whom the Software is furnished to do so,
16  * subject to the following conditions:
17  *
18  * The above copyright notice and this permission notice shall be
19  * included in all copies or substantial portions of the Software.
20  *
21  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
22  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
23  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
24  * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR
25  * ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
26  * CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
27  * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
28  */
29 
30 /*
31  * The text above constitutes the entire PortAudio license; however,
32  * the PortAudio community also makes the following non-binding requests:
33  *
34  * Any person wishing to distribute modifications to the Software is
35  * requested to send the modifications to the original developer so that
36  * they can be incorporated into the canonical version. It is also
37  * requested that these non-binding requests be included along with the
38  * license above.
39  */
40 
46 #include "portaudio.h"
47 #include "pa_win_waveformat.h"
48 
49 #ifdef __cplusplus
50 extern "C"
51 {
52 #endif /* __cplusplus */
53 
54 
55 /* Setup flags */
56 typedef enum PaWasapiFlags
57 {
58  /* puts WASAPI into exclusive mode */
59  paWinWasapiExclusive = (1 << 0),
60 
61  /* allows to skip internal PA processing completely */
62  paWinWasapiRedirectHostProcessor = (1 << 1),
63 
64  /* assigns custom channel mask */
65  paWinWasapiUseChannelMask = (1 << 2),
66 
67  /* selects non-Event driven method of data read/write
68  Note: WASAPI Event driven core is capable of 2ms latency!!!, but Polling
69  method can only provide 15-20ms latency. */
70  paWinWasapiPolling = (1 << 3),
71 
72  /* forces custom thread priority setting, must be used if PaWasapiStreamInfo::threadPriority
73  is set to a custom value */
74  paWinWasapiThreadPriority = (1 << 4)
75 }
76 PaWasapiFlags;
77 #define paWinWasapiExclusive (paWinWasapiExclusive)
78 #define paWinWasapiRedirectHostProcessor (paWinWasapiRedirectHostProcessor)
79 #define paWinWasapiUseChannelMask (paWinWasapiUseChannelMask)
80 #define paWinWasapiPolling (paWinWasapiPolling)
81 #define paWinWasapiThreadPriority (paWinWasapiThreadPriority)
82 
83 
84 /* Host processor. Allows to skip internal PA processing completely.
85  You must set paWinWasapiRedirectHostProcessor flag to PaWasapiStreamInfo::flags member
86  in order to have host processor redirected to your callback.
87  Use with caution! inputFrames and outputFrames depend solely on final device setup.
88  To query maximal values of inputFrames/outputFrames use PaWasapi_GetFramesPerHostBuffer.
89 */
90 typedef void (*PaWasapiHostProcessorCallback) (void *inputBuffer, long inputFrames,
91  void *outputBuffer, long outputFrames,
92  void *userData);
93 
94 /* Device role. */
95 typedef enum PaWasapiDeviceRole
96 {
97  eRoleRemoteNetworkDevice = 0,
98  eRoleSpeakers,
99  eRoleLineLevel,
100  eRoleHeadphones,
101  eRoleMicrophone,
102  eRoleHeadset,
103  eRoleHandset,
104  eRoleUnknownDigitalPassthrough,
105  eRoleSPDIF,
106  eRoleHDMI,
107  eRoleUnknownFormFactor
108 }
109 PaWasapiDeviceRole;
110 
111 
112 /* Jack connection type. */
113 typedef enum PaWasapiJackConnectionType
114 {
115  eJackConnTypeUnknown,
116  eJackConnType3Point5mm,
117  eJackConnTypeQuarter,
118  eJackConnTypeAtapiInternal,
119  eJackConnTypeRCA,
120  eJackConnTypeOptical,
121  eJackConnTypeOtherDigital,
122  eJackConnTypeOtherAnalog,
123  eJackConnTypeMultichannelAnalogDIN,
124  eJackConnTypeXlrProfessional,
125  eJackConnTypeRJ11Modem,
126  eJackConnTypeCombination
127 }
128 PaWasapiJackConnectionType;
129 
130 
131 /* Jack geometric location. */
132 typedef enum PaWasapiJackGeoLocation
133 {
134  eJackGeoLocUnk = 0,
135  eJackGeoLocRear = 0x1, /* matches EPcxGeoLocation::eGeoLocRear */
136  eJackGeoLocFront,
137  eJackGeoLocLeft,
138  eJackGeoLocRight,
139  eJackGeoLocTop,
140  eJackGeoLocBottom,
141  eJackGeoLocRearPanel,
142  eJackGeoLocRiser,
143  eJackGeoLocInsideMobileLid,
144  eJackGeoLocDrivebay,
145  eJackGeoLocHDMI,
146  eJackGeoLocOutsideMobileLid,
147  eJackGeoLocATAPI,
148  eJackGeoLocReserved5,
149  eJackGeoLocReserved6,
150 }
151 PaWasapiJackGeoLocation;
152 
153 
154 /* Jack general location. */
155 typedef enum PaWasapiJackGenLocation
156 {
157  eJackGenLocPrimaryBox = 0,
158  eJackGenLocInternal,
159  eJackGenLocSeparate,
160  eJackGenLocOther
161 }
162 PaWasapiJackGenLocation;
163 
164 
165 /* Jack's type of port. */
166 typedef enum PaWasapiJackPortConnection
167 {
168  eJackPortConnJack = 0,
169  eJackPortConnIntegratedDevice,
170  eJackPortConnBothIntegratedAndJack,
171  eJackPortConnUnknown
172 }
173 PaWasapiJackPortConnection;
174 
175 
176 /* Thread priority. */
178 {
179  eThreadPriorityNone = 0,
181  eThreadPriorityCapture,
182  eThreadPriorityDistribution,
183  eThreadPriorityGames,
184  eThreadPriorityPlayback,
186  eThreadPriorityWindowManager
187 }
189 
190 
191 /* Stream descriptor. */
192 typedef struct PaWasapiJackDescription
193 {
194  unsigned long channelMapping;
195  unsigned long color; /* derived from macro: #define RGB(r,g,b) ((COLORREF)(((BYTE)(r)|((WORD)((BYTE)(g))<<8))|(((DWORD)(BYTE)(b))<<16))) */
196  PaWasapiJackConnectionType connectionType;
197  PaWasapiJackGeoLocation geoLocation;
198  PaWasapiJackGenLocation genLocation;
199  PaWasapiJackPortConnection portConnection;
200  unsigned int isConnected;
201 }
203 
204 
214 {
215  eAudioCategoryOther = 0,
216  eAudioCategoryCommunications = 3,
217  eAudioCategoryAlerts = 4,
218  eAudioCategorySoundEffects = 5,
219  eAudioCategoryGameEffects = 6,
220  eAudioCategoryGameMedia = 7,
221  eAudioCategoryGameChat = 8,
222  eAudioCategorySpeech = 9,
223  eAudioCategoryMovie = 10,
224  eAudioCategoryMedia = 11
225 }
227 
228 
237 {
241 }
243 
244 
245 /* Stream descriptor. */
246 typedef struct PaWasapiStreamInfo
247 {
248  unsigned long size;
250  unsigned long version;
252  unsigned long flags;
260  PaWinWaveFormatChannelMask channelMask;
261 
267  PaWasapiHostProcessorCallback hostProcessorOutput;
268  PaWasapiHostProcessorCallback hostProcessorInput;
269 
278 
284 
290 }
292 
293 
304 
305 
317 int PaWasapi_GetDeviceDefaultFormat( void *pFormat, unsigned int nFormatSize, PaDeviceIndex nDevice );
318 
319 
327 int/*PaWasapiDeviceRole*/ PaWasapi_GetDeviceRole( PaDeviceIndex nDevice );
328 
329 
342 PaError PaWasapi_ThreadPriorityBoost( void **hTask, PaWasapiThreadPriority nPriorityClass );
343 
344 
353 
354 
365 PaError PaWasapi_GetFramesPerHostBuffer( PaStream *pStream, unsigned int *nInput, unsigned int *nOutput );
366 
367 
377 PaError PaWasapi_GetJackCount(PaDeviceIndex nDevice, int *jcount);
378 
379 
392 PaError PaWasapi_GetJackDescription(PaDeviceIndex nDevice, int jindex, PaWasapiJackDescription *pJackDescription);
393 
394 
395 /*
396  IMPORTANT:
397 
398  WASAPI is implemented for Callback and Blocking interfaces. It supports Shared and Exclusive
399  share modes.
400 
401  Exclusive Mode:
402 
403  Exclusive mode allows to deliver audio data directly to hardware bypassing
404  software mixing.
405  Exclusive mode is specified by 'paWinWasapiExclusive' flag.
406 
407  Callback Interface:
408 
409  Provides best audio quality with low latency. Callback interface is implemented in
410  two versions:
411 
412  1) Event-Driven:
413  This is the most powerful WASAPI implementation which provides glitch-free
414  audio at around 3ms latency in Exclusive mode. Lowest possible latency for this mode is
415  3 ms for HD Audio class audio chips. For the Shared mode latency can not be
416  lower than 20 ms.
417 
418  2) Poll-Driven:
419  Polling is another 2-nd method to operate with WASAPI. It is less efficient than Event-Driven
420  and provides latency at around 10-13ms. Polling must be used to overcome a system bug
421  under Windows Vista x64 when application is WOW64(32-bit) and Event-Driven method simply
422  times out (event handle is never signalled on buffer completion). Please note, such WOW64 bug
423  does not exist in Vista x86 or Windows 7.
424  Polling can be setup by speciying 'paWinWasapiPolling' flag. Our WASAPI implementation detects
425  WOW64 bug and sets 'paWinWasapiPolling' automatically.
426 
427  Thread priority:
428 
429  Normally thread priority is set automatically and does not require modification. Although
430  if user wants some tweaking thread priority can be modified by setting 'paWinWasapiThreadPriority'
431  flag and specifying 'PaWasapiStreamInfo::threadPriority' with value from PaWasapiThreadPriority
432  enum.
433 
434  Blocking Interface:
435 
436  Blocking interface is implemented but due to above described Poll-Driven method can not
437  deliver lowest possible latency. Specifying too low latency in Shared mode will result in
438  distorted audio although Exclusive mode adds stability.
439 
440  Pa_IsFormatSupported:
441 
442  To check format with correct Share Mode (Exclusive/Shared) you must supply
443  PaWasapiStreamInfo with flags paWinWasapiExclusive set through member of
444  PaStreamParameters::hostApiSpecificStreamInfo structure.
445 
446  Pa_OpenStream:
447 
448  To set desired Share Mode (Exclusive/Shared) you must supply
449  PaWasapiStreamInfo with flags paWinWasapiExclusive set through member of
450  PaStreamParameters::hostApiSpecificStreamInfo structure.
451 */
452 
453 #ifdef __cplusplus
454 }
455 #endif /* __cplusplus */
456 
457 #endif /* PA_WIN_WASAPI_H */