change Coder to Codec everywhere
[flac.git] / src / libFLAC / include / private / lpc.h
1 /* libFLAC - Free Lossless Audio Codec library
2  * Copyright (C) 2000,2001  Josh Coalson
3  *
4  * This library is free software; you can redistribute it and/or
5  * modify it under the terms of the GNU Library General Public
6  * License as published by the Free Software Foundation; either
7  * version 2 of the License, or (at your option) any later version.
8  *
9  * This library is distributed in the hope that it will be useful,
10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
12  * Library General Public License for more details.
13  *
14  * You should have received a copy of the GNU Library General Public
15  * License along with this library; if not, write to the
16  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
17  * Boston, MA  02111-1307, USA.
18  */
19
20 #ifndef FLAC__PRIVATE__LPC_H
21 #define FLAC__PRIVATE__LPC_H
22
23 #include "FLAC/ordinals.h"
24
25 #define FLAC__MAX_LPC_ORDER (32u)
26
27 /*
28  *      FLAC__lpc_compute_autocorrelation()
29  *      --------------------------------------------------------------------
30  *      Compute the autocorrelation for lags between 0 and lag-1.
31  *      Assumes data[] outside of [0,data_len-1] == 0.
32  *      Asserts that lag > 0.
33  *
34  *      IN data[0,data_len-1]
35  *      IN data_len
36  *      IN 0 < lag <= data_len
37  *      OUT autoc[0,lag-1]
38  */
39 void FLAC__lpc_compute_autocorrelation(const real data[], unsigned data_len, unsigned lag, real autoc[]);
40
41 /*
42  *      FLAC__lpc_compute_lp_coefficients()
43  *      --------------------------------------------------------------------
44  *      Computes LP coefficients for orders 1..max_order.
45  *      Do not call if autoc[0] == 0.0.  This means the signal is zero
46  *      and there is no point in calculating a predictor.
47  *
48  *      IN autoc[0,max_order]                      autocorrelation values
49  *      IN 0 < max_order <= FLAC__MAX_LPC_ORDER    max LP order to compute
50  *      OUT lp_coeff[0,max_order-1][0,max_order-1] LP coefficients for each order
51  *      *** IMPORTANT:
52  *      *** lp_coeff[0,max_order-1][max_order,FLAC__MAX_LPC_ORDER-1] are untouched
53  *      OUT error[0,max_order-1]                   error for each order
54  *      
55  *      Example: if max_order is 9, the LP coefficients for order 9 will be
56  *               in lp_coeff[8][0,8], the LP coefficients for order 8 will be
57  *                       in lp_coeff[7][0,7], etc.
58  */
59 void FLAC__lpc_compute_lp_coefficients(const real autoc[], unsigned max_order, real lp_coeff[][FLAC__MAX_LPC_ORDER], real error[]);
60
61 /*
62  *      FLAC__lpc_quantize_coefficients()
63  *      --------------------------------------------------------------------
64  *      Quantizes the LP coefficients.  NOTE: precision + bits_per_sample
65  *      must be less than 32 (sizeof(int32)*8).
66  *
67  *      IN lp_coeff[0,order-1]    LP coefficients
68  *      IN order                  LP order
69  *      IN FLAC__MIN_QLP_COEFF_PRECISION < precision
70  *                                desired precision (in bits, including sign
71  *                                bit) of largest coefficient
72  *      IN bits_per_sample > 0    bits per sample of the originial signal
73  *      OUT qlp_coeff[0,order-1]  quantized coefficients
74  *      OUT bits                  # of bits to shift right to get approximated
75  *                                LP coefficients.  NOTE: could be negative,
76  *                                but |*bits| will always be <= precision
77  *      RETURN 0 => quantization OK
78  *             1 => coefficients vary too much to quantize to the desired
79  *                  precision.  'bits' is unset
80  *             2 => coefficients are all zero, which is bad.  'bits' is unset
81  */
82 int FLAC__lpc_quantize_coefficients(const real lp_coeff[], unsigned order, unsigned precision, unsigned bits_per_sample, int32 qlp_coeff[], int *bits);
83
84 /*
85  *      FLAC__lpc_compute_residual_from_qlp_coefficients()
86  *      --------------------------------------------------------------------
87  *      Compute the residual signal obtained from sutracting the predicted
88  *      signal from the original.
89  *
90  *      IN data[-order,data_len-1] original signal (NOTE THE INDICES!)
91  *      IN data_len                length of original signal
92  *      IN qlp_coeff[0,order-1]    quantized LP coefficients
93  *      IN order > 0               LP order
94  *      IN lp_quantization         quantization of LP coefficients in bits
95  *      OUT residual[0,data_len-1] residual signal
96  */
97 void FLAC__lpc_compute_residual_from_qlp_coefficients(const int32 data[], unsigned data_len, const int32 qlp_coeff[], unsigned order, int lp_quantization, int32 residual[]);
98
99 /*
100  *      FLAC__lpc_restore_signal()
101  *      --------------------------------------------------------------------
102  *      Restore the original signal by summing the residual and the
103  *      predictor.
104  *
105  *      IN residual[0,data_len-1]  residual signal
106  *      IN data_len                length of original signal
107  *      IN qlp_coeff[0,order-1]    quantized LP coefficients
108  *      IN order > 0               LP order
109  *      IN lp_quantization         quantization of LP coefficients in bits
110  *      *** IMPORTANT: the caller must pass in the historical samples:
111  *      IN  data[-order,-1]        previously-reconstructed historical samples
112  *      OUT data[0,data_len-1]     original signal
113  */
114 void FLAC__lpc_restore_signal(const int32 residual[], unsigned data_len, const int32 qlp_coeff[], unsigned order, int lp_quantization, int32 data[]);
115
116 /*
117  *      FLAC__lpc_compute_expected_bits_per_residual_sample()
118  *      --------------------------------------------------------------------
119  *      Compute the expected number of bits per residual signal sample
120  *      based on the LP error (which is related to the residual variance).
121  *
122  *      IN lpc_error >= 0.0   error returned from calculating LP coefficients
123  *      IN total_samples > 0  # of samples in residual signal
124  *      RETURN                expected bits per sample
125  */
126 real FLAC__lpc_compute_expected_bits_per_residual_sample(real lpc_error, unsigned total_samples);
127
128 /*
129  *      FLAC__lpc_compute_best_order()
130  *      --------------------------------------------------------------------
131  *      Compute the best order from the array of signal errors returned
132  *      during coefficient computation.
133  *
134  *      IN lpc_error[0,max_order-1] >= 0.0  error returned from calculating LP coefficients
135  *      IN max_order > 0                    max LP order
136  *      IN total_samples > 0                # of samples in residual signal
137  *      IN bits_per_signal_sample           # of bits per sample in the original signal
138  *      RETURN [1,max_order]                best order
139  */
140 unsigned FLAC__lpc_compute_best_order(const real lpc_error[], unsigned max_order, unsigned total_samples, unsigned bits_per_signal_sample);
141
142 #endif