annotate src/portaudio_20140130/include/pa_win_wasapi.h @ 169:223a55898ab9 tip default

Add null config files
author Chris Cannam <cannam@all-day-breakfast.com>
date Mon, 02 Mar 2020 14:03:47 +0000
parents e3d5853d5918
children
rev   line source
cannam@124 1 #ifndef PA_WIN_WASAPI_H
cannam@124 2 #define PA_WIN_WASAPI_H
cannam@124 3 /*
cannam@124 4 * $Id: $
cannam@124 5 * PortAudio Portable Real-Time Audio Library
cannam@124 6 * DirectSound specific extensions
cannam@124 7 *
cannam@124 8 * Copyright (c) 1999-2007 Ross Bencina and Phil Burk
cannam@124 9 *
cannam@124 10 * Permission is hereby granted, free of charge, to any person obtaining
cannam@124 11 * a copy of this software and associated documentation files
cannam@124 12 * (the "Software"), to deal in the Software without restriction,
cannam@124 13 * including without limitation the rights to use, copy, modify, merge,
cannam@124 14 * publish, distribute, sublicense, and/or sell copies of the Software,
cannam@124 15 * and to permit persons to whom the Software is furnished to do so,
cannam@124 16 * subject to the following conditions:
cannam@124 17 *
cannam@124 18 * The above copyright notice and this permission notice shall be
cannam@124 19 * included in all copies or substantial portions of the Software.
cannam@124 20 *
cannam@124 21 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
cannam@124 22 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
cannam@124 23 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
cannam@124 24 * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR
cannam@124 25 * ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
cannam@124 26 * CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
cannam@124 27 * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
cannam@124 28 */
cannam@124 29
cannam@124 30 /*
cannam@124 31 * The text above constitutes the entire PortAudio license; however,
cannam@124 32 * the PortAudio community also makes the following non-binding requests:
cannam@124 33 *
cannam@124 34 * Any person wishing to distribute modifications to the Software is
cannam@124 35 * requested to send the modifications to the original developer so that
cannam@124 36 * they can be incorporated into the canonical version. It is also
cannam@124 37 * requested that these non-binding requests be included along with the
cannam@124 38 * license above.
cannam@124 39 */
cannam@124 40
cannam@124 41 /** @file
cannam@124 42 @ingroup public_header
cannam@124 43 @brief WASAPI-specific PortAudio API extension header file.
cannam@124 44 */
cannam@124 45
cannam@124 46 #include "portaudio.h"
cannam@124 47 #include "pa_win_waveformat.h"
cannam@124 48
cannam@124 49 #ifdef __cplusplus
cannam@124 50 extern "C"
cannam@124 51 {
cannam@124 52 #endif /* __cplusplus */
cannam@124 53
cannam@124 54
cannam@124 55 /* Setup flags */
cannam@124 56 typedef enum PaWasapiFlags
cannam@124 57 {
cannam@124 58 /* puts WASAPI into exclusive mode */
cannam@124 59 paWinWasapiExclusive = (1 << 0),
cannam@124 60
cannam@124 61 /* allows to skip internal PA processing completely */
cannam@124 62 paWinWasapiRedirectHostProcessor = (1 << 1),
cannam@124 63
cannam@124 64 /* assigns custom channel mask */
cannam@124 65 paWinWasapiUseChannelMask = (1 << 2),
cannam@124 66
cannam@124 67 /* selects non-Event driven method of data read/write
cannam@124 68 Note: WASAPI Event driven core is capable of 2ms latency!!!, but Polling
cannam@124 69 method can only provide 15-20ms latency. */
cannam@124 70 paWinWasapiPolling = (1 << 3),
cannam@124 71
cannam@124 72 /* forces custom thread priority setting. must be used if PaWasapiStreamInfo::threadPriority
cannam@124 73 is set to custom value. */
cannam@124 74 paWinWasapiThreadPriority = (1 << 4)
cannam@124 75 }
cannam@124 76 PaWasapiFlags;
cannam@124 77 #define paWinWasapiExclusive (paWinWasapiExclusive)
cannam@124 78 #define paWinWasapiRedirectHostProcessor (paWinWasapiRedirectHostProcessor)
cannam@124 79 #define paWinWasapiUseChannelMask (paWinWasapiUseChannelMask)
cannam@124 80 #define paWinWasapiPolling (paWinWasapiPolling)
cannam@124 81 #define paWinWasapiThreadPriority (paWinWasapiThreadPriority)
cannam@124 82
cannam@124 83
cannam@124 84 /* Host processor. Allows to skip internal PA processing completely.
cannam@124 85 You must set paWinWasapiRedirectHostProcessor flag to PaWasapiStreamInfo::flags member
cannam@124 86 in order to have host processor redirected to your callback.
cannam@124 87 Use with caution! inputFrames and outputFrames depend solely on final device setup.
cannam@124 88 To query maximal values of inputFrames/outputFrames use PaWasapi_GetFramesPerHostBuffer.
cannam@124 89 */
cannam@124 90 typedef void (*PaWasapiHostProcessorCallback) (void *inputBuffer, long inputFrames,
cannam@124 91 void *outputBuffer, long outputFrames,
cannam@124 92 void *userData);
cannam@124 93
cannam@124 94 /* Device role */
cannam@124 95 typedef enum PaWasapiDeviceRole
cannam@124 96 {
cannam@124 97 eRoleRemoteNetworkDevice = 0,
cannam@124 98 eRoleSpeakers,
cannam@124 99 eRoleLineLevel,
cannam@124 100 eRoleHeadphones,
cannam@124 101 eRoleMicrophone,
cannam@124 102 eRoleHeadset,
cannam@124 103 eRoleHandset,
cannam@124 104 eRoleUnknownDigitalPassthrough,
cannam@124 105 eRoleSPDIF,
cannam@124 106 eRoleHDMI,
cannam@124 107 eRoleUnknownFormFactor
cannam@124 108 }
cannam@124 109 PaWasapiDeviceRole;
cannam@124 110
cannam@124 111
cannam@124 112 /* Jack connection type */
cannam@124 113 typedef enum PaWasapiJackConnectionType
cannam@124 114 {
cannam@124 115 eJackConnTypeUnknown,
cannam@124 116 eJackConnType3Point5mm,
cannam@124 117 eJackConnTypeQuarter,
cannam@124 118 eJackConnTypeAtapiInternal,
cannam@124 119 eJackConnTypeRCA,
cannam@124 120 eJackConnTypeOptical,
cannam@124 121 eJackConnTypeOtherDigital,
cannam@124 122 eJackConnTypeOtherAnalog,
cannam@124 123 eJackConnTypeMultichannelAnalogDIN,
cannam@124 124 eJackConnTypeXlrProfessional,
cannam@124 125 eJackConnTypeRJ11Modem,
cannam@124 126 eJackConnTypeCombination
cannam@124 127 }
cannam@124 128 PaWasapiJackConnectionType;
cannam@124 129
cannam@124 130
cannam@124 131 /* Jack geometric location */
cannam@124 132 typedef enum PaWasapiJackGeoLocation
cannam@124 133 {
cannam@124 134 eJackGeoLocUnk = 0,
cannam@124 135 eJackGeoLocRear = 0x1, /* matches EPcxGeoLocation::eGeoLocRear */
cannam@124 136 eJackGeoLocFront,
cannam@124 137 eJackGeoLocLeft,
cannam@124 138 eJackGeoLocRight,
cannam@124 139 eJackGeoLocTop,
cannam@124 140 eJackGeoLocBottom,
cannam@124 141 eJackGeoLocRearPanel,
cannam@124 142 eJackGeoLocRiser,
cannam@124 143 eJackGeoLocInsideMobileLid,
cannam@124 144 eJackGeoLocDrivebay,
cannam@124 145 eJackGeoLocHDMI,
cannam@124 146 eJackGeoLocOutsideMobileLid,
cannam@124 147 eJackGeoLocATAPI,
cannam@124 148 eJackGeoLocReserved5,
cannam@124 149 eJackGeoLocReserved6,
cannam@124 150 }
cannam@124 151 PaWasapiJackGeoLocation;
cannam@124 152
cannam@124 153
cannam@124 154 /* Jack general location */
cannam@124 155 typedef enum PaWasapiJackGenLocation
cannam@124 156 {
cannam@124 157 eJackGenLocPrimaryBox = 0,
cannam@124 158 eJackGenLocInternal,
cannam@124 159 eJackGenLocSeparate,
cannam@124 160 eJackGenLocOther
cannam@124 161 }
cannam@124 162 PaWasapiJackGenLocation;
cannam@124 163
cannam@124 164
cannam@124 165 /* Jack's type of port */
cannam@124 166 typedef enum PaWasapiJackPortConnection
cannam@124 167 {
cannam@124 168 eJackPortConnJack = 0,
cannam@124 169 eJackPortConnIntegratedDevice,
cannam@124 170 eJackPortConnBothIntegratedAndJack,
cannam@124 171 eJackPortConnUnknown
cannam@124 172 }
cannam@124 173 PaWasapiJackPortConnection;
cannam@124 174
cannam@124 175
cannam@124 176 /* Thread priority */
cannam@124 177 typedef enum PaWasapiThreadPriority
cannam@124 178 {
cannam@124 179 eThreadPriorityNone = 0,
cannam@124 180 eThreadPriorityAudio, //!< Default for Shared mode.
cannam@124 181 eThreadPriorityCapture,
cannam@124 182 eThreadPriorityDistribution,
cannam@124 183 eThreadPriorityGames,
cannam@124 184 eThreadPriorityPlayback,
cannam@124 185 eThreadPriorityProAudio, //!< Default for Exclusive mode.
cannam@124 186 eThreadPriorityWindowManager
cannam@124 187 }
cannam@124 188 PaWasapiThreadPriority;
cannam@124 189
cannam@124 190
cannam@124 191 /* Stream descriptor. */
cannam@124 192 typedef struct PaWasapiJackDescription
cannam@124 193 {
cannam@124 194 unsigned long channelMapping;
cannam@124 195 unsigned long color; /* derived from macro: #define RGB(r,g,b) ((COLORREF)(((BYTE)(r)|((WORD)((BYTE)(g))<<8))|(((DWORD)(BYTE)(b))<<16))) */
cannam@124 196 PaWasapiJackConnectionType connectionType;
cannam@124 197 PaWasapiJackGeoLocation geoLocation;
cannam@124 198 PaWasapiJackGenLocation genLocation;
cannam@124 199 PaWasapiJackPortConnection portConnection;
cannam@124 200 unsigned int isConnected;
cannam@124 201 }
cannam@124 202 PaWasapiJackDescription;
cannam@124 203
cannam@124 204
cannam@124 205 /* Stream descriptor. */
cannam@124 206 typedef struct PaWasapiStreamInfo
cannam@124 207 {
cannam@124 208 unsigned long size; /**< sizeof(PaWasapiStreamInfo) */
cannam@124 209 PaHostApiTypeId hostApiType; /**< paWASAPI */
cannam@124 210 unsigned long version; /**< 1 */
cannam@124 211
cannam@124 212 unsigned long flags; /**< collection of PaWasapiFlags */
cannam@124 213
cannam@124 214 /* Support for WAVEFORMATEXTENSIBLE channel masks. If flags contains
cannam@124 215 paWinWasapiUseChannelMask this allows you to specify which speakers
cannam@124 216 to address in a multichannel stream. Constants for channelMask
cannam@124 217 are specified in pa_win_waveformat.h. Will be used only if
cannam@124 218 paWinWasapiUseChannelMask flag is specified.
cannam@124 219 */
cannam@124 220 PaWinWaveFormatChannelMask channelMask;
cannam@124 221
cannam@124 222 /* Delivers raw data to callback obtained from GetBuffer() methods skipping
cannam@124 223 internal PortAudio processing inventory completely. userData parameter will
cannam@124 224 be the same that was passed to Pa_OpenStream method. Will be used only if
cannam@124 225 paWinWasapiRedirectHostProcessor flag is specified.
cannam@124 226 */
cannam@124 227 PaWasapiHostProcessorCallback hostProcessorOutput;
cannam@124 228 PaWasapiHostProcessorCallback hostProcessorInput;
cannam@124 229
cannam@124 230 /* Specifies thread priority explicitly. Will be used only if paWinWasapiThreadPriority flag
cannam@124 231 is specified.
cannam@124 232
cannam@124 233 Please note, if Input/Output streams are opened simultaniously (Full-Duplex mode)
cannam@124 234 you shall specify same value for threadPriority or othervise one of the values will be used
cannam@124 235 to setup thread priority.
cannam@124 236 */
cannam@124 237 PaWasapiThreadPriority threadPriority;
cannam@124 238 }
cannam@124 239 PaWasapiStreamInfo;
cannam@124 240
cannam@124 241
cannam@124 242 /** Returns default sound format for device. Format is represented by PaWinWaveFormat or
cannam@124 243 WAVEFORMATEXTENSIBLE structure.
cannam@124 244
cannam@124 245 @param pFormat Pointer to PaWinWaveFormat or WAVEFORMATEXTENSIBLE structure.
cannam@124 246 @param nFormatSize Size of PaWinWaveFormat or WAVEFORMATEXTENSIBLE structure in bytes.
cannam@124 247 @param nDevice Device index.
cannam@124 248
cannam@124 249 @return Non-negative value indicating the number of bytes copied into format decriptor
cannam@124 250 or, a PaErrorCode (which are always negative) if PortAudio is not initialized
cannam@124 251 or an error is encountered.
cannam@124 252 */
cannam@124 253 int PaWasapi_GetDeviceDefaultFormat( void *pFormat, unsigned int nFormatSize, PaDeviceIndex nDevice );
cannam@124 254
cannam@124 255
cannam@124 256 /** Returns device role (PaWasapiDeviceRole enum).
cannam@124 257
cannam@124 258 @param nDevice device index.
cannam@124 259
cannam@124 260 @return Non-negative value indicating device role or, a PaErrorCode (which are always negative)
cannam@124 261 if PortAudio is not initialized or an error is encountered.
cannam@124 262 */
cannam@124 263 int/*PaWasapiDeviceRole*/ PaWasapi_GetDeviceRole( PaDeviceIndex nDevice );
cannam@124 264
cannam@124 265
cannam@124 266 /** Boost thread priority of calling thread (MMCSS). Use it for Blocking Interface only for thread
cannam@124 267 which makes calls to Pa_WriteStream/Pa_ReadStream.
cannam@124 268
cannam@124 269 @param hTask Handle to pointer to priority task. Must be used with PaWasapi_RevertThreadPriority
cannam@124 270 method to revert thread priority to initial state.
cannam@124 271
cannam@124 272 @param nPriorityClass Id of thread priority of PaWasapiThreadPriority type. Specifying
cannam@124 273 eThreadPriorityNone does nothing.
cannam@124 274
cannam@124 275 @return Error code indicating success or failure.
cannam@124 276 @see PaWasapi_RevertThreadPriority
cannam@124 277 */
cannam@124 278 PaError PaWasapi_ThreadPriorityBoost( void **hTask, PaWasapiThreadPriority nPriorityClass );
cannam@124 279
cannam@124 280
cannam@124 281 /** Boost thread priority of calling thread (MMCSS). Use it for Blocking Interface only for thread
cannam@124 282 which makes calls to Pa_WriteStream/Pa_ReadStream.
cannam@124 283
cannam@124 284 @param hTask Task handle obtained by PaWasapi_BoostThreadPriority method.
cannam@124 285 @return Error code indicating success or failure.
cannam@124 286 @see PaWasapi_BoostThreadPriority
cannam@124 287 */
cannam@124 288 PaError PaWasapi_ThreadPriorityRevert( void *hTask );
cannam@124 289
cannam@124 290
cannam@124 291 /** Get number of frames per host buffer. This is maximal value of frames of WASAPI buffer which
cannam@124 292 can be locked for operations. Use this method as helper to findout maximal values of
cannam@124 293 inputFrames/outputFrames of PaWasapiHostProcessorCallback.
cannam@124 294
cannam@124 295 @param pStream Pointer to PaStream to query.
cannam@124 296 @param nInput Pointer to variable to receive number of input frames. Can be NULL.
cannam@124 297 @param nOutput Pointer to variable to receive number of output frames. Can be NULL.
cannam@124 298 @return Error code indicating success or failure.
cannam@124 299 @see PaWasapiHostProcessorCallback
cannam@124 300 */
cannam@124 301 PaError PaWasapi_GetFramesPerHostBuffer( PaStream *pStream, unsigned int *nInput, unsigned int *nOutput );
cannam@124 302
cannam@124 303
cannam@124 304 /** Get number of jacks associated with a WASAPI device. Use this method to determine if
cannam@124 305 there are any jacks associated with the provided WASAPI device. Not all audio devices
cannam@124 306 will support this capability. This is valid for both input and output devices.
cannam@124 307 @param nDevice device index.
cannam@124 308 @param jcount Number of jacks is returned in this variable
cannam@124 309 @return Error code indicating success or failure
cannam@124 310 @see PaWasapi_GetJackDescription
cannam@124 311 */
cannam@124 312 PaError PaWasapi_GetJackCount(PaDeviceIndex nDevice, int *jcount);
cannam@124 313
cannam@124 314
cannam@124 315 /** Get the jack description associated with a WASAPI device and jack number
cannam@124 316 Before this function is called, use PaWasapi_GetJackCount to determine the
cannam@124 317 number of jacks associated with device. If jcount is greater than zero, then
cannam@124 318 each jack from 0 to jcount can be queried with this function to get the jack
cannam@124 319 description.
cannam@124 320 @param nDevice device index.
cannam@124 321 @param jindex Which jack to return information
cannam@124 322 @param KSJACK_DESCRIPTION This structure filled in on success.
cannam@124 323 @return Error code indicating success or failure
cannam@124 324 @see PaWasapi_GetJackCount
cannam@124 325 */
cannam@124 326 PaError PaWasapi_GetJackDescription(PaDeviceIndex nDevice, int jindex, PaWasapiJackDescription *pJackDescription);
cannam@124 327
cannam@124 328
cannam@124 329 /*
cannam@124 330 IMPORTANT:
cannam@124 331
cannam@124 332 WASAPI is implemented for Callback and Blocking interfaces. It supports Shared and Exclusive
cannam@124 333 share modes.
cannam@124 334
cannam@124 335 Exclusive Mode:
cannam@124 336
cannam@124 337 Exclusive mode allows to deliver audio data directly to hardware bypassing
cannam@124 338 software mixing.
cannam@124 339 Exclusive mode is specified by 'paWinWasapiExclusive' flag.
cannam@124 340
cannam@124 341 Callback Interface:
cannam@124 342
cannam@124 343 Provides best audio quality with low latency. Callback interface is implemented in
cannam@124 344 two versions:
cannam@124 345
cannam@124 346 1) Event-Driven:
cannam@124 347 This is the most powerful WASAPI implementation which provides glitch-free
cannam@124 348 audio at around 3ms latency in Exclusive mode. Lowest possible latency for this mode is
cannam@124 349 3 ms for HD Audio class audio chips. For the Shared mode latency can not be
cannam@124 350 lower than 20 ms.
cannam@124 351
cannam@124 352 2) Poll-Driven:
cannam@124 353 Polling is another 2-nd method to operate with WASAPI. It is less efficient than Event-Driven
cannam@124 354 and provides latency at around 10-13ms. Polling must be used to overcome a system bug
cannam@124 355 under Windows Vista x64 when application is WOW64(32-bit) and Event-Driven method simply
cannam@124 356 times out (event handle is never signalled on buffer completion). Please note, such WOW64 bug
cannam@124 357 does not exist in Vista x86 or Windows 7.
cannam@124 358 Polling can be setup by speciying 'paWinWasapiPolling' flag. Our WASAPI implementation detects
cannam@124 359 WOW64 bug and sets 'paWinWasapiPolling' automatically.
cannam@124 360
cannam@124 361 Thread priority:
cannam@124 362
cannam@124 363 Normally thread priority is set automatically and does not require modification. Although
cannam@124 364 if user wants some tweaking thread priority can be modified by setting 'paWinWasapiThreadPriority'
cannam@124 365 flag and specifying 'PaWasapiStreamInfo::threadPriority' with value from PaWasapiThreadPriority
cannam@124 366 enum.
cannam@124 367
cannam@124 368 Blocking Interface:
cannam@124 369
cannam@124 370 Blocking interface is implemented but due to above described Poll-Driven method can not
cannam@124 371 deliver lowest possible latency. Specifying too low latency in Shared mode will result in
cannam@124 372 distorted audio although Exclusive mode adds stability.
cannam@124 373
cannam@124 374 Pa_IsFormatSupported:
cannam@124 375
cannam@124 376 To check format with correct Share Mode (Exclusive/Shared) you must supply
cannam@124 377 PaWasapiStreamInfo with flags paWinWasapiExclusive set through member of
cannam@124 378 PaStreamParameters::hostApiSpecificStreamInfo structure.
cannam@124 379
cannam@124 380 Pa_OpenStream:
cannam@124 381
cannam@124 382 To set desired Share Mode (Exclusive/Shared) you must supply
cannam@124 383 PaWasapiStreamInfo with flags paWinWasapiExclusive set through member of
cannam@124 384 PaStreamParameters::hostApiSpecificStreamInfo structure.
cannam@124 385 */
cannam@124 386
cannam@124 387 #ifdef __cplusplus
cannam@124 388 }
cannam@124 389 #endif /* __cplusplus */
cannam@124 390
cannam@124 391 #endif /* PA_WIN_WASAPI_H */