Commit 866ed6ea authored by Monty's avatar Monty
Browse files

Commit 01-ov_read_filter patch from #381; closes feature request #1352. Also...

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.


svn path=/trunk/vorbis/; revision=14771
parent 529b45ab
......@@ -20,9 +20,10 @@ All libvorbisfile decoding routines are declared in "vorbis/vorbisfile.h".
<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 @@ or <a href="ov_open_callbacks.html"><tt>ov_open_callbacks()</tt></a>.</td>
<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>
......
<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(&amp;vf,
buffer, 4096,0,2,1,&amp;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 &copy; 2007 Xiph.org</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
</tr><tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>vorbisfile version 1.2.0 - 20070723</p></td>
</tr>
</table>
</body>
</html>
......@@ -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>
......
......@@ -176,6 +176,9 @@ extern vorbis_comment *ov_comment(OggVorbis_File *vf,int link);
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);
......
......@@ -1721,6 +1721,11 @@ static int host_is_big_endian() {
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 @@ static int host_is_big_endian() {
*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 @@ long ov_read(OggVorbis_File *vf,char *buffer,int length,
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,
}
}
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
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment