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 
305 int PaWasapi_GetDeviceDefaultFormat( void *pFormat, unsigned int nFormatSize, PaDeviceIndex nDevice );
306 
307 
315 int/*PaWasapiDeviceRole*/ PaWasapi_GetDeviceRole( PaDeviceIndex nDevice );
316 
317 
330 PaError PaWasapi_ThreadPriorityBoost( void **hTask, PaWasapiThreadPriority nPriorityClass );
331 
332 
341 
342 
353 PaError PaWasapi_GetFramesPerHostBuffer( PaStream *pStream, unsigned int *nInput, unsigned int *nOutput );
354 
355 
364 PaError PaWasapi_GetJackCount(PaDeviceIndex nDevice, int *jcount);
365 
366 
378 PaError PaWasapi_GetJackDescription(PaDeviceIndex nDevice, int jindex, PaWasapiJackDescription *pJackDescription);
379 
380 
381 /*
382  IMPORTANT:
383 
384  WASAPI is implemented for Callback and Blocking interfaces. It supports Shared and Exclusive
385  share modes.
386 
387  Exclusive Mode:
388 
389  Exclusive mode allows to deliver audio data directly to hardware bypassing
390  software mixing.
391  Exclusive mode is specified by 'paWinWasapiExclusive' flag.
392 
393  Callback Interface:
394 
395  Provides best audio quality with low latency. Callback interface is implemented in
396  two versions:
397 
398  1) Event-Driven:
399  This is the most powerful WASAPI implementation which provides glitch-free
400  audio at around 3ms latency in Exclusive mode. Lowest possible latency for this mode is
401  3 ms for HD Audio class audio chips. For the Shared mode latency can not be
402  lower than 20 ms.
403 
404  2) Poll-Driven:
405  Polling is another 2-nd method to operate with WASAPI. It is less efficient than Event-Driven
406  and provides latency at around 10-13ms. Polling must be used to overcome a system bug
407  under Windows Vista x64 when application is WOW64(32-bit) and Event-Driven method simply
408  times out (event handle is never signalled on buffer completion). Please note, such WOW64 bug
409  does not exist in Vista x86 or Windows 7.
410  Polling can be setup by speciying 'paWinWasapiPolling' flag. Our WASAPI implementation detects
411  WOW64 bug and sets 'paWinWasapiPolling' automatically.
412 
413  Thread priority:
414 
415  Normally thread priority is set automatically and does not require modification. Although
416  if user wants some tweaking thread priority can be modified by setting 'paWinWasapiThreadPriority'
417  flag and specifying 'PaWasapiStreamInfo::threadPriority' with value from PaWasapiThreadPriority
418  enum.
419 
420  Blocking Interface:
421 
422  Blocking interface is implemented but due to above described Poll-Driven method can not
423  deliver lowest possible latency. Specifying too low latency in Shared mode will result in
424  distorted audio although Exclusive mode adds stability.
425 
426  Pa_IsFormatSupported:
427 
428  To check format with correct Share Mode (Exclusive/Shared) you must supply
429  PaWasapiStreamInfo with flags paWinWasapiExclusive set through member of
430  PaStreamParameters::hostApiSpecificStreamInfo structure.
431 
432  Pa_OpenStream:
433 
434  To set desired Share Mode (Exclusive/Shared) you must supply
435  PaWasapiStreamInfo with flags paWinWasapiExclusive set through member of
436  PaStreamParameters::hostApiSpecificStreamInfo structure.
437 */
438 
439 #ifdef __cplusplus
440 }
441 #endif /* __cplusplus */
442 
443 #endif /* PA_WIN_WASAPI_H */