blob: 1ff2a2cf7bc8d150d62384437af5167754f8196d [file] [log] [blame]
/*
* 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 Concert Sound, Bass Enhancement, */
/* Equalizer, Power Spectrum Analyzer, Trebble Enhancement and volume management */
/* bundle. */
/* */
/* 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 */
/* ======= */
/* Three data formats are support Stereo,Mono-In-Stereo and Mono. The data is */
/* interleaved as follows: */
/* */
/* Byte Offset Stereo Input Mono-In-Stereo Input Mono Input */
/* =========== ============ ==================== ============== */
/* 0 Left Sample #1 Mono Sample #1 Mono Sample #1 */
/* 2 Right Sample #1 Mono Sample #1 Mono Sample #2 */
/* 4 Left Sample #2 Mono Sample #2 Mono Sample #3 */
/* 6 Right Sample #2 Mono Sample #2 Mono Sample #4 */
/* . . . . */
/* . . . . */
/* */
/****************************************************************************************/
#ifndef __LVM_H__
#define __LVM_H__
#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */
/****************************************************************************************/
/* */
/* Includes */
/* */
/****************************************************************************************/
#include "LVM_Types.h"
/****************************************************************************************/
/* */
/* Definitions */
/* */
/****************************************************************************************/
/* Memory table*/
#define LVM_NR_MEMORY_REGIONS 4 /* Number of memory regions */
/* Concert Sound effect level presets */
#define LVM_CS_EFFECT_NONE 0 /* 0% effect, minimum value */
#define LVM_CS_EFFECT_LOW 16384 /* 50% effect */
#define LVM_CS_EFFECT_MED 24576 /* 75% effect */
#define LVM_CS_EFFECT_HIGH 32767 /* 100% effect, maximum value */
/* Treble enhancement */
#define LVM_TE_LOW_MIPS 32767
/* Bass enhancement effect level presets */
#define LVM_BE_0DB 0 /* 0dB boost, no effect */
#define LVM_BE_3DB 3 /* +3dB boost */
#define LVM_BE_6DB 6 /* +6dB boost */
#define LVM_BE_9DB 9 /* +9dB boost */
#define LVM_BE_12DB 12 /* +12dB boost */
#define LVM_BE_15DB 15 /* +15dB boost */
/* N-Band Equalizer */
#define LVM_EQ_NBANDS 5 /* Number of bands for equalizer */
/* Headroom management */
#define LVM_HEADROOM_MAX_NBANDS 5
/****************************************************************************************/
/* */
/* Types */
/* */
/****************************************************************************************/
/* Instance handle */
typedef void *LVM_Handle_t;
/* Status return values */
typedef enum
{
LVM_SUCCESS = 0, /* Successful return from a routine */
LVM_ALIGNMENTERROR = 1, /* Memory alignment error */
LVM_NULLADDRESS = 2, /* NULL allocation address */
LVM_OUTOFRANGE = 3, /* Out of range control parameter */
LVM_INVALIDNUMSAMPLES = 4, /* Invalid number of samples */
LVM_WRONGAUDIOTIME = 5, /* Wrong time value for audio time*/
LVM_ALGORITHMDISABLED = 6, /* Algorithm is disabled*/
LVM_ALGORITHMPSA = 7, /* Algorithm PSA returns an error */
LVM_RETURNSTATUS_DUMMY = LVM_MAXENUM
} LVM_ReturnStatus_en;
/* Buffer Management mode */
typedef enum
{
LVM_MANAGED_BUFFERS = 0,
LVM_UNMANAGED_BUFFERS = 1,
LVM_BUFFERS_DUMMY = LVM_MAXENUM
} LVM_BufferMode_en;
/* Output device type */
typedef enum
{
LVM_HEADPHONES = 0,
LVM_EX_HEADPHONES = 1,
LVM_SPEAKERTYPE_MAX = LVM_MAXENUM
} LVM_OutputDeviceType_en;
/* Virtualizer mode selection*/
typedef enum
{
LVM_CONCERTSOUND = 0,
LVM_VIRTUALIZERTYPE_DUMMY = LVM_MAXENUM
} LVM_VirtualizerType_en;
/* N-Band Equaliser operating mode */
typedef enum
{
LVM_EQNB_OFF = 0,
LVM_EQNB_ON = 1,
LVM_EQNB_DUMMY = LVM_MAXENUM
} LVM_EQNB_Mode_en;
/* Bass Enhancement operating mode */
typedef enum
{
LVM_BE_OFF = 0,
LVM_BE_ON = 1,
LVM_BE_DUMMY = LVM_MAXENUM
} LVM_BE_Mode_en;
/* Bass Enhancement centre frequency selection control */
typedef enum
{
LVM_BE_CENTRE_55Hz = 0,
LVM_BE_CENTRE_66Hz = 1,
LVM_BE_CENTRE_78Hz = 2,
LVM_BE_CENTRE_90Hz = 3,
LVM_BE_CENTRE_DUMMY = LVM_MAXENUM
} LVM_BE_CentreFreq_en;
/* Bass Enhancement HPF selection control */
typedef enum
{
LVM_BE_HPF_OFF = 0,
LVM_BE_HPF_ON = 1,
LVM_BE_HPF_DUMMY = LVM_MAXENUM
} LVM_BE_FilterSelect_en;
/* Volume Control operating mode */
typedef enum
{
LVM_VC_OFF = 0,
LVM_VC_ON = 1,
LVM_VC_DUMMY = LVM_MAXENUM
} LVM_VC_Mode_en;
/* Treble Enhancement operating mode */
typedef enum
{
LVM_TE_OFF = 0,
LVM_TE_ON = 1,
LVM_TE_DUMMY = LVM_MAXENUM
} LVM_TE_Mode_en;
/* Headroom management operating mode */
typedef enum
{
LVM_HEADROOM_OFF = 0,
LVM_HEADROOM_ON = 1,
LVM_Headroom_DUMMY = LVM_MAXENUM
} LVM_Headroom_Mode_en;
typedef enum
{
LVM_PSA_SPEED_SLOW, /* Peak decaying at slow speed */
LVM_PSA_SPEED_MEDIUM, /* Peak decaying at medium speed */
LVM_PSA_SPEED_FAST, /* Peak decaying at fast speed */
LVM_PSA_SPEED_DUMMY = LVM_MAXENUM
} LVM_PSA_DecaySpeed_en;
typedef enum
{
LVM_PSA_OFF = 0,
LVM_PSA_ON = 1,
LVM_PSA_DUMMY = LVM_MAXENUM
} LVM_PSA_Mode_en;
/* Version information */
typedef struct
{
LVM_CHAR *pVersionNumber; /* Pointer to the version number in the format X.YY.ZZ */
LVM_CHAR *pPlatform; /* Pointer to the library platform type */
} LVM_VersionInfo_st;
/****************************************************************************************/
/* */
/* Structures */
/* */
/****************************************************************************************/
/* Memory table containing the region definitions */
typedef struct
{
LVM_MemoryRegion_st Region[LVM_NR_MEMORY_REGIONS]; /* One definition for each region */
} LVM_MemTab_t;
/* N-Band 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 (x100) */
} LVM_EQNB_BandDef_t;
/* Headroom band definition */
typedef struct
{
LVM_UINT16 Limit_Low; /* Low frequency limit of the band in Hertz */
LVM_UINT16 Limit_High; /* High frequency limit of the band in Hertz */
LVM_INT16 Headroom_Offset; /* Headroom = biggest band gain - Headroom_Offset */
} LVM_HeadroomBandDef_t;
/* Control Parameter structure */
typedef struct
{
/* General parameters */
LVM_Mode_en OperatingMode; /* Bundle operating mode On/Bypass */
LVM_Fs_en SampleRate; /* Sample rate */
LVM_Format_en SourceFormat; /* Input data format */
LVM_OutputDeviceType_en SpeakerType; /* Output device type */
/* Concert Sound Virtualizer parameters*/
LVM_Mode_en VirtualizerOperatingMode; /* Virtualizer operating mode On/Off */
LVM_VirtualizerType_en VirtualizerType; /* Virtualizer type: ConcertSound */
LVM_UINT16 VirtualizerReverbLevel; /* Virtualizer reverb level in % */
LVM_INT16 CS_EffectLevel; /* Concert Sound effect level */
/* N-Band Equaliser parameters */
LVM_EQNB_Mode_en EQNB_OperatingMode; /* N-Band Equaliser operating mode */
LVM_UINT16 EQNB_NBands; /* Number of bands */
LVM_EQNB_BandDef_t *pEQNB_BandDefinition; /* Pointer to equaliser definitions */
/* Bass Enhancement parameters */
LVM_BE_Mode_en BE_OperatingMode; /* Bass Enhancement operating mode */
LVM_INT16 BE_EffectLevel; /* Bass Enhancement effect level */
LVM_BE_CentreFreq_en BE_CentreFreq; /* Bass Enhancement centre frequency */
LVM_BE_FilterSelect_en BE_HPF; /* Bass Enhancement high pass filter selector */
/* Volume Control parameters */
LVM_INT16 VC_EffectLevel; /* Volume Control setting in dBs */
LVM_INT16 VC_Balance; /* Left Right Balance control in dB (-96 to 96 dB), -ve values reduce
Right channel while +ve value reduces Left channel*/
/* Treble Enhancement parameters */
LVM_TE_Mode_en TE_OperatingMode; /* Treble Enhancement On/Off */
LVM_INT16 TE_EffectLevel; /* Treble Enhancement gain dBs */
/* Spectrum Analyzer parameters Control */
LVM_PSA_Mode_en PSA_Enable;
LVM_PSA_DecaySpeed_en PSA_PeakDecayRate; /* Peak value decay rate*/
} LVM_ControlParams_t;
/* Instance Parameter structure */
typedef struct
{
/* General */
LVM_BufferMode_en BufferMode; /* Buffer management mode */
LVM_UINT16 MaxBlockSize; /* Maximum processing block size */
/* N-Band Equaliser */
LVM_UINT16 EQNB_NumBands; /* Maximum number of equaliser bands */
/* PSA */
LVM_PSA_Mode_en PSA_Included; /* Controls the instance memory allocation for PSA: ON/OFF */
} LVM_InstParams_t;
/* Headroom management parameter structure */
typedef struct
{
LVM_Headroom_Mode_en Headroom_OperatingMode; /* Headroom Control On/Off */
LVM_HeadroomBandDef_t *pHeadroomDefinition; /* Pointer to headroom bands definition */
LVM_UINT16 NHeadroomBands; /* Number of headroom bands */
} LVM_HeadroomParams_t;
/****************************************************************************************/
/* */
/* Function Prototypes */
/* */
/****************************************************************************************/
/****************************************************************************************/
/* */
/* FUNCTION: LVM_GetVersionInfo */
/* */
/* DESCRIPTION: */
/* This function is used to retrieve information about the library's version. */
/* */
/* PARAMETERS: */
/* pVersion Pointer to an empty version info structure */
/* */
/* RETURNS: */
/* LVM_SUCCESS Succeeded */
/* LVM_NULLADDRESS when pVersion is NULL */
/* */
/* NOTES: */
/* 1. This function may be interrupted by the LVM_Process function */
/* */
/****************************************************************************************/
LVM_ReturnStatus_en LVM_GetVersionInfo(LVM_VersionInfo_st *pVersion);
/****************************************************************************************/
/* */
/* FUNCTION: LVM_GetMemoryTable */
/* */
/* 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 */
/* pInstParams Pointer to the instance parameters */
/* */
/* RETURNS: */
/* LVM_SUCCESS Succeeded */
/* LVM_NULLADDRESS When one of pMemoryTable or pInstParams is NULL */
/* LVM_OUTOFRANGE When any of the Instance parameters are out of range */
/* */
/* NOTES: */
/* 1. This function may be interrupted by the LVM_Process function */
/* */
/****************************************************************************************/
LVM_ReturnStatus_en LVM_GetMemoryTable(LVM_Handle_t hInstance,
LVM_MemTab_t *pMemoryTable,
LVM_InstParams_t *pInstParams);
/****************************************************************************************/
/* */
/* FUNCTION: LVM_GetInstanceHandle */
/* */
/* DESCRIPTION: */
/* This function is used to create a bundle instance. It returns the created instance */
/* handle through phInstance. All parameters are set to their default, inactive state. */
/* */
/* PARAMETERS: */
/* phInstance pointer to the instance handle */
/* pMemoryTable Pointer to the memory definition table */
/* pInstParams Pointer to the instance parameters */
/* */
/* RETURNS: */
/* LVM_SUCCESS Initialisation succeeded */
/* LVM_NULLADDRESS One or more memory has a NULL pointer */
/* LVM_OUTOFRANGE When any of the Instance parameters are out of range */
/* */
/* NOTES: */
/* 1. This function must not be interrupted by the LVM_Process function */
/* */
/****************************************************************************************/
LVM_ReturnStatus_en LVM_GetInstanceHandle(LVM_Handle_t *phInstance,
LVM_MemTab_t *pMemoryTable,
LVM_InstParams_t *pInstParams);
/****************************************************************************************/
/* */
/* FUNCTION: LVM_ClearAudioBuffers */
/* */
/* DESCRIPTION: */
/* This function is used to clear the internal audio buffers of the bundle. */
/* */
/* PARAMETERS: */
/* hInstance Instance handle */
/* */
/* RETURNS: */
/* LVM_SUCCESS Initialisation succeeded */
/* LVM_NULLADDRESS Instance memory has a NULL pointer */
/* */
/* NOTES: */
/* 1. This function must not be interrupted by the LVM_Process function */
/* */
/****************************************************************************************/
LVM_ReturnStatus_en LVM_ClearAudioBuffers(LVM_Handle_t hInstance);
/****************************************************************************************/
/* */
/* FUNCTION: LVM_GetControlParameters */
/* */
/* DESCRIPTION: */
/* Request the LifeVibes module parameters. The current parameter set is returned */
/* via the parameter pointer. */
/* */
/* PARAMETERS: */
/* hInstance Instance handle */
/* pParams Pointer to an empty parameter structure */
/* */
/* RETURNS: */
/* LVM_SUCCESS Succeeded */
/* LVM_NULLADDRESS when any of hInstance or pParams is NULL */
/* */
/* NOTES: */
/* 1. This function may be interrupted by the LVM_Process function */
/* */
/****************************************************************************************/
LVM_ReturnStatus_en LVM_GetControlParameters(LVM_Handle_t hInstance,
LVM_ControlParams_t *pParams);
/****************************************************************************************/
/* */
/* FUNCTION: LVM_SetControlParameters */
/* */
/* DESCRIPTION: */
/* Sets or changes the LifeVibes module parameters. */
/* */
/* PARAMETERS: */
/* hInstance Instance handle */
/* pParams Pointer to a parameter structure */
/* */
/* RETURNS: */
/* LVM_SUCCESS Succeeded */
/* LVM_NULLADDRESS When hInstance, pParams or any control pointers are NULL */
/* LVM_OUTOFRANGE When any of the control parameters are out of range */
/* */
/* NOTES: */
/* 1. This function may be interrupted by the LVM_Process function */
/* */
/****************************************************************************************/
LVM_ReturnStatus_en LVM_SetControlParameters(LVM_Handle_t hInstance,
LVM_ControlParams_t *pParams);
/****************************************************************************************/
/* */
/* FUNCTION: LVM_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 */
/* AudioTime Audio Time of the current input data in milli-seconds */
/* */
/* RETURNS: */
/* LVM_SUCCESS Succeeded */
/* LVM_INVALIDNUMSAMPLES When the NumSamples is not a valied multiple in unmanaged */
/* buffer mode */
/* LVM_ALIGNMENTERROR When either the input our output buffers are not 32-bit */
/* aligned in unmanaged mode */
/* LVM_NULLADDRESS When one of hInstance, pInData or pOutData is NULL */
/* */
/* NOTES: */
/* 1. The input and output buffers must be 32-bit aligned */
/* 2. Number of samples is defined as follows: */
/* MONO the number of samples in the block */
/* MONOINSTEREO the number of sample pairs in the block */
/* STEREO the number of sample pairs in the block */
/* */
/****************************************************************************************/
LVM_ReturnStatus_en LVM_Process(LVM_Handle_t hInstance,
const LVM_INT16 *pInData,
LVM_INT16 *pOutData,
LVM_UINT16 NumSamples,
LVM_UINT32 AudioTime);
/****************************************************************************************/
/* */
/* FUNCTION: LVM_SetHeadroomParams */
/* */
/* DESCRIPTION: */
/* This function is used to set the automatic headroom management parameters. */
/* */
/* PARAMETERS: */
/* hInstance Instance Handle */
/* pHeadroomParams Pointer to headroom parameter structure */
/* */
/* RETURNS: */
/* LVM_NULLADDRESS When hInstance or pHeadroomParams is NULL */
/* LVM_SUCCESS Succeeded */
/* */
/* NOTES: */
/* 1. This function may be interrupted by the LVM_Process function */
/* */
/****************************************************************************************/
LVM_ReturnStatus_en LVM_SetHeadroomParams( LVM_Handle_t hInstance,
LVM_HeadroomParams_t *pHeadroomParams);
/****************************************************************************************/
/* */
/* FUNCTION: LVM_GetHeadroomParams */
/* */
/* DESCRIPTION: */
/* This function is used to get the automatic headroom management parameters. */
/* */
/* PARAMETERS: */
/* hInstance Instance Handle */
/* pHeadroomParams Pointer to headroom parameter structure (output) */
/* */
/* RETURNS: */
/* LVM_SUCCESS Succeeded */
/* LVM_NULLADDRESS When hInstance or pHeadroomParams are NULL */
/* */
/* NOTES: */
/* 1. This function may be interrupted by the LVM_Process function */
/* */
/****************************************************************************************/
LVM_ReturnStatus_en LVM_GetHeadroomParams( LVM_Handle_t hInstance,
LVM_HeadroomParams_t *pHeadroomParams);
/****************************************************************************************/
/* */
/* FUNCTION: LVM_GetSpectrum */
/* */
/* DESCRIPTION: */
/* This function is used to retrieve Spectral information at a given Audio time */
/* for display usage */
/* */
/* PARAMETERS: */
/* hInstance Instance Handle */
/* pCurrentPeaks Pointer to location where currents peaks are to be saved */
/* pPastPeaks Pointer to location where past peaks are to be saved */
/* pCentreFreqs Pointer to location where centre frequency of each band is */
/* to be saved */
/* AudioTime Audio time at which the spectral information is needed */
/* */
/* RETURNS: */
/* LVM_SUCCESS Succeeded */
/* LVM_NULLADDRESS If any of input addresses are NULL */
/* LVM_WRONGAUDIOTIME Failure due to audio time error */
/* */
/* NOTES: */
/* 1. This function may be interrupted by the LVM_Process function */
/* */
/****************************************************************************************/
LVM_ReturnStatus_en LVM_GetSpectrum( LVM_Handle_t hInstance,
LVM_UINT8 *pCurrentPeaks,
LVM_UINT8 *pPastPeaks,
LVM_INT32 AudioTime);
/****************************************************************************************/
/* */
/* FUNCTION: LVM_SetVolumeNoSmoothing */
/* */
/* DESCRIPTION: */
/* This function is used to set output volume without any smoothing */
/* */
/* PARAMETERS: */
/* hInstance Instance Handle */
/* pParams Control Parameters, only volume value is used here */
/* */
/* RETURNS: */
/* LVM_SUCCESS Succeeded */
/* LVM_NULLADDRESS If any of input addresses are NULL */
/* LVM_OUTOFRANGE When any of the control parameters are out of range */
/* */
/* NOTES: */
/* 1. This function may be interrupted by the LVM_Process function */
/* */
/****************************************************************************************/
LVM_ReturnStatus_en LVM_SetVolumeNoSmoothing( LVM_Handle_t hInstance,
LVM_ControlParams_t *pParams);
#ifdef __cplusplus
}
#endif /* __cplusplus */
#endif /* __LVM_H__ */