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