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