/*
 * Copyright (c) Hisilicon Technologies Co., Ltd. 2010-2019. All rights reserved.
 * Description: Subtitle output Module
 * Author: Hisilicon
 * Create: 2010-03-10
 */
#ifndef UAPI_SO_H
#define UAPI_SO_H

#include "td_type.h"

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

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

/* * Number of palette */ /* * CNcomment:调色板颜色个数 */
#define UAPI_SO_PALETTE_ENTRY 256

/* * Invalid pts value */ /* * CNcomment:无效的PTS值 */
#define UAPI_SO_NO_PTS (-1)

/* * The max node in SO */ /* * CNcomment:SO能缓存的最大节点数 */
#define UAPI_SO_MAX_NODE_NUM 20

/* * The max buffer size */ /* * CNcomment:SO最大的缓存长度 */
#define UAPI_SO_MAX_BUFFER_SIZE 0x200000

/* * Subtitle type */ /* * CNcomment:字幕类型 */
typedef enum {
    UAPI_SUBTITLE_BITMAP = 0x0, /* *<Bmp subtitle */ /* *<CNcomment:图像字幕 */
    UAPI_SUBTITLE_TEXT, /* *<Text subtitle */        /* *<CNcomment:string字幕 */
    UAPI_SUBTITLE_ASS, /* *<Ass/ssa sbutitle */      /* *<CNcomment:ass字幕 */
    UAPI_SUBTITLE_MAX
} uapi_so_subtitle_type;

/* * Message type of subtitle */ /* * CNcomment:显示消息，对于teltext，含显示和擦除两个消息 */
typedef enum {
    UAPI_SO_DISP_MSG_NORM = 0x0, /* *<Draw the subtitle */ /* *<CNcomment:正常显示数据 */
    UAPI_SO_DISP_MSG_ERASE, /* *<Clear the subtitle */     /* *<CNcomment:擦除 */
    UAPI_SO_DISP_MSG_END /* *<Message of drawing a page */ /* *<CNcomment:整页显示结束 */
} uapi_so_disp_msg_type;

/* * The parameter of clear region */ /* * CNcomment:擦除参数 */
typedef struct {
    td_u32 x, y, w, h; /* *<Postion of clearing */ /* *<CNcomment:擦除位置和高宽信息 */
    td_s64 clear_time; /* *<Clear operation time, larger than or equal to s64NodePts+u32Duration */
                       /* *<CNcomment:擦除操作发生的时间,大于等于s64NodePts+u32Duration */
    td_s64 node_pts; /* *<the present pts of sub */      /* *<CNcomment:字幕显示时间戳 */
    td_u32 duration; /* *<the present duration of sub */ /* *<CNcomment:字幕显示时间长度 */
} uapi_so_clear_param;

/* * Color components  */ /* * CNcomment:颜色结构 */
typedef struct {
    td_u8 red; /* *<Red component */     /* *<CNcomment:R分量颜色值 */
    td_u8 green; /* *<Green component */ /* *<CNcomment:G分量颜色值 */
    td_u8 blue; /* *<Blue component */   /* *<CNcomment:B分量颜色值 */
    td_u8 alpha; /* *<Alpha component */ /* *<CNcomment:透明度，值为0为透明，0xFF为不透明 */
} uapi_so_color;

