doc/vorbisfile/ov_read.html

   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.25 - 20000615</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 loop.
  22 </p><p>
  23    This function deals with more complicated bitstream chaining issues.
  24    Up to this point, everything could more or less hide the multiple
  25    logical bitstream nature of chaining from the toplevel application
  26    if the toplevel application didn't particularly care.  However, when we actually read audio back, we must be aware that multiple bitstream sections do not necessarily
  27    have to have the same number of channels or sampling rate.
  28 </p><p>
  29    <tt>ov_read()</tt> passes back the logical bitstream number currently
  30    being decoded along with the PCM data in order that the toplevel
  31    application can take action on channel/sample rate changes.
  32 </p>
  33
  34 <br><br>
  35 <table border=0 color=black cellspacing=0 cellpadding=7>
  36 <tr bgcolor=#cccccc>
  37         <td>
  38 <pre><b>
  39 long ov_read(<a href="OggVorbis_File.html">OggVorbis_File</a> *vf, char *buffer, int length, int bigendianp, int word, int sgned, int *bitstream);
  40 </b></pre>
  41         </td>
  42 </tr>
  43 </table>
  44
  45 <h3>Parameters</h3>
  46 <dl>
  47 <dt><i>vf</i></dt>
  48 <dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible vorbisfile
  49 functions.</dd>
  50 <dt><i>buffer</i></dt>
  51 <dd>A pointer to an output buffer.  The decoded output is inserted into this buffer.</dd>
  52 <dt><i>length</i></dt>
  53 <dd>Number of bytes to be read into the buffer. Should be the same size as the buffer.  A typical value is 4096.</dd>
  54 <dt><i>bigendianp</i></dt>
  55 <dd>Specifies big or little endian byte packing.  0 for little endian, 1 for big endian.  Typical value is 0.</dd>
  56 <dt><i>word</i></dt>
  57 <dd>Specifies word size.  Possible arguments are 1 for 8-bit samples, or 2 or 16-bit samples.  Typical value is 2.</dd>
  58 <dt><i>sgned</i></dt>
  59 <dd>Signed or unsigned data.  0 for unsigned, 1 for signed.  Typically 1.</dd>
  60 <dt><i>bitstream</i></dt>
  61 <dd>A pointer to the number of the current logical bitstream.</dd>
  62 </dl>
  63
  64
  65 <h3>Return Values</h3>
  66 <blockquote>
  67 <dl>
  68 <dt>OV_HOLE</dt>
  69   <dd>indicates there was an interruption in the data.
  70       <br>(one of: garbage between pages, loss of sync followed by
  71            recapture, or a corrupt page)</dd>
  72 <dt>OV_EBADLINK</dt>
  73   <dd>indicates that an invalid stream section was supplied to
  74       libvorbisfile, or the requested link is corrupt.</dd>
  75 <dt>0</dt>
  76   <dd>indicates EOF</dd>
  77 <dt><i>n</i></dt>
  78   <dd>indicates actual number of bytes read.  <tt>ov_read()</tt> will
  79       decode at most one vorbis packet per invocation, so the value
  80       returned will generally be less than <tt>length</tt>.
  81 </dl>
  82 </blockquote>
  83
  84 <h3>Notes</h3>
  85 <p><b>Typical usage:</b>
  86 <blockquote>
  87 <tt>bytes_read = ov_read(&amp;vf,
  88 buffer, 4096,0,2,1,&amp;current_section)</tt>
  89 </blockquote>
  90
  91 This reads up to 4096 bytes into a buffer, with signed 16-bit
  92 little-endian samples.
  93 </p>
  94
  95 <br>
  96 <br><br>
  97 <hr noshade>
  98 <table border=0 width=100%>
  99 <tr valign=top>
 100 <td><p class=tiny>copyright &copy; 2000 vorbis team</p></td>
 101 <td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/index.html">Ogg Vorbis</a><br><a href="mailto:team@vorbis.org">team@vorbis.org</a></p></td>
 102 </tr><tr>
 103 <td><p class=tiny>vorbisfile documentation</p></td>
 104 <td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
 105 </tr>
 106 </table>
 107
 108
 109 </body>
 110
 111 </html>