]> git.jsancho.org Git - lugaru.git/blob - Dependencies/libvorbis/doc/06-floor0.tex
Fixed SDL linkage and internal libjpeg linkage breaks
[lugaru.git] / Dependencies / libvorbis / doc / 06-floor0.tex
1 % -*- mode: latex; TeX-master: "Vorbis_I_spec"; -*-
2 %!TEX root = Vorbis_I_spec.tex
3 % $Id$
4 \section{Floor type 0 setup and decode} \label{vorbis:spec:floor0}
5
6 \subsection{Overview}
7
8 Vorbis floor type zero uses Line Spectral Pair (LSP, also alternately
9 known as Line Spectral Frequency or LSF) representation to encode a
10 smooth spectral envelope curve as the frequency response of the LSP
11 filter.  This representation is equivalent to a traditional all-pole
12 infinite impulse response filter as would be used in linear predictive
13 coding; LSP representation may be converted to LPC representation and
14 vice-versa.
15
16
17
18 \subsection{Floor 0 format}
19
20 Floor zero configuration consists of six integer fields and a list of
21 VQ codebooks for use in coding/decoding the LSP filter coefficient
22 values used by each frame.
23
24 \subsubsection{header decode}
25
26 Configuration information for instances of floor zero decodes from the
27 codec setup header (third packet).  configuration decode proceeds as
28 follows:
29
30 \begin{Verbatim}[commandchars=\\\{\}]
31   1) [floor0_order] = read an unsigned integer of 8 bits
32   2) [floor0_rate] = read an unsigned integer of 16 bits
33   3) [floor0_bark_map_size] = read an unsigned integer of 16 bits
34   4) [floor0_amplitude_bits] = read an unsigned integer of six bits
35   5) [floor0_amplitude_offset] = read an unsigned integer of eight bits
36   6) [floor0_number_of_books] = read an unsigned integer of four bits and add 1
37   7) array [floor0_book_list] = read a list of [floor0_number_of_books] unsigned integers of eight bits each;
38 \end{Verbatim}
39
40 An end-of-packet condition during any of these bitstream reads renders
41 this stream undecodable.  In addition, any element of the array
42 \varname{[floor0_book_list]} that is greater than the maximum codebook
43 number for this bitstream is an error condition that also renders the
44 stream undecodable.
45
46
47
48 \subsubsection{packet decode} \label{vorbis:spec:floor0-decode}
49
50 Extracting a floor0 curve from an audio packet consists of first
51 decoding the curve amplitude and \varname{[floor0_order]} LSP
52 coefficient values from the bitstream, and then computing the floor
53 curve, which is defined as the frequency response of the decoded LSP
54 filter.
55
56 Packet decode proceeds as follows:
57 \begin{Verbatim}[commandchars=\\\{\}]
58   1) [amplitude] = read an unsigned integer of [floor0_amplitude_bits] bits
59   2) if ( [amplitude] is greater than zero ) \{
60        3) [coefficients] is an empty, zero length vector
61        4) [booknumber] = read an unsigned integer of \link{vorbis:spec:ilog}{ilog}( [floor0_number_of_books] ) bits
62        5) if ( [booknumber] is greater than the highest number decode codebook ) then packet is undecodable
63        6) [last] = zero;
64        7) vector [temp_vector] = read vector from bitstream using codebook number [floor0_book_list] element [booknumber] in VQ context.
65        8) add the scalar value [last] to each scalar in vector [temp_vector]
66        9) [last] = the value of the last scalar in vector [temp_vector]
67       10) concatenate [temp_vector] onto the end of the [coefficients] vector
68       11) if (length of vector [coefficients] is less than [floor0_order], continue at step 6
69
70      \}
71
72  12) done.
73
74 \end{Verbatim}
75
76 Take note of the following properties of decode:
77 \begin{itemize}
78  \item An \varname{[amplitude]} value of zero must result in a return code that indicates this channel is unused in this frame (the output of the channel will be all-zeroes in synthesis).  Several later stages of decode don't occur for an unused channel.
79  \item An end-of-packet condition during decode should be considered a
80 nominal occruence; if end-of-packet is reached during any read
81 operation above, floor decode is to return 'unused' status as if the
82 \varname{[amplitude]} value had read zero at the beginning of decode.
83
84  \item The book number used for decode
85 can, in fact, be stored in the bitstream in \link{vorbis:spec:ilog}{ilog}( \varname{[floor0_number_of_books]} -
86 1 ) bits.  Nevertheless, the above specification is correct and values
87 greater than the maximum possible book value are reserved.
88
89  \item The number of scalars read into the vector \varname{[coefficients]}
90 may be greater than \varname{[floor0_order]}, the number actually
91 required for curve computation.  For example, if the VQ codebook used
92 for the floor currently being decoded has a
93 \varname{[codebook_dimensions]} value of three and
94 \varname{[floor0_order]} is ten, the only way to fill all the needed
95 scalars in \varname{[coefficients]} is to to read a total of twelve
96 scalars as four vectors of three scalars each.  This is not an error
97 condition, and care must be taken not to allow a buffer overflow in
98 decode. The extra values are not used and may be ignored or discarded.
99 \end{itemize}
100
101
102
103
104 \subsubsection{curve computation} \label{vorbis:spec:floor0-synth}
105
106 Given an \varname{[amplitude]} integer and \varname{[coefficients]}
107 vector from packet decode as well as the [floor0_order],
108 [floor0_rate], [floor0_bark_map_size], [floor0_amplitude_bits] and
109 [floor0_amplitude_offset] values from floor setup, and an output
110 vector size \varname{[n]} specified by the decode process, we compute a
111 floor output vector.
112
113 If the value \varname{[amplitude]} is zero, the return value is a
114 length \varname{[n]} vector with all-zero scalars.  Otherwise, begin by
115 assuming the following definitions for the given vector to be
116 synthesized:
117
118    \begin{displaymath}
119      \mathrm{map}_i = \left\{
120        \begin{array}{ll}
121           \min (
122             \mathtt{floor0\_bark\_map\_size} - 1,
123             foobar
124           ) & \textrm{for } i \in [0,n-1] \\
125           -1 & \textrm{for } i = n
126         \end{array}
127       \right.
128     \end{displaymath}
129
130     where
131
132     \begin{displaymath}
133     foobar =
134       \left\lfloor
135         \mathrm{bark}\left(\frac{\mathtt{floor0\_rate} \cdot i}{2n}\right) \cdot \frac{\mathtt{floor0\_bark\_map\_size}} {\mathrm{bark}(.5 \cdot \mathtt{floor0\_rate})}
136       \right\rfloor
137     \end{displaymath}
138
139     and
140
141     \begin{displaymath}
142       \mathrm{bark}(x) = 13.1 \arctan (.00074x) + 2.24 \arctan (.0000000185x^2 + .0001x)
143     \end{displaymath}
144
145 The above is used to synthesize the LSP curve on a Bark-scale frequency
146 axis, then map the result to a linear-scale frequency axis.
147 Similarly, the below calculation synthesizes the output LSP curve \varname{[output]} on a log
148 (dB) amplitude scale, mapping it to linear amplitude in the last step:
149
150 \begin{enumerate}
151  \item  \varname{[i]} = 0
152  \item  \varname{[$\omega$]} = $\pi$ * map element \varname{[i]} / \varname{[floor0_bark_map_size]}
153  \item if ( \varname{[floor0_order]} is odd ) {
154   \begin{enumerate}
155    \item calculate \varname{[p]} and \varname{[q]} according to:
156            \begin{eqnarray*}
157              p & = & (1 - \cos^2\omega)\prod_{j=0}^{\frac{\mathtt{floor0\_order}-3}{2}} 4 (\cos([\mathtt{coefficients}]_{2j+1}) - \cos \omega)^2 \\
158              q & = & \frac{1}{4} \prod_{j=0}^{\frac{\mathtt{floor0\_order}-1}{2}} 4 (\cos([\mathtt{coefficients}]_{2j}) - \cos \omega)^2
159            \end{eqnarray*}
160
161   \end{enumerate}
162   } else \varname{[floor0_order]} is even {
163   \begin{enumerate}
164    \item calculate \varname{[p]} and \varname{[q]} according to:
165            \begin{eqnarray*}
166              p & = & \frac{(1 - \cos^2\omega)}{2} \prod_{j=0}^{\frac{\mathtt{floor0\_order}-2}{2}} 4 (\cos([\mathtt{coefficients}]_{2j+1}) - \cos \omega)^2 \\
167              q & = & \frac{(1 + \cos^2\omega)}{2} \prod_{j=0}^{\frac{\mathtt{floor0\_order}-2}{2}} 4 (\cos([\mathtt{coefficients}]_{2j}) - \cos \omega)^2
168            \end{eqnarray*}
169
170   \end{enumerate}
171   }
172
173  \item calculate \varname{[linear_floor_value]} according to:
174          \begin{displaymath}
175            \exp \left( .11512925 \left(\frac{\mathtt{amplitude} \cdot \mathtt{floor0\_amplitute\_offset}}{(2^{\mathtt{floor0\_amplitude\_bits}}-1)\sqrt{p+q}}
176                   - \mathtt{floor0\_amplitude\_offset} \right) \right)
177          \end{displaymath}
178
179  \item \varname{[iteration_condition]} = map element \varname{[i]}
180  \item \varname{[output]} element \varname{[i]} = \varname{[linear_floor_value]}
181  \item increment \varname{[i]}
182  \item if ( map element \varname{[i]} is equal to \varname{[iteration_condition]} ) continue at step 5
183  \item if ( \varname{[i]} is less than \varname{[n]} ) continue at step 2
184  \item done
185 \end{enumerate}
186
187
188
189
190
191
192