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