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 #ifndef _LVPSA_H_
     19 #define _LVPSA_H_
     20 
     21 
     22 #include "LVM_Types.h"
     23 
     24 
     25 #ifdef __cplusplus
     26 extern "C" {
     27 #endif /* __cplusplus */
     28 
     29 /****************************************************************************************/
     30 /*                                                                                      */
     31 /*  CONSTANTS DEFINITIONS                                                               */
     32 /*                                                                                      */
     33 /****************************************************************************************/
     34 
     35 /* Memory table*/
     36 #define     LVPSA_NR_MEMORY_REGIONS                  4      /* Number of memory regions                                          */
     37 
     38 /****************************************************************************************/
     39 /*                                                                                      */
     40 /*  TYPES DEFINITIONS                                                                   */
     41 /*                                                                                      */
     42 /****************************************************************************************/
     43 /* Memory Types */
     44 typedef enum
     45 {
     46     LVPSA_PERSISTENT      = LVM_PERSISTENT,
     47     LVPSA_PERSISTENT_DATA = LVM_PERSISTENT_DATA,
     48     LVPSA_PERSISTENT_COEF = LVM_PERSISTENT_COEF,
     49     LVPSA_SCRATCH         = LVM_SCRATCH,
     50     LVPSA_MEMORY_DUMMY = LVM_MAXINT_32                      /* Force 32 bits enum, don't use it!                                 */
     51 } LVPSA_MemoryTypes_en;
     52 
     53 /* Level detection speed control parameters */
     54 typedef enum
     55 {
     56     LVPSA_SPEED_LOW,                                        /* Low speed level   detection                                       */
     57     LVPSA_SPEED_MEDIUM,                                     /* Medium speed level   detection                                    */
     58     LVPSA_SPEED_HIGH,                                       /* High speed level   detection                                      */
     59     LVPSA_SPEED_DUMMY = LVM_MAXINT_32                       /* Force 32 bits enum, don't use it!                                 */
     60 } LVPSA_LevelDetectSpeed_en;
     61 
     62 /* Filter control parameters */
     63 typedef struct
     64 {
     65     LVM_UINT16                 CenterFrequency;             /* Center frequency of the band-pass filter (in Hz)                  */
     66     LVM_UINT16                 QFactor;                     /* Quality factor of the filter             (in 1/100)               */
     67     LVM_INT16                  PostGain;                    /* Postgain to apply after the filtering    (in dB Q16.0)            */
     68 
     69 } LVPSA_FilterParam_t;
     70 
     71 /* LVPSA initialization parameters */
     72 typedef struct
     73 {
     74     LVM_UINT16                 SpectralDataBufferDuration;  /* Spectral data buffer duration in time (ms in Q16.0)               */
     75     LVM_UINT16                 MaxInputBlockSize;           /* Maximum expected input block size (in samples)                    */
     76     LVM_UINT16                 nBands;                      /* Number of bands of the SA                                         */
     77     LVPSA_FilterParam_t       *pFiltersParams;              /* Points to nBands filter param structures for filters settings     */
     78 
     79 } LVPSA_InitParams_t, *pLVPSA_InitParams_t;
     80 
     81 /* LVPSA control parameters */
     82 typedef struct
     83 {
     84     LVM_Fs_en                  Fs;                          /* Input sampling rate                                               */
     85     LVPSA_LevelDetectSpeed_en  LevelDetectionSpeed;         /* Level detection speed                                             */
     86 
     87 } LVPSA_ControlParams_t, *pLVPSA_ControlParams_t;
     88 
     89 /* Memory region definition */
     90 typedef struct
     91 {
     92     LVM_UINT32                 Size;                        /* Region size in bytes                                              */
     93     LVPSA_MemoryTypes_en       Type;                        /* Region type                                                       */
     94     void                       *pBaseAddress;               /* Pointer to the region base address                                */
     95 } LVPSA_MemoryRegion_t;
     96 
     97 /* Memory table containing the region definitions */
     98 typedef struct
     99 {
    100     LVPSA_MemoryRegion_t       Region[LVPSA_NR_MEMORY_REGIONS];/* One definition for each region                                 */
    101 } LVPSA_MemTab_t;
    102 
    103 /* Audio time type */
    104 typedef LVM_INT32 LVPSA_Time;
    105 
    106 /* Module instance Handle */
    107 typedef void *pLVPSA_Handle_t;
    108 
    109 /* LVPSA return codes */
    110 typedef enum
    111 {
    112     LVPSA_OK,                                               /* The function ran without any problem                              */
    113     LVPSA_ERROR_INVALIDPARAM,                               /* A parameter is incorrect                                          */
    114     LVPSA_ERROR_WRONGTIME,                                  /* An incorrect AudioTime is used                                    */
    115     LVPSA_ERROR_NULLADDRESS,                                /* A pointer has a NULL value                                        */
    116     LVPSA_RETURN_DUMMY = LVM_MAXINT_32                      /* Force 32 bits enum, don't use it!                                 */
    117 } LVPSA_RETURN;
    118 
    119 
    120 
    121 /*********************************************************************************************************************************
    122    FUNCTIONS PROTOTYPE
    123 **********************************************************************************************************************************/
    124 /*********************************************************************************************************************************/
    125 /*                                                                                                                               */
    126 /* FUNCTION:            LVPSA_Memory                                                                                         */
    127 /*                                                                                                                               */
    128 /* DESCRIPTION:                                                                                                                  */
    129 /*  This function is used for memory allocation and free. It can be called in                                                    */
    130 /*  two ways:                                                                                                                    */
    131 /*                                                                                                                               */
    132 /*      hInstance = NULL                Returns the memory requirements                                                          */
    133 /*      hInstance = Instance handle     Returns the memory requirements and                                                      */
    134 /*                                      allocated base addresses for the instance                                                */
    135 /*                                                                                                                               */
    136 /*  When this function is called for memory allocation (hInstance=NULL) the memory                                               */
    137 /*  base address pointers are NULL on return.                                                                                    */
    138 /*                                                                                                                               */
    139 /*  When the function is called for free (hInstance = Instance Handle) the memory                                                */
    140 /*  table returns the allocated memory and base addresses used during initialisation.                                            */
    141 /*                                                                                                                               */
    142 /* PARAMETERS:                                                                                                                   */
    143 /*  hInstance           Instance Handle                                                                                          */
    144 /*  pMemoryTable        Pointer to an empty memory definition table                                                              */
    145 /*  pInitParams         Pointer to the instance init parameters                                                                  */
    146 /*                                                                                                                               */
    147 /* RETURNS:                                                                                                                      */
    148 /*  LVPSA_OK            Succeeds                                                                                                 */
    149 /*  otherwise           Error due to bad parameters                                                                              */
    150 /*                                                                                                                               */
    151 /*********************************************************************************************************************************/
    152 LVPSA_RETURN LVPSA_Memory            ( pLVPSA_Handle_t             hInstance,
    153                                        LVPSA_MemTab_t             *pMemoryTable,
    154                                        LVPSA_InitParams_t         *pInitParams    );
    155 
    156 /*********************************************************************************************************************************/
    157 /*                                                                                                                               */
    158 /* FUNCTION:            LVPSA_Init                                                                                               */
    159 /*                                                                                                                               */
    160 /* DESCRIPTION:                                                                                                                  */
    161 /*  Initializes the LVPSA module.                                                                                                */
    162 /*                                                                                                                               */
    163 /*                                                                                                                               */
    164 /* PARAMETERS:                                                                                                                   */
    165 /*  phInstance          Pointer to the instance Handle                                                                           */
    166 /*  pInitParams         Pointer to the instance init parameters                                                                  */
    167 /*  pControlParams      Pointer to the instance control parameters                                                               */
    168 /*  pMemoryTable        Pointer to the memory definition table                                                                   */
    169 /*                                                                                                                               */
    170 /*                                                                                                                               */
    171 /* RETURNS:                                                                                                                      */
    172 /*  LVPSA_OK            Succeeds                                                                                                 */
    173 /*  otherwise           Error due to bad parameters                                                                              */
    174 /*                                                                                                                               */
    175 /*********************************************************************************************************************************/
    176 LVPSA_RETURN LVPSA_Init              ( pLVPSA_Handle_t             *phInstance,
    177                                        LVPSA_InitParams_t          *pInitParams,
    178                                        LVPSA_ControlParams_t       *pControlParams,
    179                                        LVPSA_MemTab_t              *pMemoryTable  );
    180 
    181 /*********************************************************************************************************************************/
    182 /*                                                                                                                               */
    183 /* FUNCTION:            LVPSA_Control                                                                                            */
    184 /*                                                                                                                               */
    185 /* DESCRIPTION:                                                                                                                  */
    186 /*  Controls the LVPSA module.                                                                                                   */
    187 /*                                                                                                                               */
    188 /* PARAMETERS:                                                                                                                   */
    189 /*  hInstance           Instance Handle                                                                                          */
    190 /*  pNewParams          Pointer to the instance new control parameters                                                           */
    191 /*                                                                                                                               */
    192 /* RETURNS:                                                                                                                      */
    193 /*  LVPSA_OK            Succeeds                                                                                                 */
    194 /*  otherwise           Error due to bad parameters                                                                              */
    195 /*                                                                                                                               */
    196 /*********************************************************************************************************************************/
    197 LVPSA_RETURN LVPSA_Control           ( pLVPSA_Handle_t             hInstance,
    198                                        LVPSA_ControlParams_t      *pNewParams     );
    199 
    200 /*********************************************************************************************************************************/
    201 /*                                                                                                                               */
    202 /* FUNCTION:            LVPSA_Process                                                                                            */
    203 /*                                                                                                                               */
    204 /* DESCRIPTION:                                                                                                                  */
    205 /*  The process calculates the levels of the frequency bands.                                                                    */
    206 /*                                                                                                                               */
    207 /* PARAMETERS:                                                                                                                   */
    208 /*  hInstance           Instance Handle                                                                                          */
    209 /*  pLVPSA_InputSamples Pointer to the input samples buffer                                                                      */
    210 /*  InputBlockSize      Number of mono samples to process                                                                        */
    211 /*  AudioTime           Playback time of the first input sample                                                                  */
    212 /*                                                                                                                               */
    213 /*                                                                                                                               */
    214 /* RETURNS:                                                                                                                      */
    215 /*  LVPSA_OK            Succeeds                                                                                                 */
    216 /*  otherwise           Error due to bad parameters                                                                              */
    217 /*                                                                                                                               */
    218 /*********************************************************************************************************************************/
    219 LVPSA_RETURN LVPSA_Process           ( pLVPSA_Handle_t      hInstance,
    220                                        LVM_INT16           *pLVPSA_InputSamples,
    221                                        LVM_UINT16           InputBlockSize,
    222                                        LVPSA_Time           AudioTime             );
    223 
    224 /*********************************************************************************************************************************/
    225 /*                                                                                                                               */
    226 /* FUNCTION:            LVPSA_GetSpectrum                                                                                        */
    227 /*                                                                                                                               */
    228 /* DESCRIPTION:                                                                                                                  */
    229 /*  This function is used for memory allocation and free.                                                                        */
    230 /*                                                                                                                               */
    231 /*                                                                                                                               */
    232 /* PARAMETERS:                                                                                                                   */
    233 /*  hInstance            Instance Handle                                                                                         */
    234 /*  GetSpectrumAudioTime Time to retrieve the values at                                                                          */
    235 /*  pCurrentValues       Pointer to an empty buffer : Current level values output                                                */
    236 /*  pPeakValues          Pointer to an empty buffer : Peak level values output                                                   */
    237 /*                                                                                                                               */
    238 /*                                                                                                                               */
    239 /* RETURNS:                                                                                                                      */
    240 /*  LVPSA_OK            Succeeds                                                                                                 */
    241 /*  otherwise           Error due to bad parameters                                                                              */
    242 /*                                                                                                                               */
    243 /*********************************************************************************************************************************/
    244 LVPSA_RETURN LVPSA_GetSpectrum       ( pLVPSA_Handle_t      hInstance,
    245                                        LVPSA_Time           GetSpectrumAudioTime,
    246                                        LVM_UINT8           *pCurrentValues,
    247                                        LVM_UINT8           *pPeakValues           );
    248 
    249 /*********************************************************************************************************************************/
    250 /*                                                                                                                               */
    251 /* FUNCTION:            LVPSA_GetControlParams                                                                                   */
    252 /*                                                                                                                               */
    253 /* DESCRIPTION:                                                                                                                  */
    254 /*  Get the current control parameters of the LVPSA module.                                                                      */
    255 /*                                                                                                                               */
    256 /* PARAMETERS:                                                                                                                   */
    257 /*  hInstance           Instance Handle                                                                                          */
    258 /*  pParams             Pointer to an empty control parameters structure                                                         */
    259 /* RETURNS:                                                                                                                      */
    260 /*  LVPSA_OK            Succeeds                                                                                                 */
    261 /*  otherwise           Error due to bad parameters                                                                              */
    262 /*                                                                                                                               */
    263 /*********************************************************************************************************************************/
    264 LVPSA_RETURN LVPSA_GetControlParams  (    pLVPSA_Handle_t            hInstance,
    265                                           LVPSA_ControlParams_t     *pParams      );
    266 
    267 /*********************************************************************************************************************************/
    268 /*                                                                                                                               */
    269 /* FUNCTION:            LVPSA_GetInitParams                                                                                      */
    270 /*                                                                                                                               */
    271 /* DESCRIPTION:                                                                                                                  */
    272 /*  Get the initialization parameters of the LVPSA module.                                                                       */
    273 /*                                                                                                                               */
    274 /* PARAMETERS:                                                                                                                   */
    275 /*  hInstance           Instance Handle                                                                                          */
    276 /*  pParams             Pointer to an empty init parameters structure                                                            */
    277 /* RETURNS:                                                                                                                      */
    278 /*  LVPSA_OK            Succeeds                                                                                                 */
    279 /*  otherwise           Error due to bad parameters                                                                              */
    280 /*                                                                                                                               */
    281 /*********************************************************************************************************************************/
    282 LVPSA_RETURN LVPSA_GetInitParams     (    pLVPSA_Handle_t            hInstance,
    283                                           LVPSA_InitParams_t        *pParams      );
    284 
    285 
    286 #ifdef __cplusplus
    287 }
    288 #endif /* __cplusplus */
    289 
    290 #endif /* _LVPSA_H */
    291