RubyGems - gstreamer - Versions diffs - 1.1.0-x86-mingw32 - Mend

gstreamer 1.1.0-x86-mingw32

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1897) hide show

data/vendor/local/share/doc/libvorbis-1.3.2/libvorbis/vorbis_version_string.html ADDED Viewed

@@ -0,0 +1,56 @@
+<html>
+<head>
+<title>libvorbis - function - vorbis_version_string</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>libvorbis documentation</p></td>
+<td align=right><p class=tiny>libvorbis version 1.3.2 - 20101101</p></td>
+</tr>
+</table>
+<h1>vorbis_version_string</h1>
+<p><i>declared in "vorbis/codec.h";</i></p>
+<p>This function returns a string giving version information for libvorbis. (This is not the same string that libvorbis encodes into the vendor field of comment headers.)</p>
+<table border=0 color=black cellspacing=0 cellpadding=7>
+<tr bgcolor=#cccccc>
+	<td>
+<pre><b>
+extern const char *vorbis_version_string(void);
+</b></pre>
+	</td>
+</tr>
+</table>
+<h3>Parameters</h3>
+<p>None.</p>
+<h3>Return Values</h3>
+<blockquote>
+<li>The libvorbis version string. The string is in static storage.</li>
+</blockquote>
+<p>
+<br><br>
+<hr noshade>
+<table border=0 width=100%>
+<tr valign=top>
+<td><p class=tiny>copyright &copy; 2010 Xiph.Org</p></td>
+<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/index.html">Ogg Vorbis</a></p></td>
+</tr><tr>
+<td><p class=tiny>libvorbis documentation</p></td>
+<td align=right><p class=tiny>libvorbis version 1.3.2 - 20101101</p></td>
+</tr>
+</table>
+</body>
+</html>

data/vendor/local/share/doc/libvorbis-1.3.2/lspmap.png ADDED Viewed

Binary file

data/vendor/local/share/doc/libvorbis-1.3.2/oddlsp.png ADDED Viewed

Binary file

data/vendor/local/share/doc/libvorbis-1.3.2/oggstream.html ADDED Viewed

