00001 <html>
00002
00003 <head>
00004 <title>Vorbisfile - function - ov_read</title>
00005 <link rel=stylesheet href="style.css" type="text/css">
00006 </head>
00007
00008 <body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
00009 <table border=0 width=100%>
00010 <tr>
00011 <td><p class=tiny>Vorbisfile documentation</p></td>
00012 <td align=right><p class=tiny>vorbisfile version 1.68 - 20030307</p></td>
00013 </tr>
00014 </table>
00015
00016 <h1>ov_read()</h1>
00017
00018 <p><i>declared in "vorbis/vorbisfile.h";</i></p>
00019
00020 <p>
00021 This is the main function used to decode a Vorbis file within a
00022 loop. It returns up to the specified number of bytes of decoded PCM audio
00023 in the requested endianness, signedness, and word size. If the audio is
00024 multichannel, the channels are interleaved in the output buffer.
00025 If the passed in buffer is large, <tt>ov_read()</tt> will not fill
00026 it; the passed in buffer size is treated as a <em>limit</em> and
00027 not a request.
00028 <p>
00029
00030 Note that up to this point, the Vorbisfile API could more or less hide the
00031 multiple logical bitstream nature of chaining from the toplevel
00032 application if the toplevel application didn't particularly care.
00033 However, when reading audio back, the application must be aware
00034 that multiple bitstream sections do not necessarily use the same
00035 number of channels or sampling rate. <p> <tt>ov_read()</tt> passes
00036 back the index of the sequential logical bitstream currently being
00037 decoded (in <tt>*bitstream</tt>) along with the PCM data in order
00038 that the toplevel application can handle channel and/or sample
00039 rate changes. This number will be incremented at chaining
00040 boundaries even for non-seekable streams. For seekable streams, it
00041 represents the actual chaining index within the physical bitstream.
00042 <p>
00043
00044 <br><br>
00045 <table border=0 color=black cellspacing=0 cellpadding=7>
00046 <tr bgcolor=#cccccc>
00047 <td>
00048 <pre><b>
00049 long ov_read(<a href="OggVorbis_File.html">OggVorbis_File</a> *vf, char *buffer, int length, int bigendianp, int word, int sgned, int *bitstream);
00050 </b></pre>
00051 </td>
00052 </tr>
00053 </table>
00054
00055 <h3>Parameters</h3>
00056 <dl>
00057 <dt><i>vf</i></dt>
00058 <dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile
00059 functions.</dd>
00060 <dt><i>buffer</i></dt>
00061 <dd>A pointer to an output buffer. The decoded output is inserted into this buffer.</dd>
00062 <dt><i>length</i></dt>
00063 <dd>Number of bytes to be read into the buffer. Should be the same size as the buffer. A typical value is 4096.</dd>
00064 <dt><i>bigendianp</i></dt>
00065 <dd>Specifies big or little endian byte packing. 0 for little endian, 1 for b
00066 ig endian. Typical value is 0.</dd>
00067 <dt><i>word</i></dt>
00068 <dd>Specifies word size. Possible arguments are 1 for 8-bit samples, or 2 or
00069 16-bit samples. Typical value is 2.</dd>
00070 <dt><i>sgned</i></dt>
00071 <dd>Signed or unsigned data. 0 for unsigned, 1 for signed. Typically 1.</dd>
00072 <dt><i>bitstream</i></dt>
00073 <dd>A pointer to the number of the current logical bitstream.</dd>
00074 </dl>
00075
00076
00077 <h3>Return Values</h3>
00078 <blockquote>
00079 <dl>
00080 <dt>OV_HOLE</dt>
00081 <dd>indicates there was an interruption in the data.
00082 <br>(one of: garbage between pages, loss of sync followed by
00083 recapture, or a corrupt page)</dd>
00084 <dt>OV_EBADLINK</dt>
00085 <dd>indicates that an invalid stream section was supplied to
00086 libvorbisfile, or the requested link is corrupt.</dd>
00087 <dt>0</dt>
00088 <dd>indicates EOF</dd>
00089 <dt><i>n</i></dt>
00090 <dd>indicates actual number of bytes read. <tt>ov_read()</tt> will
00091 decode at most one vorbis packet per invocation, so the value
00092 returned will generally be less than <tt>length</tt>.
00093 </dl>
00094 </blockquote>
00095
00096 <h3>Notes</h3>
00097 <p><b>Typical usage:</b>
00098 <blockquote>
00099 <tt>bytes_read = ov_read(&vf,
00100 buffer, 4096,0,2,1,&current_section)</tt>
00101 </blockquote>
00102
00103 This reads up to 4096 bytes into a buffer, with signed 16-bit
00104 little-endian samples.
00105 </p>
00106
00107
00108
00109 <br><br>
00110 <hr noshade>
00111 <table border=0 width=100%>
00112 <tr valign=top>
00113 <td><p class=tiny>copyright © 2003 Xiph.org</p></td>
00114 <td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
00115 </tr><tr>
00116 <td><p class=tiny>Vorbisfile documentation</p></td>
00117 <td align=right><p class=tiny>vorbisfile version 1.68 - 20030307</p></td>
00118 </tr>
00119 </table>
00120
00121 </body>
00122
00123 </html>
