PortAudio: portaudio.h Source File

PortAudio 2.0

- Main Page
- Related Pages
- Modules
- Data Structures
- Files

- File List
- Globals

portaudio.h
Go to the documentation of this file.
1 #ifndef PORTAUDIO_H
2 #define PORTAUDIO_H
3 /*
4 * $Id: portaudio.h 1859 2012-09-01 00:10:13Z philburk $
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
53
57 int Pa_GetVersion( void );
58
59
63 const char* Pa_GetVersionText( void );
64
65
70 typedef int PaError;
71 typedef enum PaErrorCode
72 {
73 paNoError = 0,
74
75 paNotInitialized = -10000,
76 paUnanticipatedHostError,
77 paInvalidChannelCount,
78 paInvalidSampleRate,
79 paInvalidDevice,
80 paInvalidFlag,
81 paSampleFormatNotSupported,
82 paBadIODeviceCombination,
83 paInsufficientMemory,
84 paBufferTooBig,
85 paBufferTooSmall,
86 paNullCallback,
87 paBadStreamPtr,
88 paTimedOut,
89 paInternalError,
90 paDeviceUnavailable,
91 paIncompatibleHostApiSpecificStreamInfo,
92 paStreamIsStopped,
93 paStreamIsNotStopped,
94 paInputOverflowed,
95 paOutputUnderflowed,
96 paHostApiNotFound,
97 paInvalidHostApi,
98 paCanNotReadFromACallbackStream,
99 paCanNotWriteToACallbackStream,
100 paCanNotReadFromAnOutputOnlyStream,
101 paCanNotWriteToAnInputOnlyStream,
102 paIncompatibleStreamHostApi,
103 paBadBufferPtr
104 } PaErrorCode;
105
106
110 const char *Pa_GetErrorText( PaError errorCode );
111
112
132 PaError Pa_Initialize( void );
133
134
151 PaError Pa_Terminate( void );
152
153
154
161 typedef int PaDeviceIndex;
162
163
169 #define paNoDevice ((PaDeviceIndex)-1)
170
171
177 #define paUseHostApiSpecificDeviceSpecification ((PaDeviceIndex)-2)
178
179
180 /* Host API enumeration mechanism */
181
187 typedef int PaHostApiIndex;
188
189
199 PaHostApiIndex Pa_GetHostApiCount( void );
200
201
210 PaHostApiIndex Pa_GetDefaultHostApi( void );
211
212
224 typedef enum PaHostApiTypeId
225 {
226 paInDevelopment=0, /* use while developing support for a new host API */
227 paDirectSound=1,
228 paMME=2,
229 paASIO=3,
230 paSoundManager=4,
231 paCoreAudio=5,
232 paOSS=7,
233 paALSA=8,
234 paAL=9,
235 paBeOS=10,
236 paWDMKS=11,
237 paJACK=12,
238 paWASAPI=13,
239 paAudioScienceHPI=14
240 } PaHostApiTypeId;
241
242
245 typedef struct PaHostApiInfo
246 {
248 int structVersion;
250 PaHostApiTypeId type;
252 const char *name;
253
259 int deviceCount;
260
265 PaDeviceIndex defaultInputDevice;
266
271 PaDeviceIndex defaultOutputDevice;
272
273 } PaHostApiInfo;
274
275
289 const PaHostApiInfo * Pa_GetHostApiInfo( PaHostApiIndex hostApi );
290
291
307 PaHostApiIndex Pa_HostApiTypeIdToHostApiIndex( PaHostApiTypeId type );
308
309
331 PaDeviceIndex Pa_HostApiDeviceIndexToDeviceIndex( PaHostApiIndex hostApi,
332 int hostApiDeviceIndex );
333
334
335
338 typedef struct PaHostErrorInfo{
339 PaHostApiTypeId hostApiType;
340 long errorCode;
341 const char *errorText;
342 }PaHostErrorInfo;
343
344
358 const PaHostErrorInfo* Pa_GetLastHostErrorInfo( void );
359
360
361
362 /* Device enumeration and capabilities */
363
371 PaDeviceIndex Pa_GetDeviceCount( void );
372
373
380 PaDeviceIndex Pa_GetDefaultInputDevice( void );
381
382
398 PaDeviceIndex Pa_GetDefaultOutputDevice( void );
399
400
409 typedef double PaTime;
410
411
433 typedef unsigned long PaSampleFormat;
434
435
436 #define paFloat32 ((PaSampleFormat) 0x00000001)
437 #define paInt32 ((PaSampleFormat) 0x00000002)
438 #define paInt24 ((PaSampleFormat) 0x00000004)
439 #define paInt16 ((PaSampleFormat) 0x00000008)
440 #define paInt8 ((PaSampleFormat) 0x00000010)
441 #define paUInt8 ((PaSampleFormat) 0x00000020)
442 #define paCustomFormat ((PaSampleFormat) 0x00010000)
444 #define paNonInterleaved ((PaSampleFormat) 0x80000000)
449 typedef struct PaDeviceInfo
450 {
451 int structVersion; /* this is struct version 2 */
452 const char *name;
453 PaHostApiIndex hostApi;
455 int maxInputChannels;
456 int maxOutputChannels;
457
459 PaTime defaultLowInputLatency;
460 PaTime defaultLowOutputLatency;
462 PaTime defaultHighInputLatency;
463 PaTime defaultHighOutputLatency;
464
465 double defaultSampleRate;
466 } PaDeviceInfo;
467
468
482 const PaDeviceInfo* Pa_GetDeviceInfo( PaDeviceIndex device );
483
484
487 typedef struct PaStreamParameters
488 {
495 PaDeviceIndex device;
496
502 int channelCount;
503
508 PaSampleFormat sampleFormat;
509
521 PaTime suggestedLatency;
522
528 void *hostApiSpecificStreamInfo;
529
530 } PaStreamParameters;
531
532
534 #define paFormatIsSupported (0)
535
558 PaError Pa_IsFormatSupported( const PaStreamParameters *inputParameters,
559 const PaStreamParameters *outputParameters,
560 double sampleRate );
561
562
563
564 /* Streaming types and functions */
565
566
584 typedef void PaStream;
585
586
591 #define paFramesPerBufferUnspecified (0)
592
593
602 typedef unsigned long PaStreamFlags;
603
605 #define paNoFlag ((PaStreamFlags) 0)
606
610 #define paClipOff ((PaStreamFlags) 0x00000001)
611
615 #define paDitherOff ((PaStreamFlags) 0x00000002)
616
626 #define paNeverDropInput ((PaStreamFlags) 0x00000004)
627
634 #define paPrimeOutputBuffersUsingStreamCallback ((PaStreamFlags) 0x00000008)
635
639 #define paPlatformSpecificFlags ((PaStreamFlags)0xFFFF0000)
640
648 typedef struct PaStreamCallbackTimeInfo{
649 PaTime inputBufferAdcTime;
650 PaTime currentTime;
651 PaTime outputBufferDacTime;
652 } PaStreamCallbackTimeInfo;
653
654
661 typedef unsigned long PaStreamCallbackFlags;
662
670 #define paInputUnderflow ((PaStreamCallbackFlags) 0x00000001)
671
679 #define paInputOverflow ((PaStreamCallbackFlags) 0x00000002)
680
685 #define paOutputUnderflow ((PaStreamCallbackFlags) 0x00000004)
686
690 #define paOutputOverflow ((PaStreamCallbackFlags) 0x00000008)
691
696 #define paPrimingOutput ((PaStreamCallbackFlags) 0x00000010)
697
702 typedef enum PaStreamCallbackResult
703 {
704 paContinue=0,
705 paComplete=1,
706 paAbort=2
707 } PaStreamCallbackResult;
708
709
779 typedef int PaStreamCallback(
780 const void *input, void *output,
781 unsigned long frameCount,
782 const PaStreamCallbackTimeInfo* timeInfo,
783 PaStreamCallbackFlags statusFlags,
784 void *userData );
785
786
841 PaError Pa_OpenStream( PaStream** stream,
842 const PaStreamParameters *inputParameters,
843 const PaStreamParameters *outputParameters,
844 double sampleRate,
845 unsigned long framesPerBuffer,
846 PaStreamFlags streamFlags,
847 PaStreamCallback *streamCallback,
848 void *userData );
849
850
881 PaError Pa_OpenDefaultStream( PaStream** stream,
882 int numInputChannels,
883 int numOutputChannels,
884 PaSampleFormat sampleFormat,
885 double sampleRate,
886 unsigned long framesPerBuffer,
887 PaStreamCallback *streamCallback,
888 void *userData );
889
890
894 PaError Pa_CloseStream( PaStream *stream );
895
896
911 typedef void PaStreamFinishedCallback( void *userData );
912
913
932 PaError Pa_SetStreamFinishedCallback( PaStream *stream, PaStreamFinishedCallback* streamFinishedCallback );
933
934
937 PaError Pa_StartStream( PaStream *stream );
938
939
943 PaError Pa_StopStream( PaStream *stream );
944
945
949 PaError Pa_AbortStream( PaStream *stream );
950
951
964 PaError Pa_IsStreamStopped( PaStream *stream );
965
966
980 PaError Pa_IsStreamActive( PaStream *stream );
981
982
983
988 typedef struct PaStreamInfo
989 {
991 int structVersion;
992
999 PaTime inputLatency;
1000
1007 PaTime outputLatency;
1008
1016 double sampleRate;
1017
1018 } PaStreamInfo;
1019
1020
1034 const PaStreamInfo* Pa_GetStreamInfo( PaStream *stream );
1035
1036
1052 PaTime Pa_GetStreamTime( PaStream *stream );
1053
1054
1071 double Pa_GetStreamCpuLoad( PaStream* stream );
1072
1073
1095 PaError Pa_ReadStream( PaStream* stream,
1096 void *buffer,
1097 unsigned long frames );
1098
1099
1122 PaError Pa_WriteStream( PaStream* stream,
1123 const void *buffer,
1124 unsigned long frames );
1125
1126
1135 signed long Pa_GetStreamReadAvailable( PaStream* stream );
1136
1137
1146 signed long Pa_GetStreamWriteAvailable( PaStream* stream );
1147
1148
1149 /* Miscellaneous utilities */
1150
1151
1157 PaError Pa_GetSampleSize( PaSampleFormat format );
1158
1159
1167 void Pa_Sleep( long msec );
1168
1169
1170
1171 #ifdef __cplusplus
1172 }
1173 #endif /* __cplusplus */
1174 #endif /* PORTAUDIO_H */