Veyra-NRVideo 补帧闪黑像素取样器:九点采样、双阶段事件与有界回读的现场诊断实践

原创2026-11-15 20:51:122,130 阅读
文章标签:音视频视频处理图像处理桌面应用直播

Veyra-NRVideo 补帧闪黑像素取样器:九点采样、双阶段事件与有界回读的现场诊断实践

本文以仓库中的 FG flash pixel sampler 诊断源码为主线,完整拆解 Veyra-NRVideo 为定位"补帧+源时间戳闪黑"而构建的九点像素取样方案:它如何在同一条呈现命令列表里同时记录"进入 presenter 的最终画面"和"Draw 之后的交换链 buffer",如何用 fence 与关闭时一次性回读把开销压到可接受范围,以及如何从两份 CSV 判断故障发生在图/补帧提供方、blit 与资源复用,还是呈现之后的窗口与显示路径。读完后你应当能独立复用这两个头文件、读懂现场回传的证据包,并清楚这套方法的结论边界在哪里。

1. 问题背景:FPS 正常、NGX 成功,都不等于像素正常

这项诊断工具的产生原因,记录在 补帧+源时间戳闪黑排查计划 与 闪黑排查报告 中:用户现场为 RTX 5090、Magewell Pro Capture HDMI 4K+ 采集、3840×2160 P010/PQ 约 59.94fps、LG 电视约 144Hz,开启补帧并使用"采用源时间戳"时出现整屏黑闪;关闭补帧,或把采集从 60 降到 30,黑闪消失。

问题在于,常规遥测几乎无法排除像素层面的异常:

  • 日志显示最后稳定段约 927 秒、924 个 FPS 样本,中位源 60 / 提交 120,55399 个有效 FG、invalid=0、providerDisabled=0;
  • 18 条 ERROR 全部指向 QML 几何操作与一次配置保存失败,没有任何 NGX / FG / Present / device-lost 错误;
  • 手机录像确实拍到了两帧接近全黑(约 3.467 秒与 4.300 秒,黑帧 ROI 平均码值约 1.97/255 与 2.09/255,周围正常画面约 89–92/255)。

也就是说:"Present 调用成功"与"屏幕上是正常图像"是两件事。闪黑可能发生在图输出之前(采集、色彩契约、补帧提供方),也可能发生在图正常但 blit / 描述符 / 资源复用出错,还可能发生在两者都正常、问题出在提交之后的窗口、遮罩、合成、驱动或显示路径。这三类原因的修复方向完全不同,所以需要一个能在真实呈现链路内留下证据的取样器。

2. 诊断代码的定位:只存在于诊断副本,不进入产品与 CMake

关联说明文件 scripts/diagnostics/fg-flash/README.md 的第一句话就是全篇最重要的约束:

Diagnostic-only sources; not linked into the normal product or its CMake targets.

它不是播放器的一部分,也没有被任何产品目标或 CMake target 引用。仓库里只保留三样东西:

路径 作用
FlashPixelProbe.h 九点 RGBA8 / RGB10 采样器与 CSV 落盘
FieldPixelProbe.h 帧身份、源/缓冲配对事件、关闭时输出
README.md 用法、限制与基线哈希

关键机制是 README 中那句 "The generated external VideoPresenter copy":取样代码不是自动挂钩的,而是通过一份生成的外部 VideoPresenter 副本注入 record() 调用,用这份副本重链接出诊断 EXE。这样做的原因很直接——VideoPresenter::present() 的结尾正好是"最终图像"与"交换链 buffer"都在同一张命令列表里、还没 Submit 的时刻,这是唯一能同时看到两者、又不需要跨进程抓帧的位置。

仓库内的产品 src/engine/VideoPresenter.cpp 不含任何探针调用;正常的绘制-呈现路径见 VideoPresenter.cpp,只有转场与资源状态管理。因此阅读本文时要把两件事分开:取样器是取证工具,产品里的兼容开关是另一条独立实现的可选路径(第 8 节)。

3. FlashPixelProbe.h:九点采样器的结构

3.1 容量与显存预算:一个可计算的硬上限

inline constexpr unsigned capacity=20000, points=9, stride=512;

