Veyra 补帧与“采用源时间戳”闪黑排查:面向采集源实时渲染的像素级诊断方法

原创2026-11-14 16:46:571,841 阅读
文章标签:音视频视频处理图像处理桌面应用直播

Veyra 补帧与“采用源时间戳”闪黑排查:面向采集源实时渲染的像素级诊断方法

本篇围绕 Veyra 仓库中的排查计划 FG_SOURCE_FLASH_PLAN_2026-10-08.md 展开:当采集源(如 4K/P010/PQ 游戏信号)开启补帧并选择“采用源时间戳”节奏时出现整幅黑闪,而关闭补帧或改用“采集 60→30”后黑闪消失。文章完整继承该计划文档的排查范围、六步判断流程与完成门槛,并结合 VideoPresenter、PresentationScheduler、CaptureHalfRate 等源码与 FG flash 像素探针 诊断实现,说明“源时间戳”与“60→30 降采样”在引擎中的真实含义、双阶段像素取样如何落地,以及为何“缓解故障”不能直接推出“PTS 错误”这类根因结论。

一、故障定义:什么设置会闪,什么设置不闪

计划文档给出的原始现象非常具体,这也是整篇排查的方法论起点——先固定故障的边界条件,再谈根因:

  • 用户提供了 veyra-qml(41).log 与一段手机录像;
  • 闪黑出现的条件:补帧开启 + 内容节奏选择“采用源时间戳”;
  • 不闪的条件:关闭补帧,或采集节奏改为 60→30;
  • 计划明确声明:在拥有可复现根因之前,“不把假说写成产品修复”。

“采用源时间戳”和“采集 60→30”并非普通开关,而是 Veyra 内容节奏(content cadence)体系中的两个选项。在 ProPage.qml 中,这个下拉列表有六个选项,与 EnhancementSettings.h 中的枚举一一对应:

enum class ContentRate { Transport, Auto, Fps30, Fps50, Fps60, Capture60To30 };
QML 选项 id 标签 枚举
0 采用源时间戳 ContentRate::Transport
1 自动剔除重复帧 ContentRate::Auto
2 / 3 / 4 识别 30 / 50 / 60fps 内容 Fps30 / Fps50 / Fps60
5 采集 60→30(PS5 30 帧) ContentRate::Capture60To30

理解这两种模式在引擎里的实现,是判断“哪个环节可能黑”的前提,下面两节分别拆解。

二、“采用源时间戳”的实现:PresentationScheduler 的 pacing 模型

“采用源时间戳”(Transport)的含义是:呈现时刻由源 PTS 推导出单调的主机时间轴。核心实现在 PresentationScheduler.h:

// Maps source timestamps to a monotonic host timeline. File playback keeps a
// continuous source anchor; live sources may explicitly re-anchor each input
// pair before enhancement because their device/source clock is not guaranteed
// to match the host clock. Processing completion must never re-anchor a pair.
// Units: 100 ns.
class PresentationScheduler {
public:
    void reset(uint64_t epoch,int64_t source,int64_t host,int64_t lookahead,bool paceSourcePts=true);
    // Unbuffered capture is ready-driven. A late first callback or clock drift
    // must not turn its source timestamps into a persistent presentation hold.
    int64_t deadline(int64_t pts)const{return paced_?host_+(pts-source_)+delay_:host_;}
    int64_t cadenceDeadline(int64_t pts,int64_t now)const{return paced_?deadline(pts):now;}
    bool expired(int64_t pts,int64_t now,int64_t tolerance)const{return now>deadline(pts)+tolerance;}
};

可以归纳出三个要点:

  1. 单位是 100ns(Windows 时间戳单位),deadline(pts) 把源 PTS 线性映射为“主机时间上这一帧最迟何时呈现”;delay_(lookahead)是呈现提前量;
  2. 锚点(anchor)与 epoch 绑定:anchored(epoch, paceSourcePts) 要求 epoch 与 pacing 模式都匹配。源码注释解释了原因——补帧开/关会重建 graph,epoch 随之重启,旧锚点会“过期”;
  3. 无 pacing 的输入以“就绪”驱动:注释明确写了“晚到的首次回调或时钟漂移不得把源时间戳变成持久的呈现挂起”,这正是“源时间戳”模式下最容易引入异常的状态——采集源的时钟不与主机时钟保证一致,任何漂移都会直接体现为呈现时序压力。

