PortAudio  2.0
Data Structures | Macros | Typedefs | Enumerations | Functions
pa_win_wasapi.h File Reference

WASAPI-specific PortAudio API extension header file. More...

#include "portaudio.h"
#include "pa_win_waveformat.h"

Go to the source code of this file.

Data Structures

struct  PaWasapiJackDescription
 
struct  PaWasapiStreamInfo
 

Macros

#define paWinWasapiExclusive   (paWinWasapiExclusive)
 
#define paWinWasapiRedirectHostProcessor   (paWinWasapiRedirectHostProcessor)
 
#define paWinWasapiUseChannelMask   (paWinWasapiUseChannelMask)
 
#define paWinWasapiPolling   (paWinWasapiPolling)
 
#define paWinWasapiThreadPriority   (paWinWasapiThreadPriority)
 
#define paWinWasapiExplicitSampleFormat   (paWinWasapiExplicitSampleFormat)
 
#define paWinWasapiAutoConvert   (paWinWasapiAutoConvert)
 
#define paWasapiStreamStateError   (paWasapiStreamStateError)
 
#define paWasapiStreamStateThreadPrepare   (paWasapiStreamStateThreadPrepare)
 
#define paWasapiStreamStateThreadStart   (paWasapiStreamStateThreadStart)
 
#define paWasapiStreamStateThreadStop   (paWasapiStreamStateThreadStop)
 

Typedefs

typedef enum PaWasapiFlags PaWasapiFlags
 
typedef enum PaWasapiStreamState PaWasapiStreamState
 
typedef void(* PaWasapiHostProcessorCallback )(void *inputBuffer, long inputFrames, void *outputBuffer, long outputFrames, void *userData)
 
typedef void(* PaWasapiStreamStateCallback )(PaStream *pStream, unsigned int stateFlags, unsigned int errorId, void *pUserData)
 
typedef enum PaWasapiDeviceRole PaWasapiDeviceRole
 
typedef enum
PaWasapiJackConnectionType 
PaWasapiJackConnectionType
 
typedef enum
PaWasapiJackGeoLocation 
PaWasapiJackGeoLocation
 
typedef enum
PaWasapiJackGenLocation 
PaWasapiJackGenLocation
 
typedef enum
PaWasapiJackPortConnection 
PaWasapiJackPortConnection
 
typedef enum PaWasapiThreadPriority PaWasapiThreadPriority
 
typedef struct
PaWasapiJackDescription 
PaWasapiJackDescription
 
typedef enum PaWasapiStreamCategory PaWasapiStreamCategory
 
typedef enum PaWasapiStreamOption PaWasapiStreamOption
 
typedef struct PaWasapiStreamInfo PaWasapiStreamInfo
 

Enumerations

enum  PaWasapiFlags {
  paWinWasapiExclusive = (1 << 0), paWinWasapiRedirectHostProcessor = (1 << 1), paWinWasapiUseChannelMask = (1 << 2), paWinWasapiPolling = (1 << 3),
  paWinWasapiThreadPriority = (1 << 4), paWinWasapiExplicitSampleFormat = (1 << 5), paWinWasapiAutoConvert = (1 << 6)
}
 
enum  PaWasapiStreamState { paWasapiStreamStateError = (1 << 0), paWasapiStreamStateThreadPrepare = (1 << 1), paWasapiStreamStateThreadStart = (1 << 2), paWasapiStreamStateThreadStop = (1 << 3) }
 
enum  PaWasapiDeviceRole {
  eRoleRemoteNetworkDevice = 0, eRoleSpeakers, eRoleLineLevel, eRoleHeadphones,
  eRoleMicrophone, eRoleHeadset, eRoleHandset, eRoleUnknownDigitalPassthrough,
  eRoleSPDIF, eRoleHDMI, eRoleUnknownFormFactor
}
 
enum  PaWasapiJackConnectionType {
  eJackConnTypeUnknown, eJackConnType3Point5mm, eJackConnTypeQuarter, eJackConnTypeAtapiInternal,
  eJackConnTypeRCA, eJackConnTypeOptical, eJackConnTypeOtherDigital, eJackConnTypeOtherAnalog,
  eJackConnTypeMultichannelAnalogDIN, eJackConnTypeXlrProfessional, eJackConnTypeRJ11Modem, eJackConnTypeCombination
}
 
