Mercurial > hg > sv-dependency-builds

comparison src/libvorbis-1.3.3/doc/vorbisfile/ov_read.html @ 1:05aa0afa9217

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Bring in flac, ogg, vorbis
author Chris Cannam
date Tue, 19 Mar 2013 17:37:49 +0000
parents
children
comparison
equal deleted inserted replaced
0:c7265573341e 1:05aa0afa9217
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.3.2 - 20101101</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
29 <p>The output channels are in stream order and not remapped. Vorbis I
30 defines channel order as follows:
31
32 <ul>
33 <li>one channel - the stream is monophonic
34 <li>two channels - the stream is stereo. channel order: left, right
35 <li>three channels - the stream is a 1d-surround encoding. channel order: left,
36 center, right
37 <li>four channels - the stream is quadraphonic surround. channel order: front left,
38 front right, rear left, rear right
39 <li>five channels - the stream is five-channel surround. channel order: front left,
40 center, front right, rear left, rear right
41 <li>six channels - the stream is 5.1 surround. channel order: front left, center,
42 front right, rear left, rear right, LFE
43 <li>seven channels - the stream is 6.1 surround. channel order: front left, center,
44 front right, side left, side right, rear center, LFE
45 <li>eight channels - the stream is 7.1 surround. channel order: front left, center,
46 front right, side left, side right, rear left, rear right,
47 LFE
48 <li>greater than eight channels - channel use and order is undefined
49 </ul>
50
51 <p>Note that up to this point, the Vorbisfile API could more or less hide the
52 multiple logical bitstream nature of chaining from the toplevel
53 application if the toplevel application didn't particularly care.
54 However, when reading audio back, the application must be aware
55 that multiple bitstream sections do not necessarily use the same
56 number of channels or sampling rate. <p> <tt>ov_read()</tt> passes
57 back the index of the sequential logical bitstream currently being
58 decoded (in <tt>*bitstream</tt>) along with the PCM data in order
59 that the toplevel application can handle channel and/or sample
60 rate changes. This number will be incremented at chaining
61 boundaries even for non-seekable streams. For seekable streams, it
62 represents the actual chaining index within the physical bitstream.
63 <p>
64
65 <br><br>
66 <table border=0 color=black cellspacing=0 cellpadding=7>
67 <tr bgcolor=#cccccc>
68 <td>
69 <pre><b>
70 long ov_read(<a href="OggVorbis_File.html">OggVorbis_File</a> *vf, char *buffer, int length, int bigendianp, int word, int sgned, int *bitstream);
71 </b></pre>
72 </td>
73 </tr>
74 </table>
75
76 <h3>Parameters</h3>
77 <dl>
78 <dt><i>vf</i></dt>
79 <dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile
80 functions.</dd>
81 <dt><i>buffer</i></dt>
82 <dd>A pointer to an output buffer. The decoded output is inserted into this buffer.</dd>
83 <dt><i>length</i></dt>
84 <dd>Number of bytes to be read into the buffer. Should be the same size as the buffer. A typical value is 4096.</dd>
85 <dt><i>bigendianp</i></dt>
86 <dd>Specifies big or little endian byte packing. 0 for little endian, 1 for b
87 ig endian. Typical value is 0.</dd>
88 <dt><i>word</i></dt>
89 <dd>Specifies word size. Possible arguments are 1 for 8-bit samples, or 2 or
90 16-bit samples. Typical value is 2.</dd>
91 <dt><i>sgned</i></dt>
92 <dd>Signed or unsigned data. 0 for unsigned, 1 for signed. Typically 1.</dd>
93 <dt><i>bitstream</i></dt>
94 <dd>A pointer to the number of the current logical bitstream.</dd>
95 </dl>
96
97
98 <h3>Return Values</h3>
99 <blockquote>
100 <dl>
101 <dt>OV_HOLE</dt>
102 <dd>indicates there was an interruption in the data.
103 <br>(one of: garbage between pages, loss of sync followed by
104 recapture, or a corrupt page)</dd>
105 <dt>OV_EBADLINK</dt>
106 <dd>indicates that an invalid stream section was supplied to
107 libvorbisfile, or the requested link is corrupt.</dd>
108 <dt>OV_EINVAL</dt>
109 <dd>indicates the initial file headers couldn't be read or
110 are corrupt, or that the initial open call for <i>vf</i>
111 failed.</dd>
112 <dt>0</dt>
113 <dd>indicates EOF</dd>
114 <dt><i>n</i></dt>
115 <dd>indicates actual number of bytes read. <tt>ov_read()</tt> will
116 decode at most one vorbis packet per invocation, so the value
117 returned will generally be less than <tt>length</tt>.
118 </dl>
119 </blockquote>
120
121 <h3>Notes</h3>
122 <p><b>Typical usage:</b>
123 <blockquote>
124 <tt>bytes_read = ov_read(&amp;vf,
125 buffer, 4096,0,2,1,&amp;current_section)</tt>
126 </blockquote>
127
128 This reads up to 4096 bytes into a buffer, with signed 16-bit
129 little-endian samples.
130 </p>
131
132
133
134 <br><br>
135 <hr noshade>
136 <table border=0 width=100%>
137 <tr valign=top>
138 <td><p class=tiny>copyright &copy; 2000-2010 Xiph.Org</p></td>
139 <td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
140 </tr><tr>
141 <td><p class=tiny>Vorbisfile documentation</p></td>
142 <td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td>
143 </tr>
144 </table>
145
146 </body>
147
148 </html>