三个常量决定了整套取样的资源上界:

  • capacity = 20000:最多保留 20000 条取样记录,写满即置 overflow=true 并丢弃后续记录;
  • points = 9:每条记录取 3×3 共九个像素;
  • stride = 512:每条记录在 readback 缓冲里占 512 字节(九个像素,每像素一份 1×1 拷贝,行距按 256 字节对齐后仍留余量)。

回读缓冲在第一次 record() 时惰性创建,宽度直接等于 capacity * points * stride:

rd.Width=uint64_t(capacity)*points*stride;

即 20000 × 9 × 512 = 92,160,000 字节 ≈ 87.9 MiB,与报告中"约 88MiB 有界 readback"一致。这是一次性有界分配,不会随帧数增长——这一点和"持续抓帧"式诊断有本质区别,也是它能被允许在用户现场跑几十秒的前提。

3.2 Entry:让每个像素样本带上足够的因果信息

struct Entry {bool generated;uint64_t source;uint32_t slot;DXGI_FORMAT format;
              uint64_t epoch,revision;int64_t pts,unix100ns;const char* stage;};

字段设计对应了排查所需的全部对照维度:

  • generated:这一张是真实增强原帧还是补帧生成帧;
  • source:源帧 ID,对应 pipeline::FrameIdentity::sourceFrameId(结构定义见 FrameBatch.h);
  • slot:输出池槽位,用于判断纹理奇偶复用是否错配;
  • epoch / revision:引擎代次与设置 revision,用来区分"场景重建/设置变更"与"运行中异常";
  • pts:源时间戳(100ns),配合"采用源时间戳"这一现场条件;
  • unix100ns:记录时刻的墙上时间,用于和日志、手机录像做粗对齐;
  • stage:present-input 或 present,标明这条样本来自"进入 presenter 的纹理"还是"Draw 之后的 buffer"。

3.3 record():分配、格式白名单、屏障、九次 1×1 拷贝

record() 的执行顺序值得逐段确认,因为它决定了证据的可信度:

  1. 容量检查:entries.size()==capacity 时置 overflow 并返回,绝不扩容;
  2. 惰性建缓冲:READBACK 堆、D3D12_RESOURCE_DIMENSION_BUFFER、COPY_DEST 初始状态,失败置 failed;
  3. 格式白名单:
if(d.Format!=DXGI_FORMAT_R10G10B10A2_UNORM&&d.Format!=DXGI_FORMAT_R8G8B8A8_UNORM){failed=true;return;}

只接受 HDR10 主链路常见的 10-bit RGB 与 8-bit RGBA;其它格式(例如某些中间 FP16 表面)直接判为采样失败,避免输出"看起来有数但其实不对"的 CSV;

  1. 状态切换:从 COMMON 转到 COPY_SOURCE,取样结束后再用交换 StateBefore/StateAfter 的方式还原;
  2. 九次 CopyTextureRegion:每次拷贝一个 1×1 的 box,落到 readback 缓冲中 (entries.size()*points + y*3 + x) * stride 的位置,PlacedFootprint.Footprint 为 {d.Format,1,1,1,256};
  3. 打时间戳:GetSystemTimePreciseAsFileTime 取 FILETIME,减去 116444736000000000(1601→1970 的 100ns 偏移)得到 Unix 100ns;
  4. 入队:把 Entry 追加到 entries。

注意第 4 步是一个诊断假设:它默认目标纹理在采样前处于 COMMON。这在生成副本注入的位置成立,但如果把这段代码搬到状态管理不同的调用点,就必须先修正屏障,否则会得到 D3D12 状态错误或不可信数据。

3.4 九个点到底采在哪里

采样位置由一行算术决定:

const unsigned xx=unsigned(d.Width)*(x+1)/4,yy=d.Height*(y+1)/4;

x、y 取 0/1/2,于是九点落在宽高的 1/4、1/2、3/4 网格上,即画面中心与四个象限的代表点。这是刻意的折中:

  • 比单点取样更容易抓到"整屏黑"这类全画面故障;
  • 又远小于全画面回读,拷贝量固定为 9 × 1 像素;
  • 代价是它无法证明"某个像素没问题",只能证明"这九个位置现在是什么值"。报告里对此的表述很明确:"9 点采样不覆盖每个像素,更不是面板扫描证据"。

3.5 dump():黑点判定与返回值语义

dump() 在关闭流程里被调用一次,Map 之后逐条解析:

