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