eZIP工具¶

1. 简介¶

eZIP是思澈开发硬件级无损压缩加速模块，直接集成在 SoC 架构中。通过eZIP硬件，将有效的降低数据传输带宽、减少存储空间占用、提高系统帧率。
eZIP软件工具是为了适配eZIP硬件而开发的一个图片（png、gif、bmp）转换（压缩）工具，同时也提供了其他类型图形（jpg、mp4）的格式转换功能。版本2.6.9开始支持bmp。

2. 主命令¶

完整命令	主参数	功能描述
`eZIP -convert xxx`	`[-binfile 1]`	转换一个图片为像素bin文件，开头包含4个字节（v9是12个字节）的`lv_img_header_t`头
`eZIP -convert xxx`	`[-binfile 2]`	转换一个图片为eZIP压缩后的bin文件，开头包含4个字节（v9是12个字节）`lv_img_header_t`头
`eZIP -convert xxx`	`[-cfile 1]`	转换一个图片为像素c文件，使用`lv_img_dsc_t`数据结构
`eZIP -convert xxx`	`[-cfile 2]`	转换一个图片为eZIP压缩的c文件，使用`lv_img_dsc_t`数据结构
`eZIP -dir xxx`	`[-binfile 1 [wxh]]`	转换一个目录下对应分辨率的图片为像素bin文件
`eZIP -dir xxx`	`[-binfile 2 [wxh]]`	转换一个目录下对应分辨率的图片为eZIP压缩后的bin文件
`eZIP -dir xxx`	`[-cfile 1 [wxh]]`	转换一个目录下对应分辨率的图片为像素c文件
`eZIP -dir xxx`	`[-cfile 2 [wxh]]`	转换一个目录下对应分辨率的图片为eZIP压缩的c文件
`eZIP -lz4 xxx`		使用lz4压缩xxx文件
`eZIP -unlz4 xxx`		解压-lz4压缩的文件
`eZIP -gzip xxx`		使用gzip压缩xxx文件
`eZIP -ungzip xxx`		解压-gzip压缩的文件
`eZIP -img2jpg xxx`	`[-cfile 2]` `[-binfile 2]` `[-quality xx]`	显式转换png或bmp图片为jpg；jpg不支持alpha，带alpha图片会丢失透明信息或被合成。

3. 命令参数¶

2.1 -convert xxx¶

作用
- 转换一张图片（.png、.bmp、.gif、.jpg、 .mp4、.c）或一个freetype（.ttf）文件。其中，
  - .png：将转换为芯片硬件支持的eZIP格式
  - .bmp：版本2.6.9开始支持。带alpha的bmp将转换为带alpha的eZIP格式，不带alpha的bmp将转换为普通eZIP格式
  - .gif：将转换为芯片硬件支持的agif格式
  - .c：支持lvgl的像素格式的c文件转换为eZIP格式
  - .jpg：保持jpg格式，根据参数-cfile或-binfile转换为c或jpg格式
  - .mp4：保持mp4格式，根据参数-cfile或-binfile转换为c或mp4格式
  - .ttf: 保持ttf数据，根据参数-cfile或-binfile转换为c或ttf/bin格式

可选参数

转换类型（默认是binfile 2)

参数类型	功能描述
`-binfile 1`	转换为像素bin文件，开头包含`lv_img_header_t`头
`-binfile 2`	转换为eZIP压缩后的bin文件，开头包含`lv_img_header_t`头
`-cfile 1`	转换为像素c文件，使用`lv_img_dsc_t`数据结构
`-cfile 2`	转换为eZIP压缩的c文件，使用`lv_img_dsc_t`数据结构

芯片类型（默认是sf55x)

参数类型

功能描述

-chip xxx

default: sf55x
-chip sf55x
-chip sf58x
-chip sf56x
-chip sf52x
-chip sf57x
-chip sf…x [注：将来芯片命名]
输出颜色（默认是-rgb565）

参数类型

功能描述

-rgb565

输出565格式。如果原图是带alpha的，则输出是带alpha的

-rgb888

输出888格式。如果原图是带alpha的，则输出是带alpha的
lvgl版本（默认是-lvgl_version 8）

参数类型

功能描述

-lvgl_version 9

生成lvgl v9格式的数据
是否需要dither（默认是-dither 1）

参数类型

功能描述

-dither 0

888转换为565的时候不做dither

-dither 1

888转换为565的时候做dither
生成C文件时数据结构变量的段名（默认是ROM3_IMG）

参数类型

功能描述

-section XXX

