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  paCanNotInitializeRecursively
156 } PaErrorCode;
157 
158 
162 const char *Pa_GetErrorText( PaError errorCode );
163 
164 
184 PaError Pa_Initialize( void );
185 
186 
203 PaError Pa_Terminate( void );
204 
205 
206 
213 typedef int PaDeviceIndex;
214 
215 
221 #define paNoDevice ((PaDeviceIndex)-1)
222 
223 
229 #define paUseHostApiSpecificDeviceSpecification ((PaDeviceIndex)-2)
230 
231 
232 /* Host API enumeration mechanism */
233 
239 typedef int PaHostApiIndex;
240 
241 
251 PaHostApiIndex Pa_GetHostApiCount( void );
252 
253 
262 PaHostApiIndex Pa_GetDefaultHostApi( void );
263 
264 
276 typedef enum PaHostApiTypeId
277 {
278  paInDevelopment=0, /* use while developing support for a new host API */
279  paDirectSound=1,
280  paMME=2,
281  paASIO=3,
282  paSoundManager=4,
283  paCoreAudio=5,
284  paOSS=7,
285  paALSA=8,
286  paAL=9,
287  paBeOS=10,
288  paWDMKS=11,
289  paJACK=12,
290  paWASAPI=13,
291  paAudioScienceHPI=14,
292  paAudioIO=15
294 
295 
298 typedef struct PaHostApiInfo
299 {
305  const char *name;
306 
313 
318  PaDeviceIndex defaultInputDevice;
319 
324  PaDeviceIndex defaultOutputDevice;
325 
326 } PaHostApiInfo;
327 
328 
342 const PaHostApiInfo * Pa_GetHostApiInfo( PaHostApiIndex hostApi );
343 
344 
360 PaHostApiIndex Pa_HostApiTypeIdToHostApiIndex( PaHostApiTypeId type );
361 
362 
384 PaDeviceIndex Pa_HostApiDeviceIndexToDeviceIndex( PaHostApiIndex hostApi,
385  int hostApiDeviceIndex );
386 
387 
388 
391 typedef struct PaHostErrorInfo{
393  long errorCode;
394  const char *errorText;
396 
397 
412 
413 
414 
415 /* Device enumeration and capabilities */
416 
424 PaDeviceIndex Pa_GetDeviceCount( void );
425 
426 
433 PaDeviceIndex Pa_GetDefaultInputDevice( void );
434 
435 
451 PaDeviceIndex Pa_GetDefaultOutputDevice( void );
452 
453 
462 typedef double PaTime;
463 
464 
486 typedef unsigned long PaSampleFormat;
487 
488 
489 #define paFloat32 ((PaSampleFormat) 0x00000001)
490 #define paInt32 ((PaSampleFormat) 0x00000002)
491 #define paInt24 ((PaSampleFormat) 0x00000004)
492 #define paInt16 ((PaSampleFormat) 0x00000008)
493 #define paInt8 ((PaSampleFormat) 0x00000010)
494 #define paUInt8 ((PaSampleFormat) 0x00000020)
495 #define paCustomFormat ((PaSampleFormat) 0x00010000)
497 #define paNonInterleaved ((PaSampleFormat) 0x80000000)
502 typedef struct PaDeviceInfo
503 {
504  int structVersion; /* this is struct version 2 */
505  const char *name;
506  PaHostApiIndex hostApi;
508  int maxInputChannels;
509  int maxOutputChannels;
510 
513  PaTime defaultLowOutputLatency;
516  PaTime defaultHighOutputLatency;
517 
518  double defaultSampleRate;
519 } PaDeviceInfo;
520 
521 
535 const PaDeviceInfo* Pa_GetDeviceInfo( PaDeviceIndex device );
536 
537 
540 typedef struct PaStreamParameters
541 {
548  PaDeviceIndex device;
549 
556 
561  PaSampleFormat sampleFormat;
562 
575 
582 
584 
585 
587 #define paFormatIsSupported (0)
588 
611 PaError Pa_IsFormatSupported( const PaStreamParameters *inputParameters,
612  const PaStreamParameters *outputParameters,
613  double sampleRate );
614 
615 
616 
617 /* Streaming types and functions */
618 
619 
637 typedef void PaStream;
638 
639 
644 #define paFramesPerBufferUnspecified (0)
645 
646 
655 typedef unsigned long PaStreamFlags;
656 
658 #define paNoFlag ((PaStreamFlags) 0)
659 
663 #define paClipOff ((PaStreamFlags) 0x00000001)
664 
668 #define paDitherOff ((PaStreamFlags) 0x00000002)
669 
679 #define paNeverDropInput ((PaStreamFlags) 0x00000004)
680 
687 #define paPrimeOutputBuffersUsingStreamCallback ((PaStreamFlags) 0x00000008)
688 
692 #define paPlatformSpecificFlags ((PaStreamFlags)0xFFFF0000)
693 
703  PaTime currentTime;
706 
707 
714 typedef unsigned long PaStreamCallbackFlags;
715 
723 #define paInputUnderflow ((PaStreamCallbackFlags) 0x00000001)
724 
732 #define paInputOverflow ((PaStreamCallbackFlags) 0x00000002)
733 
738 #define paOutputUnderflow ((PaStreamCallbackFlags) 0x00000004)
739 
743 #define paOutputOverflow ((PaStreamCallbackFlags) 0x00000008)
744 
749 #define paPrimingOutput ((PaStreamCallbackFlags) 0x00000010)
750 
756 {
761 
762 
832 typedef int PaStreamCallback(
833  const void *input, void *output,
834  unsigned long frameCount,
835  const PaStreamCallbackTimeInfo* timeInfo,
836  PaStreamCallbackFlags statusFlags,
837  void *userData );
838 
839 
897 PaError Pa_OpenStream( PaStream** stream,
898  const PaStreamParameters *inputParameters,
899  const PaStreamParameters *outputParameters,
900  double sampleRate,
901  unsigned long framesPerBuffer,
902  PaStreamFlags streamFlags,
903  PaStreamCallback *streamCallback,
904  void *userData );
905 
906 
937 PaError Pa_OpenDefaultStream( PaStream** stream,
938  int numInputChannels,
939  int numOutputChannels,
940  PaSampleFormat sampleFormat,
941  double sampleRate,
942  unsigned long framesPerBuffer,
943  PaStreamCallback *streamCallback,
944  void *userData );
945 
946 
950 PaError Pa_CloseStream( PaStream *stream );
951 
952 
967 typedef void PaStreamFinishedCallback( void *userData );
968 
969 
988 PaError Pa_SetStreamFinishedCallback( PaStream *stream, PaStreamFinishedCallback* streamFinishedCallback );
989 
990 
993 PaError Pa_StartStream( PaStream *stream );
994 
995 
999 PaError Pa_StopStream( PaStream *stream );
1000 
1001 
1005 PaError Pa_AbortStream( PaStream *stream );
1006 
1007 
1020 PaError Pa_IsStreamStopped( PaStream *stream );
1021 
1022 
1036 PaError Pa_IsStreamActive( PaStream *stream );
1037 
1038 
1039 
1044 typedef struct PaStreamInfo
1045 {
1048 
1056 
1064 
1072  double sampleRate;
1073 
1074 } PaStreamInfo;
1075 
1076 
1090 const PaStreamInfo* Pa_GetStreamInfo( PaStream *stream );
1091 
1092 
1108 PaTime Pa_GetStreamTime( PaStream *stream );
1109 
1110 
1127 double Pa_GetStreamCpuLoad( PaStream* stream );
1128 
1129 
1155 PaError Pa_ReadStream( PaStream* stream,
1156  void *buffer,
1157  unsigned long frames );
1158 
1159 
1186 PaError Pa_WriteStream( PaStream* stream,
1187  const void *buffer,
1188  unsigned long frames );
1189 
1190 
1202 signed long Pa_GetStreamReadAvailable( PaStream* stream );
1203 
1204 
1216 signed long Pa_GetStreamWriteAvailable( PaStream* stream );
1217 
1218 
1219 /* Miscellaneous utilities */
1220 
1221 
1227 PaError Pa_GetSampleSize( PaSampleFormat format );
1228 
1229 
1237 void Pa_Sleep( long msec );
1238 
1239 
1240 
1241 #ifdef __cplusplus
1242 }
1243 #endif /* __cplusplus */
1244 #endif /* PORTAUDIO_H */
PaError Pa_Initialize(void)
struct PaDeviceInfo PaDeviceInfo
int structVersion
Definition: portaudio.h:301
PaTime defaultHighInputLatency
Definition: portaudio.h:515
int PaHostApiIndex
Definition: portaudio.h:239
PaDeviceIndex Pa_GetDefaultInputDevice(void)
PaDeviceIndex Pa_GetDeviceCount(void)
PaHostApiTypeId type
Definition: portaudio.h:303
struct PaStreamInfo PaStreamInfo
PaError Pa_StopStream(PaStream *stream)
struct PaHostErrorInfo PaHostErrorInfo
void PaStream
Definition: portaudio.h:637
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:1072
PaHostApiIndex Pa_GetDefaultHostApi(void)
const char * name
Definition: portaudio.h:305
int PaStreamCallback(const void *input, void *output, unsigned long frameCount, const PaStreamCallbackTimeInfo *timeInfo, PaStreamCallbackFlags statusFlags, void *userData)
Definition: portaudio.h:832
const PaHostErrorInfo * Pa_GetLastHostErrorInfo(void)
PaError Pa_IsFormatSupported(const PaStreamParameters *inputParameters, const PaStreamParameters *outputParameters, double sampleRate)
void PaStreamFinishedCallback(void *userData)
Definition: portaudio.h:967
int PaDeviceIndex
Definition: portaudio.h:213
PaError Pa_SetStreamFinishedCallback(PaStream *stream, PaStreamFinishedCallback *streamFinishedCallback)
PaTime defaultLowInputLatency
Definition: portaudio.h:512
PaError Pa_StartStream(PaStream *stream)
void * hostApiSpecificStreamInfo
Definition: portaudio.h:581
struct PaHostApiInfo PaHostApiInfo
const char * versionControlRevision
Definition: portaudio.h:99
PaDeviceIndex defaultInputDevice
Definition: portaudio.h:318
PaDeviceIndex Pa_HostApiDeviceIndexToDeviceIndex(PaHostApiIndex hostApi, int hostApiDeviceIndex)
PaError Pa_IsStreamStopped(PaStream *stream)
PaTime inputLatency
Definition: portaudio.h:1055
PaSampleFormat sampleFormat
Definition: portaudio.h:561
const char * versionText
Definition: portaudio.h:101
const char * errorText
Definition: portaudio.h:394
unsigned long PaStreamFlags
Definition: portaudio.h:655
int PaError
Definition: portaudio.h:121
PaError Pa_IsStreamActive(PaStream *stream)
PaHostApiTypeId
Definition: portaudio.h:276
PaTime suggestedLatency
Definition: portaudio.h:574
struct PaVersionInfo PaVersionInfo
int Pa_GetVersion(void)
unsigned long PaStreamCallbackFlags
Definition: portaudio.h:714
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:324
int structVersion
Definition: portaudio.h:1047
PaError Pa_AbortStream(PaStream *stream)
const PaHostApiInfo * Pa_GetHostApiInfo(PaHostApiIndex hostApi)
unsigned long PaSampleFormat
Definition: portaudio.h:486
PaHostApiIndex hostApi
Definition: portaudio.h:506
signed long Pa_GetStreamReadAvailable(PaStream *stream)
PaHostApiIndex Pa_GetHostApiCount(void)
const PaDeviceInfo * Pa_GetDeviceInfo(PaDeviceIndex device)
PaDeviceIndex Pa_GetDefaultOutputDevice(void)
PaStreamCallbackResult
Definition: portaudio.h:755
PaDeviceIndex device
Definition: portaudio.h:548
struct PaStreamCallbackTimeInfo PaStreamCallbackTimeInfo
void Pa_Sleep(long msec)
PaError Pa_ReadStream(PaStream *stream, void *buffer, unsigned long frames)
PaHostApiTypeId hostApiType
Definition: portaudio.h:392
PaTime outputLatency
Definition: portaudio.h:1063
PaError Pa_WriteStream(PaStream *stream, const void *buffer, unsigned long frames)
double PaTime
Definition: portaudio.h:462
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)