typedef struct {
    void (*on_create)(ESGUI_MenuPage_T *page);          // 分配资源，初始化页面
    void (*on_destroy)(ESGUI_MenuPage_T *page);         // 释放资源
    void (*on_draw)(ESGUI_MenuPage_T *page);            // 绘制背景 + 所有项
    uint16_t (*special_item_draw)(...);                   // 特殊条目标记绘制
    uint16_t (*get_special_item_draw_w)(...);            // 特殊条目宽度计算
    ESGUI_MenuAction_T (*on_input)(...);                // 按键/编码器输入处理
    void (*on_focus_change)(...);                       // 焦点变化通知（启动动画）
    void (*on_page_chenge)(...);                        // 页面切换回调（Push/Pop 动画）
} esgui_page_vtable_t;

#include "ESGUI.h"
#include "ESGUI_UseCanvas.h"

#define SCREEN_W   128
#define SCREEN_H   64
#define STRIP_H    16                 // 条带高度（8 的倍数，越大 RAM 占用越高）

uint8_t canvas_buf[SCREEN_W * STRIP_H / 8];  // 条带显存
Canvas canvas;
CanvasStripIter canvas_iter;
ESGUI_T ui;

/* 回调：按 OK 进入下一页 */
ESGUI_MenuAction_T on_enter_sub(ESGUI_MenuPage_T *page, void *arg) {
    extern ESGUI_MenuPage_T sub_page;
    return (ESGUI_MenuAction_T){ACT_PUSH_PAGE, &sub_page};
}

/* 回调：按 BACK 返回 */
ESGUI_MenuAction_T on_pop(ESGUI_MenuPage_T *page, void *arg) {
    return (ESGUI_MenuAction_T){ACT_POP_PAGE, NULL};
}

/* 条目结构：{x, y, label, icon, on_enter, arg} */
ESGUI_MenuItem_T main_items[] = {
    {0, 0, "Setting",  NULL, on_enter_sub, NULL},
    {0, 0, "Info",     NULL, on_enter_sub, NULL},
    {0, 0, "Exit",     NULL, on_pop,       NULL},
};
ESGUI_MenuPage_T main_page;

void ui_init(void) {
    /* 绑定画布（分块刷新） */
    ESGUI_BindCanvas(&ui, &canvas, &canvas_iter,
                     canvas_buf, SCREEN_W, SCREEN_H, STRIP_H);

    /* 创建默认文本菜单页面（使用默认 vtable） */
    ESGUI_DefaltTextMenuCreate(&main_page, main_items, "Main Menu", 3);

    /* 初始化 UI，传入首页面 */
    ESGUI_Init(&ui, &main_page, ESGUI_CanvasRefresh_CB, ESGUI_AnimTick_CB);
}

/* 主循环（1ms ~ 10ms 周期） */
void ui_loop(uint32_t tick_ms, ESGUI_EventCode_t key) {
    ESGUI_FeedKey(&ui, key, tick_ms);   // 输入事件（多线程模式下入队，可改由任意任务调用）
    ESGUI_Tick(&ui, tick_ms);           // 动画 + 绘制（必须由唯一 UI 线程调用）
}

/* 送屏回调：将当前条带数据写入 OLED */
void ESGUI_UseCanvasFlush(int x0, int y0, int x1, int y1,
                         const uint8_t *buff, void *user) {
    // 例如：SSD1315_I2C_Write(x0, y0, x1, y1, buff);
}

#define ESGUI_ENABLE_MULTITHREAD  1    // 1=开启（默认）；0=关闭，Async 退化为直接同步调用

#define ESGUI_SYNC_MODE  0
// 0 = 自动适配（默认）：
//     GCC/Clang/ARMCC6 → 内建原子 __atomic_*（多核安全，生产/消费可分核运行）
//     其他编译器（MSVC/IAR/ARMCC5）→ 自动退化为 volatile（单核语义）
// 1 = 纯软件：仅用 volatile，零内建原子、零 asm、零 RTOS，任何 C 编译器可用
//     （限定：单核 + 单生产者 + 单消费者）

/* 任意任务 / 中断中 */
ESGUI_FeedKey(&ui, EVT_KEY_OK, tick_ms);                       // 按键
ESGUI_PushPageAsync(&ui, &sub_page);                           // 入栈
ESGUI_PopPageAsync(&ui);                                       // 出栈
ESGUI_ShowPopupAsync(&ui, &popup);                             // 弹窗
ESGUI_ClosePopupAsync(&ui);                                    // 关弹窗
ESGUI_HandleActionAsync(&ui, (ESGUI_MenuAction_T){ACT_REFRESH, NULL});
ESGUI_OverlayAddAsync(&ui, &overlay);                          // 覆盖层
ESGUI_AnimStartAsync(&ui, &anim_cfg);                          // 动画

static ESGUI_ProducerBox_T net_box;      /* 例：网络任务专属收件箱 */

/* init 阶段（任务启动前，单线程）执行一次 */
void app_init(void) {
    ESGUI_ProducerBoxInit(&net_box);
    ESGUI_ProducerBoxRegister(&ui, &net_box);   /* 上限 ESGUI_MAX_PRODUCER */
}