定义生成C文件时数据结构变量的段名。其中lv_img_dsc_t的头段名为XXX_HEADER
生成bin文件时扩展名（默认是.bin）

参数类型

功能描述

-binext .xxx

生成bin文件时，文件的扩展名为.xxx
提取alpha，生成mask

参数类型

功能描述

-mask

从带alpha的png中提取alpha
生成文件的输出目录（默认输出目录是output）

参数类型

功能描述

-outdir xxx

生成文件的输出到xxx目录

参数类型	功能描述
`-chip xxx`	default: sf55x -chip sf55x -chip sf58x -chip sf56x -chip sf52x -chip sf57x -chip sf…x [注：将来芯片命名]

参数类型	功能描述
`-rgb565`	输出565格式。如果原图是带alpha的，则输出是带alpha的
`-rgb888`	输出888格式。如果原图是带alpha的，则输出是带alpha的

参数类型	功能描述
`-lvgl_version 9`	生成lvgl v9格式的数据

参数类型	功能描述
`-section XXX`	定义生成C文件时数据结构变量的段名。其中lv_img_dsc_t的头段名为XXX_HEADER

参数类型	功能描述
`-binext .xxx`	生成bin文件时，文件的扩展名为`.xxx`

参数类型	功能描述
`-mask`	从带alpha的png中提取alpha

参数类型	功能描述
`-outdir xxx`	生成文件的输出到xxx目录

2.2 -dir xxx¶

作用

转换一个目录（包括子目录）。采用-dir时，目录下的资源有两种组织方式：

Solution下要求的资源放置方式，需要严格按照图片资源的位置。此种方式下，命令行必须带分辨率[wxh]，例如ezip -dir images -cfile 2 410x494。eZIP只处理common和命令行指定分辨率目录下的资源，其他分辨率目录会跳过。

目录要求如下：
  +- images/
    +- app_name/               # 每个应用单独一个目录
      +- common/               # 所有分辨率共用资源
        +- ezip/
        +- ezip_dither/
        +- no_ezip/
        +- gif/
        +- mp4/
        +- mask/
        +- jpg/
      +- 410x494/              # 指定分辨率资源，目录名必须为 宽x高
        +- ezip/
        +- ezip_dither/
        +- no_ezip/
        +- gif/
        +- mp4/
        +- mask/
        +- jpg/

分辨率目录要求：
- `common`：所有分辨率共用的图片资源。
- `[wxh]`：某个分辨率专用的图片资源，例如`410x494`；命令行带`410x494`时，只处理`common`和`410x494`。

资源类型子目录要求：
- `ezip_dither`： `-dither 3`时，且输出rgb565时，存放需要非旋转但有渐进色的图片
- `ezip`： 存放非旋转的png/bmp图片。 eZIP在`-binfile 2`或`-cfile 2`的时候，会进行压缩处理，否则转换为像素的c文件或bin文件。版本2.6.9开始支持bmp：带alpha的bmp输出带alpha的eZIP，不带alpha的bmp输出不带alpha的eZIP
- `no_ezip`： 存放需要旋转的png/bmp图片。eZIP不做压缩处理，直接转换为像素的c文件或bin文件
- `gif`： 存放gif图片。 eZIP在`-binfile 2`或`-cfile 2`的时候，会进行压缩处理；否则，直接转换为c文件或bin文件
- `mp4`： 存放h264的视频。eZIP不做压缩处理，直接转换为c文件或bin文件
- `mask`： 存放作为mask的图片。eZIP会抽取该图片所有像素的alpha
- `jpg`： 存放jpg图片。支持Baseline jpg、渐进式或非YUV420的jpg，eZIP会先规范化为硬件支持的Baseline YUV420 jpg，再转换为c文件或bin文件

如果命令行包含`-img2jpg`，则`ezip`目录下无alpha的png/bmp图片会先按eZIP路径编码，再生成jpg候选并比较实际输出大小；只有jpg候选小于eZIP结果时才输出jpg。带alpha的png/bmp不会转jpg，仍按eZIP路径输出。

图片资源在xxx目录下随意放置（命令行不带分辨率）此种方式下，eZIP会根据会直接根据-binfile/-cfile后面跟的数字1或2决定怎么转换。如果是1，则是转换为像素；如果是2，则是进行压缩处理。

注意：使用-dir命令，如果使用-cfile，会自动生成一个头文件（通常按输入目录命名，形如 xxx_header.h），其中包括所有图片结构变量的声明。

  /*---------------------alarm_common_ezip begin--------------------*/
  LV_IMG_DECLARE(img_alarm_add_icon);
  LV_IMG_DECLARE(img_alarm_check);
  LV_IMG_DECLARE(img_alarm_delete_icon);
  LV_IMG_DECLARE(img_alarm_fail_icon);
  LV_IMG_DECLARE(img_alarm_selected);
  LV_IMG_DECLARE(img_alarm_success_icon);
  LV_IMG_DECLARE(img_gif_alarm);

  /*---------------------alarm_common_ezip  end--------------------*/

