diff options
Diffstat (limited to 'doc/vorbisfile')
58 files changed, 669 insertions, 281 deletions
diff --git a/doc/vorbisfile/OggVorbis_File.html b/doc/vorbisfile/OggVorbis_File.html index e4a033e1..293295bb 100644 --- a/doc/vorbisfile/OggVorbis_File.html +++ b/doc/vorbisfile/OggVorbis_File.html @@ -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 © 2003 Xiph.org</p></td> +<td><p class=tiny>copyright © 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> diff --git a/doc/vorbisfile/callbacks.html b/doc/vorbisfile/callbacks.html index eda3c47e..5ed01241 100644 --- a/doc/vorbisfile/callbacks.html +++ b/doc/vorbisfile/callbacks.html @@ -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 © 2003 Xiph.org</p></td> +<td><p class=tiny>copyright © 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> diff --git a/doc/vorbisfile/chaining_example_c.html b/doc/vorbisfile/chaining_example_c.html index 4443b62c..d092b78c 100644 --- a/doc/vorbisfile/chaining_example_c.html +++ b/doc/vorbisfile/chaining_example_c.html @@ -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,&ov,NULL,-1)<0){ + <font color="#4169E1">if</font>(ov_open_callbacks(stdin,&ov,NULL,-1,OV_CALLBACKS_NOCLOSE)<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 © 2004 Xiph.org</p></td> +<td><p class=tiny>copyright © 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> diff --git a/doc/vorbisfile/chainingexample.html b/doc/vorbisfile/chainingexample.html index 0e5a69dc..e2c313eb 100644 --- a/doc/vorbisfile/chainingexample.html +++ b/doc/vorbisfile/chainingexample.html @@ -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,&ov,NULL,-1)>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 © 2004 Xiph.org</p></td> +<td><p class=tiny>copyright © 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> diff --git a/doc/vorbisfile/crosslap.html b/doc/vorbisfile/crosslap.html index 16a768d9..d998eb22 100644 --- a/doc/vorbisfile/crosslap.html +++ b/doc/vorbisfile/crosslap.html @@ -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 © 2003 Xiph.org</p></td> +<td><p class=tiny>copyright © 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> diff --git a/doc/vorbisfile/datastructures.html b/doc/vorbisfile/datastructures.html index 07366184..d3294a3a 100644 --- a/doc/vorbisfile/datastructures.html +++ b/doc/vorbisfile/datastructures.html @@ -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 © 2003 Xiph.org</p></td> +<td><p class=tiny>copyright © 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> diff --git a/doc/vorbisfile/decoding.html b/doc/vorbisfile/decoding.html index 71211144..3a2b405a 100644 --- a/doc/vorbisfile/decoding.html +++ b/doc/vorbisfile/decoding.html @@ -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 © 2003 Xiph.org</p></td> +<td><p class=tiny>copyright © 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> diff --git a/doc/vorbisfile/example.html b/doc/vorbisfile/example.html index eca62e03..3427aa2d 100644 --- a/doc/vorbisfile/example.html +++ b/doc/vorbisfile/example.html @@ -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 © 2003 Xiph.org</p></td> +<td><p class=tiny>copyright © 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> diff --git a/doc/vorbisfile/exampleindex.html b/doc/vorbisfile/exampleindex.html index 6f8dce37..b1686646 100644 --- a/doc/vorbisfile/exampleindex.html +++ b/doc/vorbisfile/exampleindex.html @@ -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 © 2003 Xiph.org</p></td> +<td><p class=tiny>copyright © 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> diff --git a/doc/vorbisfile/fileinfo.html b/doc/vorbisfile/fileinfo.html index ab55f144..8b92d906 100644 --- a/doc/vorbisfile/fileinfo.html +++ b/doc/vorbisfile/fileinfo.html @@ -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 © 2003 Xiph.org</p></td>
+<td><p class=tiny>copyright © 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>
diff --git a/doc/vorbisfile/index.html b/doc/vorbisfile/index.html index 27ebd18b..fc858663 100644 --- a/doc/vorbisfile/index.html +++ b/doc/vorbisfile/index.html @@ -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 © 2003 Xiph.org</p></td> +<td><p class=tiny>copyright © 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> diff --git a/doc/vorbisfile/initialization.html b/doc/vorbisfile/initialization.html index 173a7868..c49b4e79 100644 --- a/doc/vorbisfile/initialization.html +++ b/doc/vorbisfile/initialization.html @@ -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 © 2003 Xiph.org</p></td> +<td><p class=tiny>copyright © 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> diff --git a/doc/vorbisfile/ov_bitrate.html b/doc/vorbisfile/ov_bitrate.html index 222a4256..afd3945b 100644 --- a/doc/vorbisfile/ov_bitrate.html +++ b/doc/vorbisfile/ov_bitrate.html @@ -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 © 2003 Xiph.org</p></td> +<td><p class=tiny>copyright © 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> diff --git a/doc/vorbisfile/ov_bitrate_instant.html b/doc/vorbisfile/ov_bitrate_instant.html index eb6baa68..137effbf 100644 --- a/doc/vorbisfile/ov_bitrate_instant.html +++ b/doc/vorbisfile/ov_bitrate_instant.html @@ -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 © 2003 Xiph.org</p></td> +<td><p class=tiny>copyright © 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> diff --git a/doc/vorbisfile/ov_callbacks.html b/doc/vorbisfile/ov_callbacks.html index 8a01daf7..603705ed 100644 --- a/doc/vorbisfile/ov_callbacks.html +++ b/doc/vorbisfile/ov_callbacks.html @@ -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 +href="ov_fopen.html">ov_fopen()</a> and <a +href="ov_open.html">ov_open()</a>. + +<dt><tt>OV_CALLBACKS_NOCLOSE</tt><dd> + +The same as <tt>OV_CALLBACKS_DEFAULT</tt>, but with the +<tt>close_func</tt> field set to NULL. The most typical use would be +to use <a href="ov_open_callbacks.html">ov_open_callbacks()</a> to +provide the same behavior as <a href="ov_open.html">ov_open()</a>, but +not close the file/data handle in <a +href="ov_clear.html">ov_clear()</a>. + +<dt><tt>OV_CALLBACKS_STREAMONLY</tt><dd> + +A set of callbacks that set <tt>seek_func</tt> and <tt>tell_func</tt> +to NULL, thus forcing strict streaming-only behavior regardless of +whether or not the input is actually seekable. + +<dt><tt>OV_CALLBACKS_STREAMONLY_NOCLOSE</tt><dd> + +The same as <tt>OV_CALLBACKS_STREAMONLY</tt>, but with +<tt>close_func</tt> also set to null, preventing libvorbisfile from +attempting to close the file/data handle in <a +href="ov_clear.html">ov_clear()</a>. + +</dl> +<p> + +<h3>Examples and usage</h3> + See <a href="callbacks.html">the callbacks and non-stdio I/O document</a> for more detailed information on required behavior of the various callback functions.<p> @@ -65,11 +104,11 @@ functions.<p> <hr noshade> <table border=0 width=100%> <tr valign=top> -<td><p class=tiny>copyright © 2003 Xiph.org</p></td> +<td><p class=tiny>copyright © 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> diff --git a/doc/vorbisfile/ov_clear.html b/doc/vorbisfile/ov_clear.html index 805f73c7..62f353ae 100644 --- a/doc/vorbisfile/ov_clear.html +++ b/doc/vorbisfile/ov_clear.html @@ -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> @@ -17,8 +17,8 @@ <p><i>declared in "vorbis/vorbisfile.h";</i></p> -<p> After a bitstream has been opened using <a href="ov_open.html">ov_open()</a>/<a href="ov_open_callbacks.html">ov_open_callbacks()</a> and decoding is complete, the application must call <tt>ov_clear()</tt> to clear -the decoder's buffers. <tt>ov_clear()</tt> will also close the file.<p> +<p> After a bitstream has been opened using <a href="ov_fopen.html">ov_fopen()</a>/<a href="ov_open.html">ov_open()</a>/<a href="ov_open_callbacks.html">ov_open_callbacks()</a> and decoding is complete, the application must call <tt>ov_clear()</tt> to clear +the decoder's buffers. <tt>ov_clear()</tt> will also close the file unless it was opened using <a href="ov_open_callbacks.html">ov_open_callbacks()</a> with the <tt>close_func</tt> callback set to NULL.<p> <tt>ov_clear()</tt> must also be called after a successful call to <a href="ov_test.html">ov_test()</a> or <a href="ov_test_callbacks.html">ov_test_callbacks()</a>.<p> @@ -37,7 +37,7 @@ int ov_clear(OggVorbis_File *vf); <dl> <dt><i>vf</i></dt> <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> +functions. After <tt>ov_clear</tt> has been called, the contents of this structure are deallocated, and it can no longer be used without being reinitialized by a call to <a href="ov_fopen.html">ov_fopen()</a>, <a href="ov_open.html">ov_open()</a> or <a href="ov_open_callbacks.html">ov_open_callbacks()</a>.</dd> </dl> @@ -51,11 +51,11 @@ functions. After <tt>ov_clear</tt> has been called, the structure is deallocate <hr noshade> <table border=0 width=100%> <tr valign=top> -<td><p class=tiny>copyright © 2003 Xiph.org</p></td> +<td><p class=tiny>copyright © 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> diff --git a/doc/vorbisfile/ov_comment.html b/doc/vorbisfile/ov_comment.html index 28aaf31d..740ecab5 100644 --- a/doc/vorbisfile/ov_comment.html +++ b/doc/vorbisfile/ov_comment.html @@ -10,7 +10,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> @@ -53,11 +53,11 @@ functions.</dd> <hr noshade> <table border=0 width=100%> <tr valign=top> -<td><p class=tiny>copyright © 2003 Xiph.org</p></td> +<td><p class=tiny>copyright © 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> diff --git a/doc/vorbisfile/ov_crosslap.html b/doc/vorbisfile/ov_crosslap.html index 81eb2177..b13ebbd1 100644 --- a/doc/vorbisfile/ov_crosslap.html +++ b/doc/vorbisfile/ov_crosslap.html @@ -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,11 +87,11 @@ long ov_crosslap(<a href="OggVorbis_File.html">OggVorbis_File</a> *old, <a href= <hr noshade> <table border=0 width=100%> <tr valign=top> -<td><p class=tiny>copyright © 2003 Xiph.org</p></td> +<td><p class=tiny>copyright © 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> diff --git a/doc/vorbisfile/ov_fopen.html b/doc/vorbisfile/ov_fopen.html new file mode 100644 index 00000000..256f5817 --- /dev/null +++ b/doc/vorbisfile/ov_fopen.html @@ -0,0 +1,124 @@ +<html> + +<head> +<title>Vorbisfile - function - ov_fopen</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.2.0 - 20070723</p></td> +</tr> +</table> + +<h1>ov_fopen</h1> + +<p><i>declared in "vorbis/vorbisfile.h";</i></p> + +<p>This is the simplest function used to open and initialize an OggVorbis_File +structure. It sets up all the related decoding structure. +<p>The first argument is a file path suitable +for passing to fopen(). <tt>vf</tt> should be a pointer to an empty +OggVorbis_File structure -- this is used for ALL the externally visible +libvorbisfile functions. Once this has been called, the same <a +href="OggVorbis_File.html">OggVorbis_File</a> struct should be passed +to all the libvorbisfile functions. +<p>The <tt>vf</tt> structure initialized using ov_fopen() must +eventually be cleaned using <a href="ov_clear.html">ov_clear()</a>. + +<p> +It is often useful to call <tt>ov_fopen()</tt> simply to determine +whether a given file is a Vorbis bitstream. If the <tt>ov_fopen()</tt> +call fails, then the file is either inaccessable (errno is set) or not +recognizable as Vorbis (errno unchanged). If the call succeeds but +the initialized <tt>vf</tt> structure will not be used, the +application is responsible for calling <a +href="ov_clear.html">ov_clear()</a> to clear the decoder's buffers and +close the file.<p> + +<br><br> +<table border=0 color=black cellspacing=0 cellpadding=7> +<tr bgcolor=#cccccc> + <td> +<pre><b> +int ov_fopen(char *path,<a href="OggVorbis_File.html">OggVorbis_File</a> *vf); +</b></pre> + </td> +</tr> +</table> + +<h3>Parameters</h3> +<dl> +<dt><i>path</i></dt> +<dd>Null terminated string containing a file path suitable for passing to <tt>fopen()</tt>. +</dd> +<dt><i>vf</i></dt> +<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 libvorbisfile functions.</dd> +</dl> + + +<h3>Return Values</h3> +<blockquote> +<li>0 indicates success</li> + +<li>less than zero for failure:</li> +<ul> +<li>OV_EREAD - A read from media returned an error.</li> +<li>OV_ENOTVORBIS - Bitstream does not contain any Vorbis data.</li> +<li>OV_EVERSION - Vorbis version mismatch.</li> +<li>OV_EBADHEADER - Invalid Vorbis bitstream header.</li> +<li>OV_EFAULT - Internal logic fault; indicates a bug or heap/stack corruption.</li> +</ul> +</blockquote> +<p> + +<h3>Notes</h3> +<dl> + +<dt><b>[a] Threaded decode</b><p> +<dd>If your decoder is threaded, it is recommended that you NOT call +<tt>ov_open_callbacks()</tt> +in the main control thread--instead, call <tt>ov_open_callbacks()</tt> in your decode/playback +thread. This is important because <tt>ov_open_callbacks()</tt> may be a fairly time-consuming +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). See <a href="threads.html">Thread Safety</a> for other information on using libvorbisfile with threads. +<p> + +<dt><b>[b] Mixed media streams</b><p> +<dd> +As of Vorbisfile release 1.2.0, Vorbisfile is able to access the +Vorbis content in mixed-media Ogg streams, not just Vorbis-only +streams. For example, Vorbisfile may be used to open and access the +audio from an Ogg stream consisting of Theora video and Vorbis audio. +Vorbisfile 1.2.0 decodes the first logical audio stream of each +physical stream section.<p> + +<dt><b>[c] Faster testing for Vorbis files</b><p> +<dd><a href="ov_test.html">ov_test()</a> and <a +href="ov_test_callbacks.html">ov_test_callbacks()</a> provide less +computationally expensive ways to test a file for Vorbisness, but +require more setup code.<p> + +</dl> + +<br><br> +<hr noshade> +<table border=0 width=100%> +<tr valign=top> +<td><p class=tiny>copyright © 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.2.0 - 20070723</p></td> +</tr> +</table> + +</body> + +</html> diff --git a/doc/vorbisfile/ov_info.html b/doc/vorbisfile/ov_info.html index c8dd9eff..c9cc0627 100644 --- a/doc/vorbisfile/ov_info.html +++ b/doc/vorbisfile/ov_info.html @@ -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> @@ -51,11 +51,11 @@ functions. </dd> <hr noshade> <table border=0 width=100%> <tr valign=top> -<td><p class=tiny>copyright © 2003 Xiph.org</p></td> +<td><p class=tiny>copyright © 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> diff --git a/doc/vorbisfile/ov_open.html b/doc/vorbisfile/ov_open.html index ba530311..9b6f9e02 100644 --- a/doc/vorbisfile/ov_open.html +++ b/doc/vorbisfile/ov_open.html @@ -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> @@ -17,28 +17,45 @@ <p><i>declared in "vorbis/vorbisfile.h";</i></p> -<p>This is the main function used to open and initialize an OggVorbis_File -structure. It sets up all the related decoding structure. +<p>ov_open is one of three initialization functions used to initialize +an OggVorbis_File structure and prepare a bitstream for playback. + +<p><em><b> WARNING for Windows developers: </b> Do not use ov_open() in +Windows applications; Windows linking places restrictions on +passing <tt>FILE *</tt> handles successfully, and ov_open() runs +afoul of these restrictions <a href="#winfoot">[a]</a>. See the <a +href="ov_open_callbacks.html">ov_open_callbacks() page </a> for +details on using <a +href="ov_open_callbacks.html">ov_open_callbacks()</a> instead. </em> + <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 libvorbisfile +OggVorbis_File structure -- this is used for ALL the externally visible libvorbisfile functions. Once this has been called, the same <a href="OggVorbis_File.html">OggVorbis_File</a> -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 <a href="ov_clear.html">ov_clear()</a>, 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() -</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 <a href="ov_clear.html">ov_clear()</a> to clear -the decoder's buffers and close the file for you.<p> +struct should be passed to all the libvorbisfile functions.<p> + +The <tt>vf</tt> structure initialized using ov_fopen() must eventually +be cleaned using <a href="ov_clear.html">ov_clear()</a>. Once a +<tt>FILE *</tt> handle is passed to ov_open() successfully, the +application MUST NOT <tt>fclose()</tt> or in any other way manipulate +that file handle. Vorbisfile will close the file in <a +href="ov_clear.html">ov_clear()</a>. If the application must be able +to close the <tt>FILE *</tt> handle itself, see <a +href="ov_open_callbacks.html">ov_open_callbacks()</a> with the use of +<tt>OV_CALLBACKS_NOCLOSE</tt>. + +<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 Vorbis. If the call +succeeds but the initialized <tt>vf</tt> structure will not be used, +the application is responsible for calling <a +href="ov_clear.html">ov_clear()</a> to clear the decoder's buffers and +close the file.<p> + +If [and only if] an <tt>ov_open()</tt> call fails, the application +must explicitly <tt>fclose()</tt> the <tt>FILE *</tt> pointer itself. -(Note that <a href="ov_test.html">ov_test()</a> provides a less expensive way to test a file for Vorbisness.)<p> <br><br> <table border=0 color=black cellspacing=0 cellpadding=7> @@ -87,26 +104,77 @@ should contain the length (in bytes) of the buffer. Used together with <tt>init </blockquote> <p> +<a name="notes"></a> <h3>Notes</h3> -<p>If your decoder is threaded, it is recommended that you NOT call +<dl> + +<a name="winfoot"></a> +<dt><b>[a] Windows and ov_open()</b><p> + +<dd>Under Windows, stdio file access is implemented in each of many +variants of crt.o, several of which are typically installed on any one +Windows machine. If libvorbisfile and the application using +libvorbisfile are not linked against the exact same +version/variant/build of crt.o (and they usually won't be, especially +using a prebuilt libvorbis DLL), <tt>FILE *</tt> handles cannot be +opened in the application and then passed to vorbisfile to be used +by stdio calls from vorbisfile's different version of CRT. For this +reason, using <a href="ov_open.html">ov_open()</a> under Windows +without careful, expert linking will typically cause a protection +fault. Windows programmers should use <a +href="ov_fopen.html">ov_fopen()</a> (which will only use libvorbis's +crt.o) or <a href="ov_open_callbacks.html">ov_open_callbacks()</a> +(which will only use the application's crt.o) instead.<p> + +This warning only applies to Windows and only applies to <a +href="ov_open.html">ov_open()</a>. It is perfectly safe to use <a +href="ov_open.html">ov_open()</a> on all other platforms.<p> + +For more information, see the following microsoft pages on <a +href="http://msdn2.microsoft.com/en-us/library/abx4dbyh(VS.80).aspx">C +runtime library linking</a> and a specific description of <a +href="http://msdn2.microsoft.com/en-us/library/ms235460(VS.80).aspx">restrictions +on passing CRT objects across DLL boundaries</a>. + +<p> + +<dt><b>[b] Threaded decode</b><p> +<dd>If your decoder is threaded, it is recommended that you NOT call <tt>ov_open()</tt> -in the main control thread--instead, call <tt>ov_open()</tt> IN your decode/playback +in the main control thread--instead, call <tt>ov_open()</tt> in your decode/playback thread. This is important because <tt>ov_open()</tt> may be a fairly time-consuming 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). See <a href="threads.html">Thread Safety</a> for other information on using libvorbisfile with threads. +<p> + +<dt><b>[c] Mixed media streams</b><p> +<dd> +As of Vorbisfile release 1.2.0, Vorbisfile is able to access the +Vorbis content in mixed-media Ogg streams, not just Vorbis-only +streams. For example, Vorbisfile may be used to open and access the +audio from an Ogg stream consisting of Theora video and Vorbis audio. +Vorbisfile 1.2.0 decodes the first logical audio stream of each +physical stream section.<p> + +<dt><b>[d] Faster testing for Vorbis files</b><p> +<dd><a href="ov_test.html">ov_test()</a> and <a +href="ov_test_callbacks.html">ov_test_callbacks()</a> provide less +computationally expensive ways to test a file for Vorbisness, but +require more setup code.<p> +</dl> <br><br> <hr noshade> <table border=0 width=100%> <tr valign=top> -<td><p class=tiny>copyright © 2003 Xiph.org</p></td> +<td><p class=tiny>copyright © 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> diff --git a/doc/vorbisfile/ov_open_callbacks.html b/doc/vorbisfile/ov_open_callbacks.html index 16893c90..6718f12e 100644 --- a/doc/vorbisfile/ov_open_callbacks.html +++ b/doc/vorbisfile/ov_open_callbacks.html @@ -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> @@ -17,22 +17,28 @@ <p><i>declared in "vorbis/vorbisfile.h";</i></p> -<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 libvorbisfile functions. -<p> -It is often useful to call <tt>ov_open_callbacks()</tt> -simply to determine whether a given stream is a vorbis bitstream. If the -<tt>ov_open_callbacks()</tt> -call fails, then the data is not recognizable as such. When you use <tt>ov_open_callbacks() -</tt>for -this, you should close or otherwise deallocate your <tt>datasource</tt> 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 call your close callback.<p> +<p>This is an alternative function used to open and initialize an +OggVorbis_File structure when using a data source other than a file, +when its necessary to modify default file access behavior, or to +initialize a Vorbis decode from a <tt>FILE *</tt> pointer under +Windows where <a href="ov_open.html">ov_open()</a> cannot be used. It +allows the application to specify custom file manipulation routines +and sets up all the related decoding structures. + +<p>Once ov_open_callbacks() has been called, the same +<tt>OggVorbis_File</tt> struct should be passed to all the +libvorbisfile functions. Unlike <a +href="ov_fopen.html">ov_fopen()</a> and <a +href="ov_open.html">ov_open()</a>, ov_open_callbacks() may be used to +instruct vorbisfile to either automatically close or not to close the +file/data access handle in <a href="ov_clear.html">ov_clear()</a>. +Automatic closure is disabled by passing NULL as the close callback, +or using one of the predefined callback sets that specify a NULL close +callback. The application is responsible for closing a file when a +call to ov_open_callbacks() is unsuccessful.<p> -See also <a href="callbacks.html">Callbacks and Non-stdio I/O</a> for information on designing and specifying the required callback functions.<p> +See also <a href="callbacks.html">Callbacks and Non-stdio I/O</a> for +information on designing and specifying custom callback functions.<p> <br><br> <table border=0 color=black cellspacing=0 cellpadding=7> @@ -62,7 +68,7 @@ should be a pointer to a buffer containing the data read.</dd> read from the stream and the stream is not seekable. In this case, <tt>ibytes</tt> should contain the length (in bytes) of the buffer. Used together with <tt>initial</tt>.</dd> <dt><i>callbacks</i></dt> -<dd>A completed <a href="ov_callbacks.html">ov_callbacks</a> struct which indicates desired custom file manipulation routines.</dd> +<dd>A completed <a href="ov_callbacks.html">ov_callbacks</a> struct which indicates desired custom file manipulation routines. vorbisfile.h defines several preprovided callback sets; see <a href="ov_callbacks.html">ov_callbacks</a> for details.</dd> </dl> @@ -72,7 +78,7 @@ should contain the length (in bytes) of the buffer. Used together with <tt>init <li>less than zero for failure:</li> <ul> <li>OV_EREAD - A read from media returned an error.</li> -<li>OV_ENOTVORBIS - Bitstream is not Vorbis data.</li> +<li>OV_ENOTVORBIS - Bitstream does not contain any Vorbis data.</li> <li>OV_EVERSION - Vorbis version mismatch.</li> <li>OV_EBADHEADER - Invalid Vorbis bitstream header.</li> <li>OV_EFAULT - Internal logic fault; indicates a bug or heap/stack corruption.</li> @@ -81,25 +87,58 @@ should contain the length (in bytes) of the buffer. Used together with <tt>init <p> <h3>Notes</h3> -<p>If your decoder is threaded, it is recommended that you NOT call +<dl> + +<dt><b>[a] Windows and use as an ov_open() substitute</b><p> Windows +applications should not use <a href="ov_open.html">ov_open()</a> due +to the likelihood of <a href="ov_open.html#winfoot">CRT linking +mismatches and runtime protection faults +[ov_open:a]</a>. ov_open_callbacks() is a safe substitute; specifically: + +<pre><tt>ov_open_callbacks(f, vf, initial, ibytes, OV_CALLBACKS_DEFAULT);</tt> +</pre> + +... provides exactly the same functionality as <a +href="ov_open.html">ov_open()</a> but will always work correctly under +Windows, regardless of linking setup details.<p> + +<dt><b>[b] Threaded decode</b><p> +<dd>If your decoder is threaded, it is recommended that you NOT call <tt>ov_open_callbacks()</tt> -in the main control thread--instead, call <tt>ov_open_callbacks()</tt> IN your decode/playback +in the main control thread--instead, call <tt>ov_open_callbacks()</tt> in your decode/playback thread. This is important because <tt>ov_open_callbacks()</tt> may be a fairly time-consuming 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). -See <a href="threads.html">Thread Safety</a> for other information on using libvorbisfile with threads. +example). See <a href="threads.html">Thread Safety</a> for other information on using libvorbisfile with threads. +<p> + +<dt><b>[c] Mixed media streams</b><p> +<dd> +As of Vorbisfile release 1.2.0, Vorbisfile is able to access the +Vorbis content in mixed-media Ogg streams, not just Vorbis-only +streams. For example, Vorbisfile may be used to open and access the +audio from an Ogg stream consisting of Theora video and Vorbis audio. +Vorbisfile 1.2.0 decodes the first logical audio stream of each +physical stream section.<p> + +<dt><b>[d] Faster testing for Vorbis files</b><p> +<dd><a href="ov_test.html">ov_test()</a> and <a +href="ov_test_callbacks.html">ov_test_callbacks()</a> provide less +computationally expensive ways to test a file for Vorbisness, but +require more setup code.<p> + +</dl> <br><br> <hr noshade> <table border=0 width=100%> <tr valign=top> -<td><p class=tiny>copyright © 2003 Xiph.org</p></td> +<td><p class=tiny>copyright © 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> diff --git a/doc/vorbisfile/ov_pcm_seek.html b/doc/vorbisfile/ov_pcm_seek.html index 3c554699..73e2f668 100644 --- a/doc/vorbisfile/ov_pcm_seek.html +++ b/doc/vorbisfile/ov_pcm_seek.html @@ -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> @@ -70,11 +70,11 @@ nonzero indicates failure, described by several error codes: <hr noshade> <table border=0 width=100%> <tr valign=top> -<td><p class=tiny>copyright © 2003 Xiph.org</p></td> +<td><p class=tiny>copyright © 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> diff --git a/doc/vorbisfile/ov_pcm_seek_lap.html b/doc/vorbisfile/ov_pcm_seek_lap.html index 124a7f93..4a30a92f 100644 --- a/doc/vorbisfile/ov_pcm_seek_lap.html +++ b/doc/vorbisfile/ov_pcm_seek_lap.html @@ -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> @@ -90,11 +90,11 @@ nonzero indicates failure, described by several error codes: <hr noshade> <table border=0 width=100%> <tr valign=top> -<td><p class=tiny>copyright © 2003 Xiph.org</p></td> +<td><p class=tiny>copyright © 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> diff --git a/doc/vorbisfile/ov_pcm_seek_page.html b/doc/vorbisfile/ov_pcm_seek_page.html index 5dbda3c0..796609ec 100644 --- a/doc/vorbisfile/ov_pcm_seek_page.html +++ b/doc/vorbisfile/ov_pcm_seek_page.html @@ -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> @@ -71,11 +71,11 @@ nonzero indicates failure, described by several error codes: <hr noshade> <table border=0 width=100%> <tr valign=top> -<td><p class=tiny>copyright © 2003 Xiph.org</p></td> +<td><p class=tiny>copyright © 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> diff --git a/doc/vorbisfile/ov_pcm_seek_page_lap.html b/doc/vorbisfile/ov_pcm_seek_page_lap.html index dd81db76..558f6ab2 100644 --- a/doc/vorbisfile/ov_pcm_seek_page_lap.html +++ b/doc/vorbisfile/ov_pcm_seek_page_lap.html @@ -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> @@ -99,11 +99,11 @@ nonzero indicates failure, described by several error codes: <hr noshade> <table border=0 width=100%> <tr valign=top> -<td><p class=tiny>copyright © 2003 Xiph.org</p></td> +<td><p class=tiny>copyright © 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> diff --git a/doc/vorbisfile/ov_pcm_tell.html b/doc/vorbisfile/ov_pcm_tell.html index 1d8961fa..09a9cd42 100644 --- a/doc/vorbisfile/ov_pcm_tell.html +++ b/doc/vorbisfile/ov_pcm_tell.html @@ -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,11 +50,11 @@ functions.</dd> <hr noshade> <table border=0 width=100%> <tr valign=top> -<td><p class=tiny>copyright © 2003 Xiph.org</p></td> +<td><p class=tiny>copyright © 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> diff --git a/doc/vorbisfile/ov_pcm_total.html b/doc/vorbisfile/ov_pcm_total.html index ce8fb1ba..fb44bccc 100644 --- a/doc/vorbisfile/ov_pcm_total.html +++ b/doc/vorbisfile/ov_pcm_total.html @@ -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,11 +54,11 @@ total length in pcm samples of content if i=-1.</li> <hr noshade> <table border=0 width=100%> <tr valign=top> -<td><p class=tiny>copyright © 2003 Xiph.org</p></td> +<td><p class=tiny>copyright © 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> diff --git a/doc/vorbisfile/ov_raw_seek.html b/doc/vorbisfile/ov_raw_seek.html index 1e5fbbec..285afdb9 100644 --- a/doc/vorbisfile/ov_raw_seek.html +++ b/doc/vorbisfile/ov_raw_seek.html @@ -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> @@ -70,11 +70,11 @@ nonzero indicates failure, described by several error codes: <hr noshade> <table border=0 width=100%> <tr valign=top> -<td><p class=tiny>copyright © 2003 Xiph.org</p></td> +<td><p class=tiny>copyright © 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> diff --git a/doc/vorbisfile/ov_raw_seek_lap.html b/doc/vorbisfile/ov_raw_seek_lap.html index 56c49534..2a55a62d 100644 --- a/doc/vorbisfile/ov_raw_seek_lap.html +++ b/doc/vorbisfile/ov_raw_seek_lap.html @@ -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> @@ -97,11 +97,11 @@ nonzero indicates failure, described by several error codes: <hr noshade> <table border=0 width=100%> <tr valign=top> -<td><p class=tiny>copyright © 2003 Xiph.org</p></td> +<td><p class=tiny>copyright © 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> diff --git a/doc/vorbisfile/ov_raw_tell.html b/doc/vorbisfile/ov_raw_tell.html index 51d03b61..525ce883 100644 --- a/doc/vorbisfile/ov_raw_tell.html +++ b/doc/vorbisfile/ov_raw_tell.html @@ -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.</dd> <hr noshade> <table border=0 width=100%> <tr valign=top> -<td><p class=tiny>copyright © 2003 Xiph.org</p></td> +<td><p class=tiny>copyright © 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> diff --git a/doc/vorbisfile/ov_raw_total.html b/doc/vorbisfile/ov_raw_total.html index a6c71c77..7b89f0ec 100644 --- a/doc/vorbisfile/ov_raw_total.html +++ b/doc/vorbisfile/ov_raw_total.html @@ -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> @@ -55,11 +55,11 @@ total length in compressed bytes of content if i=-1.</li> <hr noshade> <table border=0 width=100%> <tr valign=top> -<td><p class=tiny>copyright © 2003 Xiph.org</p></td> +<td><p class=tiny>copyright © 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> diff --git a/doc/vorbisfile/ov_read.html b/doc/vorbisfile/ov_read.html index e545f47e..4e923543 100644 --- a/doc/vorbisfile/ov_read.html +++ b/doc/vorbisfile/ov_read.html @@ -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> @@ -110,11 +110,11 @@ little-endian samples. <hr noshade> <table border=0 width=100%> <tr valign=top> -<td><p class=tiny>copyright © 2003 Xiph.org</p></td> +<td><p class=tiny>copyright © 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> diff --git a/doc/vorbisfile/ov_read_float.html b/doc/vorbisfile/ov_read_float.html index e10e1c61..2a9c9f10 100644 --- a/doc/vorbisfile/ov_read_float.html +++ b/doc/vorbisfile/ov_read_float.html @@ -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> @@ -88,7 +88,7 @@ This decodes up to 1024 float samples. <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> diff --git a/doc/vorbisfile/ov_seekable.html b/doc/vorbisfile/ov_seekable.html index b8f8c918..fee1d880 100644 --- a/doc/vorbisfile/ov_seekable.html +++ b/doc/vorbisfile/ov_seekable.html @@ -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,11 +50,11 @@ functions.</dd> <hr noshade> <table border=0 width=100%> <tr valign=top> -<td><p class=tiny>copyright © 2003 Xiph.org</p></td> +<td><p class=tiny>copyright © 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> diff --git a/doc/vorbisfile/ov_serialnumber.html b/doc/vorbisfile/ov_serialnumber.html index a5f0f0cd..abd01c77 100644 --- a/doc/vorbisfile/ov_serialnumber.html +++ b/doc/vorbisfile/ov_serialnumber.html @@ -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,11 +54,11 @@ functions.</dd> <hr noshade> <table border=0 width=100%> <tr valign=top> -<td><p class=tiny>copyright © 2003 Xiph.org</p></td> +<td><p class=tiny>copyright © 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> diff --git a/doc/vorbisfile/ov_streams.html b/doc/vorbisfile/ov_streams.html index 997edccc..a8f2a62a 100644 --- a/doc/vorbisfile/ov_streams.html +++ b/doc/vorbisfile/ov_streams.html @@ -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> @@ -51,11 +51,11 @@ functions. </dd> <hr noshade> <table border=0 width=100%> <tr valign=top> -<td><p class=tiny>copyright © 2003 Xiph.org</p></td> +<td><p class=tiny>copyright © 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> diff --git a/doc/vorbisfile/ov_test.html b/doc/vorbisfile/ov_test.html index 9aa72d1f..0975972e 100644 --- a/doc/vorbisfile/ov_test.html +++ b/doc/vorbisfile/ov_test.html @@ -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> @@ -19,11 +19,21 @@ <p> This partially opens a vorbis file to test for Vorbis-ness. It loads -the headers for the first chain, and tests for seekability (but does not seek). +the headers for the first chain and tests for seekability (but does not seek). Use <a href="ov_test_open.html">ov_test_open()</a> to finish opening the file or <a href="ov_clear.html">ov_clear</a> to close/free it. <p> +<p><em><b> WARNING for Windows developers: </b> Do not use ov_test() +in Windows applications; Windows linking places restrictions on +passing <tt>FILE *</tt> handles successfully, and ov_test() runs afoul +of these restrictions <a href="#winfoot">[a]</a> in exactly the same +way as <a href="ov_open.html">ov_open()</a>. See the <a +href="ov_test_callbacks.html">ov_test_callbacks() page </a> for +details on using <a +href="ov_test_callbacks.html">ov_test_callbacks()</a> instead. </em> +<p> + <table border=0 color=black cellspacing=0 cellpadding=7> <tr bgcolor=#cccccc> <td> @@ -62,7 +72,7 @@ should contain the length (in bytes) of the buffer. Used together with <tt>init <li>less than zero for failure:</li> <ul> <li>OV_EREAD - A read from media returned an error.</li> -<li>OV_ENOTVORBIS - Bitstream is not Vorbis data.</li> +<li>OV_ENOTVORBIS - Bitstream contains no Vorbis data.</li> <li>OV_EVERSION - Vorbis version mismatch.</li> <li>OV_EBADHEADER - Invalid Vorbis bitstream header.</li> <li>OV_EFAULT - Internal logic fault; indicates a bug or heap/stack corruption.</li> @@ -70,17 +80,19 @@ should contain the length (in bytes) of the buffer. Used together with <tt>init </blockquote> <p> +<h3>Notes</h3> +All the <a href="ov_open.html#notes">notes from ov_open()</a> apply to ov_test(). <br><br> <hr noshade> <table border=0 width=100%> <tr valign=top> -<td><p class=tiny>copyright © 2003 Xiph.org</p></td> +<td><p class=tiny>copyright © 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> diff --git a/doc/vorbisfile/ov_test_callbacks.html b/doc/vorbisfile/ov_test_callbacks.html index 160b2518..5d659cdd 100644 --- a/doc/vorbisfile/ov_test_callbacks.html +++ b/doc/vorbisfile/ov_test_callbacks.html @@ -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> @@ -18,7 +18,13 @@ <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 structures. +structure when using a data source other than a file, +when its necessary to modify default file access behavior, or to +test for Vorbis content from a <tt>FILE *</tt> pointer under +Windows where <a href="ov_open.html">ov_test()</a> cannot be used. It +allows the application 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 libvorbisfile functions. <p> @@ -52,7 +58,7 @@ should be a pointer to a buffer containing the data read.</dd> read from the file and the stream is not seekable. In this case, <tt>ibytes</tt> should contain the length (in bytes) of the buffer. Used together with <tt>initial</tt>.</dd> <dt><i>callbacks</i></dt> -<dd>A completed <a href="ov_callbacks.html">ov_callbacks</a> struct which indicates desired custom file manipulation routines.</dd> +<dd>A completed <a href="ov_callbacks.html">ov_callbacks</a> struct which indicates desired custom file manipulation routines. vorbisfile.h defines several preprovided callback sets; see <a href="ov_callbacks.html">ov_callbacks</a> for details.</dd> </dl> @@ -62,7 +68,7 @@ should contain the length (in bytes) of the buffer. Used together with <tt>init <li>less than zero for failure:</li> <ul> <li>OV_EREAD - A read from media returned an error.</li> -<li>OV_ENOTVORBIS - Bitstream is not Vorbis data.</li> +<li>OV_ENOTVORBIS - Bitstream contains no Vorbis data.</li> <li>OV_EVERSION - Vorbis version mismatch.</li> <li>OV_EBADHEADER - Invalid Vorbis bitstream header.</li> <li>OV_EFAULT - Internal logic fault; indicates a bug or heap/stack corruption.</li> @@ -70,18 +76,33 @@ should contain the length (in bytes) of the buffer. Used together with <tt>init </blockquote> <p> +<h3>Notes</h3> +<dl> + +<dt><b>[a] Windows and use as an ov_test() substitute</b><p> Windows +applications should not use <a href="ov_test.html">ov_test()</a> due +to the likelihood of <a href="ov_open.html#winfoot">CRT linking +mismatches and runtime protection faults +[ov_open:a]</a>. ov_test_callbacks() is a safe substitute; specifically: +<pre><tt>ov_test_callbacks(f, vf, initial, ibytes, OV_CALLBACKS_DEFAULT);</tt> +</pre> +... provides exactly the same functionality as <a +href="ov_test.html">ov_test()</a> but will always work correctly under +Windows, regardless of linking setup details.<p> + +</dl> <br><br> <hr noshade> <table border=0 width=100%> <tr valign=top> -<td><p class=tiny>copyright © 2003 Xiph.org</p></td> +<td><p class=tiny>copyright © 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> diff --git a/doc/vorbisfile/ov_test_open.html b/doc/vorbisfile/ov_test_open.html index c0a320cb..d379311d 100644 --- a/doc/vorbisfile/ov_test_open.html +++ b/doc/vorbisfile/ov_test_open.html @@ -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> @@ -62,11 +62,11 @@ struct should be passed to all the libvorbisfile functions.</dd> <hr noshade> <table border=0 width=100%> <tr valign=top> -<td><p class=tiny>copyright © 2003 Xiph.org</p></td> +<td><p class=tiny>copyright © 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> diff --git a/doc/vorbisfile/ov_time_seek.html b/doc/vorbisfile/ov_time_seek.html index a4d4071f..28376b16 100644 --- a/doc/vorbisfile/ov_time_seek.html +++ b/doc/vorbisfile/ov_time_seek.html @@ -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> @@ -69,11 +69,11 @@ nonzero indicates failure, described by several error codes: <hr noshade> <table border=0 width=100%> <tr valign=top> -<td><p class=tiny>copyright © 2003 Xiph.org</p></td> +<td><p class=tiny>copyright © 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> diff --git a/doc/vorbisfile/ov_time_seek_lap.html b/doc/vorbisfile/ov_time_seek_lap.html index fbb62906..b6098181 100644 --- a/doc/vorbisfile/ov_time_seek_lap.html +++ b/doc/vorbisfile/ov_time_seek_lap.html @@ -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> @@ -92,11 +92,11 @@ nonzero indicates failure, described by several error codes: <hr noshade> <table border=0 width=100%> <tr valign=top> -<td><p class=tiny>copyright © 2003 Xiph.org</p></td> +<td><p class=tiny>copyright © 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> diff --git a/doc/vorbisfile/ov_time_seek_page.html b/doc/vorbisfile/ov_time_seek_page.html index 87904227..40e410ab 100644 --- a/doc/vorbisfile/ov_time_seek_page.html +++ b/doc/vorbisfile/ov_time_seek_page.html @@ -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> @@ -70,11 +70,11 @@ nonzero indicates failure, described by several error codes: <hr noshade> <table border=0 width=100%> <tr valign=top> -<td><p class=tiny>copyright © 2003 Xiph.org</p></td> +<td><p class=tiny>copyright © 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> diff --git a/doc/vorbisfile/ov_time_seek_page_lap.html b/doc/vorbisfile/ov_time_seek_page_lap.html index 003db33f..75b02d33 100644 --- a/doc/vorbisfile/ov_time_seek_page_lap.html +++ b/doc/vorbisfile/ov_time_seek_page_lap.html @@ -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> @@ -99,11 +99,11 @@ nonzero indicates failure, described by several error codes: <hr noshade> <table border=0 width=100%> <tr valign=top> -<td><p class=tiny>copyright © 2003 Xiph.org</p></td> +<td><p class=tiny>copyright © 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> diff --git a/doc/vorbisfile/ov_time_tell.html b/doc/vorbisfile/ov_time_tell.html index e2c0af56..a9bbe26d 100644 --- a/doc/vorbisfile/ov_time_tell.html +++ b/doc/vorbisfile/ov_time_tell.html @@ -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,11 +50,11 @@ functions.</dd> <hr noshade> <table border=0 width=100%> <tr valign=top> -<td><p class=tiny>copyright © 2003 Xiph.org</p></td> +<td><p class=tiny>copyright © 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> diff --git a/doc/vorbisfile/ov_time_total.html b/doc/vorbisfile/ov_time_total.html index a06f4c56..d691dead 100644 --- a/doc/vorbisfile/ov_time_total.html +++ b/doc/vorbisfile/ov_time_total.html @@ -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,11 +54,11 @@ functions.</dd> <hr noshade> <table border=0 width=100%> <tr valign=top> -<td><p class=tiny>copyright © 2003 Xiph.org</p></td> +<td><p class=tiny>copyright © 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> diff --git a/doc/vorbisfile/overview.html b/doc/vorbisfile/overview.html index 8fe77e9b..cf491197 100644 --- a/doc/vorbisfile/overview.html +++ b/doc/vorbisfile/overview.html @@ -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> @@ -47,11 +47,11 @@ via callbacks</a> <hr noshade> <table border=0 width=100%> <tr valign=top> -<td><p class=tiny>copyright © 2003 Xiph.org</p></td> +<td><p class=tiny>copyright © 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> diff --git a/doc/vorbisfile/reference.html b/doc/vorbisfile/reference.html index 33840252..a6c64b48 100644 --- a/doc/vorbisfile/reference.html +++ b/doc/vorbisfile/reference.html @@ -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,6 +23,7 @@ <a href="ov_callbacks.html">ov_callbacks</a><br> <br> <b>Setup/Teardown</b><br> +<a href="ov_fopen.html">ov_fopen()</a><br> <a href="ov_open.html">ov_open()</a><br> <a href="ov_open_callbacks.html">ov_open_callbacks()</a><br> <a href="ov_clear.html">ov_clear()</a><br> @@ -69,11 +70,11 @@ <hr noshade> <table border=0 width=100%> <tr valign=top> -<td><p class=tiny>copyright © 2003 Xiph.org</p></td> +<td><p class=tiny>copyright © 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> diff --git a/doc/vorbisfile/return.html b/doc/vorbisfile/return.html index 8aa4691a..5349a2f5 100644 --- a/doc/vorbisfile/return.html +++ b/doc/vorbisfile/return.html @@ -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> @@ -64,11 +64,11 @@ is normally automatic and this return code is for informational purposes only.</ <hr noshade> <table border=0 width=100%> <tr valign=top> -<td><p class=tiny>copyright © 2003 Xiph.org</p></td> +<td><p class=tiny>copyright © 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> diff --git a/doc/vorbisfile/seekexample.html b/doc/vorbisfile/seekexample.html index 664ddcd8..ef0259af 100644 --- a/doc/vorbisfile/seekexample.html +++ b/doc/vorbisfile/seekexample.html @@ -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> @@ -32,7 +32,6 @@ First, relevant headers, including vorbis-specific "codec.h" and "vorbisfile.h" #include <stdio.h> #include "vorbis/codec.h" #include "vorbis/vorbisfile.h" -#include "../lib/misc.h" </b></pre> </td> </tr> @@ -52,16 +51,30 @@ int main(){ </tr> </table> -<p><a href="ov_open.html">ov_open()</a> must be +<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><a href="ov_open_callbacks.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. +<a href="ov_open_callbacks.html">ov_open_callbacks()</a> also checks to ensure that we're reading Vorbis format and not something else. <br><br> <table border=0 width=100% color=black cellspacing=0 cellpadding=7> <tr bgcolor=#cccccc> <td> <pre><b> - if(ov_open(stdin,&ov,NULL,-1)<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); } @@ -126,11 +139,11 @@ distribution in <a href="seeking_test_c.html">seeking_test.c</a>. <hr noshade> <table border=0 width=100%> <tr valign=top> -<td><p class=tiny>copyright © 2003 Xiph.org</p></td> +<td><p class=tiny>copyright © 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> diff --git a/doc/vorbisfile/seeking.html b/doc/vorbisfile/seeking.html index e570d5a0..19f07172 100644 --- a/doc/vorbisfile/seeking.html +++ b/doc/vorbisfile/seeking.html @@ -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>
@@ -94,11 +94,11 @@ nonseekable files and streams. <hr noshade>
<table border=0 width=100%>
<tr valign=top>
-<td><p class=tiny>copyright © 2003 Xiph.org</p></td>
+<td><p class=tiny>copyright © 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>
diff --git a/doc/vorbisfile/seeking_example_c.html b/doc/vorbisfile/seeking_example_c.html index 87c47e89..101745f7 100644 --- a/doc/vorbisfile/seeking_example_c.html +++ b/doc/vorbisfile/seeking_example_c.html @@ -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> @@ -28,14 +28,17 @@ The example program source: #include <stdio.h> #include "vorbis/codec.h" #include "vorbis/vorbisfile.h" -#include "../lib/misc.h" int main(){ OggVorbis_File ov; int i; +#ifdef _WIN32 /* We need to set stdin to binary mode under Windows */ + _setmode( _fileno( stdin ), _O_BINARY ); +#endif + /* open the file/pipe on stdin */ - if(ov_open(stdin,&ov,NULL,-1)==-1){ + if(ov_open_callbacks(stdin,&ov,NULL,-1,OV_CALLBACKS_NOCLOSE)==-1){ printf("Could not open input as an OggVorbis file.\n\n"); exit(1); } @@ -70,11 +73,11 @@ int main(){ <hr noshade> <table border=0 width=100%> <tr valign=top> -<td><p class=tiny>copyright © 2003 Xiph.org</p></td> +<td><p class=tiny>copyright © 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> diff --git a/doc/vorbisfile/seeking_test_c.html b/doc/vorbisfile/seeking_test_c.html index 87c47e89..101745f7 100644 --- a/doc/vorbisfile/seeking_test_c.html +++ b/doc/vorbisfile/seeking_test_c.html @@ -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> @@ -28,14 +28,17 @@ The example program source: #include <stdio.h> #include "vorbis/codec.h" #include "vorbis/vorbisfile.h" -#include "../lib/misc.h" int main(){ OggVorbis_File ov; int i; +#ifdef _WIN32 /* We need to set stdin to binary mode under Windows */ + _setmode( _fileno( stdin ), _O_BINARY ); +#endif + /* open the file/pipe on stdin */ - if(ov_open(stdin,&ov,NULL,-1)==-1){ + if(ov_open_callbacks(stdin,&ov,NULL,-1,OV_CALLBACKS_NOCLOSE)==-1){ printf("Could not open input as an OggVorbis file.\n\n"); exit(1); } @@ -70,11 +73,11 @@ int main(){ <hr noshade> <table border=0 width=100%> <tr valign=top> -<td><p class=tiny>copyright © 2003 Xiph.org</p></td> +<td><p class=tiny>copyright © 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> diff --git a/doc/vorbisfile/seekingexample.html b/doc/vorbisfile/seekingexample.html index a137786b..73c02ac2 100644 --- a/doc/vorbisfile/seekingexample.html +++ b/doc/vorbisfile/seekingexample.html @@ -80,23 +80,22 @@ int main(int argc, char **argv){ #ifdef _WIN32 _setmode( _fileno( stdin ), _O_BINARY ); - _setmode( _fileno( stdout ), _O_BINARY ); #endif </b></pre> </td> </tr> </table> -<p><a href="ov_open.html">ov_open()</a> must be +<p><a href="ov_open_callbacks.html">ov_open_callbacks()</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. +<a href="ov_open_callbacks.html">ov_open_callbacks()</a> also checks to ensure that we're reading Vorbis format and not something else. <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); } diff --git a/doc/vorbisfile/threads.html b/doc/vorbisfile/threads.html index f3acc828..ebfb9f9d 100644 --- a/doc/vorbisfile/threads.html +++ b/doc/vorbisfile/threads.html @@ -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> @@ -37,11 +37,11 @@ href="OggVorbis_File.html">OggVorbis_File</a> instance may be used safely from m <hr noshade> <table border=0 width=100%> <tr valign=top> -<td><p class=tiny>copyright © 2003 Xiph.org</p></td> +<td><p class=tiny>copyright © 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> diff --git a/doc/vorbisfile/vorbis_comment.html b/doc/vorbisfile/vorbis_comment.html index cf367865..ba81ad78 100644 --- a/doc/vorbisfile/vorbis_comment.html +++ b/doc/vorbisfile/vorbis_comment.html @@ -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> @@ -57,11 +57,11 @@ or set to some reasonable default (usually 0). <hr noshade> <table border=0 width=100%> <tr valign=top> -<td><p class=tiny>copyright © 2003 Xiph.org</p></td> +<td><p class=tiny>copyright © 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> diff --git a/doc/vorbisfile/vorbis_info.html b/doc/vorbisfile/vorbis_info.html index f97eedcb..54bd6212 100644 --- a/doc/vorbisfile/vorbis_info.html +++ b/doc/vorbisfile/vorbis_info.html @@ -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> @@ -67,11 +67,11 @@ The vorbis_info structure contains basic information about the audio in a vorbis <hr noshade> <table border=0 width=100%> <tr valign=top> -<td><p class=tiny>copyright © 2003 Xiph.org</p></td> +<td><p class=tiny>copyright © 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> diff --git a/doc/vorbisfile/vorbisfile_example_c.html b/doc/vorbisfile/vorbisfile_example_c.html index bdb9f615..f9f1873f 100644 --- a/doc/vorbisfile/vorbisfile_example_c.html +++ b/doc/vorbisfile/vorbisfile_example_c.html @@ -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> @@ -46,7 +46,7 @@ int main(int argc, char **argv){ _setmode( _fileno( stdout ), _O_BINARY ); #endif - 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); } @@ -93,11 +93,11 @@ int main(int argc, char **argv){ <hr noshade> <table border=0 width=100%> <tr valign=top> -<td><p class=tiny>copyright © 2003 Xiph.org</p></td> +<td><p class=tiny>copyright © 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> |