补帧侧对时序同样敏感。LiveFgAdmission.h 决定一个帧对是否还值得送去生成:

// A pair is indivisible: NGX MFG indices share history.
// Admit while at least its last generated timestamp can still be useful.
inline bool admitLiveFg(int64_t now, int64_t lastDeadline, double elapsedMs,
                        std::optional<double> completionP95Ms, double presentP95Ms) {
    constexpr int64_t tolerance = 100000; // Same 10 ms grace as presentation.
    if(now > lastDeadline && now-lastDeadline > tolerance)return false;
    ...
}

即:帧对一旦超过最后期限且超出 10ms 宽限,就不再准入生成。这意味着在源时间戳 pacing 下,若某对帧的 deadline 计算异常或呈现管线延迟增大,生成帧会“过期作废”——这是排查时重点区分的“生成帧失效/过期”一类事件。

呈现端的入口是 VideoPresenter.h 的 present():

bool present(gfx::D3D12DeviceContext&, gfx::CommandSlotRing&, pipeline::EnhanceGraph&,
             unsigned slot, bool generated, bool referencesValid = true, int comparison = 0,
             bool baseReference = false, float split = .5f,
             pipeline::FrameIdentity identity = {}, PreviewView view = {},
             int64_t sourcePts100ns = -1, bool retainUnchanged = false);

注意两个参数:sourcePts100ns 把源时间戳透传到呈现层(“采用源时间戳”在像素管线里的落点),slot 与 generated 对应交换链/资源槽位的奇偶复用。头文件还特别注释了 XeSS 这一类 provider 接管 Present 的情形(L39-L44):provider 在 Present 内部阻塞以 pacing 它自己生成的帧,曾尝试的辅助线程 Present 导致源速率从 51 掉到 24/s,最终保留同步调用。这决定了排查必须区分“应用自管 Present”与“provider 自管 Present”两条路径——后续诊断探针也明确声明覆盖不到 XeSS 内部生成帧。

三、“采集 60→30”的实现:保留 PTS 的网格降采样

“60→30”之所以在黑闪场景中“有效”,其机制在 CaptureHalfRate.h 里可以看得很清楚:

// Explicit 60/59.94 transport -> 30/29.97 sampling before any GPU work.
// Keeps original PTS. It does not claim to detect unique pictures or repair
// irregular game cadence. Quarter-slot tolerance absorbs timestamp jitter.
class CaptureHalfRate {
    bool accept(int64_t pts, int64_t transportInterval, bool boundary,
                const uint64_t* picture = nullptr) { ... }
};
  • 它只做一件事:在 GPU 工作之前把 60/59.94 的传输流按 2 倍间隔的网格抽成 30/29.97,并保留原始 PTS;pts + transportInterval/4 < next_ 的判定带“四分之一槽”容差以吸收时间戳抖动;
  • 后期补丁(2026-10-27 注释)还处理了一个 30fps 游戏在 60Hz 下每幅画面出现两次、第二份拷贝晚到 16.7ms 的问题:当连续 kSecondCopies(3)次保留到“第二份拷贝”(用画面号 PictureCompare 识别)时,下一份“第一份拷贝”也会被提前纳入,让网格重新对齐。

这里的关键推论来自配套报告 FG_SOURCE_FLASH_REPORT_2026-10-08.md 的结论:“60→30 保留真实 PTS、减半源工作量、扩大每对帧的处理窗口,它缓解了故障,但不能单独证明源 PTS 有错。” 这与计划文档中“区分真正的设备/Present 错误,而不是把缓解手段当证据”的纪律一脉相承。

四、排查范围与保全策略

