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 the N-Band equaliser. */ 21 /* */ 22 /* This files includes all definitions, types, structures and function */ 23 /* prototypes required by the calling layer. All other types, structures and */ 24 /* functions are private. */ 25 /* */ 26 /****************************************************************************************/ 27 /* */ 28 /* Note: 1 */ 29 /* ======= */ 30 /* The algorithm can execute either with separate input and output buffers or with */ 31 /* a common buffer, i.e. the data is processed in-place. */ 32 /* */ 33 /****************************************************************************************/ 34 /* */ 35 /* Note: 2 */ 36 /* ======= */ 37 /* Two data formats are support Stereo and Mono-In-Stereo. The data is interleaved as */ 38 /* follows: */ 39 /* Byte Offset Stereo Input Mono-In-Stereo Input */ 40 /* =========== ============ ==================== */ 41 /* 0 Left Sample #1 Mono Sample #1 */ 42 /* 2 Right Sample #1 Mono Sample #1 */ 43 /* 4 Left Sample #2 Mono Sample #2 */ 44 /* 6 Right Sample #2 Mono Sample #2 */ 45 /* . . . */ 46 /* . . . */ 47 /* */ 48 /* Mono format data is not supported, the calling routine must convert a Mono stream */ 49 /* in to Mono-In-Stereo format. */ 50 /* */ 51 /****************************************************************************************/ 52 /* */ 53 /* Note: 3 */ 54 /* ======= */ 55 /* The format of the data in the filter band definition structure is as follows: */ 56 /* */ 57 /* Gain is in integer dB, range -15dB to +15dB inclusive */ 58 /* Frequency is the centre frequency in Hz, range DC to Nyquist */ 59 /* QFactor is the Q multiplied by 100, range 0.25 (25) to 12 (1200) */ 60 /* */ 61 /* Example: */ 62 /* Gain = 7 7dB gain */ 63 /* Frequency = 2467 Centre frequency = 2.467kHz */ 64 /* QFactor = 1089 Q = 10.89 */ 65 /* */ 66 /* The equaliser filters are passed as a pointer to and array of filter band */ 67 /* definitions structures. There must be one filter definition for each band. */ 68 /* */ 69 /****************************************************************************************/ 70 71 72 #ifndef __LVEQNB_H__ 73 #define __LVEQNB_H__ 74 75 #ifdef __cplusplus 76 extern "C" { 77 #endif /* __cplusplus */ 78 79 80 /****************************************************************************************/ 81 /* */ 82 /* Includes */ 83 /* */ 84 /****************************************************************************************/ 85 86 #include "LVM_Types.h" 87 #include "LVM_Common.h" 88 89 /****************************************************************************************/ 90 /* */ 91 /* Definitions */ 92 /* */ 93 /****************************************************************************************/ 94 95 /* Memory table */ 96 #define LVEQNB_MEMREGION_INSTANCE 0 /* Offset to the instance memory region */ 97 #define LVEQNB_MEMREGION_PERSISTENT_DATA 1 /* Offset to persistent data memory region */ 98 #define LVEQNB_MEMREGION_PERSISTENT_COEF 2 /* Offset to persistent coefficient region */ 99 #define LVEQNB_MEMREGION_SCRATCH 3 /* Offset to data scratch memory region */ 100 #define LVEQNB_NR_MEMORY_REGIONS 4 /* Number of memory regions */ 101 102 /* Callback events */ 103 #define LVEQNB_EVENT_NONE 0x0000 /* Not a valid event */ 104 #define LVEQNB_EVENT_ALGOFF 0x0001 /* EQNB has completed switch off */ 105 106 /****************************************************************************************/ 107 /* */ 108 /* Types */ 109 /* */ 110 /****************************************************************************************/ 111 112 /* Instance handle */ 113 typedef void *LVEQNB_Handle_t; 114 115 116 /* Operating modes */ 117 typedef enum 118 { 119 LVEQNB_BYPASS = 0, 120 LVEQNB_ON = 1, 121 LVEQNB_MODE_MAX = LVM_MAXINT_32 122 } LVEQNB_Mode_en; 123 124 125 /* Filter mode control */ 126 typedef enum 127 { 128 LVEQNB_FILTER_OFF = 0, 129 LVEQNB_FILTER_ON = 1, 130 LVEQNB_FILTER_DUMMY = LVM_MAXINT_32 131 } LVEQNB_FilterMode_en; 132 133 134 /* Memory Types */ 135 typedef enum 136 { 137 LVEQNB_PERSISTENT = 0, 138 LVEQNB_PERSISTENT_DATA = 1, 139 LVEQNB_PERSISTENT_COEF = 2, 140 LVEQNB_SCRATCH = 3, 141 LVEQNB_MEMORY_MAX = LVM_MAXINT_32 142 } LVEQNB_MemoryTypes_en; 143 144 145 /* Function return status */ 146 typedef enum 147 { 148 LVEQNB_SUCCESS = 0, /* Successful return from a routine */ 149 LVEQNB_ALIGNMENTERROR = 1, /* Memory alignment error */ 150 LVEQNB_NULLADDRESS = 2, /* NULL allocation address */ 151 LVEQNB_TOOMANYSAMPLES = 3, /* Maximum block size exceeded */ 152 LVEQNB_STATUS_MAX = LVM_MAXINT_32 153 } LVEQNB_ReturnStatus_en; 154 155 156 /****************************************************************************************/ 157 /* */ 158 /* Linked enumerated type and capability definitions */ 159 /* */ 160 /* The capability definitions are used to define the required capabilities at */ 161 /* initialisation, these are added together to give the capability word. The */ 162 /* enumerated type is used to select the mode through a control function at run time. */ 163 /* */ 164 /* The capability definition is related to the enumerated type value by the equation: */ 165 /* */ 166 /* Capability_value = 2^Enumerated_value */ 167 /* */ 168 /* For example, a module could be configurd at initialisation to support two sample */ 169 /* rates only by calling the init function with the value: */ 170 /* Capabilities.SampleRate = LVEQNB_CAP_32000 + LVEQNB_CAP_44100; */ 171 /* */ 172 /* and at run time it would be passed the value LVEQNB_FS_32000 through the control */ 173 /* function to select operation at 32kHz */ 174 /* */ 175 /****************************************************************************************/ 176 177 /* 178 * Supported source data formats 179 */ 180 #define LVEQNB_CAP_STEREO 1 181 #define LVEQNB_CAP_MONOINSTEREO 2 182 183 typedef enum 184 { 185 LVEQNB_STEREO = 0, 186 LVEQNB_MONOINSTEREO = 1, 187 #ifdef SUPPORT_MC 188 LVEQNB_MULTICHANNEL = 2, 189 #endif 190 LVEQNB_SOURCE_MAX = LVM_MAXINT_32 191 } LVEQNB_SourceFormat_en; 192 193 194 /* 195 * Supported sample rates in samples per second 196 */ 197 #define LVEQNB_CAP_FS_8000 1 198 #define LVEQNB_CAP_FS_11025 2 199 #define LVEQNB_CAP_FS_12000 4 200 #define LVEQNB_CAP_FS_16000 8 201 #define LVEQNB_CAP_FS_22050 16 202 #define LVEQNB_CAP_FS_24000 32 203 #define LVEQNB_CAP_FS_32000 64 204 #define LVEQNB_CAP_FS_44100 128 205 #define LVEQNB_CAP_FS_48000 256 206 #if defined(BUILD_FLOAT) && defined(HIGHER_FS) 207 #define LVEQNB_CAP_FS_88200 512 208 #define LVEQNB_CAP_FS_96000 1024 209 #define LVEQNB_CAP_FS_176400 2048 210 #define LVEQNB_CAP_FS_192000 4096 211 #endif 212 213 typedef enum 214 { 215 LVEQNB_FS_8000 = 0, 216 LVEQNB_FS_11025 = 1, 217 LVEQNB_FS_12000 = 2, 218 LVEQNB_FS_16000 = 3, 219 LVEQNB_FS_22050 = 4, 220 LVEQNB_FS_24000 = 5, 221 LVEQNB_FS_32000 = 6, 222 LVEQNB_FS_44100 = 7, 223 LVEQNB_FS_48000 = 8, 224 #ifdef HIGHER_FS 225 LVEQNB_FS_88200 = 9, 226 LVEQNB_FS_96000 = 10, 227 LVEQNB_FS_176400 = 11, 228 LVEQNB_FS_192000 = 12, 229 #endif 230 LVEQNB_FS_MAX = LVM_MAXINT_32 231 } LVEQNB_Fs_en; 232 233 234 /****************************************************************************************/ 235 /* */ 236 /* Structures */ 237 /* */ 238 /****************************************************************************************/ 239 240 /* Memory region definition */ 241 typedef struct 242 { 243 LVM_UINT32 Size; /* Region size in bytes */ 244 LVM_UINT16 Alignment; /* Region alignment in bytes */ 245 LVEQNB_MemoryTypes_en Type; /* Region type */ 246 void *pBaseAddress; /* Pointer to the region base address */ 247 } LVEQNB_MemoryRegion_t; 248 249 250 /* Memory table containing the region definitions */ 251 typedef struct 252 { 253 LVEQNB_MemoryRegion_t Region[LVEQNB_NR_MEMORY_REGIONS]; /* One definition for each region */ 254 } LVEQNB_MemTab_t; 255 256 257 /* Equaliser band definition */ 258 typedef struct 259 { 260 LVM_INT16 Gain; /* Band gain in dB */ 261 LVM_UINT16 Frequency; /* Band centre frequency in Hz */ 262 LVM_UINT16 QFactor; /* Band quality factor */ 263 } LVEQNB_BandDef_t; 264 265 266 /* Parameter structure */ 267 typedef struct 268 { 269 /* General parameters */ 270 LVEQNB_Mode_en OperatingMode; 271 LVEQNB_Fs_en SampleRate; 272 LVEQNB_SourceFormat_en SourceFormat; 273 274 /* Equaliser parameters */ 275 LVM_UINT16 NBands; /* Number of bands */ 276 LVEQNB_BandDef_t *pBandDefinition; /* Pointer to equaliser definitions */ 277 #ifdef SUPPORT_MC 278 LVM_INT16 NrChannels; 279 #endif 280 } LVEQNB_Params_t; 281 282 283 /* Capability structure */ 284 typedef struct 285 { 286 /* General parameters */ 287 LVM_UINT16 SampleRate; 288 289 LVM_UINT16 SourceFormat; 290 LVM_UINT16 MaxBlockSize; 291 LVM_UINT16 MaxBands; 292 293 /* Callback parameters */ 294 LVM_Callback CallBack; /* Bundle callback */ 295 void *pBundleInstance; /* Bundle instance handle */ 296 297 } LVEQNB_Capabilities_t; 298 299 300 /****************************************************************************************/ 301 /* */ 302 /* Function Prototypes */ 303 /* */ 304 /****************************************************************************************/ 305 306 /****************************************************************************************/ 307 /* */ 308 /* FUNCTION: LVEQNB_Memory */ 309 /* */ 310 /* DESCRIPTION: */ 311 /* This function is used for memory allocation and free. It can be called in */ 312 /* two ways: */ 313 /* */ 314 /* hInstance = NULL Returns the memory requirements */ 315 /* hInstance = Instance handle Returns the memory requirements and */ 316 /* allocated base addresses for the instance */ 317 /* */ 318 /* When this function is called for memory allocation (hInstance=NULL) the memory */ 319 /* base address pointers are NULL on return. */ 320 /* */ 321 /* When the function is called for free (hInstance = Instance Handle) the memory */ 322 /* table returns the allocated memory and base addresses used during initialisation. */ 323 /* */ 324 /* PARAMETERS: */ 325 /* hInstance Instance Handle */ 326 /* pMemoryTable Pointer to an empty memory definition table */ 327 /* pCapabilities Pointer to the default capabilities */ 328 /* */ 329 /* RETURNS: */ 330 /* LVEQNB_SUCCESS Succeeded */ 331 /* LVEQNB_NULLADDRESS When any of pMemoryTable and pCapabilities is NULL address */ 332 /* */ 333 /* NOTES: */ 334 /* 1. This function may be interrupted by the LVEQNB_Process function */ 335 /* */ 336 /****************************************************************************************/ 337 338 LVEQNB_ReturnStatus_en LVEQNB_Memory(LVEQNB_Handle_t hInstance, 339 LVEQNB_MemTab_t *pMemoryTable, 340 LVEQNB_Capabilities_t *pCapabilities); 341 342 343 /****************************************************************************************/ 344 /* */ 345 /* FUNCTION: LVEQNB_Init */ 346 /* */ 347 /* DESCRIPTION: */ 348 /* Create and initialisation function for the N-Band equalliser module */ 349 /* */ 350 /* This function can be used to create an algorithm instance by calling with */ 351 /* hInstance set to NULL. In this case the algorithm returns the new instance */ 352 /* handle. */ 353 /* */ 354 /* This function can be used to force a full re-initialisation of the algorithm */ 355 /* by calling with hInstance = Instance Handle. In this case the memory table */ 356 /* should be correct for the instance, this can be ensured by calling the function */ 357 /* LVEQNB_Memory before calling this function. */ 358 /* */ 359 /* PARAMETERS: */ 360 /* hInstance Instance handle */ 361 /* pMemoryTable Pointer to the memory definition table */ 362 /* pCapabilities Pointer to the initialisation capabilities */ 363 /* */ 364 /* RETURNS: */ 365 /* LVEQNB_SUCCESS Initialisation succeeded */ 366 /* LVEQNB_NULLADDRESS When pCapabilities or pMemoryTableis or phInstance are NULL */ 367 /* LVEQNB_NULLADDRESS One or more of the memory regions has a NULL base address */ 368 /* pointer for a memory region with a non-zero size. */ 369 /* */ 370 /* */ 371 /* NOTES: */ 372 /* 1. The instance handle is the pointer to the base address of the first memory */ 373 /* region. */ 374 /* 2. This function must not be interrupted by the LVEQNB_Process function */ 375 /* */ 376 /****************************************************************************************/ 377 378 LVEQNB_ReturnStatus_en LVEQNB_Init(LVEQNB_Handle_t *phInstance, 379 LVEQNB_MemTab_t *pMemoryTable, 380 LVEQNB_Capabilities_t *pCapabilities); 381 382 383 /****************************************************************************************/ 384 /* */ 385 /* FUNCTION: LVEQNB_GetParameters */ 386 /* */ 387 /* DESCRIPTION: */ 388 /* Request the equaliser module parameters. The current parameter set is returned */ 389 /* via the parameter pointer. */ 390 /* */ 391 /* PARAMETERS: */ 392 /* hInstance Instance handle */ 393 /* pParams Pointer to an empty parameter structure */ 394 /* */ 395 /* RETURNS: */ 396 /* LVEQNB_SUCCESS Succeeds */ 397 /* LVEQNB_NULLADDRESS Instance or pParams is NULL pointer */ 398 /* */ 399 /* NOTES: */ 400 /* 1. This function may be interrupted by the LVEQNB_Process function */ 401 /* */ 402 /****************************************************************************************/ 403 404 LVEQNB_ReturnStatus_en LVEQNB_GetParameters(LVEQNB_Handle_t hInstance, 405 LVEQNB_Params_t *pParams); 406 407 408 /****************************************************************************************/ 409 /* */ 410 /* FUNCTION: LVEQNB_GetCapabilities */ 411 /* */ 412 /* DESCRIPTION: */ 413 /* Request the equaliser module capabilities. The capabilities set is returned */ 414 /* via the pointer. */ 415 /* */ 416 /* PARAMETERS: */ 417 /* hInstance Instance handle */ 418 /* pCapabilities Pointer to an empty capability structure */ 419 /* */ 420 /* RETURNS: */ 421 /* LVEQNB_SUCCESS Succeeds */ 422 /* LVEQNB_NULLADDRESS hInstance or pCapabilities is NULL */ 423 /* */ 424 /* NOTES: */ 425 /* 1. This function may be interrupted by the LVEQNB_Process function */ 426 /* */ 427 /****************************************************************************************/ 428 429 LVEQNB_ReturnStatus_en LVEQNB_GetCapabilities(LVEQNB_Handle_t hInstance, 430 LVEQNB_Capabilities_t *pCapabilities); 431 432 433 /****************************************************************************************/ 434 /* */ 435 /* FUNCTION: LVEQNB_Control */ 436 /* */ 437 /* DESCRIPTION: */ 438 /* Sets or changes the equaliser module parameters. */ 439 /* */ 440 /* PARAMETERS: */ 441 /* hInstance Instance handle */ 442 /* pParams Pointer to a parameter structure */ 443 /* */ 444 /* RETURNS: */ 445 /* LVEQNB_SUCCESS Succeeded */ 446 /* LVEQNB_NULLADDRESS Instance or pParams is NULL pointer */ 447 /* LVEQNB_NULLADDRESS NULL address for the equaliser filter definitions and the */ 448 /* number of bands is non-zero */ 449 /* */ 450 /* NOTES: */ 451 /* 1. This function may be interrupted by the LVEQNB_Process function */ 452 /* */ 453 /****************************************************************************************/ 454 455 LVEQNB_ReturnStatus_en LVEQNB_Control(LVEQNB_Handle_t hInstance, 456 LVEQNB_Params_t *pParams); 457 458 459 /****************************************************************************************/ 460 /* */ 461 /* FUNCTION: LVEQNB_Process */ 462 /* */ 463 /* DESCRIPTION: */ 464 /* Process function for the LifeVibes module. */ 465 /* */ 466 /* PARAMETERS: */ 467 /* hInstance Instance handle */ 468 /* pInData Pointer to the input data */ 469 /* pOutData Pointer to the output data */ 470 /* NumSamples Number of samples in the input buffer */ 471 /* */ 472 /* RETURNS: */ 473 /* LVEQNB_SUCCESS Succeeded */ 474 /* LVEQNB_NULLADDRESS When hInstance, pInData or pOutData are NULL */ 475 /* LVEQNB_ALIGNMENTERROR When pInData or pOutData are not 32-bit aligned */ 476 /* LVEQNB_TOOMANYSAMPLES NumSamples was larger than the maximum block size */ 477 /* */ 478 /* NOTES: */ 479 /* */ 480 /****************************************************************************************/ 481 #ifdef BUILD_FLOAT 482 LVEQNB_ReturnStatus_en LVEQNB_Process(LVEQNB_Handle_t hInstance, 483 const LVM_FLOAT *pInData, 484 LVM_FLOAT *pOutData, 485 LVM_UINT16 NumSamples); 486 #else 487 LVEQNB_ReturnStatus_en LVEQNB_Process(LVEQNB_Handle_t hInstance, 488 const LVM_INT16 *pInData, 489 LVM_INT16 *pOutData, 490 LVM_UINT16 NumSamples); 491 #endif 492 493 494 495 #ifdef __cplusplus 496 } 497 #endif /* __cplusplus */ 498 499 #endif /* __LVEQNB__ */ 500 501