+++ /dev/null
-#ifndef PORTAUDIO_H\r
-#define PORTAUDIO_H\r
-/*\r
- * $Id: portaudio.h 1745 2011-08-25 17:44:01Z rossb $\r
- * PortAudio Portable Real-Time Audio Library\r
- * PortAudio API Header File\r
- * Latest version available at: http://www.portaudio.com/\r
- *\r
- * Copyright (c) 1999-2002 Ross Bencina and Phil Burk\r
- *\r
- * Permission is hereby granted, free of charge, to any person obtaining\r
- * a copy of this software and associated documentation files\r
- * (the "Software"), to deal in the Software without restriction,\r
- * including without limitation the rights to use, copy, modify, merge,\r
- * publish, distribute, sublicense, and/or sell copies of the Software,\r
- * and to permit persons to whom the Software is furnished to do so,\r
- * subject to the following conditions:\r
- *\r
- * The above copyright notice and this permission notice shall be\r
- * included in all copies or substantial portions of the Software.\r
- *\r
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,\r
- * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF\r
- * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.\r
- * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR\r
- * ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF\r
- * CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION\r
- * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\r
- */\r
-\r
-/*\r
- * The text above constitutes the entire PortAudio license; however,\r
- * the PortAudio community also makes the following non-binding requests:\r
- *\r
- * Any person wishing to distribute modifications to the Software is\r
- * requested to send the modifications to the original developer so that\r
- * they can be incorporated into the canonical version. It is also\r
- * requested that these non-binding requests be included along with the\r
- * license above.\r
- */\r
-\r
-/** @file\r
- @ingroup public_header\r
- @brief The portable PortAudio API.\r
-*/\r
-\r
-\r
-#ifdef __cplusplus\r
-extern "C"\r
-{\r
-#endif /* __cplusplus */\r
-\r
-\r
-/** Retrieve the release number of the currently running PortAudio build,\r
- eg 1900.\r
-*/\r
-int Pa_GetVersion( void );\r
-\r
-\r
-/** Retrieve a textual description of the current PortAudio build,\r
- eg "PortAudio V19-devel 13 October 2002".\r
-*/\r
-const char* Pa_GetVersionText( void );\r
-\r
-\r
-/** Error codes returned by PortAudio functions.\r
- Note that with the exception of paNoError, all PaErrorCodes are negative.\r
-*/\r
-\r
-typedef int PaError;\r
-typedef enum PaErrorCode\r
-{\r
- paNoError = 0,\r
-\r
- paNotInitialized = -10000,\r
- paUnanticipatedHostError,\r
- paInvalidChannelCount,\r
- paInvalidSampleRate,\r
- paInvalidDevice,\r
- paInvalidFlag,\r
- paSampleFormatNotSupported,\r
- paBadIODeviceCombination,\r
- paInsufficientMemory,\r
- paBufferTooBig,\r
- paBufferTooSmall,\r
- paNullCallback,\r
- paBadStreamPtr,\r
- paTimedOut,\r
- paInternalError,\r
- paDeviceUnavailable,\r
- paIncompatibleHostApiSpecificStreamInfo,\r
- paStreamIsStopped,\r
- paStreamIsNotStopped,\r
- paInputOverflowed,\r
- paOutputUnderflowed,\r
- paHostApiNotFound,\r
- paInvalidHostApi,\r
- paCanNotReadFromACallbackStream,\r
- paCanNotWriteToACallbackStream,\r
- paCanNotReadFromAnOutputOnlyStream,\r
- paCanNotWriteToAnInputOnlyStream,\r
- paIncompatibleStreamHostApi,\r
- paBadBufferPtr\r
-} PaErrorCode;\r
-\r
-\r
-/** Translate the supplied PortAudio error code into a human readable\r
- message.\r
-*/\r
-const char *Pa_GetErrorText( PaError errorCode );\r
-\r
-\r
-/** Library initialization function - call this before using PortAudio.\r
- This function initializes internal data structures and prepares underlying\r
- host APIs for use. With the exception of Pa_GetVersion(), Pa_GetVersionText(),\r
- and Pa_GetErrorText(), this function MUST be called before using any other\r
- PortAudio API functions.\r
-\r
- If Pa_Initialize() is called multiple times, each successful\r
- call must be matched with a corresponding call to Pa_Terminate().\r
- Pairs of calls to Pa_Initialize()/Pa_Terminate() may overlap, and are not\r
- required to be fully nested.\r
-\r
- Note that if Pa_Initialize() returns an error code, Pa_Terminate() should\r
- NOT be called.\r
-\r
- @return paNoError if successful, otherwise an error code indicating the cause\r
- of failure.\r
-\r
- @see Pa_Terminate\r
-*/\r
-PaError Pa_Initialize( void );\r
-\r
-\r
-/** Library termination function - call this when finished using PortAudio.\r
- This function deallocates all resources allocated by PortAudio since it was\r
- initialized by a call to Pa_Initialize(). In cases where Pa_Initialise() has\r
- been called multiple times, each call must be matched with a corresponding call\r
- to Pa_Terminate(). The final matching call to Pa_Terminate() will automatically\r
- close any PortAudio streams that are still open.\r
-\r
- Pa_Terminate() MUST be called before exiting a program which uses PortAudio.\r
- Failure to do so may result in serious resource leaks, such as audio devices\r
- not being available until the next reboot.\r
-\r
- @return paNoError if successful, otherwise an error code indicating the cause\r
- of failure.\r
-\r
- @see Pa_Initialize\r
-*/\r
-PaError Pa_Terminate( void );\r
-\r
-\r
-\r
-/** The type used to refer to audio devices. Values of this type usually\r
- range from 0 to (Pa_GetDeviceCount()-1), and may also take on the PaNoDevice\r
- and paUseHostApiSpecificDeviceSpecification values.\r
-\r
- @see Pa_GetDeviceCount, paNoDevice, paUseHostApiSpecificDeviceSpecification\r
-*/\r
-typedef int PaDeviceIndex;\r
-\r
-\r
-/** A special PaDeviceIndex value indicating that no device is available,\r
- or should be used.\r
-\r
- @see PaDeviceIndex\r
-*/\r
-#define paNoDevice ((PaDeviceIndex)-1)\r
-\r
-\r
-/** A special PaDeviceIndex value indicating that the device(s) to be used\r
- are specified in the host api specific stream info structure.\r
-\r
- @see PaDeviceIndex\r
-*/\r
-#define paUseHostApiSpecificDeviceSpecification ((PaDeviceIndex)-2)\r
-\r
-\r
-/* Host API enumeration mechanism */\r
-\r
-/** The type used to enumerate to host APIs at runtime. Values of this type\r
- range from 0 to (Pa_GetHostApiCount()-1).\r
-\r
- @see Pa_GetHostApiCount\r
-*/\r
-typedef int PaHostApiIndex;\r
-\r
-\r
-/** Retrieve the number of available host APIs. Even if a host API is\r
- available it may have no devices available.\r
-\r
- @return A non-negative value indicating the number of available host APIs\r
- or, a PaErrorCode (which are always negative) if PortAudio is not initialized\r
- or an error is encountered.\r
-\r
- @see PaHostApiIndex\r
-*/\r
-PaHostApiIndex Pa_GetHostApiCount( void );\r
-\r
-\r
-/** Retrieve the index of the default host API. The default host API will be\r
- the lowest common denominator host API on the current platform and is\r
- unlikely to provide the best performance.\r
-\r
- @return A non-negative value ranging from 0 to (Pa_GetHostApiCount()-1)\r
- indicating the default host API index or, a PaErrorCode (which are always\r
- negative) if PortAudio is not initialized or an error is encountered.\r
-*/\r
-PaHostApiIndex Pa_GetDefaultHostApi( void );\r
-\r
-\r
-/** Unchanging unique identifiers for each supported host API. This type\r
- is used in the PaHostApiInfo structure. The values are guaranteed to be\r
- unique and to never change, thus allowing code to be written that\r
- conditionally uses host API specific extensions.\r
-\r
- New type ids will be allocated when support for a host API reaches\r
- "public alpha" status, prior to that developers should use the\r
- paInDevelopment type id.\r
-\r
- @see PaHostApiInfo\r
-*/\r
-typedef enum PaHostApiTypeId\r
-{\r
- paInDevelopment=0, /* use while developing support for a new host API */\r
- paDirectSound=1,\r
- paMME=2,\r
- paASIO=3,\r
- paSoundManager=4,\r
- paCoreAudio=5,\r
- paOSS=7,\r
- paALSA=8,\r
- paAL=9,\r
- paBeOS=10,\r
- paWDMKS=11,\r
- paJACK=12,\r
- paWASAPI=13,\r
- paAudioScienceHPI=14\r
-} PaHostApiTypeId;\r
-\r
-\r
-/** A structure containing information about a particular host API. */\r
-\r
-typedef struct PaHostApiInfo\r
-{\r
- /** this is struct version 1 */\r
- int structVersion;\r
- /** The well known unique identifier of this host API @see PaHostApiTypeId */\r
- PaHostApiTypeId type;\r
- /** A textual description of the host API for display on user interfaces. */\r
- const char *name;\r
-\r
- /** The number of devices belonging to this host API. This field may be\r
- used in conjunction with Pa_HostApiDeviceIndexToDeviceIndex() to enumerate\r
- all devices for this host API.\r
- @see Pa_HostApiDeviceIndexToDeviceIndex\r
- */\r
- int deviceCount;\r
-\r
- /** The default input device for this host API. The value will be a\r
- device index ranging from 0 to (Pa_GetDeviceCount()-1), or paNoDevice\r
- if no default input device is available.\r
- */\r
- PaDeviceIndex defaultInputDevice;\r
-\r
- /** The default output device for this host API. The value will be a\r
- device index ranging from 0 to (Pa_GetDeviceCount()-1), or paNoDevice\r
- if no default output device is available.\r
- */\r
- PaDeviceIndex defaultOutputDevice;\r
-\r
-} PaHostApiInfo;\r
-\r
-\r
-/** Retrieve a pointer to a structure containing information about a specific\r
- host Api.\r
-\r
- @param hostApi A valid host API index ranging from 0 to (Pa_GetHostApiCount()-1)\r
-\r
- @return A pointer to an immutable PaHostApiInfo structure describing\r
- a specific host API. If the hostApi parameter is out of range or an error\r
- is encountered, the function returns NULL.\r
-\r
- The returned structure is owned by the PortAudio implementation and must not\r
- be manipulated or freed. The pointer is only guaranteed to be valid between\r
- calls to Pa_Initialize() and Pa_Terminate().\r
-*/\r
-const PaHostApiInfo * Pa_GetHostApiInfo( PaHostApiIndex hostApi );\r
-\r
-\r
-/** Convert a static host API unique identifier, into a runtime\r
- host API index.\r
-\r
- @param type A unique host API identifier belonging to the PaHostApiTypeId\r
- enumeration.\r
-\r
- @return A valid PaHostApiIndex ranging from 0 to (Pa_GetHostApiCount()-1) or,\r
- a PaErrorCode (which are always negative) if PortAudio is not initialized\r
- or an error is encountered.\r
-\r
- The paHostApiNotFound error code indicates that the host API specified by the\r
- type parameter is not available.\r
-\r
- @see PaHostApiTypeId\r
-*/\r
-PaHostApiIndex Pa_HostApiTypeIdToHostApiIndex( PaHostApiTypeId type );\r
-\r
-\r
-/** Convert a host-API-specific device index to standard PortAudio device index.\r
- This function may be used in conjunction with the deviceCount field of\r
- PaHostApiInfo to enumerate all devices for the specified host API.\r
-\r
- @param hostApi A valid host API index ranging from 0 to (Pa_GetHostApiCount()-1)\r
-\r
- @param hostApiDeviceIndex A valid per-host device index in the range\r
- 0 to (Pa_GetHostApiInfo(hostApi)->deviceCount-1)\r
-\r
- @return A non-negative PaDeviceIndex ranging from 0 to (Pa_GetDeviceCount()-1)\r
- or, a PaErrorCode (which are always negative) if PortAudio is not initialized\r
- or an error is encountered.\r
-\r
- A paInvalidHostApi error code indicates that the host API index specified by\r
- the hostApi parameter is out of range.\r
-\r
- A paInvalidDevice error code indicates that the hostApiDeviceIndex parameter\r
- is out of range.\r
-\r
- @see PaHostApiInfo\r
-*/\r
-PaDeviceIndex Pa_HostApiDeviceIndexToDeviceIndex( PaHostApiIndex hostApi,\r
- int hostApiDeviceIndex );\r
-\r
-\r
-\r
-/** Structure used to return information about a host error condition.\r
-*/\r
-typedef struct PaHostErrorInfo{\r
- PaHostApiTypeId hostApiType; /**< the host API which returned the error code */\r
- long errorCode; /**< the error code returned */\r
- const char *errorText; /**< a textual description of the error if available, otherwise a zero-length string */\r
-}PaHostErrorInfo;\r
-\r
-\r
-/** Return information about the last host error encountered. The error\r
- information returned by Pa_GetLastHostErrorInfo() will never be modified\r
- asynchronously by errors occurring in other PortAudio owned threads\r
- (such as the thread that manages the stream callback.)\r
-\r
- This function is provided as a last resort, primarily to enhance debugging\r
- by providing clients with access to all available error information.\r
-\r
- @return A pointer to an immutable structure constraining information about\r
- the host error. The values in this structure will only be valid if a\r
- PortAudio function has previously returned the paUnanticipatedHostError\r
- error code.\r
-*/\r
-const PaHostErrorInfo* Pa_GetLastHostErrorInfo( void );\r
-\r
-/* Device enumeration and capabilities */\r
-\r
-/** Retrieve the number of available devices. The number of available devices\r
- may be zero.\r
-\r
- @return A non-negative value indicating the number of available devices or,\r
- a PaErrorCode (which are always negative) if PortAudio is not initialized\r
- or an error is encountered.\r
-*/\r
-PaDeviceIndex Pa_GetDeviceCount( void );\r
-\r
-\r
-/** Retrieve the index of the default input device. The result can be\r
- used in the inputDevice parameter to Pa_OpenStream().\r
-\r
- @return The default input device index for the default host API, or paNoDevice\r
- if no default input device is available or an error was encountered.\r
-*/\r
-PaDeviceIndex Pa_GetDefaultInputDevice( void );\r
-\r
-\r
-/** Retrieve the index of the default output device. The result can be\r
- used in the outputDevice parameter to Pa_OpenStream().\r
-\r
- @return The default output device index for the default host API, or paNoDevice\r
- if no default output device is available or an error was encountered.\r
-\r
- @note\r
- On the PC, the user can specify a default device by\r
- setting an environment variable. For example, to use device #1.\r
-<pre>\r
- set PA_RECOMMENDED_OUTPUT_DEVICE=1\r
-</pre>\r
- The user should first determine the available device ids by using\r
- the supplied application "pa_devs".\r
-*/\r
-PaDeviceIndex Pa_GetDefaultOutputDevice( void );\r
-\r
-\r
-/** The type used to represent monotonic time in seconds. PaTime is\r
- used for the fields of the PaStreamCallbackTimeInfo argument to the\r
- PaStreamCallback and as the result of Pa_GetStreamTime().\r
-\r
- PaTime values have unspecified origin.\r
-\r
- @see PaStreamCallback, PaStreamCallbackTimeInfo, Pa_GetStreamTime\r
-*/\r
-typedef double PaTime;\r
-\r
-\r
-/** A type used to specify one or more sample formats. Each value indicates\r
- a possible format for sound data passed to and from the stream callback,\r
- Pa_ReadStream and Pa_WriteStream.\r
-\r
- The standard formats paFloat32, paInt16, paInt32, paInt24, paInt8\r
- and aUInt8 are usually implemented by all implementations.\r
-\r
- The floating point representation (paFloat32) uses +1.0 and -1.0 as the\r
- maximum and minimum respectively.\r
-\r
- paUInt8 is an unsigned 8 bit format where 128 is considered "ground"\r
-\r
- The paNonInterleaved flag indicates that audio data is passed as an array\r
- of pointers to separate buffers, one buffer for each channel. Usually,\r
- when this flag is not used, audio data is passed as a single buffer with\r
- all channels interleaved.\r
-\r
- @see Pa_OpenStream, Pa_OpenDefaultStream, PaDeviceInfo\r
- @see paFloat32, paInt16, paInt32, paInt24, paInt8\r
- @see paUInt8, paCustomFormat, paNonInterleaved\r
-*/\r
-typedef unsigned long PaSampleFormat;\r
-\r
-\r
-#define paFloat32 ((PaSampleFormat) 0x00000001) /**< @see PaSampleFormat */\r
-#define paInt32 ((PaSampleFormat) 0x00000002) /**< @see PaSampleFormat */\r
-#define paInt24 ((PaSampleFormat) 0x00000004) /**< Packed 24 bit format. @see PaSampleFormat */\r
-#define paInt16 ((PaSampleFormat) 0x00000008) /**< @see PaSampleFormat */\r
-#define paInt8 ((PaSampleFormat) 0x00000010) /**< @see PaSampleFormat */\r
-#define paUInt8 ((PaSampleFormat) 0x00000020) /**< @see PaSampleFormat */\r
-#define paCustomFormat ((PaSampleFormat) 0x00010000) /**< @see PaSampleFormat */\r
-\r
-#define paNonInterleaved ((PaSampleFormat) 0x80000000) /**< @see PaSampleFormat */\r
-\r
-/** A structure providing information and capabilities of PortAudio devices.\r
- Devices may support input, output or both input and output.\r
-*/\r
-typedef struct PaDeviceInfo\r
-{\r
- int structVersion; /* this is struct version 2 */\r
- const char *name;\r
- PaHostApiIndex hostApi; /**< note this is a host API index, not a type id*/\r
-\r
- int maxInputChannels;\r
- int maxOutputChannels;\r
-\r
- /** Default latency values for interactive performance. */\r
- PaTime defaultLowInputLatency;\r
- PaTime defaultLowOutputLatency;\r
- /** Default latency values for robust non-interactive applications (eg. playing sound files). */\r
- PaTime defaultHighInputLatency;\r
- PaTime defaultHighOutputLatency;\r
-\r
- double defaultSampleRate;\r
-} PaDeviceInfo;\r
-\r
-\r
-/** Retrieve a pointer to a PaDeviceInfo structure containing information\r
- about the specified device.\r
- @return A pointer to an immutable PaDeviceInfo structure. If the device\r
- parameter is out of range the function returns NULL.\r
-\r
- @param device A valid device index in the range 0 to (Pa_GetDeviceCount()-1)\r
-\r
- @note PortAudio manages the memory referenced by the returned pointer,\r
- the client must not manipulate or free the memory. The pointer is only\r
- guaranteed to be valid between calls to Pa_Initialize() and Pa_Terminate().\r
-\r
- @see PaDeviceInfo, PaDeviceIndex\r
-*/\r
-const PaDeviceInfo* Pa_GetDeviceInfo( PaDeviceIndex device );\r
-\r
-\r
-/** Parameters for one direction (input or output) of a stream.\r
-*/\r
-typedef struct PaStreamParameters\r
-{\r
- /** A valid device index in the range 0 to (Pa_GetDeviceCount()-1)\r
- specifying the device to be used or the special constant\r
- paUseHostApiSpecificDeviceSpecification which indicates that the actual\r
- device(s) to use are specified in hostApiSpecificStreamInfo.\r
- This field must not be set to paNoDevice.\r
- */\r
- PaDeviceIndex device;\r
-\r
- /** The number of channels of sound to be delivered to the\r
- stream callback or accessed by Pa_ReadStream() or Pa_WriteStream().\r
- It can range from 1 to the value of maxInputChannels in the\r
- PaDeviceInfo record for the device specified by the device parameter.\r
- */\r
- int channelCount;\r
-\r
- /** The sample format of the buffer provided to the stream callback,\r
- a_ReadStream() or Pa_WriteStream(). It may be any of the formats described\r
- by the PaSampleFormat enumeration.\r
- */\r
- PaSampleFormat sampleFormat;\r
-\r
- /** The desired latency in seconds. Where practical, implementations should\r
- configure their latency based on these parameters, otherwise they may\r
- choose the closest viable latency instead. Unless the suggested latency\r
- is greater than the absolute upper limit for the device implementations\r
- should round the suggestedLatency up to the next practical value - ie to\r
- provide an equal or higher latency than suggestedLatency wherever possible.\r
- Actual latency values for an open stream may be retrieved using the\r
- inputLatency and outputLatency fields of the PaStreamInfo structure\r
- returned by Pa_GetStreamInfo().\r
- @see default*Latency in PaDeviceInfo, *Latency in PaStreamInfo\r
- */\r
- PaTime suggestedLatency;\r
-\r
- /** An optional pointer to a host api specific data structure\r
- containing additional information for device setup and/or stream processing.\r
- hostApiSpecificStreamInfo is never required for correct operation,\r
- if not used it should be set to NULL.\r
- */\r
- void *hostApiSpecificStreamInfo;\r
-\r
-} PaStreamParameters;\r
-\r
-\r
-/** Return code for Pa_IsFormatSupported indicating success. */\r
-#define paFormatIsSupported (0)\r
-\r
-/** Determine whether it would be possible to open a stream with the specified\r
- parameters.\r
-\r
- @param inputParameters A structure that describes the input parameters used to\r
- open a stream. The suggestedLatency field is ignored. See PaStreamParameters\r
- for a description of these parameters. inputParameters must be NULL for\r
- output-only streams.\r
-\r
- @param outputParameters A structure that describes the output parameters used\r
- to open a stream. The suggestedLatency field is ignored. See PaStreamParameters\r
- for a description of these parameters. outputParameters must be NULL for\r
- input-only streams.\r
-\r
- @param sampleRate The required sampleRate. For full-duplex streams it is the\r
- sample rate for both input and output\r
-\r
- @return Returns 0 if the format is supported, and an error code indicating why\r
- the format is not supported otherwise. The constant paFormatIsSupported is\r
- provided to compare with the return value for success.\r
-\r
- @see paFormatIsSupported, PaStreamParameters\r
-*/\r
-PaError Pa_IsFormatSupported( const PaStreamParameters *inputParameters,\r
- const PaStreamParameters *outputParameters,\r
- double sampleRate );\r
-\r
-\r
-\r
-/* Streaming types and functions */\r
-\r
-\r
-/**\r
- A single PaStream can provide multiple channels of real-time\r
- streaming audio input and output to a client application. A stream\r
- provides access to audio hardware represented by one or more\r
- PaDevices. Depending on the underlying Host API, it may be possible\r
- to open multiple streams using the same device, however this behavior\r
- is implementation defined. Portable applications should assume that\r
- a PaDevice may be simultaneously used by at most one PaStream.\r
-\r
- Pointers to PaStream objects are passed between PortAudio functions that\r
- operate on streams.\r
-\r
- @see Pa_OpenStream, Pa_OpenDefaultStream, Pa_OpenDefaultStream, Pa_CloseStream,\r
- Pa_StartStream, Pa_StopStream, Pa_AbortStream, Pa_IsStreamActive,\r
- Pa_GetStreamTime, Pa_GetStreamCpuLoad\r
-\r
-*/\r
-typedef void PaStream;\r
-\r
-\r
-/** Can be passed as the framesPerBuffer parameter to Pa_OpenStream()\r
- or Pa_OpenDefaultStream() to indicate that the stream callback will\r
- accept buffers of any size.\r
-*/\r
-#define paFramesPerBufferUnspecified (0)\r
-\r
-\r
-/** Flags used to control the behavior of a stream. They are passed as\r
- parameters to Pa_OpenStream or Pa_OpenDefaultStream. Multiple flags may be\r
- ORed together.\r
-\r
- @see Pa_OpenStream, Pa_OpenDefaultStream\r
- @see paNoFlag, paClipOff, paDitherOff, paNeverDropInput,\r
- paPrimeOutputBuffersUsingStreamCallback, paPlatformSpecificFlags\r
-*/\r
-typedef unsigned long PaStreamFlags;\r
-\r
-/** @see PaStreamFlags */\r
-#define paNoFlag ((PaStreamFlags) 0)\r
-\r
-/** Disable default clipping of out of range samples.\r
- @see PaStreamFlags\r
-*/\r
-#define paClipOff ((PaStreamFlags) 0x00000001)\r
-\r
-/** Disable default dithering.\r
- @see PaStreamFlags\r
-*/\r
-#define paDitherOff ((PaStreamFlags) 0x00000002)\r
-\r
-/** Flag requests that where possible a full duplex stream will not discard\r
- overflowed input samples without calling the stream callback. This flag is\r
- only valid for full duplex callback streams and only when used in combination\r
- with the paFramesPerBufferUnspecified (0) framesPerBuffer parameter. Using\r
- this flag incorrectly results in a paInvalidFlag error being returned from\r
- Pa_OpenStream and Pa_OpenDefaultStream.\r
-\r
- @see PaStreamFlags, paFramesPerBufferUnspecified\r
-*/\r
-#define paNeverDropInput ((PaStreamFlags) 0x00000004)\r
-\r
-/** Call the stream callback to fill initial output buffers, rather than the\r
- default behavior of priming the buffers with zeros (silence). This flag has\r
- no effect for input-only and blocking read/write streams.\r
-\r
- @see PaStreamFlags\r
-*/\r
-#define paPrimeOutputBuffersUsingStreamCallback ((PaStreamFlags) 0x00000008)\r
-\r
-/** A mask specifying the platform specific bits.\r
- @see PaStreamFlags\r
-*/\r
-#define paPlatformSpecificFlags ((PaStreamFlags)0xFFFF0000)\r
-\r
-/**\r
- Timing information for the buffers passed to the stream callback.\r
-\r
- Time values are expressed in seconds and are synchronised with the time base used by Pa_GetStreamTime() for the associated stream.\r
-\r
- @see PaStreamCallback, Pa_GetStreamTime\r
-*/\r
-typedef struct PaStreamCallbackTimeInfo{\r
- PaTime inputBufferAdcTime; /**< The time when the first sample of the input buffer was captured at the ADC input */\r
- PaTime currentTime; /**< The time when the stream callback was invoked */\r
- PaTime outputBufferDacTime; /**< The time when the first sample of the output buffer will output the DAC */\r
-} PaStreamCallbackTimeInfo;\r
-\r
-\r
-/**\r
- Flag bit constants for the statusFlags to PaStreamCallback.\r
-\r
- @see paInputUnderflow, paInputOverflow, paOutputUnderflow, paOutputOverflow,\r
- paPrimingOutput\r
-*/\r
-typedef unsigned long PaStreamCallbackFlags;\r
-\r
-/** In a stream opened with paFramesPerBufferUnspecified, indicates that\r
- input data is all silence (zeros) because no real data is available. In a\r
- stream opened without paFramesPerBufferUnspecified, it indicates that one or\r
- more zero samples have been inserted into the input buffer to compensate\r
- for an input underflow.\r
- @see PaStreamCallbackFlags\r
-*/\r
-#define paInputUnderflow ((PaStreamCallbackFlags) 0x00000001)\r
-\r
-/** In a stream opened with paFramesPerBufferUnspecified, indicates that data\r
- prior to the first sample of the input buffer was discarded due to an\r
- overflow, possibly because the stream callback is using too much CPU time.\r
- Otherwise indicates that data prior to one or more samples in the\r
- input buffer was discarded.\r
- @see PaStreamCallbackFlags\r
-*/\r
-#define paInputOverflow ((PaStreamCallbackFlags) 0x00000002)\r
-\r
-/** Indicates that output data (or a gap) was inserted, possibly because the\r
- stream callback is using too much CPU time.\r
- @see PaStreamCallbackFlags\r
-*/\r
-#define paOutputUnderflow ((PaStreamCallbackFlags) 0x00000004)\r
-\r
-/** Indicates that output data will be discarded because no room is available.\r
- @see PaStreamCallbackFlags\r
-*/\r
-#define paOutputOverflow ((PaStreamCallbackFlags) 0x00000008)\r
-\r
-/** Some of all of the output data will be used to prime the stream, input\r
- data may be zero.\r
- @see PaStreamCallbackFlags\r
-*/\r
-#define paPrimingOutput ((PaStreamCallbackFlags) 0x00000010)\r
-\r
-/**\r
- Allowable return values for the PaStreamCallback.\r
- @see PaStreamCallback\r
-*/\r
-typedef enum PaStreamCallbackResult\r
-{\r
- paContinue=0, /**< Signal that the stream should continue invoking the callback and processing audio. */\r
- paComplete=1, /**< Signal that the stream should stop invoking the callback and finish once all output samples have played. */\r
- paAbort=2 /**< Signal that the stream should stop invoking the callback and finish as soon as possible. */\r
-} PaStreamCallbackResult;\r
-\r
-\r
-/**\r
- Functions of type PaStreamCallback are implemented by PortAudio clients.\r
- They consume, process or generate audio in response to requests from an\r
- active PortAudio stream.\r
-\r
- When a stream is running, PortAudio calls the stream callback periodically.\r
- The callback function is responsible for processing buffers of audio samples\r
- passed via the input and output parameters.\r
-\r
- The PortAudio stream callback runs at very high or real-time priority.\r
- It is required to consistently meet its time deadlines. Do not allocate\r
- memory, access the file system, call library functions or call other functions\r
- from the stream callback that may block or take an unpredictable amount of\r
- time to complete.\r
-\r
- In order for a stream to maintain glitch-free operation the callback\r
- must consume and return audio data faster than it is recorded and/or\r
- played. PortAudio anticipates that each callback invocation may execute for\r
- a duration approaching the duration of frameCount audio frames at the stream\r
- sample rate. It is reasonable to expect to be able to utilise 70% or more of\r
- the available CPU time in the PortAudio callback. However, due to buffer size\r
- adaption and other factors, not all host APIs are able to guarantee audio\r
- stability under heavy CPU load with arbitrary fixed callback buffer sizes.\r
- When high callback CPU utilisation is required the most robust behavior\r
- can be achieved by using paFramesPerBufferUnspecified as the\r
- Pa_OpenStream() framesPerBuffer parameter.\r
-\r
- @param input and @param output are either arrays of interleaved samples or;\r
- if non-interleaved samples were requested using the paNonInterleaved sample\r
- format flag, an array of buffer pointers, one non-interleaved buffer for\r
- each channel.\r
-\r
- The format, packing and number of channels used by the buffers are\r
- determined by parameters to Pa_OpenStream().\r
-\r
- @param frameCount The number of sample frames to be processed by\r
- the stream callback.\r
-\r
- @param timeInfo Timestamps indicating the ADC capture time of the first sample\r
- in the input buffer, the DAC output time of the first sample in the output buffer\r
- and the time the callback was invoked.\r
- See PaStreamCallbackTimeInfo and Pa_GetStreamTime()\r
-\r
- @param statusFlags Flags indicating whether input and/or output buffers\r
- have been inserted or will be dropped to overcome underflow or overflow\r
- conditions.\r
-\r
- @param userData The value of a user supplied pointer passed to\r
- Pa_OpenStream() intended for storing synthesis data etc.\r
-\r
- @return\r
- The stream callback should return one of the values in the\r
- ::PaStreamCallbackResult enumeration. To ensure that the callback continues\r
- to be called, it should return paContinue (0). Either paComplete or paAbort\r
- can be returned to finish stream processing, after either of these values is\r
- returned the callback will not be called again. If paAbort is returned the\r
- stream will finish as soon as possible. If paComplete is returned, the stream\r
- will continue until all buffers generated by the callback have been played.\r
- This may be useful in applications such as soundfile players where a specific\r
- duration of output is required. However, it is not necessary to utilize this\r
- mechanism as Pa_StopStream(), Pa_AbortStream() or Pa_CloseStream() can also\r
- be used to stop the stream. The callback must always fill the entire output\r
- buffer irrespective of its return value.\r
-\r
- @see Pa_OpenStream, Pa_OpenDefaultStream\r
-\r
- @note With the exception of Pa_GetStreamCpuLoad() it is not permissible to call\r
- PortAudio API functions from within the stream callback.\r
-*/\r
-typedef int PaStreamCallback(\r
- const void *input, void *output,\r
- unsigned long frameCount,\r
- const PaStreamCallbackTimeInfo* timeInfo,\r
- PaStreamCallbackFlags statusFlags,\r
- void *userData );\r
-\r
-\r
-/** Opens a stream for either input, output or both.\r
-\r
- @param stream The address of a PaStream pointer which will receive\r
- a pointer to the newly opened stream.\r
-\r
- @param inputParameters A structure that describes the input parameters used by\r
- the opened stream. See PaStreamParameters for a description of these parameters.\r
- inputParameters must be NULL for output-only streams.\r
-\r
- @param outputParameters A structure that describes the output parameters used by\r
- the opened stream. See PaStreamParameters for a description of these parameters.\r
- outputParameters must be NULL for input-only streams.\r
-\r
- @param sampleRate The desired sampleRate. For full-duplex streams it is the\r
- sample rate for both input and output\r
-\r
- @param framesPerBuffer The number of frames passed to the stream callback\r
- function, or the preferred block granularity for a blocking read/write stream.\r
- The special value paFramesPerBufferUnspecified (0) may be used to request that\r
- the stream callback will receive an optimal (and possibly varying) number of\r
- frames based on host requirements and the requested latency settings.\r
- Note: With some host APIs, the use of non-zero framesPerBuffer for a callback\r
- stream may introduce an additional layer of buffering which could introduce\r
- additional latency. PortAudio guarantees that the additional latency\r
- will be kept to the theoretical minimum however, it is strongly recommended\r
- that a non-zero framesPerBuffer value only be used when your algorithm\r
- requires a fixed number of frames per stream callback.\r
-\r
- @param streamFlags Flags which modify the behavior of the streaming process.\r
- This parameter may contain a combination of flags ORed together. Some flags may\r
- only be relevant to certain buffer formats.\r
-\r
- @param streamCallback A pointer to a client supplied function that is responsible\r
- for processing and filling input and output buffers. If this parameter is NULL\r
- the stream will be opened in 'blocking read/write' mode. In blocking mode,\r
- the client can receive sample data using Pa_ReadStream and write sample data\r
- using Pa_WriteStream, the number of samples that may be read or written\r
- without blocking is returned by Pa_GetStreamReadAvailable and\r
- Pa_GetStreamWriteAvailable respectively.\r
-\r
- @param userData A client supplied pointer which is passed to the stream callback\r
- function. It could for example, contain a pointer to instance data necessary\r
- for processing the audio buffers. This parameter is ignored if streamCallback\r
- is NULL.\r
-\r
- @return\r
- Upon success Pa_OpenStream() returns paNoError and places a pointer to a\r
- valid PaStream in the stream argument. The stream is inactive (stopped).\r
- If a call to Pa_OpenStream() fails, a non-zero error code is returned (see\r
- PaError for possible error codes) and the value of stream is invalid.\r
-\r
- @see PaStreamParameters, PaStreamCallback, Pa_ReadStream, Pa_WriteStream,\r
- Pa_GetStreamReadAvailable, Pa_GetStreamWriteAvailable\r
-*/\r
-PaError Pa_OpenStream( PaStream** stream,\r
- const PaStreamParameters *inputParameters,\r
- const PaStreamParameters *outputParameters,\r
- double sampleRate,\r
- unsigned long framesPerBuffer,\r
- PaStreamFlags streamFlags,\r
- PaStreamCallback *streamCallback,\r
- void *userData );\r
-\r
-\r
-/** A simplified version of Pa_OpenStream() that opens the default input\r
- and/or output devices.\r
-\r
- @param stream The address of a PaStream pointer which will receive\r
- a pointer to the newly opened stream.\r
-\r
- @param numInputChannels The number of channels of sound that will be supplied\r
- to the stream callback or returned by Pa_ReadStream. It can range from 1 to\r
- the value of maxInputChannels in the PaDeviceInfo record for the default input\r
- device. If 0 the stream is opened as an output-only stream.\r
-\r
- @param numOutputChannels The number of channels of sound to be delivered to the\r
- stream callback or passed to Pa_WriteStream. It can range from 1 to the value\r
- of maxOutputChannels in the PaDeviceInfo record for the default output device.\r
- If 0 the stream is opened as an output-only stream.\r
-\r
- @param sampleFormat The sample format of both the input and output buffers\r
- provided to the callback or passed to and from Pa_ReadStream and Pa_WriteStream.\r
- sampleFormat may be any of the formats described by the PaSampleFormat\r
- enumeration.\r
-\r
- @param sampleRate Same as Pa_OpenStream parameter of the same name.\r
- @param framesPerBuffer Same as Pa_OpenStream parameter of the same name.\r
- @param streamCallback Same as Pa_OpenStream parameter of the same name.\r
- @param userData Same as Pa_OpenStream parameter of the same name.\r
-\r
- @return As for Pa_OpenStream\r
-\r
- @see Pa_OpenStream, PaStreamCallback\r
-*/\r
-PaError Pa_OpenDefaultStream( PaStream** stream,\r
- int numInputChannels,\r
- int numOutputChannels,\r
- PaSampleFormat sampleFormat,\r
- double sampleRate,\r
- unsigned long framesPerBuffer,\r
- PaStreamCallback *streamCallback,\r
- void *userData );\r
-\r
-\r
-/** Closes an audio stream. If the audio stream is active it\r
- discards any pending buffers as if Pa_AbortStream() had been called.\r
-*/\r
-PaError Pa_CloseStream( PaStream *stream );\r
-\r
-\r
-/** Functions of type PaStreamFinishedCallback are implemented by PortAudio\r
- clients. They can be registered with a stream using the Pa_SetStreamFinishedCallback\r
- function. Once registered they are called when the stream becomes inactive\r
- (ie once a call to Pa_StopStream() will not block).\r
- A stream will become inactive after the stream callback returns non-zero,\r
- or when Pa_StopStream or Pa_AbortStream is called. For a stream providing audio\r
- output, if the stream callback returns paComplete, or Pa_StopStream is called,\r
- the stream finished callback will not be called until all generated sample data\r
- has been played.\r
-\r
- @param userData The userData parameter supplied to Pa_OpenStream()\r
-\r
- @see Pa_SetStreamFinishedCallback\r
-*/\r
-typedef void PaStreamFinishedCallback( void *userData );\r
-\r
-\r
-/** Register a stream finished callback function which will be called when the\r
- stream becomes inactive. See the description of PaStreamFinishedCallback for\r
- further details about when the callback will be called.\r
-\r
- @param stream a pointer to a PaStream that is in the stopped state - if the\r
- stream is not stopped, the stream's finished callback will remain unchanged\r
- and an error code will be returned.\r
-\r
- @param streamFinishedCallback a pointer to a function with the same signature\r
- as PaStreamFinishedCallback, that will be called when the stream becomes\r
- inactive. Passing NULL for this parameter will un-register a previously\r
- registered stream finished callback function.\r
-\r
- @return on success returns paNoError, otherwise an error code indicating the cause\r
- of the error.\r
-\r
- @see PaStreamFinishedCallback\r
-*/\r
-PaError Pa_SetStreamFinishedCallback( PaStream *stream, PaStreamFinishedCallback* streamFinishedCallback );\r
-\r
-\r
-/** Commences audio processing.\r
-*/\r
-PaError Pa_StartStream( PaStream *stream );\r
-\r
-\r
-/** Terminates audio processing. It waits until all pending\r
- audio buffers have been played before it returns.\r
-*/\r
-PaError Pa_StopStream( PaStream *stream );\r
-\r
-\r
-/** Terminates audio processing immediately without waiting for pending\r
- buffers to complete.\r
-*/\r
-PaError Pa_AbortStream( PaStream *stream );\r
-\r
-\r
-/** Determine whether the stream is stopped.\r
- A stream is considered to be stopped prior to a successful call to\r
- Pa_StartStream and after a successful call to Pa_StopStream or Pa_AbortStream.\r
- If a stream callback returns a value other than paContinue the stream is NOT\r
- considered to be stopped.\r
-\r
- @return Returns one (1) when the stream is stopped, zero (0) when\r
- the stream is running or, a PaErrorCode (which are always negative) if\r
- PortAudio is not initialized or an error is encountered.\r
-\r
- @see Pa_StopStream, Pa_AbortStream, Pa_IsStreamActive\r
-*/\r
-PaError Pa_IsStreamStopped( PaStream *stream );\r
-\r
-\r
-/** Determine whether the stream is active.\r
- A stream is active after a successful call to Pa_StartStream(), until it\r
- becomes inactive either as a result of a call to Pa_StopStream() or\r
- Pa_AbortStream(), or as a result of a return value other than paContinue from\r
- the stream callback. In the latter case, the stream is considered inactive\r
- after the last buffer has finished playing.\r
-\r
- @return Returns one (1) when the stream is active (ie playing or recording\r
- audio), zero (0) when not playing or, a PaErrorCode (which are always negative)\r
- if PortAudio is not initialized or an error is encountered.\r
-\r
- @see Pa_StopStream, Pa_AbortStream, Pa_IsStreamStopped\r
-*/\r
-PaError Pa_IsStreamActive( PaStream *stream );\r
-\r
-\r
-\r
-/** A structure containing unchanging information about an open stream.\r
- @see Pa_GetStreamInfo\r
-*/\r
-\r
-typedef struct PaStreamInfo\r
-{\r
- /** this is struct version 1 */\r
- int structVersion;\r
-\r
- /** The input latency of the stream in seconds. This value provides the most\r
- accurate estimate of input latency available to the implementation. It may\r
- differ significantly from the suggestedLatency value passed to Pa_OpenStream().\r
- The value of this field will be zero (0.) for output-only streams.\r
- @see PaTime\r
- */\r
- PaTime inputLatency;\r
-\r
- /** The output latency of the stream in seconds. This value provides the most\r
- accurate estimate of output latency available to the implementation. It may\r
- differ significantly from the suggestedLatency value passed to Pa_OpenStream().\r
- The value of this field will be zero (0.) for input-only streams.\r
- @see PaTime\r
- */\r
- PaTime outputLatency;\r
-\r
- /** The sample rate of the stream in Hertz (samples per second). In cases\r
- where the hardware sample rate is inaccurate and PortAudio is aware of it,\r
- the value of this field may be different from the sampleRate parameter\r
- passed to Pa_OpenStream(). If information about the actual hardware sample\r
- rate is not available, this field will have the same value as the sampleRate\r
- parameter passed to Pa_OpenStream().\r
- */\r
- double sampleRate;\r
-\r
-} PaStreamInfo;\r
-\r
-\r
-/** Retrieve a pointer to a PaStreamInfo structure containing information\r
- about the specified stream.\r
- @return A pointer to an immutable PaStreamInfo structure. If the stream\r
- parameter invalid, or an error is encountered, the function returns NULL.\r
-\r
- @param stream A pointer to an open stream previously created with Pa_OpenStream.\r
-\r
- @note PortAudio manages the memory referenced by the returned pointer,\r
- the client must not manipulate or free the memory. The pointer is only\r
- guaranteed to be valid until the specified stream is closed.\r
-\r
- @see PaStreamInfo\r
-*/\r
-const PaStreamInfo* Pa_GetStreamInfo( PaStream *stream );\r
-\r
-\r
-/** Returns the current time in seconds for a stream according to the same clock used\r
- to generate callback PaStreamCallbackTimeInfo timestamps. The time values are\r
- monotonically increasing and have unspecified origin.\r
-\r
- Pa_GetStreamTime returns valid time values for the entire life of the stream,\r
- from when the stream is opened until it is closed. Starting and stopping the stream\r
- does not affect the passage of time returned by Pa_GetStreamTime.\r
-\r
- This time may be used for synchronizing other events to the audio stream, for\r
- example synchronizing audio to MIDI.\r
-\r
- @return The stream's current time in seconds, or 0 if an error occurred.\r
-\r
- @see PaTime, PaStreamCallback, PaStreamCallbackTimeInfo\r
-*/\r
-PaTime Pa_GetStreamTime( PaStream *stream );\r
-\r
-\r
-/** Retrieve CPU usage information for the specified stream.\r
- The "CPU Load" is a fraction of total CPU time consumed by a callback stream's\r
- audio processing routines including, but not limited to the client supplied\r
- stream callback. This function does not work with blocking read/write streams.\r
-\r
- This function may be called from the stream callback function or the\r
- application.\r
-\r
- @return\r
- A floating point value, typically between 0.0 and 1.0, where 1.0 indicates\r
- that the stream callback is consuming the maximum number of CPU cycles possible\r
- to maintain real-time operation. A value of 0.5 would imply that PortAudio and\r
- the stream callback was consuming roughly 50% of the available CPU time. The\r
- return value may exceed 1.0. A value of 0.0 will always be returned for a\r
- blocking read/write stream, or if an error occurs.\r
-*/\r
-double Pa_GetStreamCpuLoad( PaStream* stream );\r
-\r
-\r
-/** Read samples from an input stream. The function doesn't return until\r
- the entire buffer has been filled - this may involve waiting for the operating\r
- system to supply the data.\r
-\r
- @param stream A pointer to an open stream previously created with Pa_OpenStream.\r
-\r
- @param buffer A pointer to a buffer of sample frames. The buffer contains\r
- samples in the format specified by the inputParameters->sampleFormat field\r
- used to open the stream, and the number of channels specified by\r
- inputParameters->numChannels. If non-interleaved samples were requested using\r
- the paNonInterleaved sample format flag, buffer is a pointer to the first element\r
- of an array of buffer pointers, one non-interleaved buffer for each channel.\r
-\r
- @param frames The number of frames to be read into buffer. This parameter\r
- is not constrained to a specific range, however high performance applications\r
- will want to match this parameter to the framesPerBuffer parameter used\r
- when opening the stream.\r
-\r
- @return On success PaNoError will be returned, or PaInputOverflowed if input\r
- data was discarded by PortAudio after the previous call and before this call.\r
-*/\r
-PaError Pa_ReadStream( PaStream* stream,\r
- void *buffer,\r
- unsigned long frames );\r
-\r
-\r
-/** Write samples to an output stream. This function doesn't return until the\r
- entire buffer has been consumed - this may involve waiting for the operating\r
- system to consume the data.\r
-\r
- @param stream A pointer to an open stream previously created with Pa_OpenStream.\r
-\r
- @param buffer A pointer to a buffer of sample frames. The buffer contains\r
- samples in the format specified by the outputParameters->sampleFormat field\r
- used to open the stream, and the number of channels specified by\r
- outputParameters->numChannels. If non-interleaved samples were requested using\r
- the paNonInterleaved sample format flag, buffer is a pointer to the first element\r
- of an array of buffer pointers, one non-interleaved buffer for each channel.\r
-\r
- @param frames The number of frames to be written from buffer. This parameter\r
- is not constrained to a specific range, however high performance applications\r
- will want to match this parameter to the framesPerBuffer parameter used\r
- when opening the stream.\r
-\r
- @return On success PaNoError will be returned, or paOutputUnderflowed if\r
- additional output data was inserted after the previous call and before this\r
- call.\r
-*/\r
-PaError Pa_WriteStream( PaStream* stream,\r
- const void *buffer,\r
- unsigned long frames );\r
-\r
-\r
-/** Retrieve the number of frames that can be read from the stream without\r
- waiting.\r
-\r
- @return Returns a non-negative value representing the maximum number of frames\r
- that can be read from the stream without blocking or busy waiting or, a\r
- PaErrorCode (which are always negative) if PortAudio is not initialized or an\r
- error is encountered.\r
-*/\r
-signed long Pa_GetStreamReadAvailable( PaStream* stream );\r
-\r
-\r
-/** Retrieve the number of frames that can be written to the stream without\r
- waiting.\r
-\r
- @return Returns a non-negative value representing the maximum number of frames\r
- that can be written to the stream without blocking or busy waiting or, a\r
- PaErrorCode (which are always negative) if PortAudio is not initialized or an\r
- error is encountered.\r
-*/\r
-signed long Pa_GetStreamWriteAvailable( PaStream* stream );\r
-\r
-\r
-/* Miscellaneous utilities */\r
-\r
-\r
-/** Retrieve the size of a given sample format in bytes.\r
-\r
- @return The size in bytes of a single sample in the specified format,\r
- or paSampleFormatNotSupported if the format is not supported.\r
-*/\r
-PaError Pa_GetSampleSize( PaSampleFormat format );\r
-\r
-\r
-/** Put the caller to sleep for at least 'msec' milliseconds. This function is\r
- provided only as a convenience for authors of portable code (such as the tests\r
- and examples in the PortAudio distribution.)\r
-\r
- The function may sleep longer than requested so don't rely on this for accurate\r
- musical timing.\r
-*/\r
-void Pa_Sleep( long msec );\r
-\r
-\r
-\r
-#ifdef __cplusplus\r
-}\r
-#endif /* __cplusplus */\r
-#endif /* PORTAUDIO_H */\r
projects / freetel-svn-tracking.git / commitdiff