"Fossies" - the Fresh Open Source Software Archive

Member "quicktime4linux-2.3/thirdparty/libvorbis-1.1.1/doc/xml/04-codec.xml" (31 May 2008, 35373 Bytes) of package /linux/privat/old/quicktime4linux-2.3-src.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) XML source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 <?xml version="1.0" standalone="no"?>
    2 <!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
    3                 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
    4 <!ENTITY pi     "&#x03C0;"> <!-- GREEK SMALL LETTER PI -->
    5 ]>
    6 
    7 <section id="vorbis-spec-codec">
    8 <sectioninfo>
    9 <releaseinfo>
   10  $Id: 04-codec.xml 7186 2004-07-20 07:19:25Z xiphmont $
   11 </releaseinfo>
   12 </sectioninfo>
   13 <title>Codec Setup and Packet Decode</title>
   14 
   15 <section>
   16 <title>Overview</title>
   17 
   18 <para>
   19 This document serves as the top-level reference document for the
   20 bit-by-bit decode specification of Vorbis I.  This document assumes a
   21 high-level understanding of the Vorbis decode process, which is
   22 provided in <xref linkend="vorbis-spec-intro"/>.  <xref
   23 linkend="vorbis-spec-bitpacking"/> covers reading and writing bit fields from
   24 and to bitstream packets.</para>
   25 
   26 </section>
   27 
   28 <section>
   29 <title>Header decode and decode setup</title>
   30 
   31 <para>
   32 A Vorbis bitstream begins with three header packets. The header
   33 packets are, in order, the identification header, the comments header,
   34 and the setup header. All are required for decode compliance.  An
   35 end-of-packet condition during decoding the first or third header
   36 packet renders the stream undecodable.  End-of-packet decoding the
   37 comment header is a non-fatal error condition.</para>
   38 
   39 <section><title>Common header decode</title>
   40 
   41 <para>
   42 Each header packet begins with the same header fields.
   43 </para>
   44 
   45 <screen>
   46   1) [packet_type] : 8 bit value
   47   2) 0x76, 0x6f, 0x72, 0x62, 0x69, 0x73: the characters 'v','o','r','b','i','s' as six octets
   48 </screen>
   49 
   50 <para>
   51 Decode continues according to packet type; the identification header
   52 is type 1, the comment header type 3 and the setup header type 5
   53 (these types are all odd as a packet with a leading single bit of '0'
   54 is an audio packet).  The packets must occur in the order of
   55 identification, comment, setup.</para>
   56 
   57 </section>
   58 
   59 <section><title>Identification header</title>
   60 
   61 <para>
   62 The identification header is a short header of only a few fields used
   63 to declare the stream definitively as Vorbis, and provide a few externally
   64 relevant pieces of information about the audio stream. The
   65 identification header is coded as follows:</para>
   66 
   67 <screen>
   68  1) [vorbis_version] = read 32 bits as unsigned integer
   69  2) [audio_channels] = read 8 bit integer as unsigned
   70  3) [audio_sample_rate] = read 32 bits as unsigned integer
   71  4) [bitrate_maximum] = read 32 bits as signed integer
   72  5) [bitrate_nominal] = read 32 bits as signed integer
   73  6) [bitrate_minimum] = read 32 bits as signed integer
   74  7) [blocksize_0] = 2 exponent (read 4 bits as unsigned integer)
   75  8) [blocksize_1] = 2 exponent (read 4 bits as unsigned integer)
   76  9) [framing_flag] = read one bit
   77 </screen>
   78 
   79 <para>
   80 <varname>[vorbis_version]</varname> is to read '0' in order to be compatible
   81 with this document.  Both <varname>[audio_channels]</varname> and
   82 <varname>[audio_sample_rate]</varname> must read greater than zero.  Allowed final
   83 blocksize values are 64, 128, 256, 512, 1024, 2048, 4096 and 8192 in
   84 Vorbis I.  <varname>[blocksize_0]</varname> must be less than or equal to
   85 <varname>[blocksize_1]</varname>.  The framing bit must be nonzero.  Failure to
   86 meet any of these conditions renders a stream undecodable.</para>
   87 
   88 <para>
   89 The bitrate fields above are used only as hints. The nominal bitrate
   90 field especially may be considerably off in purely VBR streams.  The
   91 fields are meaningful only when greater than zero.</para>
   92 
   93 <itemizedlist>
   94   <listitem><simpara>All three fields set to the same value implies a fixed rate, or tightly bounded, nearly fixed-rate bitstream</simpara></listitem>
   95   <listitem><simpara>Only nominal set implies a VBR or ABR stream that averages the nominal bitrate</simpara></listitem>
   96   <listitem><simpara>Maximum and or minimum set implies a VBR bitstream that obeys the bitrate limits</simpara></listitem>
   97   <listitem><simpara>None set indicates the encoder does not care to speculate.</simpara></listitem>
   98 </itemizedlist>
   99 
  100 </section>
  101 
  102 <section><title>Comment header</title>
  103 <para>
  104 Comment header decode and data specification is covered in
  105 <xref linkend="vorbis-spec-comment"/>.</para>
  106 </section>
  107 
  108 <section><title>Setup header</title>
  109 
  110 <para>
  111 Vorbis codec setup is configurable to an extreme degree:
  112 
  113 <mediaobject>
  114 <imageobject>
  115  <imagedata fileref="components.png" format="PNG"/>
  116 </imageobject>
  117 <textobject>
  118  <phrase>[decoder pipeline configuration]</phrase>
  119 </textobject>
  120 </mediaobject>
  121 </para>
  122 
  123 <para>
  124 The setup header contains the bulk of the codec setup information
  125 needed for decode.  The setup header contains, in order, the lists of
  126 codebook configurations, time-domain transform configurations
  127 (placeholders in Vorbis I), floor configurations, residue
  128 configurations, channel mapping configurations and mode
  129 configurations. It finishes with a framing bit of '1'.  Header decode
  130 proceeds in the following order:</para>
  131 
  132 <section><title>Codebooks</title>
  133 
  134 <orderedlist>
  135 <listitem><simpara><varname>[vorbis_codebook_count]</varname> = read eight bits as unsigned integer and add one</simpara></listitem>
  136 <listitem><simpara>Decode <varname>[vorbis_codebook_count]</varname> codebooks in order as defined
  137 in <xref linkend="vorbis-spec-codebook"/>.  Save each configuration, in
  138 order, in an array of
  139 codebook configurations <varname>[vorbis_codebook_configurations]</varname>.</simpara></listitem>
  140 </orderedlist>
  141 
  142 </section>
  143 
  144 <section><title>Time domain transforms</title>
  145 
  146 <para>
  147 These hooks are placeholders in Vorbis I.  Nevertheless, the
  148 configuration placeholder values must be read to maintain bitstream
  149 sync.</para>
  150 
  151 <orderedlist>
  152 <listitem><simpara><varname>[vorbis_time_count]</varname> = read 6 bits as unsigned integer and add one</simpara></listitem>
  153 <listitem><simpara>read <varname>[vorbis_time_count]</varname> 16 bit values; each value should be zero.  If any value is nonzero, this is an error condition and the stream is undecodable.</simpara></listitem>
  154 </orderedlist>
  155 
  156 </section>
  157 
  158 <section><title>Floors</title>
  159 
  160 <para>
  161 Vorbis uses two floor types; header decode is handed to the decode
  162 abstraction of the appropriate type.</para>
  163 
  164 <orderedlist>
  165  <listitem><simpara><varname>[vorbis_floor_count]</varname> = read 6 bits as unsigned integer and add one</simpara></listitem>
  166  <listitem><para>For each <varname>[i]</varname> of <varname>[vorbis_floor_count]</varname> floor numbers:
  167   <orderedlist>
  168    <listitem><simpara>read the floor type: vector <varname>[vorbis_floor_types]</varname> element <varname>[i]</varname> =
  169 read 16 bits as unsigned integer</simpara></listitem>
  170    <listitem><simpara>If the floor type is zero, decode the floor
  171 configuration as defined in <xref linkend="vorbis-spec-floor0"/>; save
  172 this
  173 configuration in slot <varname>[i]</varname> of the floor configuration array <varname>[vorbis_floor_configurations]</varname>.</simpara></listitem>
  174    <listitem><simpara>If the floor type is one,
  175 decode the floor configuration as defined in <xref
  176 linkend="vorbis-spec-floor1"/>; save this configuration in slot <varname>[i]</varname> of the floor configuration array <varname>[vorbis_floor_configurations]</varname>.</simpara></listitem>
  177    <listitem><simpara>If the the floor type is greater than one, this stream is undecodable; ERROR CONDITION</simpara></listitem>
  178   </orderedlist>
  179  </para></listitem>
  180 </orderedlist>
  181 
  182 </section>
  183 
  184 <section><title>Residues</title>
  185 
  186 <para>
  187 Vorbis uses three residue types; header decode of each type is identical.
  188 </para>
  189 
  190 <orderedlist>
  191 <listitem><simpara><varname>[vorbis_residue_count]</varname> = read 6 bits as unsigned integer and add one
  192 </simpara></listitem>
  193 <listitem><para>For each of <varname>[vorbis_residue_count]</varname> residue numbers:
  194  <orderedlist>
  195   <listitem><simpara>read the residue type; vector <varname>[vorbis_residue_types]</varname> element <varname>[i]</varname> = read 16 bits as unsigned integer</simpara></listitem>
  196   <listitem><simpara>If the residue type is zero,
  197 one or two, decode the residue configuration as defined in <xref
  198 linkend="vorbis-spec-residue"/>; save this configuration in slot <varname>[i]</varname> of the residue configuration array <varname>[vorbis_residue_configurations]</varname>.</simpara></listitem>
  199   <listitem><simpara>If the the residue type is greater than two, this stream is undecodable; ERROR CONDITION</simpara></listitem>
  200  </orderedlist>
  201 </para></listitem>
  202 </orderedlist>
  203 
  204 </section>
  205 
  206 <section><title>Mappings</title>
  207 
  208 <para>
  209 Mappings are used to set up specific pipelines for encoding
  210 multichannel audio with varying channel mapping applications. Vorbis I
  211 uses a single mapping type (0), with implicit PCM channel mappings.</para>
  212 
  213 <orderedlist>
  214  <listitem><simpara><varname>[vorbis_mapping_count]</varname> = read 6 bits as unsigned integer and add one</simpara></listitem>
  215  <listitem><para>For each <varname>[i]</varname> of <varname>[vorbis_mapping_count]</varname> mapping numbers:
  216   <orderedlist>
  217    <listitem><simpara>read the mapping type: 16 bits as unsigned integer.  There's no reason to save the mapping type in Vorbis I.</simpara></listitem>
  218    <listitem><simpara>If the mapping type is nonzero, the stream is undecodable</simpara></listitem>
  219    <listitem><para>If the mapping type is zero:
  220     <orderedlist>
  221      <listitem><para>read 1 bit as a boolean flag
  222       <orderedlist>
  223        <listitem><simpara>if set, <varname>[vorbis_mapping_submaps]</varname> = read 4 bits as unsigned integer and add one</simpara></listitem>
  224        <listitem><simpara>if unset, <varname>[vorbis_mapping_submaps]</varname> = 1</simpara></listitem>
  225       </orderedlist>
  226       </para>
  227      </listitem>
  228      <listitem><para>read 1 bit as a boolean flag
  229        <orderedlist>
  230          <listitem><para>if set, square polar channel mapping is in use:
  231            <orderedlist>
  232              <listitem><simpara><varname>[vorbis_mapping_coupling_steps]</varname> = read 8 bits as unsigned integer and add one</simpara></listitem>
  233              <listitem><para>for <varname>[j]</varname> each of <varname>[vorbis_mapping_coupling_steps]</varname> steps:
  234                <orderedlist>
  235                  <listitem><simpara>vector <varname>[vorbis_mapping_magnitude]</varname> element <varname>[j]</varname>= read <link linkend="vorbis-spec-ilog">ilog</link>(<varname>[audio_channels]</varname> - 1) bits as unsigned integer</simpara></listitem>
  236                  <listitem><simpara>vector <varname>[vorbis_mapping_angle]</varname> element <varname>[j]</varname>= read <link linkend="vorbis-spec-ilog">ilog</link>(<varname>[audio_channels]</varname> - 1) bits as unsigned integer</simpara></listitem>
  237                  <listitem><simpara>the numbers read in the above two steps are channel numbers representing the channel to treat as magnitude and the channel to treat as angle, respectively.  If for any coupling step the angle channel number equals the magnitude channel number, the magnitude channel number is greater than <varname>[audio_channels]</varname>-1, or the angle channel is greater than <varname>[audio_channels]</varname>-1, the stream is undecodable.</simpara></listitem>
  238                </orderedlist>
  239                </para>
  240              </listitem>
  241            </orderedlist>
  242            </para>
  243          </listitem>
  244          <listitem><simpara>if unset, <varname>[vorbis_mapping_coupling_steps]</varname> = 0</simpara></listitem>
  245        </orderedlist>
  246        </para>
  247      </listitem>
  248      <listitem><simpara>read 2 bits (reserved field); if the value is nonzero, the stream is undecodable</simpara></listitem>
  249      <listitem><simpara>if <varname>[vorbis_mapping_submaps]</varname> is greater than one, we read channel multiplex settings. For each <varname>[j]</varname> of <varname>[audio_channels]</varname> channels:</simpara>
  250       <orderedlist>
  251        <listitem><simpara>vector <varname>[vorbis_mapping_mux]</varname> element <varname>[j]</varname> = read 4 bits as unsigned integer</simpara></listitem>
  252        <listitem><simpara>if the value is greater than the highest numbered submap (<varname>[vorbis_mapping_submaps]</varname> - 1), this in an error condition rendering the stream undecodable</simpara></listitem>
  253       </orderedlist>
  254      </listitem>
  255      <listitem><simpara>for each submap <varname>[j]</varname> of <varname>[vorbis_mapping_submaps]</varname> submaps, read the floor and residue numbers for use in decoding that submap:</simpara>
  256       <orderedlist>
  257        <listitem><simpara>read and discard 8 bits (the unused time configuration placeholder)</simpara></listitem>
  258        <listitem><simpara>read 8 bits as unsigned integer for the floor number; save in vector <varname>[vorbis_mapping_submap_floor]</varname> element <varname>[j]</varname></simpara></listitem>
  259        <listitem><simpara>verify the floor number is not greater than the highest number floor configured for the bitstream. If it is, the bitstream is undecodable</simpara></listitem>
  260        <listitem><simpara>read 8 bits as unsigned integer for the residue number; save in vector <varname>[vorbis_mapping_submap_residue]</varname> element <varname>[j]</varname></simpara></listitem>
  261        <listitem><simpara>verify the residue number is not greater than the highest number residue configured for the bitstream.  If it is, the bitstream is undecodable</simpara></listitem>
  262       </orderedlist>
  263      </listitem>
  264      <listitem><simpara>save this mapping configuration in slot <varname>[i]</varname> of the mapping configuration array <varname>[vorbis_mapping_configurations]</varname>.</simpara></listitem>
  265     </orderedlist></para>
  266    </listitem>
  267   </orderedlist>
  268  </para></listitem>
  269 </orderedlist>
  270 
  271 </section>
  272 
  273 <section><title>Modes</title>
  274 
  275 <orderedlist>
  276  <listitem><simpara><varname>[vorbis_mode_count]</varname> = read 6 bits as unsigned integer and add one</simpara></listitem>
  277  <listitem><simpara>For each of <varname>[vorbis_mode_count]</varname> mode numbers:</simpara>
  278   <orderedlist>
  279   <listitem><simpara><varname>[vorbis_mode_blockflag]</varname> = read 1 bit</simpara></listitem>
  280   <listitem><simpara><varname>[vorbis_mode_windowtype]</varname> = read 16 bits as unsigned integer</simpara></listitem>
  281   <listitem><simpara><varname>[vorbis_mode_transformtype]</varname> = read 16 bits as unsigned integer</simpara></listitem>
  282   <listitem><simpara><varname>[vorbis_mode_mapping]</varname> = read 8 bits as unsigned integer</simpara></listitem>
  283   <listitem><simpara>verify ranges; zero is the only legal value in Vorbis I for
  284 <varname>[vorbis_mode_windowtype]</varname>
  285 and <varname>[vorbis_mode_transformtype]</varname>.  <varname>[vorbis_mode_mapping]</varname> must not be greater than the highest number mapping in use.  Any illegal values render the stream undecodable.</simpara></listitem>
  286   <listitem><simpara>save this mode configuration in slot <varname>[i]</varname> of the mode configuration array
  287 <varname>[vorbis_mode_configurations]</varname>.</simpara></listitem>
  288  </orderedlist>
  289 </listitem>
  290 <listitem><simpara>read 1 bit as a framing flag.  If unset, a framing error occurred and the stream is not
  291 decodable.</simpara></listitem>
  292 </orderedlist>
  293 
  294 <para>
  295 After reading mode descriptions, setup header decode is complete.
  296 </para>
  297 
  298 </section>
  299 
  300 </section>
  301 
  302 </section>
  303 
  304 <section>
  305 <title>Audio packet decode and synthesis</title>
  306 
  307 <para>
  308 Following the three header packets, all packets in a Vorbis I stream
  309 are audio.  The first step of audio packet decode is to read and
  310 verify the packet type. <emphasis>A non-audio packet when audio is expected
  311 indicates stream corruption or a non-compliant stream. The decoder
  312 must ignore the packet and not attempt decoding it to audio</emphasis>.
  313 </para>
  314 
  315 <section><title>packet type, mode and window decode</title>
  316 
  317 <orderedlist>
  318  <listitem><simpara>read 1 bit <varname>[packet_type]</varname>; check that packet type is 0 (audio)</simpara></listitem>
  319  <listitem><simpara>read <link linkend="vorbis-spec-ilog">ilog</link>([vorbis_mode_count]-1) bits
  320 <varname>[mode_number]</varname></simpara></listitem>
  321  <listitem><simpara>decode blocksize <varname>[n]</varname> is equal to <varname>[blocksize_0]</varname> if 
  322 <varname>[vorbis_mode_blockflag]</varname> is 0, else <varname>[n]</varname> is equal to <varname>[blocksize_1]</varname>.</simpara></listitem>
  323  <listitem><simpara>perform window selection and setup; this window is used later by the inverse MDCT:</simpara>
  324   <orderedlist>
  325    <listitem><simpara>if this is a long window (the <varname>[vorbis_mode_blockflag]</varname> flag of this mode is
  326 set):</simpara>
  327     <orderedlist>
  328      <listitem><simpara>read 1 bit for <varname>[previous_window_flag]</varname></simpara></listitem>
  329      <listitem><simpara>read 1 bit for <varname>[next_window_flag]</varname></simpara></listitem>
  330      <listitem><simpara>if <varname>[previous_window_flag]</varname> is not set, the left half
  331          of the window will be a hybrid window for lapping with a
  332          short block.  See <xref
  333 linkend="vorbis-spec-window"/> for an illustration of overlapping
  334 dissimilar
  335          windows. Else, the left half window will have normal long
  336          shape.</simpara></listitem>
  337      <listitem><simpara>if <varname>[next_window_flag]</varname> is not set, the right half of
  338          the window will be a hybrid window for lapping with a short
  339          block.  See <xref linkend="vorbis-spec-window"/> for an
  340 illustration of overlapping dissimilar
  341          windows. Else, the left right window will have normal long
  342          shape.</simpara></listitem>
  343     </orderedlist>
  344    </listitem>
  345    <listitem><simpara> if this is a short window, the window is always the same 
  346        short-window shape.</simpara></listitem>
  347   </orderedlist>
  348  </listitem>
  349 </orderedlist>
  350 
  351 <para>
  352 Vorbis windows all use the slope function y=sin(0.5 * &pi; * sin^2((x+.5)/n * &pi;)),
  353 where n is window size and x ranges 0...n-1, but dissimilar
  354 lapping requirements can affect overall shape.  Window generation
  355 proceeds as follows:</para>
  356 
  357 <orderedlist>
  358  <listitem><simpara> <varname>[window_center]</varname> = <varname>[n]</varname> / 2</simpara></listitem>
  359  <listitem><para> if (<varname>[vorbis_mode_blockflag]</varname> is set and <varname>[previous_window_flag]</varname> is
  360 not set) then
  361   <orderedlist>
  362    <listitem><simpara><varname>[left_window_start]</varname> = <varname>[n]</varname>/4 -
  363 <varname>[blocksize_0]</varname>/4</simpara></listitem>
  364    <listitem><simpara><varname>[left_window_end]</varname> = <varname>[n]</varname>/4 + <varname>[blocksize_0]</varname>/4</simpara></listitem>
  365    <listitem><simpara><varname>[left_n]</varname> = <varname>[blocksize_0]</varname>/2</simpara></listitem>
  366   </orderedlist>
  367  else
  368   <orderedlist>
  369    <listitem><simpara><varname>[left_window_start]</varname> = 0</simpara></listitem>
  370    <listitem><simpara><varname>[left_window_end]</varname> = <varname>[window_center]</varname></simpara></listitem>
  371    <listitem><simpara><varname>[left_n]</varname> = <varname>[n]</varname>/2</simpara></listitem>
  372   </orderedlist></para>
  373  </listitem>
  374  <listitem><para> if (<varname>[vorbis_mode_blockflag]</varname> is set and <varname>[next_window_flag]</varname> is not
  375 set) then 
  376   <orderedlist>
  377    <listitem><simpara><varname>[right_window_start]</varname> = <varname>[n]*3</varname>/4 -
  378 <varname>[blocksize_0]</varname>/4</simpara></listitem>
  379    <listitem><simpara><varname>[right_window_end]</varname> = <varname>[n]*3</varname>/4 +
  380 <varname>[blocksize_0]</varname>/4</simpara></listitem>
  381    <listitem><simpara><varname>[right_n]</varname> = <varname>[blocksize_0]</varname>/2</simpara></listitem>
  382   </orderedlist>
  383  else
  384   <orderedlist>
  385    <listitem><simpara><varname>[right_window_start]</varname> = <varname>[window_center]</varname></simpara></listitem>
  386    <listitem><simpara><varname>[right_window_end]</varname> = <varname>[n]</varname></simpara></listitem>
  387    <listitem><simpara><varname>[right_n]</varname> = <varname>[n]</varname>/2</simpara></listitem>
  388   </orderedlist></para>
  389  </listitem>
  390  <listitem><simpara> window from range 0 ... <varname>[left_window_start]</varname>-1 inclusive is zero</simpara></listitem>
  391  <listitem><simpara> for <varname>[i]</varname> in range <varname>[left_window_start]</varname> ...
  392 <varname>[left_window_end]</varname>-1, window(<varname>[i]</varname>) = sin(.5 * &pi; * sin^2( (<varname>[i]</varname>-<varname>[left_window_start]</varname>+.5) / <varname>[left_n]</varname> * .5 * &pi;) )</simpara></listitem>
  393  <listitem><simpara> window from range <varname>[left_window_end]</varname> ... <varname>[right_window_start]</varname>-1
  394 inclusive is one</simpara></listitem><listitem><simpara> for <varname>[i]</varname> in range <varname>[right_window_start]</varname> ... <varname>[right_window_end]</varname>-1, window(<varname>[i]</varname>) = sin(.5 * &pi; * sin^2( (<varname>[i]</varname>-<varname>[right_window_start]</varname>+.5) / <varname>[right_n]</varname> * .5 * &pi; + .5 * &pi;) )</simpara></listitem>
  395 <listitem><simpara> window from range <varname>[right_window_start]</varname> ... <varname>[n]</varname>-1 is
  396 zero</simpara></listitem>
  397 </orderedlist>
  398 
  399 <para>
  400 An end-of-packet condition up to this point should be considered an
  401 error that discards this packet from the stream.  An end of packet
  402 condition past this point is to be considered a possible nominal
  403 occurrence.</para>
  404 
  405 </section>
  406 
  407 <section><title>floor curve decode</title>
  408 
  409 <para>
  410 From this point on, we assume out decode context is using mode number
  411 <varname>[mode_number]</varname> from configuration array
  412 <varname>[vorbis_mode_configurations]</varname> and the map number
  413 <varname>[vorbis_mode_mapping]</varname> (specified by the current mode) taken
  414 from the mapping configuration array
  415 <varname>[vorbis_mapping_configurations]</varname>.</para>
  416 
  417 <para>
  418 Floor curves are decoded one-by-one in channel order.</para>
  419 
  420 <para>
  421 For each floor <varname>[i]</varname> of <varname>[audio_channels]</varname>
  422  <orderedlist>
  423   <listitem><simpara><varname>[submap_number]</varname> = element <varname>[i]</varname> of vector [vorbis_mapping_mux]</simpara></listitem>
  424   <listitem><simpara><varname>[floor_number]</varname> = element <varname>[submap_number]</varname> of vector
  425 [vorbis_submap_floor]</simpara></listitem>
  426   <listitem><simpara>if the floor type of this
  427 floor (vector <varname>[vorbis_floor_types]</varname> element
  428 <varname>[floor_number]</varname>) is zero then decode the floor for
  429 channel <varname>[i]</varname> according to the
  430 <xref linkend="vorbis-spec-floor0-decode"/></simpara></listitem>
  431   <listitem><simpara>if the type of this floor
  432 is one then decode the floor for channel <varname>[i]</varname> according
  433 to the <xref linkend="vorbis-spec-floor1-decode"/></simpara></listitem>
  434   <listitem><simpara>save the needed decoded floor information for channel for later synthesis</simpara></listitem>
  435   <listitem><simpara>if the decoded floor returned 'unused', set vector <varname>[no_residue]</varname> element
  436 <varname>[i]</varname> to true, else set vector <varname>[no_residue]</varname> element <varname>[i]</varname> to
  437 false</simpara></listitem>
  438  </orderedlist>
  439 </para>
  440 
  441 <para>
  442 An end-of-packet condition during floor decode shall result in packet
  443 decode zeroing all channel output vectors and skipping to the
  444 add/overlap output stage.</para>
  445 
  446 </section>
  447 
  448 <section><title>nonzero vector propagate</title>
  449 
  450 <para>
  451 A possible result of floor decode is that a specific vector is marked
  452 'unused' which indicates that that final output vector is all-zero
  453 values (and the floor is zero).  The residue for that vector is not
  454 coded in the stream, save for one complication.  If some vectors are
  455 used and some are not, channel coupling could result in mixing a
  456 zeroed and nonzeroed vector to produce two nonzeroed vectors.</para>
  457 
  458 <para>
  459 for each <varname>[i]</varname> from 0 ... <varname>[vorbis_mapping_coupling_steps]</varname>-1
  460 
  461 <orderedlist>
  462  <listitem><simpara>if either <varname>[no_residue]</varname> entry for channel
  463 (<varname>[vorbis_mapping_magnitude]</varname> element <varname>[i]</varname>)
  464 or channel
  465 (<varname>[vorbis_mapping_angle]</varname> element <varname>[i]</varname>)
  466 are set to false, then both must be set to false.  Note that an 'unused' 
  467 floor has no decoded floor information; it is important that this is 
  468 remembered at floor curve synthesis time.</simpara></listitem>
  469 </orderedlist>
  470 </para>
  471 
  472 </section>
  473 
  474 <section><title>residue decode</title>
  475 
  476 <para>
  477 Unlike floors, which are decoded in channel order, the residue vectors
  478 are decoded in submap order.</para>
  479 
  480 <para>
  481 for each submap <varname>[i]</varname> in order from 0 ... <varname>[vorbis_mapping_submaps]</varname>-1</para>
  482 
  483 <orderedlist>
  484  <listitem><simpara><varname>[ch]</varname> = 0</simpara></listitem>
  485  <listitem><simpara>for each channel <varname>[j]</varname> in order from 0 ... <varname>[audio_channels]</varname> - 1</simpara>
  486   <orderedlist>
  487    <listitem><simpara>if channel <varname>[j]</varname> in submap <varname>[i]</varname> (vector <varname>[vorbis_mapping_mux]</varname> element <varname>[j]</varname> is equal to <varname>[i]</varname>)</simpara>
  488     <orderedlist>
  489      <listitem><para>if vector <varname>[no_residue]</varname> element <varname>[j]</varname> is true
  490       <orderedlist>
  491        <listitem><simpara>vector <varname>[do_not_decode_flag]</varname> element <varname>[ch]</varname> is set</simpara></listitem>
  492       </orderedlist>
  493      else
  494       <orderedlist>
  495        <listitem><simpara>vector <varname>[do_not_decode_flag]</varname> element <varname>[ch]</varname> is unset</simpara></listitem>
  496       </orderedlist></para>
  497      </listitem>
  498      <listitem><simpara>increment <varname>[ch]</varname></simpara></listitem>
  499     </orderedlist>
  500    </listitem>
  501   </orderedlist>
  502  </listitem><listitem><simpara><varname>[residue_number]</varname> = vector <varname>[vorbis_mapping_submap_residue]</varname> element <varname>[i]</varname></simpara></listitem>
  503  <listitem><simpara><varname>[residue_type]</varname> = vector <varname>[vorbis_residue_types]</varname> element <varname>[residue_number]</varname></simpara></listitem>
  504  <listitem><simpara>decode <varname>[ch]</varname> vectors using residue <varname>[residue_number]</varname>, according to type <varname>[residue_type]</varname>, also passing vector <varname>[do_not_decode_flag]</varname> to indicate which vectors in the bundle should not be decoded. Correct per-vector decode length is <varname>[n]</varname>/2.</simpara></listitem>
  505  <listitem><simpara><varname>[ch]</varname> = 0</simpara></listitem>
  506  <listitem><simpara>for each channel <varname>[j]</varname> in order from 0 ... <varname>[audio_channels]</varname></simpara>
  507   <orderedlist>
  508    <listitem><simpara>if channel <varname>[j]</varname> is in submap <varname>[i]</varname> (vector <varname>[vorbis_mapping_mux]</varname> element <varname>[j]</varname> is equal to <varname>[i]</varname>)</simpara>
  509     <orderedlist>
  510      <listitem><simpara>residue vector for channel <varname>[j]</varname> is set to decoded residue vector <varname>[ch]</varname></simpara></listitem>
  511      <listitem><simpara>increment <varname>[ch]</varname></simpara></listitem>
  512     </orderedlist>
  513    </listitem>
  514   </orderedlist>
  515  </listitem>
  516 </orderedlist>
  517 
  518 </section>
  519 
  520 <section><title>inverse coupling</title>
  521 
  522 <para>
  523 for each <varname>[i]</varname> from <varname>[vorbis_mapping_coupling_steps]</varname>-1 descending to 0
  524 
  525 <orderedlist>
  526  <listitem><simpara><varname>[magnitude_vector]</varname> = the residue vector for channel
  527 (vector <varname>[vorbis_mapping_magnitude]</varname> element <varname>[i]</varname>)</simpara></listitem>
  528  <listitem><simpara><varname>[angle_vector]</varname> = the residue vector for channel (vector
  529 <varname>[vorbis_mapping_angle]</varname> element <varname>[i]</varname>)</simpara></listitem>
  530  <listitem><simpara>for each scalar value <varname>[M]</varname> in vector <varname>[magnitude_vector]</varname> and the corresponding scalar value <varname>[A]</varname> in vector <varname>[angle_vector]</varname>:</simpara>
  531   <orderedlist>
  532    <listitem><para>if (<varname>[M]</varname> is greater than zero)
  533     <orderedlist>
  534      <listitem><para>if (<varname>[A]</varname> is greater than zero)
  535       <orderedlist>
  536        <listitem><simpara><varname>[new_M]</varname> = <varname>[M]</varname></simpara></listitem>
  537        <listitem><simpara><varname>[new_A]</varname> = <varname>[M]</varname>-<varname>[A]</varname></simpara></listitem>
  538       </orderedlist>
  539      else
  540       <orderedlist>
  541        <listitem><simpara><varname>[new_A]</varname> = <varname>[M]</varname></simpara></listitem>
  542        <listitem><simpara><varname>[new_M]</varname> = <varname>[M]</varname>+<varname>[A]</varname></simpara></listitem>
  543       </orderedlist>
  544      </para></listitem>
  545     </orderedlist>
  546    else
  547     <orderedlist>
  548      <listitem><para>if (<varname>[A]</varname> is greater than zero)
  549       <orderedlist>
  550        <listitem><simpara><varname>[new_M]</varname> = <varname>[M]</varname></simpara></listitem>
  551        <listitem><simpara><varname>[new_A]</varname> = <varname>[M]</varname>+<varname>[A]</varname></simpara></listitem>
  552       </orderedlist>
  553      else
  554       <orderedlist>
  555        <listitem><simpara><varname>[new_A]</varname> = <varname>[M]</varname></simpara></listitem>
  556        <listitem><simpara><varname>[new_M]</varname> = <varname>[M]</varname>-<varname>[A]</varname></simpara></listitem>
  557       </orderedlist>
  558      </para></listitem>
  559     </orderedlist>
  560    </para></listitem>
  561    <listitem><simpara>set scalar value <varname>[M]</varname> in vector <varname>[magnitude_vector]</varname> to <varname>[new_M]</varname></simpara></listitem>
  562    <listitem><simpara>set scalar value <varname>[A]</varname> in vector <varname>[angle_vector]</varname> to <varname>[new_A]</varname></simpara></listitem>
  563   </orderedlist>
  564  </listitem>
  565 </orderedlist>
  566 </para>
  567 
  568 </section>
  569 
  570 <section><title>dot product</title>
  571 
  572 <para>
  573 For each channel, synthesize the floor curve from the decoded floor
  574 information, according to packet type. Note that the vector synthesis
  575 length for floor computation is <varname>[n]</varname>/2.</para>
  576 
  577 <para>
  578 For each channel, multiply each element of the floor curve by each
  579 element of that channel's residue vector.  The result is the dot
  580 product of the floor and residue vectors for each channel; the produced
  581 vectors are the length <varname>[n]</varname>/2 audio spectrum for each
  582 channel.</para>
  583 
  584 <para>
  585 One point is worth mentioning about this dot product; a common mistake
  586 in a fixed point implementation might be to assume that a 32 bit
  587 fixed-point representation for floor and residue and direct
  588 multiplication of the vectors is sufficient for acceptable spectral
  589 depth in all cases because it happens to mostly work with the current
  590 Xiph.Org reference encoder. </para>
  591 
  592 <para>
  593 However, floor vector values can span ~140dB (~24 bits unsigned), and
  594 the audio spectrum vector should represent a minimum of 120dB (~21
  595 bits with sign), even when output is to a 16 bit PCM device.  For the
  596 residue vector to represent full scale if the floor is nailed to
  597 -140dB, it must be able to span 0 to +140dB.  For the residue vector
  598 to reach full scale if the floor is nailed at 0dB, it must be able to
  599 represent -140dB to +0dB.  Thus, in order to handle full range
  600 dynamics, a residue vector may span -140dB to +140dB entirely within
  601 spec.  A 280dB range is approximately 48 bits with sign; thus the
  602 residue vector must be able to represent a 48 bit range and the dot
  603 product must be able to handle an effective 48 bit times 24 bit
  604 multiplication.  This range may be achieved using large (64 bit or
  605 larger) integers, or implementing a movable binary point
  606 representation.</para>
  607 
  608 </section>
  609 
  610 <section><title>inverse MDCT</title>
  611 
  612 <para>
  613 Convert the audio spectrum vector of each channel back into time
  614 domain PCM audio via an inverse Modified Discrete Cosine Transform
  615 (MDCT).  A detailed description of the MDCT is available in the paper
  616 <ulink url="http://www.iocon.com/resource/docs/ps/eusipco_corrected.ps"><citetitle pubwork="article">The
  617 use of multirate filter banks for coding of high quality digital
  618 audio</citetitle></ulink>, by T. Sporer, K. Brandenburg and B. Edler.  The window
  619 function used for the MDCT is the function described earlier.</para>
  620 
  621 </section>
  622 
  623 <section><title>overlap_add</title>
  624 
  625 <para>
  626 Windowed MDCT output is overlapped and added with the right hand data
  627 of the previous window such that the 3/4 point of the previous window
  628 is aligned with the 1/4 point of the current window (as illustrated in
  629 <xref linkend="vorbis-spec-window"/>).  The overlapped portion
  630 produced from overlapping the previous and current frame data is
  631 finished data to be returned by the decoder.  This data spans from the
  632 center of the previous window to the center of the current window.  In
  633 the case of same-sized windows, the amount of data to return is
  634 one-half block consisting of and only of the overlapped portions. When
  635 overlapping a short and long window, much of the returned range does not
  636 actually overlap.  This does not damage transform orthogonality.  Pay
  637 attention however to returning the correct data range; the amount of
  638 data to be returned is:
  639 
  640 <programlisting>
  641 window_blocksize(previous_window)/4+window_blocksize(current_window)/4
  642 </programlisting>
  643 
  644 from the center (element windowsize/2) of the previous window to the
  645 center (element windowsize/2-1, inclusive) of the current window.</para>
  646 
  647 <para>
  648 Data is not returned from the first frame; it must be used to 'prime'
  649 the decode engine.  The encoder accounts for this priming when
  650 calculating PCM offsets; after the first frame, the proper PCM output
  651 offset is '0' (as no data has been returned yet).</para>
  652 
  653 </section>
  654 
  655 <section><title>output channel order</title>
  656 
  657 <para>
  658 Vorbis I specifies only a channel mapping type 0.  In mapping type 0,
  659 channel mapping is implicitly defined as follows for standard audio
  660 applications:</para>
  661 
  662 <variablelist>
  663  <varlistentry>
  664   <term>one channel</term>
  665   <listitem>
  666    <simpara>the stream is monophonic</simpara>
  667   </listitem>
  668  </varlistentry><varlistentry>
  669   <term>two channels</term><listitem>
  670    <simpara>the stream is stereo.  channel order: left, right</simpara>
  671   </listitem>
  672  </varlistentry><varlistentry>
  673   <term>three channels</term><listitem>
  674    <simpara>the stream is a 1d-surround encoding.  channel order: left,
  675 center, right</simpara>
  676   </listitem>
  677  </varlistentry><varlistentry>
  678   <term>four channels</term><listitem>
  679    <simpara>the stream is quadraphonic surround.  channel order: front left,
  680 front right, rear left, rear right</simpara>
  681   </listitem>
  682  </varlistentry><varlistentry>
  683   <term>five channels</term><listitem>
  684    <simpara>the stream is five-channel surround.  channel order: front left,
  685 front center, front right, rear left, rear right</simpara>
  686   </listitem>
  687  </varlistentry><varlistentry>
  688   <term>six channels</term><listitem>
  689    <simpara>the stream is 5.1 surround.  channel order: front left, front
  690 center, front right, rear left, rear right, LFE</simpara>
  691   </listitem>
  692  </varlistentry><varlistentry>
  693   <term>greater than six channels</term><listitem>
  694    <simpara>channel use and order is defined by the application</simpara>
  695   </listitem>
  696  </varlistentry>
  697 </variablelist>
  698 
  699 <para>
  700 Applications using Vorbis for dedicated purposes may define channel
  701 mapping as seen fit.  Future channel mappings (such as three and four
  702 channel <ulink url="http://www.ambisonic.net/">Ambisonics</ulink>) will
  703 make use of channel mappings other than mapping 0.</para>
  704 
  705 </section>
  706 
  707 </section>
  708 
  709 </section>