Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/libvorbis-1.2.0/doc/vorbisfile/ov_read.html @ 16

Last change on this file since 16 was 16, checked in by landauf, 16 years ago

added libvorbis

File size: 4.1 KB
Line 
1<html>
2
3<head>
4<title>Vorbisfile - function - ov_read</title>
5<link rel=stylesheet href="style.css" type="text/css">
6</head>
7
8<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
9<table border=0 width=100%>
10<tr>
11<td><p class=tiny>Vorbisfile documentation</p></td>
12<td align=right><p class=tiny>vorbisfile version 1.2.0 - 20070723</p></td>
13</tr>
14</table>
15
16<h1>ov_read()</h1>
17
18<p><i>declared in "vorbis/vorbisfile.h";</i></p>
19
20<p>
21   This is the main function used to decode a Vorbis file within a
22   loop.  It returns up to the specified number of bytes of decoded PCM audio
23   in the requested endianness, signedness, and word size.  If the audio is
24   multichannel, the channels are interleaved in the output buffer.
25   If the passed in buffer is large, <tt>ov_read()</tt> will not fill
26   it; the passed in buffer size is treated as a <em>limit</em> and
27   not a request.
28<p>
29   
30Note that up to this point, the Vorbisfile API could more or less hide the
31   multiple logical bitstream nature of chaining from the toplevel
32   application if the toplevel application didn't particularly care.
33   However, when reading audio back, the application must be aware
34   that multiple bitstream sections do not necessarily use the same
35   number of channels or sampling rate. <p> <tt>ov_read()</tt> passes
36   back the index of the sequential logical bitstream currently being
37   decoded (in <tt>*bitstream</tt>) along with the PCM data in order
38   that the toplevel application can handle channel and/or sample
39   rate changes. This number will be incremented at chaining
40   boundaries even for non-seekable streams. For seekable streams, it
41   represents the actual chaining index within the physical bitstream.
42<p>
43
44<br><br>
45<table border=0 color=black cellspacing=0 cellpadding=7>
46<tr bgcolor=#cccccc>
47        <td>
48<pre><b>
49long ov_read(<a href="OggVorbis_File.html">OggVorbis_File</a> *vf, char *buffer, int length, int bigendianp, int word, int sgned, int *bitstream);
50</b></pre>
51        </td>
52</tr>
53</table>
54
55<h3>Parameters</h3>
56<dl>
57<dt><i>vf</i></dt>
58<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile
59functions.</dd>
60<dt><i>buffer</i></dt>
61<dd>A pointer to an output buffer.  The decoded output is inserted into this buffer.</dd>
62<dt><i>length</i></dt>
63<dd>Number of bytes to be read into the buffer. Should be the same size as the buffer.  A typical value is 4096.</dd>
64<dt><i>bigendianp</i></dt>
65<dd>Specifies big or little endian byte packing.  0 for little endian, 1 for b
66ig endian.  Typical value is 0.</dd>
67<dt><i>word</i></dt>
68<dd>Specifies word size.  Possible arguments are 1 for 8-bit samples, or 2 or
6916-bit samples.  Typical value is 2.</dd>
70<dt><i>sgned</i></dt>
71<dd>Signed or unsigned data.  0 for unsigned, 1 for signed.  Typically 1.</dd>
72<dt><i>bitstream</i></dt>
73<dd>A pointer to the number of the current logical bitstream.</dd>
74</dl>
75
76
77<h3>Return Values</h3>
78<blockquote>
79<dl>
80<dt>OV_HOLE</dt>
81  <dd>indicates there was an interruption in the data.
82      <br>(one of: garbage between pages, loss of sync followed by
83           recapture, or a corrupt page)</dd>
84<dt>OV_EBADLINK</dt>
85  <dd>indicates that an invalid stream section was supplied to
86      libvorbisfile, or the requested link is corrupt.</dd>
87<dt>0</dt>
88  <dd>indicates EOF</dd>
89<dt><i>n</i></dt>
90  <dd>indicates actual number of bytes read.  <tt>ov_read()</tt> will
91      decode at most one vorbis packet per invocation, so the value
92      returned will generally be less than <tt>length</tt>.
93</dl>
94</blockquote>
95
96<h3>Notes</h3>
97<p><b>Typical usage:</b>
98<blockquote>
99<tt>bytes_read = ov_read(&amp;vf,
100buffer, 4096,0,2,1,&amp;current_section)</tt>
101</blockquote>
102
103This reads up to 4096 bytes into a buffer, with signed 16-bit
104little-endian samples.
105</p>
106
107
108
109<br><br>
110<hr noshade>
111<table border=0 width=100%>
112<tr valign=top>
113<td><p class=tiny>copyright &copy; 2007 Xiph.org</p></td>
114<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
115</tr><tr>
116<td><p class=tiny>Vorbisfile documentation</p></td>
117<td align=right><p class=tiny>vorbisfile version 1.2.0 - 20070723</p></td>
118</tr>
119</table>
120
121</body>
122
123</html>
Note: See TracBrowser for help on using the repository browser.