From 0abcbbfac5e066858445f75f83007996a3195f99 Mon Sep 17 00:00:00 2001 From: Monty Date: Wed, 20 May 2009 00:18:35 +0000 Subject: Update documentation to reflect new API calls, and extended error return behavior. svn path=/trunk/ogg/; revision=16017 --- doc/libogg/bitpacking.html | 4 ++ doc/libogg/encoding.html | 4 ++ doc/libogg/general.html | 2 +- doc/libogg/ogg_iovec_t.html | 62 +++++++++++++++++++++++++++ doc/libogg/ogg_stream_init.html | 2 +- doc/libogg/ogg_stream_iovecin.html | 83 +++++++++++++++++++++++++++++++++++++ doc/libogg/ogg_stream_packetin.html | 5 ++- doc/libogg/ogg_stream_pagein.html | 2 +- doc/libogg/ogg_sync_buffer.html | 2 +- doc/libogg/oggpack_writecheck.html | 81 ++++++++++++++++++++++++++++++++++++ 10 files changed, 242 insertions(+), 5 deletions(-) create mode 100644 doc/libogg/ogg_iovec_t.html create mode 100644 doc/libogg/ogg_stream_iovecin.html create mode 100644 doc/libogg/oggpack_writecheck.html (limited to 'doc/libogg') diff --git a/doc/libogg/bitpacking.html b/doc/libogg/bitpacking.html index 0b8e1b8..a285644 100644 --- a/doc/libogg/bitpacking.html +++ b/doc/libogg/bitpacking.html @@ -29,6 +29,10 @@ All the libogg specific functions are declared in "ogg/ogg.h". Initializes a buffer for writing using this bitpacking library. +oggpack_writecheck + Asynchronously checks error status of bitpacker write buffer. + + oggpack_reset Clears and resets the buffer to the initial position. diff --git a/doc/libogg/encoding.html b/doc/libogg/encoding.html index 32fa766..9485248 100644 --- a/doc/libogg/encoding.html +++ b/doc/libogg/encoding.html @@ -38,6 +38,10 @@ All the libogg specific functions are declared in "ogg/ogg.h". Submits a raw packet to the streaming layer, so that it can be formed into a page. +ogg_stream_iovecin + iovec version of ogg_stream_packetin() above. + + ogg_stream_pageout Outputs a completed page if the stream contains enough packets to form a full page. diff --git a/doc/libogg/general.html b/doc/libogg/general.html index 550ff0c..43788e5 100644 --- a/doc/libogg/general.html +++ b/doc/libogg/general.html @@ -79,7 +79,7 @@ All the libogg specific functions are declared in "ogg/ogg.h". Returns the sequential page number for this page. -ogg_packet_clear +ogg_packet_clear Clears the ogg_packet structure. diff --git a/doc/libogg/ogg_iovec_t.html b/doc/libogg/ogg_iovec_t.html new file mode 100644 index 0000000..4b3c32f --- /dev/null +++ b/doc/libogg/ogg_iovec_t.html @@ -0,0 +1,62 @@ + + + +libogg - datatype - ogg_iovec_t + + + + + + + + + +

libogg documentation

libogg - 20011015

+ +

ogg_iovec_t

+ +

declared in "ogg/ogg.h"

+ +

+The ogg_iovec_t struct encapsulates a length-encoded buffer. An array +of ogg_iovec_t is used to pass a list of buffers to functions that +accept data in ogg_iovec_t* form. +

+ + + + + +
+

+typedef struct {
+  void *iov_base;
+  size_t iov_len;
+} ogg_iovec_t;
+
+
+ +

Relevant Struct Members

+
+
iov_base
+
Pointer to the buffer data.
+
iov_len
+
Length of buffer data in bytes.
+
+ + +

+
+ + + + + + + + +

copyright © 2001 xiph.org foundation

Ogg Container Format

libogg documentation

libogg - 20011015

