# Moonlight 客户端渲染 profile

## 目的

统一 `kiosk-shell` 产品入口与现场调试入口的 Moonlight 呈现参数，避免测试时只改了
`vdi-moonlight` 脚本而正式页面仍使用另一套 VSync、Frame Pacing 和解码器配置。

代码默认 profile 是 `smooth`；RK3528现场在硬解与EGL验证通过后，通过render.conf
选择了 `low-latency` 和2K30。软件基线和其他未验证设备仍使用smooth。
不把关闭同步当成通用修复，现场对照与风险见 `rendering-execution-20261102.md`。

## 产品入口环境变量

这些变量由 `kiosk-shell` 和 `vdi-moonlight` 调试启动器读取，重启串流进程后生效：

```text
VDI_STREAM_PROFILE=smooth       # 默认，VSync + Frame Pacing
VDI_STREAM_PROFILE=low-latency  # 关闭 VSync + Frame Pacing，减少呈现等待
VDI_STREAM_PROFILE=diagnostic   # smooth + Moonlight 性能叠图
VDI_STREAM_STATS=1             # 独立开启叠图，可同时比较smooth和low-latency
VDI_MOONLIGHT_DECODER=software  # 系统客户端默认；RKMPP现场配置使用 hardware
VDI_MOONLIGHT_CODEC=H.264       # 当前默认，先不切换 HEVC/AV1
VDI_MOONLIGHT_PROGRAM=...      # 可指定独立构建的Moonlight启动器，不覆盖系统二进制
VDI_SDL_FORCE_EGL=1             # 仅现场验证 SDL X11 EGL 时设置
VDI_SDL_VIDEODRIVER=wayland     # 仅实验；正式入口的X11窗口激活逻辑尚需适配
```

每次会话启动时，最终 profile、解码器、编解码器、同步开关、SDL renderer 和完整参数
会写入 `~/vdi-terminal/logs/moonlight-YYYYMMDD.log` 的 `[VDI launch]` 段落。

## A/B 顺序

1. 先恢复并确认 Sunshine 使用 `h264_nvenc`，否则客户端 A/B 不能说明服务端问题已经解决。
2. 1080p60：比较 `smooth` 与 `low-latency`，两组都设置 `VDI_STREAM_STATS=1` 收集 queue/render/jitter。
3. RK3528 硬解与 EGL/GLES 现场路径已验证；后续仍需单独完成 2K60 验收，不能由 2K30 结果推断。
4. 任何 profile 都必须保留 `--absolute-mouse`；当前已解决的双光标行为不应回退。

## GPU 重启故障边界

`gpu-restart-diagnosis-20261102.md` 已确认当前没有经过验证的重启后软件恢复办法。profile
只改变客户端呈现，不会修复 Windows Code 43、NVML 失败或 Sunshine 回退 `libx264`。
GPU 修复仍需设备厂商提供匹配的 GM204M/13D9 生产版 vBIOS，并在维护窗口内按验收标准
重复验证 `nvidia-smi`、DXGI、`h264_nvenc` 和 Windows/VM 重启后的持久性。

## RK3528现场配置与回退

`~/.config/vdi-terminal/render.conf` 当前内容：

```ini
profile=low-latency
stats=0
program=/home/armbian/vdi-terminal/bin/vdi-moonlight-rkmpp
decoder=hardware
codec=H.264
```

Windows桌面卡当前请求2560x1440@30、30Mbps，实际持续动画约23FPS；
虚拟屏仍为30Hz。私有构建位于 `~/vdi-build/rkmpp-experiment`，不要删除该目录。
目前是用户目录内的POC部署，尚未打包为完整OTA镜像。

如现场发现关闭同步导致明显撕裂，可先将profile改为smooth，并将桌面卡FPS改回20。
如需彻底退回系统客户端，退出串流后将render.conf改名保存，并恢复
`desktops.before-rkmpp-20261102.json` 为desktops.json，然后重新启动kiosk受管栈。
系统 `/usr/bin/moonlight-qt` 未被覆盖，不需要卸载MPP或替换系统FFmpeg。

设备访问规则是 `/etc/udev/rules.d/70-vdi-rockchip-video.rules`，限定video组0660；
部署工具会安装并重载规则。udev匹配已验证，本轮未重启盒子做重启后串流复验。