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 一直这么用,全屏稳定 全屏单窗口是唯一可靠路径

所以在这台机器上,"拿一块能画的屏 + 拿到触摸"只有一条路:

  1. 用 wl_shell 开一个 fullscreen surface;
  2. 触摸不走 wayland,自己打开 /dev/input/eventN 读 evdev,并用EVIOCGRAB 把它独占,让 DJI 的其它进程收不到。

这两件事 bbui 自己在做(见 sdk/bbapp_run.c,它就是从 src/ 里那套代码抽出来的)。

1.2 为什么不做成 .so 插件

最直觉的设计是"bbui 里 dlopen 一个应用 .so,调它的 draw()"。它在别的机器上会更好,在这台机器上是错的:

于是最终模型定成 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 一次点击的完整旅程

以"点秒表图标"为例,把上面那张图的每一步落到进程和文件上:

  1. src/desktop.c 命中卡片 → bb_apps_run(i)(src/apps.c)。
  2. 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 秒)。
  3. 父进程 usleep(120ms) 后 raise(SIGTERM) → bbui 走正常退出(释放 EVIOCGRAB、销毁 wl_shell_surface、_exit(0))。
  4. app-run.sh 轮询 pgrep -x blackbox-ui 直到它消失(最多 5 s,超时 pkill)。
  5. 脚本导出 BBAPP_DATA/BBAPP_ASSETS/BBAPP_LOG,chmod 755 入口,后台启动应用。
  6. 应用 main() → bbapp_main():连 wayland → 枚举 output/触摸设备 → 挑主屏 →create_buffer() → wl_shell_set_fullscreen → EVIOCGRAB → init() → 帧循环。
  7. 用户点左上「返回」→ bbapp_quit() → 释放独占、销毁 surface、exec /blackbox/opt/bin/bbui。
  8. 应用自己崩了/被 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 提供的是"给我一块全屏画布 + 触摸事件",仅此而已。它不提供:

这不是省事,是刻意的:SDK 每多一层抽象,就多一个在这台怪机器上出问题的地方。需要这些能力时,加在应用里,别加在 SDK 里。


下一步 → 02 快速开始:把 Hello World 装到机器上。

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