readme.txt (4227B)
1 Notes about WDM-KS host API 2 --------------------------- 3 4 Status history 5 -------------- 6 16th January 2011: 7 Added support for WaveRT device API (Vista and later) for even lesser 8 latency support. 9 10 10th November 2005: 11 Made following changes: 12 * OpenStream: Try all PaSampleFormats internally if the the chosen 13 format is not supported natively. This fixed several problems 14 with soundcards that did not take kindly to using 24-bit 3-byte formats. 15 * OpenStream: Make the minimum framesPerHostIBuffer (and framesPerHostOBuffer) 16 the default frameSize for the playback/recording pin. 17 * ProcessingThread: Added a switch to only call PaUtil_EndBufferProcessing 18 if the total input frames equals the total output frames 19 20 5th September 2004: 21 This is the first public version of the code. It should be considered 22 an alpha release with zero guarantee not to crash on any particular 23 system. So far it has only been tested in the author's development 24 environment, which means a Win2k/SP2 PIII laptop with integrated 25 SoundMAX driver and USB Tascam US-428 compiled with both MinGW 26 (GCC 3.3) and MSVC++6 using the MS DirectX 9 SDK. 27 It has been most widely tested with the MinGW build, with most of the 28 test programs (particularly paqa_devs and paqa_errs) passing. 29 There are some notable failures: patest_out_underflow and both of the 30 blocking I/O tests (as blocking I/O is not implemented). 31 At this point the code needs to be tested with a much wider variety 32 of configurations and feedback provided from testers regarding 33 both working and failing cases. 34 35 What is the WDM-KS host API? 36 ---------------------------- 37 PortAudio for Windows currently has 3 functional host implementations. 38 MME uses the oldest Windows audio API which does not offer good 39 play/record latency. 40 DirectX improves this, but still imposes a penalty 41 of 10s of milliseconds due to the system mixing of streams from 42 multiple applications. 43 ASIO offers very good latency, but requires special drivers which are 44 not always available for cheaper audio hardware. Also, when ASIO 45 drivers are available, they are not always so robust because they 46 bypass all of the standardised Windows device driver architecture 47 and hit the hardware their own way. 48 Alternatively there are a couple of free (but closed source) ASIO 49 implementations which connect to the lower level Windows 50 "Kernel Streaming" API, but again these require special installation 51 by the user, and can be limited in functionality or difficult to use. 52 53 This is where the PortAudio "WDM-KS" host implementation comes in. 54 It directly connects PortAudio to the same Kernel Streaming API which 55 those ASIO bridges use. This avoids the mixing penatly of DirectX, 56 giving at least as good latency as any ASIO driver, but it has the 57 advantage of working with ANY Windows audio hardware which is available 58 through the normal MME/DirectX routes without the user requiring 59 any additional device drivers to be installed, and allowing all 60 device selection to be done through the normal PortAudio API. 61 62 Note that in general you should only be using this host API if your 63 application has a real requirement for very low latency audio (<20ms), 64 either because you are generating sounds in real-time based upon 65 user input, or you a processing recorded audio in real time. 66 67 The only thing to be aware of is that using the KS interface will 68 block that device from being used by the rest of system through 69 the higher level APIs, or conversely, if the system is using 70 a device, the KS API will not be able to use it. MS recommend that 71 you should keep the device open only when your application has focus. 72 In PortAudio terms, this means having a stream Open on a WDMKS device. 73 74 Usage 75 ----- 76 To add the WDMKS backend to your program which is already using 77 PortAudio, you must define PA_USE_WDMKS=1 in your build file, 78 and include the pa_win_wdmks\pa_win_wdmks.c into your build. 79 The file should compile in both C and C++. 80 You will need a DirectX SDK installed on your system for the 81 ks.h and ksmedia.h header files. 82 You will need to link to the system "setupapi" library. 83 Note that if you use MinGW, you will get more warnings from 84 the DX header files when using GCC(C), and still a few warnings 85 with G++(CPP).