if(e.format==DXGI_FORMAT_R10G10B10A2_UNORM){uint32_t v=0;std::memcpy(&v,p,4);rgb={v&1023,(v>>10)&1023,(v>>20)&1023};}
else rgb={unsigned(p[0])*1023/255,unsigned(p[1])*1023/255,unsigned(p[2])*1023/255};

8-bit 样本被线性放大到 0–1023,使两种格式在同一码值尺度上可比。判定规则是:

  • 单点:localMax<=5(三个通道最大码值不超过 5)记为黑点;
  • 单条记录:九个点全黑(black==points)才记为"这一帧全黑";
  • 汇总:分别累计真实帧与生成帧的全黑数量。

CSV 表头固定为:

ordinal,source,generated,slot,format,minCode,maxCode,meanCode,blackPoints,epoch,revision,pts100ns,unix100ns,stage

其中 minCode/maxCode/meanCode 是九点九通道的极值与均值(mean 除以 points*3),blackPoints 是 0–9 的计数。这些列足以回答三类问题:这一帧是黑还是暗?是整帧黑还是局部?黑的是原帧还是生成帧?

函数末尾的返回值语义同样重要:

const bool ok=out.good()&&blackReal==0&&blackGenerated==0&&!overflow;

也就是说 dump() 返回 true 表示"没有任何取样帧全黑",它在 FieldPixelProbe 的日志里被打印为 nonblack=。这个布尔值是"本次运行未见全黑样本"的意思,不是"画质通过"的意思,更不能反过来当作故障复现。

4. FieldPixelProbe.h:把像素与提交、呈现事件配对

单点像素只能说明"某个时刻某个位置是黑的"。要判断责任环节,还需要知道这张图是第几帧、属于哪次提交、那次 Present 是否成功。这就是 FieldPixelProbe 的职责。

4.1 Event 与序数配对

struct Event {size_t sourceOrdinal,bufferOrdinal;uint64_t frame,epoch,revision,fence;
              int64_t pts,recorded,presentEnd;unsigned backBuffer;int result=-1;};

record() 先记一条 present-input,再记一条 present,两次成功后压入一个 Event,用 sourceOrdinal / bufferOrdinal 指向 flashProbe::entries 中的两条记录。这样两份 CSV 可以通过序数直接 join,不需要靠时间戳猜配对。

顺序也很关键:

flashProbe::record(device,list,source,generated,frame,slot,epoch,revision,pts,"present-input");
flashProbe::record(device,list,buffer,generated,frame,slot,epoch,revision,pts,"present");

两条拷贝落在同一张命令列表里,因此它们看到的是同一个 GPU 时刻的图像状态,中间不存在另一帧插入的可能。这正是 README 所强调的 "in the same command list"。

容量检查也相应按两条计算:

if(flashProbe::entries.size()+2>flashProbe::capacity){flashProbe::overflow=true;return;}

于是 capacity=20000 实际对应约 10000 次呈现。报告里"取样最多 10000 次提交,120fps 约 83 秒"正是由此得来(10000 / 120 ≈ 83 秒),高倍率补帧会更早到上限。

4.2 submitted / presented:不侵入逐帧路径的时序钩子

inline void submitted(ID3D12Fence* fence,uint64_t value){
    if(flashProbe::entries.size()==submittedEntries)return;
    submittedEntries=flashProbe::entries.size();lastFence=fence;lastValue=value;
    if(!events.empty())events.back().fence=value;
}
inline void presented(bool ok){
    if(!events.empty()&&events.back().presentEnd==0){events.back().presentEnd=wall100ns();events.back().result=ok?1:0;}
}

这两个钩子只做记录:前者保存最近一次真正提交的 fence 值与提交时的记录数(submittedEntries),后者写 Present 结束时间与结果。submitted() 里的提前返回还顺带解决了"记录了但没提交"的问题——它只在记录数增长后才更新,避免同一提交被多次覆盖。

4.3 finish():只在收尾等待一次 fence

整个设计的性能底线体现在 finish() 的注释里:

Close already drains the private presenter queue. Shared-queue paths use their submitted fence; wait only here, never in the per-frame loop.

