PortAudio  2.0
portaudio.h
Go to the documentation of this file.
1 #ifndef PORTAUDIO_H
2 #define PORTAUDIO_H
3 /*
4  * $Id$
5  * PortAudio Portable Real-Time Audio Library
6  * PortAudio API Header File
7  * Latest version available at: http://www.portaudio.com/
8  *
9  * Copyright (c) 1999-2002 Ross Bencina and Phil Burk
10  *
11  * Permission is hereby granted, free of charge, to any person obtaining
12  * a copy of this software and associated documentation files
13  * (the "Software"), to deal in the Software without restriction,
14  * including without limitation the rights to use, copy, modify, merge,
15  * publish, distribute, sublicense, and/or sell copies of the Software,
16  * and to permit persons to whom the Software is furnished to do so,
17  * subject to the following conditions:
18  *
19  * The above copyright notice and this permission notice shall be
20  * included in all copies or substantial portions of the Software.
21  *
22  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
23  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
24  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
25  * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR
26  * ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
27  * CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
28  * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
29  */
30 
31 /*
32  * The text above constitutes the entire PortAudio license; however,
33  * the PortAudio community also makes the following non-binding requests:
34  *
35  * Any person wishing to distribute modifications to the Software is
36  * requested to send the modifications to the original developer so that
37  * they can be incorporated into the canonical version. It is also
38  * requested that these non-binding requests be included along with the
39  * license above.
40  */
41 
48 #ifdef __cplusplus
49 extern "C"
50 {
51 #endif /* __cplusplus */
52 
58 int Pa_GetVersion( void );
59 
67 const char* Pa_GetVersionText( void );
68 
81 #define paMakeVersionNumber(major, minor, subminor) \
82  (((major)&0xFF)<<16 | ((minor)&0xFF)<<8 | ((subminor)&0xFF))
83 
84 
90 typedef struct PaVersionInfo {
91  int versionMajor;
92  int versionMinor;
93  int versionSubMinor;
101  const char *versionText;
102 } PaVersionInfo;
103 
114 const PaVersionInfo* Pa_GetVersionInfo( void );
115 
116 
121 typedef int PaError;
122 typedef enum PaErrorCode
123 {
124  paNoError = 0,
125 
126  paNotInitialized = -10000,
127  paUnanticipatedHostError,
128  paInvalidChannelCount,
129  paInvalidSampleRate,
130  paInvalidDevice,
131  paInvalidFlag,
132  paSampleFormatNotSupported,
133  paBadIODeviceCombination,
134  paInsufficientMemory,
135  paBufferTooBig,
136  paBufferTooSmall,
137  paNullCallback,
138  paBadStreamPtr,
139  paTimedOut,
140  paInternalError,
141  paDeviceUnavailable,
142  paIncompatibleHostApiSpecificStreamInfo,
143  paStreamIsStopped,
144  paStreamIsNotStopped,
145  paInputOverflowed,
146  paOutputUnderflowed,
147  paHostApiNotFound,
148  paInvalidHostApi,
149  paCanNotReadFromACallbackStream,
150  paCanNotWriteToACallbackStream,
151  paCanNotReadFromAnOutputOnlyStream,
152  paCanNotWriteToAnInputOnlyStream,
153  paIncompatibleStreamHostApi,
154  paBadBufferPtr
155 } PaErrorCode;
156 
157 
161 const char *Pa_GetErrorText( PaError errorCode );
162 
163 
183 PaError Pa_Initialize( void );
184 
185 
202 PaError Pa_Terminate( void );
203 
204 
205 
212 typedef int PaDeviceIndex;
213 
214 
220 #define paNoDevice ((PaDeviceIndex)-1)
221 
222 
228 #define paUseHostApiSpecificDeviceSpecification ((PaDeviceIndex)-2)
229 
230 
231 /* Host API enumeration mechanism */
232 
238 typedef int PaHostApiIndex;
239 
240 
250 PaHostApiIndex Pa_GetHostApiCount( void );
251 
252 
261 PaHostApiIndex Pa_GetDefaultHostApi( void );
262 
263 
275 typedef enum PaHostApiTypeId
276 {
277  paInDevelopment=0, /* use while developing support for a new host API */
278  paDirectSound=1,
279  paMME=2,
280  paASIO=3,
281  paSoundManager=4,
282  paCoreAudio=5,
283  paOSS=7,
284  paALSA=8,
285  paAL=9,
286  paBeOS=10,
287  paWDMKS=11,
288  paJACK=12,
289  paWASAPI=13,
290  paAudioScienceHPI=14,
291  paAudioIO=15
293 
294 
297 typedef struct PaHostApiInfo
298 {
304  const char *name;
305 
312 
317  PaDeviceIndex defaultInputDevice;
318 
323  PaDeviceIndex defaultOutputDevice;
324 
325 } PaHostApiInfo;
326 
327 
341 const PaHostApiInfo * Pa_GetHostApiInfo( PaHostApiIndex hostApi );
342 
343 
359 PaHostApiIndex Pa_HostApiTypeIdToHostApiIndex( PaHostApiTypeId type );
360 
361 
383 PaDeviceIndex Pa_HostApiDeviceIndexToDeviceIndex( PaHostApiIndex hostApi,
384  int hostApiDeviceIndex );
385 
386 
387 
390 typedef struct PaHostErrorInfo{
392  long errorCode;
393  const char *errorText;
395 
396 
411 
412 
413 
414 /* Device enumeration and capabilities */
415 
423 PaDeviceIndex Pa_GetDeviceCount( void );
424 
425 
432 PaDeviceIndex Pa_GetDefaultInputDevice( void );
433 
434 
450 PaDeviceIndex Pa_GetDefaultOutputDevice( void );
451 
452 
461 typedef double PaTime;
462 
463 
485 typedef unsigned long PaSampleFormat;
486 
487 
488 #define paFloat32 ((PaSampleFormat) 0x00000001)
489 #define paInt32 ((PaSampleFormat) 0x00000002)
490 #define paInt24 ((PaSampleFormat) 0x00000004)
491 #define paInt16 ((PaSampleFormat) 0x00000008)
492 #define paInt8 ((PaSampleFormat) 0x00000010)
493 #define paUInt8 ((PaSampleFormat) 0x00000020)
494 #define paCustomFormat ((PaSampleFormat) 0x00010000)
496 #define paNonInterleaved ((PaSampleFormat) 0x80000000)
501 typedef struct PaDeviceInfo
502 {
503  int structVersion; /* this is struct version 2 */
504  const char *name;
505  PaHostApiIndex hostApi;
507  int maxInputChannels;
508  int maxOutputChannels;
509 
512  PaTime defaultLowOutputLatency;
515  PaTime defaultHighOutputLatency;
516 
517  double defaultSampleRate;
518 } PaDeviceInfo;
519 
520 
534 const PaDeviceInfo* Pa_GetDeviceInfo( PaDeviceIndex device );
535 
536 
539 typedef struct PaStreamParameters
540 {
547  PaDeviceIndex device;
548 
555 
560  PaSampleFormat sampleFormat;
561 
574 
581 
583 
584 
586 #define paFormatIsSupported (0)
587 
610 PaError Pa_IsFormatSupported( const PaStreamParameters *inputParameters,
611  const PaStreamParameters *outputParameters,
612  double sampleRate );
613 
614 
615 
616 /* Streaming types and functions */
617 
618 
636 typedef void PaStream;
637 
638 
643 #define paFramesPerBufferUnspecified (0)
644 
645 
654 typedef unsigned long PaStreamFlags;
655 
657 #define paNoFlag ((PaStreamFlags) 0)
658 
662 #define paClipOff ((PaStreamFlags) 0x00000001)
663 
667 #define paDitherOff ((PaStreamFlags) 0x00000002)
668 
678 #define paNeverDropInput ((PaStreamFlags) 0x00000004)
679 
686 #define paPrimeOutputBuffersUsingStreamCallback ((PaStreamFlags) 0x00000008)
687 
691 #define paPlatformSpecificFlags ((PaStreamFlags)0xFFFF0000)
692 
702  PaTime currentTime;
705 
706 
713 typedef unsigned long PaStreamCallbackFlags;
714 
722 #define paInputUnderflow ((PaStreamCallbackFlags) 0x00000001)
723 
731 #define paInputOverflow ((PaStreamCallbackFlags) 0x00000002)
732 
737 #define paOutputUnderflow ((PaStreamCallbackFlags) 0x00000004)
738 
742 #define paOutputOverflow ((PaStreamCallbackFlags) 0x00000008)
743 
748 #define paPrimingOutput ((PaStreamCallbackFlags) 0x00000010)
749 
755 {
760 
761 
831 typedef int PaStreamCallback(
832  const void *input, void *output,
833  unsigned long frameCount,
834  const PaStreamCallbackTimeInfo* timeInfo,
835  PaStreamCallbackFlags statusFlags,
836  void *userData );
837 
838 
896 PaError Pa_OpenStream( PaStream** stream,
897  const PaStreamParameters *inputParameters,
898  const PaStreamParameters *outputParameters,
899  double sampleRate,
900  unsigned long framesPerBuffer,
901  PaStreamFlags streamFlags,
902  PaStreamCallback *streamCallback,
903  void *userData );
904 
905 
936 PaError Pa_OpenDefaultStream( PaStream** stream,
937  int numInputChannels,
938  int numOutputChannels,
939  PaSampleFormat sampleFormat,
940  double sampleRate,
941  unsigned long framesPerBuffer,
942  PaStreamCallback *streamCallback,
943  void *userData );
944 
945 
949 PaError Pa_CloseStream( PaStream *stream );
950 
951 
966 typedef void PaStreamFinishedCallback( void *userData );
967 
968 
987 PaError Pa_SetStreamFinishedCallback( PaStream *stream, PaStreamFinishedCallback* streamFinishedCallback );
988 
989 
992 PaError Pa_StartStream( PaStream *stream );
993 
994 
998 PaError Pa_StopStream( PaStream *stream );
999 
1000 
1004 PaError Pa_AbortStream( PaStream *stream );
1005 
1006 
1019 PaError Pa_IsStreamStopped( PaStream *stream );
1020 
1021 
1035 PaError Pa_IsStreamActive( PaStream *stream );
1036 
1037 
1038 
1043 typedef struct PaStreamInfo
1044 {
1047 
1055 
1063 
1071  double sampleRate;
1072 
1073 } PaStreamInfo;
1074 
1075 
1089 const PaStreamInfo* Pa_GetStreamInfo( PaStream *stream );
1090 
1091 
1107 PaTime Pa_GetStreamTime( PaStream *stream );
1108 
1109 
1126 double Pa_GetStreamCpuLoad( PaStream* stream );
1127 
1128 
1154 PaError Pa_ReadStream( PaStream* stream,
1155  void *buffer,
1156  unsigned long frames );
1157 
1158 
1185 PaError Pa_WriteStream( PaStream* stream,
1186  const void *buffer,
1187  unsigned long frames );
1188 
1189 
1201 signed long Pa_GetStreamReadAvailable( PaStream* stream );
1202 
1203 
1215 signed long Pa_GetStreamWriteAvailable( PaStream* stream );
1216 
1217 
1218 /* Miscellaneous utilities */
1219 
1220 
1226 PaError Pa_GetSampleSize( PaSampleFormat format );
1227 
1228 
1236 void Pa_Sleep( long msec );
1237 
1238 
1239 
1240 #ifdef __cplusplus
1241 }
1242 #endif /* __cplusplus */
1243 #endif /* PORTAUDIO_H */
PaError Pa_Initialize(void)
struct PaDeviceInfo PaDeviceInfo
int structVersion
Definition: portaudio.h:300
PaTime defaultHighInputLatency
Definition: portaudio.h:514
int PaHostApiIndex
Definition: portaudio.h:238
PaDeviceIndex Pa_GetDefaultInputDevice(void)
PaDeviceIndex Pa_GetDeviceCount(void)
PaHostApiTypeId type
Definition: portaudio.h:302
struct PaStreamInfo PaStreamInfo
PaError Pa_StopStream(PaStream *stream)
struct PaHostErrorInfo PaHostErrorInfo
void PaStream
Definition: portaudio.h:636
const PaStreamInfo * Pa_GetStreamInfo(PaStream *stream)
PaError Pa_GetSampleSize(PaSampleFormat format)
PaError Pa_OpenStream(PaStream **stream, const PaStreamParameters *inputParameters, const PaStreamParameters *outputParameters, double sampleRate, unsigned long framesPerBuffer, PaStreamFlags streamFlags, PaStreamCallback *streamCallback, void *userData)
double sampleRate
Definition: portaudio.h:1071
PaHostApiIndex Pa_GetDefaultHostApi(void)
const char * name
Definition: portaudio.h:304
int PaStreamCallback(const void *input, void *output, unsigned long frameCount, const PaStreamCallbackTimeInfo *timeInfo, PaStreamCallbackFlags statusFlags, void *userData)
Definition: portaudio.h:831
const PaHostErrorInfo * Pa_GetLastHostErrorInfo(void)
PaError Pa_IsFormatSupported(const PaStreamParameters *inputParameters, const PaStreamParameters *outputParameters, double sampleRate)
void PaStreamFinishedCallback(void *userData)
Definition: portaudio.h:966
int PaDeviceIndex
Definition: portaudio.h:212
PaError Pa_SetStreamFinishedCallback(PaStream *stream, PaStreamFinishedCallback *streamFinishedCallback)
PaTime defaultLowInputLatency
Definition: portaudio.h:511
PaError Pa_StartStream(PaStream *stream)
void * hostApiSpecificStreamInfo
Definition: portaudio.h:580
struct PaHostApiInfo PaHostApiInfo
const char * versionControlRevision
Definition: portaudio.h:99
PaDeviceIndex defaultInputDevice
Definition: portaudio.h:317
PaDeviceIndex Pa_HostApiDeviceIndexToDeviceIndex(PaHostApiIndex hostApi, int hostApiDeviceIndex)
PaError Pa_IsStreamStopped(PaStream *stream)
PaTime inputLatency
Definition: portaudio.h:1054
PaSampleFormat sampleFormat
Definition: portaudio.h:560
const char * versionText
Definition: portaudio.h:101
const char * errorText
Definition: portaudio.h:393
unsigned long PaStreamFlags
Definition: portaudio.h:654
int PaError
Definition: portaudio.h:121
PaError Pa_IsStreamActive(PaStream *stream)
PaHostApiTypeId
Definition: portaudio.h:275
PaTime suggestedLatency
Definition: portaudio.h:573
struct PaVersionInfo PaVersionInfo
int Pa_GetVersion(void)
unsigned long PaStreamCallbackFlags
Definition: portaudio.h:713
PaTime Pa_GetStreamTime(PaStream *stream)
struct PaStreamParameters PaStreamParameters
PaError Pa_OpenDefaultStream(PaStream **stream, int numInputChannels, int numOutputChannels, PaSampleFormat sampleFormat, double sampleRate, unsigned long framesPerBuffer, PaStreamCallback *streamCallback, void *userData)
PaDeviceIndex defaultOutputDevice
Definition: portaudio.h:323
int structVersion
Definition: portaudio.h:1046
PaError Pa_AbortStream(PaStream *stream)
const PaHostApiInfo * Pa_GetHostApiInfo(PaHostApiIndex hostApi)
unsigned long PaSampleFormat
Definition: portaudio.h:485
PaHostApiIndex hostApi
Definition: portaudio.h:505
signed long Pa_GetStreamReadAvailable(PaStream *stream)
PaHostApiIndex Pa_GetHostApiCount(void)
const PaDeviceInfo * Pa_GetDeviceInfo(PaDeviceIndex device)
PaDeviceIndex Pa_GetDefaultOutputDevice(void)
PaStreamCallbackResult
Definition: portaudio.h:754
PaDeviceIndex device
Definition: portaudio.h:547
struct PaStreamCallbackTimeInfo PaStreamCallbackTimeInfo
void Pa_Sleep(long msec)
PaError Pa_ReadStream(PaStream *stream, void *buffer, unsigned long frames)
PaHostApiTypeId hostApiType
Definition: portaudio.h:391
PaTime outputLatency
Definition: portaudio.h:1062
PaError Pa_WriteStream(PaStream *stream, const void *buffer, unsigned long frames)
double PaTime
Definition: portaudio.h:461
const char * Pa_GetErrorText(PaError errorCode)
const PaVersionInfo * Pa_GetVersionInfo(void)
PaHostApiIndex Pa_HostApiTypeIdToHostApiIndex(PaHostApiTypeId type)
signed long Pa_GetStreamWriteAvailable(PaStream *stream)
PaError Pa_CloseStream(PaStream *stream)
PaError Pa_Terminate(void)
const char * Pa_GetVersionText(void)
double Pa_GetStreamCpuLoad(PaStream *stream)