Mercurial > hg > sv-dependency-builds

annotate src/portaudio/include/pa_win_wasapi.h @ 94:d278df1123f9

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