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 Dynamic Bass Enhancement */ 21/* module. */ 22/* */ 23/* This files includes all definitions, types, structures and function */ 24/* prototypes required by the calling layer. All other types, structures and */ 25/* functions are private. */ 26/* */ 27/****************************************************************************************/ 28/* */ 29/* Note: 1 */ 30/* ======= */ 31/* The algorithm can execute either with separate input and output buffers or with */ 32/* a common buffer, i.e. the data is processed in-place. */ 33/* */ 34/****************************************************************************************/ 35/* */ 36/* Note: 2 */ 37/* ======= */ 38/* The Dynamic Bass Enhancement algorithm always processes data as stereo input. Mono*/ 39/* format data is not supported. The data is interleaved as follows: */ 40/* */ 41/* Byte Offset Stereo Input Mono-In-Stereo Input */ 42/* =========== ============ ==================== */ 43/* 0 Left Sample #1 Mono Sample #1 */ 44/* 2 Right Sample #1 Mono Sample #1 */ 45/* 4 Left Sample #2 Mono Sample #2 */ 46/* 6 Right Sample #2 Mono Sample #2 */ 47/* . . . */ 48/* . . . */ 49/* */ 50/* Mono format data is not supported, the calling routine must convert a Mono stream */ 51/* in to Mono-In-Stereo format. */ 52/* */ 53/****************************************************************************************/ 54 55#ifndef __LVDBE_H__ 56#define __LVDBE_H__ 57 58#ifdef __cplusplus 59extern "C" { 60#endif /* __cplusplus */ 61 62 63/****************************************************************************************/ 64/* */ 65/* Includes */ 66/* */ 67/****************************************************************************************/ 68 69#include "LVM_Types.h" 70 71 72/****************************************************************************************/ 73/* */ 74/* Definitions */ 75/* */ 76/****************************************************************************************/ 77 78/* Memory table*/ 79#define LVDBE_NR_MEMORY_REGIONS 4 /* Number of memory regions */ 80 81/* Bass Enhancement effect level */ 82#define LVDBE_EFFECT_03DB 3 /* Effect defines for backwards compatibility */ 83#define LVDBE_EFFECT_06DB 6 84#define LVDBE_EFFECT_09DB 9 85#define LVDBE_EFFECT_12DB 12 86#define LVDBE_EFFECT_15DB 15 87 88 89/****************************************************************************************/ 90/* */ 91/* Types */ 92/* */ 93/****************************************************************************************/ 94 95/* Instance handle */ 96typedef void *LVDBE_Handle_t; 97 98 99/* Operating modes */ 100typedef enum 101{ 102 LVDBE_OFF = 0, 103 LVDBE_ON = 1, 104 LVDBE_MODE_MAX = LVM_MAXINT_32 105} LVDBE_Mode_en; 106 107 108/* High pass filter */ 109typedef enum 110{ 111 LVDBE_HPF_OFF = 0, 112 LVDBE_HPF_ON = 1, 113 LVDBE_HPF_MAX = LVM_MAXINT_32 114} LVDBE_FilterSelect_en; 115 116 117/* Volume control */ 118typedef enum 119{ 120 LVDBE_VOLUME_OFF = 0, 121 LVDBE_VOLUME_ON = 1, 122 LVDBE_VOLUME_MAX = LVM_MAXINT_32 123} LVDBE_Volume_en; 124 125 126/* Memory Types */ 127typedef enum 128{ 129 LVDBE_PERSISTENT = 0, 130 LVDBE_PERSISTENT_DATA = 1, 131 LVDBE_PERSISTENT_COEF = 2, 132 LVDBE_SCRATCH = 3, 133 LVDBE_MEMORY_MAX = LVM_MAXINT_32 134 135} LVDBE_MemoryTypes_en; 136 137 138/* Function return status */ 139typedef enum 140{ 141 LVDBE_SUCCESS = 0, /* Successful return from a routine */ 142 LVDBE_ALIGNMENTERROR = 1, /* Memory alignment error */ 143 LVDBE_NULLADDRESS = 2, /* NULL allocation address */ 144 LVDBE_TOOMANYSAMPLES = 3, /* Maximum block size exceeded */ 145 LVDBE_SIZEERROR = 4, /* Incorrect structure size */ 146 LVDBE_STATUS_MAX = LVM_MAXINT_32 147} LVDBE_ReturnStatus_en; 148 149 150/****************************************************************************************/ 151/* */ 152/* Linked enumerated type and capability definitions */ 153/* */ 154/* The capability definitions are used to define the required capabilities at */ 155/* initialisation, these are added together to give the capability word. The */ 156/* enumerated type is used to select the mode through a control function at run time. */ 157/* */ 158/* The capability definition is related to the enumerated type value by the equation: */ 159/* */ 160/* Capability_value = 2^Enumerated_value */ 161/* */ 162/* For example, a module could be configurd at initialisation to support two sample */ 163/* rates only by calling the init function with the value: */ 164/* Capabilities.SampleRate = LVDBE_CAP_32000 + LVCS_DBE_44100; */ 165/* */ 166/* and at run time it would be passed the value LVDBE_FS_32000 through the control */ 167/* function to select operation at 32kHz */ 168/* */ 169/****************************************************************************************/ 170 171/* 172 * Bass Enhancement centre frequency 173 */ 174#define LVDBE_CAP_CENTRE_55Hz 1 175#define LVDBE_CAP_CENTRE_66Hz 2 176#define LVDBE_CAP_CENTRE_78Hz 4 177#define LVDBE_CAP_CENTRE_90Hz 8 178 179typedef enum 180{ 181 LVDBE_CENTRE_55HZ = 0, 182 LVDBE_CENTRE_66HZ = 1, 183 LVDBE_CENTRE_78HZ = 2, 184 LVDBE_CENTRE_90HZ = 3, 185 LVDBE_CENTRE_MAX = LVM_MAXINT_32 186} LVDBE_CentreFreq_en; 187 188 189/* 190 * Supported sample rates in samples per second 191 */ 192#define LVDBE_CAP_FS_8000 1 193#define LVDBE_CAP_FS_11025 2 194#define LVDBE_CAP_FS_12000 4 195#define LVDBE_CAP_FS_16000 8 196#define LVDBE_CAP_FS_22050 16 197#define LVDBE_CAP_FS_24000 32 198#define LVDBE_CAP_FS_32000 64 199#define LVDBE_CAP_FS_44100 128 200#define LVDBE_CAP_FS_48000 256 201 202typedef enum 203{ 204 LVDBE_FS_8000 = 0, 205 LVDBE_FS_11025 = 1, 206 LVDBE_FS_12000 = 2, 207 LVDBE_FS_16000 = 3, 208 LVDBE_FS_22050 = 4, 209 LVDBE_FS_24000 = 5, 210 LVDBE_FS_32000 = 6, 211 LVDBE_FS_44100 = 7, 212 LVDBE_FS_48000 = 8, 213 LVDBE_FS_MAX = LVM_MAXINT_32 214} LVDBE_Fs_en; 215 216 217/****************************************************************************************/ 218/* */ 219/* Structures */ 220/* */ 221/****************************************************************************************/ 222 223/* Memory region definition */ 224typedef struct 225{ 226 LVM_UINT32 Size; /* Region size in bytes */ 227 LVM_UINT16 Alignment; /* Region alignment in bytes */ 228 LVDBE_MemoryTypes_en Type; /* Region type */ 229 void *pBaseAddress; /* Pointer to the region base address */ 230} LVDBE_MemoryRegion_t; 231 232 233/* Memory table containing the region definitions */ 234typedef struct 235{ 236 LVDBE_MemoryRegion_t Region[LVDBE_NR_MEMORY_REGIONS]; /* One definition for each region */ 237} LVDBE_MemTab_t; 238 239 240/* Parameter structure */ 241typedef struct 242{ 243 LVDBE_Mode_en OperatingMode; 244 LVDBE_Fs_en SampleRate; 245 LVM_INT16 EffectLevel; 246 LVDBE_CentreFreq_en CentreFrequency; 247 LVDBE_FilterSelect_en HPFSelect; 248 LVDBE_Volume_en VolumeControl; 249 LVM_INT16 VolumedB; 250 LVM_INT16 HeadroomdB; 251 252} LVDBE_Params_t; 253 254 255/* Capability structure */ 256typedef struct 257{ 258 LVM_UINT16 SampleRate; /* Sampling rate capabilities */ 259 LVM_UINT16 CentreFrequency; /* Centre frequency capabilities */ 260 LVM_UINT16 MaxBlockSize; /* Maximum block size in sample pairs */ 261} LVDBE_Capabilities_t; 262 263 264/****************************************************************************************/ 265/* */ 266/* Function Prototypes */ 267/* */ 268/****************************************************************************************/ 269 270/****************************************************************************************/ 271/* */ 272/* FUNCTION: LVDBE_Memory */ 273/* */ 274/* DESCRIPTION: */ 275/* This function is used for memory allocation and free. It can be called in */ 276/* two ways: */ 277/* */ 278/* hInstance = NULL Returns the memory requirements */ 279/* hInstance = Instance handle Returns the memory requirements and */ 280/* allocated base addresses for the instance */ 281/* */ 282/* When this function is called for memory allocation (hInstance=NULL) the memory */ 283/* base address pointers are NULL on return. */ 284/* */ 285/* When the function is called for free (hInstance = Instance Handle) the memory */ 286/* table returns the allocated memory and base addresses used during initialisation. */ 287/* */ 288/* PARAMETERS: */ 289/* hInstance Instance Handle */ 290/* pMemoryTable Pointer to an empty memory definition table */ 291/* pCapabilities Pointer to the default capabilites */ 292/* */ 293/* RETURNS: */ 294/* LVDBE_SUCCESS Succeeded */ 295/* */ 296/* NOTES: */ 297/* 1. This function may be interrupted by the LVDBE_Process function */ 298/* */ 299/****************************************************************************************/ 300 301LVDBE_ReturnStatus_en LVDBE_Memory(LVDBE_Handle_t hInstance, 302 LVDBE_MemTab_t *pMemoryTable, 303 LVDBE_Capabilities_t *pCapabilities); 304 305 306/****************************************************************************************/ 307/* */ 308/* FUNCTION: LVDBE_Init */ 309/* */ 310/* DESCRIPTION: */ 311/* Create and initialisation function for the Bass Enhancement module */ 312/* */ 313/* This function can be used to create an algorithm instance by calling with */ 314/* hInstance set to NULL. In this case the algorithm returns the new instance */ 315/* handle. */ 316/* */ 317/* This function can be used to force a full re-initialisation of the algorithm */ 318/* by calling with hInstance = Instance Handle. In this case the memory table */ 319/* should be correct for the instance, this can be ensured by calling the function */ 320/* LVDBE_Memory before calling this function. */ 321/* */ 322/* PARAMETERS: */ 323/* hInstance Instance handle */ 324/* pMemoryTable Pointer to the memory definition table */ 325/* pCapabilities Pointer to the initialisation capabilities */ 326/* */ 327/* RETURNS: */ 328/* LVDBE_SUCCESS Initialisation succeeded */ 329/* LVDBE_ALIGNMENTERROR Instance or scratch memory on incorrect alignment */ 330/* LVDBE_NULLADDRESS One or more memory has a NULL pointer */ 331/* */ 332/* NOTES: */ 333/* 1. The instance handle is the pointer to the base address of the first memory */ 334/* region. */ 335/* 2. This function must not be interrupted by the LVDBE_Process function */ 336/* */ 337/****************************************************************************************/ 338 339LVDBE_ReturnStatus_en LVDBE_Init(LVDBE_Handle_t *phInstance, 340 LVDBE_MemTab_t *pMemoryTable, 341 LVDBE_Capabilities_t *pCapabilities); 342 343 344/****************************************************************************************/ 345/* */ 346/* FUNCTION: LVDBE_GetParameters */ 347/* */ 348/* DESCRIPTION: */ 349/* Request the Bass Enhancement parameters. The current parameter set is returned */ 350/* via the parameter pointer. */ 351/* */ 352/* PARAMETERS: */ 353/* hInstance Instance handle */ 354/* pParams Pointer to an empty parameter structure */ 355/* */ 356/* RETURNS: */ 357/* LVDBE_SUCCESS Always succeeds */ 358/* */ 359/* NOTES: */ 360/* 1. This function may be interrupted by the LVDBE_Process function */ 361/* */ 362/****************************************************************************************/ 363 364LVDBE_ReturnStatus_en LVDBE_GetParameters(LVDBE_Handle_t hInstance, 365 LVDBE_Params_t *pParams); 366 367 368/****************************************************************************************/ 369/* */ 370/* FUNCTION: LVDBE_GetCapabilities */ 371/* */ 372/* DESCRIPTION: */ 373/* Request the Dynamic Bass Enhancement capabilities. The initial capabilities are */ 374/* returned via the pointer. */ 375/* */ 376/* PARAMETERS: */ 377/* hInstance Instance handle */ 378/* pCapabilities Pointer to an empty capabilitiy structure */ 379/* */ 380/* RETURNS: */ 381/* LVDBE_Success Always succeeds */ 382/* */ 383/* NOTES: */ 384/* 1. This function may be interrupted by the LVDBE_Process function */ 385/* */ 386/****************************************************************************************/ 387 388LVDBE_ReturnStatus_en LVDBE_GetCapabilities(LVDBE_Handle_t hInstance, 389 LVDBE_Capabilities_t *pCapabilities); 390 391 392/****************************************************************************************/ 393/* */ 394/* FUNCTION: LVDBE_Control */ 395/* */ 396/* DESCRIPTION: */ 397/* Sets or changes the Bass Enhancement parameters. Changing the parameters while the */ 398/* module is processing signals may have the following side effects: */ 399/* */ 400/* General parameters: */ 401/* =================== */ 402/* OperatingMode: Changing the mode of operation may cause a change in volume */ 403/* level. */ 404/* */ 405/* SampleRate: Changing the sample rate may cause pops and clicks. */ 406/* */ 407/* EffectLevel: Changing the effect level setting will have no side effects */ 408/* */ 409/* CentreFrequency: Changing the centre frequency may cause pops and clicks */ 410/* */ 411/* HPFSelect: Selecting/de-selecting the high pass filter may cause pops and */ 412/* clicks */ 413/* */ 414/* VolumedB Changing the volume setting will have no side effects */ 415/* */ 416/* */ 417/* PARAMETERS: */ 418/* hInstance Instance handle */ 419/* pParams Pointer to a parameter structure */ 420/* */ 421/* RETURNS: */ 422/* LVDBE_SUCCESS Always succeeds */ 423/* */ 424/* NOTES: */ 425/* 1. This function must not be interrupted by the LVDBE_Process function */ 426/* */ 427/****************************************************************************************/ 428 429LVDBE_ReturnStatus_en LVDBE_Control(LVDBE_Handle_t hInstance, 430 LVDBE_Params_t *pParams); 431 432 433/****************************************************************************************/ 434/* */ 435/* FUNCTION: LVDBE_Process */ 436/* */ 437/* DESCRIPTION: */ 438/* Process function for the Bass Enhancement module. */ 439/* */ 440/* PARAMETERS: */ 441/* hInstance Instance handle */ 442/* pInData Pointer to the input data */ 443/* pOutData Pointer to the output data */ 444/* NumSamples Number of samples in the input buffer */ 445/* */ 446/* RETURNS: */ 447/* LVDBE_SUCCESS Succeeded */ 448/* LVDBE_TOOMANYSAMPLES NumSamples was larger than the maximum block size */ 449/* */ 450/* NOTES: */ 451/* */ 452/****************************************************************************************/ 453 454LVDBE_ReturnStatus_en LVDBE_Process(LVDBE_Handle_t hInstance, 455 const LVM_INT16 *pInData, 456 LVM_INT16 *pOutData, 457 LVM_UINT16 NumSamples); 458 459 460#ifdef __cplusplus 461} 462#endif /* __cplusplus */ 463 464#endif /* __LVDBE_H__ */ 465