source: svn/trunk/newcon3bcm2_21bu/nexus/lib/softgfx/include/b_softgfx_lib.h

/***************************************************************************
* (c)2003-2009 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: $
* $brcm_Revision: $
* $brcm_Date: $
*
* Description: header file for Soft Graphics App Lib
*
* Revision History:
*
* $brcm_Log: $
* 
***************************************************************************/
#ifndef B_SOFTGFX_LIB_H__
#define B_SOFTGFX_LIB_H__

#include "bstd.h"
#include "nexus_types.h"
#include "nexus_platform.h"
#include "nexus_surface.h"
#include "nexus_striped_surface.h"


/**************************************************************************
 * This IP Applib module provides Soft Graphics functions including:
 *      - Fill
 *      - Blit (simple blit and blend)
 *      - Anti-flutter
 ***************************************************************************/

#ifdef __cplusplus
extern "C" {
#endif

/**
Summary:
Public handle for Soft Graphics App Lib
**/
typedef struct B_SoftGfx * B_SoftGfxHandle;

/**
Summary:
Settings used for B_SoftGfx_Open
**/
typedef struct B_SoftGfx_OpenSettings
{
    int tbd; 
} B_SoftGfx_OpenSettings;

/***************************************************************************
Summary:
Get default settings for B_SoftGfx_Open
***************************************************************************/
void B_SoftGfx_GetDefaultOpenSettings(
   B_SoftGfx_OpenSettings *pSettings /* [out] */
   );

/***************************************************************************
Summary:
Open a Soft Graphics interface for blit and fill operations.
***************************************************************************/
B_SoftGfxHandle B_SoftGfx_Open(
    const B_SoftGfx_OpenSettings *pSettings
    );

/***************************************************************************
Summary:
Close a Soft Graphics interface.
***************************************************************************/
void B_SoftGfx_Close(
    B_SoftGfxHandle handle
    );

/**
Summary:
How to fill the surface with the given color

Description:
Used in B_SoftGfx_FillSettings
**/
typedef enum B_SoftGfx_FillOp
{
    B_SoftGfx_FillOp_eIgnore = 0, /* Do not change the values for the channel (either color or alpha) */
    B_SoftGfx_FillOp_eCopy,       /* Copy the value of the channel (color or alpha) from the constant color to the surface */
    B_SoftGfx_FillOp_eBlend,      /* For color channel, blend surface color with constant color using constant alpha.
                                     This operation is not support for the alpha channel. */
    B_SoftGfx_FillOp_eMax
} B_SoftGfx_FillOp;

/**
Summary:
Parameters for B_SoftGfx_Fill
**/
typedef struct B_SoftGfx_FillSettings
{
    NEXUS_SurfaceHandle   surface;
    NEXUS_Pixel           color;    /* Color to fill */
    NEXUS_Rect            rect;     /* Area of surface to fill. width,height of 0,0 fills the entire surface */
    B_SoftGfx_FillOp      colorOp;  /* Operation to take on the color channel */
    B_SoftGfx_FillOp      alphaOp;  /* Operation to take on the alpha channel */                                        
} B_SoftGfx_FillSettings;


typedef struct B_SoftGfx_ScaleSettings
{
    NEXUS_SurfaceHandle     srcsurface;
    NEXUS_SurfaceHandle     outsurface;
    NEXUS_Rect              srcrect;
    NEXUS_Rect              outrect;
    bool                    bApplySclFiltering;
} B_SoftGfx_ScaleSettings;

/***************************************************************************
Summary:
Create a new surface by copying from a striped surface

Description:
A striped surface is the output of NEXUS_StillDecoder_GetStripedSurface.
***************************************************************************/
NEXUS_SurfaceHandle B_SoftGfx_Destripe( NEXUS_StripedSurfaceHandle stripedSurface);


/***************************************************************************
Summary:
Get default settings for the structure.
***************************************************************************/
void B_SoftGfx_GetDefaultFillSettings(
    B_SoftGfx_FillSettings *pSettings /* [out] */
    );

/***************************************************************************
Summary:
Fill, tint or otherwise modify the pixels of an area of a surface using a constant 
value. This routine modifies the color channels and/or the alpha channel of the 
pixels of a surface using a constant value.

Notes: 
1) Normal fill opeartion can be achieved by specifying both colorOp and alphaOp 
   as B_SoftGfx_FillOp_eCopy

2) If surface is in palette format then color represents the index to the clut.
   If surface is in non-palette format, say ARGB8888 or ARGB4444, then color 
   parameter has to be in the ARGB8888 format. 

   Ex: In ARGB4444 BLUE color is represented by 0xF00F. But, for filling an 
   ARGB4444 surface with solid BLUE color, the color parameter should be 0xFF0000FF 
   (as in ARGB8888 format).

3) Only B_SoftGfx_FillOp_eCopy operation is supported for palette surface.

4) Color channels of a non-paletter surface can be blended with the color channels 
   of the constant color using constant alpha. For such operations, user needs 
   to specify :
        colorOp = B_SoftGfx_FillOp_eBlend 
        alphaOp = B_SoftGfx_FillOp_eIgnore
   Note: Blend fill is supported only for surfaces with pixel formats with alpha
   component only. 
   Ex: Blend fill is supported for ARGB888, ARGB4444, RGBA4444, etc.
       Blend fill is not supported for RGB565, etc.

***************************************************************************/
NEXUS_Error B_SoftGfx_Fill(
    B_SoftGfxHandle handle,
    const B_SoftGfx_FillSettings *pSettings
    );

/**
Summary:
Color operations available in B_SoftGfx_BlitSettings

Description:
Below is the generic color blend equation:

    R   =       R1   *  Alpha1  +        R2     *        Alpha2  *   (1-Alpha1) 
    G   =       G1   *  Alpha1  +        G2     *        Alpha2  *   (1-Alpha1)   
    B   =       B1   *  Alpha1  +        B2     *        Alpha2  *   (1-Alpha1) 
Alpha   =        1   -  (1   -  Alpha1)  *   (  1        -   Alpha2)    
    R   =       R        /   Alpha       
    G   =       G        /   Alpha       
    B   =       B        /   Alpha       
where, 
    [R1,G1,B1] are color components for a pixel from srcsurface
    [R2,G2,B2] are color components for corresponding pixel from dstsurface
    [R,G,B] are color components for the resultant blended pixel on the outsurface

Alpha1 and Alpha2 are derived based on BlitColorOp as shown below:

BlitColorOp         -       Alpha1       -       Alpha2             OPERATION 
------------------    ------------------   --------------------
eCopySource         -       NA           -         NA               Blit 
eUseConstantAlpha   -  constAlphaColorOp -  constAlphaColorOp       Blend 
eUseSourceAlpha     -  srcsurface_alpha  -  srcsurface_alpha        Blend 
eUseDestAlpha       -  dstsurface_alpha  -  dstsurface_alpha        Blend 
eUseBlendEquation   -  srcsurface_alpha  -  dstsurface_alpha        Blend

See B_SofGfx_BlitSettings for constAlphaColorOp parameter.
**/
typedef enum B_SoftGfx_BlitColorOp
{
    B_SoftGfx_BlitColorOp_eCopySource = 0,        /* Copy the source color with no blending. Valid only with B_SoftGfx_BlitAlphaOp_eCopySource. This means Blitting. */
    B_SoftGfx_BlitColorOp_eUseConstantAlpha,      /* Blend the source and dest colors using the alpha from the constAlphaColorOp param */
    B_SoftGfx_BlitColorOp_eUseSourceAlpha,        /* Blend the source and dest colors using the alpha from the source pixels */
    B_SoftGfx_BlitColorOp_eUseDestAlpha,          /* Blend the source and dest colors using the alpha from the dest pixels */
    B_SoftGfx_BlitColorOp_eUseBlendEquation,      /* Blend the source and dest colors using constant alpha for color & blend operations */
    B_SoftGfx_BlitColorOp_eMax
} B_SoftGfx_BlitColorOp;

/**
Summary:
Alpha operations available in B_SoftGfx_BlitSettings

Description:
**/
typedef enum B_SoftGfx_BlitAlphaOp
{
    B_SoftGfx_BlitAlphaOp_eCopySource = 0,        /* Oa = Sa. Copy the source alpha to the output alpha. */
    B_SoftGfx_BlitAlphaOp_eCopyDest,              /* Oa = Da. Copy the dest alpha to the output alpha */
    B_SoftGfx_BlitAlphaOp_eCopyConstant,          /* Oa = constAlphaAlphaOp. Copy the constant alpha for alphaOp parameter as the output alpha */
    B_SoftGfx_BlitAlphaOp_eUseBlendEquation,      /* Alpha = 1 - (1 - Alpha1) * (1 - Alpha2) 
                                                     where, Alpha1 and Alpha2 are defined as per the BlitColorOp given 
                                                     in the description of B_SoftGfx_BlitColorOp above */
    B_SoftGfx_BlitAlphaOp_eMax
} B_SoftGfx_BlitAlphaOp;

#define B_SOFTGFX_COLOR_MATRIX_COEFF_COUNT           (20)

/***************************************************************************
Summary:
5x4 coefficient matrix for blitter color space convertor

Description:
        This matrix is used to modify the incoming source values.
        Typically this is done to convert from one color space to another.

        The values used for the color matrix are equal to the values stored 
        in the ai32_Matrix array right shifted by the ulShift value. In
        addition, negative values are converted to positive values before
        shifting and then turned back into negative values. For
        example, if a value in the matrix was 4 and the shift value was 2, then
        the final value is 1 (4>>2 = 1). If a value in the matrix was 7
        and the shift value was 3, then the final value would be 0.875.
        If a value in the matrix was -7 and the shift value was 3 then the
        final values is -0.875.

        The values within the color matrix are in the following order:

              |  M[0]   M[1]   M[2]   M[3]   M[4] |
              |  M[5]   M[6]   M[7]   M[8]   M[9] |
              | M[10]  M[11]  M[12]  M[13]  M[14] |
              | M[15]  M[16]  M[17]  M[18]  M[19] |

        This is multiplied with a column vector of 
        < C2in, C1in, C0in, Ain, 1 > which yields the following equations:

        C2out =  M[0]*C2in +  M[1]*C1in +  M[2]*C0in +  M[3]*Ain +  M[4]
        C1out =  M[5]*C2in +  M[6]*C1in +  M[7]*C0in +  M[8]*Ain +  M[9]
        C0out = M[10]*C2in + M[11]*C1in + M[12]*C0in + M[13]*Ain + M[14]
        Aout  = M[15]*C2in + M[16]*C1in + M[17]*C0in + M[18]*Ain + M[19]

        The default is to for the matrix to represent the identity.
        M[0] = M[6] = M[12] = M[18] = 1. All other values are zero.

    NOTE: Even though proposed interface (like Nexus_Graphics2D) has 20 
    coefficients for better performance, coefficients (M[3], M[8], M[13], M18]) 
    involving Ain will not be used. 
    Also, Aout will simply be = Ain. 
    (Meaning M[15], M[16], M[17], M[18] and M[19] will not be used).

Used in B_SoftGfx_Blit
****************************************************************************/
typedef struct B_SoftGfx_ColorMatrix
{
    unsigned shift;
    int32_t  coeffMatrix[B_SOFTGFX_COLOR_MATRIX_COEFF_COUNT];
} B_SoftGfx_ColorMatrix;

/**
Summary:
Parameters for B_SoftGfx_Blit

Description:
B_SoftGfx_blit can be used for following two operations:
1) Blit a rectangle from source surface to output surface
2) Blend rectangles from source and destination surfaces on to the output surface

Simple Blit Operation:
- Copies srcrect from srcsurface to outsurface
- dstsurface and dstx, dsty are ignored
- colorOp should B_SoftGfx_BlitColorOp_eCopySource
- alphaOp should B_SoftGfx_BlitAlphaOp_eCopySource
- constAlphaColorOp and constAlphaAlphaOp are ignored
- srcsurface and outsurface should be of same pixel format

Blend Operation:
- Blends rectangles from src and dst surfaces based on the color and alpha operations and
  writes on to the outsurface.
- Requires all three surfaces: src, dst and out
- colorOp, alphaOp and constAlpha for color and alpha operations define the blend parameters
- Blending is supported only on surfaces with non-palette RGB pixel formats
- srcsurface, dstsurface and outsurface should be of same pixel format
**/
typedef struct B_SoftGfx_BlitSettings
{
    NEXUS_SurfaceHandle     srcsurface;
    NEXUS_SurfaceHandle     dstsurface;         /* Required only for blending. For blt, it will be ignored. */
    NEXUS_SurfaceHandle     outsurface; 
    
    NEXUS_Rect              srcrect;            /* As there is no support for scaling, the same width, height will be used for dst and out surfaces */
    int16_t                 dstx, dsty;         /* Required only for blending. For blt, these will be ignored. */
    int16_t                 outx, outy;         
    
    B_SoftGfx_BlitColorOp   colorOp;            /* Specify how to blit the color component */
    B_SoftGfx_BlitAlphaOp   alphaOp;            /* Specify how to blit the alpha component */

    uint8_t                 constAlphaColorOp;  /* Used by some operations */
    uint8_t                 constAlphaAlphaOp;  /* Used by some operations */

    bool                    bApplyAntiFlutterFiler; /* **DEPRECATED** parameter. 7550 will be using anti-flutter from GFD block.
                                                    Anti-flutter filtering will be applied on the modified rect on the outsurface */ 

    bool                    conversionMatrixEnabled;/* If true, use conversionMatrix. No automatic RGB to YCbCr conversion will take place. */
    B_SoftGfx_ColorMatrix   conversionMatrix;
} B_SoftGfx_BlitSettings;

/***************************************************************************
Summary:
Get default settings for the structure.
***************************************************************************/
void B_SoftGfx_GetDefaultBlitSettings(
    B_SoftGfx_BlitSettings *pSettings /* [out] */
    );

/***************************************************************************
Summary:
Perform a block transfer (blit) from one or two surfaces to an output.

Description:
Blit can be a simple blit or alpha blended blit. See B_SoftGfx_BlitSettings 
for details.
***************************************************************************/
NEXUS_Error B_SoftGfx_Blit(
    B_SoftGfxHandle              handle,
    const B_SoftGfx_BlitSettings *pSettings
    );

/***************************************************************************
Summary:
Get default settings for the structure.
***************************************************************************/
void B_SoftGfx_GetDefaultScaleSettings(
    B_SoftGfx_ScaleSettings *pSettings /* [out] */
    );


/***************************************************************************
Summary:
Perform scale-up/down from one surfaces to another.

Description:
User can choose to enable filtering (slower but better quality) or not
***************************************************************************/
NEXUS_Error B_SoftGfx_Scale(
    B_SoftGfxHandle              handle,
    B_SoftGfx_ScaleSettings *pSettings
    );
#ifdef __cplusplus
}
#endif
#endif /* #ifndef B_SOFTGFX_LIB_H__ */