eZIP工具¶

1. 简介¶

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

2. 主命令¶

完整命令	主参数	功能描述
`eZIP -convert xxx`	`[-binfile 1]`	转换一个图片为像素bin文件，开头包含4个字节的`lv_img_header_t`头
`eZIP -convert xxx`	`[-binfile 2]`	转换一个图片为eZIP压缩后的bin文件，开头包含4个字节的`lv_img_header_t`头
`eZIP -convert xxx`	`[-cfile 1]`	转换一个图片为像素c文件，使用`lv_img_dsc_t`数据结构
`eZIP -convert xxx`	`[-cfile 2]`	转换一个图片为eZIP压缩的bin文件，使用`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压缩的bin文件
`eZIP -lz4 xxx`		使用lz4压缩xxx文件
`eZIP -unlz4 xxx`		解压-lz4压缩的文件
`eZIP -gzip xxx`		使用gzip压缩xxx文件
`eZIP -ungzip xxx`		解压-gzip压缩的文件

3. 命令参数¶

2.1 -convert xxx¶

作用
- 转换一个文件

可选参数

转换类型（默认是binfile 2)

参数类型	功能描述
`-binfile 1`	转换为像素bin文件，开头包含4个字节的`lv_img_header_t`头
`-binfile 2`	转换为eZIP压缩后的bin文件，开头包含4个字节的`lv_img_header_t`头
`-cfile 1`	转换为像素c文件，使用`lv_img_dsc_t`数据结构
`-cfile 2`	转换为eZIP压缩的bin文件，使用`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时，目录下的资源有两种组织方式：
1. Solution下要求的资源放置方式，需要严格按照图片资源的位置。此种方式下，命令行必须带分辨率[wxh]。eZIP会根据图片所在的分辨率（common、wxh）以及子目录（ezip、ezip_dither、gif、mp4、jpg、mask、no_ezip）进行对应的解码
  - ezip_dither： -dither 3时，且输出rgb565时，存放需要非旋转但有渐进色的图片
  - ezip：存放非旋转的图片。 ezip在-binfile 2或-cfile 2的时候，会进行压缩处理，否则转换为像素的c文件或bin文件
  - no_ezip：存放需要旋转的图片。ezip不做压缩处理，直接转换为像素的c文件或bin文件
  - gif：存放gif图片。 ezip在-binfile 2或-cfile 2的时候，会进行压缩处理；否则，直接转换为c文件或bin文件
  - mp4：存放h264的视频。ezip不做压缩处理，直接转换为c文件或bin文件
  - mask：存放作为mask的图片。ezip会抽取该图片所有像素的alpha
  - jpg：存放Baseline类型的jpg图片。ezip不做压缩处理，直接转换为c文件或bin文件
2. 图片资源在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

-binfile时生成文件是否分目录存放

参数类型

功能描述

-separate_dir

生成文件存放在对应的子目录下（应用名）
-cfile时生成c文件的结构变量是否添加增加LV_ATTRIBUTE_USED_XXX

参数类型

功能描述

-attr_used

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

参数类型	功能描述
`-separate_dir`	生成文件存放在对应的子目录下（应用名）

参数类型	功能描述
`-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 -lz4 xxx¶

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

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文件

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 -cfile 2 -section ROM1_IMG -attr_used -binext .ezip

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

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

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

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文件

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 gzip压缩和解压¶

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图片。