具体流程:

  1. 如果 lastFence 未完成,用 SetEventOnCompletion + WaitForSingleObject(event, 10000) 最多等 10 秒;
  2. 等待失败或超时则记 error 日志并直接返回,不做 Map(宁可不产出数据,也不产出未完成的 GPU 数据);
  3. flashProbe::entries.resize(submittedEntries),把"记录了但提交失败"的尾部裁掉;
  4. 解析输出目录、建目录、生成文件名 flash-pixels-<pid>-<unix100ns>.csv;
  5. 调 flashProbe::dump() 写像素 CSV,再写 -events.csv;
  6. 打一条 info 日志,随后清空 events、readback、entries 与失败标志。

第 3 步是这份实现里最容易被忽略、但对证据有效性最关键的细节:如果最后几帧记录了却没有成功提交,它们的像素从未被 GPU 写过,留在 CSV 里就会变成"凭空出现的黑帧"。

4.4 输出位置与文件名

const DWORD length=GetEnvironmentVariableW(L"VEYRA_FLASH_PROBE_DIR",overridePath,32768);
const auto dir=length&&length<32768?std::filesystem::path(overridePath):veyra::runtime::logsDirectory();
  • 优先使用环境变量 VEYRA_FLASH_PROBE_DIR(启动器会把它指向本轮独立输出目录);
  • 否则退回 veyra::runtime::logsDirectory(),其实现为应用根目录下的 logs(见 RuntimePaths.cpp)。

每次运行产出两个文件:flash-pixels-<pid>-<时间>.csv 与同名 -events.csv。前者是像素与身份,后者是提交/呈现事件。

4.5 两份 CSV 的列语义

像素 CSV 已在上文列出。事件 CSV 的列为:

sourceOrdinal,bufferOrdinal,frame,epoch,revision,pts100ns,recordUnix100ns,presentEndUnix100ns,backBuffer,submitFence,presentOk
列 含义 典型用途
sourceOrdinal / bufferOrdinal 指向像素 CSV 的 ordinal 把输入纹理与交换链 buffer 配对
frame 源帧 ID 与引擎日志、FrameIdentity 对齐
epoch / revision 引擎代次与设置 revision 区分重建/改设置与运行中异常
pts100ns 源时间戳 验证"采用源时间戳"下的时间关系
recordUnix100ns 记录时刻 与 engine.log、录像做粗对齐
presentEndUnix100ns Present 返回时刻 估算该帧在呈现侧停留的时间
backBuffer 交换链 buffer 索引 判断是否与缓冲区轮转相关
submitFence 提交时 fence 值 证明这批样本确实被提交
presentOk Present 结果(1/0) 排除 Present 失败导致的"黑屏"

一个实用的判读方式是:先按 presentOk=0 过滤,再按 epoch/revision 分段,最后才看黑样本分布。顺序反过来很容易把"设置重建瞬间的一帧"当成"运行期竞争"。

5. 现场启动器:start-fg-flash-diagnostic.ps1

取样器需要一个可复现、可交回的运行环境,这部分由 start-fg-flash-diagnostic.ps1 承担。

5.1 参数

param(
    [string]$AppDirectory = $PSScriptRoot,
    [string]$ProfileSource = '',
    [string]$OutputDirectory = '',
    [string]$Source = '',
    [ValidateRange(15,90)][int]$DurationSeconds = 90
)
参数 默认 说明
AppDirectory 脚本所在目录 必须是完整播放器目录
ProfileSource <app>/runtime_local/user-data-2.0.0 原配置来源,只读复制
OutputDirectory <app>/logs/flash-diagnostic-<时间> 已存在则直接报错,拒绝覆盖证据
Source 空 可选媒体/采集源,作为位置参数传给播放器
DurationSeconds 90 限制在 15–90 秒,换算成 --exit-after 毫秒

5.2 前置检查与进程互斥

启动器先校验四个文件存在:veyra-flash-diagnostic.exe、qt.conf、Qt6Core.dll、qml/Veyra/Main.qml;缺任何一个就抛出"先把诊断文件放到原 2.0.6 NVIDIA 目录"。

随后检查互斥:

$players = @(Get-Process -Name 'veyra_qml_ui','veyra-flash-diagnostic','flash-pixel-probe' -ErrorAction SilentlyContinue)
if ($players.Count -gt 0) { throw 'Close other Veyra players before starting this diagnostic.' }

这一条不是形式主义:如果原播放器还在跑,GPU 上就会有两个呈现链路和解码会话,取样掩码、fence 与显存读数都会失去可比性。

