SDK 文档 / 06 · 绘制

06 · 绘制

一句话概括这套渲染:一块 712×400 的 ARGB 内存,每帧你从零画满,SDK 把它 attach 给合成器。没有控件、没有属性动画、没有局部刷新——只有 cairo。

6.1 画布尺寸是怎么来的

设备的 wl_output 报的 mode 是 400×712(竖的),但面板物理上是横放的。如果照 mode 原样开画布,画面会整体转 90°(实测 401×713,点哪儿都不对)。

SDK 的处理(pick_target()):

SW = g_mode_h;   /* 712 */
SH = g_mode_w;   /* 400 */
if (rot == 90 || rot == 270) swap(SW, SH);   /* 竖屏时再转回来 */

所以 draw(cr, w, h) 里的 w/h 是 712 / 400,bbapp_width()/height() 同值。按横屏、左上角原点、y 向下写代码,不需要任何换算。

环境变量 作用 什么时候用
BBAPP_W / BBAPP_H 强推画布尺寸 换屏实验、离屏调试
BBAPP_ROT 0(默认)/90/180/270 面板装反、竖屏应用
BBAPP_OUTPUT 指定 output 名字(如 DSI-1) 两块屏选错时
BBAPP_TOUCH 指定触摸设备路径 同上

竖屏应用(BBAPP_ROT=90):画布变成 400×712,坐标映射也会跟着换(见 07)。

6.2 像素格式与缓冲区

项 值
格式 CAIRO_FORMAT_ARGB32 = WL_SHM_FORMAT_ARGB8888(预乘 alpha,小端即 BGRA 字节序)
stride w * 4(712 → 2848 字节)
大小 712 × 400 × 4 = 1,139,200 字节(约 1.09 MB)
内存 mkstemp("/tmp/bbapp-shm-XXXXXX") + ftruncate + mmap,立即 unlink
缓冲数量 3 个(轮转,2026-11-03 从单缓冲改的)
同步方式 每个 buffer 自己的 busy 标志:全在合成器手里就跳过这一帧

为什么必须是 3 个:单缓冲 + busy 在别的合成器上没问题,但在 DJI 的 weston 上第一帧之后永远收不到 wl_buffer.release —— 于是整个应用停在第一帧,触摸有反应(日志里能看到 tap x,y)但画面一动不动。秒表"点不动"就是这么来的。现在三块轮转,谁空闲画谁;全忙就丢这一帧,因此不会撕裂,高负载时帧率自己往下掉。

调试时可以开 BBAPP_DUMP=<帧数>:每帧存到 <data>/frames/app-NN.png,"点了到底有没有变化"看两帧对比即可(设备上没法给应用截屏)。

/* 每帧都是新建的 cairo 上下文,你的状态不会残留 */
static void draw_frame(void) {
    cairo_surface_t *cs = cairo_image_surface_create_for_data(pix, CAIRO_FORMAT_ARGB32, SW, SH, SW*4);
    cairo_t *cr = cairo_create(cs);

    cairo_set_source_rgb(cr, BB_C_BG_R, BB_C_BG_G, BB_C_BG_B);
    cairo_paint(cr);            /* ← 背景由 SDK 刷,你不用自己清屏 */

    g_app->draw(cr, SW, SH);    /* ← 你的全部绘制 */

    draw_back_button(cr);       /* ← SDK 盖在最上层 */
    draw_toast(cr);             /* ← 有 toast 时盖在返回键之上 */

    cairo_destroy(cr); cairo_surface_destroy(cs);
    wl_surface_attach(...); wl_surface_damage(surf, 0, 0, SW, SH); wl_surface_commit(surf);
}

不要保存 cr。 每帧都是新的上下文,指针下一帧就失效了。

6.3 帧循环:什么时候画

for (;;) {
    double now = bbapp_now();
    if (app->tick) app->tick(now);
    if (need_draw || app->tick) draw_frame();   /* 内部挑空闲 buffer,全忙就跳过 */
    wl_display_flush(dpy);
    poll({wayland_fd, evdev_fd}, 16ms);
    ...
}
应用类型 注册了 tick? 出帧节奏
静态界面(设置页、计算器) 否 只在触摸/bbapp_redraw()/bbapp_toast() 后出一帧
动画 / 时钟 / 秒表 是 每轮循环都出帧,实际受合成器节流(实测约 60 fps)
静态但想低延迟 否 同上,更省电

两条实践建议:

  1. 能不用 tick 就不用。 tick 一注册就是持续重绘,功耗直接体现为发热和掉电。注意这里的因果关系:条件里是 need_draw || app->tick,**只要 tick 存在,need_draw 就不重要了**。所以"每秒只刷一次"这种需求在当前 API 下做不到——要么不注册 tick(只在点击后出帧),要么接受持续重绘。
  2. poll 的超时是 16 ms,所以 tick 最快也就 ~60 次/秒,不用担心它跑飞。

6.4 性能预算

cairo 在这台机器上是纯 CPU 光栅化(没有 GPU 加速路径),712×400 全屏重绘每帧要写满 1.09 MB 内存。可行的做法:

