Jack2 1.9.6

portaudio.h

Go to the documentation of this file.
00001 
00002 #ifndef PORTAUDIO_H
00003 #define PORTAUDIO_H
00004 /*
00005  * $Id: portaudio.h,v 1.1.2.2 2006/06/20 14:44:48 letz Exp $
00006  * PortAudio Portable Real-Time Audio Library
00007  * PortAudio API Header File
00008  * Latest version available at: http://www.portaudio.com/
00009  *
00010  * Copyright (c) 1999-2002 Ross Bencina and Phil Burk
00011  *
00012  * Permission is hereby granted, free of charge, to any person obtaining
00013  * a copy of this software and associated documentation files
00014  * (the "Software"), to deal in the Software without restriction,
00015  * including without limitation the rights to use, copy, modify, merge,
00016  * publish, distribute, sublicense, and/or sell copies of the Software,
00017  * and to permit persons to whom the Software is furnished to do so,
00018  * subject to the following conditions:
00019  *
00020  * The above copyright notice and this permission notice shall be
00021  * included in all copies or substantial portions of the Software.
00022  *
00023  * Any person wishing to distribute modifications to the Software is
00024  * requested to send the modifications to the original developer so that
00025  * they can be incorporated into the canonical version.
00026  *
00027  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
00028  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
00029  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
00030  * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR
00031  * ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
00032  * CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
00033  * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
00034  */
00035 
00041 #ifdef __cplusplus
00042 extern "C"
00043 {
00044 #endif /* __cplusplus */
00045 
00046 
00050     int Pa_GetVersion( void );
00051 
00052 
00056     const char* Pa_GetVersionText( void );
00057 
00058 
00063     typedef int PaError;
00064     typedef enum PaErrorCode {
00065         paNoError = 0,
00066 
00067         paNotInitialized = -10000,
00068         paUnanticipatedHostError,
00069         paInvalidChannelCount,
00070         paInvalidSampleRate,
00071         paInvalidDevice,
00072         paInvalidFlag,
00073         paSampleFormatNotSupported,
00074         paBadIODeviceCombination,
00075         paInsufficientMemory,
00076         paBufferTooBig,
00077         paBufferTooSmall,
00078         paNullCallback,
00079         paBadStreamPtr,
00080         paTimedOut,
00081         paInternalError,
00082         paDeviceUnavailable,
00083         paIncompatibleHostApiSpecificStreamInfo,
00084         paStreamIsStopped,
00085         paStreamIsNotStopped,
00086         paInputOverflowed,
00087         paOutputUnderflowed,
00088         paHostApiNotFound,
00089         paInvalidHostApi,
00090         paCanNotReadFromACallbackStream,       
00091         paCanNotWriteToACallbackStream,        
00092         paCanNotReadFromAnOutputOnlyStream,    
00093         paCanNotWriteToAnInputOnlyStream,      
00094         paIncompatibleStreamHostApi,
00095         paBadBufferPtr
00096     }
00097     PaErrorCode;
00098 
00099 
00103     const char *Pa_GetErrorText( PaError errorCode );
00104 
00105 
00124     PaError Pa_Initialize( void );
00125 
00126 
00143     PaError Pa_Terminate( void );
00144 
00145 
00146 
00153     typedef int PaDeviceIndex;
00154 
00155 
00161 #define paNoDevice ((PaDeviceIndex)-1)
00162 
00163 
00169 #define paUseHostApiSpecificDeviceSpecification ((PaDeviceIndex)-2)
00170 
00171 
00172     /* Host API enumeration mechanism */
00173 
00179     typedef int PaHostApiIndex;
00180 
00181 
00191     PaHostApiIndex Pa_GetHostApiCount( void );
00192 
00193 
00202     PaHostApiIndex Pa_GetDefaultHostApi( void );
00203 
00204 
00216     typedef enum PaHostApiTypeId {
00217         paInDevelopment = 0,  /* use while developing support for a new host API */
00218         paDirectSound = 1,
00219         paMME = 2,
00220         paASIO = 3,
00221         paSoundManager = 4,
00222         paCoreAudio = 5,
00223         paOSS = 7,
00224         paALSA = 8,
00225         paAL = 9,
00226         paBeOS = 10,
00227         paWDMKS = 11,
00228         paJACK = 12,
00229         paWASAPI = 13
00230     }
00231     PaHostApiTypeId;
00232 
00233 
00236     typedef struct PaHostApiInfo {
00238         int structVersion;
00240         PaHostApiTypeId type;
00242         const char *name;
00243 
00249         int deviceCount;
00250 
00255         PaDeviceIndex defaultInputDevice;
00256 
00261         PaDeviceIndex defaultOutputDevice;
00262 
00263     }
00264     PaHostApiInfo;
00265 
00266 
00280     const PaHostApiInfo * Pa_GetHostApiInfo( PaHostApiIndex hostApi );
00281 
00282 
00298     PaHostApiIndex Pa_HostApiTypeIdToHostApiIndex( PaHostApiTypeId type );
00299 
00300 
00322     PaDeviceIndex Pa_HostApiDeviceIndexToDeviceIndex( PaHostApiIndex hostApi,
00323             int hostApiDeviceIndex );
00324 
00325 
00326 
00329     typedef struct PaHostErrorInfo {
00330         PaHostApiTypeId hostApiType;    
00331         long errorCode;                 
00332         const char *errorText;          
00333     }
00334     PaHostErrorInfo;
00335 
00336 
00350     const PaHostErrorInfo* Pa_GetLastHostErrorInfo( void );
00351 
00352 
00353 
00354     /* Device enumeration and capabilities */
00355 
00363     PaDeviceIndex Pa_GetDeviceCount( void );
00364 
00365 
00372     PaDeviceIndex Pa_GetDefaultInputDevice( void );
00373 
00374 
00390     PaDeviceIndex Pa_GetDefaultOutputDevice( void );
00391 
00392 
00399     typedef double PaTime;
00400 
00401 
00421     typedef unsigned long PaSampleFormat;
00422 
00423 
00424 #define paFloat32        ((PaSampleFormat) 0x00000001) 
00425 #define paInt32          ((PaSampleFormat) 0x00000002) 
00426 #define paInt24          ((PaSampleFormat) 0x00000004) 
00427 #define paInt16          ((PaSampleFormat) 0x00000008) 
00428 #define paInt8           ((PaSampleFormat) 0x00000010) 
00429 #define paUInt8          ((PaSampleFormat) 0x00000020) 
00430 #define paCustomFormat   ((PaSampleFormat) 0x00010000)
00432 #define paNonInterleaved ((PaSampleFormat) 0x80000000)
00433 
00437     typedef struct PaDeviceInfo {
00438         int structVersion;  /* this is struct version 2 */
00439         const char *name;
00440         PaHostApiIndex hostApi; /* note this is a host API index, not a type id*/
00441 
00442         int maxInputChannels;
00443         int maxOutputChannels;
00444 
00445         /* Default latency values for interactive performance. */
00446         PaTime defaultLowInputLatency;
00447         PaTime defaultLowOutputLatency;
00448         /* Default latency values for robust non-interactive applications (eg. playing sound files). */
00449         PaTime defaultHighInputLatency;
00450         PaTime defaultHighOutputLatency;
00451 
00452         double defaultSampleRate;
00453     }
00454     PaDeviceInfo;
00455 
00456 
00470     const PaDeviceInfo* Pa_GetDeviceInfo( PaDeviceIndex device );
00471 
00472 
00475     typedef struct PaStreamParameters {
00482         PaDeviceIndex device;
00483 
00489         int channelCount;
00490 
00495         PaSampleFormat sampleFormat;
00496 
00508         PaTime suggestedLatency;
00509 
00515         void *hostApiSpecificStreamInfo;
00516 
00517     }
00518     PaStreamParameters;
00519 
00520 
00522 #define paFormatIsSupported (0)
00523 
00546     PaError Pa_IsFormatSupported( const PaStreamParameters *inputParameters,
00547                                   const PaStreamParameters *outputParameters,
00548                                   double sampleRate );
00549 
00550 
00551 
00552     /* Streaming types and functions */
00553 
00554 
00572     typedef void PaStream;
00573 
00574 
00579 #define paFramesPerBufferUnspecified  (0)
00580 
00581 
00590     typedef unsigned long PaStreamFlags;
00591 
00593 #define   paNoFlag          ((PaStreamFlags) 0)
00594 
00598 #define   paClipOff         ((PaStreamFlags) 0x00000001)
00599 
00603 #define   paDitherOff       ((PaStreamFlags) 0x00000002)
00604 
00614 #define   paNeverDropInput  ((PaStreamFlags) 0x00000004)
00615 
00622 #define   paPrimeOutputBuffersUsingStreamCallback ((PaStreamFlags) 0x00000008)
00623 
00627 #define   paPlatformSpecificFlags ((PaStreamFlags)0xFFFF0000)
00628 
00632     typedef struct PaStreamCallbackTimeInfo {
00633         PaTime inputBufferAdcTime;
00634         PaTime currentTime;
00635         PaTime outputBufferDacTime;
00636     }
00637     PaStreamCallbackTimeInfo;
00638 
00639 
00646     typedef unsigned long PaStreamCallbackFlags;
00647 
00655 #define paInputUnderflow   ((PaStreamCallbackFlags) 0x00000001)
00656 
00664 #define paInputOverflow    ((PaStreamCallbackFlags) 0x00000002)
00665 
00670 #define paOutputUnderflow  ((PaStreamCallbackFlags) 0x00000004)
00671 
00675 #define paOutputOverflow   ((PaStreamCallbackFlags) 0x00000008)
00676 
00681 #define paPrimingOutput    ((PaStreamCallbackFlags) 0x00000010)
00682 
00687     typedef enum PaStreamCallbackResult
00688     {
00689         paContinue = 0,
00690         paComplete = 1,
00691         paAbort = 2
00692     } PaStreamCallbackResult;
00693 
00694 
00739     typedef int PaStreamCallback(
00740         const void *input, void *output,
00741         unsigned long frameCount,
00742         const PaStreamCallbackTimeInfo* timeInfo,
00743         PaStreamCallbackFlags statusFlags,
00744         void *userData );
00745 
00746 
00801     PaError Pa_OpenStream( PaStream** stream,
00802                            const PaStreamParameters *inputParameters,
00803                            const PaStreamParameters *outputParameters,
00804                            double sampleRate,
00805                            unsigned long framesPerBuffer,
00806                            PaStreamFlags streamFlags,
00807                            PaStreamCallback *streamCallback,
00808                            void *userData );
00809 
00810 
00841     PaError Pa_OpenDefaultStream( PaStream** stream,
00842                                   int numInputChannels,
00843                                   int numOutputChannels,
00844                                   PaSampleFormat sampleFormat,
00845                                   double sampleRate,
00846                                   unsigned long framesPerBuffer,
00847                                   PaStreamCallback *streamCallback,
00848                                   void *userData );
00849 
00850 
00854     PaError Pa_CloseStream( PaStream *stream );
00855 
00856 
00871     typedef void PaStreamFinishedCallback( void *userData );
00872 
00873 
00892     PaError Pa_SetStreamFinishedCallback( PaStream *stream, PaStreamFinishedCallback* streamFinishedCallback );
00893 
00894 
00897     PaError Pa_StartStream( PaStream *stream );
00898 
00899 
00903     PaError Pa_StopStream( PaStream *stream );
00904 
00905 
00909     PaError Pa_AbortStream( PaStream *stream );
00910 
00911 
00924     PaError Pa_IsStreamStopped( PaStream *stream );
00925 
00926 
00940     PaError Pa_IsStreamActive( PaStream *stream );
00941 
00942 
00943 
00948     typedef struct PaStreamInfo {
00950         int structVersion;
00951 
00958         PaTime inputLatency;
00959 
00966         PaTime outputLatency;
00967 
00975         double sampleRate;
00976 
00977     }
00978     PaStreamInfo;
00979 
00980 
00994     const PaStreamInfo* Pa_GetStreamInfo( PaStream *stream );
00995 
00996 
01005     PaTime Pa_GetStreamTime( PaStream *stream );
01006 
01007 
01024     double Pa_GetStreamCpuLoad( PaStream* stream );
01025 
01026 
01048     PaError Pa_ReadStream( PaStream* stream,
01049                            void *buffer,
01050                            unsigned long frames );
01051 
01052 
01075     PaError Pa_WriteStream( PaStream* stream,
01076                             const void *buffer,
01077                             unsigned long frames );
01078 
01079 
01088     signed long Pa_GetStreamReadAvailable( PaStream* stream );
01089 
01090 
01099     signed long Pa_GetStreamWriteAvailable( PaStream* stream );
01100 
01101 
01102     /* Miscellaneous utilities */
01103 
01104 
01110     PaError Pa_GetSampleSize( PaSampleFormat format );
01111 
01112 
01120     void Pa_Sleep( long msec );
01121 
01122 
01123 
01124 #ifdef __cplusplus
01125 }
01126 #endif /* __cplusplus */
01127 #endif /* PORTAUDIO_H */