vdi-cloud/docs/independent-cursor-design-20261103.md

独立光标二次开发设计与接入条件

状态：已通过受控的 Windows 光标导出 + 盒子 X11 本地指针原型验证；尚未实现 Sunshine/Moonlight 的自动独立光标通道，不应标记为生产功能已部署。测试已结束，当前恢复单个 Windows 远程白色光标。实测结果见 独立光标可行性验证。

已核实的实际路径

• 盒子固定 Moonlight Qt 6.2.0，现有 absolute mouse 输入仍经 moonlight-common-c 的可靠输入通道发送。
• 当前 RKMPP/EGL 路径使用 PacerRender 独立线程；实际诊断会话没有主线程 render 调用，输入优先调度不会改变这个渲染路径。
• Sunshine input.cpp 的 Ctrl+Alt+Shift+N 直接翻转全局 display_cursor。video.cpp 将其地址传入 display capture。它没有按会话的目标状态、确认或租约，不能作为可靠的独立光标协议。
• Windows Desktop Duplication 可能返回独立光标形状，也可能返回已含光标的画面；不能假定所有显示设备都能从视频中无损移除光标。
• Windows 当前没有现成的 Sunshine C++ 构建环境。因此本轮可以构建盒子客户端、验证输入和刷新率，但不能把未构建的服务端补丁当成已完成联调。

参考：Sunshine input.cpp、video.cpp、Windows RAM capture、Microsoft Desktop Duplication 光标说明。master 仅用于核实设计，实际修改须先固定现场 Sunshine 版本对应提交。

实施方式

在 Sunshine 与 moonlight-common-c/Moonlight 间扩展现有加密控制通道；不另外开放未经认证的 UDP 光标端口。默认仍使用远程视频光标，仅在双方协商并确认支持后启用。新增消息必须有协议版本、会话标识、显示配置代数及严格的大小校验。

消息	必要内容与作用
能力协商	支持形状类型、最大尺寸、显隐/视频帧交接能力；旧客户端保持原行为
光标形状	形状版本、尺寸、热点、像素/掩码格式；形状变化时发送并缓存
光标状态	状态序号、形状版本、显隐、坐标、显示区域及缩放配置代数
交接请求/确认	明确目标模式，携带首个采用该模式的视频帧 ID；不能使用无确认的 toggle
位置校正	服务端主动移动与最近输入序号关联；用户持续移动时不能用旧位置反复拉回
心跳/结束	会话租约、显式结束；连接丢失时服务端自动恢复视频光标

光标移动由盒子的本地指针立即显示，形状和显隐仍取自服务端。窗口、按钮响应和内容更新继续走视频，所以独立光标不等于窗口拖动零延迟。

单光标交接

1. 服务端确认当前捕获后端可独立控制光标，客户端收到并成功创建当前形状；否则保持远程模式。
2. 服务端在明确的视频帧边界停止混合光标，并发出该帧 ID。客户端显示到这个边界后才开启本地光标，避免旧视频仍有光标时出现双指针。
3. 结束独立模式时反向交接，在开始包含远程光标的视频帧上隐藏本地光标。
4. 辅助状态超时、形状不支持、捕获设备更换、显示缩放改变、解码器重建、第二路会话接入时，执行确认后的回退。控制连接完全断开且无法继续交接时结束串流，返回选择页。
5. 不能通过替换 Windows 全局鼠标主题为透明图片实现；不能把普通箭头覆盖在视频光标上。

心跳和租约先按 250ms/1000ms 做实验参数，最终值由 Wi-Fi 抖动及故障恢复测试决定。现有全局 display_cursor 还须改为与会话/捕获生命周期一致的状态，防止多个客户端互相覆盖。

Windows 特殊情况

• 处理彩色 alpha、单色 AND/XOR 和 masked-color；不支持的形状明确回退。不能把 XOR 像素简单当透明像素。
• 热点随流画面缩放映射，窗口信箱区域不发送越界输入；切换分辨率后废弃旧代数的光标消息。
• 服务端隐藏指针、文字选择、拖动缩放、忙碌动画必须正确；锁屏/UAC 桌面切换不能继续显示过期光标。
• SDL 硬件指针操作留在主线程；网络线程仅提交有界状态，禁止直接调用 SDL_SetCursor/释放正在使用的 cursor。
• 本地移动与远程主动 warp 分开处理，避免拖动时抖动、回弹；点击仍使用已修复的按钮坐标/输入顺序。

必须通过的验收

场景	要求
移动/拖动/右键/快速双击	单光标、点击准确、无丢失的按键释放
箭头/文字/调整大小/忙碌/隐藏/自定义	形状、热点及显隐正确；不支持时可靠回退
100%/125%/150% 缩放、分辨率切换	无偏移；旧代数消息失效
辅助消息停止、控制断开、服务器重启	无持久双光标或无光标状态
窗口失焦、鼠标离开、重新捕获	不锁死本地系统指针；恢复后坐标正确
旧服务端/客户端、多会话	不误启用；保持原有远程模式
高速摄像对照	分别报告指针移动、点击响应、拖窗内容更新的 P50/P95

下一阶段开始条件

固定现场 Sunshine 版本及源码提交，在独立构建目录准备可复现 Windows 构建，备份原安装并在测试实例验证后，再修改双方协议和捕获交接。不得为部署光标实验重装当前 Windows、刷 GPU ROM 或中断其他虚拟机。