5.3 私有配置:只复制白名单,并用 SHA 证明原件未变

$names = @('chain-session.v1','chain-session.v1.vfg','qml-preferences.v1.json','ui-session.v1','presets.v1','node-anchors.json')

复制前记录每个文件的 SHA256,运行结束后逐一复核:

if (-not (Test-Path -LiteralPath $item.path -PathType Leaf) -or
    (Get-FileHash -LiteralPath $item.path -Algorithm SHA256).Hash -ne $item.sha256) { $unchanged=$false }

这一步把"用户按原设置复现"从口头约定变成了可验证事实:诊断播放器读的是副本,用户的原配置在诊断期间没有被改写。

5.4 环境隔离与启动参数

$env:TEMP=$tmp; $env:TMP=$tmp
$env:CUDA_CACHE_PATH=Join-Path $tmp 'cuda-cache'
$env:VEYRA_LOG_FILE=Join-Path $output 'engine.log'
$env:VEYRA_FLASH_PROBE_DIR=$output
$env:QML_DISABLE_DISK_CACHE='1'

五个变量各自解决一件事:临时目录与 CUDA 缓存不污染用户目录、日志固定落在本轮输出、取样 CSV 写进同一目录、QML 磁盘缓存关闭以避免把旧缓存带进对照。

进程参数是:

$arguments = @('--data-dir',$profile,'--page','pro','--exit-after',($DurationSeconds * 1000).ToString())

--data-dir 让播放器使用私有配置;--page pro 直接进入专业页便于还原补帧链路;--exit-after 是仓库通用的测试开关,其解析在 apps/veyra-qml/main.cpp,注释明确写着"0 表示一直运行到手动关闭"。

5.5 退出码与回执

if (-not $process.WaitForExit(($DurationSeconds + 45) * 1000)) {
    $forcedStop = $true; Stop-Process -Id $process.Id -Force; $process.WaitForExit(); $result = 124
} else {
    $process.WaitForExit(); $process.Refresh(); $result = $process.ExitCode
    if ($null -eq $result) { $result = 125 }
}
  • 超过 DurationSeconds + 45 秒仍未退出:强制结束,退出码记 124;
  • 拿到像素但 ExitCode 为 null(Windows PowerShell 5.1 的已知行为):记 125。

代码里那行 $null = $process.Handle 正是为了规避这个问题——先保持进程句柄再等待。报告中也保留了这条教训:"首次 PowerShell 5.1 入口取得像素但 ExitCode 为 null,不记为退出码验收通过"。同一份报告里还有一个类似的坑:PowerShell 继承模块路径导致缺少 Get-FileHash,最终改用 .NET 的哈希实现。

回执 diagnostic-receipt.json 记录 exit、forcedStop、diagnosticSha256、privateProfile、copiedSourceProfileFilesUnchanged、durationLimitSeconds 与 pixelFiles。证据 ZIP 只打包 .log、.csv、.json:

$evidence = @(Get-ChildItem -LiteralPath $output -File | Where-Object { $_.Extension -in '.log','.csv','.json' } | Select-Object -ExpandProperty FullName)
Compress-Archive -LiteralPath $evidence -DestinationPath ($output + '.zip') -CompressionLevel Optimal

注释写得很直白:"never include the copied profile or credentials"。私有配置目录不进证据包,这是这份启动器最容易被忽视的安全设计。

6. 怎么读结果:三条分叉

取样器的价值不在于"有没有黑",而在于把黑定位到链路的哪一段。原始排查计划给出的判读顺序是:

观察 结论方向 下一步
present-input 已黑 图像在进入 presenter 前就有问题 查处理图、补帧提供方、采集/色彩契约与交接
输入正常、present 黑 绘制/呈现环节 查 blit、描述符、资源复用、交换链 buffer 状态
两者都正常、屏幕仍闪黑 提交之后的路径 查窗口、遮罩、合成、驱动、显示路径

第三行有一个常被忽略的限定:报告特别补充"最后一种情况也不能直接归咎电视或驱动"。因为此时你只知道"提交前与提交时的 buffer 有像素",并不知道面板实际扫描出的内容。

6.1 为什么必须用已知黑场做正例

