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 /* Callback events */ 90 #define LVEQNB_EVENT_NONE 0x0000 /* Not a valid event */ 91 #define LVEQNB_EVENT_ALGOFF 0x0001 /* EQNB has completed switch off */ 92 93 /****************************************************************************************/ 94 /* */ 95 /* Types */ 96 /* */ 97 /****************************************************************************************/ 98 99 /* Instance handle */ 100 typedef void* LVEQNB_Handle_t; 101 102 /* Operating modes */ 103 typedef enum { LVEQNB_BYPASS = 0, LVEQNB_ON = 1, LVEQNB_MODE_MAX = LVM_MAXINT_32 } LVEQNB_Mode_en; 104 105 /* Filter mode control */ 106 typedef enum { 107 LVEQNB_FILTER_OFF = 0, 108 LVEQNB_FILTER_ON = 1, 109 LVEQNB_FILTER_DUMMY = LVM_MAXINT_32 110 } LVEQNB_FilterMode_en; 111 112 /* Function return status */ 113 typedef enum { 114 LVEQNB_SUCCESS = 0, /* Successful return from a routine */ 115 LVEQNB_ALIGNMENTERROR = 1, /* Memory alignment error */ 116 LVEQNB_NULLADDRESS = 2, /* NULL allocation address */ 117 LVEQNB_TOOMANYSAMPLES = 3, /* Maximum block size exceeded */ 118 LVEQNB_STATUS_MAX = LVM_MAXINT_32 119 } LVEQNB_ReturnStatus_en; 120 121 /****************************************************************************************/ 122 /* */ 123 /* Linked enumerated type and capability definitions */ 124 /* */ 125 /* The capability definitions are used to define the required capabilities at */ 126 /* initialisation, these are added together to give the capability word. The */ 127 /* enumerated type is used to select the mode through a control function at run time. */ 128 /* */ 129 /* The capability definition is related to the enumerated type value by the equation: */ 130 /* */ 131 /* Capability_value = 2^Enumerated_value */ 132 /* */ 133 /* For example, a module could be configurd at initialisation to support two sample */ 134 /* rates only by calling the init function with the value: */ 135 /* Capabilities.SampleRate = LVEQNB_CAP_32000 + LVEQNB_CAP_44100; */ 136 /* */ 137 /* and at run time it would be passed the value LVEQNB_FS_32000 through the control */ 138 /* function to select operation at 32kHz */ 139 /* */ 140 /****************************************************************************************/ 141 142 /* 143 * Supported source data formats 144 */ 145 #define LVEQNB_CAP_STEREO 1 146 #define LVEQNB_CAP_MONOINSTEREO 2 147 148 typedef enum { 149 LVEQNB_STEREO = 0, 150 LVEQNB_MONOINSTEREO = 1, 151 LVEQNB_MULTICHANNEL = 2, 152 LVEQNB_SOURCE_MAX = LVM_MAXINT_32 153 } LVEQNB_SourceFormat_en; 154 155 /* 156 * Supported sample rates in samples per second 157 */ 158 #define LVEQNB_CAP_FS_8000 1 159 #define LVEQNB_CAP_FS_11025 2 160 #define LVEQNB_CAP_FS_12000 4 161 #define LVEQNB_CAP_FS_16000 8 162 #define LVEQNB_CAP_FS_22050 16 163 #define LVEQNB_CAP_FS_24000 32 164 #define LVEQNB_CAP_FS_32000 64 165 #define LVEQNB_CAP_FS_44100 128 166 #define LVEQNB_CAP_FS_48000 256 167 #define LVEQNB_CAP_FS_88200 512 168 #define LVEQNB_CAP_FS_96000 1024 169 #define LVEQNB_CAP_FS_176400 2048 170 #define LVEQNB_CAP_FS_192000 4096 171 172 typedef enum { 173 LVEQNB_FS_8000 = 0, 174 LVEQNB_FS_11025 = 1, 175 LVEQNB_FS_12000 = 2, 176 LVEQNB_FS_16000 = 3, 177 LVEQNB_FS_22050 = 4, 178 LVEQNB_FS_24000 = 5, 179 LVEQNB_FS_32000 = 6, 180 LVEQNB_FS_44100 = 7, 181 LVEQNB_FS_48000 = 8, 182 LVEQNB_FS_88200 = 9, 183 LVEQNB_FS_96000 = 10, 184 LVEQNB_FS_176400 = 11, 185 LVEQNB_FS_192000 = 12, 186 LVEQNB_FS_MAX = LVM_MAXINT_32 187 } LVEQNB_Fs_en; 188 189 /****************************************************************************************/ 190 /* */ 191 /* Structures */ 192 /* */ 193 /****************************************************************************************/ 194 195 /* Equaliser band definition */ 196 typedef struct { 197 LVM_INT16 Gain; /* Band gain in dB */ 198 LVM_UINT16 Frequency; /* Band centre frequency in Hz */ 199 LVM_UINT16 QFactor; /* Band quality factor */ 200 } LVEQNB_BandDef_t; 201 202 /* Parameter structure */ 203 typedef struct { 204 /* General parameters */ 205 LVEQNB_Mode_en OperatingMode; 206 LVEQNB_Fs_en SampleRate; 207 LVEQNB_SourceFormat_en SourceFormat; 208 209 /* Equaliser parameters */ 210 LVM_UINT16 NBands; /* Number of bands */ 211 LVEQNB_BandDef_t* pBandDefinition; /* Pointer to equaliser definitions */ 212 LVM_INT16 NrChannels; 213 } LVEQNB_Params_t; 214 215 /* Capability structure */ 216 typedef struct { 217 /* General parameters */ 218 LVM_UINT16 SampleRate; 219 220 LVM_UINT16 SourceFormat; 221 LVM_UINT16 MaxBlockSize; 222 LVM_UINT16 MaxBands; 223 224 /* Callback parameters */ 225 LVM_Callback CallBack; /* Bundle callback */ 226 void* pBundleInstance; /* Bundle instance handle */ 227 228 } LVEQNB_Capabilities_t; 229 230 /****************************************************************************************/ 231 /* */ 232 /* Function Prototypes */ 233 /* */ 234 /****************************************************************************************/ 235 236 /****************************************************************************************/ 237 /* */ 238 /* FUNCTION: LVEQNB_Init */ 239 /* */ 240 /* DESCRIPTION: */ 241 /* Create and initialisation function for the N-Band equaliser module. */ 242 /* */ 243 /* PARAMETERS: */ 244 /* phInstance Pointer to instance handle */ 245 /* pCapabilities Pointer to the initialisation capabilities */ 246 /* pScratch Pointer to bundle scratch buffer */ 247 /* */ 248 /* RETURNS: */ 249 /* LVEQNB_SUCCESS Initialisation succeeded */ 250 /* LVEQNB_NULLADDRESS When pCapabilities or phInstance are NULL */ 251 /* LVEQNB_NULLADDRESS When allocated memory has a NULL base address */ 252 /* */ 253 /* NOTES: */ 254 /* 1. This function must not be interrupted by the LVEQNB_Process function */ 255 /* */ 256 /****************************************************************************************/ 257 LVEQNB_ReturnStatus_en LVEQNB_Init(LVEQNB_Handle_t* phInstance, 258 LVEQNB_Capabilities_t* pCapabilities, void* pScratch); 259 260 /****************************************************************************************/ 261 /* */ 262 /* FUNCTION: LVEQNB_DeInit */ 263 /* */ 264 /* DESCRIPTION: */ 265 /* Free the memories created during LVEQNB_Init including instance handle */ 266 /* */ 267 /* PARAMETERS: */ 268 /* phInstance Pointer to instance handle */ 269 /* */ 270 /* NOTES: */ 271 /* 1. This function must not be interrupted by the LVEQNB_Process function */ 272 /* */ 273 /****************************************************************************************/ 274 void LVEQNB_DeInit(LVEQNB_Handle_t* phInstance); 275 276 /****************************************************************************************/ 277 /* */ 278 /* FUNCTION: LVEQNB_GetParameters */ 279 /* */ 280 /* DESCRIPTION: */ 281 /* Request the equaliser module parameters. The current parameter set is returned */ 282 /* via the parameter pointer. */ 283 /* */ 284 /* PARAMETERS: */ 285 /* hInstance Instance handle */ 286 /* pParams Pointer to an empty parameter structure */ 287 /* */ 288 /* RETURNS: */ 289 /* LVEQNB_SUCCESS Succeeds */ 290 /* LVEQNB_NULLADDRESS Instance or pParams is NULL pointer */ 291 /* */ 292 /* NOTES: */ 293 /* 1. This function may be interrupted by the LVEQNB_Process function */ 294 /* */ 295 /****************************************************************************************/ 296 297 LVEQNB_ReturnStatus_en LVEQNB_GetParameters(LVEQNB_Handle_t hInstance, LVEQNB_Params_t* pParams); 298 299 /****************************************************************************************/ 300 /* */ 301 /* FUNCTION: LVEQNB_GetCapabilities */ 302 /* */ 303 /* DESCRIPTION: */ 304 /* Request the equaliser module capabilities. The capabilities set is returned */ 305 /* via the pointer. */ 306 /* */ 307 /* PARAMETERS: */ 308 /* hInstance Instance handle */ 309 /* pCapabilities Pointer to an empty capability structure */ 310 /* */ 311 /* RETURNS: */ 312 /* LVEQNB_SUCCESS Succeeds */ 313 /* LVEQNB_NULLADDRESS hInstance or pCapabilities is NULL */ 314 /* */ 315 /* NOTES: */ 316 /* 1. This function may be interrupted by the LVEQNB_Process function */ 317 /* */ 318 /****************************************************************************************/ 319 320 LVEQNB_ReturnStatus_en LVEQNB_GetCapabilities(LVEQNB_Handle_t hInstance, 321 LVEQNB_Capabilities_t* pCapabilities); 322 323 /****************************************************************************************/ 324 /* */ 325 /* FUNCTION: LVEQNB_Control */ 326 /* */ 327 /* DESCRIPTION: */ 328 /* Sets or changes the equaliser module parameters. */ 329 /* */ 330 /* PARAMETERS: */ 331 /* hInstance Instance handle */ 332 /* pParams Pointer to a parameter structure */ 333 /* */ 334 /* RETURNS: */ 335 /* LVEQNB_SUCCESS Succeeded */ 336 /* LVEQNB_NULLADDRESS Instance or pParams is NULL pointer */ 337 /* LVEQNB_NULLADDRESS NULL address for the equaliser filter definitions and the */ 338 /* number of bands is non-zero */ 339 /* */ 340 /* NOTES: */ 341 /* 1. This function may be interrupted by the LVEQNB_Process function */ 342 /* */ 343 /****************************************************************************************/ 344 345 LVEQNB_ReturnStatus_en LVEQNB_Control(LVEQNB_Handle_t hInstance, LVEQNB_Params_t* pParams); 346 347 /****************************************************************************************/ 348 /* */ 349 /* FUNCTION: LVEQNB_Process */ 350 /* */ 351 /* DESCRIPTION: */ 352 /* Process function for the LifeVibes module. */ 353 /* */ 354 /* PARAMETERS: */ 355 /* hInstance Instance handle */ 356 /* pInData Pointer to the input data */ 357 /* pOutData Pointer to the output data */ 358 /* NumSamples Number of samples in the input buffer */ 359 /* */ 360 /* RETURNS: */ 361 /* LVEQNB_SUCCESS Succeeded */ 362 /* LVEQNB_NULLADDRESS When hInstance, pInData or pOutData are NULL */ 363 /* LVEQNB_ALIGNMENTERROR When pInData or pOutData are not 32-bit aligned */ 364 /* LVEQNB_TOOMANYSAMPLES NumSamples was larger than the maximum block size */ 365 /* */ 366 /* NOTES: */ 367 /* */ 368 /****************************************************************************************/ 369 LVEQNB_ReturnStatus_en LVEQNB_Process(LVEQNB_Handle_t hInstance, const LVM_FLOAT* pInData, 370 LVM_FLOAT* pOutData, LVM_UINT16 NumSamples); 371 372 #endif /* __LVEQNB__ */ 373