seqframe控件

1. 使用场景

序列帧（seqframe）控件基于LVGL图片对象扩展，用于实现图片序列的灵活播放控制，提供：

  • 单张/多张图像的单次播放、连续播放、循环播放；

  • 自定义帧间隔、延迟启动、指定帧索引播放等控制。

2. 接口介绍

2.1 基础功能

接口函数

功能说明

关键参数说明

lv_obj_t *lv_seqframe_create(lv_obj_t *parent);

创建seqframe自定义控件实例，基于LVGL图片对象扩展

parent：父对象（如屏幕、容器），NULL表示默认屏幕

void lv_seqframe_set_src(lv_obj_t *seqframe, const lv_img_dsc_t *src);

用于为控件绑定pkg_img_seq的打包序列帧

src： pkg_img_seq资源，需通过APP_GET_IMG接口获取（示例：APP_GET_IMG(img_wifi_loading)）

void lv_seqframe_prefix(lv_obj_t *seqframe, const char *prefix, uint16_t img_cnt, uint16_t img_idx);

为控件配置外置存储的资源路径及帧参数

prefix：资源完整路径（该路径下资源需为bin格式）；img_cnt：总帧数；img_idx：起始帧索引

void lv_seqframe_select(lv_obj_t *seqframe, uint16_t idx);

跳转到序列帧的指定索引帧并显示

idx：目标帧索引（从0开始计数）

int lv_seqframe_next(lv_obj_t *seqframe);

手动切换至下一帧并返回当前帧索引

返回值：1表示切换成功（未到最后一帧）；0表示切换失败（已到最后一帧）

2.2 播放控制

接口函数

功能说明

关键参数说明

void lv_seqframe_open(lv_obj_t *seqframe, uint32_t period, uint32_t delay);

配置播放帧间隔、延迟启动时间

period：帧间隔（单位：ms）；delay：延迟播放时间（单位：ms，0表示立即播放）

void lv_seqframe_resume(lv_obj_t *seqframe);

启动或恢复序列帧播放（开启内部计时器）

seqframe：已初始化的序列帧控件实例

void lv_seqframe_pause(lv_obj_t *seqframe);

暂停序列帧播放（暂停内部计时器）

seqframe：已初始化的序列帧控件实例

void lv_seqframe_playback_mode(lv_obj_t *seqframe, lv_seqfram_play_mode_t mode);

配置序列帧的播放模式

mode：播放模式枚举值，可选LV_SEQFRAME_PLAY_LOOP（循环播放）/LV_SEQFRAME_PLAY_SINGLE（单次播放）

3. 播放模式

lv_seqframe控件支持两种播放模式：

3.1 播放多张图片打包机制的序列帧图片 - pkg_img_seq

  • 该机制基于pkg_img_seq封装，与pkg_img_seq提供的单张图片展示机制（lv_img_set_src_seq）不同，该控件提供了序列帧动自动顺序播放功能。

  • 该机制内置既打包资源在固件中（生成.c)，也可以访问文件系统中（生成.bin)。

3.1.1 图片存放和转换规则

序列帧图片需要遵循pkg_img_seq里描述的规则存放，eZIP会根据存放子目录（包含__seq子串）转换为eZIP格式并打包为一个bin。

3.1.2 调用方式

  1. 调用lv_seqframe_create，创建seq_obj

  2. 调用lv_seqframe_set_src(seq_ob, APP_GET_IMG（xxx))设置打包序列帧资源

  3. 调用lv_seqframe_open设置播放参数（帧间隔和延迟）

  4. 调用lv_seqframe_resume启动播放

  5. 调用lv_seqframe_pause暂停播放

3.2 播放某个目录下的序列图片（逐张）- prefix_seqframe

该机制提供了播放某个目录下序列图片的机制，只能用于图片存放在文件系统下的场景。

3.2.1 图片存放和转换规则

  1. 序列帧图片通常从视频抽取或者采用图形工具逐张生成，并按播放顺序依次为xxx0.png、 xxx1.png、 ··· xxxn.png，转换工具为GraphicsTool。

  2. 转换之后的图片存放在某个目录下，需要按照播放顺序依次为为xxx0.bin、 xxx1.bin、 ··· xxxn.bin。

3.1.2 调用方式

  1. 调用lv_seqframe_create，创建seq_obj

  2. 调用lv_seqframe_prefix设置资源路径及参数

  3. 调用lv_seqframe_playback_mode设置播放模式

  4. 调用lv_seqframe_open设置播放参数（帧间隔和延迟）

  5. 调用lv_seqframe_select设置当前序列帧（可选）

  6. 调用lv_seqframe_resume启动播放

  7. 调用lv_seqframe_pause暂停播放

4. 示例

4.1 播放多张图片打包机制的序列帧图片 - pkg_img_seq

4.1.1 资源

例程资源路径如下：

../../_images/seq_frame_demo_src.png

4.1.2 示例代码

// 创建序列帧控件，挂载到当前活动屏幕
lv_obj_t *seqframe = lv_seqframe_create(lv_scr_act());
// 绑定内置的序列帧动画资源
lv_seqframe_set_src(seqframe, APP_GET_SEQ(img_seqframe_loading));
// 配置播放参数：帧间隔50ms，延迟50ms后启动播放
lv_seqframe_open(seqframe, 50, 50);
// 启动序列帧动画播放
lv_seqframe_resume(seqframe);
// 设置控件在屏幕居中显示
lv_obj_align(seqframe, LV_ALIGN_CENTER, 0, 0);

4.1.3 示例效果展示

fishy

4.2 播放某个目录下的序列图片（逐张）- prefix_seqframe

4.2.1 资源

例程资源路径如下： （资源存放至外置 SD 卡/sd/photo/目录下）

../../_images/seq_frame_demo_prefix.png

4.2.2 示例代码

// 创建序列帧控件，挂载到当前活动屏幕
lv_obj_t *seqframe_prefix = lv_seqframe_create(lv_scr_act());
// 配置外置资源路径及参数：SD卡路径、总帧数18帧、从第0帧开始播放
lv_seqframe_prefix(seqframe_prefix, "/sd/photo/beauty", 18, 0);
// 设置序列帧为无限循环播放模式
lv_seqframe_playback_mode(seqframe_prefix, LV_SEQFRAME_PLAY_LOOP);
// 配置播放参数：帧间隔500ms，延迟50ms后启动播放
lv_seqframe_open(seqframe_prefix, 500, 50);
// 手动定位到序列帧第0帧
lv_seqframe_select(seqframe_prefix, 0);
// 启动序列帧动画播放
lv_seqframe_resume(seqframe_prefix);
// 设置控件在屏幕底部居中显示
lv_obj_align(seqframe_prefix, LV_ALIGN_BOTTOM_MID, 0, 0);

⚠️ 开发注意事项

  1. 外置资源需存放至设备可正常访问的存储路径（如 SD 卡/sd/photo/目录）；

  2. 外置资源文件命名必须为图片名+纯数字连续序号，后缀为 bin 格式（如beauty0.bin, beauty1.bin, beauty2.bin...)，否则无法正常加载帧资源；

  3. 内置资源与外置资源为二选一配置方式，不可对同一个控件同时配置两种资源路径。

参考例程路径：solution\examples\_dynamic_app\c\app\video。（注意该例程中由于路径是通过File Explorer选择，因此，文件名必须为纯数字连续序号）

4.2.3 示例效果展示

fishy