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 */
60 
61  /* allows to skip internal PA processing completely */
63 
64  /* assigns custom channel mask */
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 custom value. */
75 }
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 {
108 }
110 
111 
112 /* Jack connection type */
114 {
127 }
129 
130 
131 /* Jack geometric location */
133 {
135  eJackGeoLocRear = 0x1, /* matches EPcxGeoLocation::eGeoLocRear */
150 }
152 
153 
154 /* Jack general location */
156 {
161 }
163 
164 
165 /* Jack's type of port */
167 {
172 }
174 
175 
176 /* Thread priority */
178 {
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))) */
200  unsigned int isConnected;
201 }
203 
204 
205 /* Stream descriptor. */
206 typedef struct PaWasapiStreamInfo
207 {
208  unsigned long size;
210  unsigned long version;
212  unsigned long flags;
214  /* Support for WAVEFORMATEXTENSIBLE channel masks. If flags contains
215  paWinWasapiUseChannelMask this allows you to specify which speakers
216  to address in a multichannel stream. Constants for channelMask
217  are specified in pa_win_waveformat.h. Will be used only if
218  paWinWasapiUseChannelMask flag is specified.
219  */
221 
222  /* Delivers raw data to callback obtained from GetBuffer() methods skipping
223  internal PortAudio processing inventory completely. userData parameter will
224  be the same that was passed to Pa_OpenStream method. Will be used only if
225  paWinWasapiRedirectHostProcessor flag is specified.
226  */
229 
230  /* Specifies thread priority explicitly. Will be used only if paWinWasapiThreadPriority flag
231  is specified.
232 
233  Please note, if Input/Output streams are opened simultaniously (Full-Duplex mode)
234  you shall specify same value for threadPriority or othervise one of the values will be used
235  to setup thread priority.
236  */
238 }
240 
241 
253 int PaWasapi_GetDeviceDefaultFormat( void *pFormat, unsigned int nFormatSize, PaDeviceIndex nDevice );
254 
255 
263 int/*PaWasapiDeviceRole*/ PaWasapi_GetDeviceRole( PaDeviceIndex nDevice );
264 
265 
278 PaError PaWasapi_ThreadPriorityBoost( void **hTask, PaWasapiThreadPriority nPriorityClass );
279 
280 
289 
290 
301 PaError PaWasapi_GetFramesPerHostBuffer( PaStream *pStream, unsigned int *nInput, unsigned int *nOutput );
302 
303 
312 PaError PaWasapi_GetJackCount(PaDeviceIndex nDevice, int *jcount);
313 
314 
326 PaError PaWasapi_GetJackDescription(PaDeviceIndex nDevice, int jindex, PaWasapiJackDescription *pJackDescription);
327 
328 
329 /*
330  IMPORTANT:
331 
332  WASAPI is implemented for Callback and Blocking interfaces. It supports Shared and Exclusive
333  share modes.
334 
335  Exclusive Mode:
336 
337  Exclusive mode allows to deliver audio data directly to hardware bypassing
338  software mixing.
339  Exclusive mode is specified by 'paWinWasapiExclusive' flag.
340 
341  Callback Interface:
342 
343  Provides best audio quality with low latency. Callback interface is implemented in
344  two versions:
345 
346  1) Event-Driven:
347  This is the most powerful WASAPI implementation which provides glitch-free
348  audio at around 3ms latency in Exclusive mode. Lowest possible latency for this mode is
349  3 ms for HD Audio class audio chips. For the Shared mode latency can not be
350  lower than 20 ms.
351 
352  2) Poll-Driven:
353  Polling is another 2-nd method to operate with WASAPI. It is less efficient than Event-Driven
354  and provides latency at around 10-13ms. Polling must be used to overcome a system bug
355  under Windows Vista x64 when application is WOW64(32-bit) and Event-Driven method simply
356  times out (event handle is never signalled on buffer completion). Please note, such WOW64 bug
357  does not exist in Vista x86 or Windows 7.
358  Polling can be setup by speciying 'paWinWasapiPolling' flag. Our WASAPI implementation detects
359  WOW64 bug and sets 'paWinWasapiPolling' automatically.
360 
361  Thread priority:
362 
363  Normally thread priority is set automatically and does not require modification. Although
364  if user wants some tweaking thread priority can be modified by setting 'paWinWasapiThreadPriority'
365  flag and specifying 'PaWasapiStreamInfo::threadPriority' with value from PaWasapiThreadPriority
366  enum.
367 
368  Blocking Interface:
369 
370  Blocking interface is implemented but due to above described Poll-Driven method can not
371  deliver lowest possible latency. Specifying too low latency in Shared mode will result in
372  distorted audio although Exclusive mode adds stability.
373 
374  Pa_IsFormatSupported:
375 
376  To check format with correct Share Mode (Exclusive/Shared) you must supply
377  PaWasapiStreamInfo with flags paWinWasapiExclusive set through member of
378  PaStreamParameters::hostApiSpecificStreamInfo structure.
379 
380  Pa_OpenStream:
381 
382  To set desired Share Mode (Exclusive/Shared) you must supply
383  PaWasapiStreamInfo with flags paWinWasapiExclusive set through member of
384  PaStreamParameters::hostApiSpecificStreamInfo structure.
385 */
386 
387 #ifdef __cplusplus
388 }
389 #endif /* __cplusplus */
390 
391 #endif /* PA_WIN_WASAPI_H */

Generated for PortAudio by  doxygen1.8.1.1