source: svn/trunk/newcon3bcm2_21bu/magnum/portinginterface/ape/7552/bape_equalizer.h

Last change on this file was 2, checked in by jglee, 11 years ago

first commit
  • Property svn:executable set to *
File size: 16.9 KB
Line 
1/***************************************************************************
2 *     Copyright (c) 2006-2011, Broadcom Corporation
3 *     All Rights Reserved
4 *     Confidential Property of Broadcom Corporation
5 *
6 *  THIS SOFTWARE MAY ONLY BE USED SUBJECT TO AN EXECUTED SOFTWARE LICENSE
7 *  AGREEMENT  BETWEEN THE USER AND BROADCOM.  YOU HAVE NO RIGHT TO USE OR
8 *  EXPLOIT THIS MATERIAL EXCEPT SUBJECT TO THE TERMS OF SUCH AN AGREEMENT.
9 *
10 * $brcm_Workfile: bape_equalizer.h $
11 * $brcm_Revision: Hydra_Software_Devel/8 $
12 * $brcm_Date: 9/7/11 7:31p $
13 *
14 * Module Description: Audio Equalizer Interface
15 *
16 * Revision History:
17 *
18 * $brcm_Log: /magnum/portinginterface/ape/7422/bape_equalizer.h $
19 *
20 * Hydra_Software_Devel/8   9/7/11 7:31p sgadara
21 * SWDTV-6627: [35233] Correcting the enums
22 *
23 * Hydra_Software_Devel/7   9/2/11 3:53p sgadara
24 * SWDTV-6627: [35233] Refine the SRC coefficient memory allocation
25 *
26 * Hydra_Software_Devel/6   8/26/11 9:50p sgadara
27 * SWDTV-6627: [35233] Add Equalizer support
28 *
29 * Hydra_Software_Devel/5   8/15/11 10:47a jgarrett
30 * SWDTV-6627: Coverity CID 629,630
31 *
32 * Hydra_Software_Devel/4   8/12/11 6:53p jgarrett
33 * SWDTV-6627: Refactoring initial EQ code
34 *
35 * Hydra_Software_Devel/3   8/12/11 7:02p sgadara
36 * SWDTV-6627: [35233] Add first cut of Equalizer support
37 *
38 * Hydra_Software_Devel/2   2/22/11 5:43p jgarrett
39 * SW7422-146: Implemented type renaming based on filter graph review
40 * comments
41 *
42 * Hydra_Software_Devel/1   12/14/10 2:16p jgarrett
43 * SW7422-146: Adding initial API for APE/DSP
44 *
45 ***************************************************************************/
46
47#ifndef BAPE_EQUALIZER_H_
48#define BAPE_EQUALIZER_H_
49
50/*******************************************************************************
51Summary:
52    Type of Equalization for Tone Control
53   
54Description:
55    This enum describes the type of equalization that is to be applied in a
56    Tone control mode.
57*******************************************************************************/
58
59typedef enum BAPE_ToneControlEqType
60{
61    BAPE_ToneControlEqType_eShelving,    /* Shelving */
62    BAPE_ToneControlEqType_eNotch        /* Notch */
63} BAPE_ToneControlEqType;
64
65typedef struct BAPE_EqualizerToneControlSettings
66{
67    /* Bass */
68    int                             bassGain;           /* Gain Specified in 1/100 dB.  Values range from -10dB (-1000) to +10dB (+1000) */
69    unsigned                        bassFreq;           /* Frequency */   
70    BAPE_ToneControlEqType          bassEqType;         /* Equalizer Type */   
71    unsigned                        bassBandwidthFreq;  /* Frequency Bandwidth */
72
73    /* Treble */
74    int                             trebleGain;         /* Gain Specified in 1/100 dB.  Values range from -10dB (-1000) to +10dB (+1000) */   
75    unsigned                        trebleFreq;         /* Frequency */   
76    BAPE_ToneControlEqType          trebleEqType;       /* Equalizer Type */   
77    unsigned                        trebleBandwidthFreq;/* Frequency Bandwidth */
78} BAPE_EqualizerToneControlSettings;
79
80
81/**********************************************************************
82Summary:
83    Settings for 5 band graphic equalizer
84   
85Description:
86    This structure holds the settings of an equalizer when it is configured in
87    5 band equalizer mode. The values can range from -120 to +120 for the range
88    of -12dB to +12dB for each band in the hardware equalizer.
89***********************************************************************/
90typedef struct BAPE_EqualizerFiveBandSettings
91{
92    int gain100Hz;  /* Specified in 1/100 dB.  Values range from -10dB (-1000) to +10dB (+1000) */
93    int gain300Hz;  /* Specified in 1/100 dB.  Values range from -10dB (-1000) to +10dB (+1000) */
94    int gain1000Hz; /* Specified in 1/100 dB.  Values range from -10dB (-1000) to +10dB (+1000) */
95    int gain3000Hz; /* Specified in 1/100 dB.  Values range from -10dB (-1000) to +10dB (+1000) */
96    int gain10000Hz;/* Specified in 1/100 dB.  Values range from -10dB (-1000) to +10dB (+1000) */
97}BAPE_EqualizerFiveBandSettings;
98
99
100/**********************************************************************
101Summary:
102    Settings for PEQ parametric equalizer
103   
104Description:
105    This structure holds the settings of an equalizer when it is configured in
106    PEQ equalizer mode.
107***********************************************************************/
108
109/***************************************************************************
110Summary:
111    Seven Band EQ window step - time for phase in/out for filter change
112***************************************************************************/
113typedef enum BAPE_EqualizerWindowStep
114{
115    BAPE_EqualizerWindowStep_eNone,   /* No window */
116    BAPE_EqualizerWindowStep_e170_6,  /* 170.6ms at 48kHz */
117    BAPE_EqualizerWindowStep_e85_3,   /* 85.3ms at 48kHz */
118    BAPE_EqualizerWindowStep_e42_6,   /* 42.6ms at 48kHz */
119    BAPE_EqualizerWindowStep_e21_3,   /* 21.3ms at 48kHz */
120    BAPE_EqualizerWindowStep_e10_6,   /* 10.6ms at 48kHz */
121    BAPE_EqualizerWindowStep_e5_3,    /* 5.3ms at 48kHz */
122    BAPE_EqualizerWindowStep_e2_6,    /* 2.6ms at 48kHz */
123    BAPE_EqualizerWindowStep_eMax
124} BAPE_EqualizerWindowStep;
125
126typedef struct BAPE_EqualizerSevenBandSettings
127{
128    struct
129    {
130        unsigned peak;  /* Peak frequency in Hz */
131        int gain;       /* Specified in 1/100 dB.  Values range from -12dB (-1200) to +12dB (+1200) */
132        unsigned q;     /* Peak Frequency Q gain specified in 1/100 (e.g. .33 = 33) */
133    } bandSettings[7];
134
135    BAPE_EqualizerWindowStep  windowStep; /* time for phase in/out for filter change */
136}BAPE_EqualizerSevenBandSettings;
137
138
139/*******************************************************************************
140Summary:
141    Type of Filter for Low/High Pass Filtering in Subsonic/Subwoofer modes
142   
143Description:
144    This enum describes the type of filtering to be applied when the mode is
145    subwoofer or subsonic
146*******************************************************************************/
147typedef enum BAPE_EqualizerFilterType
148{
149    BAPE_EqualizerFilterType_eButterworth,    /* Butter Worth */
150    BAPE_EqualizerFilterType_eLinkwitzRiley   /* Link Witz Riley */
151}BAPE_EqualizerFilterType;
152
153/*******************************************************************************
154Summary:
155    Filter order for Low/High Pass Filtering in Subsonic/Subwoofer modes
156   
157Description:
158    This enum describes the order of the filter to be employed when the mode is
159    subwoofer or subsonic
160*******************************************************************************/
161typedef enum BAPE_EqualizerFilterOrder
162{
163    BAPE_EqualizerFilterOrder_e2 = 2,
164    BAPE_EqualizerFilterOrder_e4 = 4,
165    BAPE_EqualizerFilterOrder_e6 = 6
166}BAPE_EqualizerFilterOrder;
167
168
169/*******************************************************************************
170Summary:
171    Settings for Subsonic Filter
172   
173Description:
174    This structure holds the settings of an equalizer when it is configured in
175    Subsonic filter mode.
176*******************************************************************************/
177typedef struct BAPE_EqualizerSubsonicSettings
178{
179    unsigned            frequency;  /* Subsonic filter frequency (in Hz)  Ranges from 40..315Hz */
180    BAPE_EqualizerFilterOrder    filterOrder;      /* Possible Values: 2, 4, 6 */
181    BAPE_EqualizerFilterType     filterType;        /* Filter type for Subsonic Mode */   
182}BAPE_EqualizerSubsonicSettings;
183
184
185/*******************************************************************************
186Summary:
187    Settings for Subwoofer Filter
188   
189Description:
190    This structure holds the settings of an equalizer when it is configured in
191    Subwoofer filter mode.
192*******************************************************************************/
193typedef struct BAPE_EqualizerSubwooferSettings
194{
195    unsigned            frequency; /* Subwoofer filter frequency (in Hz) Ranges from 40..315Hz */
196    BAPE_EqualizerFilterOrder    filterOrder;      /* Possible Values: 2, 4, 6 */
197    BAPE_EqualizerFilterType     filterType;        /* Filter type for Subwoofer Mode */       
198}BAPE_EqualizerSubwooferSettings;
199
200
201/**********************************************************************
202Summary:
203    Settings for a custom equalizer mode
204   
205Description:
206    This structure holds the settings of an equalizer when it is configured in
207    custom equalizer mode.
208***********************************************************************/
209typedef struct BAPE_EqualizerIIRFilterCoefficients
210{
211    int32_t b0;
212    int32_t b1;
213    int32_t b2;
214    int32_t a1;
215    int32_t a2;   
216}BAPE_EqualizerIIRFilterCoefficients;
217
218#define BAPE_EQUALIZER_MAX_CUSTOM_FILTERS (8)
219typedef struct BAPE_EqualizerCustomSettings
220{
221    unsigned numFilters;        /* Number of biquad IIR filters to be programmed.  Ranges from 0..8. */
222    BAPE_EqualizerIIRFilterCoefficients filterCoefficients[BAPE_EQUALIZER_MAX_CUSTOM_FILTERS];
223}BAPE_EqualizerCustomSettings;
224
225
226/***************************************************************************
227Summary:
228Equalizer Stage Types
229***************************************************************************/
230typedef enum BAPE_EqualizerStageType
231{
232    BAPE_EqualizerStageType_eToneControl,
233    BAPE_EqualizerStageType_eFiveBand,
234    BAPE_EqualizerStageType_eSevenBand,
235    BAPE_EqualizerStageType_eSubsonic,
236    BAPE_EqualizerStageType_eSubwoofer,
237    BAPE_EqualizerStageType_eCustom,
238    BAPE_EqualizerStageType_eMax
239} BAPE_EqualizerStageType;
240
241/***************************************************************************
242Summary:
243Equalizer Stage Settings
244***************************************************************************/
245typedef struct BAPE_EqualizerRampSettings
246{
247    bool enable;                       /* If true (default), the coefficients will be double-buffered for on-the-fly settings changes.
248                                          If false, the coefficients are not double-buffered to save coefficient memory space.
249                                          In case there is a conflict among Stages that are packed into single SRC,
250                                          the take is rampEnabled as 'true' for all stages. It is not programmable on the fly. */ 
251    unsigned stepSize;                  /* Valid if ramping is enabled.
252                                           The Equalizer will ramp between two banks using 2^stepSize samples. */                                           
253}BAPE_EqualizerRampSettings;
254
255/***************************************************************************
256Summary:
257Equalizer Stage Settings
258***************************************************************************/
259typedef struct BAPE_EqualizerStageSettings
260{
261    BAPE_EqualizerStageType type;           /* Type of equalizer stage.  May only be set at create time. */
262    BAPE_EqualizerRampSettings   rampSettings;
263    bool bypassEnabled;                     /* If true, the values specified in modeSettings will be ignored and the data
264                                               will bypass this stage */
265
266    union
267    {
268        BAPE_EqualizerToneControlSettings toneControl;
269        BAPE_EqualizerFiveBandSettings fiveBand;
270        BAPE_EqualizerSevenBandSettings sevenBand;
271        BAPE_EqualizerSubsonicSettings subsonic;
272        BAPE_EqualizerSubwooferSettings subwoofer;
273        BAPE_EqualizerCustomSettings custom;
274    } modeSettings;
275} BAPE_EqualizerStageSettings;
276
277/***************************************************************************
278Summary:
279Equalizer Stage Handle
280 
281Description:
282An Equalizer stage represents a single operation to be performed in one or
283more equalizers.  A stage handle may be passed to more than one equalizer if
284the same operation is to be performed in more than one equalizer, however
285the equalizers must run at the same sample rate.
286 
287See Also:
288BAPE_Equalizer
289***************************************************************************/
290typedef struct BAPE_EqualizerStage *BAPE_EqualizerStageHandle;
291
292/***************************************************************************
293Summary:
294Equalizer Handle
295***************************************************************************/
296typedef struct BAPE_Equalizer *BAPE_EqualizerHandle;
297
298/***************************************************************************
299Summary:
300Equalizer Settings
301***************************************************************************/
302typedef struct BAPE_EqualizerSettings
303{
304    int tbd;
305} BAPE_EqualizerSettings;
306
307/***************************************************************************
308Summary:
309Get default open settings for an equalizer stage
310***************************************************************************/
311void BAPE_EqualizerStage_GetDefaultSettings(
312    BAPE_EqualizerStageType type,
313    BAPE_EqualizerStageSettings *pSettings     /* [out] */
314    );
315
316/***************************************************************************
317Summary:
318Create an audio equalizer stage
319***************************************************************************/
320BERR_Code BAPE_EqualizerStage_Create(
321    BAPE_Handle deviceHandle,
322    const BAPE_EqualizerStageSettings *pSettings, 
323    BAPE_EqualizerStageHandle *pHandle                 /* [out] */
324    );
325
326/***************************************************************************
327Summary:
328Destroy an audio equalizer stage
329***************************************************************************/
330void BAPE_EqualizerStage_Destroy(
331    BAPE_EqualizerStageHandle handle
332    );
333
334/***************************************************************************
335Summary:
336Get settings for an audio equalizer stage
337***************************************************************************/
338void BAPE_EqualizerStage_GetSettings(
339    BAPE_EqualizerStageHandle handle,
340    BAPE_EqualizerStageSettings *pSettings /* [out] */
341    );
342
343/***************************************************************************
344Summary:
345Set settings for an audio equalizer stage
346***************************************************************************/
347BERR_Code BAPE_EqualizerStage_SetSettings(
348    BAPE_EqualizerStageHandle handle,
349    const BAPE_EqualizerStageSettings *pSettings
350    );
351
352/***************************************************************************
353Summary:
354Get Default Equalizer Settings
355***************************************************************************/
356void BAPE_Equalizer_GetDefaultSettings(
357    BAPE_EqualizerSettings *pSettings   /* [out] */
358    );
359
360/***************************************************************************
361Summary:
362Create an equalizer
363***************************************************************************/
364BERR_Code BAPE_Equalizer_Create(
365    BAPE_Handle deviceHandle,
366    const BAPE_EqualizerSettings *pSettings,
367    BAPE_EqualizerHandle *pHandle               /* [out] */
368    );
369
370/***************************************************************************
371Summary:
372Destroy an equalizer
373***************************************************************************/
374void BAPE_Equalizer_Destroy(
375    BAPE_EqualizerHandle handle
376    );
377
378/***************************************************************************
379Summary:
380Set stages for an equalizer
381 
382Description:
383An Equalizer is capable of processing one or more stages.  The array of stages
384provided in pStages will be executed in order.  A stage may be used simultaneously
385by one or more equalizers, provided those equalizers run at the same sample
386rate.
387 
388See Also:
389BAPE_EqualizerStage
390BAPE_Equalizer_ClearStages
391***************************************************************************/
392BERR_Code BAPE_Equalizer_SetStages(
393    BAPE_EqualizerHandle handle,
394    BAPE_EqualizerStageHandle *pStages,
395    unsigned numStages
396    );
397
398/***************************************************************************
399Summary:
400Remove all stages from an equalizer
401***************************************************************************/
402void BAPE_Equalizer_ClearStages(
403    BAPE_EqualizerHandle handle
404    );
405
406/***************************************************************************
407Summary:
408Add an input to an equalizer
409***************************************************************************/
410BERR_Code BAPE_Equalizer_AddInput(
411    BAPE_EqualizerHandle handle,
412    BAPE_Connector input
413    );
414
415/***************************************************************************
416Summary:
417Remove an input from an equalizer
418***************************************************************************/
419BERR_Code BAPE_Equalizer_RemoveInput(
420    BAPE_EqualizerHandle handle,
421    BAPE_Connector input
422    );
423
424/***************************************************************************
425Summary:
426Remove all inputs from an equalizer
427***************************************************************************/
428BERR_Code BAPE_Equalizer_RemoveAllInputs(
429    BAPE_EqualizerHandle handle
430    );
431
432/***************************************************************************
433Summary:
434Get a connection handle for use downstream
435***************************************************************************/
436void BAPE_Equalizer_GetConnector(
437    BAPE_EqualizerHandle handle,
438    BAPE_Connector *pConnector     /* [out] */
439    );
440
441#endif
442
Note: See TracBrowser for help on using the repository browser.