From eadaa640c91536006fec0ad20d40e5053298d39f Mon Sep 17 00:00:00 2001 From: Ralph Giles Date: Thu, 4 Aug 2011 18:10:01 +0000 Subject: Improve documentation of ogg_stream_flush_fill and related calls. git-svn-id: http://svn.xiph.org/trunk/ogg@18053 0101bb08-14d6-0310-b084-bc0e0c8e3800 --- doc/libogg/encoding.html | 4 ++++ doc/libogg/ogg_stream_flush.html | 4 ++-- doc/libogg/ogg_stream_flush_fill.html | 11 ++++++++--- doc/libogg/ogg_stream_pageout_fill.html | 5 +++-- doc/libogg/reference.html | 1 + 5 files changed, 18 insertions(+), 7 deletions(-) (limited to 'doc') diff --git a/doc/libogg/encoding.html b/doc/libogg/encoding.html index 1fa3c0a..d97cfbd 100644 --- a/doc/libogg/encoding.html +++ b/doc/libogg/encoding.html @@ -53,6 +53,10 @@ All the libogg specific functions are declared in "ogg/ogg.h". ogg_stream_flush Forces any remaining packets in the stream to be returned as a page of any size. + +ogg_stream_flush_fill + Similar to ogg_stream_flush(), but specifies a page spill threshold in bytes. +

diff --git a/doc/libogg/ogg_stream_flush.html b/doc/libogg/ogg_stream_flush.html index ddc747b..31f2171 100644 --- a/doc/libogg/ogg_stream_flush.html +++ b/doc/libogg/ogg_stream_flush.html @@ -18,8 +18,8 @@

declared in "ogg/ogg.h";

This function checks for remaining packets inside the stream and forces remaining packets into a page, regardless of the size of the page. -

This should only be used when you want to flush an undersized page from the middle of the stream. Otherwise, ogg_stream_pageout or ogg_stream_pageout_fillshould always be used. -

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. +

This should only be used when you want to flush an undersized page from the middle of the stream. Otherwise, ogg_stream_pageout or ogg_stream_pageout_fillshould always be used. +

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 ogg_stream_pageout, it should generally be called in a loop until available packet data has been flushes, since even a single packet may span multiple pages.

diff --git a/doc/libogg/ogg_stream_flush_fill.html b/doc/libogg/ogg_stream_flush_fill.html index 8fbc8d2..d455a6b 100644 --- a/doc/libogg/ogg_stream_flush_fill.html +++ b/doc/libogg/ogg_stream_flush_fill.html @@ -17,9 +17,14 @@

declared in "ogg/ogg.h";

-

This function checks for remaining packets inside the stream and forces remaining packets into a page, regardless of the size of the page. -

This should only be used when you want to flush an undersized page from the middle of the stream. Otherwise, ogg_stream_pageout or ogg_stream_pageout_fillshould always be used. -

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. +

This function flushes available packets into pages, similar to +ogg_stream_flush(), but +allows applications to explicitly request a specific page spill +size.

+ +

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. ogg_stream_flush may be used instead if a particular page size isn't important. +

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.

diff --git a/doc/libogg/ogg_stream_pageout_fill.html b/doc/libogg/ogg_stream_pageout_fill.html index 13bd6ab..d005999 100644 --- a/doc/libogg/ogg_stream_pageout_fill.html +++ b/doc/libogg/ogg_stream_pageout_fill.html @@ -33,8 +33,9 @@ are no more pages ready for output.

been accumulated and accumulated packet data meets or exceeds the specified number of bytes, and/or when the accumulated packet data meets/exceeds the maximum page size regardless of accumulated -packet -count. Call ogg_stream_flush() if +packet count. +Call ogg_stream_flush() or +ogg_stream_flush_fill() if immediate page generation is desired regardless of accumulated data.



diff --git a/doc/libogg/reference.html b/doc/libogg/reference.html index 45cdf97..d006e61 100644 --- a/doc/libogg/reference.html +++ b/doc/libogg/reference.html @@ -62,6 +62,7 @@ ogg_stream_pageout()
ogg_stream_pageout_fill()
ogg_stream_flush()
+ogg_stream_flush_fill()

General
ogg_stream_init()
-- cgit v1.2.1