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