gosu 0.7.16 → 0.7.17

data/dependencies/libvorbis/doc/xml/07-floor1.xml

@@ -1,450 +0,0 @@
-<?xml version="1.0" standalone="no"?>
-<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-                "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
-
-]>
-
-<section id="vorbis-spec-floor1">
-<sectioninfo>
-<releaseinfo>
- $Id: 07-floor1.xml 10466 2005-11-28 00:34:44Z giles $
-</releaseinfo>
-</sectioninfo>
-<title>Floor type 1 setup and decode</title>
-
-<section>
-<title>Overview</title>
-
-<para>
-Vorbis floor type one uses a piecewise straight-line representation to
-encode a spectral envelope curve. The representation plots this curve
-mechanically on a linear frequency axis and a logarithmic (dB)
-amplitude axis. The integer plotting algorithm used is similar to
-Bresenham's algorithm.</para>
-
-</section>
-
-<section>
-<title>Floor 1 format</title>
-
-<section><title>model</title>
-
-<para>
-Floor type one represents a spectral curve as a series of
-line segments.  Synthesis constructs a floor curve using iterative
-prediction in a process roughly equivalent to the following simplified
-description:</para>
-
-<para>
-<itemizedlist>
- <listitem><simpara> the first line segment (base case) is a logical line spanning
-from x_0,y_0 to x_1,y_1 where in the base case x_0=0 and x_1=[n], the
-full range of the spectral floor to be computed.</simpara></listitem>
-
-<listitem><simpara>the induction step chooses a point x_new within an existing
-logical line segment and produces a y_new value at that point computed
-from the existing line's y value at x_new (as plotted by the line) and
-a difference value decoded from the bitstream packet.</simpara></listitem>
-
-<listitem><simpara>floor computation produces two new line segments, one running from
-x_0,y_0 to x_new,y_new and from x_new,y_new to x_1,y_1. This step is
-performed logically even if y_new represents no change to the
-amplitude value at x_new so that later refinement is additionally
-bounded at x_new.</simpara></listitem>
-
-<listitem><simpara>the induction step repeats, using a list of x values specified in
-the codec setup header at floor 1 initialization time.  Computation
-is completed at the end of the x value list.</simpara></listitem>
-
-</itemizedlist>
-</para>
-
-<para>
-Consider the following example, with values chosen for ease of
-understanding rather than representing typical configuration:</para>
-
-<para>
-For the below example, we assume a floor setup with an [n] of 128.
-The list of selected X values in increasing order is
-0,16,32,48,64,80,96,112 and 128.  In list order, the values interleave
-as 0, 128, 64, 32, 96, 16, 48, 80 and 112.  The corresponding
-list-order Y values as decoded from an example packet are 110, 20, -5,
--45, 0, -25, -10, 30 and -10.  We compute the floor in the following
-way, beginning with the first line:</para>
-
-<mediaobject>
-<imageobject>
- <imagedata fileref="floor1-1.png" format="PNG"/>
-</imageobject>
-<textobject>
- <phrase>[graph of example floor]</phrase>
-</textobject>
-</mediaobject>
-
-<para>
-We now draw new logical lines to reflect the correction to new_Y, and
-iterate for X positions 32 and 96:</para>
-
-<mediaobject>
-<imageobject>
- <imagedata fileref="floor1-2.png" format="PNG"/> 
- </imageobject>
- <textobject>
-  <phrase>[graph of example floor]</phrase>
- </textobject>
-</mediaobject>
-  
-<para>
-Although the new Y value at X position 96 is unchanged, it is still
-used later as an endpoint for further refinement.  From here on, the
-pattern should be clear; we complete the floor computation as follows:</para>
-
-<mediaobject>
-<imageobject>
- <imagedata fileref="floor1-3.png" format="PNG"/> 
- </imageobject>
- <textobject>
-  <phrase>[graph of example floor]</phrase>
- </textobject>
-</mediaobject>
-  
-<mediaobject>
-<imageobject>
- <imagedata fileref="floor1-4.png" format="PNG"/> 
- </imageobject>
- <textobject>
-  <phrase>[graph of example floor]</phrase>
- </textobject>
-</mediaobject>
-  
-
-<para>
-A more efficient algorithm with carefully defined integer rounding
-behavior is used for actual decode, as described later.  The actual
-algorithm splits Y value computation and line plotting into two steps
-with modifications to the above algorithm to eliminate noise
-accumulation through integer roundoff/truncation. </para>
-
-</section>
-
-<section><title>header decode</title>
-
-<para>
-A list of floor X values is stored in the packet header in interleaved
-format (used in list order during packet decode and synthesis).  This
-list is split into partitions, and each partition is assigned to a
-partition class.  X positions 0 and [n] are implicit and do not belong
-to an explicit partition or partition class.</para>
-
-<para>
-A partition class consists of a representation vector width (the
-number of Y values which the partition class encodes at once), a
-'subclass' value representing the number of alternate entropy books
-the partition class may use in representing Y values, the list of
-[subclass] books and a master book used to encode which alternate
-books were chosen for representation in a given packet.  The
-master/subclass mechanism is meant to be used as a flexible
-representation cascade while still using codebooks only in a scalar
-context.</para>
-
-<screen>
-
-  1) [floor1_partitions] = read 5 bits as unsigned integer
-  2) [maximum_class] = -1
-  3) iterate [i] over the range 0 ... [floor1_partitions]-1 {
-       
-        4) vector [floor1_partition_class_list] element [i] = read 4 bits as unsigned integer
-
-     }
-
-  5) [maximum_class] = largest integer scalar value in vector [floor1_partition_class_list]
-  6) iterate [i] over the range 0 ... [maximum_class] {
-
-        7) vector [floor1_class_dimensions] element [i] = read 3 bits as unsigned integer and add 1
-	8) vector [floor1_class_subclasses] element [i] = read 2 bits as unsigned integer
-        9) if ( vector [floor1_class_subclasses] element [i] is nonzero ) {
-            
-             10) vector [floor1_class_masterbooks] element [i] = read 8 bits as unsigned integer
-           
-           }
-
-       11) iterate [j] over the range 0 ... (2 exponent [floor1_class_subclasses] element [i]) - 1  {
-
-             12) array [floor1_subclass_books] element [i],[j] = 
-                 read 8 bits as unsigned integer and subtract one
-           }
-      }
-
- 13) [floor1_multiplier] = read 2 bits as unsigned integer and add one
- 14) [rangebits] = read 4 bits as unsigned integer
- 15) vector [floor1_X_list] element [0] = 0
- 16) vector [floor1_X_list] element [1] = 2 exponent [rangebits];
- 17) [floor1_values] = 2
- 18) iterate [i] over the range 0 ... [floor1_partitions]-1 {
-
-       19) [current_class_number] = vector [floor1_partition_class_list] element [i]
-       20) iterate [j] over the range 0 ... ([floor1_class_dimensions] element [current_class_number])-1 {
-             21) vector [floor1_X_list] element ([floor1_values]) = 
-                 read [rangebits] bits as unsigned integer
-             22) increment [floor1_values] by one
-           }
-     }
- 
- 23) done
-</screen>
-
-<para>
-An end-of-packet condition while reading any aspect of a floor 1
-configuration during setup renders a stream undecodable.  In
-addition, a <varname>[floor1_class_masterbooks]</varname> or
-<varname>[floor1_subclass_books]</varname> scalar element greater than the
-highest numbered codebook configured in this stream is an error
-condition that renders the stream undecodable.</para>
-
-<section id="vorbis-spec-floor1-decode">
-<title>packet decode</title>
-
-<para>
-Packet decode begins by checking the <varname>[nonzero]</varname> flag:</para>
-
-<screen>
-  1) [nonzero] = read 1 bit as boolean
-</screen>
-
-<para>
-If <varname>[nonzero]</varname> is unset, that indicates this channel contained
-no audio energy in this frame.  Decode immediately returns a status
-indicating this floor curve (and thus this channel) is unused this
-frame.  (A return status of 'unused' is different from decoding a
-floor that has all points set to minimum representation amplitude,
-which happens to be approximately -140dB).
-</para>
-
-<para>
-Assuming <varname>[nonzero]</varname> is set, decode proceeds as follows:</para>
-
-<screen>
-  1) [range] = vector { 256, 128, 86, 64 } element ([floor1_multiplier]-1)
-  2) vector [floor1_Y] element [0] = read <link linkend="vorbis-spec-ilog">ilog</link>([range]-1) bits as unsigned integer
-  3) vector [floor1_Y] element [1] = read <link linkend="vorbis-spec-ilog">ilog</link>([range]-1) bits as unsigned integer
-  4) [offset] = 2;
-  5) iterate [i] over the range 0 ... [floor1_partitions]-1 {
-
-       6) [class] = vector [floor1_partition_class]  element [i]
-       7) [cdim]  = vector [floor1_class_dimensions] element [class]
-       8) [cbits] = vector [floor1_class_subclasses] element [class]
-       9) [csub]  = (2 exponent [cbits])-1
-      10) [cval]  = 0
-      11) if ( [cbits] is greater than zero ) {
- 
-             12) [cval] = read from packet using codebook number
-                 (vector [floor1_class_masterbooks] element [class]) in scalar context
-          }
-      
-      13) iterate [j] over the range 0 ... [cdim]-1 {
-       
-             14) [book] = array [floor1_subclass_books] element [class],([cval] bitwise AND [csub])
-             15) [cval] = [cval] right shifted [cbits] bits
-	     16) if ( [book] is not less than zero ) {
-	     
-	           17) vector [floor1_Y] element ([j]+[offset]) = read from packet using codebook 
-                       [book] in scalar context
-
-                 } else [book] is less than zero {
-
-	           18) vector [floor1_Y] element ([j]+[offset]) = 0
-
-                 }
-          }
-             
-      19) [offset] = [offset] + [cdim]
-         
-     }
-  
- 20) done
-</screen>
-
-<para>
-An end-of-packet condition during curve decode should be considered a
-nominal occurrence; if end-of-packet is reached during any read
-operation above, floor decode is to return 'unused' status as if the
-<varname>[nonzero]</varname> flag had been unset at the beginning of decode.
-</para>
-
-<para>
-Vector <varname>[floor1_Y]</varname> contains the values from packet decode
-needed for floor 1 synthesis.</para>
-
-</section>
-
-<section id="vorbis-spec-floor1-synth">
-<title>curve computation</title>
-
-<para>
-Curve computation is split into two logical steps; the first step
-derives final Y amplitude values from the encoded, wrapped difference
-values taken from the bitstream.  The second step plots the curve
-lines.  Also, although zero-difference values are used in the
-iterative prediction to find final Y values, these points are
-conditionally skipped during final line computation in step two.
-Skipping zero-difference values allows a smoother line fit.  </para>
-
-<para>
-Although some aspects of the below algorithm look like inconsequential
-optimizations, implementors are warned to follow the details closely.
-Deviation from implementing a strictly equivalent algorithm can result
-in serious decoding errors.</para>
-
-<section>
-<title>step 1: amplitude value synthesis</title>
-
-<para>
-Unwrap the always-positive-or-zero values read from the packet into
-+/- difference values, then apply to line prediction.</para>
-
-<screen>
-  1) [range] = vector { 256, 128, 86, 64 } element ([floor1_multiplier]-1)
-  2) vector [floor1_step2_flag] element [0] = set
-  3) vector [floor1_step2_flag] element [1] = set
-  4) vector [floor1_final_Y] element [0] = vector [floor1_Y] element [0]
-  5) vector [floor1_final_Y] element [1] = vector [floor1_Y] element [1]
-  6) iterate [i] over the range 2 ... [floor1_values]-1 {
-    
-       7) [low_neighbor_offset] = <link linkend="vorbis-spec-low_neighbor">low_neighbor</link>([floor1_X_list],[i])
-       8) [high_neighbor_offset] = <link linkend="vorbis-spec-high_neighbor">high_neighbor</link>([floor1_X_list],[i])
-
-       9) [predicted] = <link linkend="vorbis-spec-render_point">render_point</link>( vector [floor1_X_list] element [low_neighbor_offset],
-				      vector [floor1_final_Y] element [low_neighbor_offset],
-                                      vector [floor1_X_list] element [high_neighbor_offset],
-				      vector [floor1_final_Y] element [high_neighbor_offset],
-                                      vector [floor1_X_list] element [i] )
-
-      10) [val] = vector [floor1_Y] element [i]
-      11) [highroom] = [range] - [predicted]
-      12) [lowroom]  = [predicted]
-      13) if ( [highroom] is less than [lowroom] ) {
-
-            14) [room] = [highroom] * 2
-         
-          } else [highroom] is not less than [lowroom] {
-		      
-            15) [room] = [lowroom] * 2
-        
-          }
-
-      16) if ( [val] is nonzero ) {
-
-            17) vector [floor1_step2_flag] element [low_neighbor_offset] = set
-            18) vector [floor1_step2_flag] element [high_neighbor_offset] = set
-            19) vector [floor1_step2_flag] element [i] = set
-            20) if ( [val] is greater than or equal to [room] ) {
- 
-                  21) if ( [highroom] is greater than [lowroom] ) {
-
-                        22) vector [floor1_final_Y] element [i] = [val] - [lowroom] + [predicted]
-		     
-		      } else [highroom] is not greater than [lowroom] {
-              
-                        23) vector [floor1_final_Y] element [i] = [predicted] - [val] + [highroom] - 1
-                   
-                      }
-               
-                } else [val] is less than [room] {
-		 
-		  24) if ([val] is odd) {
-                 
-                        25) vector [floor1_final_Y] element [i] = 
-                            [predicted] - (([val] + 1) divided by  2 using integer division)
-
-                      } else [val] is even {
-
-                        26) vector [floor1_final_Y] element [i] = 
-                            [predicted] + ([val] / 2 using integer division)
-                          
-                      }
-
-                }      
-
-          } else [val] is zero {
-
-            27) vector [floor1_step2_flag] element [i] = unset
-            28) vector [floor1_final_Y] element [i] = [predicted]
-
-          }
-
-     }
-
- 29) done
-
-</screen>
-
-</section>
-
-<section>
-<title>step 2: curve synthesis</title>
-
-<para>
-Curve synthesis generates a return vector <varname>[floor]</varname> of length
-<varname>[n]</varname> (where <varname>[n]</varname> is provided by the decode process
-calling to floor decode).  Floor 1 curve synthesis makes use of the
-<varname>[floor1_X_list]</varname>, <varname>[floor1_final_Y]</varname> and
-<varname>[floor1_step2_flag]</varname> vectors, as well as [floor1_multiplier]
-and [floor1_values] values.</para>
-
-<para>
-Decode begins by sorting the scalars from vectors
-<varname>[floor1_X_list]</varname>, <varname>[floor1_final_Y]</varname> and
-<varname>[floor1_step2_flag]</varname> together into new vectors
-<varname>[floor1_X_list]'</varname>, <varname>[floor1_final_Y]'</varname> and
-<varname>[floor1_step2_flag]'</varname> according to ascending sort order of the
-values in <varname>[floor1_X_list]</varname>.  That is, sort the values of
-<varname>[floor1_X_list]</varname> and then apply the same permutation to
-elements of the other two vectors so that the X, Y and step2_flag
-values still match.</para>
-
-<para>
-Then compute the final curve in one pass:</para>
-
-<screen>
-  1) [hx] = 0
-  2) [lx] = 0
-  3) [ly] = vector [floor1_final_Y]' element [0] * [floor1_multiplier]
-  4) iterate [i] over the range 1 ... [floor1_values]-1 {
-
-       5) if ( [floor1_step2_flag]' element [i] is set ) {
-
-             6) [hy] = [floor1_final_Y]' element [i] * [floor1_multiplier]
- 	     7) [hx] = [floor1_X_list]' element [i]
-             8) <link linkend="vorbis-spec-render_line">render_line</link>( [lx], [ly], [hx], [hy], [floor] )
-             9) [lx] = [hx]
-	    10) [ly] = [hy]
-          }
-     }
- 
- 11) if ( [hx] is less than [n] ) {
-
-        12) <link linkend="vorbis-spec-render_line">render_line</link>( [hx], [hy], [n], [hy], [floor] )
-
-     }
-
- 13) if ( [hx] is greater than [n] ) {
-
-            14) truncate vector [floor] to [n] elements
-
-     }
- 
- 15) for each scalar in vector [floor], perform a lookup substitution using 
-     the scalar value from [floor] as an offset into the vector <link linkend="vorbis-spec-floor1_inverse_dB_table">[floor1_inverse_dB_static_table]</link>
-
- 16) done
-
-</screen>
-
-</section>
-
-</section>
-
-</section>
-</section>
-</section>
-

