Tremor/doc/OggVorbis_File.html

   1 <html>
   2
   3 <head>
   4 <title>Tremor - datatype - OggVorbis_File</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>OggVorbis_File</h1>
  17
  18 <p><i>declared in "ivorbisfile.h"</i></p>
  19
  20 <p>
  21 The OggVorbis_File structure defines an Ogg Vorbis file.
  22 <p>
  23
  24 This structure is used in all libvorbisidec routines.  Before it can be used,
  25 it must be initialized by <a href="ov_open.html">ov_open()</a> or <a
  26 href="ov_open_callbacks.html">ov_open_callbacks()</a>.
  27
  28 <p>
  29 After use, the OggVorbis_File structure must be deallocated with a
  30 call to <a href="ov_clear.html">ov_clear()</a>.
  31
  32 <p>
  33 Once a file or data source is opened successfully by libvorbisidec
  34 (using <a href="ov_open.html">ov_open()</a> or <a
  35 href="ov_open_callbacks.html">ov_open_callbacks()</a>), it is owned by
  36 libvorbisidec.  The file should not be used by any other applications or
  37 functions outside of the libvorbisidec API.  The file must not be closed
  38 directly by the application at any time after a successful open;
  39 libvorbisidec expects to close the file within <a
  40 href="ov_clear.html">ov_clear()</a>.
  41 <p>
  42 If the call to <a href="ov_open.html">ov_open()</a> or <a
  43 href="ov_open_callbacks.html">ov_open_callbacks()</a> <b>fails</b>,
  44 libvorbisidec does <b>not</b> assume ownership of the file and the
  45 application is expected to close it if necessary.
  46
  47 <br><br>
  48 <table border=0 width=100% color=black cellspacing=0 cellpadding=7>
  49 <tr bgcolor=#cccccc>
  50         <td>
  51 <pre><b>typedef struct {
  52   void             *datasource; /* Pointer to a FILE *, etc. */
  53   int              seekable;
  54   ogg_int64_t      offset;
  55   ogg_int64_t      end;
  56   ogg_sync_state   oy;
  57
  58   /* If the FILE handle isn't seekable (eg, a pipe), only the current
  59      stream appears */
  60   int              links;
  61   ogg_int64_t      *offsets;
  62   ogg_int64_t      *dataoffsets;
  63   long             *serialnos;
  64   ogg_int64_t      *pcmlengths;
  65   vorbis_info      *vi;
  66   vorbis_comment   *vc;
  67
  68   /* Decoding working state local storage */
  69   ogg_int64_t      pcm_offset;
  70   int              ready_state;
  71   long             current_serialno;
  72   int              current_link;
  73
  74   ogg_int64_t      bittrack;
  75   ogg_int64_t      samptrack;
  76
  77   ogg_stream_state os; /* take physical pages, weld into a logical
  78                           stream of packets */
  79   vorbis_dsp_state vd; /* central working state for the packet->PCM decoder */
  80   vorbis_block     vb; /* local working space for packet->PCM decode */
  81
  82   <a href="ov_callbacks.html">ov_callbacks</a> callbacks;
  83
  84 } OggVorbis_File;</b></pre>
  85         </td>
  86 </tr>
  87 </table>
  88
  89 <h3>Relevant Struct Members</h3>
  90 <dl>
  91 <dt><i>datasource</i></dt>
  92
  93 <dd>Pointer to file or other ogg source.  When using stdio based
  94 file/stream access, this field contains a <tt>FILE</tt> pointer. When using
  95 custom IO via callbacks, libvorbisidec treats this void pointer as a
  96 black box only to be passed to the callback routines provided by the
  97 application.</dd>
  98
  99 <dt><i>seekable</i></dt>
 100 <dd>Read-only int indicating whether file is seekable. E.g., a physical file is seekable, a pipe isn't.</dd>
 101 <dt><i>links</i></dt>
 102 <dd>Read-only int indicating the number of logical bitstreams within the physical bitstream.</dd>
 103 <dt><i>ov_callbacks</i></dt>
 104 <dd>Collection of file manipulation routines to be used on this data source.  When using stdio/FILE access via <a href="ov_open.html">ov_open()</a>, the callbacks will be filled in with stdio calls or wrappers to stdio calls.</dd>
 105 </dl>
 106
 107 <h3>Notes</h3>
 108
 109 <p>Tremor requires a native 64 bit integer type to compile and
 110 function; The GNU build system will locate and typedef
 111 <tt>ogg_int64_t</tt> to the appropriate native type.  If not using the
 112 GNU build tools, you will need to define <tt>ogg_int64_t</tt> as a
 113 64-bit type inside your system's project file/Makefile, etc. On win32,
 114 for example, this should be defined as <tt>__int64</tt>.
 115 <p>
 116
 117
 118 <br><br>
 119 <hr noshade>
 120 <table border=0 width=100%>
 121 <tr valign=top>
 122 <td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
 123 <td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
 124 </tr><tr>
 125 <td><p class=tiny>Tremor documentation</p></td>
 126 <td align=right><p class=tiny>Tremor version 1.0 - 20020403</p></td>
 127 </tr>
 128 </table>
 129
 130 </body>
 131
 132 </html>