source: svn/newcon3bcm2_21bu/nexus/modules/audio/7552/include/nexus_studio_sound.h

/***************************************************************************
*     (c)2004-2011 Broadcom Corporation
*  
*  This program is the proprietary software of Broadcom Corporation and/or its licensors,
*  and may only be used, duplicated, modified or distributed pursuant to the terms and
*  conditions of a separate, written license agreement executed between you and Broadcom
*  (an "Authorized License").  Except as set forth in an Authorized License, Broadcom grants
*  no license (express or implied), right to use, or waiver of any kind with respect to the
*  Software, and Broadcom expressly reserves all rights in and to the Software and all
*  intellectual property rights therein.  IF YOU HAVE NO AUTHORIZED LICENSE, THEN YOU
*  HAVE NO RIGHT TO USE THIS SOFTWARE IN ANY WAY, AND SHOULD IMMEDIATELY
*  NOTIFY BROADCOM AND DISCONTINUE ALL USE OF THE SOFTWARE.  
*   
*  Except as expressly set forth in the Authorized License,
*   
*  1.     This program, including its structure, sequence and organization, constitutes the valuable trade
*  secrets of Broadcom, and you shall use all reasonable efforts to protect the confidentiality thereof,
*  and to use this information only in connection with your use of Broadcom integrated circuit products.
*   
*  2.     TO THE MAXIMUM EXTENT PERMITTED BY LAW, THE SOFTWARE IS PROVIDED "AS IS" 
*  AND WITH ALL FAULTS AND BROADCOM MAKES NO PROMISES, REPRESENTATIONS OR 
*  WARRANTIES, EITHER EXPRESS, IMPLIED, STATUTORY, OR OTHERWISE, WITH RESPECT TO 
*  THE SOFTWARE.  BROADCOM SPECIFICALLY DISCLAIMS ANY AND ALL IMPLIED WARRANTIES 
*  OF TITLE, MERCHANTABILITY, NONINFRINGEMENT, FITNESS FOR A PARTICULAR PURPOSE, 
*  LACK OF VIRUSES, ACCURACY OR COMPLETENESS, QUIET ENJOYMENT, QUIET POSSESSION 
*  OR CORRESPONDENCE TO DESCRIPTION. YOU ASSUME THE ENTIRE RISK ARISING OUT OF 
*  USE OR PERFORMANCE OF THE SOFTWARE.
*  
*  3.     TO THE MAXIMUM EXTENT PERMITTED BY LAW, IN NO EVENT SHALL BROADCOM OR ITS 
*  LICENSORS BE LIABLE FOR (i) CONSEQUENTIAL, INCIDENTAL, SPECIAL, INDIRECT, OR 
*  EXEMPLARY DAMAGES WHATSOEVER ARISING OUT OF OR IN ANY WAY RELATING TO YOUR 
*  USE OF OR INABILITY TO USE THE SOFTWARE EVEN IF BROADCOM HAS BEEN ADVISED OF 
*  THE POSSIBILITY OF SUCH DAMAGES; OR (ii) ANY AMOUNT IN EXCESS OF THE AMOUNT 
*  ACTUALLY PAID FOR THE SOFTWARE ITSELF OR U.S. $1, WHICHEVER IS GREATER. THESE 
*  LIMITATIONS SHALL APPLY NOTWITHSTANDING ANY FAILURE OF ESSENTIAL PURPOSE OF 
*  ANY LIMITED REMEDY.
* 
* $brcm_Workfile: nexus_studio_sound.h $
* $brcm_Revision: 2 $
* $brcm_Date: 8/24/11 5:31p $
*
* API Description:
*   API name: StudioSound
*    Specific APIs related to SRS StudioSound Audio Processing
*
* Revision History:
*
* $brcm_Log: /nexus/modules/audio/7422/include/nexus_studio_sound.h $
* 
* 2   8/24/11 5:31p jgarrett
* SW7344-176: Adding null_allowed attribute for kernelmode
* 
* 1   8/18/11 5:51p jgarrett
* SWDTV-6306: Merge DTV APE changes to main branch
* 
* Nexus_APE_Integration/1   7/1/11 5:50p jgarrett
* SWDTV-6306: Integrated to latest 7422 baseline and nexus audio
*  directory structure
* 
* 6   5/30/11 5:45p jhaberf
* SWDTV-7253: removed shutdown attr as this is no longer used
* 
* 5   3/21/11 12:15p jhaberf
* SWDTV-5784: Updated SRS StudioSound interface parameters required for
*  certification
* 
* 4   3/16/11 3:04p jhaberf
* SWDTV-5784: Updated SRS StudioSound interface with new HPF/PEQ
*  parameters
* 
* 3   3/4/11 1:55p jhaberf
* SWDTV-5047: Added PEQ filter mode to StudioSound settings
* 
* 2   2/7/11 3:33p jhaberf
* SW35230-2941: Provided SRS Studio Sound mode setting
* 
* 1   11/10/10 7:06p jhaberf
* SW3548-2923: Added Support for SRS Studio.
* 
* 
***************************************************************************/