data/dependencies/libvorbis/doc/xml/08-residue.xml

@@ -1,492 +0,0 @@
-<?xml version="1.0" standalone="no"?>
-<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-                "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
-
-]>
-
-<section id="vorbis-spec-residue">
-<sectioninfo>
- <releaseinfo>
-  $Id: 08-residue.xml 13159 2007-06-21 05:22:35Z xiphmont $
- </releaseinfo>
-</sectioninfo>
-<title>Residue setup and decode</title>
-
-
-<section>
-<title>Overview</title>
-
-<para>
-A residue vector represents the fine detail of the audio spectrum of
-one channel in an audio frame after the encoder subtracts the floor
-curve and performs any channel coupling.  A residue vector may
-represent spectral lines, spectral magnitude, spectral phase or
-hybrids as mixed by channel coupling.  The exact semantic content of
-the vector does not matter to the residue abstraction.</para>
-
-<para>
-Whatever the exact qualities, the Vorbis residue abstraction codes the
-residue vectors into the bitstream packet, and then reconstructs the
-vectors during decode.  Vorbis makes use of three different encoding
-variants (numbered 0, 1 and 2) of the same basic vector encoding
-abstraction.</para>
-
-</section>
-
-<section>
-<title>Residue format</title>
-
-<para>
-Residue format partitions each vector in the vector bundle into chunks,
-classifies each chunk, encodes the chunk classifications and finally
-encodes the chunks themselves using the the specific VQ arrangement
-defined for each selected classification.
-The exact interleaving and partitioning vary by residue encoding number,
-however the high-level process used to classify and encode the residue 
-vector is the same in all three variants.</para>
-
-<para>
-A set of coded residue vectors are all of the same length.  High level
-coding structure, ignoring for the moment exactly how a partition is
-encoded and simply trusting that it is, is as follows:</para>
-
-<para>
-<itemizedlist>
-<listitem><para>Each vector is partitioned into multiple equal sized chunks
-according to configuration specified.  If we have a vector size of
-<emphasis>n</emphasis>, a partition size <emphasis>residue_partition_size</emphasis>, and a total
-of <emphasis>ch</emphasis> residue vectors, the total number of partitioned chunks
-coded is <emphasis>n</emphasis>/<emphasis>residue_partition_size</emphasis>*<emphasis>ch</emphasis>.  It is
-important to note that the integer division truncates.  In the below
-example, we assume an example <emphasis>residue_partition_size</emphasis> of 8.</para></listitem>
-
-<listitem><para>Each partition in each vector has a classification number that
-specifies which of multiple configured VQ codebook setups are used to
-decode that partition.  The classification numbers of each partition
-can be thought of as forming a vector in their own right, as in the
-illustration below.  Just as the residue vectors are coded in grouped
-partitions to increase encoding efficiency, the classification vector
-is also partitioned into chunks.  The integer elements of each scalar
-in a classification chunk are built into a single scalar that
-represents the classification numbers in that chunk.  In the below
-example, the classification codeword encodes two classification
-numbers.</para></listitem>
-
-<listitem><para>The values in a residue vector may be encoded monolithically in a
-single pass through the residue vector, but more often efficient
-codebook design dictates that each vector is encoded as the additive
-sum of several passes through the residue vector using more than one
-VQ codebook.  Thus, each residue value potentially accumulates values
-from multiple decode passes.  The classification value associated with
-a partition is the same in each pass, thus the classification codeword
-is coded only in the first pass.</para></listitem>
-
-</itemizedlist>
-</para>
-
-<mediaobject>
-<imageobject>
- <imagedata fileref="residue-pack.png" format="PNG"/>
-</imageobject>
-<textobject>
- <phrase>[illustration of residue vector format]</phrase>
-</textobject>
-</mediaobject>
-
-</section>
-
-<section><title>residue 0</title>
-
-<para>
-Residue 0 and 1 differ only in the way the values within a residue
-partition are interleaved during partition encoding (visually treated
-as a black box--or cyan box or brown box--in the above figure).</para>
-
-<para>
-Residue encoding 0 interleaves VQ encoding according to the
-dimension of the codebook used to encode a partition in a specific
-pass.  The dimension of the codebook need not be the same in multiple
-passes, however the partition size must be an even multiple of the
-codebook dimension.</para>
-
-<para>
-As an example, assume a partition vector of size eight, to be encoded
-by residue 0 using codebook sizes of 8, 4, 2 and 1:</para>
-
-<programlisting>
-
-            original residue vector: [ 0 1 2 3 4 5 6 7 ]
-
-codebook dimensions = 8  encoded as: [ 0 1 2 3 4 5 6 7 ]
-
-codebook dimensions = 4  encoded as: [ 0 2 4 6 ], [ 1 3 5 7 ]
-
-codebook dimensions = 2  encoded as: [ 0 4 ], [ 1 5 ], [ 2 6 ], [ 3 7 ]
-
-codebook dimensions = 1  encoded as: [ 0 ], [ 1 ], [ 2 ], [ 3 ], [ 4 ], [ 5 ], [ 6 ], [ 7 ]
-
-</programlisting>
-
-<para>
-It is worth mentioning at this point that no configurable value in the
-residue coding setup is restricted to a power of two.</para>
-
-</section>
-
-<section><title>residue 1</title>
-
-<para>
-Residue 1 does not interleave VQ encoding.  It represents partition
-vector scalars in order.  As with residue 0, however, partition length
-must be an integer multiple of the codebook dimension, although
-dimension may vary from pass to pass.</para>
-
-<para>
-As an example, assume a partition vector of size eight, to be encoded
-by residue 0 using codebook sizes of 8, 4, 2 and 1:</para>
-
-<programlisting>
-
-            original residue vector: [ 0 1 2 3 4 5 6 7 ]
-
-codebook dimensions = 8  encoded as: [ 0 1 2 3 4 5 6 7 ]
-
-codebook dimensions = 4  encoded as: [ 0 1 2 3 ], [ 4 5 6 7 ]
-
-codebook dimensions = 2  encoded as: [ 0 1 ], [ 2 3 ], [ 4 5 ], [ 6 7 ]
-
-codebook dimensions = 1  encoded as: [ 0 ], [ 1 ], [ 2 ], [ 3 ], [ 4 ], [ 5 ], [ 6 ], [ 7 ]
-
-</programlisting>
-
-</section>
-
-<section><title>residue 2</title>
-
-<para>
-Residue type two can be thought of as a variant of residue type 1.
-Rather than encoding multiple passed-in vectors as in residue type 1,
-the <emphasis>ch</emphasis> passed in vectors of length <emphasis>n</emphasis> are first
-interleaved and flattened into a single vector of length
-<emphasis>ch</emphasis>*<emphasis>n</emphasis>.  Encoding then proceeds as in type 1. Decoding is
-as in type 1 with decode interleave reversed. If operating on a single
-vector to begin with, residue type 1 and type 2 are equivalent.</para>
-
-<mediaobject>
-<imageobject>
- <imagedata fileref="residue2.png" format="PNG"/>
-</imageobject>
-<textobject>
- <phrase>[illustration of residue type 2]</phrase>
-</textobject>
-</mediaobject>
-
-</section>
-
-<section>
-<title>Residue decode</title>
-
-<section><title>header decode</title>
-
-<para>
-Header decode for all three residue types is identical.</para>
-<programlisting>
-  1) [residue_begin] = read 24 bits as unsigned integer
-  2) [residue_end] = read 24 bits as unsigned integer
-  3) [residue_partition_size] = read 24 bits as unsigned integer and add one
-  4) [residue_classifications] = read 6 bits as unsigned integer and add one
-  5) [residue_classbook] = read 8 bits as unsigned integer
-</programlisting>
-
-<para>
-<varname>[residue_begin]</varname> and <varname>[residue_end]</varname> select the specific
-sub-portion of each vector that is actually coded; it implements akin
-to a bandpass where, for coding purposes, the vector effectively
-begins at element <varname>[residue_begin]</varname> and ends at
-<varname>[residue_end]</varname>.  Preceding and following values in the unpacked
-vectors are zeroed.  Note that for residue type 2, these values as
-well as <varname>[residue_partition_size]</varname>apply to the interleaved
-vector, not the individual vectors before interleave.
-<varname>[residue_partition_size]</varname> is as explained above,
-<varname>[residue_classifications]</varname> is the number of possible
-classification to which a partition can belong and
-<varname>[residue_classbook]</varname> is the codebook number used to code
-classification codewords.  The number of dimensions in book
-<varname>[residue_classbook]</varname> determines how many classification values
-are grouped into a single classification codeword.</para>
-
-<para>
-Next we read a bitmap pattern that specifies which partition classes
-code values in which passes.</para>
-
-<programlisting>
-  1) iterate [i] over the range 0 ... [residue_classifications]-1 {
-  
-       2) [high_bits] = 0
-       3) [low_bits] = read 3 bits as unsigned integer
-       4) [bitflag] = read one bit as boolean
-       5) if ( [bitflag] is set ) then [high_bits] = read five bits as unsigned integer
-       6) vector [residue_cascade] element [i] = [high_bits] * 8 + [low_bits]
-     }
-  7) done
-</programlisting>
-
-<para>
-Finally, we read in a list of book numbers, each corresponding to
-specific bit set in the cascade bitmap.  We loop over the possible
-codebook classifications and the maximum possible number of encoding
-stages (8 in Vorbis I, as constrained by the elements of the cascade
-bitmap being eight bits):</para>
-
-<programlisting>
-  1) iterate [i] over the range 0 ... [residue_classifications]-1 {
-  
-       2) iterate [j] over the range 0 ... 7 {
-  
-            3) if ( vector [residue_cascade] element [i] bit [j] is set ) {
-
-                 4) array [residue_books] element [i][j] = read 8 bits as unsigned integer
-
-               } else {
-
-                 5) array [residue_books] element [i][j] = unused
-
-               }
-          }
-      }
-
-  6) done
-</programlisting>
-
-<para>
-An end-of-packet condition at any point in header decode renders the
-stream undecodable.  In addition, any codebook number greater than the
-maximum numbered codebook set up in this stream also renders the
-stream undecodable.</para>
-
-</section>
-
-<section><title>packet decode</title>
-
-<para>
-Format 0 and 1 packet decode is identical except for specific
-partition interleave.  Format 2 packet decode can be built out of the
-format 1 decode process.  Thus we describe first the decode
-infrastructure identical to all three formats.</para>
-
-<para>
-In addition to configuration information, the residue decode process
-is passed the number of vectors in the submap bundle and a vector of
-flags indicating if any of the vectors are not to be decoded.  If the
-passed in number of vectors is 3 and vector number 1 is marked 'do not
-decode', decode skips vector 1 during the decode loop.  However, even
-'do not decode' vectors are allocated and zeroed.</para>
-
-<para>
-Depending on the values of <varname>[residue_begin]</varname> and
-<varname>[residue_end]</varname>, it is obvious that the encoded
-portion of a residue vector may be the entire possible residue vector
-or some other strict subset of the actual residue vector size with
-zero padding at either uncoded end.  However, it is also possible to
-set <varname>[residue_begin]</varname> and
-<varname>[residue_end]</varname> to specify a range partially or
-wholly beyond the maximum vector size.  Before beginning residue
-decode, limit <varname>[residue_begin]</varname> and
-<varname>[residue_end]</varname> to the maximum possible vector size
-as follows.  We assume that the number of vectors being encoded,
-<varname>[ch]</varname> is provided by the higher level decoding
-process.</para>
-
-<programlisting>
-  1) [actual_size] = current blocksize/2;
-  2) if residue encoding is format 2
-       3) [actual_size] = [actual_size] * [ch];
-  4) [limit_residue_begin] = maximum of ([residue_begin],[actual_size]);
-  5) [limit_residue_end] = maximum of ([residue_end],[actual_size]);
-</programlisting>
-
-<para>
-The following convenience values are conceptually useful to clarifying
-the decode process:</para>
-
-<programlisting>
-  1) [classwords_per_codeword] = [codebook_dimensions] value of codebook [residue_classbook]
-  2) [n_to_read] = [limit_residue_end] - [limit_residue_begin]
-  3) [partitions_to_read] = [n_to_read] / [residue_partition_size]
-</programlisting>
-
-<para>
-Packet decode proceeds as follows, matching the description offered earlier in the document. </para>
-<programlisting>
-  1) allocate and zero all vectors that will be returned.
-  2) if ([n_to_read] is zero), stop; there is no residue to decode.
-  3) iterate [pass] over the range 0 ... 7 {
-
-       4) [partition_count] = 0
-
-       5) while [partition_count] is less than [partitions_to_read]
-
-            6) if ([pass] is zero) {
-     
-                 7) iterate [j] over the range 0 .. [ch]-1 {
-
-                      8) if vector [j] is not marked 'do not decode' {
-
-                           9) [temp] = read from packet using codebook [residue_classbook] in scalar context
-                          10) iterate [i] descending over the range [classwords_per_codeword]-1 ... 0 {
-
-                               11) array [classifications] element [j],([i]+[partition_count]) =
-                                   [temp] integer modulo [residue_classifications]
-                               12) [temp] = [temp] / [residue_classifications] using integer division
-
-                              }
-      
-                         }
-            
-                    }
-          
-               }
-
-           13) iterate [i] over the range 0 .. ([classwords_per_codeword] - 1) while [partition_count] 
-               is also less than [partitions_to_read] {
-
-                 14) iterate [j] over the range 0 .. [ch]-1 {
-   
-                      15) if vector [j] is not marked 'do not decode' {
-   
-                           16) [vqclass] = array [classifications] element [j],[partition_count]
-                           17) [vqbook] = array [residue_books] element [vqclass],[pass]
-                           18) if ([vqbook] is not 'unused') {
-   
-                                19) decode partition into output vector number [j], starting at scalar 
-                                    offset [limit_residue_begin]+[partition_count]*[residue_partition_size] using 
-                                    codebook number [vqbook] in VQ context
-                          }
-                     }
-   
-                 20) increment [partition_count] by one
-
-               }
-          }
-     }
- 
- 21) done
-
-</programlisting>
-
-<para>
-An end-of-packet condition during packet decode is to be considered a
-nominal occurrence.  Decode returns the result of vector decode up to
-that point.</para>
-
-</section>
-
-<section><title>format 0 specifics</title>
-
-<para>
-Format zero decodes partitions exactly as described earlier in the
-'Residue Format: residue 0' section.  The following pseudocode
-presents the same algorithm. Assume:</para>
-
-<para>
-<itemizedlist>
-<listitem><simpara> <varname>[n]</varname> is the value in <varname>[residue_partition_size]</varname></simpara></listitem>
-<listitem><simpara><varname>[v]</varname> is the residue vector</simpara></listitem>
-<listitem><simpara><varname>[offset]</varname> is the beginning read offset in [v]</simpara></listitem>
-</itemizedlist>
-</para>
-
-<programlisting>
- 1) [step] = [n] / [codebook_dimensions]
- 2) iterate [i] over the range 0 ... [step]-1 {
-
-      3) vector [entry_temp] = read vector from packet using current codebook in VQ context
-      4) iterate [j] over the range 0 ... [codebook_dimensions]-1 {
-
-           5) vector [v] element ([offset]+[i]+[j]*[step]) =
-	        vector [v] element ([offset]+[i]+[j]*[step]) +
-                vector [entry_temp] element [j]
-
-         }
-
-    }
-
-  6) done
-
-</programlisting>
-
-</section>
-
-<section><title>format 1 specifics</title>
-
-<para>
-Format 1 decodes partitions exactly as described earlier in the
-'Residue Format: residue 1' section.  The following pseudocode
-presents the same algorithm. Assume:</para>
-
-<para>
-<itemizedlist>
-<listitem><simpara> <varname>[n]</varname> is the value in
-<varname>[residue_partition_size]</varname></simpara></listitem>
-<listitem><simpara><varname>[v]</varname> is the residue vector</simpara></listitem>
-<listitem><simpara><varname>[offset]</varname> is the beginning read offset in [v]</simpara></listitem>
-</itemizedlist>
-</para>
-
-<programlisting>
- 1) [i] = 0
- 2) vector [entry_temp] = read vector from packet using current codebook in VQ context
- 3) iterate [j] over the range 0 ... [codebook_dimensions]-1 {
-
-      4) vector [v] element ([offset]+[i]) =
-	  vector [v] element ([offset]+[i]) +
-          vector [entry_temp] element [j]
-      5) increment [i]
-
-    }
- 
-  6) if ( [i] is less than [n] ) continue at step 2
-  7) done
-</programlisting>
-
-</section>
-
-<section><title>format 2 specifics</title>
- 
-<para>
-Format 2 is reducible to format 1.  It may be implemented as an additional step prior to and an additional post-decode step after a normal format 1 decode.
-</para>
-
-<para>
-Format 2 handles 'do not decode' vectors differently than residue 0 or
-1; if all vectors are marked 'do not decode', no decode occurrs.
-However, if at least one vector is to be decoded, all the vectors are
-decoded.  We then request normal format 1 to decode a single vector
-representing all output channels, rather than a vector for each
-channel.  After decode, deinterleave the vector into independent vectors, one for each output channel.  That is:</para>
-
-<orderedlist>
- <listitem><simpara>If all vectors 0 through <emphasis>ch</emphasis>-1 are marked 'do not decode', allocate and clear a single vector <varname>[v]</varname>of length <emphasis>ch*n</emphasis> and skip step 2 below; proceed directly to the post-decode step.</simpara></listitem>
- <listitem><simpara>Rather than performing format 1 decode to produce <emphasis>ch</emphasis> vectors of length <emphasis>n</emphasis> each, call format 1 decode to produce a single vector <varname>[v]</varname> of length <emphasis>ch*n</emphasis>. </simpara></listitem>
- <listitem><para>Post decode: Deinterleave the single vector <varname>[v]</varname> returned by format 1 decode as described above into <emphasis>ch</emphasis> independent vectors, one for each outputchannel, according to:
-  <programlisting>
-  1) iterate [i] over the range 0 ... [n]-1 {
-
-       2) iterate [j] over the range 0 ... [ch]-1 {
-
-            3) output vector number [j] element [i] = vector [v] element ([i] * [ch] + [j])
-
-          }
-     }
-
-  4) done
-  </programlisting>
- </para></listitem>
-</orderedlist>
-
-</section>
-
-</section>
-
-</section>
-