.. _gif-dec:

GIF解码器
======================

简介
-------------------------
    gif解码

特点
-------------------------
    1. 仅支持GIF89a版本，不支持GIF87a
    2. 最低每行像素输出，每个像素使用RGB888表示

API说明
-------------------------

.. c:struct:: gifdec_init_pramater_t

    解码器初始化参数结构体

    .. c:member:: void* file_info

        解码gif文件名

    .. c:member:: int16_t dis_width
        
        显示图像宽度

    .. c:member:: int16_t dis_higth

        显示图像高度，暂时无效

    .. c:member:: int16_t dis_offsetx

        显示宽度偏移，暂时无效，

    .. c:member:: int16_t dis_offsety

        显示高度偏移，暂时无效

.. c:function:: int32_t gifdec_init(gifdec_init_pramater_t* init_pramater)

    解码初始化

    :param init_pramater: gifdec_init_pramater_t类型指针。详细信息参看 gifdec_init_pramater_t
    :returns: 解码器初始化后的SRAM空间已使用的总量(字节数)。
    :retval >0: 解码器使用到sram的等高线
    :retval -1: SRAM不足，初始化失败。
    :retval -2: gif文件打开失败。
    :retval -3: gif解析失败，非gif文件。


.. c:enum:: gifdec_cmd_t

    解码器控制命令

    - *Gifdec_CMD_Stop*: 值为0，解码停止，暂无效
    - *Gifdec_CMD_Start*: 值为1，解码开始，
    - *Gifdec_CMD_Pause*: 值为2，解码暂停，暂无效
    - *Gifdec_CMD_Resume*: 值为3，恢复解码暂停，暂无效

.. c:function:: int32_t gifdec_cmd(gifdec_cmd_t cmd)

    解码初始化，行解码完成后，需要再次调用此函数，才会继续解码

    :param cmd: gifdec_cmd_t枚举定义。详细信息参看 gifdec_cmd_t
    :retval 0: 成功
    :retval 其它: 失败。

.. c:function:: int32_t gifdec_set_frame_row_hook(void (*frme_row_hook)())

  可选配钩子函数，每行解码完成钩子函数。此函数调用，代表可调用gifdec_get_rgbrow()读取行像素信息

  :param frme_row_hook: 钩子函数，要求无参无返回值。
  :retval  0: 钩子函数设置成功。
  :retval -1: 失败

.. c:function:: int32_t gifdec_set_frame_hook(void (*frme_hook)())

  可选配钩子函数，每帧解码完成钩子函数

  :param frme_row_hook: 钩子函数，要求无参无返回值。
  :retval  0: 钩子函数设置成功。
  :retval -1: 失败

.. c:function:: int32_t gifdec_set_end_hook(void (*end_hook)())

  可选配钩子函数，所有帧图像解码完成

  :param frme_row_hook: 钩子函数，要求无参有返回。返回值 :非0停止解码 ；返回0继续从头开始解码
  :retval  0: 钩子函数设置成功。
  :retval -1: 失败
  :note: 若不注册，根据图像保存次数重复

.. c:function:: int32_t gifdec_get_rgbrow(uint8_t *buf_last_row,uint8_t *buf_row,int16_t*offset_x )

  从解码器中获取一行rgb图像rgb888

  :param buf_last_row: 上一帧此一整行显示的图像， rgb888
  :param buf_row: 解码行图像，带有行偏移 rgb888
  :param offset_x: 行宽度上的偏移 in pixel
  :retval  0: 成功。
  :retval -1: 失败

.. c:struct:: gifdec_info_t

    解码器状态结构体

    .. c:member:: uint16_t width

        解码显示图像宽度 in pixel

    .. c:member:: uint16_t height
        
        解码显示图像高度

    .. c:member:: uint16_t fy

        解码帧高度偏移

    .. c:member:: uint16_t fw

        解码帧图像宽度

    .. c:member:: int16_t current_row

        解码帧的当前行，未偏移fy

    .. c:member:: int16_t disposal

        解码行处理方式

    .. c:member:: int32_t delay

        解码帧延迟 in 10ms

.. c:function:: int32_t gifdec_get_status(gifdec_info_t *info)

  获取解码器状态

  :param info: 解码器状态信息，参看gifdec_info_t
  :retval  0: 成功。
  :retval -1: 失败

使用方法
-------------------------

 .. image:: ../../_static/gifdec-fsm.png
  :align: center

 1. 调用函数gifdec_init()初始化解码，并开始获取gif基本信息.并注册行、帧、完成回调函数
 2. 调用函数gifdec_cmd()开始解码
 3. 行回调函数，可调用gifdec_get_rgbrow()获取行像素信息
 4. 帧回调函数，调用gifdec_get_status()获取帧延迟时间
 5. 结束回调函数，返回值非0停止解码，返回0可继续从头解码
 6. 再次调用ifdec_cmd()开始解码


demo工程
-------------------------
SDk中demo工程gifdec