计划文档的第二节给出了严格的操作边界,值得作为一次线上故障排查的范本:

  • 只读核对真实日志、录像、当前共享 graph/presenter、GPU fence 与历史重置;独立诊断程序只添加像素取样,不改变补帧算法、准入、源时间戳或显示策略;
  • 产品基底固定为 main 对应的提交 71723e0249a17764696796fd204a6eb69d6da276,从 main 文档 tip dbfceab 建立分支 codex/fg-source-flash-20261008,只存放诊断源文件/启动脚本/记录,没有产品修复合并或新的发布授权;
  • 原桌面工作区、其它工作树、发布/候选包、SDK/DLL/模型、驱动与用户配置全部保持不动;不制造压力或竞争 GPU 负载,测试串行且单进程不超过 300 秒;
  • 所有输出收敛到 E:/项目/Veyra/{reports,tests,logs,tmp,test-packages}/fg-source-flash-20261008,运行库用只读硬链接共享原件,配置、缓存和日志隔离;
  • pre-document-state.json 在创建本轮文档工作树之前固定了 35 个原工作树/495 个脏文件作为基线,并明确声明“此基线不冒充工具排查前的开工快照”——保全证据以实际构建和用例收据为准。

五、六步排查流程:从日志分段到最小修复

计划文档的“执行和判断”一节给出了完整的六步路径。下面逐步展开,并标注每一步在仓库中的实现或证据落点。

1. 日志分段:区分四类事件

按进程、设置 revision、补帧后端、内容节奏分段,目标是把现象拆成四类互斥事件:手动重建(用户改设置触发 graph 重建)、场景切换、生成帧失效/过期、真正的设备/Present 错误。配套报告的核对结果是:18 条 ERROR 为 17 次 QML 几何操作失败和 1 次配置保存失败,没有 NGX/FG/Present/device-lost 错误,且“错误和黑闪的关联没有被证实”——这说明第 1 步的价值在于排除,而不是定罪。

2. 录像逐帧核验:确认“整幅”而非“残影”

对手机录像逐帧检查,确认是整屏黑闪。报告中的量化证据:录像 720×1280/30fps/146 帧,第 104 帧(约 3.467s)和第 129 帧(4.300s)屏幕接近全黑,邻帧即恢复;黑帧 ROI 平均码值分别约 1.97/255 与 2.09/255,周围正常画面约 89–92/255。这排除了“局部运动残影”。同时明确两条纪律:不从 30fps 录像推断物理黑闪持续了 33ms;手机创建时间 06:24:11Z 与应用日志时段“有重叠”但两个时钟未校准,不能硬对齐。

3. 独立原生 EXE:九点取样矩阵

用一个复用产品静态库的独立原生 EXE,对确定非黑的 4K P010/PQ 输入跑对照矩阵:源 60/隔帧 30、重复/静止内容、不同光流后端、原版 NR 路径。方法学要点:Draw 之后只在 GPU 侧复制九个分布位置的像素,结束后一次性读取,不逐帧等待 CPU。

报告中的实测结果(本机 RTX 5070/616.56,非黑 4K 输入):

原生用例 原帧样本 生成帧样本 九点全黑
HDR4K、FG 关 480 0 0
HDR4K、DLSS2X、NVOF、源 60 794 673 0
HDR4K、DLSS2X、NVOF、隔帧 30 294 293 0
HDR4K、DLSS2X、AMD 光流、静止 60 647 441 0
同上 + 两层 Lecram NR1080 477 219 0
同上 + 两层 NVIDIA 原版 NR1080 628 242 0

六组全部 exit 0、GPU 错误 0。报告特别注明:早期两组误用枚举 0(Lecram),修正为 NvidiaOriginal=3 后补做最后一组;初次缺少 EXE 旁 shaders 导致初始化失败,不计入通过——这种“失败保留原收据”的记录方式就是保全纪律的体现。

4. 真实 QML 诊断 EXE:双阶段取样

若本机不复现,则交付“真实 QML 播放器 + 诊断取样”的 EXE,同时采两路像素:

  • 进入 presenter 的纹理(最终增强原帧/生成帧);
  • Draw 之后的交换链 buffer。

每条样本记录 source ID、epoch/revision、PTS、wall time、buffer index 与提交 fence,并用已知黑场正例验证检测器本身有效。报告中的正例验证结果:DLSS2X/源 60 + 已知黑场输入,480 原帧/479 生成帧中准确检测到 13 张黑原帧/12 张黑生成帧,呈现输入与 buffer 一致;另一组 PowerShell 5.1 入口下 449 原帧/1345 生成帧检测到 13/36 张黑帧,exit 0。

5. 现场复现与三路归因

现场按原设置复现 15–20 秒后关闭,拿到像素与事件 CSV 后按决策树定位:

输入已黑        → 查 graph / provider / 交接
输入正常、buffer 黑 → 查 blit / 描述符 / 资源复用
两者均正常、现场屏幕仍闪黑 → 查提交后窗口、遮罩、合成、驱动与显示路径
(最后一种也不能直接归咎电视或驱动)

这条决策树是整篇文档最有引用价值的部分:它把“黑闪”这一模糊现象拆成了输入侧 / 呈现侧 / 显示侧三个互斥排查面,每一面都有对应的代码与证据落点,而且最后特别声明不得把显示侧问题直接甩锅给电视或驱动。

6. 稳定复现后才做最小修复

“有稳定复现后再实施最小修复并做匹配 A/B;本机 5070 的软件短测不替代 5090/Magewell/LG HDR 实卡验收。”——验收环境与故障环境必须匹配(现场是 RTX 5090/32GB、驱动 617.42、Magewell Pro Capture HDMI4K+、3840×2160/P010/PQ/约 59.94fps、LG TV SSCR2 约 143.988Hz),本机 5070/约 320Hz 显示器的结果只能证明“取样器正确”,不能证明“现场已修复”。

六、诊断探针的源码实现:九点取样与有界 readback

计划里“九个分布位置、有界 readback”的描述,在 scripts/diagnostics/fg-flash/FlashPixelProbe.h 中有完整实现(该目录 README 声明其为纯诊断源码,不链接进产品构建):

namespace flashProbe {
inline constexpr unsigned capacity=20000, points=9, stride=512;
// record(): 与 Draw 同一 command list 内采样
//   1) buffer 转 COPY_SOURCE 屏障
//   2) 在 (x+1)/4, (y+1)/4 的 3x3 网格上 CopyTextureRegion 九个 1x1 BOX
//   3) 屏障转回,记录 entry{generated, source, slot, format, epoch,
//      revision, pts, unix100ns, stage}
// dump(): 仅在收尾后一次 Map,计算 minCode/maxCode/meanCode,
//   逐点 localMax<=5 记为黑点;全黑需 black==points
}

几个可直接对照计划文档的设计细节:

  • 只接受 R10G10B10A2_UNORM 与 R8G8B8A8_UNORM(现场 HDR 链路的呈现格式与 SDR 格式各一),其它格式直接标记失败,避免误读;
  • readback 缓冲大小为 capacity × points × stride = 20000 × 9 × 512 B ≈ 88 MiB,与报告“约 88MiB 有界 readback,不是持续增长的图像存储”一致;
  • CSV 列:ordinal, source, generated, slot, format, minCode, maxCode, meanCode, blackPoints, epoch, revision, pts100ns, unix100ns, stage——即报告所述“码值、帧 ID、PTS、wall time、epoch/revision、buffer index、fence 及 Present 结果”的载体(fence/Present 结果由 FieldPixelProbe.h 的配对事件补充);
  • 黑帧判据是九点中每点 RGB 最大值 ≤ 5 且九点全黑才计为整幅黑帧——报告同时提醒“正常电影黑场同样会被检测,需要与相邻原帧及现场时点区分”。

现场分发形态由 start-fg-flash-diagnostic.ps1 固化,关键参数与保护逻辑:

param(
    [string]$AppDirectory = $PSScriptRoot,
    [string]$ProfileSource = '',
    [string]$OutputDirectory = '',
    [string]$Source = '',
    [ValidateRange(15,90)][int]$DurationSeconds = 90
)
# 检查 veyra-flash-diagnostic.exe / qt.conf / Qt6Core.dll / qml/Veyra/Main.qml 就位
# 若已有 veyra_qml_ui / veyra-flash-diagnostic / flash-pixel-probe 进程则拒绝启动
# 复制 chain-session.v1(.vfg)、qml-preferences.v1.json、ui-session.v1、presets.v1、
# node-anchors.json 到独立 profile(只改副本,逐个记录 SHA256)
# 隔离 TEMP/TMP/CUDA_CACHE_PATH/VEYRA_LOG_FILE/VEYRA_FLASH_PROBE_DIR/QML_DISABLE_DISK_CACHE
# 启动参数: --data-dir <profile> --page pro --exit-after <ms> [源文件]