enum  PaWasapiJackGeoLocation {
  eJackGeoLocUnk = 0, eJackGeoLocRear = 0x1, eJackGeoLocFront, eJackGeoLocLeft,
  eJackGeoLocRight, eJackGeoLocTop, eJackGeoLocBottom, eJackGeoLocRearPanel,
  eJackGeoLocRiser, eJackGeoLocInsideMobileLid, eJackGeoLocDrivebay, eJackGeoLocHDMI,
  eJackGeoLocOutsideMobileLid, eJackGeoLocATAPI, eJackGeoLocReserved5, eJackGeoLocReserved6
}
 
enum  PaWasapiJackGenLocation { eJackGenLocPrimaryBox = 0, eJackGenLocInternal, eJackGenLocSeparate, eJackGenLocOther }
 
enum  PaWasapiJackPortConnection { eJackPortConnJack = 0, eJackPortConnIntegratedDevice, eJackPortConnBothIntegratedAndJack, eJackPortConnUnknown }
 
enum  PaWasapiThreadPriority {
  eThreadPriorityNone = 0, eThreadPriorityAudio, eThreadPriorityCapture, eThreadPriorityDistribution,
  eThreadPriorityGames, eThreadPriorityPlayback, eThreadPriorityProAudio, eThreadPriorityWindowManager
}
 
enum  PaWasapiStreamCategory {
  eAudioCategoryOther = 0, eAudioCategoryCommunications = 3, eAudioCategoryAlerts = 4, eAudioCategorySoundEffects = 5,
  eAudioCategoryGameEffects = 6, eAudioCategoryGameMedia = 7, eAudioCategoryGameChat = 8, eAudioCategorySpeech = 9,
  eAudioCategoryMovie = 10, eAudioCategoryMedia = 11
}
 
enum  PaWasapiStreamOption { eStreamOptionNone = 0, eStreamOptionRaw = 1, eStreamOptionMatchFormat = 2 }
 

Functions

PaError PaWasapi_GetAudioClient (PaStream *pStream, void **pAudioClient, int bOutput)
 
PaError PaWasapi_UpdateDeviceList ()
 
int PaWasapi_GetDeviceCurrentFormat (PaStream *pStream, void *pFormat, unsigned int formatSize, int bOutput)
 
int PaWasapi_GetDeviceDefaultFormat (void *pFormat, unsigned int formatSize, PaDeviceIndex device)
 
int PaWasapi_GetDeviceMixFormat (void *pFormat, unsigned int formatSize, PaDeviceIndex device)
 
int PaWasapi_GetDeviceRole (PaDeviceIndex device)
 
PaError PaWasapi_ThreadPriorityBoost (void **pTask, PaWasapiThreadPriority priorityClass)
 
PaError PaWasapi_ThreadPriorityRevert (void *pTask)
 
PaError PaWasapi_GetFramesPerHostBuffer (PaStream *pStream, unsigned int *pInput, unsigned int *pOutput)
 
PaError PaWasapi_GetJackCount (PaDeviceIndex device, int *pJackCount)
 
PaError PaWasapi_GetJackDescription (PaDeviceIndex device, int jackIndex, PaWasapiJackDescription *pJackDescription)
 
PaError PaWasapi_SetDefaultInterfaceId (unsigned short *pId, int bOutput)
 
PaError PaWasapi_SetStreamStateHandler (PaStream *pStream, PaWasapiStreamStateCallback fnStateHandler, void *pUserData)
 

Detailed Description

WASAPI-specific PortAudio API extension header file.

Definition in file pa_win_wasapi.h.

Typedef Documentation

Stream category. Note:

  • values are equal to WASAPI AUDIO_STREAM_CATEGORY enum
  • supported since Windows 8.0, noop on earler versions
  • values 1,2 are deprecated on Windows 10 and not included into enumeration
Version
Available as of 19.6.0

Stream option. Note:

  • values are equal to WASAPI AUDCLNT_STREAMOPTIONS enum
  • supported since Windows 8.1, noop on earler versions
Version
Available as of 19.6.0

Enumeration Type Documentation

Stream category. Note:

  • values are equal to WASAPI AUDIO_STREAM_CATEGORY enum
  • supported since Windows 8.0, noop on earler versions
  • values 1,2 are deprecated on Windows 10 and not included into enumeration
Version
Available as of 19.6.0

Definition at line 275 of file pa_win_wasapi.h.

