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