@@ -0,0 +1,234 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-15"/>
+<title>Ogg Vorbis Documentation</title>
+<style type="text/css">
+body {
+  margin: 0 18px 0 18px;
+  padding-bottom: 30px;
+  font-family: Verdana, Arial, Helvetica, sans-serif;
+  color: #333333;
+  font-size: .8em;
+}
+a {
+  color: #3366cc;
+}
+img {
+  border: 0;
+}
+#xiphlogo {
+  margin: 30px 0 16px 0;
+}
+#content p {
+  line-height: 1.4;
+}
+h1, h1 a, h2, h2 a, h3, h3 a {
+  font-weight: bold;
+  color: #ff9900;
+  margin: 1.3em 0 8px 0;
+}
+h1 {
+  font-size: 1.3em;
+}
+h2 {
+  font-size: 1.2em;
+}
+h3 {
+  font-size: 1.1em;
+}
+li {
+  line-height: 1.4;
+}
+#copyright {
+  margin-top: 30px;
+  line-height: 1.5em;
+  text-align: center;
+  font-size: .8em;
+  color: #888888;
+  clear: both;
+}
+</style>
+</head>
+<body>
+<div id="xiphlogo">
+  <a href="http://www.xiph.org/"><img src="fish_xiph_org.png" alt="Fish Logo and Xiph.Org"/></a>
+</div>
+<h1>Ogg logical and physical bitstream overview</h1>
+<h2>Ogg bitstreams</h2>
+<p>Ogg codecs use octet vectors of raw, compressed data
+(<em>packets</em>). These compressed packets do not have any
+high-level structure or boundary information; strung together, they
+appear to be streams of random bytes with no landmarks.</p>
+<p>Raw packets may be used directly by transport mechanisms that provide
+their own framing and packet-separation mechanisms (such as UDP
+datagrams). For stream based storage (such as files) and transport
+(such as TCP streams or pipes), Vorbis and other future Ogg codecs use
+the Ogg bitstream format to provide framing/sync, sync recapture
+after error, landmarks during seeking, and enough information to
+properly separate data back into packets at the original packet
+boundaries without relying on decoding to find packet boundaries.</p>
+<h2>Logical and physical bitstreams</h2>
+<p>Raw packets are grouped and encoded into contiguous pages of
+structured bitstream data called <em>logical bitstreams</em>. A
+logical bitstream consists of pages, in order, belonging to a single
+codec instance. Each page is a self contained entity (although it is
+possible that a packet may be split and encoded across one or more
+pages); that is, the page decode mechanism is designed to recognize,
+verify and handle single pages at a time from the overall bitstream.</p>
+<p>Multiple logical bitstreams can be combined (with restrictions) into a
+single <em>physical bitstream</em>. A physical bitstream consists of
+multiple logical bitstreams multiplexed at the page level and may
+include a 'meta-header' at the beginning of the multiplexed logical
+stream that serves as identification magic. Whole pages are taken in
+order from multiple logical bitstreams and combined into a single
+physical stream of pages. The decoder reconstructs the original
+logical bitstreams from the physical bitstream by taking the pages in
+order from the physical bitstream and redirecting them into the
+appropriate logical decoding entity. The simplest physical bitstream
+is a single, unmultiplexed logical bitstream with no meta-header; this
+is referred to as a 'degenerate stream'.</p>
+<p><a href="framing.html">Ogg Logical Bitstream Framing</a> discusses
+the page format of an Ogg bitstream, the packet coding process
+and logical bitstreams in detail. The remainder of this document
+specifies requirements for constructing finished, physical Ogg
+bitstreams.</p>
+<h2>Mapping Restrictions</h2>
+<p>Logical bitstreams may not be mapped/multiplexed into physical
+bitstreams without restriction. Here we discuss design restrictions
+on Ogg physical bitstreams in general, mostly to introduce
+design rationale. Each 'media' format defines its own (generally more
+restrictive) mapping. An 'Ogg Vorbis Audio Bitstream', for example, has a
+specific physical bitstream structure.
+An 'Ogg A/V' bitstream (not currently specified) will also mandate a
+specific, restricted physical bitstream format.</p>
+<h3>additional end-to-end structure</h3>
+<p>The <a href="framing.html">framing specification</a> defines
+'beginning of stream' and 'end of stream' page markers via a header
+flag (it is possible for a stream to consist of a single page). A
+stream always consists of an integer number of pages, an easy
+requirement given the variable size nature of pages.</p>
+<p>In addition to the header flag marking the first and last pages of a
+logical bitstream, the first page of an Ogg bitstream obeys
+additional restrictions. Each individual media mapping specifies its
+own implementation details regarding these restrictions.</p>
+<p>The first page of a logical Ogg bitstream consists of a single,
+small 'initial header' packet that includes sufficient information to
+identify the exact CODEC type and media requirements of the logical
+bitstream. The intent of this restriction is to simplify identifying
+the bitstream type and content; for a given media type (or across all
+Ogg media types) we can know that we only need a small, fixed
+amount of data to uniquely identify the bitstream type.</p>
+<p>As an example, Ogg Vorbis places the name and revision of the Vorbis
+CODEC, the audio rate and the audio quality into this initial header,
+thus simplifying vastly the certain identification of an Ogg Vorbis
+audio bitstream.</p>
+<h3>sequential multiplexing (chaining)</h3>
+<p>The simplest form of logical bitstream multiplexing is concatenation
+(<em>chaining</em>). Complete logical bitstreams are strung
+one-after-another in order. The bitstreams do not overlap; the final
+page of a given logical bitstream is immediately followed by the
+initial page of the next. Chaining is the only logical->physical
+mapping allowed by Ogg Vorbis.</p>
+<p>Each chained logical bitstream must have a unique serial number within
+the scope of the physical bitstream.</p>
+<h3>concurrent multiplexing (grouping)</h3>
+<p>Logical bitstreams may also be multiplexed 'in parallel'
+(<em>grouped</em>). An example of grouping would be to allow
+streaming of separate audio and video streams, using different codecs
+and different logical bitstreams, in the same physical bitstream.
+Whole pages from multiple logical bitstreams are mixed together.</p>
+<p>The initial pages of each logical bitstream must appear first; the
+media mapping specifies the order of the initial pages. For example,
+Ogg A/V will eventually specify an Ogg video bitstream with
+audio. The mapping may specify that the physical bitstream must begin
+with the initial page of a logical video bitstream, followed by the
+initial page of an audio stream. Unlike initial pages, terminal pages
+for the logical bitstreams need not all occur contiguously (although a
+specific media mapping may require this; it is not mandated by the
+generic Ogg stream spec). Terminal pages may be 'nil' pages,
+that is, pages containing no content but simply a page header with
+position information and the 'last page of bitstream' flag set in the
+page header.</p>
+<p>Each grouped bitstream must have a unique serial number within the
+scope of the physical bitstream.</p>
+<h3>sequential and concurrent multiplexing</h3>
+<p>Groups of concurrently multiplexed bitstreams may be chained
+consecutively. Such a physical bitstream obeys all the rules of both
+grouped and chained multiplexed streams; the groups, when unchained ,
+must stand on their own as a valid concurrently multiplexed
+bitstream.</p>
+<h3>multiplexing example</h3>
+<p>Below, we present an example of a grouped and chained bitstream:</p>
+<p><img src="stream.png" alt="stream"/></p>
+<p>In this example, we see pages from five total logical bitstreams
+multiplexed into a physical bitstream. Note the following
+characteristics:</p>
+<ol>
+<li>Grouped bitstreams begin together; all of the initial pages
+must appear before any data pages. When concurrently multiplexed
+groups are chained, the new group does not begin until all the
+bitstreams in the previous group have terminated.</li>
+<li>The pages of concurrently multiplexed bitstreams need not conform
+to a regular order; the only requirement is that page <tt>n</tt> of a
+logical bitstream follow page <tt>n-1</tt> in the physical bitstream.
+There are no restrictions on intervening pages belonging to other
+logical bitstreams. (Tying page appearance to bitrate demands is one
+logical strategy, ie, the page appears at the chronological point
+where decode requires more information).</li>
+</ol>
+<div id="copyright">
+  The Xiph Fish Logo is a
+  trademark (&trade;) of Xiph.Org.<br/>
+  These pages &copy; 1994 - 2005 Xiph.Org. All rights reserved.
+</div>
+</body>
+</html>