/* 网络任务内（任意时刻，无锁） */
void net_task(void *arg) {
    ...
    ESGUI_ProducerBoxPushAction(&net_box,
        (ESGUI_MenuAction_T){ACT_SHOW_POPUP, &pop_window});  /* 弹窗/切页等动作 */
    ESGUI_ProducerBoxPushKey(&net_box, EVT_KEY_OK, tick);    /* 按键事件 */
    /* 或构造任意命令：ESGUI_ProducerBoxPush(&net_box, &cmd); */
}

#include "ESGUI_3D.h"

/* 模型：局部坐标顶点 + 边 */
static const ESGUI_3DPoint_T cube_pts[] = {
    {-10,-10,-10}, { 10,-10,-10}, { 10,-10, 10}, {-10,-10, 10},
    {-10, 10,-10}, { 10, 10,-10}, { 10, 10, 10}, {-10, 10, 10},
};
static const ESGUI_3DEdge_T cube_edges[] = {
    {0,1},{1,2},{2,3},{3,0},{4,5},{5,6},{6,7},{7,4},
    {0,4},{1,5},{2,6},{3,7},
};
static const ESGUI_3D_T cube = { cube_pts, 8, cube_edges, 12 };

/* 变换：平移 + 旋转 + 缩放（全定点） */
ESGUI_3DTransform_T t;
ESGUI_3DTransformInit(&t);
t.ty = 15; //沿y轴平移(右手坐标系)
t.scale_q8 = 256;   //缩放倍率为1,即模型原始大小
ESGUI_3DTransformRotate(&t, ESGUI_3D_AXIS_Y, 30); //旋转

/* 绘制（恒等变换时零变换开销） */
ESGUI_3DWireframeDiagram(&canvas, &cube, &t, 80, 128, 64, EUI_MODE_SET);

typedef struct {
    void (*on_draw)(ESGUI_Overlay_T *ov);  /* 绘制回调（必填） */
    void *render_ctx;                       /* 渲染上下文（框架注入） */
    void *user_data;                        /* 用户私有数据 */
    uint8_t visible      : 1;               /* 1=可见 */
    uint8_t always_dirty : 1;               /* 1=每帧强制重绘（常驻动态内容） */
} ESGUI_Overlay_T;

static ESGUI_Overlay_T clock_ov = { .on_draw = clock_on_draw, .always_dirty = 1 };

/* 任意任务 / 中断（异步） */
ESGUI_OverlayAddAsync(&ui, &clock_ov);
ESGUI_OverlaySetVisibleAsync(&ui, &clock_ov, false);
ESGUI_OverlayRemoveAsync(&ui, &clock_ov);

/* 或 UI 线程内同步 */
ESGUI_OverlayAdd(&ui, &clock_ov);

static void hud_on_draw(ESGUI_Overlay_T *ov) {
    Your_draw_ctx *c = ov->render_ctx;     /* 框架自动注入 ui->draw_ctx* */
    Your_ui_draw_hline(c, 0, 127, 10);     /* 画一条 HUD 分隔线 */
}

/* 自定义绘制：比如把文本菜单改成横向标签页 */
void my_custom_draw(ESGUI_MenuPage_T *page) {
    // 完全自定义的绘制逻辑，可调用 BSP 层的 eui_draw_xxx
}

/* 自定义输入：比如把上下键改成左右键控制 */
ESGUI_MenuAction_T my_custom_input(ESGUI_MenuPage_T *page, ESGUI_EventCode_t e) {
    // ...
}

static const esgui_page_vtable_t my_vtable = {
    .on_create       = esgui_text_menu_defalt_on_create,  // 复用默认创建逻辑
    .on_destroy      = esgui_text_menu_defalt_on_destroy,
    .on_draw         = my_custom_draw,                      // 替换为自己的绘制
    .on_input        = my_custom_input,                     // 替换为自己的输入
    .on_focus_change = esgui_text_menu_defalt_on_focus_change,
    .on_page_chenge  = esgui_text_menu_default_on_page_change,
};

/* 创建页面时绑定自定义 vtable */
void MyTextMenuCreate(ESGUI_MenuPage_T *page, ...) {
    memset(page, 0, sizeof(*page));
    page->vtbl = &my_vtable;
    // ...
}

anim_t a = {0};
anim_set_var(&a, &my_var);              // 关联目标变量
anim_set_exec_cb(&a, my_callback);      // 每帧写入回调
anim_set_values(&a, 0, 100);            // 起始值 → 目标值
anim_set_time(&a, 300);                 // 300ms
anim_set_path(&a, ANIM_PATH_EASE_OUT);  // 缓动曲线
anim_start(&a);                         // 启动（若同变量已有动画，自动热更新终点）

/* 标记格式：文本 + '\x03' + '/' + 类型码 */
{"WiFi\x03/0",  NULL, on_toggle, &wifi_en},   // 方形复选框
{"Mode\x03/1",  NULL, on_toggle, &mode_sel},  // 圆形单选框
{"Vol \x03/2",  NULL, NULL,     &volume},     // 数值显示（arg 指向 int16）