PortAudio 2.0

pa_win_wasapi.h

Go to the documentation of this file.
00001 #ifndef PA_WIN_WASAPI_H
00002 #define PA_WIN_WASAPI_H
00003 /*
00004  * $Id:  $
00005  * PortAudio Portable Real-Time Audio Library
00006  * DirectSound specific extensions
00007  *
00008  * Copyright (c) 1999-2007 Ross Bencina and Phil Burk
00009  *
00010  * Permission is hereby granted, free of charge, to any person obtaining
00011  * a copy of this software and associated documentation files
00012  * (the "Software"), to deal in the Software without restriction,
00013  * including without limitation the rights to use, copy, modify, merge,
00014  * publish, distribute, sublicense, and/or sell copies of the Software,
00015  * and to permit persons to whom the Software is furnished to do so,
00016  * subject to the following conditions:
00017  *
00018  * The above copyright notice and this permission notice shall be
00019  * included in all copies or substantial portions of the Software.
00020  *
00021  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
00022  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
00023  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
00024  * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR
00025  * ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
00026  * CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
00027  * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
00028  */
00029 
00030 /*
00031  * The text above constitutes the entire PortAudio license; however, 
00032  * the PortAudio community also makes the following non-binding requests:
00033  *
00034  * Any person wishing to distribute modifications to the Software is
00035  * requested to send the modifications to the original developer so that
00036  * they can be incorporated into the canonical version. It is also 
00037  * requested that these non-binding requests be included along with the 
00038  * license above.
00039  */
00040 
00046 #include "portaudio.h"
00047 #include "pa_win_waveformat.h"
00048 
00049 #ifdef __cplusplus
00050 extern "C"
00051 {
00052 #endif /* __cplusplus */
00053 
00054 
00055 /* Setup flags */
00056 typedef enum PaWasapiFlags
00057 {
00058     /* puts WASAPI into exclusive mode */
00059     paWinWasapiExclusive                = (1 << 0),
00060 
00061     /* allows to skip internal PA processing completely */
00062     paWinWasapiRedirectHostProcessor    = (1 << 1),
00063 
00064     /* assigns custom channel mask */
00065     paWinWasapiUseChannelMask           = (1 << 2),
00066 
00067     /* selects non-Event driven method of data read/write
00068        Note: WASAPI Event driven core is capable of 2ms latency!!!, but Polling
00069              method can only provide 15-20ms latency. */
00070     paWinWasapiPolling                  = (1 << 3),
00071 
00072     /* forces custom thread priority setting. must be used if PaWasapiStreamInfo::threadPriority 
00073        is set to custom value. */
00074     paWinWasapiThreadPriority           = (1 << 4)
00075 }
00076 PaWasapiFlags;
00077 #define paWinWasapiExclusive             (paWinWasapiExclusive)
00078 #define paWinWasapiRedirectHostProcessor (paWinWasapiRedirectHostProcessor)
00079 #define paWinWasapiUseChannelMask        (paWinWasapiUseChannelMask)
00080 #define paWinWasapiPolling               (paWinWasapiPolling)
00081 #define paWinWasapiThreadPriority        (paWinWasapiThreadPriority)
00082 
00083 
00084 /* Host processor. Allows to skip internal PA processing completely. 
00085    You must set paWinWasapiRedirectHostProcessor flag to PaWasapiStreamInfo::flags member
00086    in order to have host processor redirected to your callback.
00087    Use with caution! inputFrames and outputFrames depend solely on final device setup.
00088    To query maximal values of inputFrames/outputFrames use PaWasapi_GetFramesPerHostBuffer.
00089 */
00090 typedef void (*PaWasapiHostProcessorCallback) (void *inputBuffer,  long inputFrames,
00091                                                void *outputBuffer, long outputFrames,
00092                                                void *userData);
00093 
00094 /* Device role */
00095 typedef enum PaWasapiDeviceRole
00096 {
00097     eRoleRemoteNetworkDevice = 0,
00098     eRoleSpeakers,
00099     eRoleLineLevel,
00100     eRoleHeadphones,
00101     eRoleMicrophone,
00102     eRoleHeadset,
00103     eRoleHandset,
00104     eRoleUnknownDigitalPassthrough,
00105     eRoleSPDIF,
00106     eRoleHDMI,
00107     eRoleUnknownFormFactor
00108 }
00109 PaWasapiDeviceRole;
00110 
00111 
00112 /* Jack connection type */
00113 typedef enum PaWasapiJackConnectionType
00114 {
00115     eJackConnTypeUnknown,
00116     eJackConnType3Point5mm,
00117     eJackConnTypeQuarter,
00118     eJackConnTypeAtapiInternal,
00119     eJackConnTypeRCA,
00120     eJackConnTypeOptical,
00121     eJackConnTypeOtherDigital,
00122     eJackConnTypeOtherAnalog,
00123     eJackConnTypeMultichannelAnalogDIN,
00124     eJackConnTypeXlrProfessional,
00125     eJackConnTypeRJ11Modem,
00126     eJackConnTypeCombination
00127 } 
00128 PaWasapiJackConnectionType;
00129 
00130 
00131 /* Jack geometric location */
00132 typedef enum PaWasapiJackGeoLocation
00133 {
00134         eJackGeoLocUnk = 0,
00135     eJackGeoLocRear = 0x1, /* matches EPcxGeoLocation::eGeoLocRear */
00136     eJackGeoLocFront,
00137     eJackGeoLocLeft,
00138     eJackGeoLocRight,
00139     eJackGeoLocTop,
00140     eJackGeoLocBottom,
00141     eJackGeoLocRearPanel,
00142     eJackGeoLocRiser,
00143     eJackGeoLocInsideMobileLid,
00144     eJackGeoLocDrivebay,
00145     eJackGeoLocHDMI,
00146     eJackGeoLocOutsideMobileLid,
00147     eJackGeoLocATAPI,
00148     eJackGeoLocReserved5,
00149     eJackGeoLocReserved6,
00150 } 
00151 PaWasapiJackGeoLocation;
00152 
00153 
00154 /* Jack general location */
00155 typedef enum PaWasapiJackGenLocation
00156 {
00157     eJackGenLocPrimaryBox = 0,
00158     eJackGenLocInternal,
00159     eJackGenLocSeparate,
00160     eJackGenLocOther
00161 } 
00162 PaWasapiJackGenLocation;
00163 
00164 
00165 /* Jack's type of port */
00166 typedef enum PaWasapiJackPortConnection
00167 {
00168     eJackPortConnJack = 0,
00169     eJackPortConnIntegratedDevice,
00170     eJackPortConnBothIntegratedAndJack,
00171     eJackPortConnUnknown
00172 } 
00173 PaWasapiJackPortConnection;
00174 
00175 
00176 /* Thread priority */
00177 typedef enum PaWasapiThreadPriority
00178 {
00179     eThreadPriorityNone = 0,
00180     eThreadPriorityAudio,            
00181     eThreadPriorityCapture,
00182     eThreadPriorityDistribution,
00183     eThreadPriorityGames,
00184     eThreadPriorityPlayback,
00185     eThreadPriorityProAudio,        
00186     eThreadPriorityWindowManager
00187 }
00188 PaWasapiThreadPriority;
00189 
00190 
00191 /* Stream descriptor. */
00192 typedef struct PaWasapiJackDescription 
00193 {
00194     unsigned long              channelMapping;
00195     unsigned long              color; /* derived from macro: #define RGB(r,g,b) ((COLORREF)(((BYTE)(r)|((WORD)((BYTE)(g))<<8))|(((DWORD)(BYTE)(b))<<16))) */
00196     PaWasapiJackConnectionType connectionType;
00197     PaWasapiJackGeoLocation    geoLocation;
00198     PaWasapiJackGenLocation    genLocation;
00199     PaWasapiJackPortConnection portConnection;
00200     unsigned int               isConnected;
00201 }
00202 PaWasapiJackDescription;
00203 
00204 
00205 /* Stream descriptor. */
00206 typedef struct PaWasapiStreamInfo 
00207 {
00208     unsigned long size;             
00209     PaHostApiTypeId hostApiType;    
00210     unsigned long version;          
00212     unsigned long flags;            
00214     /* Support for WAVEFORMATEXTENSIBLE channel masks. If flags contains
00215        paWinWasapiUseChannelMask this allows you to specify which speakers 
00216        to address in a multichannel stream. Constants for channelMask
00217        are specified in pa_win_waveformat.h. Will be used only if 
00218        paWinWasapiUseChannelMask flag is specified.
00219     */
00220     PaWinWaveFormatChannelMask channelMask;
00221 
00222     /* Delivers raw data to callback obtained from GetBuffer() methods skipping 
00223        internal PortAudio processing inventory completely. userData parameter will 
00224        be the same that was passed to Pa_OpenStream method. Will be used only if 
00225        paWinWasapiRedirectHostProcessor flag is specified.
00226     */
00227     PaWasapiHostProcessorCallback hostProcessorOutput;
00228     PaWasapiHostProcessorCallback hostProcessorInput;
00229 
00230     /* Specifies thread priority explicitly. Will be used only if paWinWasapiThreadPriority flag
00231        is specified.
00232 
00233        Please note, if Input/Output streams are opened simultaniously (Full-Duplex mode)
00234        you shall specify same value for threadPriority or othervise one of the values will be used
00235        to setup thread priority.
00236     */
00237     PaWasapiThreadPriority threadPriority;
00238 } 
00239 PaWasapiStreamInfo;
00240 
00241 
00253 int PaWasapi_GetDeviceDefaultFormat( void *pFormat, unsigned int nFormatSize, PaDeviceIndex nDevice );
00254 
00255 
00263 int/*PaWasapiDeviceRole*/ PaWasapi_GetDeviceRole( PaDeviceIndex nDevice );
00264 
00265 
00278 PaError PaWasapi_ThreadPriorityBoost( void **hTask, PaWasapiThreadPriority nPriorityClass );
00279 
00280 
00288 PaError PaWasapi_ThreadPriorityRevert( void *hTask );
00289 
00290 
00301 PaError PaWasapi_GetFramesPerHostBuffer( PaStream *pStream, unsigned int *nInput, unsigned int *nOutput );
00302 
00303 
00312 PaError PaWasapi_GetJackCount(PaDeviceIndex nDevice, int *jcount);
00313 
00314 
00326 PaError PaWasapi_GetJackDescription(PaDeviceIndex nDevice, int jindex, PaWasapiJackDescription *pJackDescription);
00327 
00328 
00329 /*
00330     IMPORTANT:
00331 
00332     WASAPI is implemented for Callback and Blocking interfaces. It supports Shared and Exclusive
00333     share modes. 
00334     
00335     Exclusive Mode:
00336 
00337         Exclusive mode allows to deliver audio data directly to hardware bypassing
00338         software mixing.
00339         Exclusive mode is specified by 'paWinWasapiExclusive' flag.
00340 
00341     Callback Interface:
00342 
00343         Provides best audio quality with low latency. Callback interface is implemented in 
00344         two versions:
00345 
00346         1) Event-Driven:
00347         This is the most powerful WASAPI implementation which provides glitch-free
00348         audio at around 3ms latency in Exclusive mode. Lowest possible latency for this mode is 
00349         3 ms for HD Audio class audio chips. For the Shared mode latency can not be 
00350                 lower than 20 ms.
00351 
00352         2) Poll-Driven:
00353         Polling is another 2-nd method to operate with WASAPI. It is less efficient than Event-Driven
00354         and provides latency at around 10-13ms. Polling must be used to overcome a system bug
00355         under Windows Vista x64 when application is WOW64(32-bit) and Event-Driven method simply 
00356         times out (event handle is never signalled on buffer completion). Please note, such WOW64 bug 
00357         does not exist in Vista x86 or Windows 7.
00358         Polling can be setup by speciying 'paWinWasapiPolling' flag. Our WASAPI implementation detects
00359         WOW64 bug and sets 'paWinWasapiPolling' automatically.
00360 
00361     Thread priority:
00362 
00363         Normally thread priority is set automatically and does not require modification. Although
00364         if user wants some tweaking thread priority can be modified by setting 'paWinWasapiThreadPriority'
00365         flag and specifying 'PaWasapiStreamInfo::threadPriority' with value from PaWasapiThreadPriority 
00366         enum.
00367 
00368     Blocking Interface:
00369 
00370         Blocking interface is implemented but due to above described Poll-Driven method can not
00371         deliver lowest possible latency. Specifying too low latency in Shared mode will result in 
00372         distorted audio although Exclusive mode adds stability.
00373 
00374     Pa_IsFormatSupported:
00375 
00376         To check format with correct Share Mode (Exclusive/Shared) you must supply
00377         PaWasapiStreamInfo with flags paWinWasapiExclusive set through member of 
00378         PaStreamParameters::hostApiSpecificStreamInfo structure.
00379 
00380     Pa_OpenStream:
00381 
00382         To set desired Share Mode (Exclusive/Shared) you must supply
00383         PaWasapiStreamInfo with flags paWinWasapiExclusive set through member of 
00384         PaStreamParameters::hostApiSpecificStreamInfo structure.
00385 */
00386 
00387 #ifdef __cplusplus
00388 }
00389 #endif /* __cplusplus */
00390 
00391 #endif /* PA_WIN_WASAPI_H */