做法 影响
全屏纯色 + 几十个文字/圆角矩形 很轻,帧率不受影响
每帧 cairo_image_surface_create 加载大 PNG 重,纹理每帧重新解码,几 MB 的图直接掉到个位数 fps
每帧高斯模糊 / 大范围 CAIRO_OPERATOR_* 叠加 重,复杂度跟像素数成正比
每帧 bbapp_text_w() 几十次 可接受(走 fontconfig 缓存),但布局能预算就别每帧算
每帧读文件 / 扫目录 绝对不要,放在 tap 或 init 里

经验值:一帧里的绘制指令控制在几十条,别把整张照片当背景每帧重画。

6.5 绘制助手

SDK 提供了 5 个助手,语义如下(完整签名见 09)。

bbapp_rrect() — 圆角矩形路径

bbapp_rrect(cr, x, y, w, h, r);

只建路径,不填充、不描边,后面自己 cairo_fill() / cairo_stroke()。r 会被自动夹到 min(w,h)/2,传大了不会画出畸形。

bbapp_panel() — 半透明面板

bbapp_panel(cr, x, y, w, h, 0.14);

等价于"白色 alpha 填充 + 圆角 10 + 亮度 +0.06 的 1px 描边"。半透明必须是叠在背景上才有玻璃感,所以务必先画背景(SDK 已经铺了 BB_C_BG)。

bbapp_text() / bbapp_text_c()

bbapp_text  (cr, "文字", x, baseline, size, bold, r, g, b);   /* x = 左边缘 */
bbapp_text_c(cr, "文字", cx, baseline, size, bold, r, g, b);  /* cx = 水平中心 */

bbapp_text_w() — 量宽度

double w = bbapp_text_w(cr, "文字", size, bold);   /* 返回 x_advance */

用来做右对齐、居中、或是"文字放不下就截断"。注意它必须传 cr(需要设备相关的字形度量)。

bbapp_toast() — 底部提示

bbapp_toast("已保存 %d 条", n);

6.6 主题色

和 bbui 完全一致,直接用宏(都是 0..1 的 double):

宏 RGB 用途
BB_C_BG_* 0.055, 0.075, 0.145 深蓝背景(SDK 自动铺)
BB_C_TXT_* 0.88, 0.92, 0.98 主文字(近白)
BB_C_DIM_* 0.58, 0.65, 0.78 次要文字 / 说明
BB_C_ACC_* 0.36, 0.72, 1.00 强调色(蓝)

例:

bbapp_text(cr, "标题", 24, 40, 22, 1, BB_C_TXT_R, BB_C_TXT_G, BB_C_TXT_B);

6.7 必须避开的区域

区域 大小 谁画的
左上角 (6,4) 起 72×26 返回键 SDK(最高层,应用盖不住)
底部中间 y = h-46 起,高 30 toast SDK(仅 2.5 秒内)

实践:把左上角 78×34 当作禁区(返回键 + 1px 边距),标题从 x >= 84 开始画。底部留给 toast 的空间只在弹提示时用到,可以复用,但别在那块放必须点中的控件。

6.8 画图(PNG)的正确姿势

/* 一次性加载,别放在 draw 里 */
static cairo_surface_t *img;
static void load(void) {
    char p[600];
    snprintf(p, sizeof p, "%s/logo.png", bbapp_assets_dir());
    img = cairo_image_surface_create_from_png(p);
    if (cairo_surface_status(img) != CAIRO_STATUS_SUCCESS) {
        bbapp_log("加载 %s 失败", p);
        cairo_surface_destroy(img);
        img = NULL;
    }
}

/* 每帧只做 blit */
if (img) {
    cairo_set_source_surface(cr, img, x, y);
    cairo_paint(cr);
}

6.9 1px 线为什么糊

cairo 的坐标是浮点,y = 100 这条 1px 横线会横跨 99.5~100.5,被抗锯齿摊成两条半透明。画 1px 细线时加 0.5 偏移:

cairo_set_line_width(cr, 1);
cairo_move_to(cr, 0, 100.5);
cairo_line_to(cr, W, 100.5);
cairo_stroke(cr);

SDK 自己的 bbapp_panel() 就是这么处理的(x + 0.5, y + 0.5, w - 1, h - 1)。

6.10 一个完整的最小动画

static double t0;
static int    inited;

static void app_draw(cairo_t *cr, int w, int h)
{
    if (!inited) { t0 = bbapp_now(); inited = 1; }

    double t = bbapp_now() - t0;
    double x = (w - 60) * (0.5 + 0.5 * sin(t * 1.5));

    bbapp_rrect(cr, x, h / 2.0 - 30, 60, 60, 16);
    cairo_set_source_rgba(cr, BB_C_ACC_R, BB_C_ACC_G, BB_C_ACC_B, 0.9);
    cairo_fill(cr);
}

static void app_tick(double now) { (void)now; }   /* 注册即持续重画 */

static const bbapp_app g_app = { .id = "com.example.anim", .name = "动画",
                                 .draw = app_draw, .tick = app_tick };
BBAPP_MAIN(&g_app)

注意 inited 那三行:不要用静态初始化器去调 bbapp_now()(那时 wayland 还没连上,而且 C 的静态初始化要求常量)。第一帧里取时间戳是最省事的做法。


下一步 → 07 输入:触摸设备怎么选、坐标怎么映射、点击怎么判定。

bbui 第三方应用 SDK · API 1 · 本文档随仓库 docs/sdk 自动生成