可选参数

2.1中的可选参数对-dir依然有效，另外还有以下一些扩展。

是否需要dither（默认是-dither 1）

参数类型	功能描述
`-dither 0`	888转换为565的时候不做dither
`-dither 1`	888转换为565的时候做dither
`-dither 3`	默认只有放在`ezip_dither`目录下的才做dither，其他图片不做dither

生成文件是否分目录存放（仅配合-dir使用）

参数类型	功能描述
`-separate_dir`	仅配合`-dir`使用。按输入资源路径拆分输出目录，生成文件存放在对应的资源类型/应用子目录下，用于避免不同目录下同名资源互相覆盖。
`-separate_dir header`	仅配合`-dir`使用。在分目录输出的基础上，生成的资源名/头文件声明也按应用目录做区分，用于减少头文件声明中的同名冲突。

-cfile时生成c文件的结构变量是否添加增加LV_ATTRIBUTE_USED_XXX

参数类型

功能描述

-attr_used

添加该宏以后，可以映射该宏为__attribute__((used))，用于Solution的builtin_res

参数类型	功能描述
`-attr_used`	添加该宏以后，可以映射该宏为`__attribute__((used))`，用于Solution的`builtin_res`

2.3 -gzip xxx¶

作用
- 使用gzip压缩xxx文件
可选参数
- 是否包括header（gzip标准的头，默认是包括的）
  
  参数类型
  
  功能描述
  
  -noheader
  
  disable gzip的头。生成的不带gzip头的压缩文件（.gz）
- 头上是否包括length（默认不包括）
  
  参数类型
  
  功能描述
  
  -length
  
  压缩文件起始是否是4个字节length（整个文件长度）
- 生成文件的输出目录（默认输出目录是output）
  
  参数类型
  
  功能描述
  
  -outdir xxx
  
  生成文件的输出到xxx目录

参数类型	功能描述
`-noheader`	disable gzip的头。生成的不带gzip头的压缩文件（.gz）

参数类型	功能描述
`-length`	压缩文件起始是否是4个字节length（整个文件长度）

参数类型	功能描述
`-outdir xxx`	生成文件的输出到xxx目录

2.4 -ungzip xxx¶

作用
- 解压-gzip压缩的文件
可选参数
- 与2.3节的参数一样。

2.5 -lz4 xxx¶

作用
- 使用lz4压缩xxx文件
可选参数
- 头上是否包括length（默认不包括）
  
  参数类型
  
  功能描述
  
  -length
  
  压缩文件起始是否是4个字节length（整个文件长度）
- 生成文件的输出目录（默认输出目录是output）
  
  参数类型
  
  功能描述
  
  -outdir xxx
  
  生成文件的输出到xxx目录

参数类型	功能描述
`-length`	压缩文件起始是否是4个字节length（整个文件长度）

参数类型	功能描述
`-outdir xxx`	生成文件的输出到xxx目录

2.6 -unlz4 xxx¶

作用解压-lz4压缩的文件
可选参数
- 与2.5节的参数一样。

2.7 -img2jpg xxx¶

作用转换png或bmp为jpg。默认生成的图片质量为85%，输出.jpg文件。该命令只支持png/bmp输入；原生jpg请使用-jpg或-convert xxx.jpg。

输出jpg必须满足Baseline YUV420采样，且文件中只有一个FF D8 SOI标记。如果生成结果不满足该约束，则转换失败。

可选参数

参数类型	功能描述
`-quality xx`	输出jpg的图片质量，默认为85%。图片质量越高，则生成的图片尺寸越大
`-binfile 2`	转换为jpg的bin文件，开头包含`lv_img_header_t`头
`-cfile 2`	转换为jpg的c文件，使用`lv_img_dsc_t`数据结构

3. 使用例程¶

3.1 eZIP C 文件生成¶

ezip -convert png\min_hand.png -rgb888 -cfile 1 -outdir png_out

用途：转换当前目录下png\min_hand.png的文件，生成一个 rgb888格式的像素（非压缩） C 文件，生成文件放在当前目录下的png_out子目录下。

LV_ATTRIBUTE_MEM_ALIGN_EZIP const uint8_t min_hand_map[] SECTION(".ROM3_IMG_PIXEL.min_hand") = { 
    0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,...,
};

