Tue Jul 2 14:40:38 PDT 2002

xiphmont    02/07/02 14:40:36

  Modified:    doc/vorbisfile OggVorbis_File.html datastructures.html
                        decoding.html example.html fileinfo.html index.html
                        initialization.html ov_bitrate.html
                        ov_bitrate_instant.html ov_callbacks.html
                        ov_clear.html ov_comment.html ov_info.html
                        ov_open.html ov_open_callbacks.html
                        ov_pcm_seek.html ov_pcm_seek_page.html
                        ov_pcm_tell.html ov_pcm_total.html ov_raw_seek.html
                        ov_raw_tell.html ov_raw_total.html ov_read.html
                        ov_read_float.html ov_seekable.html
                        ov_serialnumber.html ov_streams.html ov_test.html
                        ov_test_callbacks.html ov_test_open.html
                        ov_time_seek.html ov_time_seek_page.html
                        ov_time_tell.html ov_time_total.html overview.html
                        reference.html seeking.html vorbis_comment.html
                        vorbis_info.html
  Log:
  Numerous corrections and updates to libVorbisfile docs

Revision  Changes    Path
1.4       +47 -31    vorbis/doc/vorbisfile/OggVorbis_File.html

Index: OggVorbis_File.html
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/vorbisfile/OggVorbis_File.html,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4

--- OggVorbis_File.html	2001/12/19 02:00:47	1.3
+++ OggVorbis_File.html	2002/07/02 21:40:29	1.4
@@ -1,15 +1,15 @@
 <html>
 
 <head>
-<title>vorbisfile - datatype - OggVorbis_File</title>
+<title>Vorbisfile - datatype - OggVorbis_File</title>
 <link rel=stylesheet href="style.css" type="text/css">
 </head>
 
 <body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
 <table border=0 width=100%>
 <tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile - 20011218</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
 
@@ -20,10 +20,30 @@
 <p>
 The OggVorbis_File structure defines an Ogg Vorbis file.
 <p>
-This structure is used in all vorbisfile routines.  Before it can be used, it must be initialized by ov_open or ov_open_callbacks.
+
+This structure is used in all libvorbisfile routines.  Before it can be used,
+it must be initialized by ov_open() or <a
+href="ov_open_callbacks.html">ov_open_callbacks()</a>.
+
+<p>
+After use, the OggVorbis_File structure must be deallocated with a
+call to ov_clear().
+
+<p>
+Once a file or data source is opened successfully by libvorbisfile
+(using ov_open() or <a
+href="ov_open_callbacks.html">ov_open_callbacks()</a>), it is owned by
+libvorbisfile.  The file should not be used by any other applications or
+functions outside of the libvorbisfile API.  The file must not be closed
+directly by the application at any time after a successful open;
+libvorbisfile expects to close the file within <a
+href="ov_clear.html">ov_clear()</a>.
 <p>
-After use, the OggVorbis_File structure must be deallocated with a call to ov_clear().
-<p>Once a file or data source is passed to libvorbisfile, it is owned by vorbisfile.  The file should not be used by any other applications or functions outside the Vorbisfile API.
+If the call to ov_open() or <a
+href="ov_open_callbacks.html">ov_open_callbacks()</a> <b>fails</b>,
+libvorbisfile does <b>not</b> assume ownership of the file and the
+application is expected to close it if necessary.
+
 <br><br>
 <table border=0 width=100% color=black cellspacing=0 cellpadding=7>
 <tr bgcolor=#cccccc>
@@ -31,28 +51,28 @@
 <pre><b>typedef struct {
   void             *datasource; /* Pointer to a FILE *, etc. */
   int              seekable;
-  int64_t          offset;
-  int64_t          end;
+  ogg_int64_t      offset;
+  ogg_int64_t      end;
   ogg_sync_state   oy; 
 
   /* If the FILE handle isn't seekable (eg, a pipe), only the current
      stream appears */
   int              links;
-  int64_t          *offsets;
-  int64_t          *dataoffsets;
+  ogg_int64_t      *offsets;
+  ogg_int64_t      *dataoffsets;
   long             *serialnos;
-  int64_t          *pcmlengths;
+  ogg_int64_t      *pcmlengths;
   vorbis_info      *vi;
   vorbis_comment   *vc;
 
   /* Decoding working state local storage */
-  int64_t          pcm_offset;
+  ogg_int64_t      pcm_offset;
   int              ready_state;
   long             current_serialno;
   int              current_link;
 
-  double           bittrack;
-  double           samptrack;
+  ogg_int64_t      bittrack;
+  ogg_int64_t      samptrack;
 
   ogg_stream_state os; /* take physical pages, weld into a logical
                           stream of packets */
@@ -69,34 +89,30 @@
 <h3>Relevant Struct Members</h3>
 <dl>
 <dt><i>datasource</i></dt>
-<dd>Pointer to file or other ogg source.</dd>
+
+<dd>Pointer to file or other ogg source.  When using stdio based
+file/stream access, this field contains a <tt>FILE</tt> pointer. When using
+custom IO via callbacks, libvorbisfile treats this void pointer as a
+black box only to be passed to the callback routines provided by the
+application.</dd>
+
 <dt><i>seekable</i></dt>
-<dd>Read-only int indicating whether file is seekable, i.e., physical file is seekable, a pipe isn't.</dd>
+<dd>Read-only int indicating whether file is seekable. E.g., a physical file is seekable, a pipe isn't.</dd>
 <dt><i>links</i></dt>
 <dd>Read-only int indicating the number of logical bitstreams within the physical bitstream.</dd>
 <dt><i>ov_callbacks</i></dt>
-<dd>Collection of file manipulation routines to be used on this data source.</dd>
+<dd>Collection of file manipulation routines to be used on this data source.  When using stdio/FILE access via ov_open(), the callbacks will be filled in with stdio calls or wrappers to stdio calls.</dd>
 </dl>
 
-<h3>Notes</h3>
-
-<p>If your system's <tt>&lt;sys/types.h></tt> does not
-define <tt>int64_t,</tt> you will need to define this as a 64-bit type
-inside your system's project file/Makefile, etc. On win32, for example,
-this should be defined as <tt>__int64</tt>. On the Unix platform, these
-are usually defined properly in the system header files.
-<p>
-
-
 <br><br>
 <hr noshade>
 <table border=0 width=100%>
 <tr valign=top>
-<td><p class=tiny>copyright &copy; 2001 vorbis team</p></td>
-<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/index.html">Ogg Vorbis</a><br><a href="mailto:team at vorbis.org">team at vorbis.org</a></p></td>
+<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
+<td align=right><p class=tiny>Ogg Vorbis</p></td>
 </tr><tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile - 20011218</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
 

<p><p>1.4       +10 -12    vorbis/doc/vorbisfile/datastructures.html

Index: datastructures.html
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/vorbisfile/datastructures.html,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- datastructures.html	2001/12/20 01:00:21	1.3
+++ datastructures.html	2002/07/02 21:40:29	1.4
@@ -1,24 +1,22 @@
 <html>
 
 <head>
-<title>vorbisfile - Base Data Structures</title>
+<title>Vorbisfile - Base Data Structures</title>
 <link rel=stylesheet href="style.css" type="text/css">
 </head>
 
 <body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
 <table border=0 width=100%>
 <tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
 
 <h1>Base Data Structures</h1>
-<p>There are several data structures used to hold file and bitstream information during vorbisfile decoding.
+<p>There are several data structures used to hold file and bitstream information during libvorbisfile decoding. These structures are declared in "vorbis/vorbisfile.h" and "vorbis/codec.h".
 <p>
-All the <b>vorbisfile</b> specific data structures are declared in "vorbis/vorbisfile.h" or "vorbis/codec.h".
-<p>
-<p>When using vorbisfile, we usually won't need to know about most of the contents of these data structures, but it may be helpful to understand what they contain.
+<p>When using libvorbisfile, it's not necessary to know about most of the contents of these data structures, but it may be helpful to understand what they contain.
 <br><br>
 
 <table border=1 color=black width=50% cellspacing=0 cellpadding=7>
@@ -42,7 +40,7 @@
 </tr>
 <tr valign=top>
 <td>ov_callbacks</td>
-	<td>This structure contains pointers to file manipulation routines.  Can be user-specified for use with ov_open_callbacks().</td>
+	<td>This structure contains pointers to the application-specified file manipulation routines set for use by ov_open_callbacks(). See also the provided document on using application-provided callbacks instead of stdio.</td>
 </tr>
 </table>
 
@@ -50,11 +48,11 @@
 <hr noshade>
 <table border=0 width=100%>
 <tr valign=top>
-<td><p class=tiny>copyright &copy; 2000 vorbis team</p></td>
-<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a><br><a href="mailto:team at vorbis.org">team at vorbis.org</a></p></td>
+<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
+<td align=right><p class=tiny>Ogg Vorbis</p></td>
 </tr><tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
 

<p><p>1.4       +42 -10    vorbis/doc/vorbisfile/decoding.html

Index: decoding.html
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/vorbisfile/decoding.html,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- decoding.html	2001/12/19 02:00:47	1.3
+++ decoding.html	2002/07/02 21:40:29	1.4
@@ -1,24 +1,57 @@
 <html>
 
 <head>
-<title>vorbisfile - Decoding</title>
+<title>Vorbisfile - Decoding</title>
 <link rel=stylesheet href="style.css" type="text/css">
 </head>
 
 <body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
 <table border=0 width=100%>
 <tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile - 20011218</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
 
 <h1>Decoding</h1>
 
 <p>
-All the <b>vorbisfile</b> decoding routines are declared in "vorbis/vorbisfile.h".
+All libvorbisfile decoding routines are declared in "vorbis/vorbisfile.h".
 <p>
 
+After initialization, decoding audio
+is as simple as calling ov_read(). This
+function works similarly to reading from a normal file using
+<tt>read()</tt>.<p>
+
+However, a few differences are worth noting:
+
+<h2>multiple stream links</h2>
+
+A Vorbis stream may consist of multiple sections (called links) that
+encode differing numbers of channels or sample rates.  It is vitally
+important to pay attention to the link numbers returned by <a
+href="ov_read.html">ov_read</a> and handle audio changes that may
+occur at link boundaries.  Such multi-section files do exist in the
+wild and are not merely a specification curiosity.
+
+<h2>returned data amount</h2>
+
+ov_read does not attempt to completely fill
+a large, passed in data buffer; it merely guarantees that the passed
+back data does not overflow the passed in buffer size.  Large buffers
+may be filled by iteratively looping over calls to <a
+href="ov_read.html">ov_read</a> (incrementing the buffer pointer)
+until the original buffer is filled.
+
+<h2>file cursor position</h2>
+
+Vorbis files do not necessarily start at a sample number or time offset
+of zero.  Do not be surprised if a file begins at a positive offset of
+several minutes or hours, such as would happen if a large stream (such
+as a concert recording) is chopped into multiple seperate files.
+
+<p>
 <table border=1 color=black width=50% cellspacing=0 cellpadding=7>
 <tr bgcolor=#cccccc>
         <td><b>function</b></td>
@@ -31,7 +64,7 @@
 call to <a href="ov_open.html"><tt>ov_open()</tt></a>.</td>
 </tr>
 <tr valign=top>
-        <td>ov_read</td>
+        <td>ov_read_float</td>
         <td>This function decodes to floats instead of integer samples.</td>
 </tr>
 </table>
@@ -40,14 +73,13 @@
 <hr noshade>
 <table border=0 width=100%>
 <tr valign=top>
-<td><p class=tiny>copyright &copy; 2001 Xiphophorus</p></td>
-<td align=right><p class=tiny><a href="http://www.vorbis.org/">www.vorbis.org</a><br><a href="mailto:team at icecast.org">team at icecast.org</a></p></td>
+<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
+<td align=right><p class=tiny>Ogg Vorbis</p></td>
 </tr><tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile - 20011218</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
-
 
 </body>
 

<p><p>1.4       +13 -13    vorbis/doc/vorbisfile/example.html

Index: example.html
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/vorbisfile/example.html,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- example.html	2001/12/20 01:00:21	1.3
+++ example.html	2002/07/02 21:40:29	1.4
@@ -1,15 +1,15 @@
 <html>
 
 <head>
-<title>vorbisfile - Example Code</title>
+<title>Vorbisfile - Example Code</title>
 <link rel=stylesheet href="style.css" type="text/css">
 </head>
 
 <body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
 <table border=0 width=100%>
 <tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
 
@@ -17,11 +17,11 @@
 
 <p>
 The following is a run-through of the decoding example program supplied
-with vorbisfile - vorbisfile_example.c.  
+with libvorbisfile, vorbisfile_example.c.  
 This program takes a vorbis bitstream from stdin and writes raw pcm to stdout.
 
 <p>
-First, relevant headers, including vorbis-specific "codec.h" and "vorbisfile.h" have to be included.
+First, relevant headers, including vorbis-specific "vorbis/codec.h" and "vorbisfile.h" have to be included.
 
 <br><br>
 <table border=0 width=100% color=black cellspacing=0 cellpadding=7>
@@ -32,7 +32,7 @@
 #include &lt;stdlib.h&gt;
 #include &lt;math.h&gt;
 #include "vorbis/codec.h"
-#include "vorbis/vorbisfile.h"
+#include "vorbisfile.h"
 </b></pre>
         </td>
 </tr>
@@ -123,6 +123,8 @@
       ++ptr;
     }
     fprintf(stderr,"\nBitstream is %d channel, %ldHz\n",vi->channels,vi->rate);
