UTS6710/aps/application/app_frmwrk/dvb/include/al_subtitle.h

/**
* Copyright(c) 2011 Sunmedia Technologies - All Rights Reserved.
*
* @file
*
* @brief this file defines subtitle interface for app layer.
*
* The file supports the subtitle functions by used for app layer. At present, the subtitle
* start/stop function include dvb subtitle and teletext function. When starting subtitle,
* the app layer only need send the index by user seletected on the subtitle menu and
* subtitle type to afw layer. The afw layer need start subtitle function with subtitle type.
* When stopping subtitle, afw layer need stop subtitle function with subtitle type.
*/

#ifndef __AL_SUBTITLE_H__
#define __AL_SUBTITLE_H__

#include "al_basictypes.h"

#ifdef __cplusplus
	extern "C"{
#endif

/**
* @brief define subtitle descriptor language code size.
*/
#define LANG_CODE_SIZE (3)

/**
* @brief structure definition for subtitle descriptor information.
*
* After one subtitle descriptor from the PMT is parsed, the information will
* be stored to subtitle descriptor buffer with the structure. \n
* Parsing descriptor information includes the information:
* @li pid: specify the pid of the transport stream packets which carry the
* associated program element.
* @li composition page id: identify the composition page that conveys
* subtitle elements for one specific subtitle service.
* @li ancillary page id: identify the ancillary page that conveys subtitle elements
* for being shared by multiple subtitle services within a subtitle stream.
* @li language: contain charater language code of language of subtitle.
* @li type: contain the subtitle type.
*/
typedef struct _AL_Subtitle_Desc_t
{
    al_int id;   /**< subtitle id by used when play recorded file*/
    al_uint16 Pid; /**< subtitle pid */
	al_uint16 CompositionPageId; /**< composition page id */
	al_uint16 AncillaryPageId; /**< ancillary page id */
	al_uint8 Language[LANG_CODE_SIZE]; /**< subtitle language */
	al_uint8 Type; /**< subtitle type */
} AL_Subtitle_Desc_Info_t;

/**
* @brief select the subtitle data type for gotten the subtitle data.
*/
typedef enum
{
	AL_SUBTITLE_DEMUX_CHAN = 0, /**< data comes from demux channel for TS */
	AL_SUBTITLE_PE_CHAN, /**< data comes from PE channel for recorded TS */
	AL_SUBTITLE_MAX /**<invalid data source */
}AL_Subtitle_Data_Source_t;

/**
* @brief select subtitle type.
*/
typedef enum
{
	AL_SUBTITLE_TYPE_DVB_SUBTITLE = 0, /**< dvb subtitle type */
	AL_SUBTITLE_TYPE_TTX_SUBTITLE, /**< teletext subtitle type */
	AL_SUBTITLE_TYPE_MAX /**< invalid subtitle type */
}AL_Subtitle_Type_t;

/**
* @brief subtitle start function.
*
* If the subtitle type is dvb subtitle, the function will start dvb subtitle function that
* creates decoder task and display task. The subtitle page id and pid will be set middleware
* layer. The subtitle data will be gotten to subtitle buffer by openning channel with
* pid, and the decoder task will parse data. Then display task will start to display subtitle
* on the screen. @n
* If the subtitle type is teletext subtitle, the function will be start teletext function that
* creates decoder task and render task. The subtitle page and magazine number and
* pid will be set middleware layer. The teletext data will be gotten to teletext buffer by
* openning channel with pid, and the decode task will parse data with page and magazine
* number. Then render task will start ti display teletext subtitle on the screen.
*
* @param Index user selects subtitle number on the subtitle menu, and using index, the special
* subtitle descriptor information will be gotten from subtitle descriptor buffer.
*
* @param SubtitleType subtitle type.
*
* @return AL_SUCCESS if starting is successful, AL_FAILURE otherwise.
*/
AL_Return_t AL_Subtitle_Start(al_int Index, AL_Subtitle_Type_t SubtitleType);

/**
* @brief subtitle restart function.
*
* Stop and restart subtitle if the selected subtitle is different from the one which is playing.
*
* @param Index user selects subtitle number on the subtitle menu, and using index, the special
* subtitle descriptor information will be gotten from subtitle descriptor buffer.
*
* @param SubtitleType subtitle type.
*
* @return AL_SUCCESS if starting is successful, AL_FAILURE otherwise.
*/
AL_Return_t AL_Subtitle_Restart(al_int Index, AL_Subtitle_Type_t SubtitleType);

/**
* @brief subtitle stop function.
*
* If the subtitle type is dvb subtitle, the function will delete decoder task and display task
* free the subtitle buffer. @n
* If the subtitle type is teletext subtitle, the function will suspend teletext decoder thread
* and delete render task.
*
* @param al_void.
*
* @return AL_SUCCESS if stoping is successful, AL_FAILURE otherwise.
*/
AL_Return_t AL_Subtitle_Stop(al_void);

/**
* @brief subtitle reset function.
*
* The buffer that stores subtitle descriptor information is static buffer, so
* it needs be reset with following initialization or a programe change.
*
* @param al_void.
*
* @return AL_SUCCESS if reseting is successful, AL_FAILURE otherwise.
*/
AL_Return_t AL_Subtitle_Reset(al_void);

/**
* @brief the function can get the valid subtitle descriptor total number.
*
* Before the subtitle module starts to work, it needs get the subtitle descpritor
* total number. if the total number is more than 0, the subtitle module will start
* to work. otherwise stop to work.
*
* @param *GetTotalNum get the dvb subtitle total number.
*
* @return AL_SUCCESS if getting total number is successful, AL_FAILURE otherwise.
*/
AL_Return_t AL_Subtitle_GetTotalNum(al_uint32 *GetTotalNum);

/**
* @brief the function can get the parsed subtitle descriptor information.
*
* After creating the subtitle menu with pressing subtitle key, the subtitle menu
* with all subtitle types will be shown on the screen. So when displayed information
* is inited, the parsed subtitle descriptor information will be gotten.
*
* @note Index value is less than the total subtitle descriptor number.
*
* @param Index using the index can get special subtitle descriptor information from
* the buffer.
*
* @param *SubtitleDescInfo it will store the gotten subtitle descriptor information.
*
* @return AL_SUCCESS if getting subtitle descriptor information is successful,
* AL_FAILURE otherwise.
*/
AL_Return_t AL_Subtitle_GetDescInfo(al_int Index,
	AL_Subtitle_Desc_Info_t *SubtitleDescInfo);

/**
* @brief the function can set subtitle display window freezed or not.
*
* After the video is freezed with pressing freeze key, if the subtitle is
* displaying on the screen, the subtitle needs be freezed. Else the
* video isn't freezed with pressing freeze key again,  if the subtitle is
* displaying on the screen, the subtitle needn't be freezed.
*
* @param FreezeStatus if freeze is true, the subtitle needs be freezed.
* Else if freeze is false, the subtitle needn't be freezed.
*
* @return AL_SUCCESS if setting freeze is successful,
* AL_FAILURE otherwise.
*/
AL_Return_t AL_Subtitle_SetFreeze(al_bool FreezeStatus);

/**
* @brief the function can get file ts subtitle information from pe module
*
* when play recorded file, if need to display subtitle on the screen, the file ts
*subtitle information need to be gotten from pe module.
*
* @param al_void.
*
* @return AL_SUCCESS if getting file ts subtitle information is successful,
* AL_FAILURE otherwise.
*/
AL_Return_t AL_Subtitle_GetFileTsSubInfo(al_void);

/**
* @brief the function can get the subtitle start status.
*
* @param* None.
*
* @return AL_SUCCESS if getting subtitle start flag is true,
* AL_FAILURE otherwise.
*/
AL_Return_t AL_Subtitle_GetStartFlag(void);

/**
* @brief the function can parse subtitle descriptor in PMT.
*
* After parsing PMT, PSI listener will start to work. When the stream
* type is private data of PES packet, and the descriptor type is subtitle
* descriptor, the subtitle descriptor will be parsing. When parsing the
* subtitle descriptor, the information: subtitle pid, subtitle language,
* subtitle type, composition page id and ancillary page id will be
* stored to subtitle buffer.
*
* @param *Data subtitle descpriptor data.
*
* @param DataLen the number of bytes of descriptors.
*
* @param Pid subtitle pid.
*
* @return AL_SUCCESS if parsing subtitle descriptor is successful,
* AL_FAILURE otherwise .
*/
AL_Return_t AL_Subtitle_ParseDesc(al_uint8 *Data, al_uint16 DataLen, al_uint16 Pid);

#ifdef __cplusplus
}
#endif
#endif