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;
99 const char *versionControlRevision;
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} PaHostApiTypeId;
292
293
296 typedef struct PaHostApiInfo
297{
299 int structVersion;
301 PaHostApiTypeId type;
303 const char *name;
304
310 int deviceCount;
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{
390 PaHostApiTypeId hostApiType;
391 long errorCode;
392 const char *errorText;
393}PaHostErrorInfo;
394
395
409 const PaHostErrorInfo* Pa_GetLastHostErrorInfo( void );
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
510 PaTime defaultLowInputLatency;
511 PaTime defaultLowOutputLatency;
513 PaTime defaultHighInputLatency;
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
553 int channelCount;
554
559 PaSampleFormat sampleFormat;
560
572 PaTime suggestedLatency;
573
579 void *hostApiSpecificStreamInfo;
580
581} PaStreamParameters;
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
699 typedef struct PaStreamCallbackTimeInfo{
700 PaTime inputBufferAdcTime;
701 PaTime currentTime;
702 PaTime outputBufferDacTime;
703} PaStreamCallbackTimeInfo;
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
753 typedef enum PaStreamCallbackResult
754{
755 paContinue=0,
756 paComplete=1,
757 paAbort=2
758} PaStreamCallbackResult;
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{
1045 int structVersion;
1046
1053 PaTime inputLatency;
1054
1061 PaTime outputLatency;
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
1149 PaError Pa_ReadStream( PaStream* stream,
1150 void *buffer,
1151 unsigned long frames );
1152
1153
1176 PaError Pa_WriteStream( PaStream* stream,
1177 const void *buffer,
1178 unsigned long frames );
1179
1180
1189 signed long Pa_GetStreamReadAvailable( PaStream* stream );
1190
1191
1200 signed long Pa_GetStreamWriteAvailable( PaStream* stream );
1201
1202
1203/* Miscellaneous utilities */
1204
1205
1211 PaError Pa_GetSampleSize( PaSampleFormat format );
1212
1213
1221 void Pa_Sleep( long msec );
1222
1223
1224
1225#ifdef __cplusplus
1226}
1227#endif /* __cplusplus */
1228#endif /* PORTAUDIO_H */
Pa_WriteStream
PaError Pa_WriteStream(PaStream *stream, const void *buffer, unsigned long frames)
Pa_HostApiTypeIdToHostApiIndex
PaHostApiIndex Pa_HostApiTypeIdToHostApiIndex(PaHostApiTypeId type)
Pa_OpenDefaultStream
PaError Pa_OpenDefaultStream(PaStream **stream, int numInputChannels, int numOutputChannels, PaSampleFormat sampleFormat, double sampleRate, unsigned long framesPerBuffer, PaStreamCallback *streamCallback, void *userData)
Pa_ReadStream
PaError Pa_ReadStream(PaStream *stream, void *buffer, unsigned long frames)
Pa_Terminate
PaError Pa_Terminate(void)
Pa_AbortStream
PaError Pa_AbortStream(PaStream *stream)
PaStreamCallbackTimeInfo
struct PaStreamCallbackTimeInfo PaStreamCallbackTimeInfo
PaStream
void PaStream
Definition: portaudio.h:635
Pa_GetHostApiCount
PaHostApiIndex Pa_GetHostApiCount(void)
Pa_Sleep
void Pa_Sleep(long msec)
Pa_GetLastHostErrorInfo
const PaHostErrorInfo * Pa_GetLastHostErrorInfo(void)
Pa_IsStreamActive
PaError Pa_IsStreamActive(PaStream *stream)
Pa_GetStreamWriteAvailable
signed long Pa_GetStreamWriteAvailable(PaStream *stream)
Pa_GetStreamTime
PaTime Pa_GetStreamTime(PaStream *stream)
PaStreamFlags
unsigned long PaStreamFlags
Definition: portaudio.h:653
PaVersionInfo
struct PaVersionInfo PaVersionInfo
Pa_OpenStream
PaError Pa_OpenStream(PaStream **stream, const PaStreamParameters *inputParameters, const PaStreamParameters *outputParameters, double sampleRate, unsigned long framesPerBuffer, PaStreamFlags streamFlags, PaStreamCallback *streamCallback, void *userData)
PaSampleFormat
unsigned long PaSampleFormat
Definition: portaudio.h:484
PaError
int PaError
Definition: portaudio.h:121
Pa_IsStreamStopped
PaError Pa_IsStreamStopped(PaStream *stream)
Pa_GetSampleSize
PaError Pa_GetSampleSize(PaSampleFormat format)
Pa_HostApiDeviceIndexToDeviceIndex
PaDeviceIndex Pa_HostApiDeviceIndexToDeviceIndex(PaHostApiIndex hostApi, int hostApiDeviceIndex)
PaStreamCallbackFlags
unsigned long PaStreamCallbackFlags
Definition: portaudio.h:712
Pa_GetVersionText
const char * Pa_GetVersionText(void)
PaStreamInfo
struct PaStreamInfo PaStreamInfo
Pa_GetVersion
int Pa_GetVersion(void)
PaDeviceInfo
struct PaDeviceInfo PaDeviceInfo
Pa_StartStream
PaError Pa_StartStream(PaStream *stream)
Pa_GetStreamCpuLoad
double Pa_GetStreamCpuLoad(PaStream *stream)
PaStreamCallback
int PaStreamCallback(const void *input, void *output, unsigned long frameCount, const PaStreamCallbackTimeInfo *timeInfo, PaStreamCallbackFlags statusFlags, void *userData)
Definition: portaudio.h:830
PaHostApiTypeId
PaHostApiTypeId
Definition: portaudio.h:276
Pa_CloseStream
PaError Pa_CloseStream(PaStream *stream)
Pa_GetVersionInfo
const PaVersionInfo * Pa_GetVersionInfo(void)
PaStreamParameters
struct PaStreamParameters PaStreamParameters
Pa_SetStreamFinishedCallback
PaError Pa_SetStreamFinishedCallback(PaStream *stream, PaStreamFinishedCallback *streamFinishedCallback)
PaHostErrorInfo
struct PaHostErrorInfo PaHostErrorInfo
PaStreamFinishedCallback
void PaStreamFinishedCallback(void *userData)
Definition: portaudio.h:965
Pa_GetDeviceInfo
const PaDeviceInfo * Pa_GetDeviceInfo(PaDeviceIndex device)
Pa_GetStreamInfo
const PaStreamInfo * Pa_GetStreamInfo(PaStream *stream)
Pa_IsFormatSupported
PaError Pa_IsFormatSupported(const PaStreamParameters *inputParameters, const PaStreamParameters *outputParameters, double sampleRate)
Pa_Initialize
PaError Pa_Initialize(void)
Pa_GetDefaultInputDevice
PaDeviceIndex Pa_GetDefaultInputDevice(void)
Pa_GetDeviceCount
PaDeviceIndex Pa_GetDeviceCount(void)
Pa_GetStreamReadAvailable
signed long Pa_GetStreamReadAvailable(PaStream *stream)
PaDeviceIndex
int PaDeviceIndex
Definition: portaudio.h:212
Pa_GetDefaultOutputDevice
PaDeviceIndex Pa_GetDefaultOutputDevice(void)
PaHostApiInfo
struct PaHostApiInfo PaHostApiInfo
Pa_GetDefaultHostApi
PaHostApiIndex Pa_GetDefaultHostApi(void)
Pa_GetErrorText
const char * Pa_GetErrorText(PaError errorCode)
PaStreamCallbackResult
PaStreamCallbackResult
Definition: portaudio.h:754
paComplete
@ paComplete
Definition: portaudio.h:756
paAbort
@ paAbort
Definition: portaudio.h:757
paContinue
@ paContinue
Definition: portaudio.h:755
PaHostApiIndex
int PaHostApiIndex
Definition: portaudio.h:238
PaTime
double PaTime
Definition: portaudio.h:460
Pa_StopStream
PaError Pa_StopStream(PaStream *stream)
Pa_GetHostApiInfo
const PaHostApiInfo * Pa_GetHostApiInfo(PaHostApiIndex hostApi)
PaDeviceInfo
Definition: portaudio.h:501
PaDeviceInfo::defaultHighInputLatency
PaTime defaultHighInputLatency
Definition: portaudio.h:513
PaDeviceInfo::defaultLowInputLatency
PaTime defaultLowInputLatency
Definition: portaudio.h:510
PaDeviceInfo::hostApi
PaHostApiIndex hostApi
Definition: portaudio.h:504
PaHostApiInfo
Definition: portaudio.h:297
PaHostApiInfo::structVersion
int structVersion
Definition: portaudio.h:299
PaHostApiInfo::deviceCount
int deviceCount
Definition: portaudio.h:310
PaHostApiInfo::type
PaHostApiTypeId type
Definition: portaudio.h:301
PaHostApiInfo::defaultOutputDevice
PaDeviceIndex defaultOutputDevice
Definition: portaudio.h:322
PaHostApiInfo::name
const char * name
Definition: portaudio.h:303
PaHostApiInfo::defaultInputDevice
PaDeviceIndex defaultInputDevice
Definition: portaudio.h:316
PaHostErrorInfo
Definition: portaudio.h:389
PaHostErrorInfo::errorCode
long errorCode
Definition: portaudio.h:391
PaHostErrorInfo::errorText
const char * errorText
Definition: portaudio.h:392
PaHostErrorInfo::hostApiType
PaHostApiTypeId hostApiType
Definition: portaudio.h:390
PaStreamCallbackTimeInfo
Definition: portaudio.h:699
PaStreamCallbackTimeInfo::outputBufferDacTime
PaTime outputBufferDacTime
Definition: portaudio.h:702
PaStreamCallbackTimeInfo::inputBufferAdcTime
PaTime inputBufferAdcTime
Definition: portaudio.h:700
PaStreamCallbackTimeInfo::currentTime
PaTime currentTime
Definition: portaudio.h:701
PaStreamInfo
Definition: portaudio.h:1043
PaStreamInfo::inputLatency
PaTime inputLatency
Definition: portaudio.h:1053
PaStreamInfo::outputLatency
PaTime outputLatency
Definition: portaudio.h:1061
PaStreamInfo::structVersion
int structVersion
Definition: portaudio.h:1045
PaStreamInfo::sampleRate
double sampleRate
Definition: portaudio.h:1070
PaStreamParameters
Definition: portaudio.h:539
PaStreamParameters::channelCount
int channelCount
Definition: portaudio.h:553
PaStreamParameters::suggestedLatency
PaTime suggestedLatency
Definition: portaudio.h:572
PaStreamParameters::sampleFormat
PaSampleFormat sampleFormat
Definition: portaudio.h:559
PaStreamParameters::device
PaDeviceIndex device
Definition: portaudio.h:546
PaStreamParameters::hostApiSpecificStreamInfo
void * hostApiSpecificStreamInfo
Definition: portaudio.h:579
PaVersionInfo
Definition: portaudio.h:90
PaVersionInfo::versionControlRevision
const char * versionControlRevision
Definition: portaudio.h:99
PaVersionInfo::versionText
const char * versionText
Definition: portaudio.h:101