Commit 280386f2 authored by Jack Moffitt's avatar Jack Moffitt
Browse files

Added Kim's libogg docs

svn path=/trunk/ogg/; revision=1335
parent 67034762
<html>
<head>
<title>libogg - Bitpacking Functions</title>
<link rel=stylesheet href="style.css" type="text/css">
</head>
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
<table border=0 width=100%>
<tr>
<td><p class=tiny>libogg documentation</p></td>
<td align=right><p class=tiny>libogg version 1.25 - 20000615</p></td>
</tr>
</table>
<h1>Bitpacking Functions</h1>
<p>Libogg contains a basic bitpacking library that is useful for manipulating data within a buffer.
<p>
All the <b>libogg</b> specific functions are declared in "ogg/ogg.h".
<p>
<table border=1 color=black width=50% cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td><b>function</b></td>
<td><b>purpose</b></td>
</tr>
<tr valign=top>
<td><a href="oggpack_writeinit.html">oggpack_writeinit</a></td>
<td>Initializes a buffer for writing using this bitpacking library.</td>
</tr>
<tr valign=top>
<td><a href="oggpack_reset.html">oggpack_reset</a></td>
<td>Clears and resets the buffer to the initial position.</td>
</tr>
<tr valign=top>
<td><a href="oggpack_writeclear.html">oggpack_writeclear</a></td>
<td>Frees the memory used by the buffer.</td>
</tr>
<tr valign=top>
<td><a href="oggpack_readinit.html">oggpack_readinit</a></td>
<td>Initializes a buffer for reading using this bitpacking library.</td>
</tr>
<tr valign=top>
<td><a href="oggpack_write.html">oggpack_write</a></td>
<td>Writes bytes to the specified location within the buffer.</td>
</tr>
<tr valign=top>
<td><a href="oggpack_look.html">oggpack_look</a></td>
<td>Look at a specified number of bits, <=32, without advancing the location pointer.</td>
</tr>
<tr valign=top>
<td><a href="oggpack_look_huff.html">oggpack_look_huff</a></td>
<td>Look at a specified number of bits, <=8, without advancing the location pointer.</td>
</tr>
<tr valign=top>
<td><a href="oggpack_look1.html">oggpack_look1</a></td>
<td>Looks at one bit without advancing the location pointer.</td>
</tr>
<tr valign=top>
<td><a href="oggpack_adv.html">oggpack_adv</a></td>
<td>Advances the location pointer by a specified number of bits.</td>
</tr>
<tr valign=top>
<td><a href="oggpack_adv_huff.html">oggpack_adv_huff</a></td>
<td>Advances the location pointer by a specified number of bits, and checks for buffer overflow.</td>
</tr>
<tr valign=top>
<td><a href="oggpack_adv1.html">oggpack_adv1</a></td>
<td>Advances the location pointer by one bit.</td>
</tr>
<tr valign=top>
<td><a href="oggpack_read.html">oggpack_read</a></td>
<td>Reads a specified number of bits from the buffer.</td>
</tr>
<tr valign=top>
<td><a href="oggpack_read1.html">oggpack_read1</a></td>
<td>Reads one bit from the buffer.</td>
</tr>
<tr valign=top>
<td><a href="oggpack_bytes.html">oggpack_bytes</a></td>
<td>Returns the total number of bytes contained within the buffer.</td>
</tr>
<tr valign=top>
<td><a href="oggpack_bits.html">oggpack_bits</a></td>
<td>Returns the total number of bits contained within the buffer.</td>
</tr>
<tr valign=top>
<td><a href="oggpack_get_buffer.html">oggpack_get_buffer</a></td>
<td>Returns a pointer to the buffer encapsulated within the <a href="oggpack_buffer.html">oggpack_buffer</a> struct.</td>
</tr>
</table>
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2000 xiph.org</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a><br><a href="mailto:team@xiph.org">team@xiph.org</a></p></td>
</tr><tr>
<td><p class=tiny>libogg documentation</p></td>
<td align=right><p class=tiny>libogg version 1.25 - 20000615</p></td>
</tr>
</table>
</body>
</html>
<html>
<head>
<title>libogg - Base Data Structures</title>
<link rel=stylesheet href="style.css" type="text/css">
</head>
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
<table border=0 width=100%>
<tr>
<td><p class=tiny>libogg documentation</p></td>
<td align=right><p class=tiny>libogg version 1.25 - 20000615</p></td>
</tr>
</table>
<h1>Base Data Structures</h1>
<p>Libogg uses several data structures to hold data and state information.
<p>
All the <b>libogg</b> specific data structures are declared in "ogg/ogg.h".
<p>
<table border=1 color=black width=50% cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td><b>datatype</b></td>
<td><b>purpose</b></td>
</tr>
<tr valign=top>
<td><a href="ogg_page.html">ogg_page</a></td>
<td>This structure encapsulates data into one ogg bitstream page.</td>
</tr>
<tr valign=top>
<td><a href="ogg_stream_state.html">ogg_stream_state</a></td>
<td>This structure contains current encode/decode data for a logical bitstream.</td>
</tr>
<tr valign=top>
<td><a href="ogg_packet.html">ogg_packet</a></td>
<td>This structure encapsulates the data and metadata for a single raw Ogg Vorbis packet.</td>
</tr>
<tr valign=top>
<td><a href="ogg_sync_state.html">ogg_sync_state</a></td>
<td>Contains bitstream synchronization information.</td>
</tr>
</table>
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2000 xiph.org</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a><br><a href="mailto:team@xiph.org">team@xiph.org</a></p></td>
</tr><tr>
<td><p class=tiny>libogg documentation</p></td>
<td align=right><p class=tiny>libogg version 1.25 - 20000615</p></td>
</tr>
</table>
</body>
</html>
<html>
<head>
<title>libogg - Decoding</title>
<link rel=stylesheet href="style.css" type="text/css">
</head>
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
<table border=0 width=100%>
<tr>
<td><p class=tiny>libogg documentation</p></td>
<td align=right><p class=tiny>libogg version 1.25 - 20000615</p></td>
</tr>
</table>
<h1>Decoding</h1>
<p>Libogg contains a set of functions used in the decoding process.
<p>
All the <b>libogg</b> specific functions are declared in "ogg/ogg.h".
<p>
<p>Decoding is based around the ogg synchronization layer. The <a href="ogg_sync_state.html">ogg_sync_state</a> struct coordinates between incoming data and the decoder. We read data into the synchronization layer, submit the data to the stream, and output raw packets to the decoder.
<p>Decoding through the Ogg layer follows a specific logical sequence. A read loop follows these logical steps:
<ul>
<li>Expose a buffer using <a href="ogg_sync_buffer.html">ogg_sync_buffer()</a>.
<li>Read data into the buffer, using fread() or a similar function.
<li>Call <a href="ogg_sync_wrote.html">ogg_sync_wrote()</a> to tell the synchronization layer how many bytes you wrote into the buffer.
<li>Write out the data using <a href="ogg_sync_pageout.html">ogg_sync_pageout</a>.
<li>Submit the completed page to the streaming layer with <a href="ogg_stream_pagein.html">ogg_stream_pagein</a>.
<li>Output a packet of data to the codec-specific decoding layer using <a href="ogg_stream_packetout.html">ogg_stream_packetout</a>.
</ul>
<p>In practice, streams are more complex, and Ogg also must handle headers, incomplete or dropped pages, and other errors in input.
<br><br>
<table border=1 color=black width=50% cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td><b>function</b></td>
<td><b>purpose</b></td>
</tr>
<tr valign=top>
<td><a href="ogg_sync_init.html">ogg_sync_init</a></td>
<td>Initializes an Ogg bitstream.</td>
</tr>
<tr valign=top>
<td><a href="ogg_sync_clear.html">ogg_sync_clear</a></td>
<td>Clears the status information from the synchronization struct.<td>
</tr>
<tr valign=top>
<td><a href="ogg_sync_reset.html">ogg_sync_reset</a></td>
<td>Resets the synchronization status to initial values.</td>
</tr>
<tr valign=top>
<td><a href="ogg_sync_destroy.html">ogg_sync_destroy</a></td>
<td>Frees the synchronization struct.</td>
</tr>
<tr valign=top>
<td><a href="ogg_sync_buffer.html">ogg_sync_buffer</a></td>
<td>Exposes a buffer from the synchronization layer in order to read data.</td>
</tr>
<tr valign=top>
<td><a href="ogg_sync_wrote.html">ogg_sync_wrote</a></td>
<td>Tells the synchronization layer how many bytes were written into the buffer.</td>
</tr>
<tr valign=top>
<td><a href="ogg_sync_pageseek.html">ogg_sync_pageseek</a></td>
<td>Finds the borders of pages and resynchronizes the stream.</td>
</tr>
<tr valign=top>
<td><a href="ogg_sync_pageout.html">ogg_sync_pageout</a></td>
<td>Outputs a page from the synchronization layer.</td>
</tr>
<tr valign=top>
<td><a href="ogg_stream_pagein.html">ogg_stream_pagein</a></td>
<td>Submits a complete page to the stream layer.</td>
</tr>
<tr valign=top>
<td><a href="ogg_stream_packetout.html">ogg_stream_packetout</a></td>
<td>Outputs a packet to the codec-specific decoding engine.</td>
</tr>
</table>
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2000 xiph.org</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a><br><a href="mailto:team@xiph.org">team@xiph.org</a></p></td>
</tr><tr>
<td><p class=tiny>libogg documentation</p></td>
<td align=right><p class=tiny>libogg version 1.25 - 20000615</p></td>
</tr>
</table>
</body>
</html>
<html>
<head>
<title>libogg - Encoding</title>
<link rel=stylesheet href="style.css" type="text/css">
</head>
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
<table border=0 width=100%>
<tr>
<td><p class=tiny>libogg documentation</p></td>
<td align=right><p class=tiny>libogg version 1.25 - 20000615</p></td>
</tr>
</table>
<h1>Encoding</h1>
<p>Libogg contains a set of functions used in the encoding process.
<p>
All the <b>libogg</b> specific functions are declared in "ogg/ogg.h".
<p>
<p>When encoding, the encoding engine will output raw packets which must be placed into an Ogg bitstream.
<p>Raw packets are inserted into the stream, and an <a href="ogg_page.html">ogg_page</a> is output when enough packets have been written to create a full page. The pages output are pointers to buffered packet segments, and can then be written out and saved as an ogg stream.
<p>There are a couple of basic steps:
<ul>
<li>Use the encoding engine to produce a raw packet of data.
<li>Call <a href="ogg_stream_packetin.html">ogg_stream_packetin</a> to submit a raw packet to the stream.
<li>Use <a href="ogg_stream_pageout.html">ogg_stream_pageout</a> to output a page, if enough data has been submitted. Otherwise, continue submitting data.
</ul>
<br><br>
<table border=1 color=black width=50% cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td><b>function</b></td>
<td><b>purpose</b></td>
</tr>
<tr valign=top>
<td><a href="ogg_stream_packetin.html">ogg_stream_packetin</a></td>
<td>Submits a raw packet to the streaming layer, so that it can be formed into a page.</td>
</tr>
<tr valign=top>
<td><a href="ogg_stream_pageout.html">ogg_stream_pageout</a></td>
<td>Outputs a completed page if the stream contains enough packets to form a full page.<td>
</tr>
<tr valign=top>
<td><a href="ogg_stream_flush.html">ogg_stream_flush</a></td>
<td>Forces any remaining packets in the stream to be returned as a page of any size.<td>
</tr>
</table>
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2000 xiph.org</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a><br><a href="mailto:team@xiph.org">team@xiph.org</a></p></td>
</tr><tr>
<td><p class=tiny>libogg documentation</p></td>
<td align=right><p class=tiny>libogg version 1.25 - 20000615</p></td>
</tr>
</table>
</body>
</html>
<html>
<head>
<title>libogg - General Functions</title>
<link rel=stylesheet href="style.css" type="text/css">
</head>
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
<table border=0 width=100%>
<tr>
<td><p class=tiny>libogg documentation</p></td>
<td align=right><p class=tiny>libogg version 1.25 - 20000615</p></td>
</tr>
</table>
<h1>General Functions</h1>
<p>Libogg contains several functions which are generally useful when using Ogg streaming, whether encoding or decoding.
<p>
All the <b>libogg</b> specific functions are declared in "ogg/ogg.h".
<p>
<p>These functions can be used to manipulate some of the basic elements of Ogg - streams and pages. Streams and pages are important during both the encode and decode process.
<br>
<table border=1 color=black width=50% cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td><b>function</b></td>
<td><b>purpose</b></td>
</tr>
<tr valign=top>
<td><a href="ogg_stream_init.html">ogg_stream_init</a></td>
<td>Initializes an Ogg bitstream.</td>
</tr>
<tr valign=top>
<td><a href="ogg_stream_clear.html">ogg_stream_clear</a></td>
<td>Clears the storage within the Ogg stream, but does not free the stream itself.<td>
</tr>
<tr valign=top>
<td><a href="ogg_stream_reset.html">ogg_stream_reset</a></td>
<td>Resets the stream status to its initial position.</td>
</tr>
<tr valign=top>
<td><a href="ogg_stream_destroy.html">ogg_stream_destroy</a></td>
<td>Frees the entire Ogg stream.</td>
</tr>
<tr valign=top>
<td><a href="ogg_stream_eos.html">ogg_stream_eos</a></td>
<td>Indicates whether we are at the end of the stream.</td>
</tr>
<tr valign=top>
<td><a href="ogg_page_version.html">ogg_page_version</a></td>
<td>Returns the version of ogg_page that this stream/page uses</td>
</tr>
<tr valign=top>
<td><a href="ogg_page_continued.html">ogg_page_continued</a></td>
<td>Indicates if the current page contains a continued packet from the last page.</td>
</tr>
<tr valign=top>
<td><a href="ogg_page_bos.html">ogg_page_bos</a></td>
<td>Indicates if the current page is the beginning of the stream.</td>
</tr>
<tr valign=top>
<td><a href="ogg_page_eos.html">ogg_page_eos</a></td>
<td>Indicates if the current page is the end of the stream.</td>
</tr>
<tr valign=top>
<td><a href="ogg_page_granulepos.html">ogg_page_granulepos</a></td>
<td>Returns the precise playback location of this page.</td>
</tr>
<tr valign=top>
<td><a href="ogg_page_serialno.html">ogg_page_serialno</a></td>
<td>Returns the unique serial number of the logical bitstream associated with this page.</td>
</tr>
<tr valign=top>
<td><a href="ogg_page_pageno.html">ogg_page_pageno</a></td>
<td>Returns the sequential page number for this page.</td>
</tr>
</table>
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2000 xiph.org</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a><br><a href="mailto:team@xiph.org">team@xiph.org</a></p></td>
</tr><tr>
<td><p class=tiny>libogg documentation</p></td>
<td align=right><p class=tiny>libogg version 1.25 - 20000615</p></td>
</tr>
</table>
</body>
</html>
<html>
<head>
<title>libogg - Documentation</title>
<link rel=stylesheet href="style.css" type="text/css">
</head>
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
<table border=0 width=100%>
<tr>
<td><p class=tiny>libogg documentation</p></td>
<td align=right><p class=tiny>libogg version 1.25 - 20000615</p></td>
</tr>
</table>
<h1>Libogg Documentation</h1>
<p>
Libogg contains necessary functionality to create, decode, and work with Ogg bitstreams.
<p>This document explains how to use the libogg API in detail.
<p>
<a href="overview.html">libogg api overview</a><br>
<a href="reference.html">libogg api reference</a><br>
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2000 xiph.org</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a><br><a href="mailto:team@vorbis.org">team@vorbis.org</a></p></td>
</tr><tr>
<td><p class=tiny>libogg documentation</p></td>
<td align=right><p class=tiny>libogg version 1.25 - 20000615</p></td>
</tr>
</table>
</body>
</html>
<html>
<head>
<title>libogg - datatype - ogg_packet</title>
<link rel=stylesheet href="style.css" type="text/css">
</head>
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
<table border=0 width=100%>
<tr>
<td><p class=tiny>libogg documentation</p></td>
<td align=right><p class=tiny>libogg version 1.25 - 20000615</p></td>
</tr>
</table>
<h1>ogg_packet</h1>
<p><i>declared in "ogg/ogg.h"</i></p>
<p>
The ogg_packet struct encapsulates the data for a single raw packet of data.
<p>
<table border=0 width=100% color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
typedef struct {
unsigned char *packet;
long bytes;
long b_o_s;
long e_o_s;
ogg_int64_t frameno;
ogg_int64_t packetno; /* sequence number for decode; the framing
knows where there's a hole in the data,
but we need coupling so that the codec
(which is in a seperate abstraction
layer) also knows about the gap */
} ogg_packet;
</b></pre>
</td>
</tr>
</table>
<h3>Relevant Struct Members</h3>
<dl>
<dt><i>packet</i></dt>
<dd>Pointer to data in form of a packet.</dd>
<dt><i>bytes</i></dt>
<dd>Indicates size in bytes of the data within this page. Pages can be of arbitrary size.</dd>
<dt><i>b_o_s</i></dt>
<dd>Flag indicating whether this page is at the beginning of a bitstream. <tt>1</tt> indicates beginning page, <tt>0</tt> indicates any other position in the stream.</dd>
<dt><i>e_o_s</i></dt>
<dd>Flag indicating whether this page is at the end of a bitstream. <tt>1</tt> indicates ending page, <tt>0</tt> indicates any other position in the stream.</dd>
<dt><i>frameno</i></dt>
<dd>Sequential number indicating precise position within stream.</dd>
<dt><i>packetno</i></dt>
<dd>Sequential number of this packet. Used within the decoder for internal ordering.<dd>
</dl>
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2000 xiph.org</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/index.html">Ogg Vorbis</a><br><a href="mailto:team@xiph.org">team@xiph.org</a></p></td>
</tr><tr>
<td><p class=tiny>libogg documentation</p></td>
<td align=right><p class=tiny>libogg version 1.25 - 20000615</p></td>
</tr>
</table>
</body>
</html>
<html>
<head>
<title>libogg - datatype - ogg_page</title>
<link rel=stylesheet href="style.css" type="text/css">
</head>
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
<table border=0 width=100%>
<tr>
<td><p class=tiny>libogg documentation</p></td>
<td align=right><p class=tiny>libogg version 1.25 - 20000615</p></td>
</tr>
</table>
<h1>ogg_page</h1>
<p><i>declared in "ogg/ogg.h"</i></p>
<p>
The ogg_page struct encapsulates the data for an Ogg page.
<p>
Ogg pages are of arbitrary length, with an approximate maximum size of 6kB. They are made up of packet segments of 255 bytes each. There can be as many as 255 packet segments per page.
<p>
<p>For a complete description of ogg pages and headers, please refer to the <a href="framing.html">framing document</a>.
<table border=0 width=100% color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
typedef struct {
unsigned char *header;
long header_len;
unsigned char *body;
long body_len;
} ogg_page;
</b></pre>
</td>
</tr>
</table>
<h3>Relevant Struct Members</h3>
<dl>
<dt><i>header</i></dt>
<dd>Pointer to the page header for this page. The exact contents of this header are defined in the framing spec document.</dd>
<dt><i>header_len</a></dt>
<dd>Length in bytes of the page header.</a>
<dt><i>body</a></dt>
<dd>Pointer to the data for this page.</dd>
<dt><i>body_len</a></dt>
<dd>Length in bytes of the body.</dd>
</dl>
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2000 xiph.org</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/index.html">Ogg Vorbis</a><br><a href="mailto:team@xiph.org">team@xiph.org</a></p></td>
</tr><tr>
<td><p class=tiny>libogg documentation</p></td>
<td align=right><p class=tiny>libogg version 1.25 - 20000615</p></td>
</tr>
</table>
</body>
</html>
<html>
<head>
<title>libogg - function - ogg_page_bos</title>
<link rel=stylesheet href="style.css" type="text/css">
</head>
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
<table border=0 width=100%>