PortAudio  2.0
portaudio.h
Go to the documentation of this file.
00001 #ifndef PORTAUDIO_H
00002 #define PORTAUDIO_H
00003 /*
00004  * $Id: portaudio.h 1745 2011-08-25 17:44:01Z rossb $
00005  * PortAudio Portable Real-Time Audio Library
00006  * PortAudio API Header File
00007  * Latest version available at: http://www.portaudio.com/
00008  *
00009  * Copyright (c) 1999-2002 Ross Bencina and Phil Burk
00010  *
00011  * Permission is hereby granted, free of charge, to any person obtaining
00012  * a copy of this software and associated documentation files
00013  * (the "Software"), to deal in the Software without restriction,
00014  * including without limitation the rights to use, copy, modify, merge,
00015  * publish, distribute, sublicense, and/or sell copies of the Software,
00016  * and to permit persons to whom the Software is furnished to do so,
00017  * subject to the following conditions:
00018  *
00019  * The above copyright notice and this permission notice shall be
00020  * included in all copies or substantial portions of the Software.
00021  *
00022  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
00023  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
00024  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
00025  * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR
00026  * ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
00027  * CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
00028  * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
00029  */
00030 
00031 /*
00032  * The text above constitutes the entire PortAudio license; however, 
00033  * the PortAudio community also makes the following non-binding requests:
00034  *
00035  * Any person wishing to distribute modifications to the Software is
00036  * requested to send the modifications to the original developer so that
00037  * they can be incorporated into the canonical version. It is also 
00038  * requested that these non-binding requests be included along with the 
00039  * license above.
00040  */
00041 
00048 #ifdef __cplusplus
00049 extern "C"
00050 {
00051 #endif /* __cplusplus */
00052 
00053  
00057 int Pa_GetVersion( void );
00058 
00059 
00063 const char* Pa_GetVersionText( void );
00064 
00065 
00070 typedef int PaError;
00071 typedef enum PaErrorCode
00072 {
00073     paNoError = 0,
00074 
00075     paNotInitialized = -10000,
00076     paUnanticipatedHostError,
00077     paInvalidChannelCount,
00078     paInvalidSampleRate,
00079     paInvalidDevice,
00080     paInvalidFlag,
00081     paSampleFormatNotSupported,
00082     paBadIODeviceCombination,
00083     paInsufficientMemory,
00084     paBufferTooBig,
00085     paBufferTooSmall,
00086     paNullCallback,
00087     paBadStreamPtr,
00088     paTimedOut,
00089     paInternalError,
00090     paDeviceUnavailable,
00091     paIncompatibleHostApiSpecificStreamInfo,
00092     paStreamIsStopped,
00093     paStreamIsNotStopped,
00094     paInputOverflowed,
00095     paOutputUnderflowed,
00096     paHostApiNotFound,
00097     paInvalidHostApi,
00098     paCanNotReadFromACallbackStream,
00099     paCanNotWriteToACallbackStream,
00100     paCanNotReadFromAnOutputOnlyStream,
00101     paCanNotWriteToAnInputOnlyStream,
00102     paIncompatibleStreamHostApi,
00103     paBadBufferPtr
00104 } PaErrorCode;
00105 
00106 
00110 const char *Pa_GetErrorText( PaError errorCode );
00111 
00112 
00132 PaError Pa_Initialize( void );
00133 
00134 
00151 PaError Pa_Terminate( void );
00152 
00153 
00154 
00161 typedef int PaDeviceIndex;
00162 
00163 
00169 #define paNoDevice ((PaDeviceIndex)-1)
00170 
00171 
00177 #define paUseHostApiSpecificDeviceSpecification ((PaDeviceIndex)-2)
00178 
00179 
00180 /* Host API enumeration mechanism */
00181 
00187 typedef int PaHostApiIndex;
00188 
00189 
00199 PaHostApiIndex Pa_GetHostApiCount( void );
00200 
00201 
00210 PaHostApiIndex Pa_GetDefaultHostApi( void );
00211 
00212 
00224 typedef enum PaHostApiTypeId
00225 {
00226     paInDevelopment=0, /* use while developing support for a new host API */
00227     paDirectSound=1,
00228     paMME=2,
00229     paASIO=3,
00230     paSoundManager=4,
00231     paCoreAudio=5,
00232     paOSS=7,
00233     paALSA=8,
00234     paAL=9,
00235     paBeOS=10,
00236     paWDMKS=11,
00237     paJACK=12,
00238     paWASAPI=13,
00239     paAudioScienceHPI=14
00240 } PaHostApiTypeId;
00241 
00242 
00245 typedef struct PaHostApiInfo
00246 {
00248     int structVersion;
00250     PaHostApiTypeId type;
00252     const char *name;
00253 
00259     int deviceCount;
00260 
00265     PaDeviceIndex defaultInputDevice;
00266 
00271     PaDeviceIndex defaultOutputDevice;
00272     
00273 } PaHostApiInfo;
00274 
00275 
00289 const PaHostApiInfo * Pa_GetHostApiInfo( PaHostApiIndex hostApi );
00290 
00291 
00307 PaHostApiIndex Pa_HostApiTypeIdToHostApiIndex( PaHostApiTypeId type );
00308 
00309 
00331 PaDeviceIndex Pa_HostApiDeviceIndexToDeviceIndex( PaHostApiIndex hostApi,
00332         int hostApiDeviceIndex );
00333 
00334 
00335 
00338 typedef struct PaHostErrorInfo{
00339     PaHostApiTypeId hostApiType;    
00340     long errorCode;                 
00341     const char *errorText;          
00342 }PaHostErrorInfo;
00343 
00344 
00358 const PaHostErrorInfo* Pa_GetLastHostErrorInfo( void );
00359 
00360 
00361 
00362 /* Device enumeration and capabilities */
00363 
00371 PaDeviceIndex Pa_GetDeviceCount( void );
00372 
00373 
00380 PaDeviceIndex Pa_GetDefaultInputDevice( void );
00381 
00382 
00398 PaDeviceIndex Pa_GetDefaultOutputDevice( void );
00399 
00400 
00409 typedef double PaTime;
00410 
00411 
00433 typedef unsigned long PaSampleFormat;
00434 
00435 
00436 #define paFloat32        ((PaSampleFormat) 0x00000001) 
00437 #define paInt32          ((PaSampleFormat) 0x00000002) 
00438 #define paInt24          ((PaSampleFormat) 0x00000004) 
00439 #define paInt16          ((PaSampleFormat) 0x00000008) 
00440 #define paInt8           ((PaSampleFormat) 0x00000010) 
00441 #define paUInt8          ((PaSampleFormat) 0x00000020) 
00442 #define paCustomFormat   ((PaSampleFormat) 0x00010000) 
00444 #define paNonInterleaved ((PaSampleFormat) 0x80000000) 
00449 typedef struct PaDeviceInfo
00450 {
00451     int structVersion;  /* this is struct version 2 */
00452     const char *name;
00453     PaHostApiIndex hostApi; 
00455     int maxInputChannels;
00456     int maxOutputChannels;
00457 
00459     PaTime defaultLowInputLatency;
00460     PaTime defaultLowOutputLatency;
00462     PaTime defaultHighInputLatency;
00463     PaTime defaultHighOutputLatency;
00464 
00465     double defaultSampleRate;
00466 } PaDeviceInfo;
00467 
00468 
00482 const PaDeviceInfo* Pa_GetDeviceInfo( PaDeviceIndex device );
00483 
00484 
00487 typedef struct PaStreamParameters
00488 {
00495     PaDeviceIndex device;
00496     
00502     int channelCount;
00503 
00508     PaSampleFormat sampleFormat;
00509 
00521     PaTime suggestedLatency;
00522 
00528     void *hostApiSpecificStreamInfo;
00529 
00530 } PaStreamParameters;
00531 
00532 
00534 #define paFormatIsSupported (0)
00535 
00558 PaError Pa_IsFormatSupported( const PaStreamParameters *inputParameters,
00559                               const PaStreamParameters *outputParameters,
00560                               double sampleRate );
00561 
00562 
00563 
00564 /* Streaming types and functions */
00565 
00566 
00584 typedef void PaStream;
00585 
00586 
00591 #define paFramesPerBufferUnspecified  (0)
00592 
00593 
00602 typedef unsigned long PaStreamFlags;
00603 
00605 #define   paNoFlag          ((PaStreamFlags) 0)
00606 
00610 #define   paClipOff         ((PaStreamFlags) 0x00000001)
00611 
00615 #define   paDitherOff       ((PaStreamFlags) 0x00000002)
00616 
00626 #define   paNeverDropInput  ((PaStreamFlags) 0x00000004)
00627 
00634 #define   paPrimeOutputBuffersUsingStreamCallback ((PaStreamFlags) 0x00000008)
00635 
00639 #define   paPlatformSpecificFlags ((PaStreamFlags)0xFFFF0000)
00640 
00648 typedef struct PaStreamCallbackTimeInfo{
00649     PaTime inputBufferAdcTime;  
00650     PaTime currentTime;         
00651     PaTime outputBufferDacTime; 
00652 } PaStreamCallbackTimeInfo;
00653 
00654 
00661 typedef unsigned long PaStreamCallbackFlags;
00662 
00670 #define paInputUnderflow   ((PaStreamCallbackFlags) 0x00000001)
00671 
00679 #define paInputOverflow    ((PaStreamCallbackFlags) 0x00000002)
00680 
00685 #define paOutputUnderflow  ((PaStreamCallbackFlags) 0x00000004)
00686 
00690 #define paOutputOverflow   ((PaStreamCallbackFlags) 0x00000008)
00691 
00696 #define paPrimingOutput    ((PaStreamCallbackFlags) 0x00000010)
00697 
00702 typedef enum PaStreamCallbackResult
00703 {
00704     paContinue=0,   
00705     paComplete=1,   
00706     paAbort=2       
00707 } PaStreamCallbackResult;
00708 
00709 
00779 typedef int PaStreamCallback(
00780     const void *input, void *output,
00781     unsigned long frameCount,
00782     const PaStreamCallbackTimeInfo* timeInfo,
00783     PaStreamCallbackFlags statusFlags,
00784     void *userData );
00785 
00786 
00841 PaError Pa_OpenStream( PaStream** stream,
00842                        const PaStreamParameters *inputParameters,
00843                        const PaStreamParameters *outputParameters,
00844                        double sampleRate,
00845                        unsigned long framesPerBuffer,
00846                        PaStreamFlags streamFlags,
00847                        PaStreamCallback *streamCallback,
00848                        void *userData );
00849 
00850 
00881 PaError Pa_OpenDefaultStream( PaStream** stream,
00882                               int numInputChannels,
00883                               int numOutputChannels,
00884                               PaSampleFormat sampleFormat,
00885                               double sampleRate,
00886                               unsigned long framesPerBuffer,
00887                               PaStreamCallback *streamCallback,
00888                               void *userData );
00889 
00890 
00894 PaError Pa_CloseStream( PaStream *stream );
00895 
00896 
00911 typedef void PaStreamFinishedCallback( void *userData );
00912 
00913 
00932 PaError Pa_SetStreamFinishedCallback( PaStream *stream, PaStreamFinishedCallback* streamFinishedCallback ); 
00933 
00934 
00937 PaError Pa_StartStream( PaStream *stream );
00938 
00939 
00943 PaError Pa_StopStream( PaStream *stream );
00944 
00945 
00949 PaError Pa_AbortStream( PaStream *stream );
00950 
00951 
00964 PaError Pa_IsStreamStopped( PaStream *stream );
00965 
00966 
00980 PaError Pa_IsStreamActive( PaStream *stream );
00981 
00982 
00983 
00988 typedef struct PaStreamInfo
00989 {
00991     int structVersion;
00992 
00999     PaTime inputLatency;
01000 
01007     PaTime outputLatency;
01008 
01016     double sampleRate;
01017     
01018 } PaStreamInfo;
01019 
01020 
01034 const PaStreamInfo* Pa_GetStreamInfo( PaStream *stream );
01035 
01036 
01052 PaTime Pa_GetStreamTime( PaStream *stream );
01053 
01054 
01071 double Pa_GetStreamCpuLoad( PaStream* stream );
01072 
01073 
01095 PaError Pa_ReadStream( PaStream* stream,
01096                        void *buffer,
01097                        unsigned long frames );
01098 
01099 
01122 PaError Pa_WriteStream( PaStream* stream,
01123                         const void *buffer,
01124                         unsigned long frames );
01125 
01126 
01135 signed long Pa_GetStreamReadAvailable( PaStream* stream );
01136 
01137 
01146 signed long Pa_GetStreamWriteAvailable( PaStream* stream );
01147 
01148 
01155 PaHostApiTypeId Pa_GetStreamHostApiType( PaStream* stream );
01156 
01157 
01158 /* Miscellaneous utilities */
01159 
01160 
01166 PaError Pa_GetSampleSize( PaSampleFormat format );
01167 
01168 
01176 void Pa_Sleep( long msec );
01177 
01178 
01179 
01180 #ifdef __cplusplus
01181 }
01182 #endif /* __cplusplus */
01183 #endif /* PORTAUDIO_H */