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