SDK 文档 / 01 · 概念与架构
01 · 概念与架构
阅读时间约 8 分钟。这一章不写代码,讲清楚这套 SDK 的形状——为什么是"独立进程",以及由此产生的每一个限制从哪来。
1.1 设备上的图形栈实际长什么样
DJI Action 5 Pro 跑的是 Android + 一个改了过的 weston 合成器。屏幕上所有东西(相机预览、设置界面、我们的 bbui)都是 wayland 客户端。
我们量到的三条关键事实:
| 事实 | 我们怎么确认的 | 后果 |
|---|---|---|
没有 wl_seat |
wl_registry 枚举里根本没有 seat 全局对象 |
任何 wayland 客户端都收不到触摸/键盘事件 |
xdg-shell 不完整 |
xdg_toplevel.resize 发出去后合成器报 invalid arguments,随即断开连接 |
不能用现代桌面那套 xdg 窗口 |
wl_shell 可用 |
bbui 一直这么用,全屏稳定 | 全屏单窗口是唯一可靠路径 |
所以在这台机器上,"拿一块能画的屏 + 拿到触摸"只有一条路:
- 用
wl_shell开一个fullscreensurface; - 触摸不走 wayland,自己打开
/dev/input/eventN读 evdev,并用EVIOCGRAB把它独占,让 DJI 的其它进程收不到。
这两件事 bbui 自己在做(见 sdk/bbapp_run.c,它就是从 src/ 里那套代码抽出来的)。
1.2 为什么不做成 .so 插件
最直觉的设计是"bbui 里 dlopen 一个应用 .so,调它的 draw()"。它在别的机器上会更好,在这台机器上是错的:
EVIOCGRAB是进程级独占。 同一个进程里两个模块不可能"各拿一半触摸",这倒不是问题;真正的问题是——- bbui 需要把屏幕和触摸"完整交出去"。 这个需求(用户原话:"bbui 把显示和触摸完整交给应用,bbui 退出,应用继承能力")在进程内做不到:只要 bbui 还活着,它自己的帧循环、它自己的触摸状态机、它注册的 DJI 服务压制动逻辑就还在跑,随时可能插进来画一笔。
- 一个应用崩了会带走启动器。 插件模型下应用的空指针就是 bbui 的空指针,屏幕黑在那里,没有物理返回键,用户只能长按电源。
于是最终模型定成 launcher 交替:
┌──────────────────────────────┐
│ bbui(launcher,全屏 wl_shell)│
└───────────────┬──────────────┘
点桌面图标 │ fork + systemd-run(独立 cgroup)
▼
┌──────────────────────────────┐
│ app-run.sh │ 等 bbui 真的退出(最多 5 s)
└───────────────┬──────────────┘
▼
┌──────────────────────────────┐
│ 你的应用(SDK 运行时) │ wl_shell 全屏 + EVIOCGRAB
│ draw/tap/tick │ 每 2 s 压住 DJI 的 gui 服务
└───────────────┬──────────────┘
点「返回」/ 崩溃/被 kill│
▼
exec /blackbox/opt/bin/bbui ← 无论如何都回到这里
关键点:同一时刻只有一个进程拥有屏幕和触摸。不是"两个窗口切换",是"交接"。
1.3 代价(已知,不是 bug)
| 代价 | 具体表现 | 能不能改善 |
|---|---|---|
| 同时只有一个前台应用 | 不能边听歌边看天气;没有画中画 | 不能(wl_shell 单全屏 + 触摸独占) |
| 切换有可见黑屏 | 点图标到应用出画面大约 0.5~1.5 s(bbui 释放 → systemd-run 起单元 → 应用连 wayland → 首帧) | 能压一点(见下),压不到 0 |
| 应用无沙箱 | 以 root 跑,可读写 /blackbox 全盘 |
设计如此,见 08 |
| 切走就退出 | 回桌面 = 进程结束,tick 停止 |
【未实现】后台常驻 |
| 没有多点触控 API | SDK 只跟踪单指,滑动只用于"取消点击" | 【未实现】手势 API |
黑屏这 0.5~1.5 s 花在哪:app-run.sh 每 100 ms 轮询一次 bbui 是否退出(最多 50 次),bbui 退出后应用才连 wayland(4 个 roundtrip)、探测触摸、创建 shm buffer、画第一帧。其中固定开销主要是 wayland 连接和首帧光栅化,不是 sleep 写死的。
1.4 一次点击的完整旅程
以"点秒表图标"为例,把上面那张图的每一步落到进程和文件上:
src/desktop.c命中卡片 →bb_apps_run(i)(src/apps.c)。fork()→ 子进程setsid()(脱离 bbui 会话,bbui 死了它还活着)→execl("/usr/bin/systemd-run", "--collect", "--unit=bbui-app-<pid>", "/bin/sh", "/blackbox/svc/app-run.sh", <dir>, <entry>)。- 为什么必须
systemd-run:bbui 自己是ui-start.sh用systemd-run起的临时单元,bbui 退出时整个 cgroup 被拆掉,同 cgroup 的子进程会被一起杀(实测应用活 1 秒)。
- 为什么必须
- 父进程
usleep(120ms)后raise(SIGTERM)→ bbui 走正常退出(释放EVIOCGRAB、销毁wl_shell_surface、_exit(0))。 app-run.sh轮询pgrep -x blackbox-ui直到它消失(最多 5 s,超时pkill)。- 脚本导出
BBAPP_DATA/BBAPP_ASSETS/BBAPP_LOG,chmod 755入口,后台启动应用。 - 应用
main()→bbapp_main():连 wayland → 枚举 output/触摸设备 → 挑主屏 →create_buffer()→wl_shell_set_fullscreen→EVIOCGRAB→init()→ 帧循环。 - 用户点左上「返回」→
bbapp_quit()→ 释放独占、销毁 surface、exec /blackbox/opt/bin/bbui。 - 应用自己崩了/被 kill → 脚本
wait拿到 rc,exec bbui。兜底在脚本里,不在应用里。
1.5 术语表
| 词 | 含义 |
|---|---|
| 画布 / canvas | 应用坐标空间,本机 712×400。你在 draw(cr, w, h) 里拿到的 w/h 就是它 |
| 缓冲区 / buffer | 一块 wl_shm 共享内存,ARGB8888,stride = w*4,由 SDK 创建并 attach 到 surface |
| 面板 / panel | 触摸设备的原始坐标范围,本机 0..400(X)× 0..712(Y) |
| mode | wl_output.mode 报的像素尺寸,本机 400×712(竖的,和物理横放相反) |
| 帧循环 / frame loop | bbapp_main 里的 for(;;):tick() → draw(按需)→ poll(16ms) |
| busy | 某个 buffer 还在合成器手里时为 1;三块都忙就跳过这一帧(防撕裂) |
| 宿主 / host | bbui 本身。它只做扫目录和拉起进程,不参与应用绘制 |
| app-run.sh | 设备上 /blackbox/svc/app-run.sh,负责等 bbui 退出、设环境、守 DJI 服务、兜底回桌面 |
1.6 SDK 的边界
SDK 提供的是"给我一块全屏画布 + 触摸事件",仅此而已。它不提供:
- 窗口/控件/布局系统(只有 cairo 和几个画圆角矩形的助手);
- 网络、JSON、线程、定时器(自己用 libc / 自己链);
- 多点触控、滑动、长按、手势;
- 权限申请、后台常驻、跨应用通信;
- 崩溃上报(只有
app.log)。
这不是省事,是刻意的:SDK 每多一层抽象,就多一个在这台怪机器上出问题的地方。需要这些能力时,加在应用里,别加在 SDK 里。
下一步 → 02 快速开始:把 Hello World 装到机器上。