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