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