Stream option. Note:

  • values are equal to WASAPI AUDCLNT_STREAMOPTIONS enum
  • supported since Windows 8.1, noop on earler versions
Version
Available as of 19.6.0
Enumerator:
eStreamOptionNone 

default

eStreamOptionRaw 

bypass WASAPI Audio Engine DSP effects, supported since Windows 8.1

eStreamOptionMatchFormat 

force WASAPI Audio Engine into a stream format, supported since Windows 10

Definition at line 298 of file pa_win_wasapi.h.

Enumerator:
eThreadPriorityAudio 

Default for Shared mode.

eThreadPriorityProAudio 

Default for Exclusive mode.

Definition at line 239 of file pa_win_wasapi.h.

Function Documentation

PaError PaWasapi_GetAudioClient ( PaStream pStream,
void **  pAudioClient,
int  bOutput 
)

Returns pointer to WASAPI's IAudioClient object of the stream.

Parameters
pStreamPointer to PaStream object.
pAudioClientPointer to pointer of IAudioClient.
bOutputTRUE (1) for output stream, FALSE (0) for input stream.
Returns
Error code indicating success or failure.
int PaWasapi_GetDeviceCurrentFormat ( PaStream pStream,
void *  pFormat,
unsigned int  formatSize,
int  bOutput 
)

Get current audio format of the device assigned to the opened stream.

Format is represented by PaWinWaveFormat or WAVEFORMATEXTENSIBLE structure. Use this function to reconfirm format if PA's processor is overriden and paWinWasapiRedirectHostProcessor flag is specified.

Parameters
pStreamPointer to PaStream object.
pFormatPointer to PaWinWaveFormat or WAVEFORMATEXTENSIBLE structure.
formatSizeSize of PaWinWaveFormat or WAVEFORMATEXTENSIBLE structure in bytes.
bOutputTRUE (1) for output stream, FALSE (0) for input stream.
Returns
Non-negative value indicating the number of bytes copied into format decriptor or, a PaErrorCode (which is always negative) if PortAudio is not initialized or an error is encountered.
int PaWasapi_GetDeviceDefaultFormat ( void *  pFormat,
unsigned int  formatSize,
PaDeviceIndex  device 
)

Get default audio format for the device in Shared Mode.

Format is represented by PaWinWaveFormat or WAVEFORMATEXTENSIBLE structure and obtained by getting the device property with a PKEY_AudioEngine_DeviceFormat key.

Parameters
pFormatPointer to PaWinWaveFormat or WAVEFORMATEXTENSIBLE structure.
formatSizeSize of PaWinWaveFormat or WAVEFORMATEXTENSIBLE structure in bytes.
deviceDevice index.
Returns
Non-negative value indicating the number of bytes copied into format decriptor or, a PaErrorCode (which is always negative) if PortAudio is not initialized or an error is encountered.
int PaWasapi_GetDeviceMixFormat ( void *  pFormat,
unsigned int  formatSize,
PaDeviceIndex  device 
)

Get mix audio format for the device in Shared Mode.

Format is represented by PaWinWaveFormat or WAVEFORMATEXTENSIBLE structureand obtained by IAudioClient::GetMixFormat.

Parameters
pFormatPointer to PaWinWaveFormat or WAVEFORMATEXTENSIBLE structure.
formatSizeSize of PaWinWaveFormat or WAVEFORMATEXTENSIBLE structure in bytes.
deviceDevice index.
Returns
Non-negative value indicating the number of bytes copied into format decriptor or, a PaErrorCode (which is always negative) if PortAudio is not initialized or an error is encountered.
int PaWasapi_GetDeviceRole ( PaDeviceIndex  device)

Get device role (PaWasapiDeviceRole enum).

Parameters
deviceDevice index.
Returns
Non-negative value indicating device role or, a PaErrorCode (which is always negative) if PortAudio is not initialized or an error is encountered.
PaError PaWasapi_GetFramesPerHostBuffer ( PaStream pStream,
unsigned int *  pInput,
unsigned int *  pOutput 
)

Get number of frames per host buffer.

It is max value of frames of WASAPI buffer which can be locked for operations. Use this method as helper to findout max values of inputFrames/outputFrames of PaWasapiHostProcessorCallback.

