vdi-cloud/terminal/moonlight

VDI Moonlight 交互优化补丁

本目录维护当前 RK3528 / Xorg POC 私有客户端的源码修改，不替换系统 Moonlight。

基线：Moonlight Qt v6.2.0 de2467e433821664cdd2224aad8c89a625be1ad9，其检出的 moonlight-common-c 子模块保持对应版本。MPP、FFmpeg 版本仍由 tools/build-rkmpp-client.sh 固定。

补丁

• 0001-vdi-input-and-latest-frame.patch 在 Moonlight Qt 根目录应用。鼠标移动只合并队首连续事件，遇到按钮、键盘、窗口、呈现事件或其他鼠标设备立即停止；每次最多额外合并 64 个事件。绝对模式在发送按键前使用该按键事件的坐标。低延迟队列可选地把已等待的解码帧替换成新帧。
• 0002-vdi-absolute-click-barrier.patch 在 moonlight-common-c/moonlight-common-c 中应用。鼠标按钮封住此前的位置批次，后续移动只能进入新批次；发送线程只锁定自己的批次，避免旧包出队时误清除新批次。所有包依旧走原可靠鼠标通道，保留 1ms 合并限流和原坐标边界修正。
• 0003-vdi-input-priority.patch 在 Qt 根目录应用。可选地让帧就绪后的连续输入先执行，最多 32 条或 2ms，不能跨窗口/焦点/其他事件。VDI_INPUT_PRIORITY=1 才启用，默认关闭。另提供 VDI_INPUT_TIMING=1 的汇总统计，区分 SDL 输入派发年龄与主线程呈现调用耗时，不代表端到端延迟。

2026-11-03 的现场 RKMPP/EGL 使用独立 PacerRender 线程，诊断会话主线程 render 调用数为 0；因此第三补丁的新调度没有已证明的现场收益，未启用。诊断候选二进制保存为 moonlight.input-priority-20261103；默认客户端已恢复到本轮前 SHA256 35de7b1a4ade583823b23b5f2e012307f6d0a3848c8eb97bd6d4de9660afa00f。详细计划/初测限制见 docs/mouse-optimization-plan-20261103.md，独立光标接入设计见 docs/independent-cursor-design-20261103.md。

VDI_LATEST_FRAME=1 只在没有 VSync pacing source 的呈现队列生效。最多保留一个待呈现解码帧，丢弃数计入原 pacerDroppedFrames。不丢压缩包，不改变 H.264 参考链，也不提前释放正在呈现或延迟释放的上一帧。未设置或设为 0 时保留上游帧队列策略；kiosk 私有 wrapper 默认设为 1。smooth 档仍使用原 pacing 行为。

这些补丁不增加本地光标，不隐藏 Windows 光标，不改变控制协议。远程光标仍随视频显示，其延迟仍受服务器捕获/编码、网络、解码和显示影响。

构建与测试

在盒子上运行构建器时，将本目录的 patches/ 一起复制过去，通过 VDI_MOONLIGHT_PATCH_DIR 指定目录。构建器先检查固定提交，再检查补丁：已完整应用则跳过；上下文不匹配则失败，不强行覆盖其他修改。

VDI_BUILD_STAGE=moonlight \
VDI_MOONLIGHT_PATCH_DIR="$HOME/vdi-build/rkmpp-experiment/patches" \
bash tools/build-rkmpp-client.sh

tests/ 的文件复制到盒子 $VDI_RKMPP_BUILD_ROOT/latency-tests/ 后运行：

bash tools/test-moonlight-latency.sh
VDI_TEST_SANITIZE=1 ASAN_OPTIONS=detect_leaks=1 bash tools/test-moonlight-latency.sh

测试直接包含实际修改后的 SDL helper、AVFrame 队列 helper 与 InputStream.c，并链接客户端实际使用的 native 队列/线程库。覆盖跨点击合并、键盘/呈现边界、工作量上限、触摸隔离、200 帧的积压替换、已呈现帧所有权及 1,000 轮“移动→按下→移动→释放→移动”的发送线程滞后场景。测试显式启用断言，避免上游 release 头文件的 NDEBUG 使检查失效。

新增 test_input_priority.cpp 验证优先调度不越过焦点/窗口/退出/解码器重置事件，保持输入 FIFO，隔离其他窗口与合成触摸，并验证数量与时间限制。普通与 ASAN 版本均通过。当前 RKMPP/EGL 没有主线程呈现事件，新调度开关不能用作该路径的性能提升宣传。

现场数据、局限与完整回退入口见 docs/input-rendering-optimization-20261103.md。