1/******************************************************************************
2 *
3 *  Copyright (C) 2014 The Android Open Source Project
4 *  Copyright 2003 - 2004 Open Interface North America, Inc. All rights reserved.
5 *
6 *  Licensed under the Apache License, Version 2.0 (the "License");
7 *  you may not use this file except in compliance with the License.
8 *  You may obtain a copy of the License at:
9 *
10 *  http://www.apache.org/licenses/LICENSE-2.0
11 *
12 *  Unless required by applicable law or agreed to in writing, software
13 *  distributed under the License is distributed on an "AS IS" BASIS,
14 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 *  See the License for the specific language governing permissions and
16 *  limitations under the License.
17 *
18 ******************************************************************************/
19
20/**********************************************************************************
21  $Revision: #1 $
22***********************************************************************************/
23
24/**
25 @file
26
27 Dequantizer for SBC decoder; reconstructs quantized representation of subband samples.
28
29 @ingroup codec_internal
30 */
31
32/**
33@addtogroup codec_internal
34@{
35*/
36
37/**
38 This function is a fixed-point approximation of a modification of the following
39 dequantization operation defined in the spec, as inferred from section 12.6.4:
40
41 @code
42 dequant = 2^(scale_factor+1) * ((raw * 2.0 + 1.0) / ((2^bits) - 1) - 1)
43
44 2 <= bits <= 16
45 0 <= raw < (2^bits)-1   (the -1 is because quantized values with all 1's are forbidden)
46
47 -65535 < dequant < 65535
48 @endcode
49
50 The code below computes the dequantized value divided by a scaling constant
51 equal to about 1.38. This constant is chosen to ensure that the entry in the
52 dequant_long_scaled table for 16 bits is as accurate as possible, since it has
53 the least relative precision available to it due to its small magnitude.
54
55 This routine outputs in Q16.15 format.
56
57 The helper array dequant_long is defined as follows:
58
59 @code
60 dequant_long_long[bits] = round(2^31 * 1/((2^bits - 1) / 1.38...)  for 2 <= bits <= 16
61 @endcode
62
63
64 Additionally, the table entries have the following property:
65
66 @code
67 dequant_long_scaled[bits] <= 2^31 / ((2^bits - 1))  for 2 <= bits <= 16
68 @endcode
69
70 Therefore
71
72 @code
73 d = 2 * raw + 1              1 <= d <= 2^bits - 2
74
75 d' = d * dequant_long[bits]
76
77                  d * dequant_long_scaled[bits] <= (2^bits - 2) * (2^31 / (2^bits - 1))
78                  d * dequant_long_scaled[bits] <= 2^31 * (2^bits - 2)/(2^bits - 1) < 2^31
79 @endcode
80
81 Therefore, d' doesn't overflow a signed 32-bit value.
82
83 @code
84
85 d' =~ 2^31 * (raw * 2.0 + 1.0) / (2^bits - 1) / 1.38...
86
87 result = d' - 2^31/1.38... =~ 2^31 * ((raw * 2.0 + 1.0) / (2^bits - 1) - 1) / 1.38...
88
89 result is therefore a scaled approximation to dequant. It remains only to
90 turn 2^31 into 2^(scale_factor+1). Since we're aiming for Q16.15 format,
91 this is achieved by shifting right by (15-scale_factor):
92
93  (2^31 * x) >> (15-scale_factor) =~ 2^(31-15+scale_factor) * x = 2^15 * 2^(1+scale_factor) * x
94 @endcode
95
96 */
97
98#include <oi_codec_sbc_private.h>
99
100#ifndef SBC_DEQUANT_LONG_SCALED_OFFSET
101#define SBC_DEQUANT_LONG_SCALED_OFFSET 1555931970
102#endif
103
104#ifndef SBC_DEQUANT_LONG_UNSCALED_OFFSET
105#define SBC_DEQUANT_LONG_UNSCALED_OFFSET 2147483648
106#endif
107
108#ifndef SBC_DEQUANT_SCALING_FACTOR
109#define SBC_DEQUANT_SCALING_FACTOR 1.38019122262781f
110#endif
111
112const OI_UINT32 dequant_long_scaled[17];
113const OI_UINT32 dequant_long_unscaled[17];
114
115/** Scales x by y bits to the right, adding a rounding factor.
116 */
117#ifndef SCALE
118#define SCALE(x, y) (((x) + (1 <<((y)-1))) >> (y))
119#endif
120
121#ifdef DEBUG_DEQUANTIZATION
122
123#include <math.h>
124
125INLINE float dequant_float(OI_UINT32 raw, OI_UINT scale_factor, OI_UINT bits)
126{
127    float result = (1 << (scale_factor+1)) * ((raw * 2.0f + 1.0f) / ((1 << bits) - 1.0f) - 1.0f);
128
129    result /= SBC_DEQUANT_SCALING_FACTOR;
130
131    /* Unless the encoder screwed up, all correct dequantized values should
132     * satisfy this inequality. Non-compliant encoders which generate quantized
133     * values with all 1-bits set can, theoretically, trigger this assert. This
134     * is unlikely, however, and only an issue in debug mode.
135     */
136    OI_ASSERT(fabs(result) < 32768 * 1.6);
137
138    return result;
139}
140
141#endif
142
143
144INLINE OI_INT32 OI_SBC_Dequant(OI_UINT32 raw, OI_UINT scale_factor, OI_UINT bits)
145{
146    OI_UINT32 d;
147    OI_INT32 result;
148
149    OI_ASSERT(scale_factor <= 15);
150    OI_ASSERT(bits <= 16);
151
152    if (bits <= 1) {
153        return 0;
154    }
155
156    d = (raw * 2) + 1;
157    d *= dequant_long_scaled[bits];
158    result = d - SBC_DEQUANT_LONG_SCALED_OFFSET;
159
160#ifdef DEBUG_DEQUANTIZATION
161    {
162        OI_INT32 integerized_float_result;
163        float float_result;
164
165        float_result = dequant_float(raw, scale_factor, bits);
166        integerized_float_result = (OI_INT32)floor(0.5f+float_result * (1 << 15));
167
168        /* This detects overflow */
169        OI_ASSERT(((result >= 0) && (integerized_float_result >= 0)) ||
170                  ((result <= 0) && (integerized_float_result <= 0)));
171    }
172#endif
173    return result >> (15 - scale_factor);
174}
175
176/* This version of Dequant does not incorporate the scaling factor of 1.38. It
177 * is intended for use with implementations of the filterbank which are
178 * hard-coded into a DSP. Output is Q16.4 format, so that after joint stereo
179 * processing (which leaves the most significant bit equal to the sign bit if
180 * the encoder is conformant) the result will fit a 24 bit fixed point signed
181 * value.*/
182
183INLINE OI_INT32 OI_SBC_Dequant_Unscaled(OI_UINT32 raw, OI_UINT scale_factor, OI_UINT bits)
184{
185    OI_UINT32 d;
186    OI_INT32 result;
187
188    OI_ASSERT(scale_factor <= 15);
189    OI_ASSERT(bits <= 16);
190
191
192    if (bits <= 1) {
193        return 0;
194    }
195    if (bits == 16) {
196        result = (raw << 16) + raw - 0x7fff7fff;
197        return SCALE(result, 24 - scale_factor);
198    }
199
200
201    d = (raw * 2) + 1;
202    d *= dequant_long_unscaled[bits];
203    result = d - 0x80000000;
204
205    return SCALE(result, 24 - scale_factor);
206}
207
208/**
209@}
210*/
211