/*************************************************************************** * 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 */