xref: /frameworks/av/media/libeffects/lvm/lib/Eq/lib/LVEQNB.h

/*
 * Copyright (C) 2004-2010 NXP Software
 * Copyright (C) 2010 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/****************************************************************************************/
/*                                                                                      */
/*  Header file for the application layer interface of the N-Band equaliser.            */
/*                                                                                      */
/*  This files includes all definitions, types, structures and function                 */
/*  prototypes required by the calling layer. All other types, structures and           */
/*  functions are private.                                                              */
/*                                                                                      */
/****************************************************************************************/
/*                                                                                      */
/*  Note: 1                                                                             */
/*  =======                                                                             */
/*  The algorithm can execute either with separate input and output buffers or with     */
/*  a common buffer, i.e. the data is processed in-place.                               */
/*                                                                                      */
/****************************************************************************************/
/*                                                                                      */
/*  Note: 2                                                                             */
/*  =======                                                                             */
/*  Two data formats are support Stereo and Mono-In-Stereo. The data is interleaved as  */
/*  follows:                                                                            */
/*              Byte Offset         Stereo Input         Mono-In-Stereo Input           */
/*              ===========         ============         ====================           */
/*                  0               Left Sample #1          Mono Sample #1              */
/*                  2               Right Sample #1         Mono Sample #1              */
/*                  4               Left Sample #2          Mono Sample #2              */
/*                  6               Right Sample #2         Mono Sample #2              */
/*                  .                      .                     .                      */
/*                  .                      .                     .                      */
/*                                                                                      */
/*  Mono format data is not supported, the calling routine must convert a Mono stream   */
/*  in to Mono-In-Stereo format.                                                        */
/*                                                                                      */
/****************************************************************************************/
/*                                                                                      */
/*  Note: 3                                                                             */
/*  =======                                                                             */
/*  The format of the data in the filter band definition structure is as follows:       */
/*                                                                                      */
/*      Gain        is in integer dB, range -15dB to +15dB inclusive                    */
/*      Frequency   is the centre frequency in Hz, range DC to Nyquist                  */
/*      QFactor     is the Q multiplied by 100, range 0.25 (25) to 12 (1200)            */
/*                                                                                      */
/*  Example:                                                                            */
/*      Gain = 7            7dB gain                                                    */
/*      Frequency = 2467    Centre frequency = 2.467kHz                                 */
/*      QFactor = 1089      Q = 10.89                                                   */
/*                                                                                      */
/*  The equaliser filters are passed as a pointer to and array of filter band           */
/*  definitions structures. There must be one filter definition for each band.          */
/*                                                                                      */
/****************************************************************************************/


#ifndef __LVEQNB_H__
#define __LVEQNB_H__

#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */


/****************************************************************************************/
/*                                                                                      */
/*  Includes                                                                            */
/*                                                                                      */
/****************************************************************************************/

#include "LVM_Types.h"
#include "LVM_Common.h"

/****************************************************************************************/
/*                                                                                      */
/*  Definitions                                                                         */
/*                                                                                      */
/****************************************************************************************/

/* Memory table */
#define LVEQNB_MEMREGION_INSTANCE          0   /* Offset to the instance memory region */
#define LVEQNB_MEMREGION_PERSISTENT_DATA   1   /* Offset to persistent data memory region */
#define LVEQNB_MEMREGION_PERSISTENT_COEF   2   /* Offset to persistent coefficient region */
#define LVEQNB_MEMREGION_SCRATCH           3   /* Offset to data scratch memory region */
#define LVEQNB_NR_MEMORY_REGIONS           4   /* Number of memory regions */

/* Callback events */
#define LVEQNB_EVENT_NONE                   0x0000    /* Not a valid event */
#define LVEQNB_EVENT_ALGOFF                 0x0001    /* EQNB has completed switch off */

/****************************************************************************************/
/*                                                                                      */
/*  Types                                                                               */
/*                                                                                      */
/****************************************************************************************/

/* Instance handle */
typedef void *LVEQNB_Handle_t;


/* Operating modes */
typedef enum
{
    LVEQNB_BYPASS   = 0,
    LVEQNB_ON       = 1,
    LVEQNB_MODE_MAX = LVM_MAXINT_32
} LVEQNB_Mode_en;


/* Filter mode control */
typedef enum
{
    LVEQNB_FILTER_OFF   = 0,
    LVEQNB_FILTER_ON    = 1,
    LVEQNB_FILTER_DUMMY = LVM_MAXINT_32
} LVEQNB_FilterMode_en;


