Add documentation indicating that Pa_ReadStream, Pa_WriteStream, Pa_GetStreamReadAvai...

diff --git a/include/portaudio.h b/include/portaudio.h
index 5d847314ae9ba0e57468cccf4cfd52f9e100cf45..c3e174472f9e4b2434f6d86758cb238939c80e08 100644 (file)
--- 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