/* * Information of bitmap subtitle */ /* * CNcomment:图像字幕信息 */
typedef struct {
    td_s64 pts; /* *<Start a display time, unit is Millisecond */        /* *<CNcomment:显示时间戳，单位ms */
    td_u32 duration; /* *<Duration of displaying, unit is Millisecond */ /* *<CNcomment:显示时长，单位ms */
    td_u32 len; /* *<Bytes of subtitle data */                           /* *<CNcomment:数据长度，单位字节 */
    td_u8 *pix_data; /* *<Data of subtitle */                            /* *<CNcomment:图像数据 */

    uapi_so_disp_msg_type msg_type; /* *<Type of display message */ /* *<CNcomment:显示消息类型 */
    uapi_so_color palette[UAPI_SO_PALETTE_ENTRY]; /* *<Palette */ /* *<CNcomment:调色板，ARGB8888 */
    td_s32 bit_width; /* *<Bits of Pix */                   /* *<CNcomment:象素位宽 , 可以为 2,4,8位 */
    td_u32 x, y, w, h; /* *<Position of display subtitle */ /* *<CNcomment:显示位置和高宽信息 */
    td_u32 canvas_width; /* *<Display canvas width */       /* *<CNcomment:显示画布的宽度信息 */
    td_u32 canvas_height; /* *<Display canvas height */     /* *<CNcomment:显示画布的高度信息 */
} uapi_so_gfx;

/* * Infomation of text subtitle */ /* * CNcomment:文本字幕信息 */
typedef struct {
    td_s64 pts; /* *<Start a display time, unit is Millisecond */        /* *<CNcomment:显示时间戳，单位ms */
    td_u32 duration; /* *<Duration of displaying, unit is Millisecond */ /* *<CNcomment:显示时长，单位ms */
    td_u32 len; /* *<Bytes of subtitle data */ /* *<CNcomment:字幕数据长度，单位字节 */
    td_u8 *data; /* *<Data of subtitle */      /* *<CNcomment:字幕数据 */

    td_u32 x, y, w, h; /* *<Position of display subtitle */ /* *<CNcomment:显示位置和高宽信息 */
} uapi_so_text;

/* * Infomation of ass/ssa subtitle */ /* * CNcomment:ass字幕信息 */
typedef struct {
    td_s64 pts; /* *<Start a display time, unit is Millisecond */        /* *<CNcomment:显示时间戳，单位ms */
    td_u32 duration; /* *<Duration of displaying, unit is Millisecond */ /* *<CNcomment:显示时长，单位ms */
    td_u32 frame_len; /* *<Bytes of subtitle data */                     /* *<CNcomment:帧长度，单位字节 */
    td_u8 *frame_data; /* *<Data of subtitle */                          /* *<CNcomment:帧数据 */
    td_u32 extra_data_size; /* *<Length of extra data */ /* *<CNcomment:扩展数据长度，单位字节 */
    td_u8 *extra_data; /* *<Extra data */                /* *<CNcomment:扩展数据 */
} uapi_so_ass;

/* * Infomation of subtitle */ /* * CNcomment:字幕信息 */
typedef struct {
    uapi_so_subtitle_type subt_type; /* *<type */ /* *<CNcomment:字幕类型 */

    union {
        uapi_so_gfx gfx; /* *<gfx subtitle */    /* *<CNcomment:图形字幕 */
        uapi_so_text text; /* *<text subtitle */ /* *<CNcomment:文本字幕 */
        uapi_so_ass ass; /* *<ass subtitle */    /* *<CNcomment:ASS字幕 */
    } subtitle_param;
} uapi_so_subtitle_info;

/* *
\brief Call back funtion of getting current play time.
CNcomment:获取当前播放帧的时间戳，如果当前时间无效，ps64CurrentPts赋值为UAPI_SO_NO_PTS。CNend
\attention \n
None
\param[in] userdata Userdata.CNcomment:注册传入的用户态数据。CNend
\param[out] current_pts Current play time. CNcomment:当前播放帧时间戳，单位ms。CNend

\retval ::TD_SUCCESS

\see \n
None
*/
typedef td_s32 (*uapi_so_getpts_callback_func)(td_void *userdata, td_s64 *current_pts);

/* *
\brief Callback funtion of drawing the subtitle. CNcomment:字幕画图回调函数。CNend
\attention \n
None
\param[in] userdata Userdata. CNcomment:注册传入的用户态数据。CNend
\param[in] info Information of subtitle. CNcomment:字幕信息。CNend
\param[in] arg User data. CNcomment:扩展数据。CNend

\retval ::TD_SUCCESS

\see \n
None
*/
typedef td_s32 (*uapi_so_ondraw_callback_func)(td_void *userdata, const uapi_so_subtitle_info *info, td_void *arg);

