libogg documentation | libogg release 1.0 - 20000615

# Decoding

Libogg contains a set of functions used in the decoding process.

All the libogg specific functions are declared in "ogg/ogg.h".

Decoding is based around the ogg synchronization layer. The ogg_sync_state 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.

Decoding through the Ogg layer follows a specific logical sequence. A read loop follows these logical steps:

- Expose a buffer using ogg_sync_buffer().
- Read data into the buffer, using fread() or a similar function.
- Call ogg_sync_wrote() to tell the synchronization layer how many bytes you wrote into the buffer.
- Write out the data using ogg_sync_pageout.
- Submit the completed page to the streaming layer with ogg_stream_pagein.
- Output a packet of data to the codec-specific decoding layer using ogg_stream_packetout.

In practice, streams are more complex, and Ogg also must handle headers, incomplete or dropped pages, and other errors in input.

function | purpose
ogg_sync_init | Initializes an Ogg bitstream.
ogg_sync_clear | Clears the status information from the synchronization struct. |
ogg_sync_reset | Resets the synchronization status to initial values.
ogg_sync_destroy | Frees the synchronization struct.
ogg_sync_buffer | Exposes a buffer from the synchronization layer in order to read data.
ogg_sync_wrote | Tells the synchronization layer how many bytes were written into the buffer.
ogg_sync_pageseek | Finds the borders of pages and resynchronizes the stream.
ogg_sync_pageout | Outputs a page from the synchronization layer.
ogg_stream_pagein | Submits a complete page to the stream layer.
ogg_stream_packetout | Outputs a packet to the codec-specific decoding engine.
ogg_stream_packetpeek | Provides access to the next packet in the bitstream without advancing decoding.

copyright © 2000 xiph.org | Ogg Vorbis team@xiph.org
libogg documentation | libogg release 1.0 - 20000615