Home | History | Annotate | Download | only in lib
      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
     59 extern "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 */
     96 typedef void    *LVDBE_Handle_t;
     97 
     98 
     99 /* Operating modes */
    100 typedef 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 */
    109 typedef 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 */
    118 typedef 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 */
    127 typedef 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 */
    139 typedef 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 
    179 typedef 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 #if defined(BUILD_FLOAT) && defined(HIGHER_FS)
    202 #define LVDBE_CAP_FS_96000               512
    203 #define LVDBE_CAP_FS_192000              1024
    204 #endif
    205 
    206 typedef enum
    207 {
    208     LVDBE_FS_8000  = 0,
    209     LVDBE_FS_11025 = 1,
    210     LVDBE_FS_12000 = 2,
    211     LVDBE_FS_16000 = 3,
    212     LVDBE_FS_22050 = 4,
    213     LVDBE_FS_24000 = 5,
    214     LVDBE_FS_32000 = 6,
    215     LVDBE_FS_44100 = 7,
    216     LVDBE_FS_48000 = 8,
    217 #if defined(BUILD_FLOAT) && defined(HIGHER_FS)
    218     LVDBE_FS_96000 = 9,
    219     LVDBE_FS_192000 = 10,
    220 #endif
    221     LVDBE_FS_MAX   = LVM_MAXINT_32
    222 } LVDBE_Fs_en;
    223 
    224 
    225 /****************************************************************************************/
    226 /*                                                                                      */
    227 /*    Structures                                                                        */
    228 /*                                                                                      */
    229 /****************************************************************************************/
    230 
    231 /* Memory region definition */
    232 typedef 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 */
    242 typedef 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 */
    249 typedef 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 */
    264 typedef 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 
    309 LVDBE_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 
    347 LVDBE_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 
    372 LVDBE_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 
    396 LVDBE_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 
    437 LVDBE_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 #ifdef BUILD_FLOAT
    462 LVDBE_ReturnStatus_en LVDBE_Process(LVDBE_Handle_t          hInstance,
    463                                        const LVM_FLOAT      *pInData,
    464                                        LVM_FLOAT            *pOutData,
    465                                        LVM_UINT16           NumSamples);
    466 #else
    467 LVDBE_ReturnStatus_en LVDBE_Process(LVDBE_Handle_t          hInstance,
    468                                        const LVM_INT16      *pInData,
    469                                        LVM_INT16            *pOutData,
    470                                        LVM_UINT16           NumSamples);
    471 #endif
    472 
    473 #ifdef __cplusplus
    474 }
    475 #endif /* __cplusplus */
    476 
    477 #endif /* __LVDBE_H__ */
    478