1 // NOTE: Copy this file to portaudio.h in order to compile with V18 portaudio 2 3 4 #ifndef PORT_AUDIO_H 5 #define PORT_AUDIO_H 6 7 #ifdef __cplusplus 8 extern "C" 9 { 10 #endif /* __cplusplus */ 11 12 /* 13 * $Id: portaudio.h,v 1.5 2002/03/26 18:04:22 philburk Exp $ 14 * PortAudio Portable Real-Time Audio Library 15 * PortAudio API Header File 16 * Latest version available at: http://www.audiomulch.com/portaudio/ 17 * 18 * Copyright (c) 1999-2000 Ross Bencina and Phil Burk 19 * 20 * Permission is hereby granted, free of charge, to any person obtaining 21 * a copy of this software and associated documentation files 22 * (the "Software"), to deal in the Software without restriction, 23 * including without limitation the rights to use, copy, modify, merge, 24 * publish, distribute, sublicense, and/or sell copies of the Software, 25 * and to permit persons to whom the Software is furnished to do so, 26 * subject to the following conditions: 27 * 28 * The above copyright notice and this permission notice shall be 29 * included in all copies or substantial portions of the Software. 30 * 31 * Any person wishing to distribute modifications to the Software is 32 * requested to send the modifications to the original developer so that 33 * they can be incorporated into the canonical version. 34 * 35 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 36 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 37 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 38 * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR 39 * ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF 40 * CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION 41 * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 42 * 43 */ 44 45 typedef int PaError; 46 typedef enum { 47 paNoError = 0, 48 49 paHostError = -10000, 50 paInvalidChannelCount, 51 paInvalidSampleRate, 52 paInvalidDeviceId, 53 paInvalidFlag, 54 paSampleFormatNotSupported, 55 paBadIODeviceCombination, 56 paInsufficientMemory, 57 paBufferTooBig, 58 paBufferTooSmall, 59 paNullCallback, 60 paBadStreamPtr, 61 paTimedOut, 62 paInternalError, 63 paDeviceUnavailable 64 } PaErrorNum; 65 66 /* 67 Pa_Initialize() is the library initialisation function - call this before 68 using the library. 69 70 */ 71 72 PaError Pa_Initialize( void ); 73 74 /* 75 Pa_Terminate() is the library termination function - call this after 76 using the library. 77 78 */ 79 80 PaError Pa_Terminate( void ); 81 82 /* 83 Pa_GetHostError() returns a host specific error code. 84 This can be called after receiving a PortAudio error code of paHostError. 85 86 */ 87 88 long Pa_GetHostError( void ); 89 90 /* 91 Pa_GetErrorText() translates the supplied PortAudio error number 92 into a human readable message. 93 94 */ 95 96 const char *Pa_GetErrorText( PaError errnum ); 97 98 /* 99 Sample formats 100 101 These are formats used to pass sound data between the callback and the 102 stream. Each device has a "native" format which may be used when optimum 103 efficiency or control over conversion is required. 104 105 Formats marked "always available" are supported (emulated) by all 106 PortAudio implementations. 107 108 The floating point representation (paFloat32) uses +1.0 and -1.0 as the 109 maximum and minimum respectively. 110 111 paUInt8 is an unsigned 8 bit format where 128 is considered "ground" 112 113 */ 114 115 typedef unsigned long PaSampleFormat; 116 #define paFloat32 ((PaSampleFormat) (1<<0)) /*always available*/ 117 #define paInt16 ((PaSampleFormat) (1<<1)) /*always available*/ 118 #define paInt32 ((PaSampleFormat) (1<<2)) /*always available*/ 119 #define paInt24 ((PaSampleFormat) (1<<3)) 120 #define paPackedInt24 ((PaSampleFormat) (1<<4)) 121 #define paInt8 ((PaSampleFormat) (1<<5)) 122 #define paUInt8 ((PaSampleFormat) (1<<6)) 123 #define paCustomFormat ((PaSampleFormat) (1<<16)) 124 125 /* 126 Device enumeration mechanism. 127 128 Device ids range from 0 to Pa_CountDevices()-1. 129 130 Devices may support input, output or both. 131 132 */ 133 134 typedef int PaDeviceID; 135 #define paNoDevice -1 136 137 int Pa_CountDevices( void ); 138 139 typedef struct 140 { 141 int structVersion; 142 const char *name; 143 int maxInputChannels; 144 int maxOutputChannels; 145 /* Number of discrete rates, or -1 if range supported. */ 146 int numSampleRates; 147 /* Array of supported sample rates, or {min,max} if range supported. */ 148 const double *sampleRates; 149 PaSampleFormat nativeSampleFormats; 150 } 151 PaDeviceInfo; 152 153 /* 154 Pa_GetDefaultInputDeviceID(), Pa_GetDefaultOutputDeviceID() return the 155 default device ids for input and output respectively, or paNoDevice if 156 no device is available. 157 The result can be passed to Pa_OpenStream(). 158 159 On the PC, the user can specify a default device by 160 setting an environment variable. For example, to use device #1. 161 162 set PA_RECOMMENDED_OUTPUT_DEVICE=1 163 164 The user should first determine the available device ids by using 165 the supplied application "pa_devs". 166 167 */ 168 169 PaDeviceID Pa_GetDefaultInputDeviceID( void ); 170 PaDeviceID Pa_GetDefaultOutputDeviceID( void ); 171 172 173 174 /* 175 Pa_GetDeviceInfo() returns a pointer to an immutable PaDeviceInfo structure 176 for the device specified. 177 If the device parameter is out of range the function returns NULL. 178 179 PortAudio manages the memory referenced by the returned pointer, the client 180 must not manipulate or free the memory. The pointer is only guaranteed to be 181 valid between calls to Pa_Initialize() and Pa_Terminate(). 182 183 */ 184 185 const PaDeviceInfo* Pa_GetDeviceInfo( PaDeviceID device ); 186 187 /* 188 PaTimestamp is used to represent a continuous sample clock with arbitrary 189 start time that can be used for syncronization. The type is used for the 190 outTime argument to the PortAudioCallback and as the result of Pa_StreamTime() 191 192 */ 193 194 typedef double PaTimestamp; 195 196 /* 197 PortAudioCallback is implemented by PortAudio clients. 198 199 inputBuffer and outputBuffer are arrays of interleaved samples, 200 the format, packing and number of channels used by the buffers are 201 determined by parameters to Pa_OpenStream() (see below). 202 203 framesPerBuffer is the number of sample frames to be processed by the callback. 204 205 outTime is the time in samples when the buffer(s) processed by 206 this callback will begin being played at the audio output. 207 See also Pa_StreamTime() 208 209 userData is the value of a user supplied pointer passed to Pa_OpenStream() 210 intended for storing synthesis data etc. 211 212 return value: 213 The callback can return a non-zero value to stop the stream. This may be 214 useful in applications such as soundfile players where a specific duration 215 of output is required. However, it is not necessary to utilise this mechanism 216 as StopStream() will also terminate the stream. A callback returning a 217 non-zero value must fill the entire outputBuffer. 218 219 NOTE: None of the other stream functions may be called from within the 220 callback function except for Pa_GetCPULoad(). 221 222 */ 223 224 typedef int (PortAudioCallback)( 225 void *inputBuffer, void *outputBuffer, 226 unsigned long framesPerBuffer, 227 PaTimestamp outTime, void *userData ); 228 229 230 /* 231 Stream flags 232 233 These flags may be supplied (ored together) in the streamFlags argument to 234 the Pa_OpenStream() function. 235 236 */ 237 238 #define paNoFlag (0) 239 #define paClipOff (1<<0) /* disable default clipping of out of range samples */ 240 #define paDitherOff (1<<1) /* disable default dithering */ 241 #define paPlatformSpecificFlags (0x00010000) 242 typedef unsigned long PaStreamFlags; 243 244 /* 245 A single PortAudioStream provides multiple channels of real-time 246 input and output audio streaming to a client application. 247 Pointers to PortAudioStream objects are passed between PortAudio functions. 248 */ 249 250 typedef void PortAudioStream; 251 #define PaStream PortAudioStream 252 253 /* 254 Pa_OpenStream() opens a stream for either input, output or both. 255 256 stream is the address of a PortAudioStream pointer which will receive 257 a pointer to the newly opened stream. 258 259 inputDevice is the id of the device used for input (see PaDeviceID above.) 260 inputDevice may be paNoDevice to indicate that an input device is not required. 261 262 numInputChannels is the number of channels of sound to be delivered to the 263 callback. It can range from 1 to the value of maxInputChannels in the 264 PaDeviceInfo record for the device specified by the inputDevice parameter. 265 If inputDevice is paNoDevice numInputChannels is ignored. 266 267 inputSampleFormat is the sample format of inputBuffer provided to the callback 268 function. inputSampleFormat may be any of the formats described by the 269 PaSampleFormat enumeration (see above). PortAudio guarantees support for 270 the device's native formats (nativeSampleFormats in the device info record) 271 and additionally 16 and 32 bit integer and 32 bit floating point formats. 272 Support for other formats is implementation defined. 273 274 inputDriverInfo is a pointer to an optional driver specific data structure 275 containing additional information for device setup or stream processing. 276 inputDriverInfo is never required for correct operation. If not used 277 inputDriverInfo should be NULL. 278 279 outputDevice is the id of the device used for output (see PaDeviceID above.) 280 outputDevice may be paNoDevice to indicate that an output device is not required. 281 282 numOutputChannels is the number of channels of sound to be supplied by the 283 callback. See the definition of numInputChannels above for more details. 284 285 outputSampleFormat is the sample format of the outputBuffer filled by the 286 callback function. See the definition of inputSampleFormat above for more 287 details. 288 289 outputDriverInfo is a pointer to an optional driver specific data structure 290 containing additional information for device setup or stream processing. 291 outputDriverInfo is never required for correct operation. If not used 292 outputDriverInfo should be NULL. 293 294 sampleRate is the desired sampleRate. For full-duplex streams it is the 295 sample rate for both input and output 296 297 framesPerBuffer is the length in sample frames of all internal sample buffers 298 used for communication with platform specific audio routines. Wherever 299 possible this corresponds to the framesPerBuffer parameter passed to the 300 callback function. 301 302 numberOfBuffers is the number of buffers used for multibuffered communication 303 with the platform specific audio routines. If you pass zero, then an optimum 304 value will be chosen for you internally. This parameter is provided only 305 as a guide - and does not imply that an implementation must use multibuffered 306 i/o when reliable double buffering is available (such as SndPlayDoubleBuffer() 307 on the Macintosh.) 308 309 streamFlags may contain a combination of flags ORed together. 310 These flags modify the behaviour of the streaming process. Some flags may only 311 be relevant to certain buffer formats. 312 313 callback is a pointer to a client supplied function that is responsible 314 for processing and filling input and output buffers (see above for details.) 315 316 userData is a client supplied pointer which is passed to the callback 317 function. It could for example, contain a pointer to instance data necessary 318 for processing the audio buffers. 319 320 return value: 321 Upon success Pa_OpenStream() returns PaNoError and places a pointer to a 322 valid PortAudioStream in the stream argument. The stream is inactive (stopped). 323 If a call to Pa_OpenStream() fails a non-zero error code is returned (see 324 PaError above) and the value of stream is invalid. 325 326 */ 327 328 PaError Pa_OpenStream( PortAudioStream** stream, 329 PaDeviceID inputDevice, 330 int numInputChannels, 331 PaSampleFormat inputSampleFormat, 332 void *inputDriverInfo, 333 PaDeviceID outputDevice, 334 int numOutputChannels, 335 PaSampleFormat outputSampleFormat, 336 void *outputDriverInfo, 337 double sampleRate, 338 unsigned long framesPerBuffer, 339 unsigned long numberOfBuffers, 340 PaStreamFlags streamFlags, 341 PortAudioCallback *callback, 342 void *userData ); 343 344 345 /* 346 Pa_OpenDefaultStream() is a simplified version of Pa_OpenStream() that opens 347 the default input and/or output devices. Most parameters have identical meaning 348 to their Pa_OpenStream() counterparts, with the following exceptions: 349 350 If either numInputChannels or numOutputChannels is 0 the respective device 351 is not opened. This has the same effect as passing paNoDevice in the device 352 arguments to Pa_OpenStream(). 353 354 sampleFormat applies to both the input and output buffers. 355 356 */ 357 358 PaError Pa_OpenDefaultStream( PortAudioStream** stream, 359 int numInputChannels, 360 int numOutputChannels, 361 PaSampleFormat sampleFormat, 362 double sampleRate, 363 unsigned long framesPerBuffer, 364 unsigned long numberOfBuffers, 365 PortAudioCallback *callback, 366 void *userData ); 367 368 /* 369 Pa_CloseStream() closes an audio stream, flushing any pending buffers. 370 371 */ 372 373 PaError Pa_CloseStream( PortAudioStream* ); 374 375 /* 376 Pa_StartStream() and Pa_StopStream() begin and terminate audio processing. 377 Pa_StopStream() waits until all pending audio buffers have been played. 378 Pa_AbortStream() stops playing immediately without waiting for pending 379 buffers to complete. 380 381 */ 382 383 PaError Pa_StartStream( PortAudioStream *stream ); 384 385 PaError Pa_StopStream( PortAudioStream *stream ); 386 387 PaError Pa_AbortStream( PortAudioStream *stream ); 388 389 /* 390 Pa_StreamActive() returns one (1) when the stream is active (ie playing 391 or recording audio), zero (0) when not playing, or a negative error number 392 if the stream is invalid. 393 The stream is active between calls to Pa_StartStream() and Pa_StopStream(), 394 but may also become inactive if the callback returns a non-zero value. 395 In the latter case, the stream is considered inactive after the last 396 buffer has finished playing. 397 398 */ 399 400 PaError Pa_StreamActive( PortAudioStream *stream ); 401 402 /* 403 Pa_StreamTime() returns the current output time in samples for the stream. 404 This time may be used as a time reference (for example synchronizing audio to 405 MIDI). 406 407 */ 408 409 PaTimestamp Pa_StreamTime( PortAudioStream *stream ); 410 411 /* 412 Pa_GetCPULoad() returns the CPU Load for the stream. 413 The "CPU Load" is a fraction of total CPU time consumed by the stream's 414 audio processing routines including, but not limited to the client supplied 415 callback. 416 A value of 0.5 would imply that PortAudio and the sound generating 417 callback was consuming roughly 50% of the available CPU time. 418 This function may be called from the callback function or the application. 419 420 */ 421 422 double Pa_GetCPULoad( PortAudioStream* stream ); 423 424 /* 425 Pa_GetMinNumBuffers() returns the minimum number of buffers required by 426 the current host based on minimum latency. 427 On the PC, for the DirectSound implementation, latency can be optionally set 428 by user by setting an environment variable. 429 For example, to set latency to 200 msec, put: 430 431 set PA_MIN_LATENCY_MSEC=200 432 433 in the AUTOEXEC.BAT file and reboot. 434 If the environment variable is not set, then the latency will be determined 435 based on the OS. Windows NT has higher latency than Win95. 436 437 */ 438 439 int Pa_GetMinNumBuffers( int framesPerBuffer, double sampleRate ); 440 441 /* 442 Pa_Sleep() puts the caller to sleep for at least 'msec' milliseconds. 443 You may sleep longer than the requested time so don't rely on this for 444 accurate musical timing. 445 446 Pa_Sleep() is provided as a convenience for authors of portable code (such as 447 the tests and examples in the PortAudio distribution.) 448 449 */ 450 451 void Pa_Sleep( long msec ); 452 453 /* 454 Pa_GetSampleSize() returns the size in bytes of a single sample in the 455 supplied PaSampleFormat, or paSampleFormatNotSupported if the format is 456 no supported. 457 458 */ 459 460 PaError Pa_GetSampleSize( PaSampleFormat format ); 461 462 463 #ifdef __cplusplus 464 } 465 #endif /* __cplusplus */ 466 #endif /* PORT_AUDIO_H */ 467