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