diff --git a/include/portaudio.h b/include/portaudio.h index 641863e47..b8878cc46 100644 --- a/include/portaudio.h +++ b/include/portaudio.h @@ -165,13 +165,13 @@ const char *Pa_GetErrorText( PaError errorCode ); /** Library initialization function - call this before using PortAudio. This function initializes internal data structures and prepares underlying - host APIs for use. With the exception of Pa_GetVersion(), Pa_GetVersionText(), + host APIs for use. With the exception of Pa_GetVersion(), Pa_GetVersionText(), and Pa_GetErrorText(), this function MUST be called before using any other PortAudio API functions. If Pa_Initialize() is called multiple times, each successful call must be matched with a corresponding call to Pa_Terminate(). - Pairs of calls to Pa_Initialize()/Pa_Terminate() may overlap, and are not + Pairs of calls to Pa_Initialize() / Pa_Terminate() may overlap, and are not required to be fully nested. Note that if Pa_Initialize() returns an error code, Pa_Terminate() should @@ -187,7 +187,7 @@ PaError Pa_Initialize( void ); /** Library termination function - call this when finished using PortAudio. This function deallocates all resources allocated by PortAudio since it was - initialized by a call to Pa_Initialize(). In cases where Pa_Initialise() has + initialized by a call to Pa_Initialize(). In cases where Pa_Initialize() has been called multiple times, each call must be matched with a corresponding call to Pa_Terminate(). The final matching call to Pa_Terminate() will automatically close any PortAudio streams that are still open. @@ -467,10 +467,10 @@ typedef double PaTime; /** A type used to specify one or more sample formats. Each value indicates a possible format for sound data passed to and from the stream callback, - Pa_ReadStream and Pa_WriteStream. + Pa_ReadStream() and Pa_WriteStream(). The standard formats paFloat32, paInt16, paInt32, paInt24, paInt8 - and aUInt8 are usually implemented by all implementations. + and paUInt8 are usually implemented by all implementations. The floating point representation (paFloat32) uses +1.0 and -1.0 as the maximum and minimum respectively. @@ -562,7 +562,7 @@ typedef struct PaStreamParameters int channelCount; /** The sample format of the buffer provided to the stream callback, - a_ReadStream() or Pa_WriteStream(). It may be any of the formats described + Pa_ReadStream() or Pa_WriteStream(). It may be any of the formats described by the PaSampleFormat enumeration. */ PaSampleFormat sampleFormat; @@ -590,7 +590,7 @@ typedef struct PaStreamParameters } PaStreamParameters; -/** Return code for Pa_IsFormatSupported indicating success. */ +/** Return code for Pa_IsFormatSupported() indicating success. */ #define paFormatIsSupported (0) /** Determine whether it would be possible to open a stream with the specified @@ -607,7 +607,7 @@ typedef struct PaStreamParameters input-only streams. @param sampleRate The required sampleRate. For full-duplex streams it is the - sample rate for both input and output + sample rate for both input and output. @return Returns 0 if the format is supported, and an error code indicating why the format is not supported otherwise. The constant paFormatIsSupported is @@ -652,7 +652,7 @@ typedef void PaStream; /** Flags used to control the behavior of a stream. They are passed as - parameters to Pa_OpenStream or Pa_OpenDefaultStream. Multiple flags may be + parameters to Pa_OpenStream() or Pa_OpenDefaultStream(). Multiple flags may be ORed together. @see Pa_OpenStream, Pa_OpenDefaultStream @@ -679,7 +679,7 @@ typedef unsigned long PaStreamFlags; only valid for full duplex callback streams and only when used in combination with the paFramesPerBufferUnspecified (0) framesPerBuffer parameter. Using this flag incorrectly results in a paInvalidFlag error being returned from - Pa_OpenStream and Pa_OpenDefaultStream. + Pa_OpenStream() and Pa_OpenDefaultStream(). @see PaStreamFlags, paFramesPerBufferUnspecified */ @@ -882,10 +882,10 @@ typedef int PaStreamCallback( @param streamCallback A pointer to a client supplied function that is responsible for processing and filling input and output buffers. If this parameter is NULL the stream will be opened in 'blocking read/write' mode. In blocking mode, - the client can receive sample data using Pa_ReadStream and write sample data - using Pa_WriteStream, the number of samples that may be read or written - without blocking is returned by Pa_GetStreamReadAvailable and - Pa_GetStreamWriteAvailable respectively. + the client can receive sample data using Pa_ReadStream() and write sample data + using Pa_WriteStream(), the number of samples that may be read or written + without blocking is returned by Pa_GetStreamReadAvailable() and + Pa_GetStreamWriteAvailable() respectively. @param userData A client supplied pointer which is passed to the stream callback function. It could for example, contain a pointer to instance data necessary @@ -918,7 +918,7 @@ PaError Pa_OpenStream( PaStream** stream, a pointer to the newly opened stream. @param numInputChannels The number of channels of sound that will be supplied - to the stream callback or returned by Pa_ReadStream. It can range from 1 to + to the stream callback or returned by Pa_ReadStream(). It can range from 1 to the value of maxInputChannels in the PaDeviceInfo record for the default input device. If 0 the stream is opened as an output-only stream. @@ -928,7 +928,7 @@ PaError Pa_OpenStream( PaStream** stream, If 0 the stream is opened as an input-only stream. @param sampleFormat The sample format of both the input and output buffers - provided to the callback or passed to and from Pa_ReadStream and Pa_WriteStream. + provided to the callback or passed to and from Pa_ReadStream() and Pa_WriteStream(). sampleFormat may be any of the formats described by the PaSampleFormat enumeration. @@ -958,11 +958,11 @@ PaError Pa_CloseStream( PaStream *stream ); /** Functions of type PaStreamFinishedCallback are implemented by PortAudio - clients. They can be registered with a stream using the Pa_SetStreamFinishedCallback + clients. They can be registered with a stream using the Pa_SetStreamFinishedCallback() function. Once registered they are called when the stream becomes inactive (ie once a call to Pa_StopStream() will not block). A stream will become inactive after the stream callback returns non-zero, - or when Pa_StopStream or Pa_AbortStream is called. For a stream providing audio + or when Pa_StopStream() or Pa_AbortStream() is called. For a stream providing audio output, if the stream callback returns paComplete, or Pa_StopStream() is called, the stream finished callback will not be called until all generated sample data has been played. @@ -1014,7 +1014,7 @@ PaError Pa_AbortStream( PaStream *stream ); /** Determine whether the stream is stopped. A stream is considered to be stopped prior to a successful call to - Pa_StartStream and after a successful call to Pa_StopStream or Pa_AbortStream. + Pa_StartStream() and after a successful call to Pa_StopStream() or Pa_AbortStream(). If a stream callback returns a value other than paContinue the stream is NOT considered to be stopped. @@ -1086,7 +1086,7 @@ typedef struct PaStreamInfo @return A pointer to an immutable PaStreamInfo structure. If the stream parameter is invalid, or an error is encountered, the function returns NULL. - @param stream A pointer to an open stream previously created with Pa_OpenStream. + @param stream A pointer to an open stream previously created with Pa_OpenStream(). @note PortAudio manages the memory referenced by the returned pointer, the client must not manipulate or free the memory. The pointer is only @@ -1140,9 +1140,9 @@ double Pa_GetStreamCpuLoad( PaStream* stream ); Reading from a stream that is stopped is not currently supported. In particular, it is not possible to drain the read buffer by calling Pa_ReadStream after - calling Pa_StopStream. + calling Pa_StopStream(). - @param stream A pointer to an open stream previously created with Pa_OpenStream. + @param stream A pointer to an open stream previously created with Pa_OpenStream(). @param buffer A pointer to a buffer of sample frames. The buffer contains samples in the format specified by the inputParameters->sampleFormat field @@ -1170,9 +1170,9 @@ PaError Pa_ReadStream( PaStream* stream, Writing to a stream that is stopped is not currently supported. In particular, it is not possible to prefill the write buffer by calling Pa_WriteStream - prior to calling Pa_StartStream. + prior to calling Pa_StartStream(). - @param stream A pointer to an open stream previously created with Pa_OpenStream. + @param stream A pointer to an open stream previously created with Pa_OpenStream(). @param buffer A pointer to a buffer of sample frames. The buffer contains samples in the format specified by the outputParameters->sampleFormat field