PortAudio  2.0
portaudio.h
Go to the documentation of this file.
1 #ifndef PORTAUDIO_H
2 #define PORTAUDIO_H
3 /*
4  * $Id: portaudio.h 1745 2011-08-25 17:44:01Z rossb $
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
241 
242 
245 typedef struct PaHostApiInfo
246 {
252  const char *name;
253 
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{
340  long errorCode;
341  const char *errorText;
343 
344 
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 
460  PaTime defaultLowOutputLatency;
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 
503 
508  PaSampleFormat sampleFormat;
509 
522 
529 
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 
650  PaTime currentTime;
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 
703 {
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 {
992 
999  PaTime inputLatency;
1000 
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 
1155 PaHostApiTypeId Pa_GetStreamHostApiType( PaStream* stream );
1156 
1157 
1158 /* Miscellaneous utilities */
1159 
1160 
1166 PaError Pa_GetSampleSize( PaSampleFormat format );
1167 
1168 
1176 void Pa_Sleep( long msec );
1177 
1178 
1179 
1180 #ifdef __cplusplus
1181 }
1182 #endif /* __cplusplus */
1183 #endif /* PORTAUDIO_H */