[xiph-cvs] cvs commit: vorbis/lib vorbisfile.c
Ralph Giles
giles at xiph.org
Mon Mar 19 23:39:08 PST 2001
giles 01/03/19 23:39:08
Modified: doc/vorbisfile ov_read.html
lib vorbisfile.c
Log:
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.
Revision Changes Path
1.3 +37 -25 vorbis/doc/vorbisfile/ov_read.html
Index: ov_read.html
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/vorbisfile/ov_read.html,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- ov_read.html 2000/11/06 00:06:47 1.2
+++ ov_read.html 2001/03/20 07:39:07 1.3
@@ -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 @@
<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>
-<li>
-OV_EBADLINK indicates that an invalid stream section was supplied to libvorbisfile,
- or the requested link is corrupt.
-</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(&vf, buffer, 4096,0,2,1,&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(&vf,
+buffer, 4096,0,2,1,&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>
1.42 +2 -6 vorbis/lib/vorbisfile.c
Index: vorbisfile.c
===================================================================
RCS file: /usr/local/cvsroot/vorbis/lib/vorbisfile.c,v
retrieving revision 1.41
retrieving revision 1.42
diff -u -r1.41 -r1.42
--- vorbisfile.c 2001/02/26 03:50:43 1.41
+++ vorbisfile.c 2001/03/20 07:39:07 1.42
@@ -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 @@
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
--- >8 ----
List archives: http://www.xiph.org/archives/
Ogg project homepage: http://www.xiph.org/ogg/
To unsubscribe from this list, send a message to 'cvs-request at xiph.org'
containing only the word 'unsubscribe' in the body. No subject is needed.
Unsubscribe messages sent to the list will be ignored/filtered.
More information about the commits
mailing list