[xiph-commits] r18053 - trunk/ogg/doc/libogg

Thu Aug 4 11:10:01 PDT 2011

Author: giles
Date: 2011-08-04 11:10:01 -0700 (Thu, 04 Aug 2011)
New Revision: 18053

Modified:
   trunk/ogg/doc/libogg/encoding.html
   trunk/ogg/doc/libogg/ogg_stream_flush.html
   trunk/ogg/doc/libogg/ogg_stream_flush_fill.html
   trunk/ogg/doc/libogg/ogg_stream_pageout_fill.html
   trunk/ogg/doc/libogg/reference.html
Log:
Improve documentation of ogg_stream_flush_fill and related calls.


Modified: trunk/ogg/doc/libogg/encoding.html
===================================================================

--- trunk/ogg/doc/libogg/encoding.html	2011-08-04 17:57:02 UTC (rev 18052)
+++ trunk/ogg/doc/libogg/encoding.html	2011-08-04 18:10:01 UTC (rev 18053)
@@ -53,6 +53,10 @@
 <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>
+<tr valign=top>
+<td><a href="ogg_stream_flush_fill.html">ogg_stream_flush_fill</a></td>
+	<td>Similar to ogg_stream_flush(), but specifies a page spill threshold in bytes.<td>
+</tr>
 </table>
 
 <br><br>

Modified: trunk/ogg/doc/libogg/ogg_stream_flush.html
===================================================================
--- trunk/ogg/doc/libogg/ogg_stream_flush.html	2011-08-04 17:57:02 UTC (rev 18052)
+++ trunk/ogg/doc/libogg/ogg_stream_flush.html	2011-08-04 18:10:01 UTC (rev 18053)
@@ -18,8 +18,8 @@
 <p><i>declared in "ogg/ogg.h";</i></p>
 
 <p>This function checks for remaining packets inside the stream and forces remaining packets into a page, regardless of the size of the page.
-<p>This should only be used when you want to flush an undersized page from the middle of the stream.  Otherwise, <a href="ogg_stream_pageout.html">ogg_stream_pageout</a> or <a href="ogg_stream_pageout_fill.html">ogg_stream_pageout_fill</a>should always be used.  
-<p>This function can be used to verify that all packets have been flushed.  If the return value is 0, all packets have been placed into a page.
+<p>This should only be used when you want to flush an undersized page from the middle of the stream.  Otherwise, <a href="ogg_stream_pageout.html">ogg_stream_pageout</a> or <a href="ogg_stream_pageout_fill.html">ogg_stream_pageout_fill</a>should always be used.
+<p>This function can also be used to verify that all packets have been flushed.  If the return value is 0, all packets have been placed into a page. Like <a href="ogg_stream_pageout.html">ogg_stream_pageout</a>, it should generally be called in a loop until available packet data has been flushes, since even a single packet may span multiple pages.
 
 <br><br>
 <table border=0 color=black cellspacing=0 cellpadding=7>

Modified: trunk/ogg/doc/libogg/ogg_stream_flush_fill.html
===================================================================
--- trunk/ogg/doc/libogg/ogg_stream_flush_fill.html	2011-08-04 17:57:02 UTC (rev 18052)
+++ trunk/ogg/doc/libogg/ogg_stream_flush_fill.html	2011-08-04 18:10:01 UTC (rev 18053)
@@ -17,10 +17,15 @@
 
 <p><i>declared in "ogg/ogg.h";</i></p>
 
-<p>This function checks for remaining packets inside the stream and forces remaining packets into a page, regardless of the size of the page.
-<p>This should only be used when you want to flush an undersized page from the middle of the stream.  Otherwise, <a href="ogg_stream_pageout.html">ogg_stream_pageout</a> or <a href="ogg_stream_pageout_fill.html">ogg_stream_pageout_fill</a>should always be used.  
-<p>This function can be used to verify that all packets have been flushed.  If the return value is 0, all packets have been placed into a page.
+<p>This function flushes available packets into pages, similar to
+<a href="ogg_stream_flush.html">ogg_stream_flush()</a>, but
+allows applications to explicitly request a specific page spill
+size.</p>
 
+<p>This function checks for remaining packets inside the stream and forces remaining packets into pages of approximately the requested size.
+This should be used when you want to flush all remaining data from a stream. <a href="ogg_stream_flush.html">ogg_stream_flush</a> may be used instead if a particular page size isn't important. 
+<p>This function can be used to verify that all packets have been flushed.  If the return value is 0, all packets have been placed into a page. Generally speaking, it should be called in a loop until all packets are flushed, since even a single packet may span multiple pages.
+
 <br><br>
 <table border=0 color=black cellspacing=0 cellpadding=7>
 <tr bgcolor=#cccccc>

Modified: trunk/ogg/doc/libogg/ogg_stream_pageout_fill.html
===================================================================
--- trunk/ogg/doc/libogg/ogg_stream_pageout_fill.html	2011-08-04 17:57:02 UTC (rev 18052)
+++ trunk/ogg/doc/libogg/ogg_stream_pageout_fill.html	2011-08-04 18:10:01 UTC (rev 18053)
@@ -33,8 +33,9 @@
 been accumulated and accumulated packet data meets or exceeds the
 specified number of bytes, <b>and/or</b> when the accumulated packet
 data meets/exceeds the maximum page size regardless of accumulated
-packet
-count. Call <a href="ogg_stream_flush.html">ogg_stream_flush()</a> if
+packet count.
+Call <a href="ogg_stream_flush.html">ogg_stream_flush()</a> or
+<a href="ogg_stream_flush_fill.html">ogg_stream_flush_fill()</a> if
 immediate page generation is desired regardless of accumulated data.</p>
 
 <br><br>

Modified: trunk/ogg/doc/libogg/reference.html
===================================================================
--- trunk/ogg/doc/libogg/reference.html	2011-08-04 17:57:02 UTC (rev 18052)
+++ trunk/ogg/doc/libogg/reference.html	2011-08-04 18:10:01 UTC (rev 18053)
@@ -62,6 +62,7 @@
 <a href="ogg_stream_pageout.html">ogg_stream_pageout()</a><br>
 <a href="ogg_stream_pageout_fill.html">ogg_stream_pageout_fill()</a><br>
 <a href="ogg_stream_flush.html">ogg_stream_flush()</a><br>
+<a href="ogg_stream_flush_fill.html">ogg_stream_flush_fill()</a><br>
 <br>
 <b>General</b><br>
 <a href="ogg_stream_init.html">ogg_stream_init()</a><br>