+    fprintf(stderr,"\nDecoded length: %ld samples\n",
+            (long)ov_pcm_total(&vf,-1));
     fprintf(stderr,"Encoded by: %s\n\n",ov_comment(&vf,-1)->vendor);
   }
   
@@ -141,7 +143,7 @@
 <pre><b>
 
   while(!eof){
-    long ret=ov_read(&vf,pcmout,sizeof(pcmout),0,2,1,&current_section);
+    long ret=ov_read(&vf,pcmout,sizeof(pcmout),&current_section);
     if (ret == 0) {
       /* EOF */
       eof=1;
@@ -185,18 +187,16 @@
 </table>
 
 <p>
-The full source for vorbisfile_example.c can be found with the vorbis
-distribution in vorbisfile_example.c.
 
 <br><br>
 <hr noshade>
 <table border=0 width=100%>
 <tr valign=top>
-<td><p class=tiny>copyright &copy; 2000 vorbis team</p></td>
-<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a><br><a href="mailto:team at vorbis.org">team at vorbis.org</a></p></td>
+<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
+<td align=right><p class=tiny>Ogg Vorbis</p></td>
 </tr><tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
 

<p><p>1.3       +10 -11    vorbis/doc/vorbisfile/fileinfo.html

Index: fileinfo.html
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/vorbisfile/fileinfo.html,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- fileinfo.html	2000/11/06 00:06:47	1.2
+++ fileinfo.html	2002/07/02 21:40:29	1.3
@@ -1,22 +1,22 @@
 <html>
 
 <head>
-<title>vorbisfile - File Information</title>
+<title>Vorbisfile - File Information</title>
 <link rel=stylesheet href="style.css" type="text/css">
 </head>
 
 <body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
 <table border=0 width=100%>
 <tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
 
 <h1>File Information</h1>
-<p>Vorbisfile contains many functions to get information about bitstream attributes and decoding status.
+<p>Libvorbisfile contains many functions to get information about bitstream attributes and decoding status.
 <p>
-All the <b>vorbisfile</b> file information routines are declared in "vorbis/vorbisfile.h".
+All libvorbisfile file information routines are declared in "vorbis/vorbisfile.h".
 <p>
 
 <table border=1 color=black width=50% cellspacing=0 cellpadding=7>
@@ -30,7 +30,7 @@
 </tr>
 <tr valign=top>
         <td>ov_bitrate_instant</td>
-	<td>Returns the exact bitrate since the last call of this function, or -1 if beginning of the bitream or no new info is available.</td>
+	<td>Returns the exact bitrate since the last call of this function, or -1 if at the beginning of the bitream or no new information is available.</td>
 </tr>
 <tr valign=top>
         <td>ov_streams</td>
@@ -82,14 +82,13 @@
 <hr noshade>
 <table border=0 width=100%>
 <tr valign=top>
-<td><p class=tiny>copyright &copy; 2000 vorbis team</p></td>
-<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a><br><a href="mailto:team at vorbis.org">team at vorbis.org</a></p></td>
+<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
+<td align=right><p class=tiny>Ogg Vorbis</p></td>
 </tr><tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
-
 
 </body>
 

<p><p>1.3       +22 -15    vorbis/doc/vorbisfile/index.html

Index: index.html
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/vorbisfile/index.html,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- index.html	2000/11/06 00:06:47	1.2
+++ index.html	2002/07/02 21:40:29	1.3
@@ -1,39 +1,46 @@
 <html>
 
 <head>
-<title>vorbisfile - Documentation</title>
+<title>Vorbisfile - Documentation</title>
 <link rel=stylesheet href="style.css" type="text/css">
 </head>
 
 <body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
 <table border=0 width=100%>
 <tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
 
-<h1>VorbisFile Documentation</h1>
+<h1>Vorbisfile Documentation</h1>
 
 <p>
-VorbisFile is a stdio-based convenience library for decoding vorbis bitstreams.
-It is the simplest and quickest way to go from file to raw PCM audio samples--if
-your decoder doesn't need to read from anything other than a file, use
-this. This document explains how to use the vorbisfile API in detail.
+
+The Vorbisfile library provides a convenient high-level API for
+decoding and basic manipulation of all Vorbis I audio streams.
+Libvorbisfile is implemented as a layer on top of Xiph.org's reference
+libogg and libvorbis libraries.<p>
+
+Vorbisfile can be used along with any ANSI compliant stdio implementation
+for file/stream access, or use custom stream i/o routines provided by
+the embedded environment.  Both uses are described in detail in this
+documentation.
+
 <p>
-vorbisfile api overview<br>
-vorbisfile example code<br>
-vorbisfile api reference<br>
+API overview<br>
+API reference<br>
+Example code<br>
 
 <br><br>
 <hr noshade>
 <table border=0 width=100%>
 <tr valign=top>
-<td><p class=tiny>copyright &copy; 2000 vorbis team</p></td>
-<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a><br><a href="mailto:team at vorbis.org">team at vorbis.org</a></p></td>
+<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
+<td align=right><p class=tiny>Ogg Vorbis</p></td>
 </tr><tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
 

<p><p>1.4       +52 -19    vorbis/doc/vorbisfile/initialization.html

Index: initialization.html
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/vorbisfile/initialization.html,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- initialization.html	2001/12/19 02:00:47	1.3
+++ initialization.html	2002/07/02 21:40:29	1.4
@@ -1,22 +1,34 @@
 <html>
 
 <head>
-<title>libvorbisfile - Setup/Teardown</title>
+<title>Vorbisfile - Setup/Teardown</title>
 <link rel=stylesheet href="style.css" type="text/css">
 </head>
 
 <body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
 <table border=0 width=100%>
 <tr>
-<td><p class=tiny>libvorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
 
-<h1>Setup/Teardown</h1>
-<p>In order to decode audio using libvorbisfile, a bitstream containing vorbis audio must be properly initialized and cleared when decoding is finished.
+<H1>Setup/Teardown</h1> <p>In order to decode audio using
+libvorbisfile, a bitstream containing Vorbis audio must be properly
+initialized before decoding and cleared when decoding is finished.
+The simplest possible case is to use <tt>fopen()</tt> to open a Vorbis
+file and then pass the <tt>FILE *</tt> to an <a
+href="ov_open.html">ov_open()</a> call.  A successful <a
+href="return.html">return code</a> from <a
+href="ov_open.html">ov_open()</a> indicates the file is ready for use.
+Once the file is no longer needed, <a
+href="ov_clear.html">ov_clear()</a> is used to close the file and
+deallocate decoding resources.  </b>Do not</b> call <tt>fclose()</tt> on the
+file; libvorbisfile does this in the <a
+href="ov_clear.html">ov_clear()</a> call.
+
 <p>
-All the <b>vorbisfile</b> initialization and deallocation routines are declared in "vorbis/vorbisfile.h".
+All libvorbisfile initialization and deallocation routines are declared in "vorbis/vorbisfile.h".
 <p>
 
 <table border=1 color=black width=50% cellspacing=0 cellpadding=7>
@@ -31,23 +43,44 @@
 </tr>
 <tr valign=top>
         <td>ov_open_callbacks</td>
-	<td>Initializes the Ogg Vorbis bitstream with a pointer to a bitstream, default values, and custom file/bitstream manipulation routines.  Used instead of ov_open when working with a data source other than a file.</td>
-</tr>
-<tr valign=top>
-	<td>ov_clear</td>
-	<td>Closes the bitstream and cleans up loose ends.  Must be called when we're done with the bitstream.</td>
+	<td>Initializes the Ogg Vorbis bitstream with a pointer to a bitstream, default values, and custom file/bitstream manipulation routines.  Used instead of ov_open() when working with other than stdio based I/O.</td>
 </tr>
+
 <tr valign=top>
-<td>ov_test</td>
-<td>Partially opens a vorbis file for testing.</td>
+<td>ov_test</td> 
+
+<td>Partially opens a file just far enough to determine if the file
+is an Ogg Vorbis file or not.  A successful return indicates that the
+file appears to be an Ogg Vorbis file, but the <a
+href="OggVorbis_File.html">OggVorbis_File</a> struct is not yet fully
+initialized for actual decoding.  After a successful return, the file
+may be closed using ov_clear() or fully
+opened for decoding using <a
+href="ov_test_open.html">ov_test_open()</a>.<p> This call is intended to
+be used as a less expensive file open test than a full <a
+href="ov_open.html">ov_open()</a>.<p>
+Note that libvorbisfile owns the passed in file resource is it returns success; do not <tt>fclose()</tt> files owned by libvorbisfile.</td>
+
 </tr>
 <tr valign=top>
 <td>ov_test_callbacks</td>
-<td>Same as above but useful for non-files like streams.</td>
+<td>As above but allowing application-define I/O callbacks.<p>
+Note that libvorbisfile owns the passed in file resource is it returns success; do not <tt>fclose()</tt> files owned by libvorbisfile.</td>
+
 </tr>
 <tr valign=top>
 <td>ov_test_open<td>
-<td>Finish open a file opened for testing.</td>
+Finish opening a file after a successful call to ov_test() or ov_test_callbacks().</td>
+</tr>
+<tr valign=top>
+	<td>ov_clear</td> <td>Closes the
+	bitstream and cleans up loose ends.  Must be called when
+	finished with the bitstream.  After return, the <a
+	href="OggVorbis_File.html">OggVorbis_File</a> struct is
+	invalid and may not be used before being initialized again
+	before begin reinitialized.
+
+</td>
 </tr>
 </table>
 
@@ -55,11 +88,11 @@
 <hr noshade>
 <table border=0 width=100%>
 <tr valign=top>
-<td><p class=tiny>copyright &copy; 2000 vorbis team</p></td>
-<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/index.html">Ogg Vorbis</a><br><a href="mailto:team at vorbis.org">team at vorbis.org</a></p></td>
+<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
+<td align=right><p class=tiny>Ogg Vorbis</p></td>
 </tr><tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
 

<p><p>1.4       +10 -11    vorbis/doc/vorbisfile/ov_bitrate.html

Index: ov_bitrate.html
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/vorbisfile/ov_bitrate.html,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- ov_bitrate.html	2001/12/20 01:00:21	1.3
+++ ov_bitrate.html	2002/07/02 21:40:29	1.4
@@ -1,15 +1,15 @@
 <html>
 
 <head>
-<title>vorbisfile - function - ov_bitrate</title>
+<title>Vorbisfile - function - ov_bitrate</title>
 <link rel=stylesheet href="style.css" type="text/css">
 </head>
 
 <body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
 <table border=0 width=100%>
 <tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
 
@@ -35,7 +35,7 @@
 <h3>Parameters</h3>
 <dl>
 <dt><i>vf</i></dt>
-<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible vorbisfile
+<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile
 functions.</dd>
 <dt><i>i</i></dt>
 <dd>Link to the desired logical bitstream.  For nonseekable files, this argument is ignored.  To retrieve the bitrate for the entire bitstream, this parameter should be set to -1.</dd>
@@ -44,7 +44,7 @@
 
 <h3>Return Values</h3>
 <blockquote>
-<li>OV_EINVAL indicates that an invalid argument value was submitted.</li>
+<li>OV_EINVAL indicates that an invalid argument value was submitted or that the stream represented by <tt>vf</tt> is not open.</li>
 <li>OV_FALSE means the call returned a 'false' status, which in this case most likely indicates that the file is nonseekable and the upper, lower, and nominal bitrates were unset.
 <li><i>n</i> indicates the bitrate for the given logical bitstream or the entire
    physical bitstream.  If the file is open for random (seekable) access, it will
@@ -54,19 +54,18 @@
 </blockquote>
 <p>
 
-<br>
+
 <br><br>
 <hr noshade>
 <table border=0 width=100%>
 <tr valign=top>
-<td><p class=tiny>copyright &copy; 2000 vorbis team</p></td>
-<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/index.html">Ogg Vorbis</a><br><a href="mailto:team at vorbis.org">team at vorbis.org</a></p></td>
+<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
+<td align=right><p class=tiny>Ogg Vorbis</p></td>
 </tr><tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
-
 
 </body>
 

<p><p>1.4       +12 -12    vorbis/doc/vorbisfile/ov_bitrate_instant.html

Index: ov_bitrate_instant.html
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/vorbisfile/ov_bitrate_instant.html,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- ov_bitrate_instant.html	2001/12/20 01:00:21	1.3
+++ ov_bitrate_instant.html	2002/07/02 21:40:29	1.4
@@ -1,15 +1,15 @@
 <html>
 
 <head>
-<title>vorbisfile - function - ov_bitrate</title>
+<title>Vorbisfile - function - ov_bitrate</title>
 <link rel=stylesheet href="style.css" type="text/css">
 </head>
 
 <body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
 <table border=0 width=100%>
 <tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
 
@@ -33,32 +33,32 @@
 <h3>Parameters</h3>
 <dl>
 <dt><i>vf</i></dt>
-<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible vorbisfile
+<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile
 functions.
 </dl>
 
 
 <h3>Return Values</h3>
 <blockquote>
-<li>
-0 indicates the beginning of the file or unchanged bitrate info.</li>
+<li>0 indicates the beginning of the file or unchanged bitrate info.</li>
 <li><i>n</i> indicates the actual bitrate since the last call.</li>
-<li>OV_FALSE indicates that the call returned a 'false' status.  In this case, this error code is returned if playback is not in progress, and thus there is no instantaneous bitrate information to report.</li>
+<li>OV_FALSE indicates that playback is not in progress, and thus there is no instantaneous bitrate information to report.</li>
+<li>OV_EINVAL indicates that the stream represented by <tt>vf</tt> is not open.</li>
 </blockquote>
 <p>
 
+
 <br><br>
 <hr noshade>
 <table border=0 width=100%>
 <tr valign=top>
-<td><p class=tiny>copyright &copy; 2000 vorbis team</p></td>
-<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/index.html">Ogg Vorbis</a><br><a href="mailto:team at vorbis.org">team at vorbis.org</a></p></td>
+<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
+<td align=right><p class=tiny>Ogg Vorbis</p></td>
 </tr><tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
-
 
 </body>
 

<p><p>1.4       +25 -25    vorbis/doc/vorbisfile/ov_callbacks.html

Index: ov_callbacks.html
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/vorbisfile/ov_callbacks.html,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- ov_callbacks.html	2002/06/08 08:04:06	1.3
+++ ov_callbacks.html	2002/07/02 21:40:29	1.4
@@ -1,15 +1,15 @@
 <html>
 
 <head>
-<title>vorbisfile - datatype - ov_callbacks</title>
+<title>Vorbisfile - datatype - ov_callbacks</title>
 <link rel=stylesheet href="style.css" type="text/css">
 </head>
 
 <body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
 <table border=0 width=100%>
 <tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
 
@@ -19,22 +19,23 @@
 
 <p>
 The ov_callbacks structure contains file manipulation function prototypes necessary for opening, closing, seeking, and location.
-<p>
-The ov_callbacks structure does not need to be user-defined if you are working with a standard file.  The typical ov_open() call will fill ov_callbacks for you.  However, ov_callbacks should be defined if you are using other data sources.  In this situation, use ov_open_callbacks() instead of ov_open().
-<p>
 
+<p>
+The ov_callbacks structure does not need to be user-defined if you are
+working with stdio-based file manipulation; the <a
+href="ov_open.html">ov_open()</a> call provides default callbacks for
+stdio.  ov_callbacks are defined and passed to <a
+href="ov_open_callbacks.html">ov_open_callbacks()</a> when
+implementing non-stdio based stream manipulation (such as playback
+from a memory buffer).
 <p>
-The callbacks are designed following the stdio functions fread, fseek, fclose,
-and ftell. Except where otherwise noted below, they should work the same as
-these functions do.
-</p>
 
 <table border=0 width=100% color=black cellspacing=0 cellpadding=7>
 <tr bgcolor=#cccccc>
         <td>
 <pre><b>typedef struct {
   size_t (*read_func)  (void *ptr, size_t size, size_t nmemb, void *datasource);
-  int    (*seek_func)  (void *datasource, int64_t offset, int whence);
+  int    (*seek_func)  (void *datasource, ogg_int64_t offset, int whence);
   int    (*close_func) (void *datasource);
   long   (*tell_func)  (void *datasource);
 } ov_callbacks;</b></pre>
@@ -45,31 +46,30 @@
 <h3>Relevant Struct Members</h3>
 <dl>
 <dt><i>read_func</i></dt>
-<dd>Pointer to custom data reading function. Read up to size*nmemb bytes from
-the source into the buffer at ptr. Return the number of bytes read successfully.
-Must return 0 if nothing can be read. Should also set errno if an error occurs,
-in order to distinguish between error and EOF.</dd>
+<dd>Pointer to custom data reading function.</dd>
 <dt><i>seek_func</i></dt>
-<dd>Pointer to custom data seeking function. If your data source does not support
-seeking, you must</em> return -1. Returns 0 on success. Seeks to a position <em>offset</em> bytes from a position defined by <em>whence</em>. If whence is SEEK_SET, seek relative to the file start. If SEEK_CUR, seek is relative to current file position. If SEEK_END, relative to end of file.</dd>
+<dd>Pointer to custom data seeking function. If the data source is not seekable (or the application wants the data source to be treated as unseekable at all times), the provided seek callback should always return -1 (failure).</dd>
 <dt><i>close_func</i></dt>
-<dd>Pointer to custom data source closure function. This should clear any
-resources used by the data source, such as open files or network sockets. Returns 0.</dd>
+<dd>Pointer to custom data source closure function.</dd>
 <dt><i>tell_func</i></dt>
-<dd>Pointer to custom data location function. Returns the current offset (from the start) of the data stream. If your source is non-seekable, this need not be
-implemented.</dd>
+<dd>Pointer to custom data location function.</dd>
 </dl>
 
+<p>
+
+See the callbacks and non-stdio I/O document for more
+detailed information on required behavior of the various callback
+functions.<p>
 
 <br><br>
 <hr noshade>
 <table border=0 width=100%>
 <tr valign=top>
-<td><p class=tiny>copyright &copy; 2000 vorbis team</p></td>
-<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/index.html">Ogg Vorbis</a><br><a href="mailto:team at vorbis.org">team at vorbis.org</a></p></td>
+<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
+<td align=right><p class=tiny>Ogg Vorbis</p></td>
 </tr><tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
 

<p><p>1.3       +14 -13    vorbis/doc/vorbisfile/ov_clear.html

Index: ov_clear.html
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/vorbisfile/ov_clear.html,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- ov_clear.html	2000/11/06 00:06:47	1.2
+++ ov_clear.html	2002/07/02 21:40:29	1.3
@@ -1,15 +1,15 @@
 <html>
 
 <head>
-<title>vorbisfile - function - ov_clear</title>
+<title>Vorbisfile - function - ov_clear</title>
 <link rel=stylesheet href="style.css" type="text/css">
 </head>
 
 <body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
 <table border=0 width=100%>
 <tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
 
@@ -17,8 +17,11 @@
 
 <p><i>declared in "vorbis/vorbisfile.h";</i></p>
 
-<p> After a bitstream has been opened using ov_open and decoding is complete, you must call <tt>ov_clear()</tt> to clear
-the decoder's buffers and close the file for you.
+<p> After a bitstream has been opened using ov_open()/ov_open_callbacks() and decoding is complete, the application must call <tt>ov_clear()</tt> to clear
+the decoder's buffers and close the file.<p>
+
+<tt>ov_clear()</tt> must also be called after a successful call to ov_test() or ov_test_callbacks().<p>
+
 <br><br>
 <table border=0 color=black cellspacing=0 cellpadding=7>
 <tr bgcolor=#cccccc>
@@ -33,15 +36,14 @@
 <h3>Parameters</h3>
 <dl>
 <dt><i>vf</i></dt>
-<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible vorbisfile
+<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile
 functions.  After <tt>ov_clear</tt> has been called, the structure is deallocated and can no longer be used.</dd>
 </dl>
 
 
 <h3>Return Values</h3>
 <blockquote>
-<li>
-0 for success</li>
+<li>0 for success</li>
 </blockquote>
 
 
@@ -49,14 +51,13 @@
 <hr noshade>
 <table border=0 width=100%>
 <tr valign=top>
-<td><p class=tiny>copyright &copy; 2000 vorbis team</p></td>
-<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/index.html">Ogg Vorbis</a><br><a href="mailto:team at vorbis.org">team at vorbis.org</a></p></td>
+<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
+<td align=right><p class=tiny>Ogg Vorbis</p></td>
 </tr><tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
-
 
 </body>
 

<p><p>1.3       +10 -9     vorbis/doc/vorbisfile/ov_comment.html

Index: ov_comment.html
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/vorbisfile/ov_comment.html,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- ov_comment.html	2000/11/06 00:06:47	1.2
+++ ov_comment.html	2002/07/02 21:40:29	1.3
@@ -1,15 +1,16 @@
 <html>
 
 <head>
-<title>vorbisfile - function - ov_bitrate</title>
+<title>Vorbisfile - function - ov_bitrate</title>
 <link rel=stylesheet href="style.css" type="text/css">
 </head>
 
+
 <body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
 <table border=0 width=100%>
 <tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
 
@@ -34,7 +35,7 @@
 <h3>Parameters</h3>
 <dl>
 <dt><i>vf</i></dt>
-<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible vorbisfile
+<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile
 functions.</dd>
 <dt><i>i</i></dt>
 <dd>Link to the desired logical bitstream.  For nonseekable files, this argument is ignored.  To retrieve the vorbis_comment struct for the current bitstream, this parameter should be set to -1.</dd>
@@ -47,18 +48,18 @@
 <li>NULL if the specified bitstream does not exist or the file has been initialized improperly.</li>
 </blockquote>
 <p>
+
 <br><br>
 <hr noshade>
 <table border=0 width=100%>
 <tr valign=top>
-<td><p class=tiny>copyright &copy; 2000 vorbis team</p></td>
-<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/index.html">Ogg Vorbis</a><br><a href="mailto:team at vorbis.org">team at vorbis.org</a></p></td>
+<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
+<td align=right><p class=tiny>Ogg Vorbis</p></td>
 </tr><tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
-
 
 </body>
 

<p><p>1.3       +10 -11    vorbis/doc/vorbisfile/ov_info.html

Index: ov_info.html
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/vorbisfile/ov_info.html,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- ov_info.html	2000/11/06 00:06:47	1.2
+++ ov_info.html	2002/07/02 21:40:29	1.3
@@ -1,15 +1,15 @@
 <html>
 
 <head>
-<title>vorbisfile - function - ov_info</title>
+<title>Vorbisfile - function - ov_info</title>
 <link rel=stylesheet href="style.css" type="text/css">
 </head>
 
 <body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
 <table border=0 width=100%>
 <tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
 
@@ -33,9 +33,8 @@
 <h3>Parameters</h3>
 <dl>
 <dt><i>vf</i></dt>
-<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible vorbisfile
-functions. <b></strong>Once this has been called, the same <tt>OggVorbis_File</tt>
-struct should be passed to all the vorbisfile functions.</b></dd>
+<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile
+functions. </dd>
 <dt><i>i</i></dt>
 <dd>Link to the desired logical bitstream.  For nonseekable files, this argument is ignored.  To retrieve the vorbis_info struct for the current bitstream, this parameter should be set to -1.</dd>
 </dl>
@@ -47,18 +46,18 @@
 <li>NULL if the specified bitstream does not exist or the file has been initialized improperly.</li>
 </blockquote>
 <p>
+
 <br><br>
 <hr noshade>
 <table border=0 width=100%>
 <tr valign=top>
-<td><p class=tiny>copyright &copy; 2000 vorbis team</p></td>
-<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/index.html">Ogg Vorbis</a><br><a href="mailto:team at vorbis.org">team at vorbis.org</a></p></td>
+<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
+<td align=right><p class=tiny>Ogg Vorbis</p></td>
 </tr><tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
-
 
 </body>
 

<p><p>1.4       +20 -17    vorbis/doc/vorbisfile/ov_open.html

Index: ov_open.html
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/vorbisfile/ov_open.html,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- ov_open.html	2001/12/20 01:00:21	1.3
+++ ov_open.html	2002/07/02 21:40:29	1.4
@@ -1,15 +1,15 @@
 <html>
 
 <head>
-<title>vorbisfile - function - ov_open</title>
+<title>Vorbisfile - function - ov_open</title>
 <link rel=stylesheet href="style.css" type="text/css">
 </head>
 
 <body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
 <table border=0 width=100%>
 <tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
 
@@ -22,20 +22,24 @@
 <p>The first argument must be a file pointer to an already opened file
 or pipe (it need not be seekable--though this obviously restricts what
 can be done with the bitstream). <tt>vf</tt> should be a pointer to the
-OggVorbis_File structure--this is used for ALL the externally visible vorbisfile
+OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile
 functions. Once this has been called, the same OggVorbis_File
-struct should be passed to all the vorbisfile functions.
+struct should be passed to all the libvorbisfile functions.
 <p>Also, you should be aware that ov_open(), once successful, takes complete possession of the file resource.  After you have opened a file using ov_open(), you MUST close it using ov_clear(), not fclose() or any other function.
 <p>
 It is often useful to call <tt>ov_open()</tt>
 simply to determine whether a given file is a vorbis bitstream. If the
 <tt>ov_open()</tt>
-call fails, then the file is not recognizable as such. When you use <tt>ov_open()
+call fails, then the file is not recognizable as such. 
+When you use <tt>ov_open()
 </tt>for
 this, you should <tt>fclose()</tt> the file pointer if, and only if, the
 <tt>ov_open()</tt>
 call fails. If it succeeds, you must call ov_clear() to clear
-the decoder's buffers and close the file for you.
+the decoder's buffers and close the file for you.<p>
+
+(Note that ov_test() provides a less expensive way to test a file for Vorbisness.)<p>
+
 <br><br>
 <table border=0 color=black cellspacing=0 cellpadding=7>
 <tr bgcolor=#cccccc>
@@ -54,9 +58,9 @@
 or pipe (it need not be seekable--though this obviously restricts what
 can be done with the bitstream).</dd>
 <dt><i>vf</i></dt>
-<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible vorbisfile
+<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile
 functions. Once this has been called, the same <tt>OggVorbis_File</tt>
-struct should be passed to all the vorbisfile functions.</dd>
+struct should be passed to all the libvorbisfile functions.</dd>
 <dt><i>initial</i></dt>
 <dd>Typically set to NULL.  This parameter is useful if some data has already been
 read from the file and the stream is not seekable. It is used in conjunction with <tt>ibytes</tt>.  In this case, <tt>initial</tt>
@@ -70,8 +74,7 @@
 
 <h3>Return Values</h3>
 <blockquote>
-<li>
-0 for success</li>
+<li>0 indicates success</li>
 
 <li>less than zero for failure:</li>
 <ul>
@@ -92,20 +95,20 @@
 call, given that the full structure of the file is determined at this point,
 which may require reading large parts of the file under certain circumstances
 (determining all the logical bitstreams in one physical bitstream, for
-example).
+example).  See Thread Safety for other information on using libvorbisfile with threads.
 
+
 <br><br>
 <hr noshade>
 <table border=0 width=100%>
 <tr valign=top>
-<td><p class=tiny>copyright &copy; 2000 vorbis team</p></td>
-<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/index.html">Ogg Vorbis</a><br><a href="mailto:team at vorbis.org">team at vorbis.org</a></p></td>
+<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
+<td align=right><p class=tiny>Ogg Vorbis</p></td>
 </tr><tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
-
 
 </body>
 

<p><p>1.4       +16 -14    vorbis/doc/vorbisfile/ov_open_callbacks.html

Index: ov_open_callbacks.html
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/vorbisfile/ov_open_callbacks.html,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- ov_open_callbacks.html	2001/12/20 01:00:21	1.3
+++ ov_open_callbacks.html	2002/07/02 21:40:29	1.4
@@ -1,15 +1,15 @@
 <html>
 
 <head>
-<title>vorbisfile - function - ov_open_callbacks</title>
+<title>Vorbisfile - function - ov_open_callbacks</title>
 <link rel=stylesheet href="style.css" type="text/css">
 </head>
 
 <body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
 <table border=0 width=100%>
 <tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
 
@@ -20,7 +20,7 @@
 <p>This is an alternative function used to open and initialize an OggVorbis_File
 structure when using a data source other than a file.   It allows you to specify custom file manipulation routines and sets up all the related decoding structure.
 <p>Once this has been called, the same <tt>OggVorbis_File</tt>
-struct should be passed to all the vorbisfile functions.
+struct should be passed to all the libvorbisfile functions.
 <p>
 It is often useful to call <tt>ov_open_callbacks()</tt>
 simply to determine whether a given file is a vorbis bitstream. If the
@@ -30,7 +30,10 @@
 this, you should <tt>fclose()</tt> the file pointer if, and only if, the
 <tt>ov_open_callbacks()</tt>
 call fails. If it succeeds, you must call <a href=ov_clear.html>ov_clear()</a> to clear
-the decoder's buffers and close the file for you.
+the decoder's buffers and close the file for you.<p>
+
+See also Callbacks and Non-stdio I/O for information on designing and specifying the required callback functions.<p>
+
 <br><br>
 <table border=0 color=black cellspacing=0 cellpadding=7>
 <tr bgcolor=#cccccc>
@@ -49,9 +52,9 @@
 or pipe (it need not be seekable--though this obviously restricts what
 can be done with the bitstream).</dd>
 <dt><i>vf</i></dt>
-<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible vorbisfile
+<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile
 functions. Once this has been called, the same <tt>OggVorbis_File</tt>
-struct should be passed to all the vorbisfile functions.</dd>
+struct should be passed to all the libvorbisfile functions.</dd>
 <dt><i>initial</i></dt>
 <dd>Typically set to NULL.  This parameter is useful if some data has already been
 read from the file and the stream is not seekable. It is used in conjunction with <tt>ibytes</tt>.  In this case, <tt>initial</tt>
@@ -67,8 +70,7 @@
 
 <h3>Return Values</h3>
 <blockquote>
-<li>
-0 for success</li>
+<li>0 for success</li>
 <li>less than zero for failure:</li>
 <ul>
 <li>OV_EREAD - A read from media returned an error.</li>
@@ -89,19 +91,19 @@
 which may require reading large parts of the file under certain circumstances
 (determining all the logical bitstreams in one physical bitstream, for
 example).
+See Thread Safety for other information on using libvorbisfile with threads.
 
 <br><br>
 <hr noshade>
 <table border=0 width=100%>
 <tr valign=top>
-<td><p class=tiny>copyright &copy; 2000 vorbis team</p></td>
-<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/index.html">Ogg Vorbis</a><br><a href="mailto:team at vorbis.org">team at vorbis.org</a></p></td>
+<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
+<td align=right><p class=tiny>Ogg Vorbis</p></td>
 </tr><tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
-
 
 </body>
 

<p><p>1.4       +12 -13    vorbis/doc/vorbisfile/ov_pcm_seek.html

Index: ov_pcm_seek.html
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/vorbisfile/ov_pcm_seek.html,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- ov_pcm_seek.html	2001/12/20 01:00:21	1.3
+++ ov_pcm_seek.html	2002/07/02 21:40:29	1.4
@@ -1,15 +1,15 @@
 <html>
 
 <head>
-<title>vorbisfile - function - ov_bitrate</title>
+<title>Vorbisfile - function - ov_pcm_seek</title>
 <link rel=stylesheet href="style.css" type="text/css">
 </head>
 
 <body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
 <table border=0 width=100%>
 <tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
 
@@ -28,7 +28,7 @@
 <tr bgcolor=#cccccc>
         <td>
 <pre><b>
-int ov_pcm_seek(OggVorbis_File *vf,int64_t pos);
+int ov_pcm_seek(OggVorbis_File *vf,ogg_int64_t pos);
 </b></pre>
         </td>
 </tr>
@@ -37,7 +37,7 @@
 <h3>Parameters</h3>
 <dl>
 <dt><i>vf</i></dt>
-<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible vorbisfile
+<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile
 functions.</dd>
 <dt><i>pos</i></dt>
 <dd>Position in pcm samples to seek to in the bitstream.</dd>
@@ -46,8 +46,7 @@
 
 <h3>Return Values</h3>
 <blockquote>
-<li>
-0 for success</li>
+<li>0 for success</li>
 
 <li>
 nonzero indicates failure, described by several error codes:</li>
@@ -61,21 +60,21 @@
 <li>OV_EFAULT - Internal logic fault; indicates a bug or heap/stack 
                 corruption.
 </li>
-<li>OV_EBADLINK - Invalid stream section supplied to libvorbis/libvorbisfile, or the requested link is corrupt. 
+<li>OV_EBADLINK - Invalid stream section supplied to libvorbisfile, or the requested link is corrupt. 
 </li>
 </ul></blockquote>
+
 <br><br>
 <hr noshade>
 <table border=0 width=100%>
 <tr valign=top>
-<td><p class=tiny>copyright &copy; 2000 vorbis team</p></td>
-<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/index.html">Ogg Vorbis</a><br><a href="mailto:team at vorbis.org">team at vorbis.org</a></p></td>
+<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
+<td align=right><p class=tiny>Ogg Vorbis</p></td>
 </tr><tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
-
 
 </body>
 

<p><p>1.5       +11 -11    vorbis/doc/vorbisfile/ov_pcm_seek_page.html

Index: ov_pcm_seek_page.html
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/vorbisfile/ov_pcm_seek_page.html,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- ov_pcm_seek_page.html	2002/02/01 02:15:01	1.4
+++ ov_pcm_seek_page.html	2002/07/02 21:40:29	1.5
@@ -1,15 +1,15 @@
 <html>
 
 <head>
-<title>vorbisfile - function - ov_pcm_seek_page</title>
+<title>Vorbisfile - function - ov_pcm_seek_page</title>
 <link rel=stylesheet href="style.css" type="text/css">
 </head>
 
 <body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
 <table border=0 width=100%>
 <tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
 
@@ -38,7 +38,7 @@
 <h3>Parameters</h3>
 <dl>
 <dt><i>vf</i></dt>
-<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible vorbisfile
+<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile
 functions.</dd>
 <dt><i>pos</i></dt>
 <dd>Position in pcm samples to seek to in the bitstream.</dd>
@@ -62,21 +62,21 @@
 <li>OV_EFAULT - Internal logic fault; indicates a bug or heap/stack 
                 corruption.
 </li>
-<li>OV_EBADLINK - Invalid stream section supplied to libvorbis/libvorbisfile, or the requested link is corrupt. 
+<li>OV_EBADLINK - Invalid stream section supplied to libvorbisfile, or the requested link is corrupt. 
 </li>
-</ul></</blockquote>
+</ul></blockquote>
+
 <br><br>
 <hr noshade>
 <table border=0 width=100%>
 <tr valign=top>
-<td><p class=tiny>copyright &copy; 2000 vorbis team</p></td>
-<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/index.html">Ogg Vorbis</a><br><a href="mailto:team at vorbis.org">team at vorbis.org</a></p></td>
+<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
+<td align=right><p class=tiny>Ogg Vorbis</p></td>
 </tr><tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
-
 
 </body>
 

<p><p>1.3       +12 -10    vorbis/doc/vorbisfile/ov_pcm_tell.html

Index: ov_pcm_tell.html
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/vorbisfile/ov_pcm_tell.html,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- ov_pcm_tell.html	2000/11/06 00:06:47	1.2
+++ ov_pcm_tell.html	2002/07/02 21:40:29	1.3
@@ -1,15 +1,15 @@
 <html>
 
 <head>
-<title>vorbisfile - function - ov_pcm_tell</title>
+<title>Vorbisfile - function - ov_pcm_tell</title>
 <link rel=stylesheet href="style.css" type="text/css">
 </head>
 
 <body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
 <table border=0 width=100%>
 <tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
 
@@ -24,7 +24,7 @@
 <tr bgcolor=#cccccc>
         <td>
 <pre><b>
-int64_t ov_pcm_tell(OggVorbis_File *vf);
+ogg_int64_t ov_pcm_tell(OggVorbis_File *vf);
 </b></pre>
         </td>
 </tr>
@@ -33,7 +33,7 @@
 <h3>Parameters</h3>
 <dl>
 <dt><i>vf</i></dt>
-<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible vorbisfile
+<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile
 functions.</dd>
 </dl>
 
@@ -41,20 +41,22 @@
 <h3>Return Values</h3>
 <blockquote>
 <li><i>n</i> indicates the current offset in samples.</li>
+<li>OV_EINVAL means that the argument was invalid.  In this case, the requested bitstream did not exist.</li>
 </blockquote>
 <p>
+
+
 <br><br>
 <hr noshade>
 <table border=0 width=100%>
 <tr valign=top>
-<td><p class=tiny>copyright &copy; 2000 vorbis team</p></td>
-<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/index.html">Ogg Vorbis</a><br><a href="mailto:team at vorbis.org">team at vorbis.org</a></p></td>
+<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
+<td align=right><p class=tiny>Ogg Vorbis</p></td>
 </tr><tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
-
 
 </body>
 

<p><p>1.4       +11 -10    vorbis/doc/vorbisfile/ov_pcm_total.html

Index: ov_pcm_total.html
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/vorbisfile/ov_pcm_total.html,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- ov_pcm_total.html	2001/12/20 01:00:21	1.3
+++ ov_pcm_total.html	2002/07/02 21:40:29	1.4
@@ -1,15 +1,15 @@
 <html>
 
 <head>
-<title>vorbisfile - function - ov_pcm_total</title>
+<title>Vorbisfile - function - ov_pcm_total</title>
 <link rel=stylesheet href="style.css" type="text/css">
 </head>
 
 <body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
 <table border=0 width=100%>
 <tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
 
@@ -24,7 +24,7 @@
 <tr bgcolor=#cccccc>
         <td>
 <pre><b>
-int64_t ov_pcm_total(OggVorbis_File *vf,int i);
+ogg_int64_t ov_pcm_total(OggVorbis_File *vf,int i);
 </b></pre>
         </td>
 </tr>
@@ -33,7 +33,7 @@
 <h3>Parameters</h3>
 <dl>
 <dt><i>vf</i></dt>
-<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible vorbisfile
+<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile
 functions.</dd>
 <dt><i>i</i></dt>
 <dd>Link to the desired logical bitstream.  To retrieve the total pcm samples for the entire physical bitstream, this parameter should be set to -1.</dd>
@@ -48,18 +48,19 @@
 <li>length in pcm samples of logical bitstream if i=1 to n.</li>
 </blockquote>
 <p>
+
+
 <br><br>
 <hr noshade>
 <table border=0 width=100%>
 <tr valign=top>
-<td><p class=tiny>copyright &copy; 2000 vorbis team</p></td>
-<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/index.html">Ogg Vorbis</a><br><a href="mailto:team at vorbis.org">team at vorbis.org</a></p></td>
+<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
+<td align=right><p class=tiny>Ogg Vorbis</p></td>
 </tr><tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
-
 
 </body>
 

<p><p>1.4       +13 -15    vorbis/doc/vorbisfile/ov_raw_seek.html

Index: ov_raw_seek.html
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/vorbisfile/ov_raw_seek.html,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- ov_raw_seek.html	2001/12/20 01:00:21	1.3
+++ ov_raw_seek.html	2002/07/02 21:40:29	1.4
@@ -1,15 +1,15 @@
 <html>
 
 <head>
-<title>vorbisfile - function - ov_raw_seek</title>
+<title>Vorbisfile - function - ov_raw_seek</title>
 <link rel=stylesheet href="style.css" type="text/css">
 </head>
 
 <body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
 <table border=0 width=100%>
 <tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
 
@@ -21,7 +21,7 @@
 <p>This also updates everything needed within the
 decoder, so you can immediately call ov_read() and get data from
 the newly seeked to position.
-<p>When seek speed is a priority, this is the best vorbisfile seek funtion to use.
+<p>When seek speed is a priority, this is the best seek funtion to use.
 <br><br>
 <table border=0 color=black cellspacing=0 cellpadding=7>
 <tr bgcolor=#cccccc>
@@ -36,9 +36,8 @@
 <h3>Parameters</h3>
 <dl>
 <dt><i>vf</i></dt>
-<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible vorbisfile
-functions. Once this has been called, the same <tt>OggVorbis_File</tt>
-struct should be passed to all the vorbisfile functions.</dd>
+<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile
+functions.</dd>
 <dt><i>pos</i></dt>
 <dd>Position in compressed bytes to seek to in the bitstream.</dd>
 </dl>
@@ -46,31 +45,30 @@
 
 <h3>Return Values</h3>
 <blockquote>
-<li>
-0 indicates success</li>
+<li>0 indicates success</li>
 <li>nonzero indicates failure, described by several error codes:</li>
 <ul>
 <li>OV_ENOSEEK - Bitstream is not seekable.
 </li>
 <li>OV_EINVAL - Invalid argument value.
 </li>
-<li>OV_EBADLINK - Invalid stream section supplied to libvorbis/libvorbisfile, or the requested link is corrupt. 
+<li>OV_EBADLINK - Invalid stream section supplied to libvorbisfile, or the requested link is corrupt. 
 </li>
 </ul>
 </blockquote>
 <p>
+
 <br><br>
 <hr noshade>
 <table border=0 width=100%>
 <tr valign=top>
-<td><p class=tiny>copyright &copy; 2000 vorbis team</p></td>
-<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/index.html">Ogg Vorbis</a><br><a href="mailto:team at vorbis.org">team at vorbis.org</a></p></td>
+<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
+<td align=right><p class=tiny>Ogg Vorbis</p></td>
 </tr><tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
-
 
 </body>
 

<p><p>1.3       +12 -10    vorbis/doc/vorbisfile/ov_raw_tell.html

Index: ov_raw_tell.html
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/vorbisfile/ov_raw_tell.html,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- ov_raw_tell.html	2000/11/06 00:06:47	1.2
+++ ov_raw_tell.html	2002/07/02 21:40:29	1.3
@@ -1,15 +1,15 @@
 <html>
 
 <head>
-<title>vorbisfile - function - ov_raw_tell</title>
+<title>Vorbisfile - function - ov_raw_tell</title>
 <link rel=stylesheet href="style.css" type="text/css">
 </head>
 
 <body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
 <table border=0 width=100%>
 <tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
 
@@ -24,7 +24,7 @@
 <tr bgcolor=#cccccc>
         <td>
 <pre><b>
-int64_t ov_raw_tell(OggVorbis_File *vf);
+ogg_int64_t ov_raw_tell(OggVorbis_File *vf);
 </b></pre>
         </td>
 </tr>
@@ -33,7 +33,7 @@
 <h3>Parameters</h3>
 <dl>
 <dt><i>vf</i></dt>
-<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible vorbisfile
+<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile
 functions.</dd>
 </dl>
 
@@ -41,20 +41,22 @@
 <h3>Return Values</h3>
 <blockquote>
 <li><i>n</i> indicates the current offset in bytes.</li>
+<li>OV_EINVAL means that the argument was invalid.  In this case, the requested bitstream did not exist.</li>
 </blockquote>
 <p>
+
+
 <br><br>
 <hr noshade>
 <table border=0 width=100%>
 <tr valign=top>
-<td><p class=tiny>copyright &copy; 2000 vorbis team</p></td>
-<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/index.html">Ogg Vorbis</a><br><a href="mailto:team at vorbis.org">team at vorbis.org</a></p></td>
+<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
+<td align=right><p class=tiny>Ogg Vorbis</p></td>
 </tr><tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
-
 
 </body>
 

<p><p>1.3       +15 -13    vorbis/doc/vorbisfile/ov_raw_total.html

Index: ov_raw_total.html
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/vorbisfile/ov_raw_total.html,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- ov_raw_total.html	2000/11/06 00:06:47	1.2
+++ ov_raw_total.html	2002/07/02 21:40:29	1.3
@@ -1,15 +1,15 @@
 <html>
 
 <head>
-<title>vorbisfile - function - ov_raw_total</title>
+<title>Vorbisfile - function - ov_raw_total</title>
 <link rel=stylesheet href="style.css" type="text/css">
 </head>
 
 <body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
 <table border=0 width=100%>
 <tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
 
@@ -24,7 +24,7 @@
 <tr bgcolor=#cccccc>
         <td>
 <pre><b>
-int64_t ov_raw_total(OggVorbis_File *vf,int i);
+ogg_int64_t ov_raw_total(OggVorbis_File *vf,int i);
 </b></pre>
         </td>
 </tr>
@@ -33,33 +33,35 @@
 <h3>Parameters</h3>
 <dl>
 <dt><i>vf</i></dt>
-<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible vorbisfile
+<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile
 functions.</dd>
 <dt><i>i</i></dt>
-<dd><b>Link to the desired logical bitstream.  To retrieve the total bytes for the entire physical bitstream, this parameter should be set to -1.</b></dd>
+<dd>Link to the desired logical bitstream.  To retrieve the total bytes for the entire physical bitstream, this parameter should be set to -1.</dd>
 </dl>
 
 
 <h3>Return Values</h3>
 <blockquote>
 <li>OV_EINVAL means that the argument was invalid.  In this case, the requested bitstream did not exist or the bitstream is nonseekable</li>
-<li>
+<li><tt>n</tt>
 total length in compressed bytes of content if i=-1.</li>
-<li>length in compressed bytes of logical bitstream if i=1 to n.</li>
+<li><tt>n</tt> length in compressed bytes of logical bitstream if i=1 to n.</li>
 </blockquote>
 <p>
+
+
+
 <br><br>
 <hr noshade>
 <table border=0 width=100%>
 <tr valign=top>
-<td><p class=tiny>copyright &copy; 2000 vorbis team</p></td>
-<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/index.html">Ogg Vorbis</a><br><a href="mailto:team at vorbis.org">team at vorbis.org</a></p></td>
+<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
+<td align=right><p class=tiny>Ogg Vorbis</p></td>
 </tr><tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
-
 
 </body>
 

<p><p>1.5       +36 -30    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.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- ov_read.html	2001/03/20 08:04:04	1.4
+++ ov_read.html	2002/07/02 21:40:29	1.5
@@ -1,15 +1,15 @@
 <html>
 
 <head>
-<title>vorbisfile - function - ov_read</title>
+<title>Vorbisfile - function - ov_read</title>
 <link rel=stylesheet href="style.css" type="text/css">
 </head>
 
 <body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
 <table border=0 width=100%>
 <tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
 
@@ -18,24 +18,28 @@
 <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><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><p>
-    <tt>ov_read()</tt> passes back the index of the sequential logical
-    bitstream 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 at chaining boundaries even
-    for non-seekable streams. For seekable streams, it represents the
-    actual chaining index within the physical bitstream.
-<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.
-</p>
+   This is the main function used to decode a Vorbis file within a
+   loop.  It returns up to the specified number of bytes of decoded PCM audio
+   in the requested endianness, signedness, and word size.  If the audio is
+   multichannel, the channels are interleaved in the output buffer.
+   If the passed in buffer is large, <tt>ov_read()</tt> will not fill
+   it; the passed in buffer size is treated as a limit</em> and
+   not a request.
+<p>
+   
+Note that up to this point, the Vorbisfile API 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 reading audio back, the application must be aware
+   that multiple bitstream sections do not necessarily use the same
+   number of channels or sampling rate. <p> <tt>ov_read()</tt> passes
+   back the index of the sequential logical bitstream currently being
+   decoded (in <tt>*bitstream</tt>) along with the PCM data in order
+   that the toplevel application can handle channel and/or sample
+   rate changes. This number will be incremented at chaining
+   boundaries even for non-seekable streams. For seekable streams, it
+   represents the actual chaining index within the physical bitstream.
+<p>
 
 <br><br>
 <table border=0 color=black cellspacing=0 cellpadding=7>
@@ -51,16 +55,18 @@
 <h3>Parameters</h3>
 <dl>
 <dt><i>vf</i></dt>
-<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible vorbisfile
+<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile
 functions.</dd>
 <dt><i>buffer</i></dt>
 <dd>A pointer to an output buffer.  The decoded output is inserted into this buffer.</dd>
 <dt><i>length</i></dt>
 <dd>Number of bytes to be read into the buffer. Should be the same size as the buffer.  A typical value is 4096.</dd>
 <dt><i>bigendianp</i></dt>
-<dd>Specifies big or little endian byte packing.  0 for little endian, 1 for big endian.  Typical value is 0.</dd>
+<dd>Specifies big or little endian byte packing.  0 for little endian, 1 for b
+ig endian.  Typical value is 0.</dd>
 <dt><i>word</i></dt>
-<dd>Specifies word size.  Possible arguments are 1 for 8-bit samples, or 2 or 16-bit samples.  Typical value is 2.</dd>
+<dd>Specifies word size.  Possible arguments are 1 for 8-bit samples, or 2 or 
+16-bit samples.  Typical value is 2.</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>
@@ -98,19 +104,19 @@
 little-endian samples.
 </p>
 
-<br>
+
+
 <br><br>
 <hr noshade>
 <table border=0 width=100%>
 <tr valign=top>
-<td><p class=tiny>copyright &copy; 2000 vorbis team</p></td>
-<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/index.html">Ogg Vorbis</a><br><a href="mailto:team at vorbis.org">team at vorbis.org</a></p></td>
+<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
+<td align=right><p class=tiny>Ogg Vorbis</p></td>
 </tr><tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
-
 
 </body>
 

<p><p>1.2       +8 -5      vorbis/doc/vorbisfile/ov_read_float.html

Index: ov_read_float.html
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/vorbisfile/ov_read_float.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- ov_read_float.html	2001/12/19 02:00:47	1.1
+++ ov_read_float.html	2002/07/02 21:40:29	1.2
@@ -1,7 +1,7 @@
 <html>
 
 <head>
-<title>vorbisfile - function - ov_read_float</title>
+<title>Vorbisfile - function - ov_read_float</title>
 <link rel=stylesheet href="style.css" type="text/css">
 </head>
 
@@ -9,7 +9,7 @@
 <table border=0 width=100%>
 <tr>
 <td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile - 20011218</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
 
@@ -74,7 +74,7 @@
 bytes_read = ov_read_float(&amp;vf,pcm,&amp;current_section)</tt>
 </blockquote>
 
-This decodes one packets worth of float samples.
+This decodes one packet's worth of float samples.
 </p>
 
 <br>
@@ -82,11 +82,11 @@
 <hr noshade>
 <table border=0 width=100%>
 <tr valign=top>
-<td><p class=tiny>copyright &copy; 2001 vorbis team</p></td>
+<td><p class=tiny>copyright &copy; 2002 vorbis team</p></td>
 <td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/index.html">Ogg Vorbis</a><br><a href="mailto:team at vorbis.org">team at vorbis.org</a></p></td>
 </tr><tr>
 <td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile - 20011218</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
 
@@ -94,3 +94,6 @@
 </body>
 
 </html>
+
+
+

<p><p>1.3       +12 -14    vorbis/doc/vorbisfile/ov_seekable.html

Index: ov_seekable.html
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/vorbisfile/ov_seekable.html,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- ov_seekable.html	2000/11/06 00:06:47	1.2
+++ ov_seekable.html	2002/07/02 21:40:29	1.3
@@ -1,15 +1,15 @@
 <html>
 
 <head>
-<title>vorbisfile - function - ov_seekable</title>
+<title>Vorbisfile - function - ov_seekable</title>
 <link rel=stylesheet href="style.css" type="text/css">
 </head>
 
 <body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
 <table border=0 width=100%>
 <tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
 
@@ -34,31 +34,29 @@
 <h3>Parameters</h3>
 <dl>
 <dt><i>vf</i></dt>
-<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible vorbisfile
-functions. <b>Once this has been called, the same <tt>OggVorbis_File</tt>
-struct should be passed to all the vorbisfile functions.</b></dd>
+<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile
+functions.</dd>
 </dl>
 
 
 <h3>Return Values</h3>
 <blockquote>
-<li>
-0 indicates that the file is not seekable.</li>
-<li>1 indicates that the file is seekable.</li>
+<li>0 indicates that the file is not seekable.</li>
+<li>nonzero indicates that the file is seekable.</li>
 </blockquote>
 <p>
+
 <br><br>
 <hr noshade>
 <table border=0 width=100%>
 <tr valign=top>
-<td><p class=tiny>copyright &copy; 2000 vorbis team</p></td>
-<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/index.html">Ogg Vorbis</a><br><a href="mailto:team at vorbis.org">team at vorbis.org</a></p></td>
+<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
+<td align=right><p class=tiny>Ogg Vorbis</p></td>
 </tr><tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
-
 
 </body>
 

<p><p>1.3       +13 -13    vorbis/doc/vorbisfile/ov_serialnumber.html

Index: ov_serialnumber.html
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/vorbisfile/ov_serialnumber.html,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- ov_serialnumber.html	2000/11/06 00:06:47	1.2
+++ ov_serialnumber.html	2002/07/02 21:40:29	1.3
@@ -1,15 +1,15 @@
 <html>
 
 <head>
-<title>vorbisfile - function - ov_serialnumber</title>
+<title>Vorbisfile - function - ov_serialnumber</title>
 <link rel=stylesheet href="style.css" type="text/css">
 </head>
 
 <body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
 <table border=0 width=100%>
 <tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
 
@@ -17,7 +17,7 @@
 
 <p><i>declared in "vorbis/vorbisfile.h";</i></p>
 
-<p>Returns the serialnumber of the specified logical bitstream.
+<p>Returns the serialnumber of the specified logical bitstream link number within the overall physical bitstream.
 
 <br><br>
 <table border=0 color=black cellspacing=0 cellpadding=7>
@@ -33,11 +33,10 @@
 <h3>Parameters</h3>
 <dl>
 <dt><i>vf</i></dt>
-<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible vorbisfile
-functions. Once this has been called, the same <tt>OggVorbis_File</tt>
-struct should be passed to all the vorbisfile functions.</dd>
+<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile
+functions.</dd>
 <dt><i>i</i></dt>
-<dd><b>Link to the desired logical bitstream.  For nonseekable files, this argument is ignored.  To retrieve the vorbis_info struct for the current bitstream, this parameter should be set to -1.</b></dd>
+<dd>Link to the desired logical bitstream.  For nonseekable files, this argument is ignored.  To retrieve the serial number of the current bitstream, this parameter should be set to -1.</dd>
 </dl>
 
 
@@ -49,18 +48,19 @@
 <li>Returns the serial number of the logical bitstream <i>i</i> or the serial number of the current bitstream if the file is nonseekable.</li>
 </blockquote>
 <p>
+
+
 <br><br>
 <hr noshade>
 <table border=0 width=100%>
 <tr valign=top>
-<td><p class=tiny>copyright &copy; 2000 vorbis team</p></td>
-<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/index.html">Ogg Vorbis</a><br><a href="mailto:team at vorbis.org">team at vorbis.org</a></p></td>
+<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
+<td align=right><p class=tiny>Ogg Vorbis</p></td>
 </tr><tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
-
 
 </body>
 

<p><p>1.3       +10 -11    vorbis/doc/vorbisfile/ov_streams.html

Index: ov_streams.html
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/vorbisfile/ov_streams.html,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- ov_streams.html	2000/11/06 00:06:47	1.2
+++ ov_streams.html	2002/07/02 21:40:29	1.3
@@ -1,15 +1,15 @@
 <html>
 
 <head>
-<title>vorbisfile - function - ov_streams</title>
+<title>Vorbisfile - function - ov_streams</title>
 <link rel=stylesheet href="style.css" type="text/css">
 </head>
 
 <body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
 <table border=0 width=100%>
 <tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
 
@@ -33,9 +33,8 @@
 <h3>Parameters</h3>
 <dl>
 <dt><i>vf</i></dt>
-<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible vorbisfile
-functions. <b>Once this has been called, the same <tt>OggVorbis_File</tt>
-struct should be passed to all the vorbisfile functions.</b></dd>
+<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile
+functions. </dd>
 </dl>
 
 
@@ -47,18 +46,18 @@
 </blockquote>
 <p>
 
+
 <br><br>
 <hr noshade>
 <table border=0 width=100%>
 <tr valign=top>
-<td><p class=tiny>copyright &copy; 2000 vorbis team</p></td>
-<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/index.html">Ogg Vorbis</a><br><a href="mailto:team at vorbis.org">team at vorbis.org</a></p></td>
+<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
+<td align=right><p class=tiny>Ogg Vorbis</p></td>
 </tr><tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
-
 
 </body>
 

<p><p>1.3       +12 -12    vorbis/doc/vorbisfile/ov_test.html

Index: ov_test.html
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/vorbisfile/ov_test.html,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- ov_test.html	2001/12/20 01:00:21	1.2
+++ ov_test.html	2002/07/02 21:40:29	1.3
@@ -1,15 +1,15 @@
 <html>
 
 <head>
-<title>vorbisfile - function - ov_test</title>
+<title>Vorbisfile - function - ov_test</title>
 <link rel=stylesheet href="style.css" type="text/css">
 </head>
 
 <body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
 <table border=0 width=100%>
 <tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile - 20011218</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
 
@@ -41,9 +41,9 @@
 or pipe (it need not be seekable--though this obviously restricts what
 can be done with the bitstream).</dd>
 <dt><i>vf</i></dt>
-<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible vorbisfile
+<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile
 functions. Once this has been called, the same <tt>OggVorbis_File</tt>
-struct should be passed to all the vorbisfile functions.</dd>
+struct should be passed to all the libvorbisfile functions.</dd>
 <dt><i>initial</i></dt>
 <dd>Typically set to NULL.  This parameter is useful if some data has already been
 read from the file and the stream is not seekable. It is used in conjunction with <tt>ibytes</tt>.  In this case, <tt>initial</tt>
@@ -57,8 +57,7 @@
 
 <h3>Return Values</h3>
 <blockquote>
-<li>
-0 for success</li>
+<li>0 for success</li>
 
 <li>less than zero for failure:</li>
 <ul>
@@ -71,18 +70,19 @@
 </blockquote>
 <p>
 
+
+
 <br><br>
 <hr noshade>
 <table border=0 width=100%>
 <tr valign=top>
-<td><p class=tiny>copyright &copy; 2001 vorbis team</p></td>
-<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/index.html">Ogg Vorbis</a><br><a href="mailto:team at vorbis.org">team at vorbis.org</a></p></td>
+<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
+<td align=right><p class=tiny>Ogg Vorbis</p></td>
 </tr><tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile - 20011218</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
-
 
 </body>
 

<p><p>1.3       +16 -14    vorbis/doc/vorbisfile/ov_test_callbacks.html

Index: ov_test_callbacks.html
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/vorbisfile/ov_test_callbacks.html,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- ov_test_callbacks.html	2001/12/20 01:00:21	1.2
+++ ov_test_callbacks.html	2002/07/02 21:40:29	1.3
@@ -1,15 +1,15 @@
 <html>
 
 <head>
-<title>vorbisfile - function - ov_test_callbacks</title>
+<title>Vorbisfile - function - ov_test_callbacks</title>
 <link rel=stylesheet href="style.css" type="text/css">
 </head>
 
 <body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
 <table border=0 width=100%>
 <tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile - 20011218</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
 
@@ -18,9 +18,9 @@
 <p><i>declared in "vorbis/vorbisfile.h";</i></p>
 
 <p>This is an alternative function used to open and test an OggVorbis_File
-structure when using a data source other than a file.   It allows you to specify custom file manipulation routines and sets up all the related decoding structure.
+structure when using a data source other than a file.   It allows you to specify custom file manipulation routines and sets up all the related decoding structures.
 <p>Once this has been called, the same <tt>OggVorbis_File</tt>
-struct should be passed to all the vorbisfile functions.
+struct should be passed to all the libvorbisfile functions.
 <p>
 <br><br>
 <table border=0 color=black cellspacing=0 cellpadding=7>
@@ -40,9 +40,9 @@
 or pipe (it need not be seekable--though this obviously restricts what
 can be done with the bitstream).</dd>
 <dt><i>vf</i></dt>
-<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible vorbisfile
+<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile
 functions. Once this has been called, the same <tt>OggVorbis_File</tt>
-struct should be passed to all the vorbisfile functions.</dd>
+struct should be passed to all the libvorbisfile functions.</dd>
 <dt><i>initial</i></dt>
 <dd>Typically set to NULL.  This parameter is useful if some data has already been
 read from the file and the stream is not seekable. It is used in conjunction with <tt>ibytes</tt>.  In this case, <tt>initial</tt>
@@ -58,8 +58,7 @@
 
 <h3>Return Values</h3>
 <blockquote>
-<li>
-0 for success</li>
+<li>0 for success</li>
 <li>less than zero for failure:</li>
 <ul>
 <li>OV_EREAD - A read from media returned an error.</li>
@@ -71,17 +70,20 @@
 </blockquote>
 <p>
 
+
+
+
+<br><br>
 <hr noshade>
 <table border=0 width=100%>
 <tr valign=top>
-<td><p class=tiny>copyright &copy; 2001 vorbis team</p></td>
-<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/index.html">Ogg Vorbis</a><br><a href="mailto:team at vorbis.org">team at vorbis.org</a></p></td>
+<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
+<td align=right><p class=tiny>Ogg Vorbis</p></td>
 </tr><tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile - 20011218</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
-
 
 </body>
 

<p><p>1.3       +17 -10    vorbis/doc/vorbisfile/ov_test_open.html

Index: ov_test_open.html
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/vorbisfile/ov_test_open.html,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- ov_test_open.html	2001/12/20 01:00:21	1.2
+++ ov_test_open.html	2002/07/02 21:40:29	1.3
@@ -1,15 +1,15 @@
 <html>
 
 <head>
-<title>vorbisfile - function - ov_test_open</title>
+<title>Vorbisfile - function - ov_test_open</title>
 <link rel=stylesheet href="style.css" type="text/css">
 </head>
 
 <body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
 <table border=0 width=100%>
 <tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile - 20011218</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
 
@@ -35,9 +35,9 @@
 <h3>Parameters</h3>
 <dl>
 <dt><i>vf</i></dt>
-<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible vorbisfile
+<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile
 functions. Once this has been called, the same <tt>OggVorbis_File</tt>
-struct should be passed to all the vorbisfile functions.</dd>
+struct should be passed to all the libvorbisfile functions.</dd>
 </dl>
 
 
@@ -57,19 +57,26 @@
 </blockquote>
 <p>
 
+
 <br><br>
 <hr noshade>
 <table border=0 width=100%>
 <tr valign=top>
-<td><p class=tiny>copyright &copy; 2001 vorbis team</p></td>
-<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/index.html">Ogg Vorbis</a><br><a href="mailto:team at vorbis.org">team at vorbis.org</a></p></td>
+<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
+<td align=right><p class=tiny>Ogg Vorbis</p></td>
 </tr><tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile - 20011218</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
 
-
 </body>
 
 </html>
+
+
+
+
+
+
+

<p><p>1.3       +10 -11    vorbis/doc/vorbisfile/ov_time_seek.html

Index: ov_time_seek.html
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/vorbisfile/ov_time_seek.html,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- ov_time_seek.html	2000/11/06 00:06:47	1.2
+++ ov_time_seek.html	2002/07/02 21:40:29	1.3
@@ -1,15 +1,15 @@
 <html>
 
 <head>
-<title>vorbisfile - function - ov_time_seek</title>
+<title>Vorbisfile - function - ov_time_seek</title>
 <link rel=stylesheet href="style.css" type="text/css">
 </head>
 
 <body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
 <table border=0 width=100%>
 <tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
 
@@ -21,14 +21,14 @@
 streams, this seeks to the given time. For implementing seeking in a player,
 this is the only function generally needed. This also updates everything needed within the
 decoder, so you can immediately call ov_read() and get data from
-the newly seeked to position.  For obvious reasons, this doesn't work for unseekable streams.
+the newly seeked to position.  This function does not work for unseekable streams.
 
 <br><br>
 <table border=0 color=black cellspacing=0 cellpadding=7>
 <tr bgcolor=#cccccc>
         <td>
 <pre><b>
-int ov_time_seek(OggVorbis_File *vf, double seconds);
+int ov_time_seek(OggVorbis_File *vf, double s);
 </b></pre>
         </td>
 </tr>
@@ -38,7 +38,7 @@
 <dl>
 <dt><i>vf</i></dt>
 <dd>Pointer to our already opened and initialized OggVorbis_File structure.</dd>
-<dt><i>seconds</i></dt>
+<dt><i>ms</i></dt>
 <dd>Location to seek to within the file, specified in seconds.</dd>
 </dl>
 
@@ -57,14 +57,13 @@
 <hr noshade>
 <table border=0 width=100%>
 <tr valign=top>
-<td><p class=tiny>copyright &copy; 2000 vorbis team</p></td>
-<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/index.html">Ogg Vorbis</a><br><a href="mailto:team at vorbis.org">team at vorbis.org</a></p></td>
+<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
+<td align=right><p class=tiny>Ogg Vorbis</p></td>
 </tr><tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
-
 
 </body>
 

<p><p>1.4       +11 -12    vorbis/doc/vorbisfile/ov_time_seek_page.html

Index: ov_time_seek_page.html
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/vorbisfile/ov_time_seek_page.html,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- ov_time_seek_page.html	2001/12/20 01:00:21	1.3
+++ ov_time_seek_page.html	2002/07/02 21:40:29	1.4
@@ -1,15 +1,15 @@
 <html>
 
 <head>
-<title>vorbisfile - function - ov_time_seek_page</title>
+<title>Vorbisfile - function - ov_time_seek_page</title>
 <link rel=stylesheet href="style.css" type="text/css">
 </head>
 
 <body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
 <table border=0 width=100%>
 <tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
 
@@ -22,14 +22,14 @@
 <p>This function also updates everything needed within the
 decoder, so you can immediately call ov_read() and get data from
 the newly seeked to position.  
-<p>For obvious reasons, this doesn't work for unseekable streams.
+<p>This function does not work for unseekable streams.
 
 <br><br>
 <table border=0 color=black cellspacing=0 cellpadding=7>
 <tr bgcolor=#cccccc>
         <td>
 <pre><b>
-int ov_time_seek_page(OggVorbis_File *vf, double seconds);
+int ov_time_seek_page(OggVorbis_File *vf, double s);
 </b></pre>
         </td>
 </tr>
@@ -39,7 +39,7 @@
 <dl>
 <dt><i>vf</i></dt>
 <dd>Pointer to our already opened and initialized OggVorbis_File structure.</dd>
-<dt><i>seconds</i></dt>
+<dt><i>ms</i></dt>
 <dd>Location to seek to within the file, specified in seconds.</dd>
 </dl>
 
@@ -61,7 +61,7 @@
 <li>OV_EFAULT - Internal logic fault; indicates a bug or heap/stack 
                 corruption.
 </li>
-<li>OV_EBADLINK - Invalid stream section supplied to libvorbis/libvorbisfile, or the requested link is corrupt. 
+<li>OV_EBADLINK - Invalid stream section supplied to libvorbisfile, or the requested link is corrupt. 
 </li>
 </ul></blockquote>
 
@@ -70,14 +70,13 @@
 <hr noshade>
 <table border=0 width=100%>
 <tr valign=top>
-<td><p class=tiny>copyright &copy; 2000 vorbis team</p></td>
-<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/index.html">Ogg Vorbis</a><br><a href="mailto:team at vorbis.org">team at vorbis.org</a></p></td>
+<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
+<td align=right><p class=tiny>Ogg Vorbis</p></td>
 </tr><tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
-
 
 </body>
 

<p><p>1.3       +13 -13    vorbis/doc/vorbisfile/ov_time_tell.html

Index: ov_time_tell.html
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/vorbisfile/ov_time_tell.html,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- ov_time_tell.html	2000/11/06 00:06:47	1.2
+++ ov_time_tell.html	2002/07/02 21:40:29	1.3
@@ -1,15 +1,15 @@
 <html>
 
 <head>
-<title>vorbisfile - function - ov_bitrate</title>
+<title>Vorbisfile - function - ov_time_tell</title>
 <link rel=stylesheet href="style.css" type="text/css">
 </head>
 
 <body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
 <table border=0 width=100%>
 <tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
 
@@ -17,7 +17,7 @@
 
 <p><i>declared in "vorbis/vorbisfile.h";</i></p>
 
-<p>Returns the current offset in seconds.
+<p>Returns the current decoding offset in seconds.
 
 <br><br>
 <table border=0 color=black cellspacing=0 cellpadding=7>
@@ -33,30 +33,30 @@
 <h3>Parameters</h3>
 <dl>
 <dt><i>vf</i></dt>
-<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible vorbisfile
-functions. <b>Once this has been called, the same <tt>OggVorbis_File</tt>
-struct should be passed to all the vorbisfile functions.</b></dd>
+<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile
+functions.</dd>
 </dl>
 
 
 <h3>Return Values</h3>
 <blockquote>
-<li><i>n</i> indicates the current offset in bytes.</li>
+<li><i>n</i> indicates the current decoding time offset in seconds.</li>
+<li>OV_EINVAL means that the argument was invalid.  In this case, the requested bitstream did not exist.</li>
 </blockquote>
 <p>
 
+
 <br><br>
 <hr noshade>
 <table border=0 width=100%>
 <tr valign=top>
-<td><p class=tiny>copyright &copy; 2000 vorbis team</p></td>
-<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/index.html">Ogg Vorbis</a><br><a href="mailto:team at vorbis.org">team at vorbis.org</a></p></td>
+<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
+<td align=right><p class=tiny>Ogg Vorbis</p></td>
 </tr><tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
-
 
 </body>
 

<p><p>1.3       +13 -20    vorbis/doc/vorbisfile/ov_time_total.html

Index: ov_time_total.html
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/vorbisfile/ov_time_total.html,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- ov_time_total.html	2000/11/06 00:06:47	1.2
+++ ov_time_total.html	2002/07/02 21:40:29	1.3
@@ -1,15 +1,15 @@
 <html>
 
 <head>
-<title>vorbisfile - function - ov_time_total</title>
+<title>Vorbisfile - function - ov_time_total</title>
 <link rel=stylesheet href="style.css" type="text/css">
 </head>
 
 <body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
 <table border=0 width=100%>
 <tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
 
@@ -35,39 +35,32 @@
 <h3>Parameters</h3>
 <dl>
 <dt><i>vf</i></dt>
-<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible vorbisfile
-functions. Once this has been called, the same <tt>OggVorbis_File</tt>
-struct should be passed to all the vorbisfile functions.</dd>
+<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile
+functions.</dd>
 <dt><i>i</i></dt>
-<dd><b>Link to the desired logical bitstream.  To retrieve the vorbis_info struct for the current bitstream, this parameter should be set to -1.</b></dd>
+<dd>Link to the desired logical bitstream.  To retrieve the time total for the entire physical bitstream, this parameter should be set to -1.</b></dd>
 </dl>
 
 
 <h3>Return Values</h3>
 <blockquote>
 <li>OV_EINVAL means that the argument was invalid.  In this case, the requested bitstream did not exist or the bitstream is nonseekable.</li>
-<li>
-total length in seconds of content if i=-1.</li>
-<li>length in seconds of logical bitstream if i=1 to n.</li>
+<li><tt>n</tt> total length in seconds of content if i=-1.</li>
+<li><tt>n</tt> length in seconds of logical bitstream if i=1 to n.</li>
 </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.
-<br>
+
 <br><br>
 <hr noshade>
 <table border=0 width=100%>
 <tr valign=top>
-<td><p class=tiny>copyright &copy; 2000 vorbis team</p></td>
-<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/index.html">Ogg Vorbis</a><br><a href="mailto:team at vorbis.org">team at vorbis.org</a></p></td>
+<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
+<td align=right><p class=tiny>Ogg Vorbis</p></td>
 </tr><tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
-
 
 </body>
 

<p><p>1.4       +26 -10    vorbis/doc/vorbisfile/overview.html

Index: overview.html
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/vorbisfile/overview.html,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- overview.html	2001/12/20 01:00:21	1.3
+++ overview.html	2002/07/02 21:40:29	1.4
@@ -1,23 +1,27 @@
 <html>
 
 <head>
-<title>libvorbisfile - API Overview</title>
+<title>Vorbisfile - API Overview</title>
 <link rel=stylesheet href="style.css" type="text/css">
 </head>
 
 <body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
 <table border=0 width=100%>
 <tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
 
-<h1>VorbisFile API Overview</h1>
+<h1>Vorbisfile API Overview</h1>
 
-<p>The makeup of the vorbisfile API is relatively simple.  It revolves around a single file resource.  This resource is passed to the Vorbisfile API, where it is opened, manipulated, and closed, in the form of an OggVorbis_File struct.
+<p>The makeup of the Vorbisfile libvorbisfile library API is relatively
+simple.  It revolves around a single file resource.  This file resource is
+passed to libvorbisfile, where it is opened, manipulated, and closed,
+in the form of an OggVorbis_File
+struct.
 <p>
-The vorbisfile API consists of the following functional categories:
+The Vorbisfile API consists of the following functional categories:
 <p>
 <ul>
 <li><p>Base data structures
@@ -26,19 +30,31 @@
 <li><p>Seeking
 <li><p>File Information
 </ul>
+<p>
+In addition, the following subjects deserve attention additional to
+the above general overview:
+<p>
+<ul>
+<li><p>Threading and thread safety
+<li><p><a href="callbacks.html">Using [non stdio] custom stream I/O
+via callbacks</a>
+</ul>
+<p>
+
 
 <br><br>
 <hr noshade>
 <table border=0 width=100%>
 <tr valign=top>
-<td><p class=tiny>copyright &copy; 2000 vorbis team</p></td>
-<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/index.html">Ogg Vorbis</a><br><a href="mailto:team at vorbis.org">team at vorbis.org</a></p></td>
+<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
+<td align=right><p class=tiny>Ogg Vorbis</p></td>
 </tr><tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
 
 </body>
 
 </html>
+

<p><p>1.4       +12 -7     vorbis/doc/vorbisfile/reference.html

Index: reference.html
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/vorbisfile/reference.html,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- reference.html	2001/12/19 02:00:47	1.3
+++ reference.html	2002/07/02 21:40:29	1.4
@@ -8,8 +8,8 @@
 <body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
 <table border=0 width=100%>
 <tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile - 20011218</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
 
@@ -32,12 +32,13 @@
 <br>
 <b>Decoding</b><br>
 <a href="ov_read.html">ov_read()</a><br>
-ov_read_float()<br>
 <br>
 <b>Seeking</b><br>
 <a href="ov_raw_seek.html">ov_raw_seek()</a><br>
 <a href="ov_pcm_seek.html">ov_pcm_seek()</a><br>
 <a href="ov_time_seek.html">ov_time_seek()</a><br>
+ov_pcm_seek_page()<br>
+ov_time_seek_page()<br>
 <br>
 <b>File Information</b><br>
 <a href="ov_bitrate.html">ov_bitrate()</a><br>
@@ -53,15 +54,19 @@
 <a href="ov_time_tell.html">ov_time_tell()</a><br>
 <a href="ov_info.html">ov_info()</a><br>
 <a href="ov_comment.html">ov_comment()</a><br>
+<br>
+<b>Return Codes</b><br>
+
+
 <br><br>
 <hr noshade>
 <table border=0 width=100%>
 <tr valign=top>
-<td><p class=tiny>copyright &copy; 2001 vorbis team</p></td>
-<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/index.html">Ogg Vorbis</a><br><a href="mailto:team at vorbis.org">team at vorbis.org</a></p></td>
+<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
+<td align=right><p class=tiny>Ogg Vorbis</p></td>
 </tr><tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile - 20011218</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
 

<p><p>1.3       +24 -17    vorbis/doc/vorbisfile/seeking.html

Index: seeking.html
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/vorbisfile/seeking.html,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- seeking.html	2000/11/06 00:06:47	1.2
+++ seeking.html	2002/07/02 21:40:29	1.3
@@ -1,24 +1,32 @@
 <html>
 
 <head>
-<title>vorbisfile - Seeking</title>
+<title>Vorbisfile - Seeking</title>
 <link rel=stylesheet href="style.css" type="text/css">
 </head>
 
 <body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
 <table border=0 width=100%>
 <tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
 
 <h1>Seeking</h1>
 <p>Seeking functions allow you to specify a specific point in the stream to begin or continue decoding.
 <p>
-All the <b>vorbisfile</b> seeking routines are declared in "vorbis/vorbisfile.h".
-<p>
-<p>Certain seeking functions are best suited to different situations.  When speed is important, page-level seeking should be used.
+All libvorbisfile seeking routines are declared in "vorbis/vorbisfile.h".
+
+<p>Certain seeking functions are best suited to different situations.
+When speed is important and exact positioning isn't required,
+page-level seeking should be used.  Note also that Vorbis files do not
+necessarily start at a sample number or time offset of zero.  Do not
+be surprised if a file begins at a positive offset of several minutes
+or hours, such as would happen if a large stream (such as a concert
+recording) is chopped into multiple separate files.  Requesting to
+seek to a position before the beginning of such a file will seek to
+the position where audio begins.<p>
 
 </ul>
 
@@ -29,23 +37,23 @@
 </tr>
 <tr valign=top>
         <td>ov_raw_seek</td>
-	<td>This function seeks to a specific byte in the bitstream, specified in bytes.</td>
+	<td>This function seeks to a position specified in the compressed bitstream, specified in bytes.</td>
 </tr>
 <tr valign=top>
         <td>ov_pcm_seek</td>
-	<td>This function seeks to a specific point in the bitstream, specified in pcm samples.</td>
+	<td>This function seeks to a specific audio sample number, specified in pcm samples.</td>
 </tr>
 <tr valign=top>
-	<td>ov_pcm_seek_page</td>
-	<td>This function seeks to the closest page preceding a point in the bitstream, specified in pcm samples.</td>
+	<td>ov_pcm_seek_page</td>
+	<td>This function seeks to the closest page preceding the specified audio sample number, specified in pcm samples.</td>
 </tr>
 <tr valign=top>
         <td>ov_time_seek</td>
-	<td>This function seeks to a time in the bitstream, specified in seconds.  The easiest and simplest seeking method.</td>
+	<td>This function seeks to the specific time location in the bitstream, specified in integer milliseconds.  Note that this differs from the reference vorbisfile implementation, which takes seconds as a float. </td>
 </tr>
 <tr valign=top>
         <td>ov_time_seek_page</td>
-	<td>This function seeks to the closest page preceding a time in the bitstream, specified in seconds.</td>
+	<td>This function seeks to the closest page preceding the specified time position in the bitstream, specified in integer milliseconds.</td>
 </tr>
 </table>
 
@@ -53,14 +61,13 @@
 <hr noshade>
 <table border=0 width=100%>
 <tr valign=top>
-<td><p class=tiny>copyright &copy; 2000 vorbis team</p></td>
-<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/index.html">Ogg Vorbis</a><br><a href="mailto:team at vorbis.org">team at vorbis.org</a></p></td>
+<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
+<td align=right><p class=tiny>Ogg Vorbis</p></td>
 </tr><tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
-
 
 </body>
 

<p><p>1.3       +13 -10    vorbis/doc/vorbisfile/vorbis_comment.html

Index: vorbis_comment.html
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/vorbisfile/vorbis_comment.html,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- vorbis_comment.html	2000/11/06 00:06:47	1.2
+++ vorbis_comment.html	2002/07/02 21:40:29	1.3
@@ -1,15 +1,15 @@
 <html>
 
 <head>
-<title>vorbisfile - datatype - vorbis_comment</title>
+<title>Vorbisfile - datatype - vorbis_comment</title>
 <link rel=stylesheet href="style.css" type="text/css">
 </head>
 
 <body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
 <table border=0 width=100%>
 <tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
 
@@ -31,8 +31,9 @@
 <pre><b>typedef struct vorbis_comment{
   /* unlimited user comment fields. */
   char **user_comments;
-  int    comments;
-  char  *vendor;
+  int  *comment_lengths;
+  int  comments;
+  char *vendor;
 
 } vorbis_comment;</b></pre>
         </td>
@@ -42,7 +43,9 @@
 <h3>Parameters</h3>
 <dl>
 <dt><i>user_comments</i></dt>
-<dd>Unlimited user comment array.  Comments stored in normal C 0-terminated strings.</dd>
+<dd>Unlimited user comment array. The individual strings in the array are 8 bit clean, by the Vorbis specification, and as such the <tt>comment_lengths</tt> array should be consulted to determine string length.  For convenience, each string is also NULL-terminated by the decode library (although Vorbis comments are not NULL terminated within the bitstream itself).</dd>
+<dt><i>comment_lengths</i></dt>
+<dd>An int array that stores the length of each comment string</dd>
 <dt><i>comments</i></dt>
 <dd>Int signifying number of user comments in user_comments field.</dd>
 <dt><i>vendor</i></dt>
@@ -54,11 +57,11 @@
 <hr noshade>
 <table border=0 width=100%>
 <tr valign=top>
-<td><p class=tiny>copyright &copy; 2000 vorbis team</p></td>
-<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/index.html">Ogg Vorbis</a><br><a href="mailto:team at vorbis.org">team at vorbis.org</a></p></td>
+<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
+<td align=right><p class=tiny>Ogg Vorbis</p></td>
 </tr><tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
 

<p><p>1.3       +15 -37    vorbis/doc/vorbisfile/vorbis_info.html

Index: vorbis_info.html
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/vorbisfile/vorbis_info.html,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- vorbis_info.html	2000/11/06 00:06:47	1.2
+++ vorbis_info.html	2002/07/02 21:40:29	1.3
@@ -1,15 +1,15 @@
 <html>
 
 <head>
-<title>vorbisfile - datatype - vorbis_info</title>
+<title>Vorbisfile - datatype - vorbis_info</title>
 <link rel=stylesheet href="style.css" type="text/css">
 </head>
 
 <body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
 <table border=0 width=100%>
 <tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
 
@@ -18,8 +18,7 @@
 <p><i>declared in "vorbis/codec.h"</i></p>
 
 <p>
-The vorbis_info structure contains information about a vorbis bitstream.  Most of the information in this struct is more complex and in-depth than we need for vorbisfile decoding.  However, the info's there if we need or want it.
-
+The vorbis_info structure contains basic information about the audio in a vorbis bitstream.
 <p>
 
 <table border=0 width=100% color=black cellspacing=0 cellpadding=7>
@@ -33,33 +32,9 @@
   long bitrate_upper;
   long bitrate_nominal;
   long bitrate_lower;
-
-  long blocksizes[2];
+  long bitrate_window;
 
-  int        modes;
-  int        maps;
-  int        times;
-  int        floors;
-  int        residues;
-  int        books;
-  int        psys;     /* encode only */
-
-  vorbis_info_mode    *mode_param[64];
-  int                  map_type[64];
-  vorbis_info_mapping *map_param[64];
-  int                  time_type[64];
-  vorbis_info_time    *time_param[64];
-  int                  floor_type[64];
-  vorbis_info_floor   *floor_param[64];
-  int                  residue_type[64];
-  vorbis_info_residue *residue_param[64];
-  static_codebook     *book_param[256];
-  vorbis_info_psy     *psy_param[64]; /* encode only */
-  
-  /* for block long/sort tuning; encode only */
-  int        envelopesa;
-  double     preecho_thresh;
-  double     preecho_clamp;
+  void *codec_setup;
 
 } vorbis_info;</b></pre>
         </td>