这与计划第五步“现场按原设置复现 15–20 秒并关闭”一一对应:诊断 EXE 最多 90 秒自动退出、取样最多 10000 次提交(120fps 约 83 秒)、需要正常关闭才保存取样,产物是 logs/flash-diagnostic-时间.zip。

七、日志侧核对:为什么“没有 Present 错误”不等于“没有 bug”

报告对 42.6MB/141,315 行的现场日志做了量化核对,其结论直接支撑了计划中“区分四类事件”的必要性:

  • 最后 DLSS/transport 稳定段约 927 秒、924 个 FPS 样本,中位源 60/提交 120;
  • 55399 个有效 FG,invalid=0、providerDisabled=0;另有 72 次“新增生成前跳过”、11 次“过期”——不是完全没有丢帧,但没有反复 reset 证据;
  • 这些计数不包含逐帧像素,所以报告开篇即强调:不能由 FPS 或 NGX/Present 成功推断像素正常,也不能由 60→30 有效推断 PTS 错误。

版本维度的核对同样谨慎:正式 2.0.6 到当时 main 的产品差异集中在 VFG 预算,未改 DLSS/XeSS graph、VideoPresenter 或 PresentSink,“当前没有版本二分证据证明哪个改动引入黑闪”。这解释了为什么最终交付物是诊断包而非修复版:Veyra-2.0.6-black-flash-diagnostic.zip 只追加命名不同的诊断 EXE 和入口,不含新增/替换 DLL 或模型。

八、完成门槛与未测边界

计划文档把“诊断门槛”与“修复门槛”严格分开:

  • 本轮诊断交付门槛:构建和启动通过、黑场正例能够检测、原包/原工作树保持、文档如实记录未测边界;
  • 产品修复门槛(尚未满足):现场复现 → 定位 → 最小修复 → 同设置回归。

报告列出的未测边界包括:原生 VFG/HDR 全矩阵、XeSS 内部生成帧(proxy swapchain 内部生成,探针覆盖不到)、现场实卡/全屏/VRR/长稳。同时给出两条诚实的阴性边界:取样会带来额外命令和屏障,“现场阴性也不能彻底排除时序竞争”;像素正常而屏幕黑闪,只能把方向移到提交后的呈现/窗口/合成/驱动/显示路径,不能直接宣布电视或驱动有问题。下一步唯一的关键证据,是“实际闪黑那次的双阶段像素及事件 CSV”。

九、方法论小结

把这份排查文档抽象出来,是一套可复用的实时 GPU 渲染故障诊断纪律:

  1. 固定边界条件(何种设置闪/不闪),拒绝在复现前写修复;
  2. 多模态证据互不替代:日志计数 ≠ 像素证据,录像 ≠ 屏幕时钟,缓解手段 ≠ 根因证明;
  3. 诊断代码与产品代码物理隔离:探针不进产品构建,诊断 EXE 不改算法/准入/时间戳/显示策略,profile 只复制不修改;
  4. 取样必须“同 list、有界、一次读回”:与 Draw 同一 command list 采样、有界 readback、fence 完成后一次读取,避免逐帧 CPU 等待污染时序;
  5. 正例验证检测器:先用故意生成的黑场素材证明探针能看见黑,再谈现场阴性结果;
  6. 保全可审计:基线 JSON、构建/运行收据(argv、EXE SHA、退出码)、原始失败记录全部保留,不重写成“全绿”。

文中涉及的证据文件均可在仓库中继续深入:计划正文见 docs/history/plans/FG_SOURCE_FLASH_PLAN_2026-10-08.md,配套报告见 docs/history/reports/FG_SOURCE_FLASH_REPORT_2026-10-08.md,呈现与 pacing 实现见 include/veyra/engine/VideoPresenter.h、include/veyra/engine/PresentationScheduler.h、include/veyra/engine/LiveFgAdmission.h、include/veyra/engine/CaptureHalfRate.h,诊断探针与启动脚本见 scripts/diagnostics/fg-flash/ 与 scripts/diagnostics/start-fg-flash-diagnostic.ps1。

登录后查看全文
Veyra-NRVideo