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_96000 512 203 #define LVDBE_CAP_FS_192000 1024 204 #endif 205 206 typedef enum 207 { 208 LVDBE_FS_8000 = 0, 209 LVDBE_FS_11025 = 1, 210 LVDBE_FS_12000 = 2, 211 LVDBE_FS_16000 = 3, 212 LVDBE_FS_22050 = 4, 213 LVDBE_FS_24000 = 5, 214 LVDBE_FS_32000 = 6, 215 LVDBE_FS_44100 = 7, 216 LVDBE_FS_48000 = 8, 217 #if defined(BUILD_FLOAT) && defined(HIGHER_FS) 218 LVDBE_FS_96000 = 9, 219 LVDBE_FS_192000 = 10, 220 #endif 221 LVDBE_FS_MAX = LVM_MAXINT_32 222 } LVDBE_Fs_en; 223 224 225 /****************************************************************************************/ 226 /* */ 227 /* Structures */ 228 /* */ 229 /****************************************************************************************/ 230 231 /* Memory region definition */ 232 typedef struct 233 { 234 LVM_UINT32 Size; /* Region size in bytes */ 235 LVM_UINT16 Alignment; /* Region alignment in bytes */ 236 LVDBE_MemoryTypes_en Type; /* Region type */ 237 void *pBaseAddress; /* Pointer to the region base address */ 238 } LVDBE_MemoryRegion_t; 239 240 241 /* Memory table containing the region definitions */ 242 typedef struct 243 { 244 LVDBE_MemoryRegion_t Region[LVDBE_NR_MEMORY_REGIONS]; /* One definition for each region */ 245 } LVDBE_MemTab_t; 246 247 248 /* Parameter structure */ 249 typedef struct 250 { 251 LVDBE_Mode_en OperatingMode; 252 LVDBE_Fs_en SampleRate; 253 LVM_INT16 EffectLevel; 254 LVDBE_CentreFreq_en CentreFrequency; 255 LVDBE_FilterSelect_en HPFSelect; 256 LVDBE_Volume_en VolumeControl; 257 LVM_INT16 VolumedB; 258 LVM_INT16 HeadroomdB; 259 260 } LVDBE_Params_t; 261 262 263 /* Capability structure */ 264 typedef struct 265 { 266 LVM_UINT16 SampleRate; /* Sampling rate capabilities */ 267 LVM_UINT16 CentreFrequency; /* Centre frequency capabilities */ 268 LVM_UINT16 MaxBlockSize; /* Maximum block size in sample pairs */ 269 } LVDBE_Capabilities_t; 270 271 272 /****************************************************************************************/ 273 /* */ 274 /* Function Prototypes */ 275 /* */ 276 /****************************************************************************************/ 277 278 /****************************************************************************************/ 279 /* */ 280 /* FUNCTION: LVDBE_Memory */ 281 /* */ 282 /* DESCRIPTION: */ 283 /* This function is used for memory allocation and free. It can be called in */ 284 /* two ways: */ 285 /* */ 286 /* hInstance = NULL Returns the memory requirements */ 287 /* hInstance = Instance handle Returns the memory requirements and */ 288 /* allocated base addresses for the instance */ 289 /* */ 290 /* When this function is called for memory allocation (hInstance=NULL) the memory */ 291 /* base address pointers are NULL on return. */ 292 /* */ 293 /* When the function is called for free (hInstance = Instance Handle) the memory */ 294 /* table returns the allocated memory and base addresses used during initialisation. */ 295 /* */ 296 /* PARAMETERS: */ 297 /* hInstance Instance Handle */ 298 /* pMemoryTable Pointer to an empty memory definition table */ 299 /* pCapabilities Pointer to the default capabilites */ 300 /* */ 301 /* RETURNS: */ 302 /* LVDBE_SUCCESS Succeeded */ 303 /* */ 304 /* NOTES: */ 305 /* 1. This function may be interrupted by the LVDBE_Process function */ 306 /* */ 307 /****************************************************************************************/ 308 309 LVDBE_ReturnStatus_en LVDBE_Memory(LVDBE_Handle_t hInstance, 310 LVDBE_MemTab_t *pMemoryTable, 311 LVDBE_Capabilities_t *pCapabilities); 312 313 314 /****************************************************************************************/ 315 /* */ 316 /* FUNCTION: LVDBE_Init */ 317 /* */ 318 /* DESCRIPTION: */ 319 /* Create and initialisation function for the Bass Enhancement module */ 320 /* */ 321 /* This function can be used to create an algorithm instance by calling with */ 322 /* hInstance set to NULL. In this case the algorithm returns the new instance */ 323 /* handle. */ 324 /* */ 325 /* This function can be used to force a full re-initialisation of the algorithm */ 326 /* by calling with hInstance = Instance Handle. In this case the memory table */ 327 /* should be correct for the instance, this can be ensured by calling the function */ 328 /* LVDBE_Memory before calling this function. */ 329 /* */ 330 /* PARAMETERS: */ 331 /* hInstance Instance handle */ 332 /* pMemoryTable Pointer to the memory definition table */ 333 /* pCapabilities Pointer to the initialisation capabilities */ 334 /* */ 335 /* RETURNS: */ 336 /* LVDBE_SUCCESS Initialisation succeeded */ 337 /* LVDBE_ALIGNMENTERROR Instance or scratch memory on incorrect alignment */ 338 /* LVDBE_NULLADDRESS One or more memory has a NULL pointer */ 339 /* */ 340 /* NOTES: */ 341 /* 1. The instance handle is the pointer to the base address of the first memory */ 342 /* region. */ 343 /* 2. This function must not be interrupted by the LVDBE_Process function */ 344 /* */ 345 /****************************************************************************************/ 346 347 LVDBE_ReturnStatus_en LVDBE_Init(LVDBE_Handle_t *phInstance, 348 LVDBE_MemTab_t *pMemoryTable, 349 LVDBE_Capabilities_t *pCapabilities); 350 351 352 /****************************************************************************************/ 353 /* */ 354 /* FUNCTION: LVDBE_GetParameters */ 355 /* */ 356 /* DESCRIPTION: */ 357 /* Request the Bass Enhancement parameters. The current parameter set is returned */ 358 /* via the parameter pointer. */ 359 /* */ 360 /* PARAMETERS: */ 361 /* hInstance Instance handle */ 362 /* pParams Pointer to an empty parameter structure */ 363 /* */ 364 /* RETURNS: */ 365 /* LVDBE_SUCCESS Always succeeds */ 366 /* */ 367 /* NOTES: */ 368 /* 1. This function may be interrupted by the LVDBE_Process function */ 369 /* */ 370 /****************************************************************************************/ 371 372 LVDBE_ReturnStatus_en LVDBE_GetParameters(LVDBE_Handle_t hInstance, 373 LVDBE_Params_t *pParams); 374 375 376 /****************************************************************************************/ 377 /* */ 378 /* FUNCTION: LVDBE_GetCapabilities */ 379 /* */ 380 /* DESCRIPTION: */ 381 /* Request the Dynamic Bass Enhancement capabilities. The initial capabilities are */ 382 /* returned via the pointer. */ 383 /* */ 384 /* PARAMETERS: */ 385 /* hInstance Instance handle */ 386 /* pCapabilities Pointer to an empty capabilitiy structure */ 387 /* */ 388 /* RETURNS: */ 389 /* LVDBE_Success Always succeeds */ 390 /* */ 391 /* NOTES: */ 392 /* 1. This function may be interrupted by the LVDBE_Process function */ 393 /* */ 394 /****************************************************************************************/ 395 396 LVDBE_ReturnStatus_en LVDBE_GetCapabilities(LVDBE_Handle_t hInstance, 397 LVDBE_Capabilities_t *pCapabilities); 398 399 400 /****************************************************************************************/ 401 /* */ 402 /* FUNCTION: LVDBE_Control */ 403 /* */ 404 /* DESCRIPTION: */ 405 /* Sets or changes the Bass Enhancement parameters. Changing the parameters while the */ 406 /* module is processing signals may have the following side effects: */ 407 /* */ 408 /* General parameters: */ 409 /* =================== */ 410 /* OperatingMode: Changing the mode of operation may cause a change in volume */ 411 /* level. */ 412 /* */ 413 /* SampleRate: Changing the sample rate may cause pops and clicks. */ 414 /* */ 415 /* EffectLevel: Changing the effect level setting will have no side effects */ 416 /* */ 417 /* CentreFrequency: Changing the centre frequency may cause pops and clicks */ 418 /* */ 419 /* HPFSelect: Selecting/de-selecting the high pass filter may cause pops and */ 420 /* clicks */ 421 /* */ 422 /* VolumedB Changing the volume setting will have no side effects */ 423 /* */ 424 /* */ 425 /* PARAMETERS: */ 426 /* hInstance Instance handle */ 427 /* pParams Pointer to a parameter structure */ 428 /* */ 429 /* RETURNS: */ 430 /* LVDBE_SUCCESS Always succeeds */ 431 /* */ 432 /* NOTES: */ 433 /* 1. This function must not be interrupted by the LVDBE_Process function */ 434 /* */ 435 /****************************************************************************************/ 436 437 LVDBE_ReturnStatus_en LVDBE_Control(LVDBE_Handle_t hInstance, 438 LVDBE_Params_t *pParams); 439 440 441 /****************************************************************************************/ 442 /* */ 443 /* FUNCTION: LVDBE_Process */ 444 /* */ 445 /* DESCRIPTION: */ 446 /* Process function for the Bass Enhancement module. */ 447 /* */ 448 /* PARAMETERS: */ 449 /* hInstance Instance handle */ 450 /* pInData Pointer to the input data */ 451 /* pOutData Pointer to the output data */ 452 /* NumSamples Number of samples in the input buffer */ 453 /* */ 454 /* RETURNS: */ 455 /* LVDBE_SUCCESS Succeeded */ 456 /* LVDBE_TOOMANYSAMPLES NumSamples was larger than the maximum block size */ 457 /* */ 458 /* NOTES: */ 459 /* */ 460 /****************************************************************************************/ 461 #ifdef BUILD_FLOAT 462 LVDBE_ReturnStatus_en LVDBE_Process(LVDBE_Handle_t hInstance, 463 const LVM_FLOAT *pInData, 464 LVM_FLOAT *pOutData, 465 LVM_UINT16 NumSamples); 466 #else 467 LVDBE_ReturnStatus_en LVDBE_Process(LVDBE_Handle_t hInstance, 468 const LVM_INT16 *pInData, 469 LVM_INT16 *pOutData, 470 LVM_UINT16 NumSamples); 471 #endif 472 473 #ifdef __cplusplus 474 } 475 #endif /* __cplusplus */ 476 477 #endif /* __LVDBE_H__ */ 478