一份"全是非黑"的 CSV 有两种可能:设备真的没问题,或者取样器根本没在工作。因此报告记录的验收里专门包含已知黑场输入:

  • DLSS2X / 源 60,已知黑场输入共 480 原帧 / 479 生成帧,准确检测到 13 张黑原帧 / 12 张黑生成帧,呈现输入与 buffer 一致;
  • 最终 PowerShell 5.1 入口 + 已知黑场 + VFG4:449 原帧 / 1345 生成帧,检测到 13/36 张黑帧,exit0、forcedStop=false。

只有"能给黑图打上黑标签",阳性结果才有意义;否则所谓阴性只是工具失灵。报告对这一点写得很克制:"已知黑场是故意生成的测试素材,不是现场故障复现。最终取样器能检测黑图,仍不代表现场 bug 已修复。"

6.2 本机矩阵:六组都非黑说明了什么

报告的表格给出了本机 RTX 5070 的原生用例结果(原帧样本 / 生成帧样本 / 九点全黑数):

原生用例 原帧样本 生成帧样本 九点全黑
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

正确的读法是:在本机、这批输入、这条路径上,没有复现出全黑。它排除了"取样器在所有情况下都会误报黑"这一可能,但没有排除现场差异(5090、驱动 617.42、实卡输入、HDR 面板)。报告也明确写了"原生诊断没有实卡输入,也没有 HDR 面板扫描验收"。

7. 方法学边界:README 用两句话写清了

关联文档里最值得引用的其实是这两句:

A black sample is evidence of black pixels, not proof of a bug. XeSS-internal generated frames and panel scanout are not measured.

展开来看,至少有六条边界需要在使用和引用结论时保持:

  1. 黑样本只是像素事实。正常电影黑场同样会被判为黑,必须结合相邻原帧与现场时点区分。
  2. XeSS 在代理 swapchain 内部生成的帧不在覆盖范围。对这类提供方,"生成帧样本数"偏低是机制使然,不是丢帧。
  3. 面板扫描输出未测。九点采样发生在 buffer,不涉及 scanout。
  4. 采样本身改变时序。每次呈现多出 18 次单像素 GPU 拷贝与额外屏障,即使 CPU 只在退出时读一次,也会改变缓存/布局与 GPU 执行节奏。报告用这一点解释了一个非常容易误判的现象:诊断版不闪,并不等于已经定位(详见 HDR 补帧闪黑排查与可回退候选 中"诊断与原版并非单变量实验"一节)。
  5. 九点不等于全屏。它擅长抓整屏黑,弱于抓局部异常。
  6. 阴性不能彻底排除时序竞争。取样引入了新的命令与屏障,现场阴性只是"在这套被观测的时序下未出现"。

还有一条实现层面的限制值得单独提示:record() 的格式白名单只有 R10G10B10A2_UNORM 与 R8G8B8A8_UNORM。如果目标表面是 FP16 或其它格式,failed 会被置位,dump() 返回 false,日志会打出 samplerFailed=true (supported RGBA8/RGB10 only)。看到这条日志不要怀疑帧有问题,先怀疑采样点选错了对象。

8. 从诊断线索到产品开关:hdrFgCompatibility

取样器本身不修复任何东西。它留下的最有价值线索是:改变最终 GPU 访问方式的那条分支没有闪。这条线索被做成了一个默认可回退的兼容候选,最终以设置开关的形式落地,过程记录在 HDR 补帧兼容开关与本地 main 整合 与 HDR 补帧兼容报告。

8.1 生效条件

VideoPresenter::open() 里先判定"有没有资格":

copyEligible_=ctx.adapter().isNvidia&&graph.hdr10Output()&&graph.fgEnabled()&&bool(presentationQueue_);
copyBeforePresent_=false;

四个条件同时成立才"有资格":NVIDIA 适配器、HDR10 输出、应用侧补帧开启、存在独立呈现队列。有资格不等于启用——copyBeforePresent_ 初始为 false,打开源不会替用户做选择,也不会分配合成纹理。

8.2 切换:只在切换时排空一次

configurePresentation() 把用户偏好与资格合成最终决策:

bool wanted=requested.hdrFgCompatibility&&copyEligible_;

切换时:

