动画系统概述¶

架构简介¶

EmbeddedGUI 的动画系统采用类 Android 的设计思路，核心概念为：将 Animation 对象绑定到目标 View，由 duration（时长）和 interpolator（插值器）共同驱动属性变化。

动画系统的核心组件关系如下：

Animation (基类)
  |-- duration        : 动画时长（毫秒）
  |-- interpolator    : 插值器，控制动画曲线
  |-- target_view     : 目标 View
  |-- handle          : 回调句柄（start/repeat/end）
  |-- repeat_mode     : 重复模式
  |-- repeat_count    : 重复次数

动画引擎在每帧调用 egui_animation_update()，根据已过时间计算 fraction（0.0~1.0），经插值器变换后传递给具体动画子类的 on_update() 方法，由子类将变换结果应用到目标 View 的属性上。

动画类型¶

EmbeddedGUI 提供 6 种内置动画类型：

类型	结构体	说明
Alpha	`egui_animation_alpha_t`	透明度动画，实现淡入淡出
Translate	`egui_animation_translate_t`	平移动画，改变 View 的 x/y 位置
ScaleSize	`egui_animation_scale_size_t`	缩放动画，按比例缩放 View 尺寸
Resize	`egui_animation_resize_t`	尺寸动画，按宽高比例独立变化
Color	`egui_animation_color_t`	颜色动画，R/G/B 通道逐通道插值
AnimationSet	`egui_animation_set_t`	组合动画，同时播放多个子动画

生命周期¶

一个动画从创建到结束的完整流程：

init -> params_set -> target_view_set -> [interpolator_set] -> [handle_set] -> start
                                                                                  |
                                                                           on_start 回调
                                                                                  |
                                                                          update (每帧)
                                                                                  |
                                                                     fraction 到达 1.0?
                                                                        /            \
                                                                      否              是
                                                                      |               |
                                                                  继续 update    检查 repeat
                                                                                /         \
                                                                          需要重复      不重复
                                                                              |            |
                                                                       on_repeat 回调   on_end 回调
                                                                              |            |
                                                                         重置 start_time   stop

初始化步骤¶

// 1. 初始化动画对象
egui_animation_translate_init(EGUI_ANIM_OF(&anim));

// 2. 设置动画参数
EGUI_ANIMATION_TRANSLATE_PARAMS_INIT(params, from_x, to_x, from_y, to_y);
egui_animation_translate_params_set(&anim, &params);

// 3. 设置时长
egui_animation_duration_set(EGUI_ANIM_OF(&anim), 500);

// 4. 绑定目标 View
egui_animation_target_view_set(EGUI_ANIM_OF(&anim), EGUI_VIEW_OF(&my_view));

// 5. （可选）设置插值器
egui_animation_interpolator_set(EGUI_ANIM_OF(&anim), (egui_interpolator_t *)&interp);

// 6. 启动动画
egui_animation_start(EGUI_ANIM_OF(&anim));

回调机制¶

通过 egui_animation_handle_t 结构体注册三个回调：

typedef struct egui_animation_handle egui_animation_handle_t;
struct egui_animation_handle
{
    void (*start)(egui_animation_t *self);   // 动画开始时触发
    void (*repeat)(egui_animation_t *self);  // 每次重复时触发
    void (*end)(egui_animation_t *self);     // 动画结束时触发
};

使用方式：

static void on_start(egui_animation_t *self) { /* ... */ }
static void on_end(egui_animation_t *self)   { /* ... */ }
static void on_repeat(egui_animation_t *self){ /* ... */ }

static const egui_animation_handle_t handle = {
    .start  = on_start,
    .end    = on_end,
    .repeat = on_repeat,
};

egui_animation_handle_set(EGUI_ANIM_OF(&anim), &handle);

回调为 const 指针，可声明为 static const 以节省 RAM。

重复模式¶

模式	宏定义	行为
重新开始	`EGUI_ANIMATION_REPEAT_MODE_RESTART`	每次从起始值重新播放
反向	`EGUI_ANIMATION_REPEAT_MODE_REVERSE`	奇数次正向，偶数次反向，形成往返效果

repeat_count 设置为 -1 表示无限重复，设置为 0 表示不重复（播放一次），正整数表示重复指定次数。

// 无限往返
egui_animation_repeat_count_set(EGUI_ANIM_OF(&anim), -1);
egui_animation_repeat_mode_set(EGUI_ANIM_OF(&anim), EGUI_ANIMATION_REPEAT_MODE_REVERSE);

填充模式¶

API	说明
`egui_animation_is_fill_before_set(anim, true)`	动画结束后恢复到起始值（fraction=0）
`egui_animation_is_fill_after_set(anim, true)`	动画结束后保持在终止值（fraction=1）

fill_before 常用于页面退出动画，确保旧页面在动画结束后回到初始位置。

常用 API 一览¶

基础 API（egui_animation.h）¶

API	说明
`egui_animation_init(anim)`	初始化基类（由子类 init 内部调用）
`egui_animation_duration_set(anim, ms)`	设置动画时长（毫秒）
`egui_animation_interpolator_set(anim, interp)`	设置插值器
`egui_animation_target_view_set(anim, view)`	绑定目标 View
`egui_animation_handle_set(anim, handle)`	设置回调句柄
`egui_animation_repeat_mode_set(anim, mode)`	设置重复模式
`egui_animation_repeat_count_set(anim, count)`	设置重复次数（-1=无限）
`egui_animation_is_fill_before_set(anim, flag)`	结束后恢复起始值
`egui_animation_is_fill_after_set(anim, flag)`	结束后保持终止值
`egui_animation_start(anim)`	启动动画
`egui_animation_stop(anim)`	停止动画

子类初始化 API¶

API	说明
`egui_animation_alpha_init(anim)`	初始化 Alpha 动画
`egui_animation_translate_init(anim)`	初始化 Translate 动画
`egui_animation_scale_size_init(anim)`	初始化 ScaleSize 动画
`egui_animation_resize_init(anim)`	初始化 Resize 动画
`egui_animation_color_init(anim)`	初始化 Color 动画
`egui_animation_set_init(anim)`	初始化 AnimationSet

参数设置 API¶

API	说明
`egui_animation_alpha_params_set(self, params)`	设置透明度起止值
`egui_animation_translate_params_set(self, params)`	设置平移起止坐标
`egui_animation_scale_size_params_set(self, params)`	设置缩放起止比例
`egui_animation_resize_params_set(self, params)`	设置宽高比例和锚点模式
`egui_animation_color_params_set(self, params)`	设置起止颜色
`egui_animation_set_add_animation(set, anim)`	向 AnimationSet 添加子动画

类型转换宏¶

动画系统大量使用 EGUI_ANIM_OF() 宏进行向上转换：

// 将具体动画类型转换为 egui_animation_t* 基类指针
egui_animation_start(EGUI_ANIM_OF(&my_translate_anim));

插值器同理，使用强制类型转换：

egui_animation_interpolator_set(EGUI_ANIM_OF(&anim), (egui_interpolator_t *)&my_interpolator);

内存使用建议¶

动画参数使用 PARAMS_INIT 宏声明为 static const，存放在 ROM 中
动画对象本身为 static 变量，占用 RAM
插值器对象同样为 static 变量
一个 Translate 动画约占 60 字节 RAM，Alpha 动画约 40 字节
AnimationSet 本身不额外分配内存，子动画通过链表管理