/* Memory Types */
typedef enum
{
    LVEQNB_PERSISTENT      = 0,
    LVEQNB_PERSISTENT_DATA = 1,
    LVEQNB_PERSISTENT_COEF = 2,
    LVEQNB_SCRATCH         = 3,
    LVEQNB_MEMORY_MAX      = LVM_MAXINT_32
} LVEQNB_MemoryTypes_en;


/* Function return status */
typedef enum
{
    LVEQNB_SUCCESS        = 0,                          /* Successful return from a routine */
    LVEQNB_ALIGNMENTERROR = 1,                          /* Memory alignment error */
    LVEQNB_NULLADDRESS    = 2,                          /* NULL allocation address */
    LVEQNB_TOOMANYSAMPLES = 3,                          /* Maximum block size exceeded */
    LVEQNB_STATUS_MAX     = LVM_MAXINT_32
} LVEQNB_ReturnStatus_en;


/****************************************************************************************/
/*                                                                                      */
/*  Linked enumerated type and capability definitions                                   */
/*                                                                                      */
/*  The capability definitions are used to define the required capabilities at          */
/*  initialisation, these are added together to give the capability word. The           */
/*  enumerated type is used to select the mode through a control function at run time.  */
/*                                                                                      */
/*  The capability definition is related to the enumerated type value by the equation:  */
/*                                                                                      */
/*          Capability_value = 2^Enumerated_value                                       */
/*                                                                                      */
/*  For example, a module could be configurd at initialisation to support two sample    */
/*  rates only by calling the init function with the value:                             */
/*      Capabilities.SampleRate = LVEQNB_CAP_32000 + LVEQNB_CAP_44100;                  */
/*                                                                                      */
/*  and at run time it would be passed the value LVEQNB_FS_32000 through the control    */
/*  function to select operation at 32kHz                                               */
/*                                                                                      */
/****************************************************************************************/

/*
 * Supported source data formats
 */
#define LVEQNB_CAP_STEREO                  1
#define LVEQNB_CAP_MONOINSTEREO            2

typedef enum
{
    LVEQNB_STEREO       = 0,
    LVEQNB_MONOINSTEREO = 1,
    LVEQNB_SOURCE_MAX   = LVM_MAXINT_32
} LVEQNB_SourceFormat_en;


/*
 * Supported sample rates in samples per second
 */
#define LVEQNB_CAP_FS_8000                 1
#define LVEQNB_CAP_FS_11025                2
#define LVEQNB_CAP_FS_12000                4
#define LVEQNB_CAP_FS_16000                8
#define LVEQNB_CAP_FS_22050                16
#define LVEQNB_CAP_FS_24000                32
#define LVEQNB_CAP_FS_32000                64
#define LVEQNB_CAP_FS_44100                128
#define LVEQNB_CAP_FS_48000                256

typedef enum
{
    LVEQNB_FS_8000  = 0,
    LVEQNB_FS_11025 = 1,
    LVEQNB_FS_12000 = 2,
    LVEQNB_FS_16000 = 3,
    LVEQNB_FS_22050 = 4,
    LVEQNB_FS_24000 = 5,
    LVEQNB_FS_32000 = 6,
    LVEQNB_FS_44100 = 7,
    LVEQNB_FS_48000 = 8,
    LVEQNB_FS_MAX   = LVM_MAXINT_32
} LVEQNB_Fs_en;


/****************************************************************************************/
/*                                                                                      */
/*  Structures                                                                          */
/*                                                                                      */
/****************************************************************************************/

/* Memory region definition */
typedef struct
{
    LVM_UINT32                  Size;                   /* Region size in bytes */
    LVM_UINT16                  Alignment;              /* Region alignment in bytes */
    LVEQNB_MemoryTypes_en       Type;                   /* Region type */
    void                        *pBaseAddress;          /* Pointer to the region base address */
} LVEQNB_MemoryRegion_t;


/* Memory table containing the region definitions */
typedef struct
{
    LVEQNB_MemoryRegion_t       Region[LVEQNB_NR_MEMORY_REGIONS];  /* One definition for each region */
} LVEQNB_MemTab_t;


/* Equaliser band definition */
typedef struct
{
    LVM_INT16                   Gain;                   /* Band gain in dB */
    LVM_UINT16                  Frequency;              /* Band centre frequency in Hz */
    LVM_UINT16                  QFactor;                /* Band quality factor */
} LVEQNB_BandDef_t;


/* Parameter structure */
typedef struct
{
    /* General parameters */
    LVEQNB_Mode_en              OperatingMode;
    LVEQNB_Fs_en                SampleRate;
    LVEQNB_SourceFormat_en      SourceFormat;

    /* Equaliser parameters */
    LVM_UINT16                  NBands;                 /* Number of bands */
    LVEQNB_BandDef_t            *pBandDefinition;       /* Pointer to equaliser definitions */

} LVEQNB_Params_t;


