Tremor/doc/ov_read.html

   1 <html>
   2
   3 <head>
   4 <title>Tremor - 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>Tremor documentation</p></td>
  12 <td align=right><p class=tiny>Tremor version 1.0 - 20020403</p></td>
  13 </tr>
  14 </table>
  15
  16 <h1>ov_read()</h1>
  17
  18 <p><i>declared in "ivorbisfile.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 audio
  23    in host-endian, signed 16 bit PCM format.  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
  30 Note that up to this point, the Tremor 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>
  49 long ov_read(<a href="OggVorbis_File.html">OggVorbis_File</a> *vf, char *buffer, int length, 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 libvorbisidec
  59 functions.</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>bitstream</i></dt>
  65 <dd>A pointer to the number of the current logical bitstream.</dd>
  66 </dl>
  67
  68
  69 <h3>Return Values</h3>
  70 <blockquote>
  71 <dl>
  72 <dt>OV_HOLE</dt>
  73   <dd>indicates there was an interruption in the data.
  74       <br>(one of: garbage between pages, loss of sync followed by
  75            recapture, or a corrupt page)</dd>
  76 <dt>OV_EBADLINK</dt>
  77   <dd>indicates that an invalid stream section was supplied to
  78       libvorbisidec, or the requested link is corrupt.</dd>
  79 <dt>0</dt>
  80   <dd>indicates EOF</dd>
  81 <dt><i>n</i></dt>
  82   <dd>indicates actual number of bytes read.  <tt>ov_read()</tt> will
  83       decode at most one vorbis packet per invocation, so the value
  84       returned will generally be less than <tt>length</tt>.
  85 </dl>
  86 </blockquote>
  87
  88 <h3>Notes</h3>
  89 <p><b>Typical usage:</b>
  90 <blockquote>
  91 <tt>bytes_read = ov_read(&amp;vf,
  92 buffer, 4096,&amp;current_section)</tt>
  93 </blockquote>
  94
  95 This reads up to 4096 bytes into a buffer, with signed 16-bit
  96 little-endian samples.
  97 </p>
  98
  99
 100
 101 <br><br>
 102 <hr noshade>
 103 <table border=0 width=100%>
 104 <tr valign=top>
 105 <td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
 106 <td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
 107 </tr><tr>
 108 <td><p class=tiny>Tremor documentation</p></td>
 109 <td align=right><p class=tiny>Tremor version 1.0 - 20020403</p></td>
 110 </tr>
 111 </table>
 112
 113 </body>
 114
 115 </html>