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 1594 2011-02-05 14:33:29Z 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; /* note this is a host API index, not a type id*/
00454     
00455     int maxInputChannels;
00456     int maxOutputChannels;
00457 
00458     /* Default latency values for interactive performance. */
00459     PaTime defaultLowInputLatency;
00460     PaTime defaultLowOutputLatency;
00461     /* Default latency values for robust non-interactive applications (eg. playing sound files). */
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 
00644 typedef struct PaStreamCallbackTimeInfo{
00645     PaTime inputBufferAdcTime;
00646     PaTime currentTime;
00647     PaTime outputBufferDacTime;
00648 } PaStreamCallbackTimeInfo;
00649 
00650 
00657 typedef unsigned long PaStreamCallbackFlags;
00658 
00666 #define paInputUnderflow   ((PaStreamCallbackFlags) 0x00000001)
00667 
00675 #define paInputOverflow    ((PaStreamCallbackFlags) 0x00000002)
00676 
00681 #define paOutputUnderflow  ((PaStreamCallbackFlags) 0x00000004)
00682 
00686 #define paOutputOverflow   ((PaStreamCallbackFlags) 0x00000008)
00687 
00692 #define paPrimingOutput    ((PaStreamCallbackFlags) 0x00000010)
00693 
00698 typedef enum PaStreamCallbackResult
00699 {
00700     paContinue=0,
00701     paComplete=1,
00702     paAbort=2
00703 } PaStreamCallbackResult;
00704 
00705 
00754 typedef int PaStreamCallback(
00755     const void *input, void *output,
00756     unsigned long frameCount,
00757     const PaStreamCallbackTimeInfo* timeInfo,
00758     PaStreamCallbackFlags statusFlags,
00759     void *userData );
00760 
00761 
00816 PaError Pa_OpenStream( PaStream** stream,
00817                        const PaStreamParameters *inputParameters,
00818                        const PaStreamParameters *outputParameters,
00819                        double sampleRate,
00820                        unsigned long framesPerBuffer,
00821                        PaStreamFlags streamFlags,
00822                        PaStreamCallback *streamCallback,
00823                        void *userData );
00824 
00825 
00856 PaError Pa_OpenDefaultStream( PaStream** stream,
00857                               int numInputChannels,
00858                               int numOutputChannels,
00859                               PaSampleFormat sampleFormat,
00860                               double sampleRate,
00861                               unsigned long framesPerBuffer,
00862                               PaStreamCallback *streamCallback,
00863                               void *userData );
00864 
00865 
00869 PaError Pa_CloseStream( PaStream *stream );
00870 
00871 
00886 typedef void PaStreamFinishedCallback( void *userData );
00887 
00888 
00907 PaError Pa_SetStreamFinishedCallback( PaStream *stream, PaStreamFinishedCallback* streamFinishedCallback ); 
00908 
00909 
00912 PaError Pa_StartStream( PaStream *stream );
00913 
00914 
00918 PaError Pa_StopStream( PaStream *stream );
00919 
00920 
00924 PaError Pa_AbortStream( PaStream *stream );
00925 
00926 
00939 PaError Pa_IsStreamStopped( PaStream *stream );
00940 
00941 
00955 PaError Pa_IsStreamActive( PaStream *stream );
00956 
00957 
00958 
00963 typedef struct PaStreamInfo
00964 {
00966     int structVersion;
00967 
00974     PaTime inputLatency;
00975 
00982     PaTime outputLatency;
00983 
00991     double sampleRate;
00992     
00993 } PaStreamInfo;
00994 
00995 
01009 const PaStreamInfo* Pa_GetStreamInfo( PaStream *stream );
01010 
01011 
01027 PaTime Pa_GetStreamTime( PaStream *stream );
01028 
01029 
01046 double Pa_GetStreamCpuLoad( PaStream* stream );
01047 
01048 
01070 PaError Pa_ReadStream( PaStream* stream,
01071                        void *buffer,
01072                        unsigned long frames );
01073 
01074 
01097 PaError Pa_WriteStream( PaStream* stream,
01098                         const void *buffer,
01099                         unsigned long frames );
01100 
01101 
01110 signed long Pa_GetStreamReadAvailable( PaStream* stream );
01111 
01112 
01121 signed long Pa_GetStreamWriteAvailable( PaStream* stream );
01122 
01123 
01130 PaHostApiTypeId Pa_GetStreamHostApiType( PaStream* stream );
01131 
01132 
01133 /* Miscellaneous utilities */
01134 
01135 
01141 PaError Pa_GetSampleSize( PaSampleFormat format );
01142 
01143 
01151 void Pa_Sleep( long msec );
01152 
01153 
01154 
01155 #ifdef __cplusplus
01156 }
01157 #endif /* __cplusplus */
01158 #endif /* PORTAUDIO_H */