Chris@4: #ifndef PA_WIN_WASAPI_H Chris@4: #define PA_WIN_WASAPI_H Chris@4: /* Chris@4: * $Id: $ Chris@4: * PortAudio Portable Real-Time Audio Library Chris@4: * DirectSound specific extensions Chris@4: * Chris@4: * Copyright (c) 1999-2007 Ross Bencina and Phil Burk Chris@4: * Chris@4: * Permission is hereby granted, free of charge, to any person obtaining Chris@4: * a copy of this software and associated documentation files Chris@4: * (the "Software"), to deal in the Software without restriction, Chris@4: * including without limitation the rights to use, copy, modify, merge, Chris@4: * publish, distribute, sublicense, and/or sell copies of the Software, Chris@4: * and to permit persons to whom the Software is furnished to do so, Chris@4: * subject to the following conditions: Chris@4: * Chris@4: * The above copyright notice and this permission notice shall be Chris@4: * included in all copies or substantial portions of the Software. Chris@4: * Chris@4: * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, Chris@4: * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF Chris@4: * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. Chris@4: * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR Chris@4: * ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF Chris@4: * CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION Chris@4: * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. Chris@4: */ Chris@4: Chris@4: /* Chris@4: * The text above constitutes the entire PortAudio license; however, Chris@4: * the PortAudio community also makes the following non-binding requests: Chris@4: * Chris@4: * Any person wishing to distribute modifications to the Software is Chris@4: * requested to send the modifications to the original developer so that Chris@4: * they can be incorporated into the canonical version. It is also Chris@4: * requested that these non-binding requests be included along with the Chris@4: * license above. Chris@4: */ Chris@4: Chris@4: /** @file Chris@4: @ingroup public_header Chris@4: @brief WASAPI-specific PortAudio API extension header file. Chris@4: */ Chris@4: Chris@4: #include "portaudio.h" Chris@4: #include "pa_win_waveformat.h" Chris@4: Chris@4: #ifdef __cplusplus Chris@4: extern "C" Chris@4: { Chris@4: #endif /* __cplusplus */ Chris@4: Chris@4: Chris@4: /* Setup flags */ Chris@4: typedef enum PaWasapiFlags Chris@4: { Chris@4: /* puts WASAPI into exclusive mode */ Chris@4: paWinWasapiExclusive = (1 << 0), Chris@4: Chris@4: /* allows to skip internal PA processing completely */ Chris@4: paWinWasapiRedirectHostProcessor = (1 << 1), Chris@4: Chris@4: /* assigns custom channel mask */ Chris@4: paWinWasapiUseChannelMask = (1 << 2), Chris@4: Chris@4: /* selects non-Event driven method of data read/write Chris@4: Note: WASAPI Event driven core is capable of 2ms latency!!!, but Polling Chris@4: method can only provide 15-20ms latency. */ Chris@4: paWinWasapiPolling = (1 << 3), Chris@4: Chris@4: /* forces custom thread priority setting. must be used if PaWasapiStreamInfo::threadPriority Chris@4: is set to custom value. */ Chris@4: paWinWasapiThreadPriority = (1 << 4) Chris@4: } Chris@4: PaWasapiFlags; Chris@4: #define paWinWasapiExclusive (paWinWasapiExclusive) Chris@4: #define paWinWasapiRedirectHostProcessor (paWinWasapiRedirectHostProcessor) Chris@4: #define paWinWasapiUseChannelMask (paWinWasapiUseChannelMask) Chris@4: #define paWinWasapiPolling (paWinWasapiPolling) Chris@4: #define paWinWasapiThreadPriority (paWinWasapiThreadPriority) Chris@4: Chris@4: Chris@4: /* Host processor. Allows to skip internal PA processing completely. Chris@4: You must set paWinWasapiRedirectHostProcessor flag to PaWasapiStreamInfo::flags member Chris@4: in order to have host processor redirected to your callback. Chris@4: Use with caution! inputFrames and outputFrames depend solely on final device setup. Chris@4: To query maximal values of inputFrames/outputFrames use PaWasapi_GetFramesPerHostBuffer. Chris@4: */ Chris@4: typedef void (*PaWasapiHostProcessorCallback) (void *inputBuffer, long inputFrames, Chris@4: void *outputBuffer, long outputFrames, Chris@4: void *userData); Chris@4: Chris@4: /* Device role */ Chris@4: typedef enum PaWasapiDeviceRole Chris@4: { Chris@4: eRoleRemoteNetworkDevice = 0, Chris@4: eRoleSpeakers, Chris@4: eRoleLineLevel, Chris@4: eRoleHeadphones, Chris@4: eRoleMicrophone, Chris@4: eRoleHeadset, Chris@4: eRoleHandset, Chris@4: eRoleUnknownDigitalPassthrough, Chris@4: eRoleSPDIF, Chris@4: eRoleHDMI, Chris@4: eRoleUnknownFormFactor Chris@4: } Chris@4: PaWasapiDeviceRole; Chris@4: Chris@4: Chris@4: /* Jack connection type */ Chris@4: typedef enum PaWasapiJackConnectionType Chris@4: { Chris@4: eJackConnTypeUnknown, Chris@4: eJackConnType3Point5mm, Chris@4: eJackConnTypeQuarter, Chris@4: eJackConnTypeAtapiInternal, Chris@4: eJackConnTypeRCA, Chris@4: eJackConnTypeOptical, Chris@4: eJackConnTypeOtherDigital, Chris@4: eJackConnTypeOtherAnalog, Chris@4: eJackConnTypeMultichannelAnalogDIN, Chris@4: eJackConnTypeXlrProfessional, Chris@4: eJackConnTypeRJ11Modem, Chris@4: eJackConnTypeCombination Chris@4: } Chris@4: PaWasapiJackConnectionType; Chris@4: Chris@4: Chris@4: /* Jack geometric location */ Chris@4: typedef enum PaWasapiJackGeoLocation Chris@4: { Chris@4: eJackGeoLocUnk = 0, Chris@4: eJackGeoLocRear = 0x1, /* matches EPcxGeoLocation::eGeoLocRear */ Chris@4: eJackGeoLocFront, Chris@4: eJackGeoLocLeft, Chris@4: eJackGeoLocRight, Chris@4: eJackGeoLocTop, Chris@4: eJackGeoLocBottom, Chris@4: eJackGeoLocRearPanel, Chris@4: eJackGeoLocRiser, Chris@4: eJackGeoLocInsideMobileLid, Chris@4: eJackGeoLocDrivebay, Chris@4: eJackGeoLocHDMI, Chris@4: eJackGeoLocOutsideMobileLid, Chris@4: eJackGeoLocATAPI, Chris@4: eJackGeoLocReserved5, Chris@4: eJackGeoLocReserved6, Chris@4: } Chris@4: PaWasapiJackGeoLocation; Chris@4: Chris@4: Chris@4: /* Jack general location */ Chris@4: typedef enum PaWasapiJackGenLocation Chris@4: { Chris@4: eJackGenLocPrimaryBox = 0, Chris@4: eJackGenLocInternal, Chris@4: eJackGenLocSeparate, Chris@4: eJackGenLocOther Chris@4: } Chris@4: PaWasapiJackGenLocation; Chris@4: Chris@4: Chris@4: /* Jack's type of port */ Chris@4: typedef enum PaWasapiJackPortConnection Chris@4: { Chris@4: eJackPortConnJack = 0, Chris@4: eJackPortConnIntegratedDevice, Chris@4: eJackPortConnBothIntegratedAndJack, Chris@4: eJackPortConnUnknown Chris@4: } Chris@4: PaWasapiJackPortConnection; Chris@4: Chris@4: Chris@4: /* Thread priority */ Chris@4: typedef enum PaWasapiThreadPriority Chris@4: { Chris@4: eThreadPriorityNone = 0, Chris@4: eThreadPriorityAudio, //!< Default for Shared mode. Chris@4: eThreadPriorityCapture, Chris@4: eThreadPriorityDistribution, Chris@4: eThreadPriorityGames, Chris@4: eThreadPriorityPlayback, Chris@4: eThreadPriorityProAudio, //!< Default for Exclusive mode. Chris@4: eThreadPriorityWindowManager Chris@4: } Chris@4: PaWasapiThreadPriority; Chris@4: Chris@4: Chris@4: /* Stream descriptor. */ Chris@4: typedef struct PaWasapiJackDescription Chris@4: { Chris@4: unsigned long channelMapping; Chris@4: unsigned long color; /* derived from macro: #define RGB(r,g,b) ((COLORREF)(((BYTE)(r)|((WORD)((BYTE)(g))<<8))|(((DWORD)(BYTE)(b))<<16))) */ Chris@4: PaWasapiJackConnectionType connectionType; Chris@4: PaWasapiJackGeoLocation geoLocation; Chris@4: PaWasapiJackGenLocation genLocation; Chris@4: PaWasapiJackPortConnection portConnection; Chris@4: unsigned int isConnected; Chris@4: } Chris@4: PaWasapiJackDescription; Chris@4: Chris@4: Chris@4: /* Stream descriptor. */ Chris@4: typedef struct PaWasapiStreamInfo Chris@4: { Chris@4: unsigned long size; /**< sizeof(PaWasapiStreamInfo) */ Chris@4: PaHostApiTypeId hostApiType; /**< paWASAPI */ Chris@4: unsigned long version; /**< 1 */ Chris@4: Chris@4: unsigned long flags; /**< collection of PaWasapiFlags */ Chris@4: Chris@4: /* Support for WAVEFORMATEXTENSIBLE channel masks. If flags contains Chris@4: paWinWasapiUseChannelMask this allows you to specify which speakers Chris@4: to address in a multichannel stream. Constants for channelMask Chris@4: are specified in pa_win_waveformat.h. Will be used only if Chris@4: paWinWasapiUseChannelMask flag is specified. Chris@4: */ Chris@4: PaWinWaveFormatChannelMask channelMask; Chris@4: Chris@4: /* Delivers raw data to callback obtained from GetBuffer() methods skipping Chris@4: internal PortAudio processing inventory completely. userData parameter will Chris@4: be the same that was passed to Pa_OpenStream method. Will be used only if Chris@4: paWinWasapiRedirectHostProcessor flag is specified. Chris@4: */ Chris@4: PaWasapiHostProcessorCallback hostProcessorOutput; Chris@4: PaWasapiHostProcessorCallback hostProcessorInput; Chris@4: Chris@4: /* Specifies thread priority explicitly. Will be used only if paWinWasapiThreadPriority flag Chris@4: is specified. Chris@4: Chris@4: Please note, if Input/Output streams are opened simultaniously (Full-Duplex mode) Chris@4: you shall specify same value for threadPriority or othervise one of the values will be used Chris@4: to setup thread priority. Chris@4: */ Chris@4: PaWasapiThreadPriority threadPriority; Chris@4: } Chris@4: PaWasapiStreamInfo; Chris@4: Chris@4: Chris@4: /** Returns default sound format for device. Format is represented by PaWinWaveFormat or Chris@4: WAVEFORMATEXTENSIBLE structure. Chris@4: Chris@4: @param pFormat Pointer to PaWinWaveFormat or WAVEFORMATEXTENSIBLE structure. Chris@4: @param nFormatSize Size of PaWinWaveFormat or WAVEFORMATEXTENSIBLE structure in bytes. Chris@4: @param nDevice Device index. Chris@4: Chris@4: @return Non-negative value indicating the number of bytes copied into format decriptor Chris@4: or, a PaErrorCode (which are always negative) if PortAudio is not initialized Chris@4: or an error is encountered. Chris@4: */ Chris@4: int PaWasapi_GetDeviceDefaultFormat( void *pFormat, unsigned int nFormatSize, PaDeviceIndex nDevice ); Chris@4: Chris@4: Chris@4: /** Returns device role (PaWasapiDeviceRole enum). Chris@4: Chris@4: @param nDevice device index. Chris@4: Chris@4: @return Non-negative value indicating device role or, a PaErrorCode (which are always negative) Chris@4: if PortAudio is not initialized or an error is encountered. Chris@4: */ Chris@4: int/*PaWasapiDeviceRole*/ PaWasapi_GetDeviceRole( PaDeviceIndex nDevice ); Chris@4: Chris@4: Chris@4: /** Boost thread priority of calling thread (MMCSS). Use it for Blocking Interface only for thread Chris@4: which makes calls to Pa_WriteStream/Pa_ReadStream. Chris@4: Chris@4: @param hTask Handle to pointer to priority task. Must be used with PaWasapi_RevertThreadPriority Chris@4: method to revert thread priority to initial state. Chris@4: Chris@4: @param nPriorityClass Id of thread priority of PaWasapiThreadPriority type. Specifying Chris@4: eThreadPriorityNone does nothing. Chris@4: Chris@4: @return Error code indicating success or failure. Chris@4: @see PaWasapi_RevertThreadPriority Chris@4: */ Chris@4: PaError PaWasapi_ThreadPriorityBoost( void **hTask, PaWasapiThreadPriority nPriorityClass ); Chris@4: Chris@4: Chris@4: /** Boost thread priority of calling thread (MMCSS). Use it for Blocking Interface only for thread Chris@4: which makes calls to Pa_WriteStream/Pa_ReadStream. Chris@4: Chris@4: @param hTask Task handle obtained by PaWasapi_BoostThreadPriority method. Chris@4: @return Error code indicating success or failure. Chris@4: @see PaWasapi_BoostThreadPriority Chris@4: */ Chris@4: PaError PaWasapi_ThreadPriorityRevert( void *hTask ); Chris@4: Chris@4: Chris@4: /** Get number of frames per host buffer. This is maximal value of frames of WASAPI buffer which Chris@4: can be locked for operations. Use this method as helper to findout maximal values of Chris@4: inputFrames/outputFrames of PaWasapiHostProcessorCallback. Chris@4: Chris@4: @param pStream Pointer to PaStream to query. Chris@4: @param nInput Pointer to variable to receive number of input frames. Can be NULL. Chris@4: @param nOutput Pointer to variable to receive number of output frames. Can be NULL. Chris@4: @return Error code indicating success or failure. Chris@4: @see PaWasapiHostProcessorCallback Chris@4: */ Chris@4: PaError PaWasapi_GetFramesPerHostBuffer( PaStream *pStream, unsigned int *nInput, unsigned int *nOutput ); Chris@4: Chris@4: Chris@4: /** Get number of jacks associated with a WASAPI device. Use this method to determine if Chris@4: there are any jacks associated with the provided WASAPI device. Not all audio devices Chris@4: will support this capability. This is valid for both input and output devices. Chris@4: @param nDevice device index. Chris@4: @param jcount Number of jacks is returned in this variable Chris@4: @return Error code indicating success or failure Chris@4: @see PaWasapi_GetJackDescription Chris@4: */ Chris@4: PaError PaWasapi_GetJackCount(PaDeviceIndex nDevice, int *jcount); Chris@4: Chris@4: Chris@4: /** Get the jack description associated with a WASAPI device and jack number Chris@4: Before this function is called, use PaWasapi_GetJackCount to determine the Chris@4: number of jacks associated with device. If jcount is greater than zero, then Chris@4: each jack from 0 to jcount can be queried with this function to get the jack Chris@4: description. Chris@4: @param nDevice device index. Chris@4: @param jindex Which jack to return information Chris@4: @param KSJACK_DESCRIPTION This structure filled in on success. Chris@4: @return Error code indicating success or failure Chris@4: @see PaWasapi_GetJackCount Chris@4: */ Chris@4: PaError PaWasapi_GetJackDescription(PaDeviceIndex nDevice, int jindex, PaWasapiJackDescription *pJackDescription); Chris@4: Chris@4: Chris@4: /* Chris@4: IMPORTANT: Chris@4: Chris@4: WASAPI is implemented for Callback and Blocking interfaces. It supports Shared and Exclusive Chris@4: share modes. Chris@4: Chris@4: Exclusive Mode: Chris@4: Chris@4: Exclusive mode allows to deliver audio data directly to hardware bypassing Chris@4: software mixing. Chris@4: Exclusive mode is specified by 'paWinWasapiExclusive' flag. Chris@4: Chris@4: Callback Interface: Chris@4: Chris@4: Provides best audio quality with low latency. Callback interface is implemented in Chris@4: two versions: Chris@4: Chris@4: 1) Event-Driven: Chris@4: This is the most powerful WASAPI implementation which provides glitch-free Chris@4: audio at around 3ms latency in Exclusive mode. Lowest possible latency for this mode is Chris@4: 3 ms for HD Audio class audio chips. For the Shared mode latency can not be Chris@4: lower than 20 ms. Chris@4: Chris@4: 2) Poll-Driven: Chris@4: Polling is another 2-nd method to operate with WASAPI. It is less efficient than Event-Driven Chris@4: and provides latency at around 10-13ms. Polling must be used to overcome a system bug Chris@4: under Windows Vista x64 when application is WOW64(32-bit) and Event-Driven method simply Chris@4: times out (event handle is never signalled on buffer completion). Please note, such WOW64 bug Chris@4: does not exist in Vista x86 or Windows 7. Chris@4: Polling can be setup by speciying 'paWinWasapiPolling' flag. Our WASAPI implementation detects Chris@4: WOW64 bug and sets 'paWinWasapiPolling' automatically. Chris@4: Chris@4: Thread priority: Chris@4: Chris@4: Normally thread priority is set automatically and does not require modification. Although Chris@4: if user wants some tweaking thread priority can be modified by setting 'paWinWasapiThreadPriority' Chris@4: flag and specifying 'PaWasapiStreamInfo::threadPriority' with value from PaWasapiThreadPriority Chris@4: enum. Chris@4: Chris@4: Blocking Interface: Chris@4: Chris@4: Blocking interface is implemented but due to above described Poll-Driven method can not Chris@4: deliver lowest possible latency. Specifying too low latency in Shared mode will result in Chris@4: distorted audio although Exclusive mode adds stability. Chris@4: Chris@4: Pa_IsFormatSupported: Chris@4: Chris@4: To check format with correct Share Mode (Exclusive/Shared) you must supply Chris@4: PaWasapiStreamInfo with flags paWinWasapiExclusive set through member of Chris@4: PaStreamParameters::hostApiSpecificStreamInfo structure. Chris@4: Chris@4: Pa_OpenStream: Chris@4: Chris@4: To set desired Share Mode (Exclusive/Shared) you must supply Chris@4: PaWasapiStreamInfo with flags paWinWasapiExclusive set through member of Chris@4: PaStreamParameters::hostApiSpecificStreamInfo structure. Chris@4: */ Chris@4: Chris@4: #ifdef __cplusplus Chris@4: } Chris@4: #endif /* __cplusplus */ Chris@4: Chris@4: #endif /* PA_WIN_WASAPI_H */