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 
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 
892 PaError Pa_OpenStream( PaStream** stream,
893  const PaStreamParameters *inputParameters,
894  const PaStreamParameters *outputParameters,
895  double sampleRate,
896  unsigned long framesPerBuffer,
897  PaStreamFlags streamFlags,
898  PaStreamCallback *streamCallback,
899  void *userData );
900 
901 
932 PaError Pa_OpenDefaultStream( PaStream** stream,
933  int numInputChannels,
934  int numOutputChannels,
935  PaSampleFormat sampleFormat,
936  double sampleRate,
937  unsigned long framesPerBuffer,
938  PaStreamCallback *streamCallback,
939  void *userData );
940 
941 
945 PaError Pa_CloseStream( PaStream *stream );
946 
947 
962 typedef void PaStreamFinishedCallback( void *userData );
963 
964 
983 PaError Pa_SetStreamFinishedCallback( PaStream *stream, PaStreamFinishedCallback* streamFinishedCallback );
984 
985 
988 PaError Pa_StartStream( PaStream *stream );
989 
990 
994 PaError Pa_StopStream( PaStream *stream );
995 
996 
1000 PaError Pa_AbortStream( PaStream *stream );
1001 
1002 
1015 PaError Pa_IsStreamStopped( PaStream *stream );
1016 
1017 
1031 PaError Pa_IsStreamActive( PaStream *stream );
1032 
1033 
1034 
1039 typedef struct PaStreamInfo
1040 {
1043 
1051 
1059 
1067  double sampleRate;
1068 
1069 } PaStreamInfo;
1070 
1071 
1085 const PaStreamInfo* Pa_GetStreamInfo( PaStream *stream );
1086 
1087 
1103 PaTime Pa_GetStreamTime( PaStream *stream );
1104 
1105 
1122 double Pa_GetStreamCpuLoad( PaStream* stream );
1123 
1124 
1146 PaError Pa_ReadStream( PaStream* stream,
1147  void *buffer,
1148  unsigned long frames );
1149 
1150 
1173 PaError Pa_WriteStream( PaStream* stream,
1174  const void *buffer,
1175  unsigned long frames );
1176 
1177 
1186 signed long Pa_GetStreamReadAvailable( PaStream* stream );
1187 
1188 
1197 signed long Pa_GetStreamWriteAvailable( PaStream* stream );
1198 
1199 
1200 /* Miscellaneous utilities */
1201 
1202 
1208 PaError Pa_GetSampleSize( PaSampleFormat format );
1209 
1210 
1218 void Pa_Sleep( long msec );
1219 
1220 
1221 
1222 #ifdef __cplusplus
1223 }
1224 #endif /* __cplusplus */
1225 #endif /* PORTAUDIO_H */