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