PageRenderTime 35ms CodeModel.GetById 17ms app.highlight 12ms RepoModel.GetById 1ms app.codeStats 0ms

/native/external/espeak/src/portaudio18.h

http://eyes-free.googlecode.com/
C++ Header | 466 lines | 105 code | 60 blank | 301 comment | 0 complexity | 65d60b228929657a6875751b6014b8c2 MD5 | raw file
  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
  8extern "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
 45typedef int PaError;
 46typedef 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
 72PaError Pa_Initialize( void );
 73
 74/*
 75 Pa_Terminate() is the library termination function - call this after
 76 using the library.
 77
 78*/
 79
 80PaError 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
 88long Pa_GetHostError( void );
 89
 90/*
 91 Pa_GetErrorText() translates the supplied PortAudio error number
 92 into a human readable message.
 93 
 94*/
 95
 96const 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
115typedef 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
134typedef int PaDeviceID;
135#define paNoDevice -1
136
137int Pa_CountDevices( void );
138
139typedef 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}
151PaDeviceInfo;
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
169PaDeviceID Pa_GetDefaultInputDeviceID( void );
170PaDeviceID 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
185const 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
194typedef 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
224typedef 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)
242typedef   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
250typedef 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
328PaError 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
358PaError 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
373PaError 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
383PaError Pa_StartStream( PortAudioStream *stream );
384
385PaError Pa_StopStream( PortAudioStream *stream );
386
387PaError 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
400PaError 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
409PaTimestamp 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
422double 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
439int 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
451void 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
460PaError Pa_GetSampleSize( PaSampleFormat format );
461
462
463#ifdef __cplusplus
464}
465#endif /* __cplusplus */
466#endif /* PORT_AUDIO_H */