From 264bbb247f24fd273351cc5682cd480074d54c2c Mon Sep 17 00:00:00 2001 From: Monty Date: Thu, 22 Jul 1999 13:40:50 +0000 Subject: [PATCH] More documentation svn path=/trunk/vorbis/; revision=12 --- doc/programming.html | 70 +++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 64 insertions(+), 6 deletions(-) diff --git a/doc/programming.html b/doc/programming.html index 1d62f3e..a396d3d 100644 --- a/doc/programming.html +++ b/doc/programming.html @@ -24,8 +24,64 @@ as well as a working example of using libvorbis in production code.

Encoding Overview

+ +

Decoding Overview

+Decoding a bitstream with libvorbis follows roughly the following +steps: + +
    +
  1. Frame the incoming bitstream into pages +
  2. Sort the pages by logical bitstream and buffer then into logical streams +
  3. Decompose the logical streams into raw packets +
  4. Reconstruct segments of the original data from each packet +
  5. Glue the reconstructed segments back into a decoded stream +
+ +

Framing

+ +An OggSquish 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 ogg_sync_state buffer using ogg_sync_buffer() +and ogg_sync_wrote(). 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 ogg_sync_pageout(). Extra pages are +buffered; allowing them to build up in the ogg_sync_state +buffer will eventually exhaust memory.

+ +The Ogg pages returned from ogg_sync_pageout 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).

+ +

Sorting

+ +The pages produced by ogg_sync_pageout are then sorted by +serial number to seperate logical bitstreams. Initialize logical +bitstream buffers (og_stream_state) using +ogg_stream_init(). Pages are submitted to the matching +logical bitstream buffer using ogg_stream_pagein; 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 +(ogg_sync_pageout and ogg_stream_packetout will +return a negative value at positions where they had to recapture the +stream). + +

Extracting packets

+ +After submitting page[s] to a logical stream, read available packets +using ogg_stream_packetout. + +

Decoding packets

+ +

Reassembling data segments

OggSquish Bitstream Manipulation Structures

@@ -383,12 +439,14 @@ int ogg_sync_pageout(ogg_sync_state *oy, ogg_page *og); Reads complete, framed, verified Ogg pages from the sync buffer, placing the page data in og.

-Returns zero when there's no complete pages buffered for retrieval. -Returns positive when a page is returned in og. Note that the -data in og points into the sync buffer storage; the pointers -are valid until the next call to ogg_sync_buffer, -ogg_sync_clear, ogg_sync_destroy or -ogg_sync_reset. +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 +og. Note that the data in og points into the sync +buffer storage; the pointers are valid until the next call to +ogg_sync_buffer, ogg_sync_clear, +ogg_sync_destroy or ogg_sync_reset.

-- 2.7.4