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
292 
293 
296 typedef struct PaHostApiInfo
297 {
303  const char *name;
304 
311 
316  PaDeviceIndex defaultInputDevice;
317 
322  PaDeviceIndex defaultOutputDevice;
323 
324 } PaHostApiInfo;
325 
326 
340 const PaHostApiInfo * Pa_GetHostApiInfo( PaHostApiIndex hostApi );
341 
342 
358 PaHostApiIndex Pa_HostApiTypeIdToHostApiIndex( PaHostApiTypeId type );
359 
360 
382 PaDeviceIndex Pa_HostApiDeviceIndexToDeviceIndex( PaHostApiIndex hostApi,
383  int hostApiDeviceIndex );
384 
385 
386 
389 typedef struct PaHostErrorInfo{
391  long errorCode;
392  const char *errorText;
394 
395 
410 
411 
412 
413 /* Device enumeration and capabilities */
414 
422 PaDeviceIndex Pa_GetDeviceCount( void );
423 
424 
431 PaDeviceIndex Pa_GetDefaultInputDevice( void );
432 
433 
449 PaDeviceIndex Pa_GetDefaultOutputDevice( void );
450 
451 
460 typedef double PaTime;
461 
462 
484 typedef unsigned long PaSampleFormat;
485 
486 
487 #define paFloat32 ((PaSampleFormat) 0x00000001)
488 #define paInt32 ((PaSampleFormat) 0x00000002)
489 #define paInt24 ((PaSampleFormat) 0x00000004)
490 #define paInt16 ((PaSampleFormat) 0x00000008)
491 #define paInt8 ((PaSampleFormat) 0x00000010)
492 #define paUInt8 ((PaSampleFormat) 0x00000020)
493 #define paCustomFormat ((PaSampleFormat) 0x00010000)
495 #define paNonInterleaved ((PaSampleFormat) 0x80000000)
500 typedef struct PaDeviceInfo
501 {
502  int structVersion; /* this is struct version 2 */
503  const char *name;
504  PaHostApiIndex hostApi;
506  int maxInputChannels;
507  int maxOutputChannels;
508 
511  PaTime defaultLowOutputLatency;
514  PaTime defaultHighOutputLatency;
515 
516  double defaultSampleRate;
517 } PaDeviceInfo;
518 
519 
533 const PaDeviceInfo* Pa_GetDeviceInfo( PaDeviceIndex device );
534 
535 
538 typedef struct PaStreamParameters
539 {
546  PaDeviceIndex device;
547 
554 
559  PaSampleFormat sampleFormat;
560 
573 
580 
582 
583 
585 #define paFormatIsSupported (0)
586 
609 PaError Pa_IsFormatSupported( const PaStreamParameters *inputParameters,
610  const PaStreamParameters *outputParameters,
611  double sampleRate );
612 
613 
614 
615 /* Streaming types and functions */
616 
617 
635 typedef void PaStream;
636 
637 
642 #define paFramesPerBufferUnspecified (0)
643 
644 
653 typedef unsigned long PaStreamFlags;
654 
656 #define paNoFlag ((PaStreamFlags) 0)
657 
661 #define paClipOff ((PaStreamFlags) 0x00000001)
662 
666 #define paDitherOff ((PaStreamFlags) 0x00000002)
667 
677 #define paNeverDropInput ((PaStreamFlags) 0x00000004)
678 
685 #define paPrimeOutputBuffersUsingStreamCallback ((PaStreamFlags) 0x00000008)
686 
690 #define paPlatformSpecificFlags ((PaStreamFlags)0xFFFF0000)
691 
701  PaTime currentTime;
704 
705 
712 typedef unsigned long PaStreamCallbackFlags;
713 
721 #define paInputUnderflow ((PaStreamCallbackFlags) 0x00000001)
722 
730 #define paInputOverflow ((PaStreamCallbackFlags) 0x00000002)
731 
736 #define paOutputUnderflow ((PaStreamCallbackFlags) 0x00000004)
737 
741 #define paOutputOverflow ((PaStreamCallbackFlags) 0x00000008)
742 
747 #define paPrimingOutput ((PaStreamCallbackFlags) 0x00000010)
748 
754 {
759 
760 
830 typedef int PaStreamCallback(
831  const void *input, void *output,
832  unsigned long frameCount,
833  const PaStreamCallbackTimeInfo* timeInfo,
834  PaStreamCallbackFlags statusFlags,
835  void *userData );
836 
837 
895 PaError Pa_OpenStream( PaStream** stream,
896  const PaStreamParameters *inputParameters,
897  const PaStreamParameters *outputParameters,
898  double sampleRate,
899  unsigned long framesPerBuffer,
900  PaStreamFlags streamFlags,
901  PaStreamCallback *streamCallback,
902  void *userData );
903 
904 
935 PaError Pa_OpenDefaultStream( PaStream** stream,
936  int numInputChannels,
937  int numOutputChannels,
938  PaSampleFormat sampleFormat,
939  double sampleRate,
940  unsigned long framesPerBuffer,
941  PaStreamCallback *streamCallback,
942  void *userData );
943 
944 
948 PaError Pa_CloseStream( PaStream *stream );
949 
950 
965 typedef void PaStreamFinishedCallback( void *userData );
966 
967 
986 PaError Pa_SetStreamFinishedCallback( PaStream *stream, PaStreamFinishedCallback* streamFinishedCallback );
987 
988 
991 PaError Pa_StartStream( PaStream *stream );
992 
993 
997 PaError Pa_StopStream( PaStream *stream );
998 
999 
1003 PaError Pa_AbortStream( PaStream *stream );
1004 
1005 
1018 PaError Pa_IsStreamStopped( PaStream *stream );
1019 
1020 
1034 PaError Pa_IsStreamActive( PaStream *stream );
1035 
1036 
1037 
1042 typedef struct PaStreamInfo
1043 {
1046 
1054 
1062 
1070  double sampleRate;
1071 
1072 } PaStreamInfo;
1073 
1074 
1088 const PaStreamInfo* Pa_GetStreamInfo( PaStream *stream );
1089 
1090 
1106 PaTime Pa_GetStreamTime( PaStream *stream );
1107 
1108 
1125 double Pa_GetStreamCpuLoad( PaStream* stream );
1126 
1127 
1153 PaError Pa_ReadStream( PaStream* stream,
1154  void *buffer,
1155  unsigned long frames );
1156 
1157 
1184 PaError Pa_WriteStream( PaStream* stream,
1185  const void *buffer,
1186  unsigned long frames );
1187 
1188 
1200 signed long Pa_GetStreamReadAvailable( PaStream* stream );
1201 
1202 
1214 signed long Pa_GetStreamWriteAvailable( PaStream* stream );
1215 
1216 
1217 /* Miscellaneous utilities */
1218 
1219 
1225 PaError Pa_GetSampleSize( PaSampleFormat format );
1226 
1227 
1235 void Pa_Sleep( long msec );
1236 
1237 
1238 
1239 #ifdef __cplusplus
1240 }
1241 #endif /* __cplusplus */
1242 #endif /* PORTAUDIO_H */
PaError Pa_Initialize(void)
struct PaDeviceInfo PaDeviceInfo
int structVersion
Definition: portaudio.h:299
PaTime defaultHighInputLatency
Definition: portaudio.h:513
int PaHostApiIndex
Definition: portaudio.h:238
PaDeviceIndex Pa_GetDefaultInputDevice(void)
PaDeviceIndex Pa_GetDeviceCount(void)
PaHostApiTypeId type
Definition: portaudio.h:301
struct PaStreamInfo PaStreamInfo
PaError Pa_StopStream(PaStream *stream)
struct PaHostErrorInfo PaHostErrorInfo
void PaStream
Definition: portaudio.h:635
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:1070
PaHostApiIndex Pa_GetDefaultHostApi(void)
const char * name
Definition: portaudio.h:303
int PaStreamCallback(const void *input, void *output, unsigned long frameCount, const PaStreamCallbackTimeInfo *timeInfo, PaStreamCallbackFlags statusFlags, void *userData)
Definition: portaudio.h:830
const PaHostErrorInfo * Pa_GetLastHostErrorInfo(void)
PaError Pa_IsFormatSupported(const PaStreamParameters *inputParameters, const PaStreamParameters *outputParameters, double sampleRate)
void PaStreamFinishedCallback(void *userData)
Definition: portaudio.h:965
int PaDeviceIndex
Definition: portaudio.h:212
PaError Pa_SetStreamFinishedCallback(PaStream *stream, PaStreamFinishedCallback *streamFinishedCallback)
PaTime defaultLowInputLatency
Definition: portaudio.h:510
PaError Pa_StartStream(PaStream *stream)
void * hostApiSpecificStreamInfo
Definition: portaudio.h:579
struct PaHostApiInfo PaHostApiInfo
const char * versionControlRevision
Definition: portaudio.h:99
PaDeviceIndex defaultInputDevice
Definition: portaudio.h:316
PaDeviceIndex Pa_HostApiDeviceIndexToDeviceIndex(PaHostApiIndex hostApi, int hostApiDeviceIndex)
PaError Pa_IsStreamStopped(PaStream *stream)
PaTime inputLatency
Definition: portaudio.h:1053
PaSampleFormat sampleFormat
Definition: portaudio.h:559
const char * versionText
Definition: portaudio.h:101
const char * errorText
Definition: portaudio.h:392
unsigned long PaStreamFlags
Definition: portaudio.h:653
int PaError
Definition: portaudio.h:121
PaError Pa_IsStreamActive(PaStream *stream)
PaHostApiTypeId
Definition: portaudio.h:275
PaTime suggestedLatency
Definition: portaudio.h:572
struct PaVersionInfo PaVersionInfo
int Pa_GetVersion(void)
unsigned long PaStreamCallbackFlags
Definition: portaudio.h:712
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:322
int structVersion
Definition: portaudio.h:1045
PaError Pa_AbortStream(PaStream *stream)
const PaHostApiInfo * Pa_GetHostApiInfo(PaHostApiIndex hostApi)
unsigned long PaSampleFormat
Definition: portaudio.h:484
PaHostApiIndex hostApi
Definition: portaudio.h:504
signed long Pa_GetStreamReadAvailable(PaStream *stream)
PaHostApiIndex Pa_GetHostApiCount(void)
const PaDeviceInfo * Pa_GetDeviceInfo(PaDeviceIndex device)
PaDeviceIndex Pa_GetDefaultOutputDevice(void)
PaStreamCallbackResult
Definition: portaudio.h:753
PaDeviceIndex device
Definition: portaudio.h:546
struct PaStreamCallbackTimeInfo PaStreamCallbackTimeInfo
void Pa_Sleep(long msec)
PaError Pa_ReadStream(PaStream *stream, void *buffer, unsigned long frames)
PaHostApiTypeId hostApiType
Definition: portaudio.h:390
PaTime outputLatency
Definition: portaudio.h:1061
PaError Pa_WriteStream(PaStream *stream, const void *buffer, unsigned long frames)
double PaTime
Definition: portaudio.h:460
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)