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 #ifdef __cplusplus 59 extern "C" { 60 #endif /* __cplusplus */ 61 62 63 /****************************************************************************************/ 64 /* */ 65 /* Includes */ 66 /* */ 67 /****************************************************************************************/ 68 69 #include "LVM_Types.h" 70 71 72 /****************************************************************************************/ 73 /* */ 74 /* Definitions */ 75 /* */ 76 /****************************************************************************************/ 77 78 /* Memory table*/ 79 #define LVDBE_NR_MEMORY_REGIONS 4 /* Number of memory regions */ 80 81 /* Bass Enhancement effect level */ 82 #define LVDBE_EFFECT_03DB 3 /* Effect defines for backwards compatibility */ 83 #define LVDBE_EFFECT_06DB 6 84 #define LVDBE_EFFECT_09DB 9 85 #define LVDBE_EFFECT_12DB 12 86 #define LVDBE_EFFECT_15DB 15 87 88 89 /****************************************************************************************/ 90 /* */ 91 /* Types */ 92 /* */ 93 /****************************************************************************************/ 94 95 /* Instance handle */ 96 typedef void *LVDBE_Handle_t; 97 98 99 /* Operating modes */ 100 typedef enum 101 { 102 LVDBE_OFF = 0, 103 LVDBE_ON = 1, 104 LVDBE_MODE_MAX = LVM_MAXINT_32 105 } LVDBE_Mode_en; 106 107 108 /* High pass filter */ 109 typedef enum 110 { 111 LVDBE_HPF_OFF = 0, 112 LVDBE_HPF_ON = 1, 113 LVDBE_HPF_MAX = LVM_MAXINT_32 114 } LVDBE_FilterSelect_en; 115 116 117 /* Volume control */ 118 typedef enum 119 { 120 LVDBE_VOLUME_OFF = 0, 121 LVDBE_VOLUME_ON = 1, 122 LVDBE_VOLUME_MAX = LVM_MAXINT_32 123 } LVDBE_Volume_en; 124 125 126 /* Memory Types */ 127 typedef enum 128 { 129 LVDBE_PERSISTENT = 0, 130 LVDBE_PERSISTENT_DATA = 1, 131 LVDBE_PERSISTENT_COEF = 2, 132 LVDBE_SCRATCH = 3, 133 LVDBE_MEMORY_MAX = LVM_MAXINT_32 134 135 } LVDBE_MemoryTypes_en; 136 137 138 /* Function return status */ 139 typedef enum 140 { 141 LVDBE_SUCCESS = 0, /* Successful return from a routine */ 142 LVDBE_ALIGNMENTERROR = 1, /* Memory alignment error */ 143 LVDBE_NULLADDRESS = 2, /* NULL allocation address */ 144 LVDBE_TOOMANYSAMPLES = 3, /* Maximum block size exceeded */ 145 LVDBE_SIZEERROR = 4, /* Incorrect structure size */ 146 LVDBE_STATUS_MAX = LVM_MAXINT_32 147 } LVDBE_ReturnStatus_en; 148 149 150 /****************************************************************************************/ 151 /* */ 152 /* Linked enumerated type and capability definitions */ 153 /* */ 154 /* The capability definitions are used to define the required capabilities at */ 155 /* initialisation, these are added together to give the capability word. The */ 156 /* enumerated type is used to select the mode through a control function at run time. */ 157 /* */ 158 /* The capability definition is related to the enumerated type value by the equation: */ 159 /* */ 160 /* Capability_value = 2^Enumerated_value */ 161 /* */ 162 /* For example, a module could be configurd at initialisation to support two sample */ 163 /* rates only by calling the init function with the value: */ 164 /* Capabilities.SampleRate = LVDBE_CAP_32000 + LVCS_DBE_44100; */ 165 /* */ 166 /* and at run time it would be passed the value LVDBE_FS_32000 through the control */ 167 /* function to select operation at 32kHz */ 168 /* */ 169 /****************************************************************************************/ 170 171 /* 172 * Bass Enhancement centre frequency 173 */ 174 #define LVDBE_CAP_CENTRE_55Hz 1 175 #define LVDBE_CAP_CENTRE_66Hz 2 176 #define LVDBE_CAP_CENTRE_78Hz 4 177 #define LVDBE_CAP_CENTRE_90Hz 8 178 179 typedef enum 180 { 181 LVDBE_CENTRE_55HZ = 0, 182 LVDBE_CENTRE_66HZ = 1, 183 LVDBE_CENTRE_78HZ = 2, 184 LVDBE_CENTRE_90HZ = 3, 185 LVDBE_CENTRE_MAX = LVM_MAXINT_32 186 } LVDBE_CentreFreq_en; 187 188 189 /* 190 * Supported sample rates in samples per second 191 */ 192 #define LVDBE_CAP_FS_8000 1 193 #define LVDBE_CAP_FS_11025 2 194 #define LVDBE_CAP_FS_12000 4 195 #define LVDBE_CAP_FS_16000 8 196 #define LVDBE_CAP_FS_22050 16 197 #define LVDBE_CAP_FS_24000 32 198 #define LVDBE_CAP_FS_32000 64 199 #define LVDBE_CAP_FS_44100 128 200 #define LVDBE_CAP_FS_48000 256 201 #if defined(BUILD_FLOAT) && defined(HIGHER_FS) 202 #define LVDBE_CAP_FS_88200 512 203 #define LVDBE_CAP_FS_96000 1024 204 #define LVDBE_CAP_FS_176400 2048 205 #define LVDBE_CAP_FS_192000 4096 206 #endif 207 208 typedef enum 209 { 210 LVDBE_FS_8000 = 0, 211 LVDBE_FS_11025 = 1, 212 LVDBE_FS_12000 = 2, 213 LVDBE_FS_16000 = 3, 214 LVDBE_FS_22050 = 4, 215 LVDBE_FS_24000 = 5, 216 LVDBE_FS_32000 = 6, 217 LVDBE_FS_44100 = 7, 218 LVDBE_FS_48000 = 8, 219 #if defined(BUILD_FLOAT) && defined(HIGHER_FS) 220 LVDBE_FS_88200 = 9, 221 LVDBE_FS_96000 = 10, 222 LVDBE_FS_176400 = 11, 223 LVDBE_FS_192000 = 12, 224 #endif 225 LVDBE_FS_MAX = LVM_MAXINT_32 226 } LVDBE_Fs_en; 227 228 229 /****************************************************************************************/ 230 /* */ 231 /* Structures */ 232 /* */ 233 /****************************************************************************************/ 234 235 /* Memory region definition */ 236 typedef struct 237 { 238 LVM_UINT32 Size; /* Region size in bytes */ 239 LVM_UINT16 Alignment; /* Region alignment in bytes */ 240 LVDBE_MemoryTypes_en Type; /* Region type */ 241 void *pBaseAddress; /* Pointer to the region base address */ 242 } LVDBE_MemoryRegion_t; 243 244 245 /* Memory table containing the region definitions */ 246 typedef struct 247 { 248 LVDBE_MemoryRegion_t Region[LVDBE_NR_MEMORY_REGIONS]; /* One definition for each region */ 249 } LVDBE_MemTab_t; 250 251 252 /* Parameter structure */ 253 typedef struct 254 { 255 LVDBE_Mode_en OperatingMode; 256 LVDBE_Fs_en SampleRate; 257 LVM_INT16 EffectLevel; 258 LVDBE_CentreFreq_en CentreFrequency; 259 LVDBE_FilterSelect_en HPFSelect; 260 LVDBE_Volume_en VolumeControl; 261 LVM_INT16 VolumedB; 262 LVM_INT16 HeadroomdB; 263 #ifdef SUPPORT_MC 264 LVM_INT16 NrChannels; 265 #endif 266 267 } LVDBE_Params_t; 268 269 270 /* Capability structure */ 271 typedef struct 272 { 273 LVM_UINT16 SampleRate; /* Sampling rate capabilities */ 274 LVM_UINT16 CentreFrequency; /* Centre frequency capabilities */ 275 LVM_UINT16 MaxBlockSize; /* Maximum block size in sample pairs */ 276 } LVDBE_Capabilities_t; 277 278 279 /****************************************************************************************/ 280 /* */ 281 /* Function Prototypes */ 282 /* */ 283 /****************************************************************************************/ 284 285 /****************************************************************************************/ 286 /* */ 287 /* FUNCTION: LVDBE_Memory */ 288 /* */ 289 /* DESCRIPTION: */ 290 /* This function is used for memory allocation and free. It can be called in */ 291 /* two ways: */ 292 /* */ 293 /* hInstance = NULL Returns the memory requirements */ 294 /* hInstance = Instance handle Returns the memory requirements and */ 295 /* allocated base addresses for the instance */ 296 /* */ 297 /* When this function is called for memory allocation (hInstance=NULL) the memory */ 298 /* base address pointers are NULL on return. */ 299 /* */ 300 /* When the function is called for free (hInstance = Instance Handle) the memory */ 301 /* table returns the allocated memory and base addresses used during initialisation. */ 302 /* */ 303 /* PARAMETERS: */ 304 /* hInstance Instance Handle */ 305 /* pMemoryTable Pointer to an empty memory definition table */ 306 /* pCapabilities Pointer to the default capabilites */ 307 /* */ 308 /* RETURNS: */ 309 /* LVDBE_SUCCESS Succeeded */ 310 /* */ 311 /* NOTES: */ 312 /* 1. This function may be interrupted by the LVDBE_Process function */ 313 /* */ 314 /****************************************************************************************/ 315 316 LVDBE_ReturnStatus_en LVDBE_Memory(LVDBE_Handle_t hInstance, 317 LVDBE_MemTab_t *pMemoryTable, 318 LVDBE_Capabilities_t *pCapabilities); 319 320 321 /****************************************************************************************/ 322 /* */ 323 /* FUNCTION: LVDBE_Init */ 324 /* */ 325 /* DESCRIPTION: */ 326 /* Create and initialisation function for the Bass Enhancement module */ 327 /* */ 328 /* This function can be used to create an algorithm instance by calling with */ 329 /* hInstance set to NULL. In this case the algorithm returns the new instance */ 330 /* handle. */ 331 /* */ 332 /* This function can be used to force a full re-initialisation of the algorithm */ 333 /* by calling with hInstance = Instance Handle. In this case the memory table */ 334 /* should be correct for the instance, this can be ensured by calling the function */ 335 /* LVDBE_Memory before calling this function. */ 336 /* */ 337 /* PARAMETERS: */ 338 /* hInstance Instance handle */ 339 /* pMemoryTable Pointer to the memory definition table */ 340 /* pCapabilities Pointer to the initialisation capabilities */ 341 /* */ 342 /* RETURNS: */ 343 /* LVDBE_SUCCESS Initialisation succeeded */ 344 /* LVDBE_ALIGNMENTERROR Instance or scratch memory on incorrect alignment */ 345 /* LVDBE_NULLADDRESS One or more memory has a NULL pointer */ 346 /* */ 347 /* NOTES: */ 348 /* 1. The instance handle is the pointer to the base address of the first memory */ 349 /* region. */ 350 /* 2. This function must not be interrupted by the LVDBE_Process function */ 351 /* */ 352 /****************************************************************************************/ 353 354 LVDBE_ReturnStatus_en LVDBE_Init(LVDBE_Handle_t *phInstance, 355 LVDBE_MemTab_t *pMemoryTable, 356 LVDBE_Capabilities_t *pCapabilities); 357 358 359 /****************************************************************************************/ 360 /* */ 361 /* FUNCTION: LVDBE_GetParameters */ 362 /* */ 363 /* DESCRIPTION: */ 364 /* Request the Bass Enhancement parameters. The current parameter set is returned */ 365 /* via the parameter pointer. */ 366 /* */ 367 /* PARAMETERS: */ 368 /* hInstance Instance handle */ 369 /* pParams Pointer to an empty parameter structure */ 370 /* */ 371 /* RETURNS: */ 372 /* LVDBE_SUCCESS Always succeeds */ 373 /* */ 374 /* NOTES: */ 375 /* 1. This function may be interrupted by the LVDBE_Process function */ 376 /* */ 377 /****************************************************************************************/ 378 379 LVDBE_ReturnStatus_en LVDBE_GetParameters(LVDBE_Handle_t hInstance, 380 LVDBE_Params_t *pParams); 381 382 383 /****************************************************************************************/ 384 /* */ 385 /* FUNCTION: LVDBE_GetCapabilities */ 386 /* */ 387 /* DESCRIPTION: */ 388 /* Request the Dynamic Bass Enhancement capabilities. The initial capabilities are */ 389 /* returned via the pointer. */ 390 /* */ 391 /* PARAMETERS: */ 392 /* hInstance Instance handle */ 393 /* pCapabilities Pointer to an empty capabilitiy structure */ 394 /* */ 395 /* RETURNS: */ 396 /* LVDBE_Success Always succeeds */ 397 /* */ 398 /* NOTES: */ 399 /* 1. This function may be interrupted by the LVDBE_Process function */ 400 /* */ 401 /****************************************************************************************/ 402 403 LVDBE_ReturnStatus_en LVDBE_GetCapabilities(LVDBE_Handle_t hInstance, 404 LVDBE_Capabilities_t *pCapabilities); 405 406 407 /****************************************************************************************/ 408 /* */ 409 /* FUNCTION: LVDBE_Control */ 410 /* */ 411 /* DESCRIPTION: */ 412 /* Sets or changes the Bass Enhancement parameters. Changing the parameters while the */ 413 /* module is processing signals may have the following side effects: */ 414 /* */ 415 /* General parameters: */ 416 /* =================== */ 417 /* OperatingMode: Changing the mode of operation may cause a change in volume */ 418 /* level. */ 419 /* */ 420 /* SampleRate: Changing the sample rate may cause pops and clicks. */ 421 /* */ 422 /* EffectLevel: Changing the effect level setting will have no side effects */ 423 /* */ 424 /* CentreFrequency: Changing the centre frequency may cause pops and clicks */ 425 /* */ 426 /* HPFSelect: Selecting/de-selecting the high pass filter may cause pops and */ 427 /* clicks */ 428 /* */ 429 /* VolumedB Changing the volume setting will have no side effects */ 430 /* */ 431 /* */ 432 /* PARAMETERS: */ 433 /* hInstance Instance handle */ 434 /* pParams Pointer to a parameter structure */ 435 /* */ 436 /* RETURNS: */ 437 /* LVDBE_SUCCESS Always succeeds */ 438 /* */ 439 /* NOTES: */ 440 /* 1. This function must not be interrupted by the LVDBE_Process function */ 441 /* */ 442 /****************************************************************************************/ 443 444 LVDBE_ReturnStatus_en LVDBE_Control(LVDBE_Handle_t hInstance, 445 LVDBE_Params_t *pParams); 446 447 448 /****************************************************************************************/ 449 /* */ 450 /* FUNCTION: LVDBE_Process */ 451 /* */ 452 /* DESCRIPTION: */ 453 /* Process function for the Bass Enhancement module. */ 454 /* */ 455 /* PARAMETERS: */ 456 /* hInstance Instance handle */ 457 /* pInData Pointer to the input data */ 458 /* pOutData Pointer to the output data */ 459 /* NumSamples Number of samples in the input buffer */ 460 /* */ 461 /* RETURNS: */ 462 /* LVDBE_SUCCESS Succeeded */ 463 /* LVDBE_TOOMANYSAMPLES NumSamples was larger than the maximum block size */ 464 /* */ 465 /* NOTES: */ 466 /* */ 467 /****************************************************************************************/ 468 #ifdef BUILD_FLOAT 469 LVDBE_ReturnStatus_en LVDBE_Process(LVDBE_Handle_t hInstance, 470 const LVM_FLOAT *pInData, 471 LVM_FLOAT *pOutData, 472 LVM_UINT16 NumSamples); 473 #else 474 LVDBE_ReturnStatus_en LVDBE_Process(LVDBE_Handle_t hInstance, 475 const LVM_INT16 *pInData, 476 LVM_INT16 *pOutData, 477 LVM_UINT16 NumSamples); 478 #endif 479 480 #ifdef __cplusplus 481 } 482 #endif /* __cplusplus */ 483 484 #endif /* __LVDBE_H__ */ 485