+ + + + diff --git a/doc/libogg/ogg_stream_init.html b/doc/libogg/ogg_stream_init.html index 8285493..e0e58f4 100644 --- a/doc/libogg/ogg_stream_init.html +++ b/doc/libogg/ogg_stream_init.html @@ -44,7 +44,7 @@ int ogg_stream_init(ogg_stream_state *os,int
  • 0 if successful
  • --1 if unsuccessful. If this fails, the ogg_stream_state was not properly declared before calling this function.
    • +-1 if unsuccessful.

    diff --git a/doc/libogg/ogg_stream_iovecin.html b/doc/libogg/ogg_stream_iovecin.html new file mode 100644 index 0000000..d07d345 --- /dev/null +++ b/doc/libogg/ogg_stream_iovecin.html @@ -0,0 +1,83 @@ + + + +libogg - function - ogg_stream_iovecin + + + + + + + + + +

    libogg documentation

    libogg release 1.0 - 20000615

    + +

    ogg_stream_iovecin

    + +

    declared in "ogg/ogg.h";

    + +

    This function submits packet data (in the form of +an array of ogg_iovec_t, rather than using +an ogg_packet structure) to the +bitstream for page encapsulation. After this is called, more packets +can be submitted, or pages can be written out.

    + +

    In a typical encoding situation, this should be used after filling a +packet with data. +The data in the packet is copied into the internal storage managed by +the ogg_stream_state, so the caller +is free to alter the contents of os after this call has returned. + +

    + + + + +
    +
    
+int ogg_stream_iovecin(ogg_stream_state *os, ogg_iovec_t *iov, int count, long e_o_s, ogg_int64_t granulepos);
+
    +
    + +

    Parameters

    +
    +
    os
    +
    Pointer to a previously declared ogg_stream_state struct.
    +
    iov
    +
    Length-encoded buffers held in an array of ogg_iovec_t. +
    count
    +
    Length of the iov array. +
    e_o_s
    +
    End of stream flag, analagous to the e_o_s field in an ogg_packet. +
    granulepos
    +
    Granule position value, analagous to the granpos field in an ogg_packet. +
    + + +

    Return Values

    +
    +
  • +0 returned on success. -1 returned in the event of internal error +(currently only caused by a failed memory allocation, a case that can +only occur on embedded systems. It is reasonable to ignore the return +value innormal desktop applications).
    • +
    +

    + +

    +

    + + + + + + + + +

    copyright © 2000 xiph.org

    Ogg Container Format

    libogg documentation

    libogg release 1.0 - 20000615

    + + + + + diff --git a/doc/libogg/ogg_stream_packetin.html b/doc/libogg/ogg_stream_packetin.html index 0e88afb..b8c8d02 100644 --- a/doc/libogg/ogg_stream_packetin.html +++ b/doc/libogg/ogg_stream_packetin.html @@ -50,7 +50,10 @@ int ogg_stream_packetin(ogg_stream_state *os,ogg_packet *op);

    Return Values

  • -0 is always returned.
    • +0 returned on success. -1 returned in the event of internal error +(currently only caused by a failed memory allocation, a case that can +only occur on embedded systems. It is reasonable to ignore the return +value innormal desktop applications).

    diff --git a/doc/libogg/ogg_stream_pagein.html b/doc/libogg/ogg_stream_pagein.html index 88d7a9b..a6ebb2a 100644 --- a/doc/libogg/ogg_stream_pagein.html +++ b/doc/libogg/ogg_stream_pagein.html @@ -43,7 +43,7 @@ int ogg_stream_pagein(ogg_stream_state *os,

    Return Values

    -
  • -1 indicates failure. This means that the serial number of the page did not match the serial number of the bitstream, or that the page version was incorrect.
    • +
  • -1 indicates failure. This means that the serial number of the page did not match the serial number of the bitstream, the page version was incorrect, or a memory allocation failed.
  • 0 means that the page was successfully submitted to the bitstream.
    • diff --git a/doc/libogg/ogg_sync_buffer.html b/doc/libogg/ogg_sync_buffer.html index 6f77133..8001d81 100644 --- a/doc/libogg/ogg_sync_buffer.html +++ b/doc/libogg/ogg_sync_buffer.html @@ -45,7 +45,7 @@ char *ogg_sync_buffer(ogg_sync_state *oy, long size);

    Return Values

  • -Returns a pointer to the newly allocated buffer.
    • +Returns a pointer to the newly allocated buffer or NULL on error

    diff --git a/doc/libogg/oggpack_writecheck.html b/doc/libogg/oggpack_writecheck.html new file mode 100644 index 0000000..e53dbac --- /dev/null +++ b/doc/libogg/oggpack_writecheck.html @@ -0,0 +1,81 @@ + + + +libogg - function - oggpack_writecheck + + + + + + + + + +

    libogg documentation

    libogg release 1.0 - 20000615

    + +

    oggpack_writecheck

    + +

    declared in "ogg/ogg.h";

    + +

    This function checks the readiness status of +an oggpack_buffer previously +initialized for writing using the +Ogg bitpacking functions. A write +buffer that encounters an error (such as a failed malloc) will clear +its internal state and release any in-use memory, flagging itself as +'not ready'. Subsequent attempts to write using the buffer will +silently fail. This error state may be detected at any later time by +using oggpack_writecheck(). It is safe but not necessary to +call oggpack_clear() on a buffer that +has flagged an error and released its resources. + +

    Important note to developers: Although libogg checks the +results of memory allocations, these checks are only useful on a +narrow range of embedded platforms. Allocation checks perform no +useful service on a general purpose desktop OS where pages are +routinely overallocated and all allocations succeed whether memory is +available or not. The only way to detect an out of memory condition +on the vast majority of OSes is to watch for and capture segmentation +faults. This function is useful only to embedded developers. + +

    + + + + +
    +
    
+int  oggpack_writecheck(oggpack_buffer *b);
+
    +
    + +

    Parameters

    +
    +
    b
    +
    An oggpack_buffer previously initialized for writing.
    +
    + + +

    Return Values

    +
    +
  • zero: buffer is ready for writing
    • +
  • nonzero: buffer is not ready or encountered an error
    • +
    +

    + +

    +

    + + + + + + + + +

    copyright © 2000 xiph.org

    Ogg Container Format

    libogg documentation

    libogg release 1.0 - 20000615

    + + + + + -- cgit v1.2.1