[xiph-cvs] cvs commit: vorbis/doc/vorbisfile ov_pcm_seek_page.html ov_time_seek_page.html seeking_example_c.html OggVorbis_File.html chaining_example_c.html chainingexample.html datastructures.html example.html initialization.html ov_bitrate.html ov_bitrate_instant.html ov_open.html ov_open_callbacks.html ov_pcm_seek.html ov_pcm_total.html ov_raw_seek.html ov_raw_total.html ov_read.html ov_streams.html ov_time_total.html overview.html seekexample.html seeking.html vorbisfile_example_c.html
Jack Moffitt
jack at xiph.org
Mon Oct 30 20:17:56 PST 2000
jack 00/10/30 20:17:55
Modified: doc/vorbisfile Tag: branch_beta3 OggVorbis_File.html
chaining_example_c.html chainingexample.html
datastructures.html example.html
initialization.html ov_bitrate.html
ov_bitrate_instant.html ov_open.html
ov_open_callbacks.html ov_pcm_seek.html
ov_pcm_total.html ov_raw_seek.html
ov_raw_total.html ov_read.html ov_streams.html
ov_time_total.html overview.html seekexample.html
seeking.html vorbisfile_example_c.html
Added: doc/vorbisfile Tag: branch_beta3 ov_pcm_seek_page.html
ov_time_seek_page.html seeking_example_c.html
Log:
here are current docs
Revision Changes Path
No revision
No revision
1.1.2.2 +6 -3 vorbis/doc/vorbisfile/Attic/OggVorbis_File.html
Index: OggVorbis_File.html
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/vorbisfile/Attic/OggVorbis_File.html,v
retrieving revision 1.1.2.1
retrieving revision 1.1.2.2
diff -u -r1.1.2.1 -r1.1.2.2
--- OggVorbis_File.html 2000/10/30 09:16:15 1.1.2.1
+++ OggVorbis_File.html 2000/10/31 04:17:51 1.1.2.2
@@ -22,7 +22,8 @@
<p>
This structure is used in all vorbisfile 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>.
<p>
-After use, the OggVorbis_File structure must be deallocated with a call to <a href="ov_clear.html">ov_clear()</a>.
+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 passed to libvorbisfile, it is owned by vorbisfile. The file should not be used by any other applications or functions outside the Vorbisfile API.
<br><br>
<table border=0 width=100% color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
@@ -58,7 +59,7 @@
vorbis_dsp_state vd; /* central working state for the packet->PCM decoder */
vorbis_block vb; /* local working space for packet->PCM decode */
- ov_callbacks callbacks;
+ <a href="ov_callbacks.html">ov_callbacks</a> callbacks;
} OggVorbis_File;</b></pre>
</td>
@@ -72,7 +73,9 @@
<dt><i>seekable</i></dt>
<dd>Read-only int indicating whether file is seekable, i.e., physical file is seekable, a pipe isn't.</dd>
<dt><i>links</i></dt>
-<dd>Read-only int indicating the number of logical bitstreams within the physical bitstream.</dd>
+<dd>Read-only int indicating the number of logical bitstreams within the physical bitstream.</dd>
+<dt><i>ov_callbacks</i></dt>
+<dd>Collection of file manipulation routines to be used on this data source.</dd>
</dl>
<h3>Notes</h3>
1.1.2.2 +38 -39 vorbis/doc/vorbisfile/Attic/chaining_example_c.html
Index: chaining_example_c.html
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/vorbisfile/Attic/chaining_example_c.html,v
retrieving revision 1.1.2.1
retrieving revision 1.1.2.2
diff -u -r1.1.2.1 -r1.1.2.2
--- chaining_example_c.html 2000/10/30 09:16:15 1.1.2.1
+++ chaining_example_c.html 2000/10/31 04:17:51 1.1.2.2
@@ -24,45 +24,44 @@
<td>
<pre><b>
-#include "vorbis/codec.h"
-#include "vorbis/vorbisfile.h"
-#include "../lib/misc.h"
-
-int main(){
- OggVorbis_File ov;
- int i;
-
- /* open the file/pipe on stdin */
- if(ov_open(stdin,&ov,NULL,-1)==-1){
- printf("Could not open input as an OggVorbis file.\n\n");
- exit(1);
- }
-
- /* print details about each logical bitstream in the input */
- if(ov_seekable(&ov)){
- printf("Input bitstream contained %ld logical bitstream section(s).\n",
- ov_streams(&ov));
- printf("Total bitstream playing time: %ld seconds\n\n",
- (long)ov_time_total(&ov,-1));
-
- }else{
- printf("Standard input was not seekable.\n"
- "First logical bitstream information:\n\n");
- }
-
- for(i=0;i<ov_streams(&ov);i++){
- vorbis_info *vi=ov_info(&ov,i);
- printf("\tlogical bitstream section %d information:\n",i+1);
- printf("\t\t%ldHz %d channels bitrate %ldkbps serial number=%ld\n",
- vi->rate,vi->channels,ov_bitrate(&ov,i)/1000,
- ov_serialnumber(&ov,i));
- printf("\t\tcompressed length: %ld bytes ",(long)(ov_raw_total(&ov,i)));
- printf(" play time: %lds\n",(long)ov_time_total(&ov,i));
- }
-
- ov_clear(&ov);
- return 0;
-}
+#include <vorbis/codec.h>
+#include <vorbis/vorbisfile.h>
+
+int main(){
+ OggVorbis_File ov;
+ int i;
+
+ /* open the file/pipe on stdin */
+ if(ov_open(stdin,&ov,NULL,-1)<0){
+ printf("Could not open input as an OggVorbis file.\n\n");
+ exit(1);
+ }
+
+ /* print details about each logical bitstream in the input */
+ if(ov_seekable(&ov)){
+ printf("Input bitstream contained %ld logical bitstream section(s).\n",
+ ov_streams(&ov));
+ printf("Total bitstream playing time: %ld seconds\n\n",
+ (long)ov_time_total(&ov,-1));
+
+ }else{
+ printf("Standard input was not seekable.\n"
+ "First logical bitstream information:\n\n");
+ }
+
+ for(i=0;i<ov_streams(&ov);i++){
+ vorbis_info *vi=ov_info(&ov,i);
+ printf("\tlogical bitstream section %d information:\n",i+1);
+ printf("\t\t%ldHz %d channels bitrate %ldkbps serial number=%ld\n",
+ vi->rate,vi->channels,ov_bitrate(&ov,i)/1000,
+ ov_serialnumber(&ov,i));
+ printf("\t\tcompressed length: %ld bytes ",(long)(ov_raw_total(&ov,i)));
+ printf(" play time: %lds\n",(long)ov_time_total(&ov,i));
+ }
+
+ ov_clear(&ov);
+ return 0;
+}
</b></pre>
</td>
1.1.2.2 +1 -1 vorbis/doc/vorbisfile/Attic/chainingexample.html
Index: chainingexample.html
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/vorbisfile/Attic/chainingexample.html,v
retrieving revision 1.1.2.1
retrieving revision 1.1.2.2
diff -u -r1.1.2.1 -r1.1.2.2
--- chainingexample.html 2000/10/30 09:16:15 1.1.2.1
+++ chainingexample.html 2000/10/31 04:17:51 1.1.2.2
@@ -59,7 +59,7 @@
<tr bgcolor=#cccccc>
<td>
<pre><b>
- if(ov_open(stdin,&ov,NULL,-1)==-1){
+ if(ov_open(stdin,&ov,NULL,-1)<0){
printf("Could not open input as an OggVorbis file.\n\n");
exit(1);
}
1.1.2.2 +3 -1 vorbis/doc/vorbisfile/Attic/datastructures.html
Index: datastructures.html
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/vorbisfile/Attic/datastructures.html,v
retrieving revision 1.1.2.1
retrieving revision 1.1.2.2
diff -u -r1.1.2.1 -r1.1.2.2
--- datastructures.html 2000/10/30 09:16:15 1.1.2.1
+++ datastructures.html 2000/10/31 04:17:51 1.1.2.2
@@ -17,7 +17,9 @@
<p>There are several data structures used to hold file and bitstream information during vorbisfile decoding.
<p>
All the <b>vorbisfile</b> specific data structures are declared in "vorbis/vorbisfile.h" or "vorbis/codec.h".
-<p>
+<p>
+<p>When using vorbisfile, we usually won't need to know about most of the contents of these data structures, but it may be helpful to understand what they contain.
+<br><br>
<table border=1 color=black width=50% cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
1.1.2.2 +15 -14 vorbis/doc/vorbisfile/Attic/example.html
Index: example.html
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/vorbisfile/Attic/example.html,v
retrieving revision 1.1.2.1
retrieving revision 1.1.2.2
diff -u -r1.1.2.1 -r1.1.2.2
--- example.html 2000/10/30 09:16:15 1.1.2.1
+++ example.html 2000/10/31 04:17:51 1.1.2.2
@@ -140,20 +140,21 @@
<td>
<pre><b>
- while(!eof){
- long ret=ov_read(&vf,pcmout,sizeof(pcmout),0,2,1,¤t_section);
- switch(ret){
- case 0:
- /* EOF */
- eof=1;
- break;
- case -1:
- break;
- default:
- fwrite(pcmout,1,ret,stdout);
- break;
- }
- }
+ while(!eof){
+ long ret=ov_read(&vf,pcmout,sizeof(pcmout),0,2,1,¤t_section);
+ if (ret == 0) {
+ /* EOF */
+ eof=1;
+ } else if (ret < 0) {
+ /* error in the stream. Not a problem, just reporting it in
+ case we (the app) cares. In this case, we don't. */
+ } else {
+ /* we don't bother dealing with sample rate changes, etc, but
+ you'll have to*/
+ fwrite(pcmout,1,ret,stdout);
+ }
+ }
+
</b></pre>
</td>
1.1.2.2 +3 -3 vorbis/doc/vorbisfile/Attic/initialization.html
Index: initialization.html
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/vorbisfile/Attic/initialization.html,v
retrieving revision 1.1.2.1
retrieving revision 1.1.2.2
diff -u -r1.1.2.1 -r1.1.2.2
--- initialization.html 2000/10/30 09:16:15 1.1.2.1
+++ initialization.html 2000/10/31 04:17:51 1.1.2.2
@@ -1,20 +1,20 @@
<html>
<head>
-<title>vorbisfile - Setup/Teardown</title>
+<title>libvorbisfile - Setup/Teardown</title>
<link rel=stylesheet href="style.css" type="text/css">
</head>
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
<table border=0 width=100%>
<tr>
-<td><p class=tiny>vorbisfile documentation</p></td>
+<td><p class=tiny>libvorbisfile documentation</p></td>
<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
</tr>
</table>
<h1>Setup/Teardown</h1>
-<p>In order to decode audio using vorbisfile, a bitstream containing vorbis audio must be properly initialized and cleared when decoding is finished.
+<p>In order to decode audio using libvorbisfile, a bitstream containing vorbis audio must be properly initialized and cleared when decoding is finished.
<p>
All the <b>vorbisfile</b> initialization and deallocation routines are declared in "vorbis/vorbisfile.h".
<p>
1.1.2.2 +4 -3 vorbis/doc/vorbisfile/Attic/ov_bitrate.html
Index: ov_bitrate.html
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/vorbisfile/Attic/ov_bitrate.html,v
retrieving revision 1.1.2.1
retrieving revision 1.1.2.2
diff -u -r1.1.2.1 -r1.1.2.2
--- ov_bitrate.html 2000/10/30 09:16:15 1.1.2.1
+++ ov_bitrate.html 2000/10/31 04:17:52 1.1.2.2
@@ -17,7 +17,8 @@
<p><i>declared in "vorbis/vorbisfile.h";</i></p>
-<p>This function returns the average bitrate for the specified logical bitstream. This may be different from the <a href=ov_info.html>ov_info->nominal_bitrate</a> value, as it is based on the actual average for this bitstream.
+<p>This function returns the average bitrate for the specified logical bitstream. This may be different from the <a href=ov_info.html>ov_info->nominal_bitrate</a> value, as it is based on the actual average for this bitstream if the file is seekable.
+<p>Nonseekable files will return the nominal bitrate setting or the average of the upper and lower bounds, if any of these values are set.
<p>
<br><br>
@@ -43,8 +44,8 @@
<h3>Return Values</h3>
<blockquote>
-<li>
--1 indicates that the file is not seekable and the nominal, upper, and lower bounds are not set for the file.</li>
+<li>OV_EINVAL indicates that an invalid argument value was submitted.</li>
+<li>OV_FALSE means the call returned a 'false' status, which in this case most likely indicates that the file is nonseekable and the upper, lower, and nominal bitrates were unset.
<li><i>n</i> indicates the bitrate for the given logical bitstream or the entire
physical bitstream. If the file is open for random (seekable) access, it will
find the *actual* average bitrate. If the file is streaming (nonseekable), it
1.1.2.2 +2 -1 vorbis/doc/vorbisfile/Attic/ov_bitrate_instant.html
Index: ov_bitrate_instant.html
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/vorbisfile/Attic/ov_bitrate_instant.html,v
retrieving revision 1.1.2.1
retrieving revision 1.1.2.2
diff -u -r1.1.2.1 -r1.1.2.2
--- ov_bitrate_instant.html 2000/10/30 09:16:15 1.1.2.1
+++ ov_bitrate_instant.html 2000/10/31 04:17:52 1.1.2.2
@@ -42,7 +42,8 @@
<blockquote>
<li>
0 indicates the beginning of the file or unchanged bitrate info.</li>
-<li><i>n</i> indicates the actual bitrate since the last call.</li>
+<li><i>n</i> indicates the actual bitrate since the last call.</li>
+<li>OV_FALSE indicates that the call returned a 'false' status. In this case, this error code is returned if playback is not in progress, and thus there is no instantaneous bitrate information to report.</li>
</blockquote>
<p>
1.1.2.2 +11 -5 vorbis/doc/vorbisfile/Attic/ov_open.html
Index: ov_open.html
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/vorbisfile/Attic/ov_open.html,v
retrieving revision 1.1.2.1
retrieving revision 1.1.2.2
diff -u -r1.1.2.1 -r1.1.2.2
--- ov_open.html 2000/10/30 09:16:16 1.1.2.1
+++ ov_open.html 2000/10/31 04:17:52 1.1.2.2
@@ -23,8 +23,9 @@
or pipe (it need not be seekable--though this obviously restricts what
can be done with the bitstream). <tt>vf</tt> should be a pointer to the
OggVorbis_File structure--this is used for ALL the externally visible vorbisfile
-functions. Once this has been called, the same <tt>OggVorbis_File</tt>
+functions. Once this has been called, the same <a href="OggVorbis_File.html">OggVorbis_File</a>
struct should be passed to all the vorbisfile 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
@@ -33,7 +34,7 @@
</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 <tt>ov_clear()</tt> to clear
+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.
<br><br>
<table border=0 color=black cellspacing=0 cellpadding=7>
@@ -72,10 +73,15 @@
<li>
0 for success</li>
-<li>
--1 for failure</li>
+<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_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>
-If the function fails, this was not recognizable as an OggVorbis file.
<p>
<h3>Notes</h3>
1.1.2.2 +8 -4 vorbis/doc/vorbisfile/Attic/ov_open_callbacks.html
Index: ov_open_callbacks.html
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/vorbisfile/Attic/ov_open_callbacks.html,v
retrieving revision 1.1.2.1
retrieving revision 1.1.2.2
diff -u -r1.1.2.1 -r1.1.2.2
--- ov_open_callbacks.html 2000/10/30 09:16:16 1.1.2.1
+++ ov_open_callbacks.html 2000/10/31 04:17:52 1.1.2.2
@@ -69,11 +69,15 @@
<blockquote>
<li>
0 for success</li>
-
-<li>
--1 for failure</li>
+<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_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>
-If the function fails, this was not recognizable as an OggVorbis file.
<p>
<h3>Notes</h3>
1.1.2.2 +14 -2 vorbis/doc/vorbisfile/Attic/ov_pcm_seek.html
Index: ov_pcm_seek.html
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/vorbisfile/Attic/ov_pcm_seek.html,v
retrieving revision 1.1.2.1
retrieving revision 1.1.2.2
diff -u -r1.1.2.1 -r1.1.2.2
--- ov_pcm_seek.html 2000/10/30 09:16:16 1.1.2.1
+++ ov_pcm_seek.html 2000/10/31 04:17:52 1.1.2.2
@@ -50,8 +50,20 @@
0 for success</li>
<li>
-Nonzero for failure</li>
-</blockquote>
+nonzero indicates failure, described by several error codes:</li>
+<ul>
+<li>OV_ENOSEEK - Bitstream is not seekable.
+</li>
+<li>OV_EINVAL - Invalid argument value.
+</li>
+<li>OV_EREAD - A read from media returned an error.
+</li>
+<li>OV_EFAULT - Internal logic fault; indicates a bug or heap/stack
+ corruption.
+</li>
+<li>OV_EBADLINK - Invalid stream section supplied to libvorbis/libvorbisfile, or the requested link is corrupt.
+</li>
+</ul></blockquote>
<br><br>
<hr noshade>
<table border=0 width=100%>
1.1.2.2 +3 -4 vorbis/doc/vorbisfile/Attic/ov_pcm_total.html
Index: ov_pcm_total.html
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/vorbisfile/Attic/ov_pcm_total.html,v
retrieving revision 1.1.2.1
retrieving revision 1.1.2.2
diff -u -r1.1.2.1 -r1.1.2.2
--- ov_pcm_total.html 2000/10/30 09:16:16 1.1.2.1
+++ ov_pcm_total.html 2000/10/31 04:17:52 1.1.2.2
@@ -36,14 +36,13 @@
<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible vorbisfile
functions.</dd>
<dt><i>i</i></dt>
-<dd>Link to the desired logical bitstream. For nonseekable files, this argument is ignored. To retrieve the total pcm samples for the entire physical bitstream, this parameter should be set to -1.</dd>
+<dd>Link to the desired logical bitstream. To retrieve the total pcm samples for the entire physical bitstream, this parameter should be set to -1.</dd>
</dl>
<h3>Return Values</h3>
-<blockquote>
-<li>
--1 if the bitstream is nonseekable.</li>
+<blockquote>
+<li>OV_EINVAL means that the argument was invalid. In this case, the requested bitstream did not exist or the bitstream is unseekable.</li>
<li>
total length in pcm samples of content if i=-1.</li>
<li>length in pcm samples of logical bitstream if i=1 to n.</li>
1.1.2.2 +10 -2 vorbis/doc/vorbisfile/Attic/ov_raw_seek.html
Index: ov_raw_seek.html
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/vorbisfile/Attic/ov_raw_seek.html,v
retrieving revision 1.1.2.1
retrieving revision 1.1.2.2
diff -u -r1.1.2.1 -r1.1.2.2
--- ov_raw_seek.html 2000/10/30 09:16:16 1.1.2.1
+++ ov_raw_seek.html 2000/10/31 04:17:52 1.1.2.2
@@ -21,7 +21,7 @@
<p>This also updates everything needed within the
decoder, so you can immediately call <a href="ov_read.html">ov_read()</a> and get data from
the newly seeked to position.
-
+<p>When seek speed is a priority, this is the best vorbisfile seek funtion to use.
<br><br>
<table border=0 color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
@@ -48,7 +48,15 @@
<blockquote>
<li>
0 indicates success</li>
-<li>nonzero indicates failure.</li>
+<li>nonzero indicates failure, described by several error codes:</li>
+<ul>
+<li>OV_ENOSEEK - Bitstream is not seekable.
+</li>
+<li>OV_EINVAL - Invalid argument value.
+</li>
+<li>OV_EBADLINK - Invalid stream section supplied to libvorbis/libvorbisfile, or the requested link is corrupt.
+</li>
+</ul>
</blockquote>
<p>
<br><br>
1.1.2.2 +2 -3 vorbis/doc/vorbisfile/Attic/ov_raw_total.html
Index: ov_raw_total.html
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/vorbisfile/Attic/ov_raw_total.html,v
retrieving revision 1.1.2.1
retrieving revision 1.1.2.2
diff -u -r1.1.2.1 -r1.1.2.2
--- ov_raw_total.html 2000/10/30 09:16:16 1.1.2.1
+++ ov_raw_total.html 2000/10/31 04:17:52 1.1.2.2
@@ -36,14 +36,13 @@
<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible vorbisfile
functions.</dd>
<dt><i>i</i></dt>
-<dd><b>Link to the desired logical bitstream. For nonseekable files, this argument is ignored. To retrieve the total bytes for the entire physical bitstream, this parameter should be set to -1.</b></dd>
+<dd><b>Link to the desired logical bitstream. To retrieve the total bytes for the entire physical bitstream, this parameter should be set to -1.</b></dd>
</dl>
<h3>Return Values</h3>
<blockquote>
-<li>
--1 if the bitstream is nonseekable.</li>
+<li>OV_EINVAL means that the argument was invalid. In this case, the requested bitstream did not exist or the bitstream is nonseekable</li>
<li>
total length in compressed bytes of content if i=-1.</li>
<li>length in compressed bytes of logical bitstream if i=1 to n.</li>
1.1.2.2 +7 -2 vorbis/doc/vorbisfile/Attic/ov_read.html
Index: ov_read.html
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/vorbisfile/Attic/ov_read.html,v
retrieving revision 1.1.2.1
retrieving revision 1.1.2.2
diff -u -r1.1.2.1 -r1.1.2.2
--- ov_read.html 2000/10/30 09:16:16 1.1.2.1
+++ ov_read.html 2000/10/31 04:17:52 1.1.2.2
@@ -65,10 +65,15 @@
<h3>Return Values</h3>
<blockquote>
<li>
--1 indicates an error or hole in data.</li>
+OV_HOLE indicates there was an interruption in the data. (one of: garbage between pages, loss of sync followed by recapture, or a corrupt page)</li>
<li>
+OV_EBADLINK indicates that an invalid stream section was supplied to libvorbisfile,
+ or the requested link is corrupt.
+</li>
+
+<li>
0 indicates EOF</li>
-<li><i>n</i> indicates actual number of bytes read. This may vary, but will be no longer than the parameter <tt>length</tt>.</li>
+<li><i>n</i> indicates actual number of bytes read. Within a logical bitstream, the number should equal <tt>length</tt>. At the end of a logical bitstream, the number of bytes read will equal the remaining number of bytes in the bitstream.</li>
</blockquote>
<p>
<h3>Notes</h3>
1.1.2.2 +1 -1 vorbis/doc/vorbisfile/Attic/ov_streams.html
Index: ov_streams.html
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/vorbisfile/Attic/ov_streams.html,v
retrieving revision 1.1.2.1
retrieving revision 1.1.2.2
diff -u -r1.1.2.1 -r1.1.2.2
--- ov_streams.html 2000/10/30 09:16:16 1.1.2.1
+++ ov_streams.html 2000/10/31 04:17:52 1.1.2.2
@@ -1,7 +1,7 @@
<html>
<head>
-<title>vorbisfile - function - ov_bitrate</title>
+<title>vorbisfile - function - ov_streams</title>
<link rel=stylesheet href="style.css" type="text/css">
</head>
1.1.2.2 +2 -3 vorbis/doc/vorbisfile/Attic/ov_time_total.html
Index: ov_time_total.html
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/vorbisfile/Attic/ov_time_total.html,v
retrieving revision 1.1.2.1
retrieving revision 1.1.2.2
diff -u -r1.1.2.1 -r1.1.2.2
--- ov_time_total.html 2000/10/30 09:16:16 1.1.2.1
+++ ov_time_total.html 2000/10/31 04:17:52 1.1.2.2
@@ -39,14 +39,13 @@
functions. Once this has been called, the same <tt>OggVorbis_File</tt>
struct should be passed to all the vorbisfile functions.</dd>
<dt><i>i</i></dt>
-<dd><b>Link to the desired logical bitstream. For nonseekable files, this argument is ignored. To retrieve the <a href="vorbis_info.html">vorbis_info</a> struct for the current bitstream, this parameter should be set to -1.</b></dd>
+<dd><b>Link to the desired logical bitstream. To retrieve the <a href="vorbis_info.html">vorbis_info</a> struct for the current bitstream, this parameter should be set to -1.</b></dd>
</dl>
<h3>Return Values</h3>
<blockquote>
-<li>
--1 if the bitstream is nonseekable.</li>
+<li>OV_EINVAL means that the argument was invalid. In this case, the requested bitstream did not exist or the bitstream is nonseekable.</li>
<li>
total length in seconds of content if i=-1.</li>
<li>length in seconds of logical bitstream if i=1 to n.</li>
1.1.2.2 +3 -2 vorbis/doc/vorbisfile/Attic/overview.html
Index: overview.html
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/vorbisfile/Attic/overview.html,v
retrieving revision 1.1.2.1
retrieving revision 1.1.2.2
diff -u -r1.1.2.1 -r1.1.2.2
--- overview.html 2000/10/30 09:16:16 1.1.2.1
+++ overview.html 2000/10/31 04:17:52 1.1.2.2
@@ -1,7 +1,7 @@
<html>
<head>
-<title>libshout - API Overview</title>
+<title>libvorbisfile - API Overview</title>
<link rel=stylesheet href="style.css" type="text/css">
</head>
@@ -14,7 +14,8 @@
</table>
<h1>VorbisFile API Overview</h1>
-
+
+<p>The makeup of the vorbisfile API is relatively simple. It revolves around a single file resource. This resource is passed to the Vorbisfile API, where it is opened, manipulated, and closed, in the form of an <a href="OggVorbis_File.html">OggVorbis_File</a> struct.
<p>
The vorbisfile API consists of the following functional categories:
<p>
1.1.2.2 +1 -1 vorbis/doc/vorbisfile/Attic/seekexample.html
Index: seekexample.html
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/vorbisfile/Attic/seekexample.html,v
retrieving revision 1.1.2.1
retrieving revision 1.1.2.2
diff -u -r1.1.2.1 -r1.1.2.2
--- seekexample.html 2000/10/30 09:16:16 1.1.2.1
+++ seekexample.html 2000/10/31 04:17:52 1.1.2.2
@@ -61,7 +61,7 @@
<tr bgcolor=#cccccc>
<td>
<pre><b>
- if(ov_open(stdin,&ov,NULL,-1)==-1){
+ if(ov_open(stdin,&ov,NULL,-1)<0){
printf("Could not open input as an OggVorbis file.\n\n");
exit(1);
}
1.1.2.2 +12 -1 vorbis/doc/vorbisfile/Attic/seeking.html
Index: seeking.html
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/vorbisfile/Attic/seeking.html,v
retrieving revision 1.1.2.1
retrieving revision 1.1.2.2
diff -u -r1.1.2.1 -r1.1.2.2
--- seeking.html 2000/10/30 09:16:16 1.1.2.1
+++ seeking.html 2000/10/31 04:17:52 1.1.2.2
@@ -18,7 +18,10 @@
<p>
All the <b>vorbisfile</b> seeking routines are declared in "vorbis/vorbisfile.h".
<p>
+<p>Certain seeking functions are best suited to different situations. When speed is important, page-level seeking should be used.
+</ul>
+
<table border=1 color=black width=50% cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td><b>function</b></td>
@@ -33,8 +36,16 @@
<td>This function seeks to a specific point in the bitstream, specified in pcm samples.</td>
</tr>
<tr valign=top>
+ <td><a href="ov_pcm_seek.html">ov_pcm_seek_page</a></td>
+ <td>This function seeks to the closest page preceding a point in the bitstream, specified in pcm samples.</td>
+</tr>
+<tr valign=top>
<td><a href="ov_time_seek.html">ov_time_seek</a></td>
- <td>This function seeks to a specific time in the bitstream, specified in seconds. The easiest and simplest seeking method.</td>
+ <td>This function seeks to a time in the bitstream, specified in seconds. The easiest and simplest seeking method.</td>
+</tr>
+<tr valign=top>
+ <td><a href="ov_time_seek_page.html">ov_time_seek_page</a></td>
+ <td>This function seeks to the closest page preceding a time in the bitstream, specified in seconds.</td>
</tr>
</table>
1.1.2.2 +15 -15 vorbis/doc/vorbisfile/Attic/vorbisfile_example_c.html
Index: vorbisfile_example_c.html
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/vorbisfile/Attic/vorbisfile_example_c.html,v
retrieving revision 1.1.2.1
retrieving revision 1.1.2.2
diff -u -r1.1.2.1 -r1.1.2.2
--- vorbisfile_example_c.html 2000/10/30 09:16:16 1.1.2.1
+++ vorbisfile_example_c.html 2000/10/31 04:17:52 1.1.2.2
@@ -62,21 +62,21 @@
fprintf(stderr,"Encoded by: %s\n\n",ov_comment(&vf,-1)->vendor);
}
- while(!eof){
- long ret=ov_read(&vf,pcmout,sizeof(pcmout),0,2,1,¤t_section);
- switch(ret){
- case 0:
- /* EOF */
- eof=1;
- break;
- case -1:
- break;
- default:
- fwrite(pcmout,1,ret,stdout);
- break;
- }
- }
-
+ while(!eof){
+ long ret=ov_read(&vf,pcmout,sizeof(pcmout),0,2,1,¤t_section);
+ if (ret == 0) {
+ /* EOF */
+ eof=1;
+ } else if (ret < 0) {
+ /* error in the stream. Not a problem, just reporting it in
+ case we (the app) cares. In this case, we don't. */
+ } else {
+ /* we don't bother dealing with sample rate changes, etc, but
+ you'll have to*/
+ fwrite(pcmout,1,ret,stdout);
+ }
+ }
+
ov_clear(&vf);
fprintf(stderr,"Done.\n");
No revision
No revision
1.1.2.1 +83 -0 vorbis/doc/vorbisfile/Attic/ov_pcm_seek_page.html
1.1.2.1 +84 -0 vorbis/doc/vorbisfile/Attic/ov_time_seek_page.html
1.1.2.1 +83 -0 vorbis/doc/vorbisfile/Attic/seeking_example_c.html
--- >8 ----
List archives: http://www.xiph.org/archives/
Ogg project homepage: http://www.xiph.org/ogg/
To unsubscribe from this list, send a message to 'cvs-request at xiph.org'
containing only the word 'unsubscribe' in the body. No subject is needed.
Unsubscribe messages sent to the list will be ignored/filtered.
More information about the commits
mailing list