/* *
\brief Call back funtion of clearing the subtitle. CNcomment:字幕显示到时清除函数。CNend
\attention \n
None
\param[in] userdata User data. CNcomment:注册传入的用户态数据。CNend
\param[out] arg Parameter of clearing the subtitle, Type is uapi_so_clear_param. CNcomment:擦除参数，
            指向uapi_so_clear_param结构。CNend

\retval ::TD_SUCCESS

\see \n
None
*/
typedef td_s32 (*uapi_so_onclear_callback_func)(td_void *userData, td_void *arg);

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

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

/* *
\brief  Init SO module. CNcomment:subtitle output 模块初始化。CNend
\attention \n
None
\param None

\retval ::TD_SUCCESS Init success. CNcomment:初始化成功。CNend
\retval ::TD_FAILURE Operation fail. CNcomment:初始化失败。CNend

\see \n
None
*/
td_s32 uapi_so_init(td_void);

/* *
\brief  Deinit SO module. CNcomment:subtitle output 模块去初始化。CNend
\attention \n
None
\param None

\retval ::TD_SUCCESS  Deinit success. CNcomment:去初始化成功。CNend
\retval ::TD_FAILURE Operation fail. CNcomment:去初始化失败。CNend

\see \n
None
*/
td_s32 uapi_so_deinit(td_void);

/* *
\brief  Creates an SO instance. CNcomment:创建一个so实例。CNend
\attention \n
None
\param[out] handle Handle of SO instance. CNcomment:播放器实例。CNend

\retval ::TD_SUCCESS  Create success. CNcomment:创建成功，句柄有效。CNend
\retval ::TD_FAILURE  Operation fail. CNcomment:创建失败。CNend

\see \n
None
*/
td_s32 uapi_so_create(td_handle *handle);

/* *
\brief  Destroy an SO instance. CNcomment:销毁一个so实例。CNend
\attention \n
None
\param[in] handle Handle of SO instance. CNcomment:so实例句柄。CNend

\retval ::TD_SUCCESS  Destroy success. CNcomment:销毁成功。CNend
\retval ::TD_FAILURE  Operation fail. CNcomment:销毁失败，参数非法。CNend

\see \n
None
*/
td_s32 uapi_so_destroy(td_handle handle);

/* *
\brief  Setting offset time of the subtitle. CNcomment:设置字幕时间偏移。CNend
\attention \n
None
\param[in] handle Handle of SO instance. CNcomment:so实例句柄。CNend
\param[in] offset_us Offset of subtitle, unit is Millisecondes.CNcomment:字幕显示时间偏移值，单位ms。CNend

\retval ::TD_SUCCESS  Operation success. CNcomment:成功。CNend
\retval ::TD_FAILURE  Operation fail. CNcomment:失败。CNend

\see \n
None
*/
td_s32 uapi_so_set_offset(td_handle handle, td_s64 offset_us);

/* *
\brief  Register the callback function of getting current play time.
        CNcomment:注册时间戳获取回调函数，so通过获取当前播放时间戳同步字幕。CNend
\attention \n
None
\param[in] handle Handle of SO instance.CNcomment:so实例句柄。CNend
\param[in] getpts_func Callback function. CNcomment:回调函数参数。CNend
\param[in] userdata User data. CNcomment:用户态数据。CNend

\retval ::TD_SUCCESS  Register success. CNcomment:注册成功。CNend
\retval ::TD_FAILURE  Parameter invalid. CNcomment:注册失败。CNend

\see \n
None
*/
td_s32 uapi_so_reg_getpts(td_handle handle, uapi_so_getpts_callback_func getpts_func, td_void *userdata);

