UI 开发

VML 程序不是只能打印文字 —— 它有一套完整的手机界面接口：开窗、绘图、收触摸与按键、放声音、震动、存档。这一页把全部接口列出来，每个都带一句用法和一个例子。

最小程序

#include <vml_ui.h>

int main(void) {
    int w = ui_scr_get_w(), h = ui_scr_get_h();     /* ① 先问可用绘图区 */
    ui_win_open("演示", w, h);              /* ② 再按它开窗 */
    ui_2d_clear(0xFF101020);
    ui_2d_text(20, 40, "Hello", 0xFFFFFFFF, 20, VML_ANCHOR_CENTER);
    ui_2d_present();                           /* ③ 这一帧画完了 */

    int m[4];
    while (ui_win_is_closed() == 0) {          /* ④ 主循环：收消息 → 处理 → 重画 */
        if (ui_msg_wait(m, 0) == VML_MSG_TOUCHDOWN) { /* 处理 m[1], m[2] */ }
    }
    return 0;
}

四条骨架：先问尺寸 → 开窗 → 主循环（收消息 / 处理 / ui_2d_present）→ 用户关窗退出。下面按类别列出全部接口；不同语言调用方式一样，只是语法不同（见「27 种语言」）。

签名的权威来源是 Lib/c/vml_ui.h，实现在 Lib/shared/src/vmlui.c —— 27 个前端共用同一份实现。本页的签名就是从那个头文件取的，改了接口重跑生成器即可。

接口分几层

按用途分四层。写程序时按这张图找接口，比翻列表快：

┌─ 窗口 / 设备 ────────────────────────────────────────────────┐
│  开窗 ui_win_open(_ex / _pc)   问尺寸 ui_scr_get_w/h             │
│  设备方向 ui_scr_get_orientation       方向锁 ui_scr_lock_orientation         │
│  全屏 ui_scr_set_immersive             别熄屏 ui_scr_set_keep_on             │
│  传感器 ui_sensor_read(_available/_rate/_calibrate)               │
│  电量 ui_battery_read               省电 ui_power_is_saving           │
└───────────────────────────┬──────────────────────────────────┘
                            │ 开好窗之后
┌─ 输入 ────────────────────▼──────────────────────────────────┐
│  事件式（主循环）ui_msg_wait / ui_msg_read + ui_msg_get_a/b              │
│  轮询式（手感）  ui_touch_fetch / ui_key_is_down                │
└───────────────────────────┬──────────────────────────────────┘
                            │ 拿到输入 → 决定画什么
┌─ 绘图 ────────────────────▼──────────────────────────────────┐
│  图元   ui_2d_rect / ui_2d_circle / ui_2d_path / ui_2d_text …            │
│  绘图状态 ui_clip_* / ui_mask_* / ui_2d_set_alpha                   │
│  资源   ui_2d_create_block（精灵）/ ui_2d_gradient / ui_brush_*     │
│  像素   ui_2d_get_pixel / ui_2d_flood_fill / ui_scr_screenshot          │
└───────────────────────────┬──────────────────────────────────┘
                            │ 配合着用
┌─ 系统 ────────────────────▼──────────────────────────────────┐
│  对话框 ui_dlg_*    音效震动 ui_audio_beep / ui_vibrate_simple            │
│  存档 ui_store_*    参数 ui_arg_get_count / ui_arg_get                    │
│  剪贴板 ui_clipboard_*   分享 ui_share_text / ui_url_open    │
└─────────────────────────────────────────────────────────────┘

一句话记法：窗口决定你能画多大，输入告诉你用户干了什么， 绘图把东西画上去，系统是游戏之外的那些事（弹框、出声、存档）。

精灵为什么要用「矢量图块」

会动的东西（玩家、飞鸟、香蕉…）尽量做成图块（ui_2d_create_block → ui_2d_draw_block）：

• 形状只写一遍，贴的时候能旋转、缩放、镜像（缩放取负值就是镜像）；
• 每一帧从"十几次绘图调用"压成"一次贴图块"。实测 300 个精灵 × 60 帧：直接画 3531ms → 贴图块 2945ms（快 17%），精灵越多差距越大。

这些接口长在哪一层（出了问题去哪找）

   你的程序（C / BASIC / Python / … 27 种语言）
        │  #include <vml_ui.h>
        ▼
   Lib/c/vml_ui.h          ← 签名的权威来源
   Lib/shared/src/vmlui.c       ← C 包装：一行 asm("SYSCALL #5xx")
        │  syscall 500–599
        ▼
   VmlHostRuntime（UI/Shared）  ← **逻辑全在这一份**
        │   手机与桌面**编同一份**：坐标钳位、消息队列、绘图状态机…
        │  IVmlHost（只有平台真的不一样的那十几件事）
        ▼
   手机 MauiVmlHost          │  桌面 CliVmlHost（scripts/vmlcli）
   弹原生框 / 存档 / 音频     │  脚本化输入 / 写 PNG

知道这个有什么用：

• 两端行为一致（同一份实现）⇒ 桌面上验证过的，手机上就是那个行为；
• 万一出现「手机上对、桌面上错」，那一定在 **IVmlHost** 那一层（最下面那格），不用去翻绘图的代码；
• 桌面的 scripts/vmlcli 是验收脚手架 —— 改完程序先在那儿跑（秒级），别一上来就打 APK（手机上编译要一分多钟）。

窗口

开窗、问尺寸、关窗、屏幕方向 —— [help:vml/ui/window](help:vml/ui/window)

/* 例：ui_scr_get_orientation */
if (ui_scr_get_orientation() == VML_ORIENT_LANDSCAPE) { /* 横排 */ }

收消息

