Navit SVN

/work/compile/navit/src/navit/support/espeak/portaudio18.h

00001 // NOTE: Copy this file to  portaudio.h  in order to compile with V18 portaudio
00002 
00003 
00004 #ifndef PORT_AUDIO_H
00005 #define PORT_AUDIO_H
00006 
00007 #ifdef __cplusplus
00008 extern "C"
00009 {
00010 #endif /* __cplusplus */
00011 
00012 /*
00013  * $Id: portaudio.h,v 1.5 2002/03/26 18:04:22 philburk Exp $
00014  * PortAudio Portable Real-Time Audio Library
00015  * PortAudio API Header File
00016  * Latest version available at: http://www.audiomulch.com/portaudio/
00017  *
00018  * Copyright (c) 1999-2000 Ross Bencina and Phil Burk
00019  *
00020  * Permission is hereby granted, free of charge, to any person obtaining
00021  * a copy of this software and associated documentation files
00022  * (the "Software"), to deal in the Software without restriction,
00023  * including without limitation the rights to use, copy, modify, merge,
00024  * publish, distribute, sublicense, and/or sell copies of the Software,
00025  * and to permit persons to whom the Software is furnished to do so,
00026  * subject to the following conditions:
00027  *
00028  * The above copyright notice and this permission notice shall be
00029  * included in all copies or substantial portions of the Software.
00030  *
00031  * Any person wishing to distribute modifications to the Software is
00032  * requested to send the modifications to the original developer so that
00033  * they can be incorporated into the canonical version.
00034  *
00035  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
00036  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
00037  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
00038  * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR
00039  * ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
00040  * CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
00041  * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
00042  *
00043  */
00044 
00045 typedef int PaError;
00046 typedef enum {
00047     paNoError = 0,
00048 
00049     paHostError = -10000,
00050     paInvalidChannelCount,
00051     paInvalidSampleRate,
00052     paInvalidDeviceId,
00053     paInvalidFlag,
00054     paSampleFormatNotSupported,
00055     paBadIODeviceCombination,
00056     paInsufficientMemory,
00057     paBufferTooBig,
00058     paBufferTooSmall,
00059     paNullCallback,
00060     paBadStreamPtr,
00061     paTimedOut,
00062     paInternalError,
00063     paDeviceUnavailable
00064 } PaErrorNum;
00065 
00066 /*
00067  Pa_Initialize() is the library initialisation function - call this before
00068  using the library.
00069 
00070 */
00071 
00072 PaError Pa_Initialize( void );
00073 
00074 /*
00075  Pa_Terminate() is the library termination function - call this after
00076  using the library.
00077 
00078 */
00079 
00080 PaError Pa_Terminate( void );
00081 
00082 /*
00083  Pa_GetHostError() returns a host specific error code.
00084  This can be called after receiving a PortAudio error code of paHostError.
00085 
00086 */
00087 
00088 long Pa_GetHostError( void );
00089 
00090 /*
00091  Pa_GetErrorText() translates the supplied PortAudio error number
00092  into a human readable message.
00093  
00094 */
00095 
00096 const char *Pa_GetErrorText( PaError errnum );
00097 
00098 /*
00099  Sample formats
00100  
00101  These are formats used to pass sound data between the callback and the
00102  stream. Each device has a "native" format which may be used when optimum
00103  efficiency or control over conversion is required.
00104  
00105  Formats marked "always available" are supported (emulated) by all 
00106  PortAudio implementations.
00107  
00108  The floating point representation (paFloat32) uses +1.0 and -1.0 as the 
00109  maximum and minimum respectively.
00110 
00111  paUInt8 is an unsigned 8 bit format where 128 is considered "ground"
00112 
00113 */
00114 
00115 typedef unsigned long PaSampleFormat;
00116 #define paFloat32      ((PaSampleFormat) (1<<0)) /*always available*/
00117 #define paInt16        ((PaSampleFormat) (1<<1)) /*always available*/
00118 #define paInt32        ((PaSampleFormat) (1<<2)) /*always available*/
00119 #define paInt24        ((PaSampleFormat) (1<<3))
00120 #define paPackedInt24  ((PaSampleFormat) (1<<4))
00121 #define paInt8         ((PaSampleFormat) (1<<5))
00122 #define paUInt8        ((PaSampleFormat) (1<<6))
00123 #define paCustomFormat ((PaSampleFormat) (1<<16))
00124 
00125 /*
00126  Device enumeration mechanism.
00127  
00128  Device ids range from 0 to Pa_CountDevices()-1.
00129  
00130  Devices may support input, output or both.
00131 
00132 */
00133 
00134 typedef int PaDeviceID;
00135 #define paNoDevice -1
00136 
00137 int Pa_CountDevices( void );
00138 
00139 typedef struct
00140 {
00141     int structVersion;
00142     const char *name;
00143     int maxInputChannels;
00144     int maxOutputChannels;
00145     /* Number of discrete rates, or -1 if range supported. */
00146     int numSampleRates;
00147     /* Array of supported sample rates, or {min,max} if range supported. */
00148     const double *sampleRates;
00149     PaSampleFormat nativeSampleFormats;
00150 }
00151 PaDeviceInfo;
00152 
00153 /*
00154  Pa_GetDefaultInputDeviceID(), Pa_GetDefaultOutputDeviceID() return the
00155  default device ids for input and output respectively, or paNoDevice if
00156  no device is available.
00157  The result can be passed to Pa_OpenStream().
00158  
00159  On the PC, the user can specify a default device by
00160  setting an environment variable. For example, to use device #1.
00161  
00162   set PA_RECOMMENDED_OUTPUT_DEVICE=1
00163  
00164  The user should first determine the available device ids by using
00165  the supplied application "pa_devs".
00166 
00167 */
00168 
00169 PaDeviceID Pa_GetDefaultInputDeviceID( void );
00170 PaDeviceID Pa_GetDefaultOutputDeviceID( void );
00171 
00172 
00173 
00174 /*
00175  Pa_GetDeviceInfo() returns a pointer to an immutable PaDeviceInfo structure
00176  for the device specified.
00177  If the device parameter is out of range the function returns NULL.
00178 
00179  PortAudio manages the memory referenced by the returned pointer, the client
00180  must not manipulate or free the memory. The pointer is only guaranteed to be
00181  valid between calls to Pa_Initialize() and Pa_Terminate().
00182 
00183 */
00184 
00185 const PaDeviceInfo* Pa_GetDeviceInfo( PaDeviceID device );
00186 
00187 /*
00188  PaTimestamp is used to represent a continuous sample clock with arbitrary
00189  start time that can be used for syncronization. The type is used for the
00190  outTime argument to the PortAudioCallback and as the result of Pa_StreamTime()
00191 
00192 */
00193 
00194 typedef double PaTimestamp;
00195 
00196 /*
00197  PortAudioCallback is implemented by PortAudio clients.
00198  
00199  inputBuffer and outputBuffer are arrays of interleaved samples,
00200  the format, packing and number of channels used by the buffers are
00201  determined by parameters to Pa_OpenStream() (see below).
00202  
00203  framesPerBuffer is the number of sample frames to be processed by the callback.
00204  
00205  outTime is the time in samples when the buffer(s) processed by
00206  this callback will begin being played at the audio output.
00207  See also Pa_StreamTime()
00208  
00209  userData is the value of a user supplied pointer passed to Pa_OpenStream()
00210  intended for storing synthesis data etc.
00211  
00212  return value:
00213  The callback can return a non-zero value to stop the stream. This may be
00214  useful in applications such as soundfile players where a specific duration
00215  of output is required. However, it is not necessary to utilise this mechanism
00216  as StopStream() will also terminate the stream. A callback returning a
00217  non-zero value must fill the entire outputBuffer.
00218  
00219  NOTE: None of the other stream functions may be called from within the
00220  callback function except for Pa_GetCPULoad().
00221 
00222 */
00223 
00224 typedef int (PortAudioCallback)(
00225     void *inputBuffer, void *outputBuffer,
00226     unsigned long framesPerBuffer,
00227     PaTimestamp outTime, void *userData );
00228 
00229 
00230 /*
00231  Stream flags
00232  
00233  These flags may be supplied (ored together) in the streamFlags argument to
00234  the Pa_OpenStream() function.
00235 
00236 */
00237 
00238 #define   paNoFlag      (0)
00239 #define   paClipOff     (1<<0)   /* disable default clipping of out of range samples */
00240 #define   paDitherOff   (1<<1)   /* disable default dithering */
00241 #define   paPlatformSpecificFlags (0x00010000)
00242 typedef   unsigned long PaStreamFlags;
00243 
00244 /*
00245  A single PortAudioStream provides multiple channels of real-time
00246  input and output audio streaming to a client application.
00247  Pointers to PortAudioStream objects are passed between PortAudio functions.
00248 */
00249 
00250 typedef void PortAudioStream;
00251 #define PaStream PortAudioStream
00252 
00253 /*
00254  Pa_OpenStream() opens a stream for either input, output or both.
00255  
00256  stream is the address of a PortAudioStream pointer which will receive
00257  a pointer to the newly opened stream.
00258  
00259  inputDevice is the id of the device used for input (see PaDeviceID above.)
00260  inputDevice may be paNoDevice to indicate that an input device is not required.
00261  
00262  numInputChannels is the number of channels of sound to be delivered to the
00263  callback. It can range from 1 to the value of maxInputChannels in the
00264  PaDeviceInfo record for the device specified by the inputDevice parameter.
00265  If inputDevice is paNoDevice numInputChannels is ignored.
00266  
00267  inputSampleFormat is the sample format of inputBuffer provided to the callback
00268  function. inputSampleFormat may be any of the formats described by the
00269  PaSampleFormat enumeration (see above). PortAudio guarantees support for
00270  the device's native formats (nativeSampleFormats in the device info record)
00271  and additionally 16 and 32 bit integer and 32 bit floating point formats.
00272  Support for other formats is implementation defined.
00273  
00274  inputDriverInfo is a pointer to an optional driver specific data structure
00275  containing additional information for device setup or stream processing.
00276  inputDriverInfo is never required for correct operation. If not used
00277  inputDriverInfo should be NULL.
00278  
00279  outputDevice is the id of the device used for output (see PaDeviceID above.)
00280  outputDevice may be paNoDevice to indicate that an output device is not required.
00281  
00282  numOutputChannels is the number of channels of sound to be supplied by the
00283  callback. See the definition of numInputChannels above for more details.
00284  
00285  outputSampleFormat is the sample format of the outputBuffer filled by the
00286  callback function. See the definition of inputSampleFormat above for more
00287  details.
00288  
00289  outputDriverInfo is a pointer to an optional driver specific data structure
00290  containing additional information for device setup or stream processing.
00291  outputDriverInfo is never required for correct operation. If not used
00292  outputDriverInfo should be NULL.
00293  
00294  sampleRate is the desired sampleRate. For full-duplex streams it is the
00295  sample rate for both input and output
00296  
00297  framesPerBuffer is the length in sample frames of all internal sample buffers
00298  used for communication with platform specific audio routines. Wherever
00299  possible this corresponds to the framesPerBuffer parameter passed to the
00300  callback function.
00301  
00302  numberOfBuffers is the number of buffers used for multibuffered communication
00303  with the platform specific audio routines. If you pass zero, then an optimum
00304  value will be chosen for you internally. This parameter is provided only
00305  as a guide - and does not imply that an implementation must use multibuffered
00306  i/o when reliable double buffering is available (such as SndPlayDoubleBuffer()
00307  on the Macintosh.)
00308  
00309  streamFlags may contain a combination of flags ORed together.
00310  These flags modify the behaviour of the streaming process. Some flags may only
00311  be relevant to certain buffer formats.
00312  
00313  callback is a pointer to a client supplied function that is responsible
00314  for processing and filling input and output buffers (see above for details.)
00315  
00316  userData is a client supplied pointer which is passed to the callback
00317  function. It could for example, contain a pointer to instance data necessary
00318  for processing the audio buffers.
00319  
00320  return value:
00321  Upon success Pa_OpenStream() returns PaNoError and places a pointer to a
00322  valid PortAudioStream in the stream argument. The stream is inactive (stopped).
00323  If a call to Pa_OpenStream() fails a non-zero error code is returned (see
00324  PaError above) and the value of stream is invalid.
00325  
00326 */
00327 
00328 PaError Pa_OpenStream( PortAudioStream** stream,
00329                        PaDeviceID inputDevice,
00330                        int numInputChannels,
00331                        PaSampleFormat inputSampleFormat,
00332                        void *inputDriverInfo,
00333                        PaDeviceID outputDevice,
00334                        int numOutputChannels,
00335                        PaSampleFormat outputSampleFormat,
00336                        void *outputDriverInfo,
00337                        double sampleRate,
00338                        unsigned long framesPerBuffer,
00339                        unsigned long numberOfBuffers,
00340                        PaStreamFlags streamFlags,
00341                        PortAudioCallback *callback,
00342                        void *userData );
00343 
00344 
00345 /*
00346  Pa_OpenDefaultStream() is a simplified version of Pa_OpenStream() that opens
00347  the default input and/or output devices. Most parameters have identical meaning
00348  to their Pa_OpenStream() counterparts, with the following exceptions:
00349  
00350  If either numInputChannels or numOutputChannels is 0 the respective device
00351  is not opened. This has the same effect as passing paNoDevice in the device
00352  arguments to Pa_OpenStream().
00353  
00354  sampleFormat applies to both the input and output buffers.
00355 
00356 */
00357 
00358 PaError Pa_OpenDefaultStream( PortAudioStream** stream,
00359                               int numInputChannels,
00360                               int numOutputChannels,
00361                               PaSampleFormat sampleFormat,
00362                               double sampleRate,
00363                               unsigned long framesPerBuffer,
00364                               unsigned long numberOfBuffers,
00365                               PortAudioCallback *callback,
00366                               void *userData );
00367 
00368 /*
00369  Pa_CloseStream() closes an audio stream, flushing any pending buffers.
00370 
00371 */
00372 
00373 PaError Pa_CloseStream( PortAudioStream* );
00374 
00375 /*
00376  Pa_StartStream() and Pa_StopStream() begin and terminate audio processing.
00377  Pa_StopStream() waits until all pending audio buffers have been played.
00378  Pa_AbortStream() stops playing immediately without waiting for pending
00379  buffers to complete.
00380     
00381 */
00382 
00383 PaError Pa_StartStream( PortAudioStream *stream );
00384 
00385 PaError Pa_StopStream( PortAudioStream *stream );
00386 
00387 PaError Pa_AbortStream( PortAudioStream *stream );
00388 
00389 /*
00390  Pa_StreamActive() returns one (1) when the stream is active (ie playing
00391  or recording audio), zero (0) when not playing, or a negative error number
00392  if the stream is invalid.
00393  The stream is active between calls to Pa_StartStream() and Pa_StopStream(),
00394  but may also become inactive if the callback returns a non-zero value.
00395  In the latter case, the stream is considered inactive after the last
00396  buffer has finished playing.
00397  
00398 */
00399 
00400 PaError Pa_StreamActive( PortAudioStream *stream );
00401 
00402 /*
00403  Pa_StreamTime() returns the current output time in samples for the stream.
00404  This time may be used as a time reference (for example synchronizing audio to
00405  MIDI).
00406  
00407 */
00408 
00409 PaTimestamp Pa_StreamTime( PortAudioStream *stream );
00410 
00411 /*
00412  Pa_GetCPULoad() returns the CPU Load for the stream.
00413  The "CPU Load" is a fraction of total CPU time consumed by the stream's
00414  audio processing routines including, but not limited to the client supplied
00415  callback.
00416  A value of 0.5 would imply that PortAudio and the sound generating
00417  callback was consuming roughly 50% of the available CPU time.
00418  This function may be called from the callback function or the application.
00419  
00420 */
00421 
00422 double Pa_GetCPULoad( PortAudioStream* stream );
00423 
00424 /*
00425  Pa_GetMinNumBuffers() returns the minimum number of buffers required by
00426  the current host based on minimum latency.
00427  On the PC, for the DirectSound implementation, latency can be optionally set
00428  by user by setting an environment variable.
00429  For example, to set latency to 200 msec, put:
00430  
00431     set PA_MIN_LATENCY_MSEC=200
00432  
00433  in the AUTOEXEC.BAT file and reboot.
00434  If the environment variable is not set, then the latency will be determined
00435  based on the OS. Windows NT has higher latency than Win95.
00436  
00437 */
00438 
00439 int Pa_GetMinNumBuffers( int framesPerBuffer, double sampleRate );
00440 
00441 /*
00442  Pa_Sleep() puts the caller to sleep for at least 'msec' milliseconds.
00443  You may sleep longer than the requested time so don't rely on this for
00444  accurate musical timing.
00445  
00446  Pa_Sleep() is provided as a convenience for authors of portable code (such as
00447  the tests and examples in the PortAudio distribution.)
00448  
00449 */
00450 
00451 void Pa_Sleep( long msec );
00452 
00453 /*
00454  Pa_GetSampleSize() returns the size in bytes of a single sample in the
00455  supplied PaSampleFormat, or paSampleFormatNotSupported if the format is
00456  no supported.
00457   
00458 */
00459 
00460 PaError Pa_GetSampleSize( PaSampleFormat format );
00461 
00462 
00463 #ifdef __cplusplus
00464 }
00465 #endif /* __cplusplus */
00466 #endif /* PORT_AUDIO_H */