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