触摸 / 按键 / 定时器消息怎么收 —— [help:vml/ui/messages](help:vml/ui/messages)

/* 例：ui_msg_get_a */
int x = ui_msg_get_a();

多点触控与设备

多指查询、按住判断、方向锁、全屏 —— [help:vml/ui/device](help:vml/ui/device)

/* 例：ui_audio_is_playing */
ui_audio_play("bgm.mp3", 0);
while (ui_audio_is_playing()) { ui_msg_wait(msg, 200); }

错误处理

上一次调用为什么失败（取消 / 没权限 / 这一端没有这个能力） —— [help:vml/ui/device](help:vml/ui/device)

char img[256];
if (ui_camera_capture(img, sizeof(img)) > 0) {
    ui_2d_image(0, 0, img, 320, 240);
} else if (ui_error_get_code() != VML_E_CANCELLED) {
    char why[64];
    ui_error_get_message(why, sizeof(why));   /* 人话：例如「没有权限」 */
    ui_dlg_msg("取图失败", why, VML_DLG_WARN);
}

定时器与随机数

重复定时器、取时间、随机数 —— [help:vml/ui/timer](help:vml/ui/timer)

/* 例：ui_math_rand */
int n = ui_math_rand(6);      /* 0..5 */
int side = ui_math_rand(2);   /* 0 或 1 */

绘图

点线面、多边形、路径、渐变、贴图 —— [help:vml/ui/draw](help:vml/ui/draw)

/* 例：ui_brush_linear */
int b = ui_brush_linear(0xFFFF3020, 0xFF2050FF, 0, 0, 1000, 0);
ui_brush_set_fill(b);

绘图状态

裁剪、蒙版（含布尔运算）、透明度、资源计数 —— [help:vml/ui/gfx](help:vml/ui/gfx)

/* 例：ui_2d_set_alpha */
ui_2d_set_alpha(120);
ui_2d_rect(10, 10, 100, 60, 0xFF000000, 1, 0, 0);   /* 半透明黑 */
ui_2d_set_alpha(255);

像素读回

读像素、灌色、抓图贴图、截屏 —— [help:vml/ui/pixel](help:vml/ui/pixel)

/* 例：ui_2d_flood_fill */
ui_2d_flood_fill(50, 50, 0xFF00FF00, 0xFFFF0000);   /* 在红框里灌绿 */

矢量图块

录一次、带旋转缩放地反复贴（精灵用这个） —— [help:vml/ui/block](help:vml/ui/block)

/* 例：ui_2d_create_block */
bid = ui_2d_create_block(30, 20, 0);   /* 30×20 的块 */

文字

写字、字体、锚点 —— [help:vml/ui/text](help:vml/ui/text)

/* 例：ui_text_set_font */
ui_text_set_font(18, VML_FONT_BOLD, 0xFFFFFFFF, VML_ANCHOR_CENTER);
ui_2d_text_cur(180, 40, "按方向键退出");

方块贴图

把一张图切成小格反复贴 —— [help:vml/ui/piece](help:vml/ui/piece)

/* 例：ui_piece_get_cell */
ui_piece_get_cell(0, 0, 3);   /* 0 号棋子、不旋转、第 3 格 */

整数网格

棋盘 / 地图这种二维状态 —— [help:vml/ui/grid](help:vml/ui/grid)

/* 例：ui_grid_clear */
ui_grid_clear();

对话框

提示、单选、多选、输入 —— [help:vml/ui/dialog](help:vml/ui/dialog)

/* 例：ui_dlg_input */
char buf[64];
ui_dlg_input("改名", "新名字：", buf, 64);

音效与触感

合成音、音频文件、震动、屏幕常亮 —— [help:vml/ui/feel](help:vml/ui/feel)

/* 例：ui_audio_beep */
ui_audio_beep(880, 80);      /* 消一行 */
ui_audio_beep(1568, 160);    /* 消四行，音更高 */

剪贴板与分享

分享成绩、存取档码（把整局状态编成一小段文本，玩家自己存到备忘录里换设备接着玩） —— [help:vml/ui/device](help:vml/ui/device)

char code[64];
ui_clipboard_set("SAVE-1a2b3c");              /* 把存档码交给玩家 */
if (ui_clipboard_get(code, 64) > 0) { /* 读回来接着玩 */ }
ui_share_text("我在拧螺丝里拧了 8 圈！", "分享战绩");

⚠ 返回 0 是"这一端没有这个能力"（桌面就没有分享面板），不是失败 —— 游戏该照常继续。写剪贴板/弹面板在平台上都是异步的，宿主不等结果。

本地存档

存最高分这类小数据 —— [help:vml/ui/store](help:vml/ui/store)

/* 例：ui_store_get */
char buf[16];
if (ui_store_get("high", buf, 16) > 0) best = atoi(buf);

全能接口

两个字符串进、一个 JSON 出 —— [help:vml/ui/json](help:vml/ui/json)

/* 例：ui_call_json */
char buf[512];
ui_call_json("sysinfo", "", buf, 512);
puts(buf);   /* {"ok":true,"result":{…}} */

调用宿主

按数字 id 调宿主函数（带类型、零编解码） —— [help:vml/ui/call](help:vml/ui/call)

/* 例：callwithdouble4 */
double v[4];
v[0] = VML_CALL_ECHO_DOUBLE;
v[1] = 1.0; v[2] = 2.0;
double r = callwithdouble4(v);

命令行参数

程序自己的 -l 这类开关 —— [help:vml/ui/args](help:vml/ui/args)

/* 例：ui_arg_get */
char buf[64];
if (ui_arg_get(1, buf, sizeof(buf)) > 0) { /* 用了 -l 这类开关 */ }