/* *
\brief  Register the callback function of drawing subtitle.
CNcomment:注册字幕绘制清除回调函数，如果设置了该函数，则so使用该函数实现字幕输出，
          字幕显示时长到达后，so调用清除函数通知清除。CNend
\attention \n
None
\param[in] handle Handle of SO instance. CNcomment:so实例句柄。CNend
\param[in] draw_func Callback function of drawing subtitle. CNcomment:绘制函数。CNend
\param[in] clear_func Callback function of clearing subtitle. CNcomment:清除函数。CNend
\param[in] userdata User data. CNcomment:用户态数据。CNend

\retval ::TD_SUCCESS  Register success. CNcomment:注册成功。CNend
\retval ::TD_FAILURE Parameter invalid. CNcomment:注册失败。CNend

\see \n
None
*/
td_s32 uapi_so_reg_draw(td_handle handle, uapi_so_ondraw_callback_func draw_func,
    uapi_so_onclear_callback_func clear_func, td_void *userdata);

/* *
\brief  Set the surface of drawing subtitle, if you do not set the ondraw callback function,
        SO painting subtitles with the surface.
CNcomment:设置字幕绘制画布句柄，如果没有设置ondraw回调函数，则so使用设置的画布句柄输出字幕。CNend
\attention \n
This feature is not implemented. CNcomment:该功能未实现。CNend
\param[in] handle Handle of SO instance.CNcomment:so实例句柄。CNend
\param[in] surface_handle Handle of surface. CNcomment:画布句柄。CNend

\retval ::TD_SUCCESS Success of setting surface. CNcomment:设置成功。CNend
\retval ::TD_FAILURE  Operation invalid. CNcomment:设置失败。CNend

\see \n
None
*/
td_s32 uapi_so_set_surface(td_handle handle, td_handle surface_handle);

/* *
\brief  Set the font of drawing subtitle.
CNcomment:设置字幕显示字体，该设置仅对设置画布输出字幕的方式起作用。CNend
\attention \n
This feature is not implemented. CNcomment:该功能未实现。CNend
\param[in] handle Handle of SO instance.CNcomment:so实例句柄。CNend
\param[in] font Handle of font instance.CNcomment:创建的字体句柄。CNend

\retval ::TD_SUCCESS  Success.CNcomment:设置成功。CNend
\retval ::TD_FAILURE  Operation invalid. CNcomment:设置失败。CNend

\see \n
None
*/
td_s32 uapi_so_set_font(td_handle handle, td_handle font);

/* *
\brief Set the color of drawing text subtitle.
CNcomment:设置字幕显示颜色，该设置仅对设置画布输出字幕的方式起作用。CNend
\attention \n
This feature is not implemented. CNcomment:该功能未实现。CNend
\param[in] handle Handle of SO instance. CNcomment:so实例句柄。CNend
\param[in] color Value of the color. CNcomment:颜色值。CNend

\retval ::TD_SUCCESS  Success. CNcomment:设置成功。CNend
\retval ::TD_FAILURE  Operation invalid. CNcomment:设置失败。CNend

\see \n
None
*/
td_s32 uapi_so_set_color(td_handle handle, td_u32 color);

/* *
\brief Set the position of display subtitle.
CNcomment:设置字幕显示坐标，该设置仅对设置画布输出字幕的方式起作用。CNend
\attention \n
This feature is not implemented. CNcomment:该功能未实现。CNend
\param[in] handle Handle of SO instance. CNcomment:so实例句柄。CNend
\param[in] x Value of x coordinate.CNcomment:x坐标。CNend
\param[in] y Value of y coordinate. CNcomment:y坐标。CNend

\retval ::TD_SUCCESS  Success. CNcomment:设置成功。CNend
\retval ::TD_FAILURE  Parameter invalid. CNcomment:设置失败。CNend

\see \n
None
*/
td_s32 uapi_so_set_pos(td_handle handle, td_u32 x, td_u32 y);

