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