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 LVEQNB_SOURCE_MAX = LVM_MAXINT_32 188 } LVEQNB_SourceFormat_en; 189 190 191 /* 192 * Supported sample rates in samples per second 193 */ 194 #define LVEQNB_CAP_FS_8000 1 195 #define LVEQNB_CAP_FS_11025 2 196 #define LVEQNB_CAP_FS_12000 4 197 #define LVEQNB_CAP_FS_16000 8 198 #define LVEQNB_CAP_FS_22050 16 199 #define LVEQNB_CAP_FS_24000 32 200 #define LVEQNB_CAP_FS_32000 64 201 #define LVEQNB_CAP_FS_44100 128 202 #define LVEQNB_CAP_FS_48000 256 203 #if defined(BUILD_FLOAT) && defined(HIGHER_FS) 204 #define LVEQNB_CAP_FS_96000 512 205 #define LVEQNB_CAP_FS_192000 1024 206 #endif 207 208 typedef enum 209 { 210 LVEQNB_FS_8000 = 0, 211 LVEQNB_FS_11025 = 1, 212 LVEQNB_FS_12000 = 2, 213 LVEQNB_FS_16000 = 3, 214 LVEQNB_FS_22050 = 4, 215 LVEQNB_FS_24000 = 5, 216 LVEQNB_FS_32000 = 6, 217 LVEQNB_FS_44100 = 7, 218 LVEQNB_FS_48000 = 8, 219 #ifdef HIGHER_FS 220 LVEQNB_FS_96000 = 9, 221 LVEQNB_FS_192000 = 10, 222 #endif 223 LVEQNB_FS_MAX = LVM_MAXINT_32 224 } LVEQNB_Fs_en; 225 226 227 /****************************************************************************************/ 228 /* */ 229 /* Structures */ 230 /* */ 231 /****************************************************************************************/ 232 233 /* Memory region definition */ 234 typedef struct 235 { 236 LVM_UINT32 Size; /* Region size in bytes */ 237 LVM_UINT16 Alignment; /* Region alignment in bytes */ 238 LVEQNB_MemoryTypes_en Type; /* Region type */ 239 void *pBaseAddress; /* Pointer to the region base address */ 240 } LVEQNB_MemoryRegion_t; 241 242 243 /* Memory table containing the region definitions */ 244 typedef struct 245 { 246 LVEQNB_MemoryRegion_t Region[LVEQNB_NR_MEMORY_REGIONS]; /* One definition for each region */ 247 } LVEQNB_MemTab_t; 248 249 250 /* Equaliser band definition */ 251 typedef struct 252 { 253 LVM_INT16 Gain; /* Band gain in dB */ 254 LVM_UINT16 Frequency; /* Band centre frequency in Hz */ 255 LVM_UINT16 QFactor; /* Band quality factor */ 256 } LVEQNB_BandDef_t; 257 258 259 /* Parameter structure */ 260 typedef struct 261 { 262 /* General parameters */ 263 LVEQNB_Mode_en OperatingMode; 264 LVEQNB_Fs_en SampleRate; 265 LVEQNB_SourceFormat_en SourceFormat; 266 267 /* Equaliser parameters */ 268 LVM_UINT16 NBands; /* Number of bands */ 269 LVEQNB_BandDef_t *pBandDefinition; /* Pointer to equaliser definitions */ 270 271 } LVEQNB_Params_t; 272 273 274 /* Capability structure */ 275 typedef struct 276 { 277 /* General parameters */ 278 LVM_UINT16 SampleRate; 279 280 LVM_UINT16 SourceFormat; 281 LVM_UINT16 MaxBlockSize; 282 LVM_UINT16 MaxBands; 283 284 /* Callback parameters */ 285 LVM_Callback CallBack; /* Bundle callback */ 286 void *pBundleInstance; /* Bundle instance handle */ 287 288 } LVEQNB_Capabilities_t; 289 290 291 /****************************************************************************************/ 292 /* */ 293 /* Function Prototypes */ 294 /* */ 295 /****************************************************************************************/ 296 297 /****************************************************************************************/ 298 /* */ 299 /* FUNCTION: LVEQNB_Memory */ 300 /* */ 301 /* DESCRIPTION: */ 302 /* This function is used for memory allocation and free. It can be called in */ 303 /* two ways: */ 304 /* */ 305 /* hInstance = NULL Returns the memory requirements */ 306 /* hInstance = Instance handle Returns the memory requirements and */ 307 /* allocated base addresses for the instance */ 308 /* */ 309 /* When this function is called for memory allocation (hInstance=NULL) the memory */ 310 /* base address pointers are NULL on return. */ 311 /* */ 312 /* When the function is called for free (hInstance = Instance Handle) the memory */ 313 /* table returns the allocated memory and base addresses used during initialisation. */ 314 /* */ 315 /* PARAMETERS: */ 316 /* hInstance Instance Handle */ 317 /* pMemoryTable Pointer to an empty memory definition table */ 318 /* pCapabilities Pointer to the default capabilities */ 319 /* */ 320 /* RETURNS: */ 321 /* LVEQNB_SUCCESS Succeeded */ 322 /* LVEQNB_NULLADDRESS When any of pMemoryTable and pCapabilities is NULL address */ 323 /* */ 324 /* NOTES: */ 325 /* 1. This function may be interrupted by the LVEQNB_Process function */ 326 /* */ 327 /****************************************************************************************/ 328 329 LVEQNB_ReturnStatus_en LVEQNB_Memory(LVEQNB_Handle_t hInstance, 330 LVEQNB_MemTab_t *pMemoryTable, 331 LVEQNB_Capabilities_t *pCapabilities); 332 333 334 /****************************************************************************************/ 335 /* */ 336 /* FUNCTION: LVEQNB_Init */ 337 /* */ 338 /* DESCRIPTION: */ 339 /* Create and initialisation function for the N-Band equalliser module */ 340 /* */ 341 /* This function can be used to create an algorithm instance by calling with */ 342 /* hInstance set to NULL. In this case the algorithm returns the new instance */ 343 /* handle. */ 344 /* */ 345 /* This function can be used to force a full re-initialisation of the algorithm */ 346 /* by calling with hInstance = Instance Handle. In this case the memory table */ 347 /* should be correct for the instance, this can be ensured by calling the function */ 348 /* LVEQNB_Memory before calling this function. */ 349 /* */ 350 /* PARAMETERS: */ 351 /* hInstance Instance handle */ 352 /* pMemoryTable Pointer to the memory definition table */ 353 /* pCapabilities Pointer to the initialisation capabilities */ 354 /* */ 355 /* RETURNS: */ 356 /* LVEQNB_SUCCESS Initialisation succeeded */ 357 /* LVEQNB_NULLADDRESS When pCapabilities or pMemoryTableis or phInstance are NULL */ 358 /* LVEQNB_NULLADDRESS One or more of the memory regions has a NULL base address */ 359 /* pointer for a memory region with a non-zero size. */ 360 /* */ 361 /* */ 362 /* NOTES: */ 363 /* 1. The instance handle is the pointer to the base address of the first memory */ 364 /* region. */ 365 /* 2. This function must not be interrupted by the LVEQNB_Process function */ 366 /* */ 367 /****************************************************************************************/ 368 369 LVEQNB_ReturnStatus_en LVEQNB_Init(LVEQNB_Handle_t *phInstance, 370 LVEQNB_MemTab_t *pMemoryTable, 371 LVEQNB_Capabilities_t *pCapabilities); 372 373 374 /****************************************************************************************/ 375 /* */ 376 /* FUNCTION: LVEQNB_GetParameters */ 377 /* */ 378 /* DESCRIPTION: */ 379 /* Request the equaliser module parameters. The current parameter set is returned */ 380 /* via the parameter pointer. */ 381 /* */ 382 /* PARAMETERS: */ 383 /* hInstance Instance handle */ 384 /* pParams Pointer to an empty parameter structure */ 385 /* */ 386 /* RETURNS: */ 387 /* LVEQNB_SUCCESS Succeeds */ 388 /* LVEQNB_NULLADDRESS Instance or pParams is NULL pointer */ 389 /* */ 390 /* NOTES: */ 391 /* 1. This function may be interrupted by the LVEQNB_Process function */ 392 /* */ 393 /****************************************************************************************/ 394 395 LVEQNB_ReturnStatus_en LVEQNB_GetParameters(LVEQNB_Handle_t hInstance, 396 LVEQNB_Params_t *pParams); 397 398 399 /****************************************************************************************/ 400 /* */ 401 /* FUNCTION: LVEQNB_GetCapabilities */ 402 /* */ 403 /* DESCRIPTION: */ 404 /* Request the equaliser module capabilities. The capabilities set is returned */ 405 /* via the pointer. */ 406 /* */ 407 /* PARAMETERS: */ 408 /* hInstance Instance handle */ 409 /* pCapabilities Pointer to an empty capability structure */ 410 /* */ 411 /* RETURNS: */ 412 /* LVEQNB_SUCCESS Succeeds */ 413 /* LVEQNB_NULLADDRESS hInstance or pCapabilities is NULL */ 414 /* */ 415 /* NOTES: */ 416 /* 1. This function may be interrupted by the LVEQNB_Process function */ 417 /* */ 418 /****************************************************************************************/ 419 420 LVEQNB_ReturnStatus_en LVEQNB_GetCapabilities(LVEQNB_Handle_t hInstance, 421 LVEQNB_Capabilities_t *pCapabilities); 422 423 424 /****************************************************************************************/ 425 /* */ 426 /* FUNCTION: LVEQNB_Control */ 427 /* */ 428 /* DESCRIPTION: */ 429 /* Sets or changes the equaliser module parameters. */ 430 /* */ 431 /* PARAMETERS: */ 432 /* hInstance Instance handle */ 433 /* pParams Pointer to a parameter structure */ 434 /* */ 435 /* RETURNS: */ 436 /* LVEQNB_SUCCESS Succeeded */ 437 /* LVEQNB_NULLADDRESS Instance or pParams is NULL pointer */ 438 /* LVEQNB_NULLADDRESS NULL address for the equaliser filter definitions and the */ 439 /* number of bands is non-zero */ 440 /* */ 441 /* NOTES: */ 442 /* 1. This function may be interrupted by the LVEQNB_Process function */ 443 /* */ 444 /****************************************************************************************/ 445 446 LVEQNB_ReturnStatus_en LVEQNB_Control(LVEQNB_Handle_t hInstance, 447 LVEQNB_Params_t *pParams); 448 449 450 /****************************************************************************************/ 451 /* */ 452 /* FUNCTION: LVEQNB_Process */ 453 /* */ 454 /* DESCRIPTION: */ 455 /* Process function for the LifeVibes module. */ 456 /* */ 457 /* PARAMETERS: */ 458 /* hInstance Instance handle */ 459 /* pInData Pointer to the input data */ 460 /* pOutData Pointer to the output data */ 461 /* NumSamples Number of samples in the input buffer */ 462 /* */ 463 /* RETURNS: */ 464 /* LVEQNB_SUCCESS Succeeded */ 465 /* LVEQNB_NULLADDRESS When hInstance, pInData or pOutData are NULL */ 466 /* LVEQNB_ALIGNMENTERROR When pInData or pOutData are not 32-bit aligned */ 467 /* LVEQNB_TOOMANYSAMPLES NumSamples was larger than the maximum block size */ 468 /* */ 469 /* NOTES: */ 470 /* */ 471 /****************************************************************************************/ 472 #ifdef BUILD_FLOAT 473 LVEQNB_ReturnStatus_en LVEQNB_Process(LVEQNB_Handle_t hInstance, 474 const LVM_FLOAT *pInData, 475 LVM_FLOAT *pOutData, 476 LVM_UINT16 NumSamples); 477 #else 478 LVEQNB_ReturnStatus_en LVEQNB_Process(LVEQNB_Handle_t hInstance, 479 const LVM_INT16 *pInData, 480 LVM_INT16 *pOutData, 481 LVM_UINT16 NumSamples); 482 #endif 483 484 485 486 #ifdef __cplusplus 487 } 488 #endif /* __cplusplus */ 489 490 #endif /* __LVEQNB__ */ 491 492