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