/* *
\brief  Getting the number in the butitle queue.
CNcomment:获取缓冲buffer中未显示的字幕数据个数。CNend
\attention \n
None
\param[in] handle Handle of SO instance. CNcomment:so实例句柄。CNend
\param[out] num Number of subtitles in queue. CNcomment:缓冲字幕个数。CNend

\retval ::TD_SUCCESS Success. CNcomment:成功。CNend
\retval ::TD_FAILURE Operation fail. CNcomment:失败。CNend

\see \n
None
*/
td_s32 uapi_so_get_remaining_subt(td_handle handle, td_u32 *num);

/* *
\brief Clear the subtitles in queue.
CNcomment:清除字幕缓冲中的数据，字幕切换时，需调用该接口清除so字幕缓存。CNend
\attention \n
None
\param[in] handle Handle of SO instance. CNcomment:so实例句柄。CNend

\retval ::TD_SUCCESS Success. CNcomment:成功。CNend
\retval ::TD_FAILURE Operation invalid. CNcomment:失败。CNend

\see \n
None
*/
td_s32 uapi_so_reset_buf(td_handle handle);

/* *
\brief  Clear the subtitles in queue by PTS. If PTS is 0, the same as UAPI_SO_ResetSubBuf.
CNcomment:清除字幕缓冲中的数据,小于指定PTS的字幕缓冲被清除.如果指定PTS值为0,这个接口等效于UAPI_SO_ResetSubBuf。CNend
\attention \n
None
\param[in] handle Handle of SO instance. CNcomment:so实例句柄。CNend
\param[in] pts    Pts of data. CNcomment:so实例句柄。CNend

\retval ::TD_SUCCESS Success. CNcomment:成功。CNend
\retval ::TD_FAILURE Operation invalid. CNcomment:失败。CNend

\see \n
None
*/
td_s32 uapi_so_reset_buf_pts(td_handle handle, td_s64 pts);

/* *
\brief  Send subtitles to SO queue. If the data size and the number is larger than the value set by the user,
        then the transmission fails.
CNcomment:发送字幕数据给so，如果缓冲size和个数都超过用户设置的值，则发送失败。CNend
\attention \n
None
\param[in] handle Handle of SO instance. CNcomment:so实例句柄。CNend
\param[in] info Data of subtitle. CNcomment:字幕信息。CNend
\param[in] timeout_ms Timeout of sending subtitle. CNcomment:发送超时时间，单位ms。CNend

\retval ::TD_SUCCESS  Success. CNcomment:发送成功。CNend
\retval ::TD_FAILURE  Operation fail.CNcomment:发送失败。CNend

\see \n
None
*/
td_s32 uapi_so_send_data(td_handle handle, const uapi_so_subtitle_info *info, td_u32 timeout_ms);

/* *
\brief  Get current subt data in SO queue.
CNcomment:获取SO 队列中，当前正在处理的字幕数据。CNend
\attention \n
None
\param[in] handle Handle of SO instance. CNcomment:so实例句柄。CNend
\param[in] info   Data of subtitle. CNcomment:字幕信息。CNend

\retval ::TD_SUCCESS  Success. CNcomment:发送成功。CNend
\retval ::TD_FAILURE  Operation fail.CNcomment:发送失败。CNend

\see \n
None
*/
td_s32 uapi_so_get_cur_data(td_handle handle, uapi_so_subtitle_info *info);

/* *
\brief  Setting max interval time of the subtitle.
CNcomment:设置字幕最大的时间偏差。CNend
\attention \n
None
\param[in] handle Handle of SO instance. CNcomment:so实例句柄。CNend
\param[in] interval_ms max interval of subtitle, unit is Millisecondes.
CNcomment:字幕最大的时间偏差值，单位ms。CNend

\retval ::TD_SUCCESS  Operation success. CNcomment:成功。CNend
\retval ::TD_FAILURE  Operation fail. CNcomment:失败。CNend

\see \n
None
*/
td_s32 uapi_so_set_max_interval(td_handle handle, td_u32 interval_ms);

/* * @} */ /* * <!-- ==== API Declaration End ==== */

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

#endif /* UAPI_SO_H */