/* Capability structure */
typedef struct
{
    /* General parameters */
    LVM_UINT16                  SampleRate;
    LVM_UINT16                  SourceFormat;
    LVM_UINT16                  MaxBlockSize;
    LVM_UINT16                  MaxBands;

    /* Callback parameters */
    LVM_Callback                CallBack;               /* Bundle callback */
    void                        *pBundleInstance;       /* Bundle instance handle */

} LVEQNB_Capabilities_t;


/****************************************************************************************/
/*                                                                                      */
/*  Function Prototypes                                                                 */
/*                                                                                      */
/****************************************************************************************/

/****************************************************************************************/
/*                                                                                      */
/* FUNCTION:                LVEQNB_Memory                                               */
/*                                                                                      */
/* DESCRIPTION:                                                                         */
/*  This function is used for memory allocation and free. It can be called in           */
/*  two ways:                                                                           */
/*                                                                                      */
/*      hInstance = NULL                Returns the memory requirements                 */
/*      hInstance = Instance handle     Returns the memory requirements and             */
/*                                      allocated base addresses for the instance       */
/*                                                                                      */
/*  When this function is called for memory allocation (hInstance=NULL) the memory      */
/*  base address pointers are NULL on return.                                           */
/*                                                                                      */
/*  When the function is called for free (hInstance = Instance Handle) the memory       */
/*  table returns the allocated memory and base addresses used during initialisation.   */
/*                                                                                      */
/* PARAMETERS:                                                                          */
/*  hInstance               Instance Handle                                             */
/*  pMemoryTable            Pointer to an empty memory definition table                 */
/*  pCapabilities           Pointer to the default capabilities                         */
/*                                                                                      */
/* RETURNS:                                                                             */
/*  LVEQNB_SUCCESS          Succeeded                                                   */
/*  LVEQNB_NULLADDRESS      When any of pMemoryTable and pCapabilities is NULL address  */
/*                                                                                      */
/* NOTES:                                                                               */
/*  1.  This function may be interrupted by the LVEQNB_Process function                 */
/*                                                                                      */
/****************************************************************************************/

LVEQNB_ReturnStatus_en LVEQNB_Memory(LVEQNB_Handle_t            hInstance,
                                     LVEQNB_MemTab_t            *pMemoryTable,
                                     LVEQNB_Capabilities_t      *pCapabilities);


/****************************************************************************************/
/*                                                                                      */
/* FUNCTION:                LVEQNB_Init                                                 */
/*                                                                                      */
/* DESCRIPTION:                                                                         */
/*  Create and initialisation function for the N-Band equalliser module                 */
/*                                                                                      */
/*  This function can be used to create an algorithm instance by calling with           */
/*  hInstance set to NULL. In this case the algorithm returns the new instance          */
/*  handle.                                                                             */
/*                                                                                      */
/*  This function can be used to force a full re-initialisation of the algorithm        */
/*  by calling with hInstance = Instance Handle. In this case the memory table          */
/*  should be correct for the instance, this can be ensured by calling the function     */
/*  LVEQNB_Memory before calling this function.                                         */
/*                                                                                      */
/* PARAMETERS:                                                                          */
/*  hInstance               Instance handle                                             */
/*  pMemoryTable            Pointer to the memory definition table                      */
/*  pCapabilities           Pointer to the initialisation capabilities                  */
/*                                                                                      */
/* RETURNS:                                                                             */
/*  LVEQNB_SUCCESS          Initialisation succeeded                                    */
/*  LVEQNB_NULLADDRESS        When pCapabilities or pMemoryTableis or phInstance are NULL */
/*  LVEQNB_NULLADDRESS        One or more of the memory regions has a NULL base address   */
/*                          pointer for a memory region with a non-zero size.           */
/*                                                                                      */
/*                                                                                      */
/* NOTES:                                                                               */
/*  1.  The instance handle is the pointer to the base address of the first memory      */
/*      region.                                                                         */
/*  2.  This function must not be interrupted by the LVEQNB_Process function            */
/*                                                                                      */
/****************************************************************************************/

LVEQNB_ReturnStatus_en LVEQNB_Init(LVEQNB_Handle_t          *phInstance,
                                   LVEQNB_MemTab_t          *pMemoryTable,
                                   LVEQNB_Capabilities_t    *pCapabilities);


