From c7dee00e91d106acc9f1dfc31263561ecdf5cb9e Mon Sep 17 00:00:00 2001 From: Ralph Giles Date: Tue, 20 Mar 2001 07:39:07 +0000 Subject: [PATCH] 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 --- doc/vorbisfile/ov_read.html | 62 +++++++++++++++++++++++++++------------------ lib/vorbisfile.c | 8 ++---- 2 files changed, 39 insertions(+), 31 deletions(-) diff --git a/doc/vorbisfile/ov_read.html b/doc/vorbisfile/ov_read.html index ad53aaa..227dd18 100644 --- a/doc/vorbisfile/ov_read.html +++ b/doc/vorbisfile/ov_read.html @@ -13,23 +13,23 @@ -

ov_read

+

ov_read()

declared in "vorbis/vorbisfile.h";

-

This is the main function used to decode a Vorbis file within a loop. -

This function deals with more complicated bitstream chaining issues. Up to this point, everything could more or less hide the multiple +

+ This is the main function used to decode a Vorbis file within a loop. +

+ 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. -

- ov_read returns the sequential logical bitstream number currently +

+ ov_read() 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. -

+ application can take action on channel/sample rate changes. +



@@ -58,28 +58,40 @@ functions.
sgned
Signed or unsigned data. 0 for unsigned, 1 for signed. Typically 1.
bitstream
-
A pointer to the number of the current logical bitstream. +
A pointer to the number of the current logical bitstream.

Return Values

-
  • -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)
    • -
  • -OV_EBADLINK indicates that an invalid stream section was supplied to libvorbisfile, - or the requested link is corrupt. -
    • - -
  • -0 indicates EOF
    • -
  • n indicates actual number of bytes read. Within a logical bitstream, the number should equal length. At the end of a logical bitstream, the number of bytes read will equal the remaining number of bytes in the bitstream.
    • +
    +
    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)
    +
    OV_EBADLINK
    +
    indicates that an invalid stream section was supplied to + libvorbisfile, or the requested link is corrupt.
    +
    0
    +
    indicates EOF
    +
    n
    +
    indicates actual number of bytes read. ov_read() will + decode at most one vorbis packet per invocation, so the value + returned will generally be less than length. +
    -

    +

    Notes

    -

    Typical usage: bytes_read = ov_read(&vf, buffer, 4096,0,2,1,&current_section) -
    This reads up to 4096 bytes into a buffer, with signed 16-bit little-endian -samples. +

    Typical usage: +

    +bytes_read = ov_read(&vf, +buffer, 4096,0,2,1,&current_section) +
    + +This reads up to 4096 bytes into a buffer, with signed 16-bit +little-endian samples. +

    +


    diff --git a/lib/vorbisfile.c b/lib/vorbisfile.c index 03191ba..af79077 100644 --- 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 -- 2.7.4