add FLAC__lpc_compute_expected_bits_per_residual_sample_with_error_scale()
[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/config.h"
24 #include "FLAC/ordinals.h"
25
26 #define FLAC__MAX_LPC_ORDER (32u)
27
28 /*
29  *      FLAC__lpc_compute_autocorrelation()
30  *      --------------------------------------------------------------------
31  *      Compute the autocorrelation for lags between 0 and lag-1.
32  *      Assumes data[] outside of [0,data_len-1] == 0.
33  *      Asserts that lag > 0.
34  *
35  *      IN data[0,data_len-1]
36  *      IN data_len
37  *      IN 0 < lag <= data_len
38  *      OUT autoc[0,lag-1]
39  */
40 void FLAC__lpc_compute_autocorrelation(const real data[], unsigned data_len, unsigned lag, real autoc[]);
41 #ifndef FLAC__NO_ASM
42 #ifdef FLAC__CPU_IA32
43 #ifdef FLAC__HAS_NASM
44 void FLAC__lpc_compute_autocorrelation_asm_i386(const real data[], unsigned data_len, unsigned lag, real autoc[]);
45 void FLAC__lpc_compute_autocorrelation_asm_i386_sse(const real data[], unsigned data_len, unsigned lag, real autoc[]);
46 #endif
47 #endif
48 #endif
49
50 /*
51  *      FLAC__lpc_compute_lp_coefficients()
52  *      --------------------------------------------------------------------
53  *      Computes LP coefficients for orders 1..max_order.
54  *      Do not call if autoc[0] == 0.0.  This means the signal is zero
55  *      and there is no point in calculating a predictor.
56  *
57  *      IN autoc[0,max_order]                      autocorrelation values
58  *      IN 0 < max_order <= FLAC__MAX_LPC_ORDER    max LP order to compute
59  *      OUT lp_coeff[0,max_order-1][0,max_order-1] LP coefficients for each order
60  *      *** IMPORTANT:
61  *      *** lp_coeff[0,max_order-1][max_order,FLAC__MAX_LPC_ORDER-1] are untouched
62  *      OUT error[0,max_order-1]                   error for each order
63  *
64  *      Example: if max_order is 9, the LP coefficients for order 9 will be
65  *               in lp_coeff[8][0,8], the LP coefficients for order 8 will be
66  *                       in lp_coeff[7][0,7], etc.
67  */
68 void FLAC__lpc_compute_lp_coefficients(const real autoc[], unsigned max_order, real lp_coeff[][FLAC__MAX_LPC_ORDER], real error[]);
69
70 /*
71  *      FLAC__lpc_quantize_coefficients()
72  *      --------------------------------------------------------------------
73  *      Quantizes the LP coefficients.  NOTE: precision + bits_per_sample
74  *      must be less than 32 (sizeof(int32)*8).
75  *
76  *      IN lp_coeff[0,order-1]    LP coefficients
77  *      IN order                  LP order
78  *      IN FLAC__MIN_QLP_COEFF_PRECISION < precision
79  *                                desired precision (in bits, including sign
80  *                                bit) of largest coefficient
81  *      IN bits_per_sample > 0    bits per sample of the originial signal
82  *      OUT qlp_coeff[0,order-1]  quantized coefficients
83  *      OUT shift                 # of bits to shift right to get approximated
84  *                                LP coefficients.  NOTE: could be negative.
85  *      RETURN 0 => quantization OK
86  *             1 => coefficients require too much shifting for *shift to
87  *              fit in the LPC subframe header.  'shift' is unset.
88  *         2 => coefficients are all zero, which is bad.  'shift' is
89  *              unset.
90  */
91 int FLAC__lpc_quantize_coefficients(const real lp_coeff[], unsigned order, unsigned precision, unsigned bits_per_sample, int32 qlp_coeff[], int *shift);
92
93 /*
94  *      FLAC__lpc_compute_residual_from_qlp_coefficients()
95  *      --------------------------------------------------------------------
96  *      Compute the residual signal obtained from sutracting the predicted
97  *      signal from the original.
98  *
99  *      IN data[-order,data_len-1] original signal (NOTE THE INDICES!)
100  *      IN data_len                length of original signal
101  *      IN qlp_coeff[0,order-1]    quantized LP coefficients
102  *      IN order > 0               LP order
103  *      IN lp_quantization         quantization of LP coefficients in bits
104  *      OUT residual[0,data_len-1] residual signal
105  */
106 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[]);
107
108 /*
109  *      FLAC__lpc_restore_signal()
110  *      --------------------------------------------------------------------
111  *      Restore the original signal by summing the residual and the
112  *      predictor.
113  *
114  *      IN residual[0,data_len-1]  residual signal
115  *      IN data_len                length of original signal
116  *      IN qlp_coeff[0,order-1]    quantized LP coefficients
117  *      IN order > 0               LP order
118  *      IN lp_quantization         quantization of LP coefficients in bits
119  *      *** IMPORTANT: the caller must pass in the historical samples:
120  *      IN  data[-order,-1]        previously-reconstructed historical samples
121  *      OUT data[0,data_len-1]     original signal
122  */
123 void FLAC__lpc_restore_signal(const int32 residual[], unsigned data_len, const int32 qlp_coeff[], unsigned order, int lp_quantization, int32 data[]);
124 #ifndef FLAC__NO_ASM
125 #ifdef FLAC__CPU_IA32
126 #ifdef FLAC__HAS_NASM
127 void FLAC__lpc_restore_signal_asm_i386(const int32 residual[], unsigned data_len, const int32 qlp_coeff[], unsigned order, int lp_quantization, int32 data[]);
128 void FLAC__lpc_restore_signal_asm_i386_mmx(const int32 residual[], unsigned data_len, const int32 qlp_coeff[], unsigned order, int lp_quantization, int32 data[]);
129 #endif
130 #endif
131 #endif
132
133 /*
134  *      FLAC__lpc_compute_expected_bits_per_residual_sample()
135  *      --------------------------------------------------------------------
136  *      Compute the expected number of bits per residual signal sample
137  *      based on the LP error (which is related to the residual variance).
138  *
139  *      IN lpc_error >= 0.0   error returned from calculating LP coefficients
140  *      IN total_samples > 0  # of samples in residual signal
141  *      RETURN                expected bits per sample
142  */
143 real FLAC__lpc_compute_expected_bits_per_residual_sample(real lpc_error, unsigned total_samples);
144 real FLAC__lpc_compute_expected_bits_per_residual_sample_with_error_scale(real lpc_error, real error_scale);
145
146 /*
147  *      FLAC__lpc_compute_best_order()
148  *      --------------------------------------------------------------------
149  *      Compute the best order from the array of signal errors returned
150  *      during coefficient computation.
151  *
152  *      IN lpc_error[0,max_order-1] >= 0.0  error returned from calculating LP coefficients
153  *      IN max_order > 0                    max LP order
154  *      IN total_samples > 0                # of samples in residual signal
155  *      IN bits_per_signal_sample           # of bits per sample in the original signal
156  *      RETURN [1,max_order]                best order
157  */
158 unsigned FLAC__lpc_compute_best_order(const real lpc_error[], unsigned max_order, unsigned total_samples, unsigned bits_per_signal_sample);
159
160 #endif