source: svn/trunk/newcon3bcm2_21bu/dta/src/dcc/include/bdccengine.h @ 29

/***************************************************************************
 *     Copyright (c) 2002-2006, Broadcom Corporation
 *     All Rights Reserved
 *     Confidential Property of Broadcom Corporation
 *
 *  THIS SOFTWARE MAY ONLY BE USED SUBJECT TO AN EXECUTED SOFTWARE LICENSE
 *  AGREEMENT  BETWEEN THE USER AND BROADCOM.  YOU HAVE NO RIGHT TO USE OR
 *  EXPLOIT THIS MATERIAL EXCEPT SUBJECT TO THE TERMS OF SUCH AN AGREEMENT.
 *
 * $brcm_Workfile: bdccengine.h $
 * $brcm_Revision: 6 $
 * $brcm_Date: 9/22/06 1:33p $
 *
 * Module Description:
 *
 * Revision History:
 *
 * $brcm_Log: /BSEAV/lib/ccgfx/include/bdccengine.h $
 * 
 * 6   9/22/06 1:33p btosi
 * PR22275: added support for clearing the screen if the CC data stream
 * stops for an extended period (30 seconds)
 * 
 * 5   9/15/06 12:07p btosi
 * PR22275: added support for font edges
 * 
 * 4   8/23/06 9:00a btosi
 * PR22275: added support for specifying the "Safe Title" area
 * 
 * 3   8/17/06 1:13p btosi
 * PR22275: reworked the API to support loading/unloading fonts files
 * 
 * 2   7/17/06 1:35p btosi
 * PR22275: added wrapper routine BDCC_ENG_Process, support for resetting
 * the library and logic to update the time counter
 * 
 * 1   5/9/05 3:50p shyam
 * PR 8365 : Add other sub-modules of ccgfx
 * 
 ***************************************************************************/


#ifndef BDCCENGINE_H
#define BDCCENGINE_H

