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