data/vendor/local/share/doc/libvorbis-1.3.2/programming.html ADDED Viewed

@@ -0,0 +1,554 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-15"/>
+<title>Ogg Vorbis Documentation</title>
+<style type="text/css">
+body {
+  margin: 0 18px 0 18px;
+  padding-bottom: 30px;
+  font-family: Verdana, Arial, Helvetica, sans-serif;
+  color: #333333;
+  font-size: .8em;
+}
+a {
+  color: #3366cc;
+}
+img {
+  border: 0;
+}
+#xiphlogo {
+  margin: 30px 0 16px 0;
+}
+#content p {
+  line-height: 1.4;
+}
+h1, h1 a, h2, h2 a, h3, h3 a {
+  font-weight: bold;
+  color: #ff9900;
+  margin: 1.3em 0 8px 0;
+}
+h1 {
+  font-size: 1.3em;
+}
+h2 {
+  font-size: 1.2em;
+}
+h3 {
+  font-size: 1.1em;
+}
+li {
+  line-height: 1.4;
+}
+#copyright {
+  margin-top: 30px;
+  line-height: 1.5em;
+  text-align: center;
+  font-size: .8em;
+  color: #888888;
+  clear: both;
+}
+</style>
+</head>
+<body>
+<div id="xiphlogo">
+  <a href="http://www.xiph.org/"><img src="fish_xiph_org.png" alt="Fish Logo and Xiph.Org"/></a>
+</div>
+<h1>Programming with Xiph.Org <tt>libvorbis</tt></h1>
+<h2>Description</h2>
+<p>Libvorbis is the Xiph.Org Foundation's portable Ogg Vorbis CODEC
+implemented as a programmatic library. Libvorbis provides primitives
+to handle framing and manipulation of Ogg bitstreams (used by the
+Vorbis for streaming), a full analysis (encoding) interface as well as
+packet decoding and synthesis for playback.</p>
+<p>The libvorbis library does not provide any system interface; a
+full-featured demonstration player included with the library
+distribtion provides example code for a variety of system interfaces
+as well as a working example of using libvorbis in production code.</p>
+<h2>Encoding Overview</h2>
+<h2>Decoding Overview</h2>
+<p>Decoding a bitstream with libvorbis follows roughly the following
+steps:</p>
+<ol>
+<li>Frame the incoming bitstream into pages</li>
+<li>Sort the pages by logical bitstream and buffer then into logical streams</li>
+<li>Decompose the logical streams into raw packets</li>
+<li>Reconstruct segments of the original data from each packet</li>
+<li>Glue the reconstructed segments back into a decoded stream</li>
+</ol>
+<h3>Framing</h3>
+<p>An Ogg bitstream is logically arranged into pages, but to decode
+the pages, we have to find them first. The raw bitstream is first fed
+into an <tt>ogg_sync_state</tt> buffer using <tt>ogg_sync_buffer()</tt>
+and <tt>ogg_sync_wrote()</tt>. After each block we submit to the sync
+buffer, we should check to see if we can frame and extract a complete
+page or pages using <tt>ogg_sync_pageout()</tt>. Extra pages are
+buffered; allowing them to build up in the <tt>ogg_sync_state</tt>
+buffer will eventually exhaust memory.</p>
+<p>The Ogg pages returned from <tt>ogg_sync_pageout</tt> need not be
+decoded further to be used as landmarks in seeking; seeking can be
+either a rough process of simply jumping to approximately intuited
+portions of the bitstream, or it can be a precise bisection process
+that captures pages and inspects data position. When seeking,
+however, sequential multiplexing (chaining) must be accounted for;
+beginning play in a new logical bitstream requires initializing a
+synthesis engine with the headers from that bitstream. Vorbis
+bitstreams do not make use of concurent multiplexing (grouping).</p>
+<h3>Sorting</h3>
+<p>The pages produced by <tt>ogg_sync_pageout</tt> are then sorted by
+serial number to seperate logical bitstreams. Initialize logical
+bitstream buffers (<tt>og_stream_state</tt>) using
+<tt>ogg_stream_init()</tt>. Pages are submitted to the matching
+logical bitstream buffer using <tt>ogg_stream_pagein</tt>; the serial
+number of the page and the stream buffer must match, or the page will
+be rejected. A page submitted out of sequence will simply be noted,
+and in the course of outputting packets, the hole will be flagged
+(<tt>ogg_sync_pageout</tt> and <tt>ogg_stream_packetout</tt> will
+return a negative value at positions where they had to recapture the
+stream).</p>
+<h3>Extracting packets</h3>
+<p>After submitting page[s] to a logical stream, read available packets
+using <tt>ogg_stream_packetout</tt>.</p>
+<h3>Decoding packets</h3>
+<h3>Reassembling data segments</h3>
+<h2>Ogg Bitstream Manipulation Structures</h2>
+<p>Two of the Ogg bitstream data structures are intended to be
+transparent to the developer; the fields should be used directly.</p>
+<h3>ogg_packet</h3>
+<pre>
+typedef struct {
+  unsigned char *packet;
+  long  bytes;
+  long  b_o_s;
+  long  e_o_s;
+  size64 granulepos;
+} ogg_packet;
+</pre>
+<dl>
+<dt>packet:</dt>
+<dd>a pointer to the byte data of the raw packet</dd>
+<dt>bytes:</dt>
+<dd>the size of the packet' raw data</dd>
+<dt>b_o_s:</dt>
+<dd>beginning of stream; nonzero if this is the first packet of
+  the logical bitstream</dd>
+<dt>e_o_s:</dt>
+<dd>end of stream; nonzero if this is the last packet of the
+  logical bitstream</dd>
+<dt>granulepos:</dt>
+<dd>the absolute position of this packet in the original
+  uncompressed data stream.</dd>
+</dl>
+<h4>encoding notes</h4>
+<p>The encoder is responsible for setting all of
+the fields of the packet to appropriate values before submission to
+<tt>ogg_stream_packetin()</tt>; however, it is noted that the value in
+<tt>b_o_s</tt> is ignored; the first page produced from a given
+<tt>ogg_stream_state</tt> structure will be stamped as the initial
+page. <tt>e_o_s</tt>, however, must be set; this is the means by
+which the stream encoding primitives handle end of stream and cleanup.</p>
+<h4>decoding notes</h4>
+<p><tt>ogg_stream_packetout()</tt> sets the fields
+to appropriate values. Note that granulepos will be >= 0 only in the
+case that the given packet actually represents that position (ie, only
+the last packet completed on any page will have a meaningful
+<tt>granulepos</tt>). Intervening frames will see <tt>granulepos</tt> set
+to -1.</p>
+<h3>ogg_page</h3>
+<pre>
+typedef struct {
+  unsigned char *header;
+  long header_len;
+  unsigned char *body;
+  long body_len;
+} ogg_page;
+</pre>
+<dl>
+<dt>header:</dt>
+<dd>pointer to the page header data</dd>
+<dt>header_len:</dt>
+<dd>length of the page header in bytes</dd>
+<dt>body:</dt>
+<dd>pointer to the page body</dd>
+<dt>body_len:</dt>
+<dd>length of the page body</dd>
+</dl>
+<p>Note that although the <tt>header</tt> and <tt>body</tt> pointers do
+not necessarily point into a single contiguous page vector, the page
+body must immediately follow the header in the bitstream.</p>
+<h2>Ogg Bitstream Manipulation Functions</h2>
+<h3>
+int    ogg_page_bos(ogg_page *og);
+</h3>
+<p>Returns the 'beginning of stream' flag for the given Ogg page. The
+beginning of stream flag is set on the initial page of a logical
+bitstream.</p>
+<p>Zero indicates the flag is cleared (this is not the initial page of a
+logical bitstream). Nonzero indicates the flag is set (this is the
+initial page of a logical bitstream).</p>
+<h3>
+int    ogg_page_continued(ogg_page *og);
+</h3>
+<p>Returns the 'packet continued' flag for the given Ogg page. The packet
+continued flag indicates whether or not the body data of this page
+begins with packet continued from a preceeding page.</p>
+<p>Zero (unset) indicates that the body data begins with a new packet.
+Nonzero (set) indicates that the first packet data on the page is a
+continuation from the preceeding page.</p>
+<h3>
+int    ogg_page_eos(ogg_page *og);
+</h3>
+<p>Returns the 'end of stream' flag for a give Ogg page. The end of page
+flag is set on the last (terminal) page of a logical bitstream.</p>
+<p>Zero (unset) indicates that this is not the last page of a logical
+bitstream. Nonzero (set) indicates that this is the last page of a
+logical bitstream and that no addiitonal pages belonging to this
+bitstream may follow.</p>
+<h3>
+size64 ogg_page_granulepos(ogg_page *og);
+</h3>
+<p>Returns the position of this page as an absolute position within the
+original uncompressed data. The position, as returned, is 'frames
+encoded to date up to and including the last whole packet on this
+page'. Partial packets begun on this page but continued to the
+following page are not included. If no packet ends on this page, the
+frame position value will be equal to the frame position value of the
+preceeding page. If none of the original uncompressed data is yet
+represented in the logical bitstream (for example, the first page of a
+bitstream consists only of a header packet; this packet encodes only
+metadata), the value shall be zero.</p>
+<p>The units of the framenumber are determined by media mapping. A
+vorbis audio bitstream, for example, defines one frame to be the
+channel values from a single sampling period (eg, a 16 bit stereo
+bitstream consists of two samples of two bytes for a total of four
+bytes, thus a frame would be four bytes). A video stream defines one
+frame to be a single frame of video.</p>
+<h3>
+int    ogg_page_pageno(ogg_page *og);
+</h3>
+<p>Returns the sequential page number of the given Ogg page. The first
+page in a logical bitstream is numbered zero; following pages are
+numbered in increasing monotonic order.</p>
+<h3>
+int    ogg_page_serialno(ogg_page *og);
+</h3>
+<p>Returns the serial number of the given Ogg page. The serial number is
+used as a handle to distinguish various logical bitstreams in a
+physical Ogg bitstresm. Every logical bitstream within a
+physical bitstream must use a unique (within the scope of the physical
+bitstream) serial number, which is stamped on all bitstream pages.</p>
+<h3>
+int    ogg_page_version(ogg_page *og);
+</h3>
+<p>Returns the revision of the Ogg bitstream structure of the given page.
+Currently, the only permitted number is zero. Later revisions of the
+bitstream spec will increment this version should any changes be
+incompatable.</p>
+<h3>
+int    ogg_stream_clear(ogg_stream_state *os);
+</h3>
+<p>Clears and deallocates the internal storage of the given Ogg stream.
+After clearing, the stream structure is not initialized for use;
+<tt>ogg_stream_init</tt> must be called to reinitialize for use.
+Use <tt>ogg_stream_reset</tt> to reset the stream state
+to a fresh, intiialized state.</p>
+<p><tt>ogg_stream_clear</tt> does not call <tt>free()</tt> on the pointer
+<tt>os</tt>, allowing use of this call on stream structures in static
+or automatic storage. <tt>ogg_stream_destroy</tt>is a complimentary
+function that frees the pointer as well.</p>
+<p>Returns zero on success and non-zero on failure. This function always
+succeeds.</p>
+<h3>
+int    ogg_stream_destroy(ogg_stream_state *os);
+</h3>
+<p>Clears and deallocates the internal storage of the given Ogg stream,
+then frees the storage associated with the pointer <tt>os</tt>.</p>
+<p><tt>ogg_stream_clear</tt> does not call <tt>free()</tt> on the pointer
+<tt>os</tt>, allowing use of that call on stream structures in static
+or automatic storage.</p>
+<p>Returns zero on success and non-zero on failure. This function always
+succeeds.</p>
+<h3>
+int    ogg_stream_init(ogg_stream_state *os,int serialno);
+</h3>
+<p>Initialize the storage associated with <tt>os</tt> for use as an Ogg
+stream. This call is used to initialize a stream for both encode and
+decode. The given serial number is the serial number that will be
+stamped on pages of the produced bitstream (during encode), or used as
+a check that pages match (during decode).</p>
+<p>Returns zero on success, nonzero on failure.</p>
+<h3>
+int    ogg_stream_packetin(ogg_stream_state *os, ogg_packet *op);
+</h3>
+<p>Used during encoding to add the given raw packet to the given Ogg
+bitstream. The contents of <tt>op</tt> are copied;
+<tt>ogg_stream_packetin</tt> does not retain any pointers into
+<tt>op</tt>'s storage. The encoding proccess buffers incoming packets
+until enough packets have been assembled to form an entire page;
+<tt>ogg_stream_pageout</tt> is used to read complete pages.</p>
+<p>Returns zero on success, nonzero on failure.</p>
+<h3>
+int    ogg_stream_packetout(ogg_stream_state *os,ogg_packet *op);
+</h3>
+<p>Used during decoding to read raw packets from the given logical
+bitstream. <tt>ogg_stream_packetout</tt> will only return complete
+packets for which checksumming indicates no corruption. The size and
+contents of the packet exactly match those given in the encoding
+process. </p>
+<p>Returns zero if the next packet is not ready to be read (not buffered
+or incomplete), positive if it returned a complete packet in
+<tt>op</tt> and negative if there is a gap, extra bytes or corruption
+at this position in the bitstream (essentially that the bitstream had
+to be recaptured). A negative value is not necessarily an error. It
+would be a common occurence when seeking, for example, which requires
+recapture of the bitstream at the position decoding continued.</p>
+<p>If the return value is positive, <tt>ogg_stream_packetout</tt> placed
+a packet in <tt>op</tt>. The data in <tt>op</tt> points to static
+storage that is valid until the next call to
+<tt>ogg_stream_pagein</tt>, <tt>ogg_stream_clear</tt>,
+<tt>ogg_stream_reset</tt>, or <tt>ogg_stream_destroy</tt>. The
+pointers are not invalidated by more calls to
+<tt>ogg_stream_packetout</tt>.</p>
+<h3>
+int    ogg_stream_pagein(ogg_stream_state *os, ogg_page *og);
+</h3>
+<p>Used during decoding to buffer the given complete, pre-verified page
+for decoding into raw Ogg packets. The given page must be framed,
+normally produced by <tt>ogg_sync_pageout</tt>, and from the logical
+bitstream associated with <tt>os</tt> (the serial numbers must match).
+The contents of the given page are copied; <tt>ogg_stream_pagein</tt>
+retains no pointers into <tt>og</tt> storage.</p>
+<p>Returns zero on success and non-zero on failure.</p>
+<h3>
+int    ogg_stream_pageout(ogg_stream_state *os, ogg_page *og);
+</h3>
+<p>Used during encode to read complete pages from the stream buffer. The
+returned page is ready for sending out to the real world.</p>
+<p>Returns zero if there is no complete page ready for reading. Returns
+nonzero when it has placed data for a complete page into
+<tt>og</tt>. Note that the storage returned in og points into internal
+storage; the pointers in <tt>og</tt> are valid until the next call to
+<tt>ogg_stream_pageout</tt>, <tt>ogg_stream_packetin</tt>,
+<tt>ogg_stream_reset</tt>, <tt>ogg_stream_clear</tt> or
+<tt>ogg_stream_destroy</tt>.</p>
+<h3>
+int    ogg_stream_reset(ogg_stream_state *os);
+</h3>
+<p>Resets the given stream's state to that of a blank, unused stream;
+this may be used during encode or decode.</p>
+<p>Note that if used during encode, it does not alter the stream's serial
+number. In addition, the next page produced during encoding will be
+marked as the 'initial' page of the logical bitstream.</p>
+<p>When used during decode, this simply clears the data buffer of any
+pending pages. Beginning and end of stream cues are read from the
+bitstream and are unaffected by reset.</p>
+<p>Returns zero on success and non-zero on failure. This function always
+succeeds.</p>
+<h3>
+char  *ogg_sync_buffer(ogg_sync_state *oy, long size);
+</h3>
+<p>This call is used to buffer a raw bitstream for framing and
+verification. <tt>ogg_sync_buffer</tt> handles stream capture and
+recapture, checksumming, and division into Ogg pages (as required by
+<tt>ogg_stream_pagein</tt>).</p>
+<p><tt>ogg_sync_buffer</tt> exposes a buffer area into which the decoder
+copies the next (up to) <tt>size</tt> bytes. We expose the buffer
+(rather than taking a buffer) in order to avoid an extra copy many
+uses; this way, for example, <tt>read()</tt> can transfer data
+directly into the stream buffer without first needing to place it in
+temporary storage.</p>
+<p>Returns a pointer into <tt>oy</tt>'s internal bitstream sync buffer;
+the remaining space in the sync buffer is at least <tt>size</tt>
+bytes. The decoder need not write all of <tt>size</tt> bytes;
+<tt>ogg_sync_wrote</tt> is used to inform the engine how many bytes
+were actually written. Use of <tt>ogg_sync_wrote</tt> after writing
+into the exposed buffer is mandantory.</p>
+<h3>
+int    ogg_sync_clear(ogg_sync_state *oy);
+</h3>
+<p><tt>ogg_sync_clear</tt>
+clears and deallocates the internal storage of the given Ogg sync
+buffer. After clearing, the sync structure is not initialized for
+use; <tt>ogg_sync_init</tt> must be called to reinitialize for use.
+Use <tt>ogg_sync_reset</tt> to reset the sync state and buffer to a
+fresh, intiialized state.</p>
+<p><tt>ogg_sync_clear</tt> does not call <tt>free()</tt> on the pointer
+<tt>oy</tt>, allowing use of this call on sync structures in static
+or automatic storage. <tt>ogg_sync_destroy</tt>is a complimentary
+function that frees the pointer as well.</p>
+<p>Returns zero on success and non-zero on failure. This function always
+succeeds.</p>
+<h3>
+int    ogg_sync_destroy(ogg_sync_state *oy);
+</h3>
+<p>Clears and deallocates the internal storage of the given Ogg sync
+buffer, then frees the storage associated with the pointer
+<tt>oy</tt>.</p>
+<p>An alternative function,<tt>ogg_sync_clear</tt>, does not call
+<tt>free()</tt> on the pointer <tt>oy</tt>, allowing use of that call on
+stream structures in static or automatic storage.</p>
+<p>Returns zero on success and non-zero on failure. This function always
+succeeds.</p>
+<h3>
+int    ogg_sync_init(ogg_sync_state *oy);
+</h3>
+<p>Initializes the sync buffer <tt>oy</tt> for use.</p>
+<p>Returns zero on success and non-zero on failure. This function always
+succeeds.</p>
+<h3>
+int    ogg_sync_pageout(ogg_sync_state *oy, ogg_page *og);
+</h3>
+<p>Reads complete, framed, verified Ogg pages from the sync buffer,
+placing the page data in <tt>og</tt>.</p>
+<p>Returns zero when there's no complete pages buffered for
+retrieval. Returns negative when a loss of sync or recapture occurred
+(this is not necessarily an error; recapture would be required after
+seeking, for example). Returns positive when a page is returned in
+<tt>og</tt>. Note that the data in <tt>og</tt> points into the sync
+buffer storage; the pointers are valid until the next call to
+<tt>ogg_sync_buffer</tt>, <tt>ogg_sync_clear</tt>,
+<tt>ogg_sync_destroy</tt> or <tt>ogg_sync_reset</tt>.</p>
+<h3>
+int    ogg_sync_reset(ogg_sync_state *oy);
+</h3>
+<p><tt>ogg_sync_reset</tt> resets the sync state in <tt>oy</tt> to a
+clean, empty state. This is useful, for example, when seeking to a
+new location in a bitstream.</p>
+<p>Returns zero on success, nonzero on failure.</p>
+<h3>
+int    ogg_sync_wrote(ogg_sync_state *oy, long bytes);
+</h3>
+<p>Used to inform the sync state as to how many bytes were actually
+written into the exposed sync buffer. It must be equal to or less
+than the size of the buffer requested.</p>
+<p>Returns zero on success and non-zero on failure; failure occurs only
+when the number of bytes written were larger than the buffer.</p>
+<div id="copyright">
+  The Xiph Fish Logo is a
+  trademark (&trade;) of Xiph.Org.<br/>
+  These pages &copy; 1994 - 2005 Xiph.Org. All rights reserved.
+</div>
+</body>
+</html>