source: svn/newcon3bcm2_21bu/nexus/modules/audio/7552/include/nexus_audio_mixer.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_audio_mixer.h $
* $brcm_Revision: 1 $
* $brcm_Date: 10/10/11 10:18a $
*
* API Description:
*   API name: AudioMixer
*    APIs for an audio mixer.  Allows one or more inputs to be
*    connected, and provides input volume control for mixing.
*
* Revision History:
*
* $brcm_Log: /nexus/modules/audio/7422/include/nexus_audio_mixer.h $
* 
* 1   10/10/11 10:18a jgarrett
* SW7425-1119: Merge to main branch
* 
* SW7425-1119/1   8/26/11 12:19p jgarrett
* SW7425-1119: Adding mixer start/stop routines
* 
***************************************************************************/
#ifndef NEXUS_AUDIO_MIXER_H__
#define NEXUS_AUDIO_MIXER_H__

#include "nexus_types.h"
#include "nexus_audio_types.h"

#ifdef __cplusplus
extern "C" {
#endif

/*=************************************
Interface: AudioMixer

Header file: nexus_audio_mixer.h

Module: Audio

Description: Mixer two or more PCM NEXUS_AudioInputs into a single NEXUS_AudioOutput.

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

/**
Summary:
Handle for an Audio Mixer
**/
typedef struct NEXUS_AudioMixer *NEXUS_AudioMixerHandle;

/***************************************************************************
Summary:
Audio Mixer Settings
***************************************************************************/
typedef struct NEXUS_AudioMixerSettings
{
    bool mixUsingDsp;           /* If true, mix contents in the DSP as opposed to the mixer hardware.  
                                   This requires the masterInput field to be set below prior to starting
                                   any input.  This field should be set prior to NEXUS_AudioMixer_Open
                                   and not changed on the fly. */
    NEXUS_AudioInput master;    /* If mixUsingDsp is true, this field will determine what input is deemed 
                                   to be the master for mixing purposes.  The master must be started prior
                                   to starting any secondary channels, and it will determine the output timing. 
                                   It must also be directly connected to this mixer, with no post-processing 
                                   prior to mixing. */
} NEXUS_AudioMixerSettings;

/***************************************************************************
Summary:
Get default settings for an audio mixer
***************************************************************************/
void NEXUS_AudioMixer_GetDefaultSettings(
    NEXUS_AudioMixerSettings *pSettings    /* [out] Default Settings */
    );

/***************************************************************************
Summary:
Open an audio mixer
***************************************************************************/
NEXUS_AudioMixerHandle NEXUS_AudioMixer_Open( /* attr{destructor=NEXUS_AudioMixer_Close}  */
    const NEXUS_AudioMixerSettings *pSettings /* attr{null_allowed=y} */
    );

/***************************************************************************
Summary:
Close an audio mixer
***************************************************************************/
void NEXUS_AudioMixer_Close(
    NEXUS_AudioMixerHandle handle
    );

/***************************************************************************
Summary:
Get current settings for an audio mixer
***************************************************************************/
void NEXUS_AudioMixer_GetSettings(
    NEXUS_AudioMixerHandle handle,
    NEXUS_AudioMixerSettings *pSettings      /* [out] Mixer Settings */
    );

/***************************************************************************
Summary:
Start a mixer 

Description:
This call is optional.  By default, mixers will automatically start when
The first input starts, but if you want to explicitly enable the mixer
earlier call this function prior to starting any inputs.   Currently, this 
is only supported if mixUsingDsp is set to true.
***************************************************************************/
NEXUS_Error NEXUS_AudioMixer_Start(
    NEXUS_AudioMixerHandle handle
    );

/***************************************************************************
Summary:
Stop a mixer

Description:
This call is required only if you call NEXUS_AudioMixer_Start().  By default, 
mixers will automatically stop when the last input stops, but if you
have explicitly started the mixer via NEXUS_AudioMixer_Start() you must call
this routine to stop it after all inputs have stopped.
***************************************************************************/
void NEXUS_AudioMixer_Stop(
    NEXUS_AudioMixerHandle handle
    );

/***************************************************************************
Summary:
Set settings of an audio mixer
***************************************************************************/
NEXUS_Error NEXUS_AudioMixer_SetSettings(
    NEXUS_AudioMixerHandle handle,
    const NEXUS_AudioMixerSettings *pSettings    /* Mixer Settings */
    );

/***************************************************************************
Summary:
Add an audio input to a mixer
***************************************************************************/
NEXUS_Error NEXUS_AudioMixer_AddInput(
    NEXUS_AudioMixerHandle handle,
    NEXUS_AudioInput input
    );

/***************************************************************************
Summary:
Remove an audio input from a mixer
***************************************************************************/
NEXUS_Error NEXUS_AudioMixer_RemoveInput(
    NEXUS_AudioMixerHandle handle,
    NEXUS_AudioInput input
    );

/***************************************************************************
Summary:
Remove all audio inputs from a mixer
***************************************************************************/
NEXUS_Error NEXUS_AudioMixer_RemoveAllInputs(
    NEXUS_AudioMixerHandle handle
    );

/***************************************************************************
Summary:
Get the audio input connector for connection to outputs or post-processing
***************************************************************************/
NEXUS_AudioInput NEXUS_AudioMixer_GetConnector(
    NEXUS_AudioMixerHandle mixer
    );

#ifdef __cplusplus
}
#endif

#endif /* #ifndef NEXUS_AUDIO_MIXER_H__ */