#ifndef LV_ATTRIBUTE_MEM_ALIGN_PIXEL_HEADER
#define LV_ATTRIBUTE_MEM_ALIGN_PIXEL_HEADER ALIGN(4)
#endif
LV_ATTRIBUTE_MEM_ALIGN_PIXEL_HEADER const eZIP_RGBARGB888A LV_ATTRIBUTE_USED_PIXEL lv_img_dsc_t min_hand SECTION(".ROM3_IMG_PIXEL_HEADER.min_hand") = { 
  .header.cf = LV_IMG_CF_TRUE_COLOR_ALPHA,
  .header.always_zero = 0,
  .header.w = 11,
  .header.h = 180,
  .data_size  = 7920,
  .data = min_hand_map
};

ezip -convert png\menu_bg.png -cfile 2 -section ROM1_IMG -attr_used

用途：转换当前目录下png\menu_bg.png的文件，生成一个格式为rgb565格式的 eZIP （压缩） C 文件，段名为ROM1_IMG，且包含LV_ATTRIBUTE_USED_，输出目录为output。

LV_ATTRIBUTE_MEM_ALIGN_EZIP const LV_ATTRIBUTE_USED_EZIP uint8_t menu_bg_map[] SECTION(".ROM1_IMG_EZIP.menu_bg") = { 
    0x00,0x00,0x00,0x81,0x43,0x04,0x20,0x00,0x00,0x30,0x00,0x30,0x00,0x05,0x00,0x00,0x00,0x00,0x00,0x00,...,
};

#ifndef LV_ATTRIBUTE_MEM_ALIGN_EZIP_HEADER
#define LV_ATTRIBUTE_MEM_ALIGN_EZIP_HEADER ALIGN(4)
#endif
LV_ATTRIBUTE_MEM_ALIGN_EZIP_HEADER const eZIP_RGBARGB_PAL LV_ATTRIBUTE_USED_EZIP lv_img_dsc_t menu_bg SECTION(".ROM1_IMG_EZIP_HEADER.menu_bg") = { 
  .header.cf = LV_IMG_CF_RAW_ALPHA,
  .header.always_zero = 0,
  .header.w = 48,
  .header.h = 48,
  .data_size  = 129,
  .data = menu_bg_map
};

ezip -dir png -rgb888 -cfile 1 -chip sf55x -outdir png_out

用途：解码目录 png 及其子目录下的所有图片，并批量生成像素格式的c文件。

ezip -dir png -rgb888 -cfile 2 -chip sf52x 410x494 -outdir png_out

用途：解码目录 png 及其子目录下分辨率为410x494的所有图片（common子以及410x494子目录），并批量生成 eZIP 格式的文件。

ezip -gif gif_stress.gif -cfile 1 -outdir png_out 或 ezip -convert gif_stress.gif -cfile 1 -outdir png_out

用途： gif转换为c格式（原样转换）。

ezip -convert gif_stress.gif -cfile 2 -chip sf52x -outdir png_out

用途： gif转换为eZIP格式的c文件。（注意： -chip sf55x不会使用eZIP转换，会输出gif格式的c文件）

ezip -convert beauty.jpg -cfile 1 -outdir png_out

用途：jpg转换为lv_img_dsc_t结构的c文件

ezip -convert beauty.mp4 -cfile 1 -outdir png_out

用途： mp4转换为lv_img_dsc_t结构的c文件

ezip -convert _tiny55_full.ttf -cfile 2 -outdir png_out

用途：将ttf文件转换为转换为lv_font_freetype_lib_dsc_t结构的c文件

const lv_font_freetype_lib_dsc_t SECTION(".SECTION_TTF_HEADER._tiny55_full") _tiny55_full_lib = { 
  .font_lib_size = 0x1098ac,
  .font_lib_data = (const char *) ttf_map,
  .font_lib_name = name,
}

ezip -convert beauty.c -cfile 2 -chip sf52x -outdir png_out

用途：转换lvgl的像素格式的c文件为eZIP的c文件格式。该命令可用于转换第三方UI工具生成的c格式图片为eZIP格式。

3.2 eZIP bin 文件生成¶

ezip -convert png\min_hand.png -rgb888 -binfile 1 -outdir png_out

用途：转换当前目录下png\min_hand.png的文件，生成一个 rgb888格式的像素（非压缩） bin 文件，生成文件放在当前目录下的png_out子目录下。

ezip -convert png\menu_bg.png -binfile 2 -binext .ezip

