Skip to content

Vorbis
Vorbis
Commit 700cd116 authored by Monty's avatar Monty
Browse files
Options

Update documentation, version numbers, copyright dates 


svn path=/trunk/vorbis/; revision=13293
parent 6a03c686
Expand all Hide whitespace changes
Inline Side-by-side
Showing with 907 additions and 537 deletions
README
View file @ 700cd116
......@@ -5,7 +5,7 @@
* GOVERNED BY A BSD-STYLE SOURCE LICENSE INCLUDED WITH THIS SOURCE *
* IN 'COPYING'. PLEASE READ THESE TERMS BEFORE DISTRIBUTING. *
* *
* THE OggVorbis SOURCE CODE IS (C) COPYRIGHT 1994-2004 *
* THE OggVorbis SOURCE CODE IS (C) COPYRIGHT 1994-2007 *
* by the Xiph.org Foundation, http://www.xiph.org/ *
* *
********************************************************************
......
doc/Vorbis_I_spec.html
View file @ 700cd116
......@@ -2286,7 +2286,7 @@ distributing independent implementations of Vorbis software under
other licenses.</p><p>
Ogg, Vorbis, Xiph.org Foundation and their logos are trademarks (tm)
of the <a href="http://www.xiph.org/" target="_top">Xiph.org Foundation</a>. These
pages are copyright (C) 1994-2004 Xiph.org Foundation. All rights
pages are copyright (C) 1994-2007 Xiph.org Foundation. All rights
reserved.</p><p>
This document is set in DocBook XML.
</p></div></div></body></html>
doc/vorbisfile/OggVorbis_File.html
View file @ 700cd116
......@@ -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 version 1.68 - 20030307</p></td>
<td align=right><p class=tiny>vorbisfile version 1.2.0 - 20070723</p></td>
</tr>
</table>
......@@ -21,28 +21,44 @@
The OggVorbis_File structure defines an Ogg Vorbis file.
<p>
This structure is used in all libvorbisfile routines. Before it can be used,
it must be initialized by <a href="ov_open.html">ov_open()</a> or <a
href="ov_open_callbacks.html">ov_open_callbacks()</a>.
This structure is used in all libvorbisfile routines. Before it can
be used, it must be initialized by <a
href="ov_open.html">ov_open()</a>, <a
href="ov_fopen.html">ov_fopen()</a>, or <a
href="ov_open_callbacks.html">ov_open_callbacks()</a>. <em>Important
Note:</em> The use of <a href="ov_open.html">ov_open()</a> is
discouraged under Windows due to a peculiarity of Windows linking
convention; use <a href="ov_fopen.html">ov_fopen()</a> or <a
href="ov_open_callbacks.html">ov_open_callbacks()</a> instead. This
caution only applies to Windows; use of <a
href="ov_open.html">ov_open()</a> is appropriate for all other
platforms. See the <a href="ov_open.html">ov_open()</a> page for more
information.
<p>
After use, the OggVorbis_File structure must be deallocated with a
call to <a href="ov_clear.html">ov_clear()</a>.
<p>
Once a file or data source is opened successfully by libvorbisfile
(using <a href="ov_open.html">ov_open()</a> 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>
If the call to <a href="ov_open.html">ov_open()</a> or <a
Note that once a file handle is passed to a successful <a
href="ov_open.html">ov_open()</a> call, the handle is owned by
libvorbisfile and will be closed by libvorbisfile later during the
call to <a href="ov_clear.html">ov_clear()</a>. The handle should not
be used or closed outside of the libvorbisfile API. Similarly, files
opened by <a href="ov_fopen.html">ov_fopen()</a> will also be closed
internally by vorbisfile in <a href="ov_clear.html">ov_clear()</a>.<p>
<a href="ov_open_callbacks.html">ov_open_callbacks()</a> allows the
application to choose whether libvorbisfile will or will not close the
handle in <a href="ov_clear.html">ov_clear()</a>; see the <a
href="ov_open_callbacks.html">ov_open_callbacks()</a> page for more information.<p>
If a call to <a href="ov_open.html">ov_open()</a> 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.
libvorbisfile does <b>not</b> assume ownership of the handle and the
application is expected to close it if necessary. A failed <a
href="ov_fopen.html">ov_fopen()</a> call will internally close the
file handle if the open process fails.<p>
<br><br>
<table border=0 width=100% color=black cellspacing=0 cellpadding=7>
......@@ -108,11 +124,11 @@ application.</dd>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2003 Xiph.org</p></td>
<td><p class=tiny>copyright &copy; 2007 Xiph.org</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
</tr><tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>vorbisfile version 1.68 - 20030307</p></td>
<td align=right><p class=tiny>vorbisfile version 1.2.0 - 20070723</p></td>
</tr>
</table>
......
doc/vorbisfile/callbacks.html
View file @ 700cd116
......@@ -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 version 1.68 - 20030307</p></td>
<td align=right><p class=tiny>vorbisfile version 1.2.0 - 20070723</p></td>
</tr>
</table>
......@@ -50,9 +50,13 @@ The following behaviors are also expected:<p>
The seek-like function provided in the <tt>seek_func</tt> field is
used to request non-sequential data access by libvorbisfile, moving
the access cursor to the requested position.<p>
the access cursor to the requested position. The seek function is
optional; if callbacks are only to handle non-seeking (streaming) data
or the application wishes to force streaming behavior,
<tt>seek_func</tt> and <tt>tell_func</tt> should be set to NULL. If
the seek function is non-NULL, libvorbisfile mandates the following
behavior:
libvorbisfile expects the following behavior:
<ul>
<li>The seek function must always return -1 (failure) if the given
data abstraction is not seekable. It may choose to always return -1
......@@ -73,15 +77,17 @@ one past the last byte of accessible data, as would stdio
The close function should deallocate any access state used by the
passed in instance of the data access abstraction and invalidate the
instance handle. The close function is assumed to succeed.<p>
One common use of callbacks and the close function is to change the
behavior of libvorbisfile with respect to file closure for applications
that <em>must</em> <tt>fclose</tt> data files themselves. By passing
the normal stdio calls as callback functions, but passing a
<tt>close_func</tt> that does nothing, an application may call <a
href="ov_clear.html">ov_clear()</a> and then <tt>fclose()</tt> the
file originally passed to libvorbisfile.
instance handle. The close function is assumed to succeed; its return
code is not checked.<p>
The <tt>close_func</tt> may be set to NULL to indicate that libvorbis
should not attempt to close the file/data handle in <a
href="ov_clear.html">ov_clear</a> but allow the application to handle
file/data access cleanup itself. For example, by passing the normal
stdio calls as callback functions, but passing a <tt>close_func</tt>
that is NULL or does nothing (as in the case of OV_CALLBACKS_NOCLOSE), an
application may call <a href="ov_clear.html">ov_clear()</a> and then
later <tt>fclose()</tt> the file originally passed to libvorbisfile.
<h2>Tell function</h2>
......@@ -94,17 +100,19 @@ function must return the data position (and thus the total file size),
not an error.<p>
The tell function need not be provided if the data IO abstraction is
not seekable.<p>
not seekable, or the application wishes to force streaming
behavior. In this case, the <tt>tell_func</tt> and <tt>seek_func</tt>
fields should be set to NULL.<p>
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2003 Xiph.org</p></td>
<td><p class=tiny>copyright &copy; 2007 Xiph.org</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
</tr><tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>vorbisfile version 1.68 - 20030307</p></td>
<td align=right><p class=tiny>vorbisfile version 1.2.0 - 20070723</p></td>
</tr>
</table>
......
doc/vorbisfile/chaining_example_c.html
View file @ 700cd116
......@@ -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 version 1.68 - 20030307</p></td>
<td align=right><p class=tiny>vorbisfile version 1.2.0 - 20070723</p></td>
</tr>
</table>
......@@ -31,8 +31,12 @@ The example program source:
OggVorbis_File ov;
int i;
<font color="#A020F0">#ifdef _WIN32</font> <font color="#B22222">/* We need to set stdin to binary mode on windows. */</font>
_setmode( _fileno( stdin ), _O_BINARY );
<font color="#A020F0">#endif</font>
<font color="#B22222">/* open the file/pipe on stdin */</font>
<font color="#4169E1">if</font>(ov_open(stdin,&amp;ov,NULL,-1)&lt;0){
<font color="#4169E1">if</font>(ov_open_callbacks(stdin,&amp;ov,NULL,-1,OV_CALLBACKS_NOCLOSE)&lt;0){
printf(<font color="#666666">"Could not open input as an OggVorbis file.\n\n"</font>);
exit(1);
}
......@@ -73,11 +77,11 @@ The example program source:
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2004 Xiph.org</p></td>
<td><p class=tiny>copyright &copy; 2007 Xiph.org</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@vorbis.org">team@vorbis.org</a></p></td>
</tr><tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>vorbisfile version 1.68 - 20030307</p></td>
<td align=right><p class=tiny>vorbisfile version 1.2.0 - 20070723</p></td>
</tr>
</table>
......
doc/vorbisfile/chainingexample.html
View file @ 700cd116
......@@ -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 version 1.68 - 20030307</p></td>
<td align=right><p class=tiny>vorbisfile version 1.2.0 - 20070723</p></td>
</tr>
</table>
......@@ -50,16 +50,33 @@ int main(){
</tr>
</table>
<p><a href="ov_open.html">ov_open()</a> must be
called to initialize the <a href="OggVorbis_File.html">OggVorbis_File</a> structure with default values.
<a href="ov_open.html">ov_open()</a> also checks to ensure that we're reading Vorbis format and not something else.
<p>This example takes its input on stdin which is in 'text' mode by default under Windows; this will corrupt the input data unless set to binary mode. This applies only to Windows.
<br><br>
<table border=0 width=100% color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
#ifdef _WIN32 /* We need to set stdin to binary mode under Windows */
_setmode( _fileno( stdin ), _O_BINARY );
#endif
</b></pre>
</td>
</tr>
</table>
<p>We call <a href="ov_open_callbacks.html">ov_open_callbacks()</a> to
initialize the <a href="OggVorbis_File.html">OggVorbis_File</a>
structure. <a href="ov_open_callbacks.html">ov_open_callbacks()</a>
also checks to ensure that we're reading Vorbis format and not
something else. The OV_CALLBACKS_NOCLOSE callbacks instruct
libvorbisfile not to close stdin later during cleanup.<p>
<br><br>
<table border=0 width=100% color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
if(ov_open(stdin,&amp;ov,NULL,-1)&gt;0){
if(ov_open_callbacks(stdin,&ov,NULL,-1,OV_CALLBACKS_NOCLOSE)<0){
printf("Could not open input as an OggVorbis file.\n\n");
exit(1);
}
......@@ -145,11 +162,11 @@ distribution in <a href="chaining_example_c.html">chaining_example.c</a>.
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2004 Xiph.org</p></td>
<td><p class=tiny>copyright &copy; 2007 Xiph.org</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a><br><a href="mailto:team@vorbis.org">team@vorbis.org</a></p></td>
</tr><tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>vorbisfile version 1.68 - 20030307</p></td>
<td align=right><p class=tiny>vorbisfile version 1.2.0 - 20070723</p></td>
</tr>
</table>
......
doc/vorbisfile/crosslap.html
View file @ 700cd116
......@@ -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 version 1.68 - 20030307</p></td>
<td align=right><p class=tiny>vorbisfile version 1.2.0 - 20070723</p></td>
</tr>
</table>
......@@ -54,7 +54,7 @@ eliminate stairstep discontinuities all the time for exactly the
reasons described above.
<p>Frame lapping, like Vorbis performs internally during continuous
playback, is necessary to eliminate that last epislon of trouble.
playback, is necessary to eliminate that last epsilon of trouble.
<h1>Easiest Crosslap</h1>
......@@ -108,11 +108,11 @@ greater, a half-short block is 64 samples.
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2003 Xiph.org</p></td>
<td><p class=tiny>copyright &copy; 2007 Xiph.org</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
</tr><tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>vorbisfile version 1.68 - 20030307</p></td>
<td align=right><p class=tiny>vorbisfile version 1.2.0 - 20070723</p></td>
</tr>
</table>
......
doc/vorbisfile/datastructures.html
View file @ 700cd116
......@@ -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 version 1.68 - 20030307</p></td>
<td align=right><p class=tiny>vorbisfile version 1.2.0 - 20070723</p></td>
</tr>
</table>
......@@ -48,11 +48,11 @@
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2003 Xiph.org</p></td>
<td><p class=tiny>copyright &copy; 2007 Xiph.org</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
</tr><tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>vorbisfile version 1.68 - 20030307</p></td>
<td align=right><p class=tiny>vorbisfile version 1.2.0 - 20070723</p></td>
</tr>
</table>
......
doc/vorbisfile/decoding.html
View file @ 700cd116
......@@ -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 version 1.68 - 20030307</p></td>
<td align=right><p class=tiny>vorbisfile version 1.2.0 - 20070723</p></td>
</tr>
</table>
......@@ -61,7 +61,8 @@ as a concert recording) is chopped into multiple seperate files.
<td><a href="ov_read.html">ov_read</a></td>
<td>This function makes up the main chunk of a decode loop. It takes an
OggVorbis_File structure, which must have been initialized by a previous
call to <a href="ov_open.html"><tt>ov_open()</tt></a>.</td>
call to <a href="ov_open.html"><tt>ov_open()</tt></a>, <a href="ov_fopen.html"><tt>ov_fopen()</tt></a>,
or <a href="ov_open_callbacks.html"><tt>ov_open_callbacks()</tt></a>.</td>
</tr>
<tr valign=top>
<td><a href="ov_read_float.html">ov_read_float</a></td>
......@@ -73,11 +74,11 @@ call to <a href="ov_open.html"><tt>ov_open()</tt></a>.</td>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2003 Xiph.org</p></td>
<td><p class=tiny>copyright &copy; 2007 Xiph.org</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
</tr><tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>vorbisfile version 1.68 - 20030307</p></td>
<td align=right><p class=tiny>vorbisfile version 1.2.0 - 20070723</p></td>
</tr>
</table>
......
doc/vorbisfile/example.html
View file @ 700cd116
......@@ -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 version 1.68 - 20030307</p></td>
<td align=right><p class=tiny>vorbisfile version 1.2.0 - 20070723</p></td>
</tr>
</table>
......@@ -87,16 +87,19 @@ int main(int argc, char **argv){
</tr>
</table>
<p><a href="ov_open.html">ov_open()</a> must be
called to initialize the <b>OggVorbis_File</b> structure with default values.
<a href="ov_open.html">ov_open()</a> also checks to ensure that we're reading Vorbis format and not something else.
<p>We call <a href="ov_open_callbacks.html">ov_open_callbacks()</a> to
initialize the <b>OggVorbis_File</b> structure with default values.
<a href="ov_open_callbacks.html">ov_open_callbacks()</a> also checks
to ensure that we're reading Vorbis format and not something else. The
OV_CALLBACKS_NOCLOSE callbacks instruct libvorbisfile not to close
stdin later during cleanup.
<br><br>
<table border=0 width=100% color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
if(ov_open(stdin, &vf, NULL, 0) < 0) {
if(ov_open_callbacks(stdin, &vf, NULL, 0, OV_CALLBACKS_NOCLOSE) < 0) {
fprintf(stderr,"Input does not appear to be an Ogg bitstream.\n");
exit(1);
}
......@@ -192,11 +195,11 @@ Now that we've finished playing, we can pack up and go home. It's important to
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2003 Xiph.org</p></td>
<td><p class=tiny>copyright &copy; 2007 Xiph.org</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
</tr><tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>vorbisfile version 1.68 - 20030307</p></td>
<td align=right><p class=tiny>vorbisfile version 1.2.0 - 20070723</p></td>
</tr>
</table>
......
doc/vorbisfile/exampleindex.html
View file @ 700cd116
......@@ -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 version 1.68 - 20030307</p></td>
<td align=right><p class=tiny>vorbisfile version 1.2.0 - 20070723</p></td>
</tr>
</table>
......@@ -26,11 +26,11 @@ Three sample programs are included with the vorbisfile distribution.
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2003 Xiph.org</p></td>
<td><p class=tiny>copyright &copy; 2007 Xiph.org</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a><br><a href="mailto:team@vorbis.org">team@vorbis.org</a></p></td>
</tr><tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>vorbisfile version 1.68 - 20030307</p></td>
<td align=right><p class=tiny>vorbisfile version 1.2.0 - 20070723</p></td>
</tr>
</table>
......
doc/vorbisfile/fileinfo.html
View file @ 700cd116
......@@ -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 version 1.68 - 20030307</p></td>
<td align=right><p class=tiny>vorbisfile version 1.2.0 - 20070723</p></td>
</tr>
</table>
......@@ -82,11 +82,11 @@ All libvorbisfile file information routines are declared in "vorbis/vorbisfile.h
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2003 Xiph.org</p></td>
<td><p class=tiny>copyright &copy; 2007 Xiph.org</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
</tr><tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>vorbisfile version 1.68 - 20030307</p></td>
<td align=right><p class=tiny>vorbisfile version 1.2.0 - 20070723</p></td>
</tr>
</table>
......
doc/vorbisfile/index.html
View file @ 700cd116
......@@ -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 version 1.68 - 20030307</p></td>
<td align=right><p class=tiny>vorbisfile version 1.2.0 - 20070723</p></td>
</tr>
</table>
......@@ -36,11 +36,11 @@ documentation.
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2003 Xiph.org</p></td>
<td><p class=tiny>copyright &copy; 2007 Xiph.org</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
</tr><tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>vorbisfile version 1.68 - 20030307</p></td>
<td align=right><p class=tiny>vorbisfile version 1.2.0 - 20070723</p></td>
</tr>
</table>
......
doc/vorbisfile/initialization.html
View file @ 700cd116
......@@ -9,23 +9,34 @@
<table border=0 width=100%>
<tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>vorbisfile version 1.68 - 20030307</p></td>
<td align=right><p class=tiny>vorbisfile version 1.2.0 - 20070723</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 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
The simplest possible case is to use <a
href="ov_fopen.html">ov_fopen()</a> to open the file for access, check
it for Vorbis content, and prepare it for playback. 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.
href="ov_fopen.html">ov_fopen()</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.
deallocate decoding resources.<p>
On systems other than Windows<a href="ov_open.html#winfoot">[a]</a>, an
application may also open a file itself using <tt>fopen()</tt>, then pass the
<tt>FILE *</tt> to libvorbisfile using <a
href="ov_open.html">ov_open()</a>. </b>Do not</b> call
<tt>fclose()</tt> on a file handle successfully submitted to <a
href="ov_open.html">ov_open()</a>; libvorbisfile does this in the <a
href="ov_clear.html">ov_clear()</a> call.<p>
An application that requires more setup flexibility may open a data
stream using <a href="ov_open_callbacks.html">ov_open_callbacks()</a>
to change default libvorbis behavior or specify non-stdio data access
mechanisms.<p>
<p>
All libvorbisfile initialization and deallocation routines are declared in "vorbis/vorbisfile.h".
......@@ -37,13 +48,18 @@ All libvorbisfile initialization and deallocation routines are declared in "vorb
<td><b>purpose</b></td>
</tr>
<tr valign=top>
<td><a href="ov_open.html">ov_open</a></td>
<td>Initializes the Ogg Vorbis bitstream with a pointer to a bitstream and default values. This must be called before other functions in the library may be
<td><a href="ov_fopen.html">ov_fopen</a></td>
<td>Opens a file and initializes the Ogg Vorbis bitstream with default values. This must be called before other functions in the library may be
used.</td>
</tr>
<tr valign=top>
<td><a href="ov_open.html">ov_open</a></td>
<td>Initializes the Ogg Vorbis bitstream with default values from a passed in file handle. This must be called before other functions in the library may be
used. <a href="#winfoot"><em>Do not use this call under Windows [a];</em></a> Use <a href="ov_fopen.html">ov_fopen()</a> or <a href="ov_open_callbacks.html">ov_open_callbacks()</a> instead.</td>
</tr>
<tr valign=top>
<td><a href="ov_open_callbacks.html">ov_open_callbacks</a></td>
<td>Initializes the Ogg Vorbis bitstream with a pointer to a bitstream, default values, and custom file/bitstream manipulation routines. Used instead of <a href="ov_open.html">ov_open()</a> when working with other than stdio based I/O.</td>
<td>Initializes the Ogg Vorbis bitstream from a file handle and custom file/bitstream manipulation routines. Used instead of <a href="ov_open.html">ov_open()</a> or <a href="ov_fopen.html">ov_fopen()</a> when altering or replacing libvorbis's default stdio I/O behavior, or when a bitstream must be initialized from a <tt>FILE *</tt> under Windows.</td>
</tr>
<tr valign=top>
......@@ -86,13 +102,14 @@ Finish opening a file after a successful call to <a href="ov_test.html">ov_test(
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2003 Xiph.org</p></td>
<td><p class=tiny>copyright &copy; 2007 Xiph.org</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
</tr><tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>vorbisfile version 1.68 - 20030307</p></td>
<td align=right><p class=tiny>vorbisfile version 1.2.0 - 20070723</p></td>
</tr>
</table>
......
doc/vorbisfile/ov_bitrate.html
View file @ 700cd116
......@@ -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 version 1.68 - 20030307</p></td>
<td align=right><p class=tiny>vorbisfile version 1.2.0 - 20070723</p></td>
</tr>
</table>
......@@ -59,11 +59,11 @@ functions.</dd>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2003 Xiph.org</p></td>
<td><p class=tiny>copyright &copy; 2007 Xiph.org</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
</tr><tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>vorbisfile version 1.68 - 20030307</p></td>
<td align=right><p class=tiny>vorbisfile version 1.2.0 - 20070723</p></td>
</tr>
</table>
......
doc/vorbisfile/ov_bitrate_instant.html
View file @ 700cd116
......@@ -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 version 1.68 - 20030307</p></td>
<td align=right><p class=tiny>vorbisfile version 1.2.0 - 20070723</p></td>
</tr>
</table>
......@@ -52,11 +52,11 @@ functions.
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2003 Xiph.org</p></td>
<td><p class=tiny>copyright &copy; 2007 Xiph.org</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
</tr><tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>vorbisfile version 1.68 - 20030307</p></td>
<td align=right><p class=tiny>vorbisfile version 1.2.0 - 20070723</p></td>
</tr>
</table>
......
doc/vorbisfile/ov_callbacks.html
View file @ 700cd116
......@@ -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 version 1.68 - 20030307</p></td>
<td align=right><p class=tiny>vorbisfile version 1.2.0 - 20070723</p></td>
</tr>
</table>
......@@ -23,11 +23,13 @@ The ov_callbacks structure contains file manipulation function prototypes necess
<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
href="ov_fopen.html">ov_fopen()</a> and <a
href="ov_open.html">ov_open()</a> calls internally provide 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).
from a memory buffer) or when <a
href="ov_open.html#winfoot">ov_open()-style initialization from a <tt>FILE *</tt> is required under Windows [a]</a>.
<p>
<table border=0 width=100% color=black cellspacing=0 cellpadding=7>
......@@ -48,15 +50,52 @@ from a memory buffer).
<dt><i>read_func</i></dt>
<dd>Pointer to custom data reading function.</dd>
<dt><i>seek_func</i></dt>
<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>
<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) or the <tt>seek_func</tt> and <tt>tell_func</tt> fields should be set to NULL.</dd>
<dt><i>close_func</i></dt>
<dd>Pointer to custom data source closure function.</dd>
<dd>Pointer to custom data source closure function. Set to NULL if libvorbisfile should not attempt to automatically close the file/data handle.</dd>
<dt><i>tell_func</i></dt>
<dd>Pointer to custom data location function.</dd>
<dd>Pointer to custom data location 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 tell callback should always return -1 (failure) or the <tt>seek_func</tt> and <tt>tell_func</tt> fields should be set to NULL.</dd>
</dl>
<p>
<h3>Predefined callbacks</h3>
The header vorbis/vorbisfile.h provides several predefined static ov_callbacks structures that may be passed to <a
href="ov_open_callbacks.html">ov_open_callbacks()</a>:
<dl>
<dt><tt>OV_CALLBACKS_DEFAULT</tt><dd>
These callbacks provide the same behavior as used internally by <a