/****************************************************************************************/
/*                                                                                      */
/* FUNCTION:                 LVEQNB_GetParameters                                       */
/*                                                                                      */
/* DESCRIPTION:                                                                         */
/*  Request the equaliser module parameters. The current parameter set is returned      */
/*  via the parameter pointer.                                                          */
/*                                                                                      */
/* PARAMETERS:                                                                          */
/*  hInstance                Instance handle                                            */
/*  pParams                  Pointer to an empty parameter structure                    */
/*                                                                                      */
/* RETURNS:                                                                             */
/*  LVEQNB_SUCCESS           Succeeds                                                   */
/*  LVEQNB_NULLADDRESS       Instance or pParams  is NULL pointer                       */
/*                                                                                      */
/* NOTES:                                                                               */
/*  1.  This function may be interrupted by the LVEQNB_Process function                 */
/*                                                                                      */
/****************************************************************************************/

LVEQNB_ReturnStatus_en LVEQNB_GetParameters(LVEQNB_Handle_t     hInstance,
                                            LVEQNB_Params_t     *pParams);


/****************************************************************************************/
/*                                                                                      */
/* FUNCTION:                 LVEQNB_GetCapabilities                                     */
/*                                                                                      */
/* DESCRIPTION:                                                                         */
/*  Request the equaliser module capabilities. The capabilities set is returned         */
/*  via the pointer.                                                                    */
/*                                                                                      */
/* PARAMETERS:                                                                          */
/*  hInstance                Instance handle                                            */
/*  pCapabilities            Pointer to an empty capability structure                   */
/*                                                                                      */
/* RETURNS:                                                                             */
/*  LVEQNB_SUCCESS           Succeeds                                                   */
/*  LVEQNB_NULLADDRESS       hInstance or pCapabilities is NULL                         */
/*                                                                                      */
/* NOTES:                                                                               */
/*  1.  This function may be interrupted by the LVEQNB_Process function                 */
/*                                                                                      */
/****************************************************************************************/

LVEQNB_ReturnStatus_en LVEQNB_GetCapabilities(LVEQNB_Handle_t           hInstance,
                                              LVEQNB_Capabilities_t     *pCapabilities);


/****************************************************************************************/
/*                                                                                      */
/* FUNCTION:                LVEQNB_Control                                              */
/*                                                                                      */
/* DESCRIPTION:                                                                         */
/*  Sets or changes the equaliser module parameters.                                    */
/*                                                                                      */
/* PARAMETERS:                                                                          */
/*  hInstance               Instance handle                                             */
/*  pParams                 Pointer to a parameter structure                            */
/*                                                                                      */
/* RETURNS:                                                                             */
/*  LVEQNB_SUCCESS          Succeeded                                                   */
/*  LVEQNB_NULLADDRESS      Instance or pParams  is NULL pointer                        */
/*  LVEQNB_NULLADDRESS      NULL address for the equaliser filter definitions and the   */
/*                          number of bands is non-zero                                 */
/*                                                                                      */
/* NOTES:                                                                               */
/*  1.  This function may be interrupted by the LVEQNB_Process function                 */
/*                                                                                      */
/****************************************************************************************/

LVEQNB_ReturnStatus_en LVEQNB_Control(LVEQNB_Handle_t       hInstance,
                                      LVEQNB_Params_t       *pParams);


/****************************************************************************************/
/*                                                                                      */
/* FUNCTION:                LVEQNB_Process                                              */
/*                                                                                      */
/* DESCRIPTION:                                                                         */
/*  Process function for the LifeVibes module.                                          */
/*                                                                                      */
/* PARAMETERS:                                                                          */
/*  hInstance               Instance handle                                             */
/*  pInData                 Pointer to the input data                                   */
/*  pOutData                Pointer to the output data                                  */
/*  NumSamples              Number of samples in the input buffer                       */
/*                                                                                      */
/* RETURNS:                                                                             */
/*  LVEQNB_SUCCESS          Succeeded                                                   */
/*  LVEQNB_NULLADDRESS      When hInstance, pInData or pOutData are NULL                */
/*  LVEQNB_ALIGNMENTERROR   When pInData or pOutData are not 32-bit aligned             */
/*  LVEQNB_TOOMANYSAMPLES   NumSamples was larger than the maximum block size           */
/*                                                                                      */
/* NOTES:                                                                               */
/*                                                                                      */
/****************************************************************************************/

LVEQNB_ReturnStatus_en LVEQNB_Process(LVEQNB_Handle_t       hInstance,
                                      const LVM_INT16       *pInData,
                                      LVM_INT16             *pOutData,
                                      LVM_UINT16            NumSamples);



#ifdef __cplusplus
}
#endif /* __cplusplus */

#endif      /* __LVEQNB__ */