[xiph-commits] r14771 - in trunk/vorbis: doc/vorbisfile include/vorbis lib
xiphmont at svn.xiph.org
xiphmont at svn.xiph.org
Thu Apr 17 11:21:55 PDT 2008
Author: xiphmont
Date: 2008-04-17 11:21:55 -0700 (Thu, 17 Apr 2008)
New Revision: 14771
Added:
trunk/vorbis/doc/vorbisfile/ov_read_filter.html
Modified:
trunk/vorbis/doc/vorbisfile/decoding.html
trunk/vorbis/doc/vorbisfile/reference.html
trunk/vorbis/include/vorbis/vorbisfile.h
trunk/vorbis/lib/vorbisfile.c
Log:
Commit 01-ov_read_filter patch from #381; closes feature request #1352. Also updates included HTML documentation to cover the added ov_read_filter() function.
Modified: trunk/vorbis/doc/vorbisfile/decoding.html
===================================================================
--- trunk/vorbis/doc/vorbisfile/decoding.html 2008-04-17 17:50:44 UTC (rev 14770)
+++ trunk/vorbis/doc/vorbisfile/decoding.html 2008-04-17 18:21:55 UTC (rev 14771)
@@ -20,9 +20,10 @@
<p>
After <a href="initialization.html">initialization</a>, decoding audio
-is as simple as calling <a href="ov_read.html">ov_read()</a>. This
-function works similarly to reading from a normal file using
-<tt>read()</tt>.<p>
+is as simple as calling <a href="ov_read.html">ov_read()</a> (or the
+similar functions <a href="ov_read_float.html">ov_read_float()</a> and
+<a href="ov_read_filter.html">ov_read_filter</a>). This function works
+similarly to reading from a normal file using <tt>read()</tt>.<p>
However, a few differences are worth noting:
@@ -68,6 +69,10 @@
<td><a href="ov_read_float.html">ov_read_float</a></td>
<td>This function decodes to floats instead of integer samples.</td>
</tr>
+<tr valign=top>
+ <td><a href="ov_read_filter.html">ov_read_filter</a></td>
+ <td>This function works like <a href="ov_read.html">ov_read</a>, but passes the PCM data through the provided filter before converting to integer sample data.</td>
+</tr>
</table>
<br><br>
Added: trunk/vorbis/doc/vorbisfile/ov_read_filter.html
===================================================================
--- trunk/vorbis/doc/vorbisfile/ov_read_filter.html (rev 0)
+++ trunk/vorbis/doc/vorbisfile/ov_read_filter.html 2008-04-17 18:21:55 UTC (rev 14771)
@@ -0,0 +1,114 @@
+<html>
+
+<head>
+<title>Vorbisfile - function - ov_read_filter</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_read_filter()</h1>
+
+<p><i>declared in "vorbis/vorbisfile.h";</i></p>
+
+<p>
+ <tt>ov_read_filter()</tt> is a variant of <a
+ href="ov_read.html">ov_read()</a>, the main function used to decode
+ a Vorbis file within a loop. It passes the decoded floating point
+ PCM data to the filter specified in the function arguments before
+ converting the data to integer output samples. All other aspects of
+ its behavior are as with <a href="ov_read.html">ov_read()</a>.
+<p>
+
+<br><br>
+<table border=0 color=black cellspacing=0 cellpadding=7>
+<tr bgcolor=#cccccc>
+ <td>
+<pre><b>
+long ov_read_filter(<a href="OggVorbis_File.html">OggVorbis_File</a> *vf, char *buffer, int length, int bigendianp, int word, int sgned, int *bitstream,
+ void (*filter)(float **pcm,long channels,long samples,void *filter_param),void *filter_param);
+</b></pre>
+ </td>
+</tr>
+</table>
+
+<h3>Parameters</h3>
+<dl>
+<dt><i>vf</i></dt>
+<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile
+functions.</dd>
+<dt><i>buffer</i></dt>
+<dd>A pointer to an output buffer. The decoded output is inserted into this buffer.</dd>
+<dt><i>length</i></dt>
+<dd>Number of bytes to be read into the buffer. Should be the same size as the buffer. A typical value is 4096.</dd>
+<dt><i>bigendianp</i></dt>
+<dd>Specifies big or little endian byte packing. 0 for little endian, 1 for b
+ig endian. Typical value is 0.</dd>
+<dt><i>word</i></dt>
+<dd>Specifies word size. Possible arguments are 1 for 8-bit samples, or 2 or
+16-bit samples. Typical value is 2.</dd>
+<dt><i>sgned</i></dt>
+<dd>Signed or unsigned data. 0 for unsigned, 1 for signed. Typically 1.</dd>
+<dt><i>bitstream</i></dt>
+<dd>A pointer to the number of the current logical bitstream.</dd>
+<dt><i>filter</i></dt>
+<dd>Filter function to process float PCM data prior to conversion to interleaved integer output.</dd>
+<dt><i>filter_param</i></dt>
+<dd>Data to pass through to the filter function.</dd>
+
+</dl>
+
+
+<h3>Return Values</h3>
+<blockquote>
+<dl>
+<dt>OV_HOLE</dt>
+ <dd>indicates there was an interruption in the data.
+ <br>(one of: garbage between pages, loss of sync followed by
+ recapture, or a corrupt page)</dd>
+<dt>OV_EBADLINK</dt>
+ <dd>indicates that an invalid stream section was supplied to
+ libvorbisfile, or the requested link is corrupt.</dd>
+<dt>0</dt>
+ <dd>indicates EOF</dd>
+<dt><i>n</i></dt>
+ <dd>indicates actual number of bytes read. <tt>ov_read()</tt> will
+ decode at most one vorbis packet per invocation, so the value
+ returned will generally be less than <tt>length</tt>.
+</dl>
+</blockquote>
+
+<h3>Notes</h3>
+<p><b>Typical usage:</b>
+<blockquote>
+<tt>bytes_read = ov_read_filter(&vf,
+buffer, 4096,0,2,1,&current_section, filter, (void *)filter_data_ptr)</tt>
+</blockquote>
+
+This reads up to 4096 bytes into a buffer, with signed 16-bit
+little-endian samples. The decoded data is passed to the function <tt>filter</tt> before integer conversiona nd interleave.
+</p>
+
+
+
+<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>
Modified: trunk/vorbis/doc/vorbisfile/reference.html
===================================================================
--- trunk/vorbis/doc/vorbisfile/reference.html 2008-04-17 17:50:44 UTC (rev 14770)
+++ trunk/vorbis/doc/vorbisfile/reference.html 2008-04-17 18:21:55 UTC (rev 14771)
@@ -34,6 +34,7 @@
<b>Decoding</b><br>
<a href="ov_read.html">ov_read()</a><br>
<a href="ov_read_float.html">ov_read_float()</a><br>
+<a href="ov_read_filter.html">ov_read_filter()</a><br>
<a href="ov_crosslap.html">ov_crosslap()</a><br>
<br>
<b>Seeking</b><br>
Modified: trunk/vorbis/include/vorbis/vorbisfile.h
===================================================================
--- trunk/vorbis/include/vorbis/vorbisfile.h 2008-04-17 17:50:44 UTC (rev 14770)
+++ trunk/vorbis/include/vorbis/vorbisfile.h 2008-04-17 18:21:55 UTC (rev 14771)
@@ -176,6 +176,9 @@
extern long ov_read_float(OggVorbis_File *vf,float ***pcm_channels,int samples,
int *bitstream);
+extern long ov_read_filter(OggVorbis_File *vf,char *buffer,int length,
+ int bigendianp,int word,int sgned,int *bitstream,
+ void (*filter)(float **pcm,long channels,long samples,void *filter_param),void *filter_param);
extern long ov_read(OggVorbis_File *vf,char *buffer,int length,
int bigendianp,int word,int sgned,int *bitstream);
extern int ov_crosslap(OggVorbis_File *vf1,OggVorbis_File *vf2);
Modified: trunk/vorbis/lib/vorbisfile.c
===================================================================
--- trunk/vorbis/lib/vorbisfile.c 2008-04-17 17:50:44 UTC (rev 14770)
+++ trunk/vorbis/lib/vorbisfile.c 2008-04-17 18:21:55 UTC (rev 14771)
@@ -1721,6 +1721,11 @@
index within the physical bitstream. Note that the accessor
functions above are aware of this dichotomy).
+ ov_read_filter is exactly the same as ov_read except that it processes
+ the decoded audio data through a filter before packing it into the
+ requested format. This gives greater accuracy than applying a filter
+ after the audio has been converted into integral PCM.
+
input values: buffer) a buffer to hold packed PCM data for return
length) the byte length requested to be placed into buffer
bigendianp) should the data be packed LSB first (0) or
@@ -1737,8 +1742,9 @@
*section) set to the logical bitstream number */
-long ov_read(OggVorbis_File *vf,char *buffer,int length,
- int bigendianp,int word,int sgned,int *bitstream){
+long ov_read_filter(OggVorbis_File *vf,char *buffer,int length,
+ int bigendianp,int word,int sgned,int *bitstream,
+ void (*filter)(float **pcm,long channels,long samples,void *filter_param),void *filter_param){
int i,j;
int host_endian = host_is_big_endian();
@@ -1776,6 +1782,10 @@
if(samples <= 0)
return OV_EINVAL;
+ /* Here. */
+ if(filter)
+ filter(pcm,channels,samples,filter_param);
+
/* a tight loop to pack each size */
{
int val;
@@ -1868,6 +1878,11 @@
}
}
+long ov_read(OggVorbis_File *vf,char *buffer,int length,
+ int bigendianp,int word,int sgned,int *bitstream){
+ return ov_read_filter(vf, buffer, length, bigendianp, word, sgned, bitstream, NULL, NULL);
+}
+
/* input values: pcm_channels) a float vector per channel of output
length) the sample length being read by the app
More information about the commits
mailing list