#ifdef __cplusplus
extern "C" {
#endif


/***************************************************************************
 *                         708 Rendering Engine
 *                         --------------------
 * 
 * This Rendering Engine API is a wrapper around several lower-level 708
 * libraries.  In most cases, it is expected that this API will be used
 * instead of the lower-level APIs.  In those cases in which the customer/
 * system integrator has a need that isn't covered here, this code then 
 * serves as example code.
 * 
 * Scope
 * 
 * This API wraps the 708 DTVCC rendering and 608 Transcoding libraries
 * but does not wrap the APIs used to extract Closed Captioning streams
 * from MPEG User Data or from analog Line 21.  Furthermore, it does not
 * wrap the API for inserting 608 back into Line 21 on analog output.
 * 
 * 608 and 708
 * 
 * The Rendering Engine has two main entry points, one each for 708 rendering
 * and 608 transcoding.  Higher level system/driver code is expected to call the
 * appropriate API to extract the Closed Captioning data from the input, be it
 * the MPEG API (ie., bcmMPIReadClosedCaptionStatus) or the CCDecoder API
 * (bCCDProcess), and then call one of these two entry points in this API:
 * BDCC_ENG_Process608 or BDCC_ENG_Process708.
 * 
 * This API has these features:
 * 
 * 1.  manages the circular buffers
 * 2.  sequences the calls to the lower-level APIs
 * 3.  allows caller control over field and service numbers
 * 4.  allows caller ability to override various DTVCC attributes
 * 5.  provides reset
 * 6.  context-less:  all processing done on _ProcessXxx and _Periodic calls
 * 
 ***************************************************************************/    



                                /*********************
                                 *
                                 * Includes
                                 *
                                 *********************/
                                 
#include "bdcc.h"
#include "bccwinlib.h"

                                /*********************
                                 *
                                 * Defines
                                 *
                                 *********************/
                                 



                                /*********************
                                 *
                                 * Types
                                 *
                                 *********************/
                                 
/***************************************************************************
Summary:
        The close caption types the Engine can handle

Description:
        The close caption types the Engine can handle

See Also:
        
****************************************************************************/
typedef enum BDCC_ENG_Type
{
    BDCC_ENG_Type_NoChange, /* used when reseting the library and reusing the same modes */
    BDCC_ENG_Type_e608,         /* Input 608 stream is transcoded to 708 and displayed as graphics */
        BDCC_ENG_Type_e708      /* 708 stream is natively displayed as graphics */
    
} BDCC_ENG_Type ;

typedef struct BDCC_ENG_Settings
{
    /*
    ** TODO: per the standard, use 32 for both 4:3 and 16:9.
    ** We can probably get rid of the "Columns" element.
    */
    int Columns ;                       /* number of columns for DTVCC grid use 32 for 4:3 and 42 for 16:9 */
    
    int iCharCellWidth;         /* pixel width for char cell, must be compatible with font/glyph design */
    int iCharCellHeight;        /* pixel height for char cell, must be compatible with font/glyph design */
    int iSafeTitleX;                /* how much the CC window needs to be indented in the X direction */
    int iSafeTitleY;                /* how much the CC window needs to be indented in the Y direction */
    int iEdgeWidth;             /* width of the character edges in pixels */

    unsigned int    uiTimeOutMilliSecs;     /* if no data for this period of time, clear the screen    */
    
} BDCC_ENG_Settings ;


/***************************************************************************
Summary:
        The handle to the Close Caption engine.

Description:
        The handle to the Close Caption engine.

See Also:
        
****************************************************************************/
typedef struct BDCC_ENG_P_Object *BDCC_ENG_Handle ;


                                /*********************
                                 *
                                 * API Entry Points
                                 *
                                 *********************/

/**************************************************************************                
 *  
 * Function:            BDCC_ENG_GetDefaultSettings    
 *     
 * Inputs:                        
 *                                      pEngineSettings         - BDCC_ENG_Settings structure 
 *    
 * Outputs:                           
 *                                      hEngine                         - init'ed by this function
 *  
 * Returns:                     BDCC_Error_eSuccess or standard BDCC_Error error code     
 *    
 * Description:                
 *         
 * This function return the default and recommended values for various engine settings. 
 *
 * See Also:
 *    BDCC_ENG_Open
 *                
 **************************************************************************/  
BDCC_Error BDCC_ENG_GetDefaultSettings(
        BDCC_ENG_Settings *pEngineSettings);

BDCC_Error BDCC_ENG_GetSettings( BDCC_ENG_Handle hEngine, BDCC_ENG_Settings *pEngineSettings );
BDCC_Error BDCC_ENG_SetSettings( BDCC_ENG_Handle hEngine, BDCC_ENG_Settings *pEngineSettings );


/**************************************************************************                
 *  
 * Function:            BDCC_ENG_Open    
 *     
 * Inputs:                        
 *                                phEngine                      - Pointer to a Handle used to return the
 *                                                                      Engine handle
 *                                hWinLibHandle              - Handle from the lowest graphics  
 *                                                                      abstraction layer. Opened seperately.
 *                                      iCcService                              - CCx for 608 (1 to 4)
 *                                                                                Service Number for 708 (0 to 63)
 *                                      Type                            - BDCC_ENG_Type_e608 or 
 *                                                                      BDCC_ENG_Type_e708
 *                                      pEngineSettings         - BDCC_ENG_Settings structure 
 *
 * Outputs:
 *                                      hEngine                         - init'ed by this function
 *  
 * Returns:                     BDCC_Error_eSuccess or standard BDCC_Error error code     
 *    
 * Description:
 *         
 * This function inits the buffers used for 708 DTVCC Closed     
 * Captioning processing.  The 'Type' argument, in effect, is announcing
 * which processing entry point will be called during normal processing.
 * To switch between 608 and 708 (or to switch any of the init args), 
 * BDCC_ENG_Close and BDCC_ENG_Open must be called again -- or 
 * alternatively, BDCC_ENG_Reset.
 *
 * See Also:
 *    BDCC_ENG_Close
 *    BDCC_ENG_Reset
 *                
 **************************************************************************/  
BDCC_Error BDCC_ENG_Open(
        BDCC_ENG_Handle *phEngine, 
        BCCGFX_WINLIB_P_Handle hWinLibHandle 
        );

BDCC_Error BDCC_ENG_Init(
        BDCC_ENG_Handle hEngine, 
        int iCcService,
        BDCC_ENG_Type Type
        );
/**************************************************************************                
 *  
 * Function:            BDCC_ENG_Close   
 *     
 * Inputs:                        
 *                                      hEngine                         - init'ed previously by BDCC_ENG_Open   
 *    
 * Outputs:                           
 *  
 * Returns:                     BDCC_Error_eSuccess or standard BDCC_Error error code     
 *    
 * Description:                
 *         
 * This function undoes the initialization of BDCC_ENG_Open().
 *
 * See Also:
 *    BDCC_ENG_Reset
 *    BDCC_ENG_Open
 *                
 **************************************************************************/  
BDCC_Error BDCC_ENG_Close(BDCC_ENG_Handle hEngine);


/**************************************************************************                
 *  
 * Function:            BDCC_ENG_Reset    
 *     
 * Inputs:                        
 *                                      hEngine                         - init'ed previously by BDCC_ENG_Open   
 *                                      iCcService                              - CCx for 608 (1 to 4)
 *                                                                                Service Number for 708 (0 to 63)
 *                                      Type                            - 608, 708  or "NoChange"
 *                                      Columns                         - number of columns for DTVCC grid
 *                                                                                use 32 for 4:3 and 42 for 16:9
 *                                      CharCell_Width          - pixel width for char cell, must be
 *                                                                                compatible with font/glyph design
 *                                      CharCell_Height         - pixel height for char cell, must be
 *                                                                                compatible with font/glyph design
 *    
 * Outputs:                           
 *  
 * Returns:                     BDCC_Error_eSuccess or standard BDCC_Error error code     
 *    
 * Description:                
 *         
 * BDCC_ENG_Reset is logically equivalent to the sequence BDCC_ENG_Close() 
 * followed by BDCC_ENG_Open().  
 * 
 * Note:  This function is provided in case some advantage can be gained by
 * consolidating _Fini and _Init.  For example, memory need not be free and
 * re-aquired which has an effect on memory fragmentation.  Treat this function
 * as a soft reset and the sequence _Fini and _Init as a hard reset.
 * 
 * If Type is BDCC_ENG_Type_NoChange, then the reset is performed using the current
 * parameters and Type, iCcService, Columns, CharCell_Xxx are ignored.
 *
 * See Also:
 *    BDCC_ENG_Close
 *    BDCC_ENG_Open
 *                
 **************************************************************************/  
BDCC_Error BDCC_ENG_Reset(
        BDCC_ENG_Handle hEngine, 
        bool bNoChange,
        BDCC_ENG_Type Type,
        int iCcService
        );

/**************************************************************************                
 *  
 * Function:            BDCC_ENG_Process    
 *     
 * Inputs:                        
 *                                      hEngine                 - init'ed previously by BDCC_ENG_Open  
 *                                      pTriplets                       - ptr to buf of triplets (field,cc1,cc2)
 *                                      NumTriplets             - count = num_bytes / 3
 *    
 * Outputs:                           
 *  
 * Returns:                     BDCC_Error_eSuccess or standard BDCC_Error error code     
 *    
 * Description:                
 *         
 * Primarily a wrapper routine around the other BDCC functions.  Provides a single
 * entry point to simplify the interface for the application.
 *
 * If this function returns BDCC_Error_eBufferOverflow, it is expected that the
 * caller will call again to DccEngine_Reset.
 *
 **************************************************************************/  
BDCC_Error BDCC_ENG_Process(
        BDCC_ENG_Handle hEngine,
        unsigned char * pTriplets,
        int NumTriplets);

/**************************************************************************                
 *  
 * Function:            BDCC_ENG_Process608    
 *     
 * Inputs:                        
 *                                      hEngine                 - init'ed previously by BDCC_ENG_Open  
 *                                      pTriplets                       - ptr to buf of triplets (field,cc1,cc2)
 *                                      NumTriplets             - count = num_bytes / 3
 *    
 * Outputs:                           
 *  
 * Returns:                     BDCC_Error_eSuccess or standard BDCC_Error error code     
 *    
 * Description:                
 *         
 * This function sends the CC pairs matching the supplied Field through
 * the required processing for rendering.  This includes the 608 Transcoder.
 *
 * If this function returns BDCC_Error_eErrBufferOverflow, it is expected that the
 * caller will call again to BDCC_ENG_Reset.
 *
 **************************************************************************/  
BDCC_Error BDCC_ENG_Process608(
        BDCC_ENG_Handle hEngine,
        unsigned char * pTriplets,
        int NumTriplets);


/**************************************************************************                
 *  
 * Function:            BDCC_ENG_Process708   
 *     
 * Inputs:                        
 *                                      hEngine                         - init'ed previously by BDCC_ENG_Open  
 *                                      pTriplets                       - ptr to buf of triplets (cc_type,cc1,cc2)
 *                                      NumTriplets                     - count = num_bytes / 3
 *    
 * Outputs:                           
 *  
 * Returns:                     BDCC_Error_eSuccess or standard BDCC_Error error code     
 *    
 * Description:                
 *         
 * This function does the packet/service/coding/interpretation layers
 * of the 708 DTVCC spec.  It filters on the Service Number provided in the
 * previous _Init or _Reset call, as the iCcService argument.
 * 
 * If this function returns BDCC_Error_eErrBufferOverflow, it is expected that the
 * caller will call again to BDCC_ENG_Reset.
 *
 **************************************************************************/  
BDCC_Error BDCC_ENG_Process708(
        BDCC_ENG_Handle hEngine,
        unsigned char * pTriplets,
        int NumTriplets);


/**************************************************************************                
 *  
 * Function:            BDCC_ENG_Override   
 *     
 * Inputs:                        
 *                                      hEngine                         - init'ed previously by BDCC_ENG_Open  
 *                                      OverrideMask            - bitmask of overridden attributes
 *                                      pOverrides                      - structure of overrides
 *    
 * Outputs:                           
 *  
 * Returns:                     BDCC_Error_eSuccess or standard BDCC_Error error code     
 *    
 * Description:                
 *         
 * This function allows the caller to override some of the 708 DTVCC
 * interpretation attributes, such as pen size, font style and colors.
 *
 * The OverrideMask argument is a bitmask that identifies which of 
 * structure members of *pOverrides are valid and hence overridden.  The
 * mask is absolute, not relative, meaning that overrides from a previous
 * call will be 'forgotten' if not also included in the present call.  To
 * undo all overrides and revert to the stream-supplied attributes, set
 * the OverrideMask arg to 0.
 *
 * The supported overrides are (as defined in bcmDccCoding.h):
 *
 *    UPM_PENSIZE
 *    UPM_FONTSTYLE
 *    UPM_PENFG
 *    UPM_PENBG
 *    UPM_EDGECOLOR
 *    UPM_EDGETYPE
 *
 **************************************************************************/  
BDCC_Error BDCC_ENG_Override(
        BDCC_ENG_Handle hEngine,
        unsigned int OverrideMask, 
        BDCC_ENG_OverRides * pOverrides);
        

/**************************************************************************                
 *  
 * Function:            BDCC_ENG_Periodic   
 *     
 * Inputs:                        
 *                                      hEngine                         - init'ed previously by BDCC_ENG_Open  
 *    
 * Outputs:                           
 *  
 * Returns:                     BDCC_Error_eSuccess or standard BDCC_Error error code     
 *    
 * Description:                
 *    
 * This function provides the Engine API a mechanism to do sequenced
 * effects.  This is used for flashing and smooth scrolling.  The usPeriod
 * arg is set to an average value.  For example, if this is driven from a
 * field interrupt, it can be set to 16683 for a 59.94 Hz field rate.
 *
 **************************************************************************/  
BDCC_Error BDCC_ENG_Periodic( BDCC_ENG_Handle hEngine );


/*
** Data types and routines associated with managing fonts.
*/

typedef struct BDCC_FONT_DESCRIPTOR
{
    void *              hFont;
    char *              pszFontFile;  /*name and path to the font file */
    int                   iFontSize;
    int                 iMaxGlyphHeight;
    int                 iMaxGlyphWidth;    
    
} BDCC_FONT_DESCRIPTOR;
 
BDCC_Error BDCC_ENG_LoadFont( 
        BDCC_ENG_Handle hEngine,
    BDCC_FONT_DESCRIPTOR * pFontDesc, 
    int iNumToMeasure,
    char * pszCharsToMeasure 
    );
BDCC_Error BDCC_ENG_UnloadFont( BDCC_ENG_Handle hEngine,  BDCC_FONT_DESCRIPTOR * pFontDesc );
BDCC_Error BDCC_ENG_AssignFont( BDCC_ENG_Handle hEngine,  BDCC_FONT_DESCRIPTOR * pFontDesc,  BDCC_PenStyle penStyle, BDCC_FontStyle fontStyle );

#ifdef __cplusplus
}
#endif

#endif /* BDCCENGINE_H */