if(presentationRing_.initialized()&&!presentationRing_.drainQueue()){
    veyra::log::warn("present-copy","compatibility switch deferred: presentation queue drain failed");
}else{
    copyBeforePresent_=wanted;
    if(wanted&&!refresh(ctx.device())){copyBeforePresent_=false; ...}
    if(!copyBeforePresent_)compositeTarget_.Reset();
}

这段代码有两处防御值得学习:排空失败时不改状态(延迟到下一次机会),refresh() 失败时回退直呈并保留日志,effective.hdrFgCompatibility=copyBeforePresent_ 让 UI 看到的是实际生效值而不是用户期望值。仓库里还留了一个只读的测试覆盖变量 VEYRA_TEST_HDR_PRESENT_COPY,注释写明"Only bounded regression tests may force the copy path on SDR"。

8.3 呈现路径:合成到一张目标,再 CopyResource

present() 只在开关生效时改变 render target:

auto* renderTarget=copyBeforePresent_?compositeTarget_.Get():bb;

绘制结束后,状态迁移与复制在 同一函数尾部:

if(copyBeforePresent_)barriers[1].Transition.StateAfter=D3D12_RESOURCE_STATE_COPY_SOURCE;
list->ResourceBarrier(2,barriers);
if(copyBeforePresent_){
    ... // bb: PRESENT -> COPY_DEST
    list->CopyResource(bb,renderTarget);
    ... // bb: COPY_DEST -> PRESENT;composite: COPY_SOURCE -> COMMON
}

语义是:原有绘制、比较、HDR 曲线全部照旧,只是把最终合成落在单张纹理上,然后整幅复制到交换链,再回到 PRESENT。源时间戳、补帧倍率、丢帧/过期规则、光流/NR/FG 算法与 VSync 都没有改变。

8.4 代价与默认值

  • 显存:单张 DEFAULT 纹理,4K 实测分配 33,423,360 字节(31.875 MiB),固定复用,不随帧累积;只有队列排空后才重建或释放。
  • GPU:每次显示多一次整幅复制与若干屏障,报告明确"不保证零开销",也不宣称复制让算法更快。
  • 默认关闭:设置项 hdrFgCompatibility 默认为 false,见 PresentationSettings.h 与偏好桥接 Preferences.cpp。
  • UI 文案:设置页"设置 → 兼容"里的开关在 SettingsPage.qml,提示语是"默认关闭。仅 NVIDIA HDR10 补帧时生效;4K 额外约 32 MiB 显存,可能增加 GPU 开销。切换时画面可能短暂停顿。"

8.5 兼容路径与诊断探针不是一回事

这是最容易混淆的一点,值得列表对照:

维度 诊断取样器 产品兼容路径
代码位置 scripts/diagnostics/fg-flash/,仅进入诊断副本 src/engine/VideoPresenter.cpp,随产品构建
额外拷贝 每次呈现 18 次单像素拷贝 + readback 每次显示一次整幅 CopyResource
CPU 等待 关闭时一次 fence 等待 + Map 无像素回读、无额外 CPU fence 等待或睡眠
目的 取证 回避"直接绘制 HDR 交换链 → Present"路径
输出 两份 CSV + 日志 一行 present-copy 日志与 effective 设置
结论强度 只陈述像素事实 有依据的兼容候选,不等于根因已确认

最后一行必须保留:VideoPresenter.cpp 里的注释原文是"This is a compatibility candidate, not proof of a driver defect",报告也反复写"根因尚未确认,不能写'已根治'"。使用这份开关时,正确的心智模型是"一条可回退的规避路径",而不是"一个已定位 bug 的修复"。

8.6 产品侧的等价性验证

开关不能破坏画质,所以仓库里有一份针对性很强的集成测试夹具 HdrCopyPresentationFixture.h:它在同一次运行里反复切换开关(第 16 帧关、第 32 帧开、第 24/40 帧改窗口大小),每个阶段生成 640×360 P010 的确定性测试图,然后把实际呈现的 buffer 与源纹理逐像素比较:

ok=applyCompatibility(false)&&ok;
ok=applyCompatibility(true)&&ok;
for(unsigned i=0;ok&&i<64;++i){
    if(i==16)ok=applyCompatibility(false)&&ok;
    if(i==32)ok=applyCompatibility(true)&&ok;
    ...
}