Parameters
pStreamPointer to PaStream object.
pInputPointer to variable to receive number of input frames. Can be NULL.
pOutputPointer to variable to receive number of output frames. Can be NULL.
Returns
Error code indicating success or failure.
See Also
PaWasapiHostProcessorCallback
PaError PaWasapi_GetJackCount ( PaDeviceIndex  device,
int *  pJackCount 
)

Get number of jacks associated with a WASAPI device.

Use this method to determine if there are any jacks associated with the provided WASAPI device. Not all audio devices will support this capability. This is valid for both input and output devices.

Note
Not available on UWP platform.
Parameters
deviceDevice index.
pJackCountPointer to variable to receive number of jacks.
Returns
Error code indicating success or failure.
See Also
PaWasapi_GetJackDescription
PaError PaWasapi_GetJackDescription ( PaDeviceIndex  device,
int  jackIndex,
PaWasapiJackDescription pJackDescription 
)

Get the jack description associated with a WASAPI device and jack number.

Before this function is called, use PaWasapi_GetJackCount to determine the number of jacks associated with device. If jcount is greater than zero, then each jack from 0 to jcount can be queried with this function to get the jack description.

Note
Not available on UWP platform.
Parameters
deviceDevice index.
jackIndexJack index.
pJackDescriptionPointer to PaWasapiJackDescription.
Returns
Error code indicating success or failure.
See Also
PaWasapi_GetJackCount
PaError PaWasapi_SetDefaultInterfaceId ( unsigned short *  pId,
int  bOutput 
)

Set default interface Id.

By default PA implementation will use DEVINTERFACE_AUDIO_RENDER and DEVINTERFACE_AUDIO_CAPTURE if device Id is not provided explicitly. These default Ids will not allow to use Exclusive mode on UWP platform and thus you must provide device Id explicitly via this API before calling Pa_OpenStream(). Device Ids on UWP platform are obtainable via Windows::Media::Devices::MediaDevice::GetDefaultAudioRenderId() or Windows::Media::Devices::MediaDevice::GetDefaultAudioCaptureId() API.

Note
UWP platform only.
Parameters
pIdInterface Id, pointer to the 16-bit Unicode string (WCHAR). If NULL then device Id will be reset to the default, e.g. DEVINTERFACE_AUDIO_RENDER or DEVINTERFACE_AUDIO_CAPTURE.
bOutputTRUE (1) for output (render), FALSE (0) for input (capture).
Returns
Error code indicating success or failure. Will return paIncompatibleStreamHostApi if PA is not compiled for UWP platform. If Id is longer than 4096 characters paBufferTooBig will be returned.
PaError PaWasapi_SetStreamStateHandler ( PaStream pStream,
PaWasapiStreamStateCallback  fnStateHandler,
void *  pUserData 
)

Set stream state handler.

Parameters
pStreamPointer to PaStream object.
fnStateHandlerPointer to state handling function.
pUserDataPointer to user data.
Returns
Error code indicating success or failure.
PaError PaWasapi_ThreadPriorityBoost ( void **  pTask,
PaWasapiThreadPriority  priorityClass 
)

Boost thread priority of calling thread (MMCSS).

Use it for Blocking Interface only inside the thread which makes calls to Pa_WriteStream/Pa_ReadStream.

Parameters
pTaskHandle to pointer to priority task. Must be used with PaWasapi_RevertThreadPriority method to revert thread priority to initial state.
priorityClassId of thread priority of PaWasapiThreadPriority type. Specifying eThreadPriorityNone does nothing.
Returns
Error code indicating success or failure.
See Also
PaWasapi_RevertThreadPriority
PaError PaWasapi_ThreadPriorityRevert ( void *  pTask)

Boost thread priority of calling thread (MMCSS).

Use it for Blocking Interface only inside the thread which makes calls to Pa_WriteStream/Pa_ReadStream.

Parameters
pTaskTask handle obtained by PaWasapi_BoostThreadPriority method.
Returns
Error code indicating success or failure.
See Also
PaWasapi_BoostThreadPriority
PaError PaWasapi_UpdateDeviceList ( )

Update device list.

This function is available if PA_WASAPI_MAX_CONST_DEVICE_COUNT is defined during compile time with maximum constant WASAPI device count (recommended value - 32). If PA_WASAPI_MAX_CONST_DEVICE_COUNT is set to 0 (or not defined) during compile time the implementation will not define PaWasapi_UpdateDeviceList() and thus updating device list can only be possible by calling Pa_Terminate() and then Pa_Initialize().

Returns
Error code indicating success or failure.