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) |
| 静态但想低延迟 | 否 | 同上,更省电 |
两条实践建议:
- 能不用
tick就不用。tick一注册就是持续重绘,功耗直接体现为发热和掉电。注意这里的因果关系:条件里是need_draw || app->tick,**只要tick存在,need_draw就不重要了**。所以"每秒只刷一次"这种需求在当前 API 下做不到——要么不注册tick(只在点击后出帧),要么接受持续重绘。 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 = 水平中心 */
baseline是基线,不是顶边。文字视觉中心大致在baseline - size*0.35,所以"竖直居中"通常写成y + h/2 + size*0.36;- 字体固定
WenQuanYi Micro Hei,中英通吃;缺字时由 fontconfig 回退; - 每次调用都会
cairo_select_font_face+set_font_size,成本很低,不用自己缓存。
bbapp_text_w() — 量宽度
double w = bbapp_text_w(cr, "文字", size, bold); /* 返回 x_advance */
用来做右对齐、居中、或是"文字放不下就截断"。注意它必须传 cr(需要设备相关的字形度量)。
bbapp_toast() — 底部提示
bbapp_toast("已保存 %d 条", n);
- 显示 2.5 秒,居中在底部(
y = h-46,高 30); - 宽度 = 文字宽 + 28,超长会被
vsnprintf截到 191 字节; - 只有最后一条有效(覆盖式,不排队);
- 会自己请求重绘,不用再调
bbapp_redraw()。
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);
}
assets/是只读的,路径用bbapp_assets_dir()拼,不要写死/blackbox/apps/...;- 图片建议预缩放到屏幕尺寸内(本机最大 712×400),别在设备上做缩放;
- 退出前
cairo_surface_destroy()(或干脆不管,进程退出就回收)。
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 输入:触摸设备怎么选、坐标怎么映射、点击怎么判定。