readHdrWords() 只在这个边界内有界回读,比较 10-bit RGB 码值并允许误差 ≤1。报告记录的 4K 交换链结果是"各 512 原帧 / 620 生成帧、94 次无损 10-bit 窗口对照,最大 RGB 码值误差 0、D3D12 错误 0",并注明"4K 是输出缓冲验证,测试输入 640×360 P010,不宣称 4K NR 或物理 HDR 显示验收"。

9. 现场复现清单

如果你手上有一份现场闪黑的机器,按下面的顺序做一遍,就能得到与报告同构的证据:

  1. 准备目录:把诊断包顶层文件放到原 2.0.6 NVIDIA 便携版根目录,与 veyra_qml_ui.exe 同级,不覆盖原 EXE。
  2. 确认前置文件:veyra-flash-diagnostic.exe、qt.conf、Qt6Core.dll、qml/Veyra/Main.qml 四者齐备。
  3. 关闭其它播放器:否则启动器直接报错退出。
  4. 运行启动器:Start-Flash-Diagnostic.cmd(或直接 powershell.exe -NoProfile -ExecutionPolicy Bypass -File scripts/diagnostics/start-fg-flash-diagnostic.ps1 并显式传参)。
  5. 还原现场条件:同一采集源、同一补帧后端与倍率、勾选"采用源时间戳",在容易闪黑的静止场景复现 15–20 秒,看到黑闪后正常关闭诊断播放器。
  6. 取回证据:logs/flash-diagnostic-<时间>.zip,内含 flash-pixels-*.csv、*-events.csv、engine.log、diagnostic-receipt.json。
  7. 核对回执:exit=0、forcedStop=false、copiedSourceProfileFilesUnchanged=true、pixelFiles 非空。任一项不符合,本次样本就不能作为对照证据。

如果控制台被误关或播放器崩溃,取样未完成时不会有 CSV——这不是工具坏了,而是 finish() 里"fence 未完成就不 Map"的保守策略在起作用(超时会记 teardown sample fence not complete ... not mapping)。

10. 常见问题

Q:跑完没有 flash-pixels-*.csv,只有 events? A:看 engine.log 里的 flash-probe 日志。出现 no pixel CSV written; samples=... samplerFailed=true (supported RGBA8/RGB10 only) 说明采样目标格式不在白名单内;出现 teardown sample fence not complete 说明收尾 fence 未在 10 秒内完成,证据被主动丢弃。

Q:CSV 里 overflow 出现在日志的 capped=true 是什么意思? A:取样记录达到 20000 条上限(约 10000 次呈现)。此时 dump() 的返回值恒为 false,日志会打 capped=true。长跑场景应降低倍率或缩短复现时间,而不是扩大容量——容量直接决定 88 MiB 的回读缓冲。

Q:为什么生成帧样本数比原帧少很多? A:两种常见原因。一是补帧实际未生效或部分生成帧被判为无效(GenerationValidity 不等于 Valid 的帧不会被呈现);二是使用 XeSS 时,其内部生成的帧不经过这里,属于已知不覆盖范围。

Q:能直接用这两份 CSV 判断"是驱动的锅"吗? A:不能。CSV 只能说明"某一时刻某九个位置的码值"。当输入与 buffer 都正常而屏幕仍在闪时,结论只能表述为"问题在提交之后的某处",需要继续区分窗口、遮罩、合成、驱动与显示路径。

Q:可以把它合进产品做常规遥测吗? A:不建议,也违背设计意图。README 第一行就写明它不进入产品与 CMake target;报告还记录了改名(veyra_qml_ui.exe → veyra-flash-diagnostic.exe)本身就可能绕开 NVIDIA App / RTSS 的按程序配置,从而让对照失真。取证工具留在诊断分支,产品侧只保留那条不读回像素的兼容路径。


证据与适用范围小结:本文所有实现细节来自 scripts/diagnostics/fg-flash/README.md、FlashPixelProbe.h、FieldPixelProbe.h、start-fg-flash-diagnostic.ps1 与产品侧 VideoPresenter;现场数据与结论边界来自 闪黑排查报告、HDR 补帧闪黑排查与可回退候选 与 兼容开关报告。截至这些记录,黑闪根因尚未确认,用户 5090 现场回测、实卡 HDR/全屏/VRR 长稳仍未验证,因此不应把任一开关或任一阴性取样结果表述为"已解决"。

登录后查看全文
Veyra-NRVideo