@@ -80,8 +55,11 @@
 <dd>Specifies the average bitrate for a VBR bitstream.  May be unset.  If the bitrate_upper and bitrate_lower parameters match, the stream is fixed bitrate.</dd>
 <dt><i>bitrate_lower</i></dt>
 <dd>Specifies the lower limit in a VBR bitstream.  If the value matches the bitrate_nominal and bitrate_upper parameters, the stream is fixed bitrate.  May be unset if no limit exists.</dd>
-<dt><i>blocksizes[2]</i></dt>
-<dd>Contains the sizes of the long and short blocks for this particular bitstream.  These are variable and can be set by the encoder.  Vorbis only supports two sizes, long and short.</dd>
+<dt><i>bitrate_window</i></dt>
+<dd>Currently unset.</dd>
+
+<dt><i>codec_setup</i></dt>
+<dd>Internal structure that contains the detailed/unpacked configuration for decoding the current Vorbis bitstream.</dd>
 </dl>
 
 
@@ -89,11 +67,11 @@
 <hr noshade>
 <table border=0 width=100%>
 <tr valign=top>
-<td><p class=tiny>copyright &copy; 2000 vorbis team</p></td>
-<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/index.html">Ogg Vorbis</a><br><a href="mailto:team at vorbis.org">team at vorbis.org</a></p></td>
+<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
+<td align=right><p class=tiny>Ogg Vorbis</p></td>
 </tr><tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
-<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
+<td><p class=tiny>Vorbisfile documentation</p></td>
+<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
 </tr>
 </table>
 

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

