fix(render): bound host-paced latency

[qiin2333]

改了啥呀

• host-paced 初始余量从“一个帧间隔 + 2 ms”降为按帧率计算的 1–2 ms API 提交余量，不再稳态固定多缓存一帧
• 未来目标最多允许“提交余量 + 半帧”；decoder burst 或无关积压超过预算时直接重锚到最新 PTS，让杂鱼旧帧别排队抬高延迟
• 相移债务仍优先偿还；偿还后若目标仍超预算，同一帧立即 catch-up，不再多塞一帧未来队列
• 日志增加 catchUp 与 maxLead，但不猜测 Surface 究竟顶掉了哪帧，Rd/丢帧只记录能够确认的提交结果
• 后处理路径不做“一帧盲减”：当前保持原始 PTS 目标，完整的 NativeImage → 最终 Surface 时间戳穿透留作独立改造
• 设置说明同步改为“积压时跳到最新帧，不固定增加一帧延迟”

为啥要改

#61 已经把同步/异步解码统一到了同一个 PTS presenter，但原来的初始锚点仍主动留出完整一帧，稳定时也会平白增加约一帧延迟；decoder burst 还会把未来队列完整保留下来，积压越多延迟越高。

这轮把直出路径改成“稳态守 PTS、积压丢旧帧”：正常情况下只付 1–2 ms 的提交余量，真实抖动超过半帧预算时优先追上最新帧。它不会承诺所有设备上绝对零额外延迟，最终仍受 Surface/VSync 相位影响，但不再人为固定增加一帧。

review 时确认了一个杂鱼陷阱：在半帧预算内减去完整一帧，会让后处理目标恒定钳成当前时间，反而绕过 PTS 节奏。这段补偿已删除；在最终 Surface 能继承原始 target 之前，不提前冒充“长期方案”。

验证

• npm run check：通过
• c++ -std=c++17 -Wall -Wextra -Werror -I nativelib/src/main/cpp nativelib/src/main/cpp/presentation_scheduler.cpp nativelib/src/test/cpp/presentation_scheduler_test.cpp -o /tmp/moonlight-presentation-scheduler-test && /tmp/moonlight-presentation-scheduler-test：通过
  • 覆盖 burst catch-up、半帧延迟预算、相移债务恢复后 catch-up、59.94 FPS 与 20,000 帧时钟偏差
• DEVECO_SDK_HOME=/Applications/DevEco-Studio.app/Contents/sdk bash ./hvigorw assembleHar --mode module -p module=nativelib@default -p product=default --no-daemon：BUILD SUCCESSFUL
• JAVA_HOME=/Applications/DevEco-Studio.app/Contents/jbr/Contents/Home DEVECO_SDK_HOME=/Applications/DevEco-Studio.app/Contents/sdk bash ./hvigorw assembleApp --mode project -p product=default --no-daemon：BUILD SUCCESSFUL
• git diff --check：通过

HDC 当前返回 [Empty]，还需真机比较 host-paced 开/关的输入到光子延迟，并观察 catchUp / maxLead 是否符合预期。

Summary by CodeRabbit

• 改进
  • 优化主机时间线呈现策略：积压时可追赶至最新帧，避免固定增加额外一帧延迟。
  • 限制未来帧的最大提前量，提升低延迟播放的稳定性。
  • 新增主机呈现统计信息，包括追赶次数和最大目标提前时间。
• 文案
  • 更新设置页面及默认配置中的相关说明，使呈现行为描述更加准确。

[coderabbitai]

📝 Walkthrough

Walkthrough

Changes

主机节奏 PTS 呈现

Layer / File(s)	Summary
调度预算与追赶行为 nativelib/src/main/cpp/presentation_scheduler.*, nativelib/src/test/cpp/presentation_scheduler_test.cpp	调度器以提交提前量建立延迟预算，在相位债务偿还后按最大未来提前量选择 PHASE_SHIFT 或 CATCH_UP，并更新相关测试。
呈现统计与配置说明 nativelib/src/main/cpp/native_render.*, entry/src/main/ets/model/StreamConfig.ets, entry/src/main/ets/pages/SettingsPageV2.ets	NativeRender 新增追赶次数和最大目标提前量统计及日志字段；默认配置与设置页文案同步描述有界低延迟呈现行为。

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related PRs

• AlkaidLab/moonlight-harmony#61：该 PR 引入的主机 PTS 呈现与调度器路径被本次调度事件和统计扩展直接修改。

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	标题准确概括了本次修改的核心：限制 host-paced 渲染延迟。

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/bound-host-paced-latency

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}