From 9faca9b95bd93dd626839e4f3261e68c620f36a5 Mon Sep 17 00:00:00 2001 From: Ross Bencina Date: Thu, 20 May 2021 12:06:14 +1000 Subject: [PATCH] Add documentation indicating that Pa_ReadStream, Pa_WriteStream, Pa_GetStreamReadAvailable and Pa_GetStreamWriteAvailable are only valid while the stream is running (between calls to Pa_StartStream and Pa_StopStream.) --- include/portaudio.h | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/include/portaudio.h b/include/portaudio.h index 5d84731..c3e1744 100644 --- a/include/portaudio.h +++ b/include/portaudio.h @@ -1129,6 +1129,10 @@ double Pa_GetStreamCpuLoad( PaStream* stream ); the entire buffer has been filled - this may involve waiting for the operating system to supply the data. + 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. + @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 @@ -1155,6 +1159,10 @@ PaError Pa_ReadStream( PaStream* stream, entire buffer has been written - this may involve waiting for the operating system to consume the data. + 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. + @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 @@ -1181,6 +1189,9 @@ PaError Pa_WriteStream( PaStream* stream, /** Retrieve the number of frames that can be read from the stream without waiting. + When the stream is stopped the return value of Pa_GetStreamReadAvailable is not + defined. + @return Returns a non-negative value representing the maximum number of frames that can be read from the stream without blocking or busy waiting or, a PaErrorCode (which are always negative) if PortAudio is not initialized or an @@ -1192,6 +1203,9 @@ signed long Pa_GetStreamReadAvailable( PaStream* stream ); /** Retrieve the number of frames that can be written to the stream without waiting. + When the stream is stopped the return value of Pa_GetStreamWriteAvailable is not + defined. + @return Returns a non-negative value representing the maximum number of frames that can be written to the stream without blocking or busy waiting or, a PaErrorCode (which are always negative) if PortAudio is not initialized or an -- 2.43.0