用途：转换当前目录下png\menu_bg.png的文件，生成一个rgb565格式的 eZIP （压缩）扩展名为.ezip 的bin文件，输出目录为output。

ezip -dir png -rgb888 -binfile 1 410x494 -chip sf52x -outdir png_out

用途：解码目录 png 及其子目录下的分辨率为410x494的所有图片（common子以及410x494子目录），并批量生成像素格式的bin文件。

ezip -dir png -binfile 2 -chip sf58x -outdir png_out

用途：解码目录 png 及其子目录下的所有图片，并批量生成 rgb565 格式的 eZIP 文件。如果图片是palette格式，则使用palette压缩。

ezip -convert gif_stress.gif -binfile 1 -outdir png_out

用途：gif转换为bin格式（原样转换）。

ezip -convert gif_stress.gif -binfile 2 -chip sf56x -outdir png_out

用途：gif转换为eZIP格式的bin文件

ezip -convert beauty.c -binfile 2 -chip sf56x -outdir png_out

用途：转换lvgl的像素格式的c文件为eZIP的bin文件格式。该命令可用于转换第三方UI工具生成的c格式图片为eZIP格式。

3.3 gzip压缩和解压¶

ezip -gzip sample.txt -outdir gzip_out

用途：使用gzip标准格式进行压缩，压缩文件为sample.txt.gz，放在gzip_out。

ezip -ungzip sample.txt.gz -outdir gzip_out

用途：使用gzip对sample.txt.gz进行解压，解压文件放在gzip_out。

ezip -gzip sample.txt -noheader -length -outdir gzip_out

用途：使用gzip对sample.txt进行压缩，压缩文件为sample.txt.gz，压缩时不加标准的头，前面加4个字节放长度，输出放在gzip_out。

ezip -ungzip sample.txt.gz -noheader -length -outdir gzip_out

用途：使用gzip对sample.txt.gz进行解压，解压文件放在gzip_out。（注意ungzip需要和gzip的参数-noheader -length配对）。

3.4 lz4压缩和解压¶

ezip -lz4 sample.txt -outdir lz4_out

用途：使用lz4格式进行压缩，压缩文件为sample.txt.lz4，放在lz4_out。

ezip -unlz4 sample.txt.lz4 -outdir lz4_out

用途：使用lz4对sample.txt.lz4进行解压，解压文件放在lz4_out。

ezip -lz4 sample.txt -length -outdir lz4_out

用途：使用lz4对sample.txt进行压缩，压缩文件为sample.txt.lz4，压缩后文件前面加4个字节放长度，输出放在lz4_out。

ezip -unlz4 sample.txt.lz4 -length -outdir lz4_out

用途：使用lz4对sample.txt.lz4进行解压，解压文件放在lz4_out。（注意unlz4需要和lz4的参数-length配对）。

3.5 eZIP文件反解为png文件¶

ezip -convert png\min_hand.bin -spt 1 -dpt 0 -outdir png_out

用途：解码eZIP的压缩文件png\min_hand.bin为png的图片。

ezip -convert psram.bin -spt 1 -dpt 0 -dec_off 0x1234 -outdir png_out

用途：解码psram.bin中偏移地址为0x1234处的eZIP bin，反解为png的图片。

ezip -dir png -spt 1 -dpt 0 -outdir png_out

用途：批量解码png目录下所有的eZIP压缩文件，反解为png图片。

3.6 图片转为jpg文件¶

-img2jpg直接作为主命令使用时，表示用户显式要求将png/bmp转换为jpg；即使源图带alpha，也会继续生成jpg，透明信息会丢失或被合成。与此不同，-dir中附带-img2jpg属于自动择优模式，只会对无alpha的png/bmp生成jpg候选，带alpha图片仍按eZIP路径输出。

ezip -img2jpg png\min_hand.png -outdir png_out

用途：显式转换当前目录下png\min_hand.png的文件，生成一个图片质量为85%的jpg格式文件，生成文件放在当前目录下的png_out子目录下。注意： jpg不带透明色，因此对于带alpha的图片会丢失透明信息或被合成。

ezip -img2jpg png\min_hand.png -binfile 2 -quality 90 -outdir png_out

用途：转换当前目录下png\min_hand.png的文件，生成一个图片质量为90%的jpg格式bin文件，生成文件放在当前目录下的png_out子目录下。注意，bin文件包括lv_img_header_t + jpg文件。

ezip -img2jpg bmp\min_hand.bmp -cfile 2 -quality 95 -outdir png_out

用途：转换当前目录下bmp\min_hand.bmp的文件，生成一个图片质量为95%的jpg格式c文件，生成文件放在当前目录下的png_out子目录下。