/*
 * Copyright (c) Hisilicon Technologies Co., Ltd. 2012-2019. All rights reserved.
 * Description: API of subtitle module
 * Author: Hisilicon
 * Create: 2012-03-12
 */
#ifndef UAPI_SUBT_H
#define UAPI_SUBT_H

#include "td_type.h"

#ifdef __cplusplus
#if __cplusplus
extern "C" {
#endif
#endif /* __cplusplus */

/* ************************** Structure Definition *************************** */
/* * \addtogroup      SUBTITLE */
/* * @{ */ /* * <!-- 【SUBTITLE】 */

/* * Invalid handle in subtitle */ /* * CNcomment:无效的字幕句柄 */
#define SUBT_INVALID_HANDLE 0x0
/* * the max item(language) in Subtitling descriptor */ /* * CNcomment:最大的字幕项(语言)个数 */
#define SUBT_ITEM_MAX_NUM 32
/* * the max subtitle instance */ /* * CNcomment:最大的字幕模块实例 */
#define SUBT_INSTANCE_MAX_NUM 8

/* * Defines the subtitle data type  */ /* * CNcomment: 定义字幕数据类型 */
typedef enum {
    UAPI_SUBT_DVB = 0x1, /* *< DVB subtitle */   /* *<CNcomment: DVB字幕 */
    UAPI_SUBT_SCTE = 0x2, /* *< SCTE subtitle */ /* *<CNcomment: SCTE字幕 */
    UAPI_SUBT_MAX
} uapi_subt_data_type;

/* * Defines the type used to code the subtitle */ /* * CNcomment:定义字幕编码类型枚举 */
typedef enum {
    UAPI_SUBT_TYPE_BITMAP = 0, /* *< Coding of bitmap */          /* *<CNcomment:位图编码 */
    UAPI_SUBT_TYPE_TEXT, /* *< Coded as a string of characters */ /* *<CNcomment:文本编码 */
    UAPI_SUBT_TYPE_MAX
} uapi_subt_type;

/* * Defines the status of the subtitling page */ /* * CNcomment:定义字幕页状态枚举 */
typedef enum {
    UAPI_SUBT_PAGE_NORMAL_CASE = 0,   /* *< Page update, use previous page instance to display */
    UAPI_SUBT_PAGE_ACQUISITION_POINT, /* *< Page refresh, use next page instance to display */
    UAPI_SUBT_PAGE_MODE_CHANGE,       /* *< New page, needed to display the new page */
    UAPI_SUBT_PAGE_MAX
} uapi_subt_page_state;

/* * Defines the data of the subtitle output */ /* * CNcomment:定义字幕输出数据结构体 */
typedef struct {
    uapi_subt_type data_type; /* *< The type used to code the subtitle */       /* *<CNcomment:字幕编码类型 */
    uapi_subt_page_state page_state; /* *< The status of the subtitling page */ /* *<CNcomment:字幕页状态 */
    td_u32 x; /* *< The horizontal address of subtitling page */                  /* *<CNcomment:x坐标 */
    td_u32 y; /* *< The vertical address of subtitling page */                    /* *<CNcomment:y坐标 */
    td_u32 w; /* *< The horizontal length of subtitling page */                   /* *<CNcomment:宽度 */
    td_u32 h; /* *< The vertical length of subtitling page */                     /* *<CNcomment:高度 */
    td_u32 bit_width; /* *< Bits in pixel-code */                                 /* *<CNcomment:位宽 */
    td_s64 pts; /* *< Presentation time stamp */                                  /* *<CNcomment:时间戳 */
    td_u32 duration; /* *< The period, expressed in ms, after which a page instance is no longer valid */
    td_u32 palette_item; /* *< Pixels of palette */       /* *<CNcomment:调色板长度 */
    td_void *palette; /* *< Palette data */               /* *<CNcomment:调色板数据 */
    td_u32 data_len; /* *< Subtitling page data length */ /* *<CNcomment:字幕数据长度 */
    td_u8 *subt_data; /* *< Subtitling page data */       /* *<CNcomment:字幕数据 */
    td_u32 display_width; /* *< Display canvas width */   /* *<CNcomment:显示画布的宽度 */
    td_u32 display_height; /* *< Display canvas height */ /* *<CNcomment:显示画布的高度 */
} uapi_subt_data;

/* * Defines the item of the subtitling content */ /* * CNcomment:定义字幕服务项结构体 */
typedef struct {
    td_u32 subt_pid; /* *<The pid for playing subtitle */  /* *<CNcomment:字幕pid */
    td_u16 page_id; /* *<The Subtitle page id */           /* *<CNcomment:字幕页id */
    td_u16 ancillary_id; /* *<The Subtitle ancillary id */ /* *<CNcomment:字幕辅助页id */
} uapi_subt_item;

/* * Defines the callback function which output the subtitling data */ /* * CNcomment:定义输出字幕数据的回调函数 */
typedef td_s32 (*uapi_subt_callback_func)(td_void *userdata, uapi_subt_data *data);

/* * Defines the callback function which get current pts */ /* * CNcomment:定义获取当前时间戳的回调函数 */
typedef td_s32 (*uapi_subt_getpts_callback_func)(td_void *userdata, td_s64 *pts);

/* * Defines the parameter of subtitle instance */ /* * CNcomment:定义字幕模块参数结构体 */
typedef struct {
    uapi_subt_item items[SUBT_ITEM_MAX_NUM]; /* *<The item of the subtitling content */
    td_u8 item_num;                            /* *<Amount of subtitling item */
    uapi_subt_callback_func output_func;     /* *<Callback function in which output subtitling page data */
    td_void *userdata;                         /* *<User data used in callback function */
    uapi_subt_data_type data_type;           /* *<subtitle data type in subt module */
} uapi_subt_param;

/* * @} */ /* * <!-- ==== Structure Definition end ==== */

/* ****************************** API Declaration **************************** */
/* * \addtogroup      SUBTITLE */
/* * @{ */ /* * <!-- [SUBTITLE] */

/* *
\brief Initialize subtitle module. CNcomment:初始化字幕模块。CNend
\attention \n
none. CNcomment:无。CNend
\retval ::TD_SUCCESS initialize success. CNcomment:初始化成功。CNend
\retval ::TD_FAILURE initialize failure. CNcomment:初始化失败。CNend
\see \n
none. CNcomment:无。CNend
*/
td_s32 uapi_subt_init(td_void);

/* *
\brief DeInitialize subtitle module. CNcomment:去初始化字幕模块。CNend
\attention \n
none. CNcomment:无。CNend
\retval ::TD_SUCCESS deinitialize success. CNcomment:去初始化成功。CNend
\retval ::TD_FAILURE deinitialize failure. CNcomment:去初始化失败。CNend
\see \n
none. CNcomment:无。CNend
*/
td_s32 uapi_subt_deinit(td_void);

/* *
\brief Create subtitle module. CNcomment:创建字幕模块。CNend
\attention \n
none. CNcomment:无。CNend
\param[in]  subtParam  parameters used in created subtitle. CNcomment:参数值。CNend
\param[out] handle        subtitle handle. CNcomment:字幕句柄。CNend
\retval ::TD_SUCCESS create success. CNcomment:创建成功。CNend
\retval ::TD_FAILURE create failure. CNcomment:创建失败。CNend
\see \n
none. CNcomment:无。CNend
*/
td_s32 uapi_subt_create(const uapi_subt_param *subtParam, td_handle *handle);

/* *
\brief Destroy subtitle module. CNcomment:销毁字幕模块。CNend
\attention \n
none. CNcomment:无。CNend
\param[in]  handle         subtitle handle. CNcomment:字幕句柄。CNend
\retval ::TD_SUCCESS destroy success. CNcomment:销毁成功。CNend
\retval ::TD_FAILURE destroy failure. CNcomment:销毁失败。CNend
\see \n
none. CNcomment:无。CNend
*/
td_s32 uapi_subt_destroy(td_handle handle);

/* *
\brief Select one subtitle content to output. CNcomment:切换字幕内容。CNend
\attention \n
none. CNcomment:无。CNend
\param[in]  handle         subtitle handle. CNcomment:字幕句柄。CNend
\param[in]  item   subtitle item. CNcomment:字幕内容项。CNend
\retval ::TD_SUCCESS switching success. CNcomment:切换成功。CNend
\retval ::TD_FAILURE switching failure. CNcomment:切换失败。CNend
\see \n
none. CNcomment:无。CNend
*/
td_s32 uapi_subt_switch_content(td_handle handle, const uapi_subt_item *item);

/* *
\brief Reset subtitle module. CNcomment:复位字幕模块。CNend
\attention \n
none. CNcomment:无。CNend
\param[in]  handle         subtitle handle. CNcomment:字幕句柄。CNend
\retval ::TD_SUCCESS reset success. CNcomment:复位成功。CNend
\retval ::TD_FAILURE reset failure. CNcomment:复位失败。CNend
\see \n
none. CNcomment:无。CNend
*/
td_s32 uapi_subt_reset(td_handle handle);

/* *
\brief Update subtitle module. CNcomment:更新字幕模块。CNend
\attention \n
none. CNcomment:无。CNend
\param[in]  subt         subtitle handle. CNcomment:字幕句柄。CNend
\param[in]  param  the new subtitle content. CNcomment:新的字幕内容信息。CNend
\retval ::TD_SUCCESS update success. CNcomment:更新成功。CNend
\retval ::TD_FAILURE update failure. CNcomment:更新失败。CNend
\see \n
none. CNcomment:无。CNend
*/
td_s32 uapi_subt_update(td_handle handle, const uapi_subt_param *param);

/* *
\brief Inject DVB subtitle stream to decoder. CNcomment:注入字幕数据到解码器。CNend
\attention \n
Used the PES packet syntax for carriage of DVB subtitles. CNcomment:DVB字幕传输使用PES格式。CNend
\param[in]  handle         subtitle handle. CNcomment:字幕句柄。CNend
\param[in]  subt_pid    the pid of subtitle stream. CNcomment:字幕流pid。CNend
\param[in]  data       subtitle stream data. CNcomment:字幕数据。CNend
\param[in]  data_size   the size of subtitle stream data. CNcomment:字幕数据长度。CNend
\retval ::TD_SUCCESS inject success. CNcomment:注入成功。CNend
\retval ::TD_FAILURE inject failure. CNcomment:注入失败。CNend
\see \n
none. CNcomment:无。CNend
*/
td_s32 uapi_subt_inject_data(td_handle handle, td_u32 subt_pid, const td_u8 *data, td_u32 data_size);

/* *
\brief Register the callback function geted current pts.
CNcomment:注册获取当前时间戳的回调函数。CNend
\attention \n
none. CNcomment:无。CNend
\param[in]  handle         subtitle handle. CNcomment:字幕句柄。CNend
\param[in]  getpts_func     callback funtion which geted current pts. CNcomment:获取当前时间戳的回调函数。CNend
\param[in]  userdata   userdata which used in callback funtion. CNcomment:回调函数的用户数据。CNend
\retval   ::TD_SUCCESS    success. CNcomment:成功。CNend
\retval   ::TD_FAILURE    failure. CNcomment:失败。CNend
\see \n
none. CNcomment: 无。CNend
*/
td_s32 uapi_subt_reg_getpts(td_handle handle, uapi_subt_getpts_callback_func getpts_func, td_void *userdata);

/* * @} */ /* * <!-- ==== API declaration end ==== */

#ifdef __cplusplus
#if __cplusplus
}
#endif
#endif /* __cplusplus */

#endif