1 /* 2 * Copyright (C) 2004-2010 NXP Software 3 * Copyright (C) 2010 The Android Open Source Project 4 * 5 * Licensed under the Apache License, Version 2.0 (the "License"); 6 * you may not use this file except in compliance with the License. 7 * You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 18 /****************************************************************************************/ 19 /* */ 20 /* Header file for the application layer interface of Dynamic Bass Enhancement */ 21 /* module. */ 22 /* */ 23 /* This files includes all definitions, types, structures and function */ 24 /* prototypes required by the calling layer. All other types, structures and */ 25 /* functions are private. */ 26 /* */ 27 /****************************************************************************************/ 28 /* */ 29 /* Note: 1 */ 30 /* ======= */ 31 /* The algorithm can execute either with separate input and output buffers or with */ 32 /* a common buffer, i.e. the data is processed in-place. */ 33 /* */ 34 /****************************************************************************************/ 35 /* */ 36 /* Note: 2 */ 37 /* ======= */ 38 /* The Dynamic Bass Enhancement algorithm always processes data as stereo input. Mono*/ 39 /* format data is not supported. The data is interleaved as follows: */ 40 /* */ 41 /* Byte Offset Stereo Input Mono-In-Stereo Input */ 42 /* =========== ============ ==================== */ 43 /* 0 Left Sample #1 Mono Sample #1 */ 44 /* 2 Right Sample #1 Mono Sample #1 */ 45 /* 4 Left Sample #2 Mono Sample #2 */ 46 /* 6 Right Sample #2 Mono Sample #2 */ 47 /* . . . */ 48 /* . . . */ 49 /* */ 50 /* Mono format data is not supported, the calling routine must convert a Mono stream */ 51 /* in to Mono-In-Stereo format. */ 52 /* */ 53 /****************************************************************************************/ 54 55 #ifndef __LVDBE_H__ 56 #define __LVDBE_H__ 57 58 /****************************************************************************************/ 59 /* */ 60 /* Includes */ 61 /* */ 62 /****************************************************************************************/ 63 64 #include "LVM_Types.h" 65 66 /****************************************************************************************/ 67 /* */ 68 /* Definitions */ 69 /* */ 70 /****************************************************************************************/ 71 72 /* Bass Enhancement effect level */ 73 #define LVDBE_EFFECT_03DB 3 /* Effect defines for backwards compatibility */ 74 #define LVDBE_EFFECT_06DB 6 75 #define LVDBE_EFFECT_09DB 9 76 #define LVDBE_EFFECT_12DB 12 77 #define LVDBE_EFFECT_15DB 15 78 79 /****************************************************************************************/ 80 /* */ 81 /* Types */ 82 /* */ 83 /****************************************************************************************/ 84 85 /* Instance handle */ 86 typedef void* LVDBE_Handle_t; 87 88 /* Operating modes */ 89 typedef enum { LVDBE_OFF = 0, LVDBE_ON = 1, LVDBE_MODE_MAX = LVM_MAXINT_32 } LVDBE_Mode_en; 90 91 /* High pass filter */ 92 typedef enum { 93 LVDBE_HPF_OFF = 0, 94 LVDBE_HPF_ON = 1, 95 LVDBE_HPF_MAX = LVM_MAXINT_32 96 } LVDBE_FilterSelect_en; 97 98 /* Volume control */ 99 typedef enum { 100 LVDBE_VOLUME_OFF = 0, 101 LVDBE_VOLUME_ON = 1, 102 LVDBE_VOLUME_MAX = LVM_MAXINT_32 103 } LVDBE_Volume_en; 104 105 /* Function return status */ 106 typedef enum { 107 LVDBE_SUCCESS = 0, /* Successful return from a routine */ 108 LVDBE_NULLADDRESS = 1, /* NULL allocation address */ 109 LVDBE_TOOMANYSAMPLES = 2, /* Maximum block size exceeded */ 110 LVDBE_STATUS_MAX = LVM_MAXINT_32 111 } LVDBE_ReturnStatus_en; 112 113 /****************************************************************************************/ 114 /* */ 115 /* Linked enumerated type and capability definitions */ 116 /* */ 117 /* The capability definitions are used to define the required capabilities at */ 118 /* initialisation, these are added together to give the capability word. The */ 119 /* enumerated type is used to select the mode through a control function at run time. */ 120 /* */ 121 /* The capability definition is related to the enumerated type value by the equation: */ 122 /* */ 123 /* Capability_value = 2^Enumerated_value */ 124 /* */ 125 /* For example, a module could be configurd at initialisation to support two sample */ 126 /* rates only by calling the init function with the value: */ 127 /* Capabilities.SampleRate = LVDBE_CAP_32000 + LVCS_DBE_44100; */ 128 /* */ 129 /* and at run time it would be passed the value LVDBE_FS_32000 through the control */ 130 /* function to select operation at 32kHz */ 131 /* */ 132 /****************************************************************************************/ 133 134 /* 135 * Bass Enhancement centre frequency 136 */ 137 #define LVDBE_CAP_CENTRE_55Hz 1 138 #define LVDBE_CAP_CENTRE_66Hz 2 139 #define LVDBE_CAP_CENTRE_78Hz 4 140 #define LVDBE_CAP_CENTRE_90Hz 8 141 142 typedef enum { 143 LVDBE_CENTRE_55HZ = 0, 144 LVDBE_CENTRE_66HZ = 1, 145 LVDBE_CENTRE_78HZ = 2, 146 LVDBE_CENTRE_90HZ = 3, 147 LVDBE_CENTRE_MAX = LVM_MAXINT_32 148 } LVDBE_CentreFreq_en; 149 150 /* 151 * Supported sample rates in samples per second 152 */ 153 #define LVDBE_CAP_FS_8000 1 154 #define LVDBE_CAP_FS_11025 2 155 #define LVDBE_CAP_FS_12000 4 156 #define LVDBE_CAP_FS_16000 8 157 #define LVDBE_CAP_FS_22050 16 158 #define LVDBE_CAP_FS_24000 32 159 #define LVDBE_CAP_FS_32000 64 160 #define LVDBE_CAP_FS_44100 128 161 #define LVDBE_CAP_FS_48000 256 162 #define LVDBE_CAP_FS_88200 512 163 #define LVDBE_CAP_FS_96000 1024 164 #define LVDBE_CAP_FS_176400 2048 165 #define LVDBE_CAP_FS_192000 4096 166 167 typedef enum { 168 LVDBE_FS_8000 = 0, 169 LVDBE_FS_11025 = 1, 170 LVDBE_FS_12000 = 2, 171 LVDBE_FS_16000 = 3, 172 LVDBE_FS_22050 = 4, 173 LVDBE_FS_24000 = 5, 174 LVDBE_FS_32000 = 6, 175 LVDBE_FS_44100 = 7, 176 LVDBE_FS_48000 = 8, 177 LVDBE_FS_88200 = 9, 178 LVDBE_FS_96000 = 10, 179 LVDBE_FS_176400 = 11, 180 LVDBE_FS_192000 = 12, 181 LVDBE_FS_MAX = LVM_MAXINT_32 182 } LVDBE_Fs_en; 183 184 /****************************************************************************************/ 185 /* */ 186 /* Structures */ 187 /* */ 188 /****************************************************************************************/ 189 190 /* Parameter structure */ 191 typedef struct { 192 LVDBE_Mode_en OperatingMode; 193 LVDBE_Fs_en SampleRate; 194 LVM_INT16 EffectLevel; 195 LVDBE_CentreFreq_en CentreFrequency; 196 LVDBE_FilterSelect_en HPFSelect; 197 LVDBE_Volume_en VolumeControl; 198 LVM_INT16 VolumedB; 199 LVM_INT16 HeadroomdB; 200 LVM_INT16 NrChannels; 201 202 } LVDBE_Params_t; 203 204 /* Capability structure */ 205 typedef struct { 206 LVM_UINT16 SampleRate; /* Sampling rate capabilities */ 207 LVM_UINT16 CentreFrequency; /* Centre frequency capabilities */ 208 LVM_UINT16 MaxBlockSize; /* Maximum block size in sample pairs */ 209 } LVDBE_Capabilities_t; 210 211 /****************************************************************************************/ 212 /* */ 213 /* Function Prototypes */ 214 /* */ 215 /****************************************************************************************/ 216 217 /****************************************************************************************/ 218 /* */ 219 /* FUNCTION: LVDBE_Init */ 220 /* */ 221 /* DESCRIPTION: */ 222 /* Create and initialisation function for the Bass Enhancement module */ 223 /* */ 224 /* PARAMETERS: */ 225 /* phInstance Pointer to instance handle */ 226 /* pCapabilities Pointer to the initialisation capabilities */ 227 /* pScratch Pointer to the bundle scratch buffer */ 228 /* */ 229 /* RETURNS: */ 230 /* LVDBE_SUCCESS Initialisation succeeded */ 231 /* LVDBE_NULLADDRESS One or more memory has a NULL pointer - malloc failure */ 232 /* */ 233 /* NOTES: */ 234 /* 1. This function must not be interrupted by the LVDBE_Process function */ 235 /* */ 236 /****************************************************************************************/ 237 LVDBE_ReturnStatus_en LVDBE_Init(LVDBE_Handle_t* phInstance, LVDBE_Capabilities_t* pCapabilities, 238 void* pScratch); 239 240 /****************************************************************************************/ 241 /* */ 242 /* FUNCTION: LVDBE_DeInit */ 243 /* */ 244 /* DESCRIPTION: */ 245 /* Free the memories created during LVDBE_Init including instance handle */ 246 /* */ 247 /* PARAMETERS: */ 248 /* phInstance Pointer to instance handle */ 249 /* */ 250 /****************************************************************************************/ 251 void LVDBE_DeInit(LVDBE_Handle_t* phInstance); 252 253 /****************************************************************************************/ 254 /* */ 255 /* FUNCTION: LVDBE_GetParameters */ 256 /* */ 257 /* DESCRIPTION: */ 258 /* Request the Bass Enhancement parameters. The current parameter set is returned */ 259 /* via the parameter pointer. */ 260 /* */ 261 /* PARAMETERS: */ 262 /* hInstance Instance handle */ 263 /* pParams Pointer to an empty parameter structure */ 264 /* */ 265 /* RETURNS: */ 266 /* LVDBE_SUCCESS Always succeeds */ 267 /* */ 268 /* NOTES: */ 269 /* 1. This function may be interrupted by the LVDBE_Process function */ 270 /* */ 271 /****************************************************************************************/ 272 273 LVDBE_ReturnStatus_en LVDBE_GetParameters(LVDBE_Handle_t hInstance, LVDBE_Params_t* pParams); 274 275 /****************************************************************************************/ 276 /* */ 277 /* FUNCTION: LVDBE_GetCapabilities */ 278 /* */ 279 /* DESCRIPTION: */ 280 /* Request the Dynamic Bass Enhancement capabilities. The initial capabilities are */ 281 /* returned via the pointer. */ 282 /* */ 283 /* PARAMETERS: */ 284 /* hInstance Instance handle */ 285 /* pCapabilities Pointer to an empty capabilitiy structure */ 286 /* */ 287 /* RETURNS: */ 288 /* LVDBE_Success Always succeeds */ 289 /* */ 290 /* NOTES: */ 291 /* 1. This function may be interrupted by the LVDBE_Process function */ 292 /* */ 293 /****************************************************************************************/ 294 295 LVDBE_ReturnStatus_en LVDBE_GetCapabilities(LVDBE_Handle_t hInstance, 296 LVDBE_Capabilities_t* pCapabilities); 297 298 /****************************************************************************************/ 299 /* */ 300 /* FUNCTION: LVDBE_Control */ 301 /* */ 302 /* DESCRIPTION: */ 303 /* Sets or changes the Bass Enhancement parameters. Changing the parameters while the */ 304 /* module is processing signals may have the following side effects: */ 305 /* */ 306 /* General parameters: */ 307 /* =================== */ 308 /* OperatingMode: Changing the mode of operation may cause a change in volume */ 309 /* level. */ 310 /* */ 311 /* SampleRate: Changing the sample rate may cause pops and clicks. */ 312 /* */ 313 /* EffectLevel: Changing the effect level setting will have no side effects */ 314 /* */ 315 /* CentreFrequency: Changing the centre frequency may cause pops and clicks */ 316 /* */ 317 /* HPFSelect: Selecting/de-selecting the high pass filter may cause pops and */ 318 /* clicks */ 319 /* */ 320 /* VolumedB Changing the volume setting will have no side effects */ 321 /* */ 322 /* */ 323 /* PARAMETERS: */ 324 /* hInstance Instance handle */ 325 /* pParams Pointer to a parameter structure */ 326 /* */ 327 /* RETURNS: */ 328 /* LVDBE_SUCCESS Always succeeds */ 329 /* */ 330 /* NOTES: */ 331 /* 1. This function must not be interrupted by the LVDBE_Process function */ 332 /* */ 333 /****************************************************************************************/ 334 335 LVDBE_ReturnStatus_en LVDBE_Control(LVDBE_Handle_t hInstance, LVDBE_Params_t* pParams); 336 337 /****************************************************************************************/ 338 /* */ 339 /* FUNCTION: LVDBE_Process */ 340 /* */ 341 /* DESCRIPTION: */ 342 /* Process function for the Bass Enhancement module. */ 343 /* */ 344 /* PARAMETERS: */ 345 /* hInstance Instance handle */ 346 /* pInData Pointer to the input data */ 347 /* pOutData Pointer to the output data */ 348 /* NumSamples Number of samples in the input buffer */ 349 /* */ 350 /* RETURNS: */ 351 /* LVDBE_SUCCESS Succeeded */ 352 /* LVDBE_TOOMANYSAMPLES NumSamples was larger than the maximum block size */ 353 /* */ 354 /* NOTES: */ 355 /* */ 356 /****************************************************************************************/ 357 LVDBE_ReturnStatus_en LVDBE_Process(LVDBE_Handle_t hInstance, const LVM_FLOAT* pInData, 358 LVM_FLOAT* pOutData, LVM_UINT16 NumSamples); 359 360 #endif /* __LVDBE_H__ */ 361