Veyra-NRVideo 补帧闪黑像素取样器:九点采样、双阶段事件与有界回读的现场诊断实践
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() 的执行顺序值得逐段确认,因为它决定了证据的可信度:
- 容量检查:
entries.size()==capacity时置overflow并返回,绝不扩容; - 惰性建缓冲:READBACK 堆、
D3D12_RESOURCE_DIMENSION_BUFFER、COPY_DEST初始状态,失败置failed; - 格式白名单:
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;
- 状态切换:从
COMMON转到COPY_SOURCE,取样结束后再用交换StateBefore/StateAfter的方式还原; - 九次
CopyTextureRegion:每次拷贝一个 1×1 的 box,落到 readback 缓冲中(entries.size()*points + y*3 + x) * stride的位置,PlacedFootprint.Footprint为{d.Format,1,1,1,256}; - 打时间戳:
GetSystemTimePreciseAsFileTime取 FILETIME,减去116444736000000000(1601→1970 的 100ns 偏移)得到 Unix 100ns; - 入队:把
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.
具体流程:
- 如果
lastFence未完成,用SetEventOnCompletion+WaitForSingleObject(event, 10000)最多等 10 秒; - 等待失败或超时则记
error日志并直接返回,不做 Map(宁可不产出数据,也不产出未完成的 GPU 数据); flashProbe::entries.resize(submittedEntries),把"记录了但提交失败"的尾部裁掉;- 解析输出目录、建目录、生成文件名
flash-pixels-<pid>-<unix100ns>.csv; - 调
flashProbe::dump()写像素 CSV,再写-events.csv; - 打一条 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.
展开来看,至少有六条边界需要在使用和引用结论时保持:
- 黑样本只是像素事实。正常电影黑场同样会被判为黑,必须结合相邻原帧与现场时点区分。
- XeSS 在代理 swapchain 内部生成的帧不在覆盖范围。对这类提供方,"生成帧样本数"偏低是机制使然,不是丢帧。
- 面板扫描输出未测。九点采样发生在 buffer,不涉及 scanout。
- 采样本身改变时序。每次呈现多出 18 次单像素 GPU 拷贝与额外屏障,即使 CPU 只在退出时读一次,也会改变缓存/布局与 GPU 执行节奏。报告用这一点解释了一个非常容易误判的现象:诊断版不闪,并不等于已经定位(详见 HDR 补帧闪黑排查与可回退候选 中"诊断与原版并非单变量实验"一节)。
- 九点不等于全屏。它擅长抓整屏黑,弱于抓局部异常。
- 阴性不能彻底排除时序竞争。取样引入了新的命令与屏障,现场阴性只是"在这套被观测的时序下未出现"。
还有一条实现层面的限制值得单独提示: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&©Eligible_;
切换时:
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. 现场复现清单
如果你手上有一份现场闪黑的机器,按下面的顺序做一遍,就能得到与报告同构的证据:
- 准备目录:把诊断包顶层文件放到原 2.0.6 NVIDIA 便携版根目录,与
veyra_qml_ui.exe同级,不覆盖原 EXE。 - 确认前置文件:
veyra-flash-diagnostic.exe、qt.conf、Qt6Core.dll、qml/Veyra/Main.qml四者齐备。 - 关闭其它播放器:否则启动器直接报错退出。
- 运行启动器:
Start-Flash-Diagnostic.cmd(或直接powershell.exe -NoProfile -ExecutionPolicy Bypass -File scripts/diagnostics/start-fg-flash-diagnostic.ps1并显式传参)。 - 还原现场条件:同一采集源、同一补帧后端与倍率、勾选"采用源时间戳",在容易闪黑的静止场景复现 15–20 秒,看到黑闪后正常关闭诊断播放器。
- 取回证据:
logs/flash-diagnostic-<时间>.zip,内含flash-pixels-*.csv、*-events.csv、engine.log、diagnostic-receipt.json。 - 核对回执:
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 长稳仍未验证,因此不应把任一开关或任一阴性取样结果表述为"已解决"。