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;
103 
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 
184 
185 
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 
251 
252 
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,
292  paPulseAudio=16
294 
295 
298 typedef struct PaHostApiInfo
299 {
305  const char *name;
306 
313 
319 
325 
327 
328 
343 
344 
361 
362 
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 
425 
426 
434 
435 
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;
508  int maxInputChannels;
509  int maxOutputChannels;
510 
513  PaTime defaultLowOutputLatency;
516  PaTime defaultHighOutputLatency;
517 
518  double defaultSampleRate;
520 
521 
536 
537 
540 typedef struct PaStreamParameters
541 {
549 
556 
562 
575 
582 
584 
585 
587 #define paFormatIsSupported (0)
588 
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 
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 {
759  paAbort=2
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 
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 
938  int numInputChannels,
939  int numOutputChannels,
940  PaSampleFormat sampleFormat,
941  double sampleRate,
942  unsigned long framesPerBuffer,
943  PaStreamCallback *streamCallback,
944  void *userData );
945 
946 
951 
952 
967 typedef void PaStreamFinishedCallback( void *userData );
968 
969 
989 
990 
994 
995 
1000 
1001 
1006 
1007 
1021 
1022 
1037 
1038 
1039 
1044 typedef struct PaStreamInfo
1045 {
1048 
1056 
1064 
1072  double sampleRate;
1073 
1075 
1076 
1091 
1092 
1109 
1110 
1127 double Pa_GetStreamCpuLoad( PaStream* stream );
1128 
1129 
1156  void *buffer,
1157  unsigned long frames );
1158 
1159 
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 
1226 
1227 
1228 /* Miscellaneous utilities */
1229 
1230 
1237 
1238 
1246 void Pa_Sleep( long msec );
1247 
1248 
1249 
1250 #ifdef __cplusplus
1251 }
1252 #endif /* __cplusplus */
1253 #endif /* PORTAUDIO_H */
PaError Pa_WriteStream(PaStream *stream, const void *buffer, unsigned long frames)
PaHostApiIndex Pa_HostApiTypeIdToHostApiIndex(PaHostApiTypeId type)
PaError Pa_OpenDefaultStream(PaStream **stream, int numInputChannels, int numOutputChannels, PaSampleFormat sampleFormat, double sampleRate, unsigned long framesPerBuffer, PaStreamCallback *streamCallback, void *userData)
PaError Pa_ReadStream(PaStream *stream, void *buffer, unsigned long frames)
PaError Pa_Terminate(void)
PaError Pa_AbortStream(PaStream *stream)
struct PaStreamCallbackTimeInfo PaStreamCallbackTimeInfo
void PaStream
Definition: portaudio.h:637
PaHostApiIndex Pa_GetHostApiCount(void)
void Pa_Sleep(long msec)
PaError Pa_IsStreamActive(PaStream *stream)
signed long Pa_GetStreamWriteAvailable(PaStream *stream)
const char * Pa_GetVersionText(void)
PaHostApiTypeId Pa_GetStreamHostApiType(PaStream *stream)
PaTime Pa_GetStreamTime(PaStream *stream)
unsigned long PaStreamFlags
Definition: portaudio.h:655
struct PaVersionInfo PaVersionInfo
const PaStreamInfo * Pa_GetStreamInfo(PaStream *stream)
PaError Pa_OpenStream(PaStream **stream, const PaStreamParameters *inputParameters, const PaStreamParameters *outputParameters, double sampleRate, unsigned long framesPerBuffer, PaStreamFlags streamFlags, PaStreamCallback *streamCallback, void *userData)
unsigned long PaSampleFormat
Definition: portaudio.h:486
int PaError
Definition: portaudio.h:121
PaError Pa_IsStreamStopped(PaStream *stream)
PaError Pa_GetSampleSize(PaSampleFormat format)
PaDeviceIndex Pa_HostApiDeviceIndexToDeviceIndex(PaHostApiIndex hostApi, int hostApiDeviceIndex)
unsigned long PaStreamCallbackFlags
Definition: portaudio.h:714
struct PaStreamInfo PaStreamInfo
int Pa_GetVersion(void)
struct PaDeviceInfo PaDeviceInfo
PaError Pa_StartStream(PaStream *stream)
const PaVersionInfo * Pa_GetVersionInfo(void)
const PaHostApiInfo * Pa_GetHostApiInfo(PaHostApiIndex hostApi)
double Pa_GetStreamCpuLoad(PaStream *stream)
int PaStreamCallback(const void *input, void *output, unsigned long frameCount, const PaStreamCallbackTimeInfo *timeInfo, PaStreamCallbackFlags statusFlags, void *userData)
Definition: portaudio.h:832
PaHostApiTypeId
Definition: portaudio.h:276
PaError Pa_CloseStream(PaStream *stream)
struct PaStreamParameters PaStreamParameters
PaError Pa_SetStreamFinishedCallback(PaStream *stream, PaStreamFinishedCallback *streamFinishedCallback)
const PaHostErrorInfo * Pa_GetLastHostErrorInfo(void)
struct PaHostErrorInfo PaHostErrorInfo
void PaStreamFinishedCallback(void *userData)
Definition: portaudio.h:967
PaError Pa_IsFormatSupported(const PaStreamParameters *inputParameters, const PaStreamParameters *outputParameters, double sampleRate)
PaError Pa_Initialize(void)
PaDeviceIndex Pa_GetDefaultInputDevice(void)
const PaDeviceInfo * Pa_GetDeviceInfo(PaDeviceIndex device)
PaDeviceIndex Pa_GetDeviceCount(void)
signed long Pa_GetStreamReadAvailable(PaStream *stream)
int PaDeviceIndex
Definition: portaudio.h:212
PaDeviceIndex Pa_GetDefaultOutputDevice(void)
struct PaHostApiInfo PaHostApiInfo
PaHostApiIndex Pa_GetDefaultHostApi(void)
const char * Pa_GetErrorText(PaError errorCode)
PaStreamCallbackResult
Definition: portaudio.h:756
@ paComplete
Definition: portaudio.h:758
@ paAbort
Definition: portaudio.h:759
@ paContinue
Definition: portaudio.h:757
int PaHostApiIndex
Definition: portaudio.h:238
double PaTime
Definition: portaudio.h:462
PaError Pa_StopStream(PaStream *stream)
PaTime defaultHighInputLatency
Definition: portaudio.h:515
PaTime defaultLowInputLatency
Definition: portaudio.h:512
PaHostApiIndex hostApi
Definition: portaudio.h:506
int structVersion
Definition: portaudio.h:301
PaHostApiTypeId type
Definition: portaudio.h:303
PaDeviceIndex defaultOutputDevice
Definition: portaudio.h:324
const char * name
Definition: portaudio.h:305
PaDeviceIndex defaultInputDevice
Definition: portaudio.h:318
const char * errorText
Definition: portaudio.h:394
PaHostApiTypeId hostApiType
Definition: portaudio.h:392
PaTime inputLatency
Definition: portaudio.h:1055
PaTime outputLatency
Definition: portaudio.h:1063
int structVersion
Definition: portaudio.h:1047
double sampleRate
Definition: portaudio.h:1072
PaTime suggestedLatency
Definition: portaudio.h:574
PaSampleFormat sampleFormat
Definition: portaudio.h:561
PaDeviceIndex device
Definition: portaudio.h:548
void * hostApiSpecificStreamInfo
Definition: portaudio.h:581
const char * versionControlRevision
Definition: portaudio.h:99
const char * versionText
Definition: portaudio.h:101