Veyra-NRVideo 本地 main 修复整合与 HDR 补帧闪黑兼容开关:从四次 --no-ff 合并到源码级验收
Veyra-NRVideo 本地 main 修复整合与 HDR 补帧闪黑兼容开关:从四次 --no-ff 合并到源码级验收
本文以 Veyra-NRVideo 仓库中的整合报告为主线,完整复盘 2026-10-09 这一轮"把已完成分支合入本地 main,同时把 HDR 补帧闪黑兼容做成默认关闭的设置开关"的工程过程。读完后你能掌握:如何在保留原作者提交的前提下做多次 --no-ff 合并、如何处理文档类冲突的"全量保留"解析、hdrFgCompatibility 这个全局偏好从 QML 开关一路走到 D3D12 呈现路径的完整调用链,以及这类 GPU 呈现改动用什么样的构建与定向回归证据才算可判读。
一、这轮整合要解决的两件事
原报告开篇就把范围钉死:用户先授权"先把目前修复合并到 main",随后要求把 HDR 补帧闪黑兼容做成设置页开关、默认关闭。本轮完成这个选择后整合已完成分支;未推送、发布、更改版本或关机。旧 UI/engine 冻结由本轮具体授权覆盖,没有继续其它历史实验。
这两件事的技术性质完全不同,也决定了后文的篇幅分配:
- 合并是仓库治理问题:要保留原作者/原作者提交、保留分支拓扑、冲突只允许"追加/前置记录",不允许整份取 ours/theirs。
- 开关是呈现路径问题:要把一个候选修复(HDR 应用侧补帧时偶发闪黑)从"自动启用"降级为"用户显式选择",并且保证默认路径的显存与逐帧开销零变化。
二、合并范围:四次 --no-ff 与提交拓扑
报告记录的合并基线是 main dbfceabee804cd81bac4a4781f0b7b4cf272902e,工作树位于 E:/项目/Veyra/worktrees/main-merge-20261002。四次合并全部使用 --no-ff,目的很直接:即使某个分支可以快进,也要留下一个合并提交,从而保留原作者、原提交与分支来源。
| 分支 | 原分支 tip | 合并提交 |
|---|---|---|
| codex/fg-source-flash-20261008 | 3fd3cde2 | 52d83eaf |
| codex/nv-vram-field-20261008 | a210ec18 | 49c9e95c |
| codex/blackmagic-followup-20261009 | 886b461b | 083d6785 |
| codex/fg-flash-fix-20261009 | f6a8fa27 | 2caa8dca |
四个分支的"产品含量"差别很大,报告对此做了明确区分:
- 前两个分支只有隔离诊断脚本/头文件和记录,因此不把像素取样或显存追踪加入正常 GUI。这一点在后文的验收边界里反复出现——正常播放路径不能因为排查而背上探针成本。
- BMD(Blackmagic)分支只改原生接收协商及其定向测试。
- HDR 候选
ce50d18的自动启用被f6a8fa27改为用户选择,这就是"开关"的来源。
产品合并节点为 2caa8dca928d50634dd301622aa2da69ab336048;之后仅修组合验收脚本和归档文档。也就是说,代码合并在 2caa8dca 就已经收敛,后续提交不再触碰生产行为。
三、冲突解析:只允许"追加",禁止整份取一边
这次合并的冲突面很窄,只涉及 AGENTS.md 和 WORKLOG 的追加/前置记录。但报告记录的处理规则值得单独摘出来,因为它是可复用的协作策略:
- 解析 Git 三阶段(base / ours / theirs),要求完整旧正文仍逐字存在;
- 在满足上一条的前提下,保留两边新增段落;
- 没有整份取 ours/theirs——那样会静默丢弃另一边的记录。
执行过程中还踩到一个工具层面的坑:首次的保护器只接受"前置记录"而拒绝 WORKLOG 末尾的"追加",于是停在冲突态;检查后把保护器扩展为同时支持前置与追加,再继续。报告同时声明:未覆盖其它工作树。
从工程角度看,这是一个典型的"文档即产物"场景:AGENTS.md 是给 Agent 读的规则文件,WORKLOG 是时间顺序的运行记录,两者语义不同(前置 vs 追加),单一方向的冲突保护器必然误报。
四、最终行为:一个默认关闭的全局开关
4.1 位置与命名
- UI 路径:设置 → 兼容 → HDR 补帧闪黑兼容
- 偏好键:全局
hdrFgCompatibility - 默认值:首次启动及旧配置缺字段均为
false - 作用域边界:不进入增强列表预设、节点配置或导出设置
原报告只给出"默认关闭、跨重启保留"的行为描述,源码则把这条契约写死在三个层级。
第一层是引擎结构体,字段注释直接写明它是一个"全局 opt-in 兼容选择,永不进入增强预设"(PresentationSettings.h):
// Global opt-in compatibility choice; never part of enhancement presets.
bool hdrFgCompatibility=false;
第二层是偏好白名单。布尔型偏好在 Preferences.cpp 的 flags 列表里注册,hdrFgCompatibility 就在其中;不在白名单里的键会被 setPreference 直接拒绝,这条防线保证了不会有意外的写入路径。
第三层是 QML 控件本身(SettingsPage.qml):
VRow {
label: qsTr("HDR 补帧闪黑兼容")
hint: qsTr("默认关闭。仅 NVIDIA HDR10 补帧时生效;4K 额外约 32 MiB 显存,可能增加 GPU 开销。切换时画面可能短暂停顿。")
VSwitch {
objectName: "set-hdr-fg-compatibility"
checked: !!veyra.preferences.hdrFgCompatibility
onToggled: v => veyra.setPreference("hdrFgCompatibility", v)
}
}
注意 objectName: "set-hdr-fg-compatibility" 这行:它让 GUI 自动化测试能在真实 QML 树里按名字定位控件,而不是靠坐标点击。GUI 验收脚本正是用递归查找 objectName 的方式拿到这个开关的(hdr-fg-toggle-test.py)。
4.2 从开关到引擎:一次 requestPresentation
开关变更走的是"保存成功后立即生效"的同步路径,而不是延迟到下次打开视频(Preferences.cpp):
void QmlPlayerBridge::applyPreference(const QString& key) {
if(key==QLatin1String("hdrFgCompatibility")){
impl_->presentation.hdrFgCompatibility=impl_->prefBool("hdrFgCompatibility",false);
impl_->engine.requestPresentation(impl_->presentation);
emit presentationChanged();
}
...
启动时的恢复逻辑则在 presentation 配置块开头单独读取一次,位置在 presentation 子对象解析之前(QmlPlayerBridge.cpp):
auto& pr = impl_->presentation;
pr.hdrFgCompatibility = impl_->prefBool("hdrFgCompatibility", false);
if (!saved.isEmpty()) {
pr.enabled = saved.value(QStringLiteral("lowQueue")).toBool();
...
}
if (pr.valid()) impl_->engine.requestPresentation(pr);
这里有一个容易被忽略的设计细节:hdrFgCompatibility 存在偏好文件的顶层,而低延迟队列、显示同步、输出上限、可变刷新存在 presentation 子对象里。因此当 presentation 为空(全新配置或老配置从未写过该项)时,函数仍会先把 hdrFgCompatibility 读成 false,再因为 saved.isEmpty() 跳过整块 presentation 解析——默认关闭与"旧配置缺字段关闭"两条语义因此不会互相干扰。
五、生效条件:只有同时满足四个条件才走复制路径
这是整篇文章最需要读源码的部分。报告写的是"仅用户开启且为 NVIDIA HDR10 应用侧补帧才使用兼容复制;SDR、非 NVIDIA、无补帧与 XeSS 保留原路径"。落实到代码,就是一个四元组判定(VideoPresenter.cpp):
// Field 2026-10-09: HDR application FG flashes on an RTX5090 while the
// pixel-copy diagnostic does not. This is a compatibility candidate, not
// proof of a driver defect. Compose separately and copy the actual final
// image to DXGI; never retain the diagnostic's CPU readback or add sleeps.
copyEligible_=ctx.adapter().isNvidia&&graph.hdr10Output()&&graph.fgEnabled()&&bool(presentationQueue_);
// Opening a source never opts the user in or allocates the copy surface.
// configurePresentation applies the saved global choice on the GPU owner.
copyBeforePresent_=false;
逐项拆开:
| 条件 | 含义 | 不满足时的行为 |
|---|---|---|
ctx.adapter().isNvidia |
适配器是 NVIDIA | 非 NVIDIA 保留原路径 |
graph.hdr10Output() |
输出为 HDR10(PQ/BT.2020 10-bit) | SDR 保留原路径 |
graph.fgEnabled() |
补帧实际启用 | 无补帧保留原路径 |
bool(presentationQueue_) |
独立呈现队列存在 | 无独立队列时不可用(XeSS 走提供方自己的 Present,也不适用) |
两个布尔变量的语义被严格区分:copyEligible_ 表示"这条链路允许复制路径",copyBeforePresent_ 表示"当前实际走复制路径"。打开片源时 copyBeforePresent_=false,注释明确说明"打开片源永远不会替用户选择开启,也不会分配复制表面"。这与报告"默认继续直接呈现,没有额外兼容纹理或复制"一一对应。
真正的开关合成发生在 configurePresentation(VideoPresenter.cpp):
bool wanted=requested.hdrFgCompatibility&©Eligible_;
wchar_t copyOverride[4]{};
if(GetEnvironmentVariableW(L"VEYRA_TEST_HDR_PRESENT_COPY",copyOverride,4)&©Override[1]==L'\0'){
if(copyOverride[0]==L'0')wanted=false;
// Only bounded regression tests may force the copy path on SDR.
else if(copyOverride[0]==L'1'&&!sink_.xess())wanted=true;
}
if(wanted!=copyBeforePresent_){
// Switching is infrequent and runs on the presentation owner thread.
// Drain once before changing the target, never in the per-frame path.
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;
veyra::log::warn("present-copy","compatibility target setup failed; retaining direct presentation");
}
if(!copyBeforePresent_)compositeTarget_.Reset();
veyra::log::info("present-copy",std::format("requested={} eligible={} enabled={} (user preference; switch drains once)",requested.hdrFgCompatibility,copyEligible_,copyBeforePresent_));
}
}
这段代码包含四个可观察的行为:
wanted是"想要"与"可用"的与运算,用户开了但链路不满足时wanted=false,实际路径不变。- 切换只在
wanted变化时发生,且排空只在切换时做一次(never in the per-frame path)。 - 排空失败不强行切换,而是记
compatibility switch deferred并保持原路径,这就是报告说的"分配/排空失败有日志和实际 effective 值"。 - 关闭时立刻
compositeTarget_.Reset(),即报告"关闭释放额外合成纹理"。
最后日志与 effective 值一致化(VideoPresenter.cpp):
auto effective=requested;
effective.hdrFgCompatibility=copyBeforePresent_;
effective 反映的是真实生效的路径,而不是用户勾选值。所以当你在日志里看到 requested=true eligible=true enabled=true 与 requested=false eligible=true enabled=false 这两行时,说明"用户选择"已经在 GPU 所属线程上被正确换算成"实际路径"——这也正是验收脚本对 hdr / hdr-4k / vfg-4k 三种模式要求必须出现的关键断言(hdr-fg-toggle-test.py)。
六、复制路径到底做了什么,代价在哪里
6.1 合成目标与分配尺寸
复制路径不是"多画一张图",而是把最终合成目标从交换链后备缓冲换成一张私有纹理,再整张 CopyResource 到后备缓冲。目标纹理的创建与尺寸校验在 refresh() 内(VideoPresenter.cpp):
if(copyBeforePresent_){
auto desc=bb->GetDesc();
if(!compositeTarget_||compositeTarget_->GetDesc().Width!=desc.Width||...){
D3D12_HEAP_PROPERTIES heap{};heap.Type=D3D12_HEAP_TYPE_DEFAULT;
desc.Flags=D3D12_RESOURCE_FLAG_ALLOW_RENDER_TARGET;
...
const auto allocation=device->GetResourceAllocationInfo(0,1,&desc);
veyra::log::info("present-copy",std::format("composition allocation {}x{} format={} bytes={} surfaces=1",...));
}
}
surfaces=1 说明了"单张、固定复用"。报告给出的具体数字是 4K 实际分配 33,423,360 字节(31.875 MiB)——33,423,360 = 3840 × 2160 × 4,即一张 4 字节/像素的 RGBA16F 级别的合成面。UI 提示里"4K 额外约 32 MiB 显存"与之吻合。
注意 GetResourceAllocationInfo 的返回值被写进日志而不是被假定为理论值:实际分配可能因对齐、堆类型而高于理论字节数,报告选择"报实际值"而不是"报理论值"。
6.2 逐帧开销:一次渲染目标切换 + 一次整图复制
在 present() 里,复制路径的改变集中在三处。第一处是渲染目标选择(VideoPresenter.cpp):
auto* renderTarget=copyBeforePresent_?compositeTarget_.Get():bb;
...
D3D12_CPU_DESCRIPTOR_HANDLE rtv{rtvs_->GetCPUDescriptorHandleForHeapStart().ptr+size_t(copyBeforePresent_?3:backBufferIndex)*inc_};
RTV 描述符堆被扩到 4 个(3 个后备缓冲 + 1 个合成面),索引 3 就是合成面的位置。
第二处是屏障状态改写(VideoPresenter.cpp):
for(auto& b:barriers)std::swap(b.Transition.StateBefore,b.Transition.StateAfter);
if(copyBeforePresent_)barriers[1].Transition.StateAfter=D3D12_RESOURCE_STATE_COPY_SOURCE;
list->ResourceBarrier(2,barriers);
第三处是复制本身(VideoPresenter.cpp):
if(copyBeforePresent_){
D3D12_RESOURCE_BARRIER copy{};copy.Type=D3D12_RESOURCE_BARRIER_TYPE_TRANSITION;
copy.Transition.pResource=bb;...
copy.Transition.StateBefore=D3D12_RESOURCE_STATE_PRESENT;
copy.Transition.StateAfter=D3D12_RESOURCE_STATE_COPY_DEST;
list->ResourceBarrier(1,©);list->CopyResource(bb,renderTarget);
...
}
这就是报告"开启后每次显示增加 GPU 图像复制与屏障,可能增加带宽、GPU 耗时及满载时的延迟;不保证零开销"的实现依据。反之,关闭时这条分支整段不执行,也没有任何额外的 Wait、Sleep 或像素回读——报告"不增加逐帧 CPU 等待、像素回读、睡眠或新帧队列"是可以用这三个判定点直接核对的。
6.3 报告里的边界声明要照抄进你的验收结论
原报告在"最终行为"一节的结尾非常克制,值得逐字保留其语义:
- 开启只适用于 NVIDIA HDR10 应用侧补帧;
- SDR、非 NVIDIA、无补帧与 XeSS 保留原路径;
- 4K 实际分配 33,423,360 字节(31.875 MiB);
- 可能增加 GPU 带宽/耗时,切换可能短暂停顿;
- 没有做 OOM 压力测试。
这几句不是免责声明,而是给出了明确的"能说"与"不能说"边界。任何二次传播都不应把它升级成"HDR 闪黑已修复"——报告在末段明确写了"HDR 现场根因未确认"。
七、合并后的构建:只重编真实受影响的消费者
报告记录的实际命令是:
py -3.11 -B scripts/acceptance/hdr-fg-toggle-build.py --combined
这条命令的设计目标是"按 Ninja 头依赖重编 13 个生产消费者(其中 8 个 engine)、新翻译资源、2 个 BMD source 和各测试 fixture;GUI/原生/GPU 测试使用对应的新 engine/source 对象。只查询原缓存,不配置/运行 Ninja 构建;原 objects/lib/EXE/manifest SHA 保持"。
从 hdr-fg-toggle-build.py 可以看清它为什么可信:
- 它先
protect()把所有输入文件(.obj、.lib、build.ninja、CMakeCache.txt、原 EXE、manifest)记录 SHA,构建结束前逐项断言未变(for p,d in inputs.items():assert sha(Path(p))==d,p)。 - 它用
ninja -t deps找出真实依赖了被改头文件的.obj,并且断言数量下限:assert len(dependent)>=10。这条断言在合并轮就救了一次场(见下节)。 - 它用
ninja -t commands取回原始编译/链接命令行,替换/Fo、/Fd输出路径后在私有目录重编——即"复用缓存里的编译参数,产物写进新目录"。 - 翻译资源是可执行资源,因此脚本单独用
rcc.exe重新生成qrc_veyra_i18n.cpp并重编该.obj,注释写明"只替换 staged JSON 会让新设置有键无译文"。 --tests-only模式只重编 fixture 并断言 GUI 的 SHA 不变(assert sha(OUT/'veyra_qml_ui.exe')==guiSha),用于"仅修正测试、不动产品"的场景。
本轮构建结果:69.141 秒、exit 0,回执路径 E:/项目/Veyra/logs/hdr-fg-toggle-20261009/build-20261009-113817/receipt.json。
| 产物 | SHA256 |
|---|---|
| veyra_qml_ui.exe | 4e0f8193afbbbe7889ce019b25999d6af60f60e375d24aa774aed5fa85a0c0e9 |
| fg-presentation-tests.exe | 5b3391771177ce80b09de4b711a0dd6a618f07b3b6b940ae219ec19ea941ced9 |
| capture-contract.exe | 358782bab947a02a64d7669cc3b8987630b6d0023e4e6386f2898c360f9be429 |
| capture-gpu.exe | 18439d7ba53b89311113b5b0dc64a9d997b546e4098002587f645859a887b358 |
注意这四个 SHA 与上一轮 HDR 开关报告里的 GUI/native SHA 并不相同——因为这一轮是"合并 + 组合"构建,输入集合已经变了。不能用旧 SHA 的通过冒充当前验收,这也是报告在失败复盘里特意强调的一条。
八、定向回归:四类测试与它们的真实覆盖
环境为 RTX5070 / 616.56,同一私有 app,测试串行,无竞争/压力负载。实际命令是 py -3.11 -B scripts/acceptance/hdr-fg-toggle-test.py 加上不同模式参数:
| 参数 | 实际结果 |
|---|---|
| capture merged-contracts-final contracts | 261 项、0 失败,0.032 秒 |
| capture merged-pixels-v2 pixels | 124 项 GPU 检查,HDYC 两方向与 UYVY BT709 相同,3.422 秒 |
| native merged-hdr-toggle hdr-4k | 512 原帧/620 生成帧、94 次窗口无损对照、最大 10-bit RGB 误差 0、D3D12 错误 0,18.859 秒 |
| gui merged-settings restore-off | 真实 QML/bridge 恢复关闭、保存/其它显示设置保持、无错误,7.922 秒;稳定设置页截图已查看 |
四个参数分别覆盖不同的风险面:
capture ... contracts——采集契约的负例。脚本对这批测试采取的是"精确计数豁免"而不是"整类忽略"(hdr-fg-toggle-test.py):先要求两类预期错误行出现精确次数(各 1 次与 5 次),再要求四条"PASS 拒绝…"断言出现精确次数,只有同时成立才把这些负例从错误扫描里剔除。
capture ... pixels——GPU 像素路径。要求 BLACKMAGIC_HDYC_GPU flip=[01] identical709=1.*pass=1 恰好匹配两次(HDYC 两个方向),并额外统计 PASS BMD source pixels delivered exactly 两次、failures=0。
native ... hdr-4k——HDR 呈现回归。HDR 覆盖了默认关闭、启用→关闭→再启用、窗口/全屏、resize/reset/销毁;4K 是交换链缓冲,源 fixture 为 640×360 P010,报告明确"不冒充 4K NR 或真实 HDR 屏幕验收"。这条限定非常关键:测试放大的是输出缓冲,不是源分辨率。
gui ... restore-off——真实 QML/bridge 偏好持久化。脚本通过 --data-dir 指定私有配置目录、--page set 直接落到设置页,注入一段 QML Timer 遍历控件树:先断言当前状态等于期望值,再调用 sw.toggled(TOGGLE) 走真实信号,随后写一个无关偏好(veyra.outputCustomFps = 61)来验证"其它显示设置不会擦除这个全局选择",最后打印 HDRGUI_PASS。校验侧还要求偏好文件里 hdrFgCompatibility 等于期望值、哨兵键 sentinel 仍为 preserved、且截图文件存在。脚本注释也很诚实:"测试调用真实组件 toggled 信号,不冒充人工鼠标点击。"
原生回归的断言强度来自 fixture 本身。HdrCopyPresentationFixture.h 会遍历 {1,2,4,2} 倍率 × {窗口, 全屏},在每轮里执行 applyCompatibility(false) → true,然后在第 16/32 帧再各切一次,并用 effective.hdrFgCompatibility==(enabled&&desc.enableFg) 校验"选择被正确换算":
const auto applyCompatibility=&{
requested.hdrFgCompatibility=enabled;
const auto effective=presenter.configurePresentation(ctx,requested,desc.enableFg,text);
return overridden||effective.hdrFgCompatibility==(enabled&&desc.enableFg);
};
它还做真正的 10-bit 逐像素对照:readHdrWords() 把实际呈现的后备缓冲与图输出纹理分别回读到 CPU,逐通道算绝对值误差并断言 maxError<=1。注释同时说明这个回读"仅属于受限集成测试,播放路径既不用这个 helper 也不用全图 CPU 等待"——这正是报告"正常 GUI 不含像素探针"的落地方式。
九、失败保留:三个真实踩坑与它们的修法
报告专门留了一节记录首次组合检查的失败,这一节比"全绿"结论更有工程价值:
-
契约 fixture 主动制造 6 条拒绝错误,却被通用日志扫描判为失败。 修法不是"忽略 ERROR 行",而是同时核对准确日志次数与相应 PASS 拒绝断言,只对这些预期负例开豁免。这条设计原则可以推广:负例测试的错误必须被"确认为已知负例",而不是被"错误扫描器无视"。
-
GPU fixture 首次漏链接新版
VideoPresenter,混用旧类实现而访问违规。 根因是测试链接时使用了缓存里的旧engine对象。修法是把全部受影响 engine 对象都换成本轮重编产物。构建脚本注释直接点明这类风险(hdr-fg-toggle-build.py):HdrColorTestsconstructs VideoPresenter directly, so it must receive the same updated engine objects as the GUI, not the cached class implementation.这是个通用的 C++ 陷阱:直接构造被测类的测试,链接时必须与产品共享同一批对象,否则会出现"同一符号、两个实现"的 ODR 级错配。
-
构建脚本一次"4 个 engine"的计数假设,在链接前被保护断言拦下。 脚本里有一条看起来"死板"的断言:
assert sum(p.stem in ('VideoPresenter','EngineController','EngineControllerImage') for p in core)==3,core assert any(p.stem=='PreviewGpuSession' for p in core),core实际依赖集合变化后,这条断言在链接前就失败,避免了一个"少换一个对象"的静默错误。
还有一个流程层面的收尾:第一次契约回执对应重链接前的 EXE,最终又对实际最终 EXE 重跑,报告明确"不用旧 SHA 的通过冒充当前验收"。
报告另有一句容易被略过的说明:scripts/gates/delivery.ps1 明确只接受 legacy UI,本次没有用它替代 QML 定向验收;也没有宣称新一次全功能、AMD、采集卡现场或长稳验收。这是对"门禁工具适用范围"的正确认知——工具不是越严格越好,而是要匹配被测对象。
十、保全与边界:这份报告为什么可复核
合并类工作最容易出问题的地方不是代码,而是"我动了什么、没动什么"。报告用三层证据把这件事锁住:
开工不可变基线:archives/hdr-fg-toggle-20261009/start.json 覆盖 39 个工作树、495 个脏文件;除获授权的 FG 与 main 之外,其余 37 个工作树受保护。
checkpoint 三点位:checkpoint/pre-merge-field-fixes-20261009、checkpoint/merged-field-fixes-20261009、checkpoint/hdr-fg-toggle-validated-20261009。三个点分别对应"合并前""合并后""开关验证后",任何回归都能定位到阶段。
产物与目录约定:新产物统一在 E:/项目/Veyra/{build,tests,logs,tmp,reports,archives}/hdr-fg-toggle-20261009;只保留一个共享私有 app(依赖硬链接,EXE / Main.qml / SettingsPage.qml 为独立副本)、当前构建和必要成功/失败证据,没有制作新的整套便携包。
donor 文件守恒:1614 项 donor 文件逐项 SHA 前后不变;正常 GUI 未引入诊断探针;源码合并没有 DLL/SDK/模型/媒体或其它二进制变更。
报告还特意声明了一个会计口径:closure.json、preservation-final.json 中的"逻辑字节含硬链接,不冒充实际新增磁盘占用或卷空间变化"。这类细节决定了保全数据能不能被第三方复算——硬链接会让"逻辑大小"与"磁盘增量"分离,混用两者会得出错误的体积结论。
现场诊断入口不是产品路径
报告提到"两个现场启动器实际各运行 15 秒,Compatible/Direct 分别写私有偏好 true/false,exit0、未强停、原配置 SHA 保持、ZIP CRC 通过"。对应的脚本是 Start-HDR-Flash-Fix.ps1,它的关键设计有三点:
[ValidateSet('Compatible','Direct')][string]$Variant = 'Compatible'
...
$prefs | Add-Member -NotePropertyName 'hdrFgCompatibility' -NotePropertyValue ($Variant -eq 'Compatible') -Force
...
# Exercise the same saved setting as Settings > Compatibility, with no
# environment override. Only this private configuration is changed.
[Environment]::SetEnvironmentVariable('VEYRA_TEST_HDR_PRESENT_COPY',$null,'Process')
- 写的是与设置页同一个布尔键,不是环境变量强制——报告原话是"移除环境强制;正常设置不依赖环境变量";
- 只改私有 profile 副本,并记录被复制文件的 SHA,结尾若发现源 profile 变化就直接抛错(
if (-not $unchanged) { throw ... }); - 保持原 EXE 文件名,注释说明"改文件名可能绕过 NVIDIA App/RTSS 的按程序配置"。
环境变量 VEYRA_TEST_HDR_PRESENT_COPY 只作为回归测试的有界覆盖保留在 configurePresentation 里,且 '1' 分支还加了 !sink_.xess() 限制,避免在提供方自有 Present 的链路上强行开启。
十一、明确未验证的部分
报告末段列出的边界,应被视为这篇文章的一部分而不是附注:
- HDR 现场根因未确认,RTX5090 尚未回测当前兼容开关;
- BMD 实卡黑屏、AMD/BMD 联用及屏幕端到端延迟尚未验证;
- NVIDIA 显存持续增长仍未定位;
- 不能将这些"本机定向通过"称为现场问题根治;
- 版本仍沿用 2.0.6 / VFG 本地基底,未推送、未发布、未更新 Release。
把这几条与 docs/history/plans/HDR_FG_COMPAT_TOGGLE_PLAN_2026-10-09.md 里的验收清单对照会发现二者一致:计划阶段就写明"BMD 实卡黑屏/延迟、5090 现场闪黑及显存增长根因仍未验,不能由本轮开关测试宣称已解决"。计划与报告在边界上的自洽,是这份材料可信度的重要来源。
十二、如果你要复现这套流程
把这一轮的做法抽象成可复用步骤,大致是:
- 先定基线:记录合并前提交、工作树路径、受保护工作树与脏文件清单;打
pre-mergecheckpoint。 - 按分支性质分级合并:诊断类分支只允许脚本/头文件/记录进入;产品类分支用
--no-ff保留来源。 - 冲突只允许追加:三阶段解析 + "完整旧正文必须逐字存在"断言,禁止整份取 ours/theirs。
- 把候选修复降级为显式选择:结构体字段默认
false、注释写明"不进入预设"、偏好白名单注册、QML 控件带objectName便于自动化。 - 用 effective 值而非请求值做校验:
effective.hdrFgCompatibility=copyBeforePresent_,日志同时打印requested/eligible/enabled。 - 构建只重编真实依赖:
ninja -t deps找消费者、ninja -t commands复用参数、输入 SHA 全程保护、i18n 用rcc重新生成、测试与产品共享同一批 engine 对象。 - 回归分层且各有断言:契约负例精确计数豁免、GPU 像素逐位对照、HDR 交换链多次开关 + 窗口状态变化、GUI 走真实信号并校验偏好文件与哨兵键。
- 区分"通过"与"根治":把未验证项逐条写在结论旁边,而不是留在口头。
这套流程的核心不是某条命令,而是"每个结论都要有可复算的证据"。报告之所以能同时说清"合并保留了原作者提交""开关默认关闭且可跨重启""4K 复制面 31.875 MiB""根因仍未确认"这四句看似矛盾的话,正是因为它把提交拓扑、源码路径、分配字节、测试断言、未验证边界分别落到了不同的证据上,而不是揉成一句总结。