Correct ov_read() documentation. Each call decodes at most one

vorbis packet and will not necessarily fill the buffer as claimed
in the html docs.

Also removed the wierd clause about *bitstream not returning the
real logical bitstream id in a seekable context. One presumes any
re-writing would happen on the server side.

svn path=/trunk/vorbis/; revision=1385

diff --git a/doc/vorbisfile/ov_read.html b/doc/vorbisfile/ov_read.html
index ad53aaa..227dd18 100644 (file)
--- a/doc/vorbisfile/ov_read.html
+++ b/doc/vorbisfile/ov_read.html
@@ -13,23 +13,23 @@
 </tr>
 </table>
 
-<h1>ov_read</h1>
+<h1>ov_read()</h1>
 
 <p><i>declared in "vorbis/vorbisfile.h";</i></p>
 
-<p>This is the main function used to decode a Vorbis file within a loop.
-<p>This function deals with more complicated bitstream chaining issues.  Up to this point, everything could more or less hide the multiple
+<p>
+   This is the main function used to decode a Vorbis file within a loop.
+</p><p>
+   This function deals with more complicated bitstream chaining issues.
+   Up to this point, everything could more or less hide the multiple
    logical bitstream nature of chaining from the toplevel application
    if the toplevel application didn't particularly care.  However, when we actually read audio back, we must be aware that multiple bitstream sections do not necessarily
    have to have the same number of channels or sampling rate.
-<p>
-   ov_read returns the sequential logical bitstream number currently
+</p><p>
+   <tt>ov_read()</tt> passes back the logical bitstream number currently
    being decoded along with the PCM data in order that the toplevel
-   application can take action on channel/sample rate changes.  This
-   number will be incremented even for streamed (non-seekable) streams
-   For seekable streams, it represents the actual logical bitstream
-   index within the physical bitstream.
-<p>
+   application can take action on channel/sample rate changes.
+</p>
 
 <br><br>
 <table border=0 color=black cellspacing=0 cellpadding=7>
@@ -58,28 +58,40 @@ functions.</dd>
 <dt><i>sgned</i></dt>
 <dd>Signed or unsigned data.  0 for unsigned, 1 for signed.  Typically 1.</dd>
 <dt><i>bitstream</i></dt>
-<dd></dd>A pointer to the number of the current logical bitstream.
+<dd>A pointer to the number of the current logical bitstream.</dd>
 </dl>
 
 
 <h3>Return Values</h3>
 <blockquote>
-<li>
-OV_HOLE indicates there was an interruption in the data. (one of: garbage between pages, loss of sync followed by recapture, or a corrupt page)</li>\r
-<li>
-OV_EBADLINK    indicates that an invalid stream section was supplied to libvorbisfile, \r
-               or the requested link is corrupt. \r
-</li>
-
-<li>
-0 indicates EOF</li>
-<li><i>n</i> indicates actual number of bytes read.  Within a logical bitstream, the number should equal <tt>length</tt>.  At the end of a logical bitstream, the number of bytes read will equal the remaining number of bytes in the bitstream.</li>
+<dl>
+<dt>OV_HOLE</dt>
+  <dd>indicates there was an interruption in the data.
+      <br>(one of: garbage between pages, loss of sync followed by
+           recapture, or a corrupt page)</dd>
+<dt>OV_EBADLINK</dt>
+  <dd>indicates that an invalid stream section was supplied to
+      libvorbisfile, or the requested link is corrupt.</dd>
+<dt>0</dt>
+  <dd>indicates EOF</dd>
+<dt><i>n</i></dt>
+  <dd>indicates actual number of bytes read.  <tt>ov_read()</tt> will
+      decode at most one vorbis packet per invocation, so the value
+      returned will generally be less than <tt>length</tt>.
+</dl>
 </blockquote>
-<p>
+
 <h3>Notes</h3>
-<p><b>Typical usage:</b> <tt>bytes_read = ov_read(&amp;vf, buffer, 4096,0,2,1,&amp;current_section)</tt>
-<br>This reads up to 4096 bytes into a buffer, with signed 16-bit little-endian
-samples.
+<p><b>Typical usage:</b>
+<blockquote>
+<tt>bytes_read = ov_read(&amp;vf,
+buffer, 4096,0,2,1,&amp;current_section)</tt>
+</blockquote>
+
+This reads up to 4096 bytes into a buffer, with signed 16-bit
+little-endian samples.
+</p>
+
 <br>
 <br><br>
 <hr noshade>

diff --git a/lib/vorbisfile.c b/lib/vorbisfile.c
index 03191ba..af79077 100644 (file)
--- a/lib/vorbisfile.c
+++ b/lib/vorbisfile.c
@@ -11,7 +11,7 @@
  ********************************************************************
 
  function: stdio-based convenience library for opening/seeking/decoding
- last mod: $Id: vorbisfile.c,v 1.41 2001/02/26 03:50:43 xiphmont Exp $
+ last mod: $Id: vorbisfile.c,v 1.42 2001/03/20 07:39:07 giles Exp $
 
  ********************************************************************/
 
@@ -1104,11 +1104,7 @@ int host_is_big_endian() {
 
    ov_read returns the sequential logical bitstream number currently
    being decoded along with the PCM data in order that the toplevel
-   application can take action on channel/sample rate changes.  This
-   number will be incremented even for streamed (non-seekable) streams
-   (for seekable streams, it represents the actual logical bitstream
-   index within the physical bitstream.  Note that the accessor
-   functions above are aware of this dichotomy).
+   application can take action on channel/sample rate changes.
 
    input values: buffer) a buffer to hold packed PCM data for return
                 length) the byte length requested to be placed into buffer