杜比视界开发手记：从动态元数据到终端原生输出
让串流画面通过设备原生的杜比视界（Dolby Vision，简称 DV）链路显示，需要主机、传输协议、解码器和屏幕共同配合。这篇手记记录了瑶光流梦对 Profile 8.1 与 8.4 的适配，也回顾了一次从联想“无极”平板黑屏入手、最终定位到解码器重启问题的排查。
整理于 2026 年 9 月 14 日，依据项目实施文档及同年 8—9 月的开发记录。文中的实机结果对应当时的设备与构建版本。
为什么我们执着于忠实呈现游戏画面
我们这些开发者，自己也是玩家。我们希望，换一块屏幕玩游戏时，能把游戏的样子也一起带过去。夜色中的层次、迎面照来的阳光、霓虹映在湿地上的颜色，共同构成了游戏的氛围。串流让我们离开桌前，也应该尽可能保留这些细节。
这份追求贯穿采集、编码、传输到显示的整个过程：尽可能保留源画面的明暗关系、色彩与层次，再根据接收屏幕的能力妥善呈现。让高光保有力度，暗部留住细节，颜色保持应有的分寸，是我们理解的高保真画面呈现。
手机、平板和电视的屏幕各有所长：有的擅长呈现深邃的暗部，有的能展现明亮的高光与丰富的色彩，有的用大画面带来更强的沉浸感。作为玩家，我们希望，也乐于探索如何充分发挥这些屏幕的素质，让游戏内容在不同终端上得到恰当而充分的表达。
这正是串流吸引我们的地方：让游戏电脑的算力与手边不同的屏幕相遇，让玩家自由选择此刻想在哪里、用怎样的画面体验游戏。持续投入 HDR 与 Dolby Vision 的端到端适配，就是为了把这份可能变成日常可用的体验。
实际体验是最终的检验：明暗变化是否自然，画面能否稳定输出，延迟是否适合操作。我们希望把复杂的适配工作做好，让玩家能够安心沉浸在游戏里。
从画面信息到原生显示
我们从 Profile 8.1 入手：沿用与 HDR10 兼容的基础画面，在 HEVC 视频码流中携带 RPU 动态元数据，再由客户端交给设备的原生解码与显示链路处理。
在这条路径中，主机根据画面分析生成动态元数据，帮助终端将已有的画面信息映射到屏幕的显示范围。它不会补回源画面中不存在的细节，也不代表游戏经过 Dolby Vision 原生制作。我们需要确认的是：元数据是否准确、是否对应当前画面，以及终端是否实际使用了它。
主机端：把元数据和画面对应起来
主机复用已有的 HDR 亮度分析与编码流程，通过原生 C++ 写入器生成 RPU，再注入 HEVC 码流。这样可以避免在实时处理过程中引入额外进程和磁盘操作，减少不必要的依赖。
其中一个重点，是按编码帧的标识绑定元数据。即使数据本身可以解析，一旦与画面错位，也无法准确描述当前场景。
我们使用 dovi_tool 做离线交叉验证，检查 Profile、L1/L5/L6 元数据字段和 CRC 校验。这个过程也帮助我们发现了扩展块对齐、NAL 起始码零字节处理等问题。这些细节藏在码流内部，却直接影响后续解析的正确性与稳定性。
客户端：从声明支持到真正输出
Android 设备声明支持 Dolby Vision 解码，只是适配的起点。实时串流使用的分辨率、帧率、编码格式，以及画面送往的显示表面（Surface），都需要在实际组合下验证。
2026 年 8 月，我们先后补齐了 HDR 设置列表中的 Dolby Vision 选项，修正了自动编码选择与 DV 请求不匹配的问题，并让串流信息覆盖层显示对应格式。随后，客户端接入 video/dolby-vision 解码路径，将画面直接输出到 Surface。
8 月 26 日，我们在索尼电视上确认了端到端 Dolby Vision 输出。这个实机结果验证了链路的可行性，其他设备仍需分别适配。随后，主机移除了验证期的灰度开关，由客户端上报的能力和会话协商结果决定是否启用 DV。
从 Profile 8.1 到 8.4
两条路线的主要区别在于基础画面采用的传递特性，这也影响了编码、显示和回退策略。
| 路线 | 基础层 | 开发重点 |
|---|---|---|
| Profile 8.1 | PQ / HDR10 兼容基础层 | 复用现有 PQ 游戏串流路径，失败时回退 HDR10 |
| Profile 8.4 | HLG 基础层 | 对齐 HLG 编码、能力协商和设备输出；失败时保留普通 HLG |
接入 8.4 需要真正提供 HLG 基础层，单独修改 PQ 码流的格式标记无法完成转换。我们为此制定了独立的实施方案，在复用 RPU 写入与注入框架的同时，处理 HLG 会话及其与 RTX HDR 应用策略的兼容问题。
8.4 的实施文档记录了 9 月 1 日的首阶段离线验证；联想“无极”平板的排查则进一步留下了两条路线正常输出的实机结果。这段经历也提醒我们：码流通过工具检查之后，设备上的解码与显示过程仍有需要解决的问题。
联想“无极”平板：解码器启动后为何仍然黑屏
问题出现在运行 Android 16 的联想 TB324ZC（“无极”平板）上，这台设备使用 Qualcomm/QTI 平台。串流已经进入 c2.dolby.vision.decoder，屏幕却持续黑屏。日志反复出现 retrieving AHB-ID for GraphicBlock failed 和 queueBuffer failed: 14，把排查方向指向了画面送往 Surface 的输出环节。
同机对照，逐步排除假设
同一台平板上的哔哩哔哩可以正常播放杜比视界视频。对照日志后，我们发现两边使用相同的 DV 解码组件和 SurfaceView 输出方式，也出现了一些相同的初始化警告。既然这些警告在正常播放时也存在，就需要结合后续输出行为判断它们是否与黑屏有关。
两边一个明显的差异是基础层：正常播放的样本使用 8.4 / HLG，串流当时使用 8.1 / PQ。我们因此先怀疑设备的 8.1 输出路径，再通过一组实验检验这个假设。
| 排查步骤 | 观察结果 | 得到的判断 |
|---|---|---|
| 临时修改兼容性标记 | 实际码流仍是 8.1，黑屏没有消失 | 改标记无法代替真实的 HLG 基础层与对应元数据 |
| 主机与客户端接入真正的 8.4 | 已确认 HLG 输出，仍然黑屏 | 8.1 / PQ 本身不是这次黑屏的根因 |
| 降到 1080p、60 帧等配置 | 仍能复现相同输出错误 | 降低分辨率、帧率不能解决问题 |
| 对照低延迟参数、静态 HDR 信息及输出配置 | 多轮调整未消除根因 | 需要继续追踪解码器启动后的状态变化 |
根因：静态 HDR 元数据更新触发了解码器重启
继续追踪事件顺序，我们发现 Sunshine 会在原生 DV 解码器启动后发送通用的静态 HDR 元数据。客户端收到更新后，沿用原有 HDR 处理逻辑，执行了一次 stop → configure → start，也就是停止、重新配置并启动解码器。
在这台设备上，Qualcomm DV 组件重启后残留了旧输出池的缓冲区 ID 记录。新的输出缓冲区与 GraphicsTracker 中的旧记录失配，随后持续出现 AHB-ID 和 queueBuffer failed: 14 错误，最终导致黑屏。问题由此定位到了解码器重启后的输出状态。
最终的修复是：原生 Dolby Vision 映射已启用时，收到主机静态 HDR 元数据只更新缓存，不再因此重启解码器。 DV 的动态映射继续使用码流中的 RPU。
这个条件需要判断准确：除了使用 video/dolby-vision MIME，还要确认厂商 color-mode 的原生映射信号已启用。同时，最新的静态元数据必须保留，供后续可能发生的 HEVC 回退使用。定位根因后，我们撤回了排查时的无关配置改动，将修复集中在实际触发问题的逻辑上。
修复之后，8.1 与 8.4 都正常出画
在同一台 TB324ZC / Android 16 上，我们使用包含根因修复的分支，以 2560 × 1600 分辨率验证了两条路线：
| 路线 | 确认的输出信息 | 实机结果 |
|---|---|---|
| Dolby Vision 8.1 | ccid=1，PQ，原生映射已启用 | 正常出画 |
| Dolby Vision 8.4 | ccid=4，transfer=7（HLG） | 正常出画 |
验证期间，两条路线均保持 Dolby Vision 输出，没有再出现上述 AHB-ID、queueBuffer 错误，也没有触发解码器恢复流程。
出画之后，补齐低延迟适配
排查还发现了一个独立的性能问题：设备使用通用的解码器名称 c2.dolby.vision.decoder，没有命中原先通过 c2.qti* 前缀识别的低延迟策略。
我们补充了 Qualcomm/QTI 平台判断，让这类组件复用已有的低延迟参数，并保留配置失败时逐级退让的机制。同机高帧率采样中，平均解码时间约从 5.04 ms 降到 1.21 ms。这是该设备在当次配置下的观察结果。
相关修复于 2026 年 9 月 1 日合入 客户端 PR #561。从黑屏到正常出画，再到低延迟参数生效，这次排查让验证覆盖到了元数据到达顺序、解码器重配和输出缓冲区状态等更具体的环节。
继续打磨实际体验
接下来，我们会继续观察暗部层次、高光和明暗场景切换的表现，检查静态界面叠加游戏画面时的稳定性，并在更多设备上验证兼容性。客户端也需要准确判断何时可以启用原生路径，以及条件不满足时如何回退。
这些工作最终都落在同一份体验上：当玩家在另一块屏幕上继续游戏时，画面依然保有熟悉的色彩与氛围，操作也依然跟手。