| /* |
| * 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__ */ |
| |