#ifndef NEXUS_STUDIO_SOUND_H__
#define NEXUS_STUDIO_SOUND_H__

#include "nexus_types.h"
#include "nexus_audio_types.h"
#include "nexus_tru_surround_hd.h"
#include "nexus_tru_volume.h"

#ifdef __cplusplus
extern "C" {
#endif

/*=************************************
Interface: TruSurrroundHd

Header file: nexus_studio_sound.h

Module: Audio

Description: SRS StudioSound Post Processing

**************************************/

/**
Summary:
Handle for SRS StudioSound stage
**/
typedef struct NEXUS_StudioSound *NEXUS_StudioSoundHandle;

#define NEXUS_SRS_SS_MAX_PEQ_BANDS    8
#define NEXUS_SRS_SS_MAX_GEQ_BANDS    10

/***************************************************************************
Summary:
StudioSound Mode - Select the opearating mode of StudioSound. Default is Mode1.
                   Based on mode, a few of the modules will be disabled by the driver internally. 
    Mode1: TruVol(on), HPF(on), CircleSurround(on), TruSurroundHD(on), GEQ(off), HardLimiter(on), TruEQ(on)
    Mode2: TruVol(off), HPF(on), CircleSurround(off), TruSurroundHD(off), GEQ(on), HardLimiter(on), TruEq(on) 

Note: When TruVol/CircleSurround/TruSurroundHD is off, a bypass gain of 1.0 will be used.
***************************************************************************/
typedef enum NEXUS_StudioSoundMode
{
    NEXUS_StudioSoundMode_eMode1,
    NEXUS_StudioSoundMode_eMode2,
    NEXUS_StudioSoundMode_eMax
} NEXUS_StudioSoundMode;

/***************************************************************************
Summary:
SRS StudioSound Input Mode
***************************************************************************/
typedef enum NEXUS_StudioSoundInputMode
{
    NEXUS_StudioSoundInputMode_eMono,
    NEXUS_StudioSoundInputMode_eStereo,
    NEXUS_StudioSoundInputMode_eMultiChannel,
    NEXUS_StudioSoundInputMode_eLtRt,
    NEXUS_StudioSoundInputMode_eMax
} NEXUS_StudioSoundInputMode;

/***************************************************************************
Summary:
SRS CircleSurround Processing Mode
***************************************************************************/
typedef enum NEXUS_CircleSurroundMode
{
    NEXUS_CircleSurroundMode_eCinema,
    NEXUS_CircleSurroundMode_eMusic,
    NEXUS_CircleSurroundMode_eMax
}NEXUS_CircleSurroundMode;

/***************************************************************************
Summary:
SRS CircleSurround Settings
***************************************************************************/
typedef struct NEXUS_CircleSurroundSettings
{
    bool enabled;                       /* If true, CircleSurround processing is enabled. Default: true */

    unsigned inputGain;                 /* Adjusts the signal level immediately prior to CircleSurround processing.  Range: 125 to 1000. Default: 1000 */
    NEXUS_CircleSurroundMode mode;      /* The CircleSurround processing mode. Default:  NEXUS_CircleSurroundMode_eCinema */
    unsigned outputMode;                /* 0: stereo ; 1: multichannel. Default: 0 (only 0 is supported) */
    unsigned outputGainFront;           /* Output gain for the front (L/R). Range: 89 to 4000. Default: 1000 */
    unsigned outputGainRear;            /* Output gain for the rear (Ls/Rs). Range: 89 to 4000. Default: 1000 */
    unsigned outputGainCenter;          /* Output gain for the center. Range: 89 to 4000. Default: 1000 */
    unsigned outputGainSubwoofer;       /* Output gain for the subwoofer. Range: 89 to 4000. Default: 1000 */
} NEXUS_CircleSurroundSettings;

/***************************************************************************
Summary:
SRS TruDialog Settings
***************************************************************************/
typedef struct NEXUS_TruDialogSettings
{
    bool enabled;               /* If true, TruDialog processing is enabled. Default: true */

    unsigned inputGain;         /* Adjusts the signal level prior immediately prior to TruDialog processing.  Range: 0 to 100. Default: 100 */
    unsigned outputGain;        /* Adjusts the signal level prior after TruDialog processing.  Range: 0 to 100. Default: 100 */
    unsigned processGain;       /* Controls how much of the calculated final output gain is applied to the output signal, effectively
                                                            controlling how much the process will raise the dialog signal.  Range: 50 to 300. Default: 150 */
    unsigned bypassGain;        /* Adjusts the signal level when TruDialog processing is disabled.  Range: 0 to 100. Default: 100 */
    unsigned enhancementGain;  /*  The amount of vocal enhancement that is applied to the audio signal.  Range: 0 to 100. Default: 100 */
} NEXUS_TruDialogSettings;

/***************************************************************************
Summary:
SRS Graphic EQ Band Modes
***************************************************************************/
typedef enum NEXUS_SrsGraphicEqBandMode
{
    NEXUS_SrsGraphicEqBandMode_eFiveBand,
    NEXUS_SrsGraphicEqBandMode_eTenBand,
    NEXUS_SrsGraphicEqBandMode_eSpeakerCompensation,
    NEXUS_SrsGraphicEqBandMode_eMax
} NEXUS_SrsGraphicEqBandMode;

/***************************************************************************
Summary:
SRS Graphic Equalizer Settings
***************************************************************************/
typedef struct NEXUS_SrsGraphicEqSettings
{
    bool leftEnabled;           /* If true, left channel processing is enabled. Default: true */
    bool rightEnabled;          /* If true, right channel processing is enabled. Default: true */
    NEXUS_SrsGraphicEqBandMode bandMode;  /* Graphic EQ band mode: 5-band or 10-band. Default NEXUS_SrsGraphicEqBandMode_eFiveBand */
    unsigned leftBandGain[NEXUS_SRS_SS_MAX_GEQ_BANDS];   /* Left channel band gain.  Range for 5-band: 316 to 3160. Range for 10-band: 251 to 4000. Default: 1000 */
    unsigned rightBandGain[NEXUS_SRS_SS_MAX_GEQ_BANDS];  /* Right channel band gain.  Range for 5-band: 316 to 3160. Range for 10-band: 251 to 4000. Default: 1000 */
    unsigned inputGain;         /* Adjusts the signal level prior immediately prior to Graphic Equalizer processing.  Range: 316 to 3160 Default: 316 */
    unsigned outputGain;        /* Adjusts the signal level prior after Graphic Equalizer processing.  Range: 0 to 100. Default: 100 */
    unsigned bypassGain;        /* Adjusts the signal level when Graphic Equalizer processing is disabled.  Range: 0 to 100. Default: 100 */
} NEXUS_SrsGraphicEqSettings;

/***************************************************************************
Summary:
SRS TruEQ Filter parameters for coefficients specified by user
***************************************************************************/
typedef struct NEXUS_TruEqFilterCoefUserParam
{
    NEXUS_SrsFilterOrder filterOrder;    /* EQ filter order.  Default: NEXUS_SrsFilterOrder_eOrder2 */
    unsigned scale;    /* Specified q-format of the coefficients. (1+scale).(31-scale) format 
                                           Default: 1. scale=1 implies a q-format of 2.30 */
    int coefficientB0;
    int coefficientA1;
    int coefficientB1;
    int coefficientA2;
    int coefficientB2;
}NEXUS_TruEqFilterCoefUserParam;

/***************************************************************************
Summary:
SRS TruEQ Filter parameters for coefficients generated by specification
***************************************************************************/
typedef struct NEXUS_TruEqFilterCoefSpecParam
{
    int bandGain;    /*  Range: (-120 to 120). Default:0 Format: q24
                                          Range in dB: -12 to 12 db. Default: 0dB
                                          Range in Fixed point: 0x00404DE6 to 0x03FB2783 */

    unsigned bandFrequency;    /*  Range: (20 - 20000)Hz. Default: 1000 Hz */
    int qFactor;    /*  Range: (25 - 1600).  Default:200 Format: q24
                                         Range in floating point: 0.25 to 16.0
                                         Range in fixed point: 0x00400000 to 0x10000000 */
}NEXUS_TruEqFilterCoefSpecParam;

/***************************************************************************
Summary:
SRS TruEQ Settings
***************************************************************************/
typedef struct NEXUS_TruEqSettings
{
    bool leftEnabled;           /* If true, left channel processing is enabled. Default: true */
    bool rightEnabled;          /* If true, right channel processing is enabled. Default: true */

    bool leftBandEnabled[NEXUS_SRS_SS_MAX_PEQ_BANDS];   /* If true, left channel processing is enabled for this band. Default: true */
    bool rightBandEnabled[NEXUS_SRS_SS_MAX_PEQ_BANDS];  /* If true, right channel processing is enabled for this band. Default: true */

    unsigned inputGain;         /* Adjusts the signal level prior immediately prior to TruEQ processing.  Range: 0 to 100. Default: 100 */
    unsigned outputGain;        /* Adjusts the signal level prior after TruEQ processing.  Range: 0 to 100. Default: 100 */
    unsigned bypassGain;        /* Adjusts the signal level when TruEQ processing is disabled.  Range: 0 to 100. Default: 100 */

    NEXUS_SrsFilterCoefGenMode coefGenMode;         /* Coefficients generation mode. Default: NEXUS_SrsFilterCoefGenMode_eFilterUser */
    union
    {
        NEXUS_TruEqFilterCoefUserParam truEqFilterCoefUser[3][NEXUS_SRS_SS_MAX_PEQ_BANDS];
                                                                  /* The first array dimension indicates 3 sampling frequencies 32, 44.1 and 48kHz respectively
                                                                                                                        will be used if coefGenMode is NEXUS_SrsFilterCoefGenMode_eFilterUser */
        NEXUS_TruEqFilterCoefSpecParam truEqFilterCoefSpec[NEXUS_SRS_SS_MAX_PEQ_BANDS];
                                                                  /* Filter specification for generating filter coeffcients,
                                                                                                                        will be used if eCoefGenMode is NEXUS_SrsFilterCoefGenMode_eFilterSpec */
    } coefParam;
} NEXUS_TruEqSettings;

/***************************************************************************
Summary:
SRS Hard Limiter Block Size
***************************************************************************/
typedef enum NEXUS_SrsHardLimiterBlockSize
{
    NEXUS_SrsHardLimiterBlockSize_e256,
    NEXUS_SrsHardLimiterBlockSize_e512,
    NEXUS_SrsHardLimiterBlockSize_e768,
    NEXUS_SrsHardLimiterBlockSize_e1024,
    NEXUS_SrsHardLimiterBlockSize_eMax
} NEXUS_SrsHardLimiterBlockSize;

/***************************************************************************
Summary:
SRS Hard Limiter Settings
***************************************************************************/
typedef struct NEXUS_SrsHardLimiterSettings
{
    bool enabled;                               /* If true, Hard limiter processing is enabled. Default: true */
    NEXUS_SrsHardLimiterBlockSize blockSize;    /* Processing block size. Default:  NEXUS_SrsHardLimiterBlockSize_e256 */
    unsigned inputGain;                         /* Adjusts the signal level prior immediately prior to hard limiter processing.  Range: 0 to 400. Default: 100 */
    unsigned outputGain;                        /* Adjusts the signal level prior after hard limiter processing.  Range: 0 to 400. Default: 100 */
    unsigned bypassGain;                        /* Adjusts the signal level when hard limiter processing is disabled.  Range: 0 to 100. Default: 100 */    
    unsigned boost;                             /* Modifies the signal level within the context of the hard limiter, so that the signal
                                                                                        will not exceed the hard limit level parameter.  Range: 1 to 256000. Default: 2820 */
    unsigned level;                             /* Specifies the level over which no signal shall bel allowed to exceed.  Range: 3 to 100000. Default: 100000 */
    unsigned delay;                             /* Specifies the length of the look-ahead delay line utilized in the hard limiter.  Range: 6 to 22.  Default: 22 */
} NEXUS_SrsHardLimiterSettings;

/***************************************************************************
Summary:
SRS StudioSound Settings
***************************************************************************/
typedef struct NEXUS_StudioSoundSettings
{
    bool enabled;               /* If true, processing is enabled.  Otherwise this stage is bypassed. Default: true */
    NEXUS_StudioSoundMode mode; /* Pre-defined operation mode of StudioSound */
    unsigned inputGain;         /* Adjusts the signal level prior to StudioSound processing.  Ranges from 0 to 100 in %. */
    unsigned outputGain;        /* Adjusts the signal level after StudioSound processing.  Ranges from 0 to 100 in %. */
    unsigned bypassGain;        /* Adjusts the signal level when StudioStound is disabled.  Ranges from 0 to 100 in %. */
    unsigned headroomGain;      /* Provides headroom for intermediate calculations to avoid clipping.  Ranges from 0 to 100 in %. */
    NEXUS_StudioSoundInputMode inputMode; /* Channel configuration present in input. Default:  NEXUS_StudioSoundInputMode_eLtRt */

    NEXUS_CircleSurroundSettings circleSurround;    /* CircleSurround settings */
    NEXUS_TruDialogSettings truDialog;              /* TruDialog settings */
    NEXUS_TruSurroundHdSettings truSurroundHd;      /* TruSurroundHd settings */
    NEXUS_TruVolumeSettings truVolume;              /* TruVolume settings */
    NEXUS_SrsGraphicEqSettings graphicEq;           /* Graphic Equalizer Settings */
    NEXUS_TruEqSettings truEq;                      /* TruEq Settings */
    NEXUS_SrsHighPassFilterSettings highPassFilter; /* High Pass Filter Settings */
    NEXUS_SrsHardLimiterSettings hardLimiter;       /* Hard Limiter Settings */
} NEXUS_StudioSoundSettings;

/***************************************************************************
Summary:
    Get default settings for an SRS StudioSound stage
***************************************************************************/
void NEXUS_StudioSound_GetDefaultSettings(
    NEXUS_StudioSoundSettings *pSettings   /* [out] default settings */
    );

/***************************************************************************
Summary:
    Open an SRS StudioSound stage
***************************************************************************/
NEXUS_StudioSoundHandle NEXUS_StudioSound_Open( /* attr{destructor=NEXUS_StudioSound_Close}  */
    const NEXUS_StudioSoundSettings *pSettings     /* attr{null_allowed=y} */
    );

/***************************************************************************
Summary:
    Close an SRS StudioSound stage
    
Description:
    Input to the stage must be removed prior to closing.
***************************************************************************/
void NEXUS_StudioSound_Close(
    NEXUS_StudioSoundHandle handle
    );

/***************************************************************************
Summary:
    Get Settings for an SRS StudioSound stage
***************************************************************************/
void NEXUS_StudioSound_GetSettings(
    NEXUS_StudioSoundHandle handle,
    NEXUS_StudioSoundSettings *pSettings    /* [out] Settings */
    );

/***************************************************************************
Summary:
    Set Settings for an SRS StudioSound stage
***************************************************************************/
NEXUS_Error NEXUS_StudioSound_SetSettings(
    NEXUS_StudioSoundHandle handle,
    const NEXUS_StudioSoundSettings *pSettings
    );

/***************************************************************************
Summary:
    Get the audio connector for an SRS StudioSound stage
***************************************************************************/
NEXUS_AudioInput NEXUS_StudioSound_GetConnector( 
    NEXUS_StudioSoundHandle handle
    );

/***************************************************************************
Summary:
Add an input to this processing stage
***************************************************************************/
NEXUS_Error NEXUS_StudioSound_AddInput(
    NEXUS_StudioSoundHandle handle,
    NEXUS_AudioInput input
    );

/***************************************************************************
Summary:
Remove an input from this processing stage
***************************************************************************/
NEXUS_Error NEXUS_StudioSound_RemoveInput(
    NEXUS_StudioSoundHandle handle,
    NEXUS_AudioInput input
    );

/***************************************************************************
Summary:
Remove all inputs from this processing stage
***************************************************************************/
NEXUS_Error NEXUS_StudioSound_RemoveAllInputs(
    NEXUS_StudioSoundHandle handle
    );

#ifdef __cplusplus
}
#endif

#endif /* #ifndef NEXUS_TRU_SURROUND_HD_H__ */