Veyra-NRVideo 帧生成施工全景:DLSS 6X、XeSS MFG 解锁、AMD FSR 接入与杜比位流探测
Veyra-NRVideo 帧生成施工全景:DLSS 6X、XeSS MFG 解锁、AMD FSR 接入与杜比位流探测
本文以仓库内的施工状态报告 docs/history/reports/FRAMEGEN_FSR_DOLBY_STATUS_2026-09-16.md 为主线,梳理 Veyra-NRVideo 在一次版本迭代中同时推进的四条技术线:NVIDIA DLSS 多帧生成(6X)的能力驱动倍率、Intel XeSS 多帧生成(MFG)的进程内解锁与节奏 hook、AMD FidelityFX FSR 帧生成的独立接入,以及采集卡杜比/DTS 位流能力探测与解码保底。读完后你应当能够:读懂每条技术线的验收命令与期望日志、理解"能力上限 / 请求倍率 / 实际出帧数"三者之间的工程约束,并知道哪些结论属于已实测、哪些仍属于未验证边界。
一、施工基线与阅读方式
该报告是一份"给人工验收/继续施工用"的状态快照,其定位非常明确:它不是功能介绍,而是证据索引。报告开头即声明已合并到 main(merge 24e7de7)、未推送、未发布,并给出整套存档点与提交链。
| 项 | 值 |
|---|---|
| 存档点(main) | 693db07,tag checkpoint/pre-framegen-fsr-dolby-2026-09-16 |
| 施工分支 | codex/framegen-fsr-dolby-20260916 |
| 关键提交链 | 35dd632(DLSS 6X)→ 4124a9d(XeSS MFG)→ ef0fb50(FSR 探针)→ 27656a6(FSR 帧生成接入)→ 950f46d(FSR 超分)→ 9179449/aa168ab(40 系解锁)→ 4154733/3dd5add(30 系解锁)→ ef016ba(A-2 节奏 hook)→ 56bb0f6/275c3f2(杜比解码/直通)→ 015f8a4(PS5+RGB24 修复)→ d5f7383 |
| 计划文档 | FRAMEGEN_FSR_DOLBY_PLAN_2026-09-16.md |
| 合并存档 | 前 checkpoint/pre-merge-framegen-20260916、分支 tip checkpoint/framegen-fsr-dolby-branch-tip-20260916、后 checkpoint/merged-framegen-20260916 |
| delivery 短测 | 多次 23/23 通过,分支 tip 最近一次 45aefe5dcbdc44f79ecba8167b83f1f0,位于 logs/delivery/ |
这类文档的真正用法是:先看提交链定位代码,再看实测数字判断可信度,最后看"未完成"表格决定下一步。报告本身也提示 EXE 哈希会随 PE 时间戳漂移(无 /Brepro),因此哈希不作为冻结项,最终门禁数字以 docs/WORKLOG.md 顶部条目为准。
二、DLSS 6X:把"倍率"变成能力驱动的运行时决策
2.1 资源与数据结构的扩容
6X 意味着每两个真实帧之间插入五张生成帧,这首先不是一个 UI 问题,而是池容量问题。报告记录的第一组改动全部落在显存与批次结构上:
- 生成帧池 3→5/parity(
kGeneratedPoolSlots=10) FrameBatch4→6interpolate上限 6- present SRV 堆 8→12
- DLSSG 后端
multiFrameCount上限 3→5 validate()允许范围 1..6
这些常量在今天仓库中的形态已经演化,但推导关系仍然可读。include/veyra/pipeline/EnhanceGraph.h 现在写成"每个 (parity, subframe) 一张生成纹理,最多七张子帧即 8X":
// One generated texture per (parity, subframe), through seven subframes at 8X.
// Each backend keeps its own supported multiplier and resource requirements.
inline constexpr unsigned kGeneratedPoolSlots=2*(FrameBatch::Capacity-1);
inline constexpr unsigned kOutputPoolSlots=2+kGeneratedPoolSlots;
公式 2*(Capacity-1) 正是报告里"5/parity、共 10 槽"的一般化形式:include/veyra/pipeline/FrameBatch.h 当前 Capacity=8,代入即得 kGeneratedPoolSlots=14(对应 8X 路径)。批次本身用 interpolate(a,b,j,n) 计算等时间间隔的中间帧 PTS,并显式拒绝 n<2||n>Capacity 与超过 1 秒的连续端点间隔——这就是"interpolate 上限 6"的实现位置:
static int64_t interpolate(int64_t a,int64_t b,uint32_t j,uint32_t n) {
// The application accepts at most one second between continuous endpoints.
if(n<2||n>Capacity||j==0||j>=n||b<=a||a>INT64_MAX-10000000||b>a+10000000)
throw std::invalid_argument("invalid interpolation interval");
const int64_t d=b-a;return a+(d/n)*j+((d%n)*j+n/2)/n;
}
append() 还会拒绝跨代(identity 不一致)或 PTS 非单调的帧,这条约束在验收时表现为"批次不合法"而不是"画面异常",属于能在日志层提前暴露的设计。
2.2 能力驱动倍率:UI、请求、后端三层分别把关
报告强调的第二个改动是能力驱动倍率(capability-driven multiplier),它由三层组成,缺一层就会出现"标 6X 实际 2X"或"补帧整档被关掉":
- UI 层:只给出运行时上报的上限内的选项。今天的实现见 src/ui/bridge/FrameGeneration.cpp,
fgMaxMultiplier()把"生成帧数"换算成"总倍率",即clamp(max+1, 2, 6):
if (s.fgCapabilityKnown && s.fgMultiFrameMax > 0) return std::clamp(s.fgMultiFrameMax + 1, 2, 6);
return 6;
fgMultiplierChoices() 再按后端截断(XeSS 走 std::min(fgMaxMultiplier(), 4)),注释写得很直白:提供一个 provider 会拒绝的值,"和给一个死控件是同一种撒谎"。
- 请求层:超上限的请求被明确拒绝并保留原值,而不是让图创建失败。src/engine/EngineController.cpp 的能力门就是这一条:
if(s.multiplier>1&&s.frameGenerationBackend==FrameGenerationBackend::Dlss&&fgMultiFrameMaxCap_>0&&
int(s.multiplier)-1>fgMultiFrameMaxCap_){
snapshot_.status=std::format(L"此显卡最多支持 {}X 帧生成;请求未应用",fgMultiFrameMaxCap_+1);
snapshot_.failed=false;
veyra::log::info("settings",std::format("multiplier gate: requested={} maxGeneratedFrames={} applied=unchanged",s.multiplier,fgMultiFrameMaxCap_));
return false;
}
注意 snapshot_.failed=false:拒绝一次设置不是引擎故障,这个区分让 UI 能在不改状态的前提下显示原因。
- 后端层:真正创建 DLSSG 时仍要再校验一次,失败则按上限降级并提示,而不是把补帧整档关掉。src/pipeline/EnhanceGraph.cpp 同时容纳了正常门与仅测试用的强制门:
const bool forceAboveCapability=GetEnvironmentVariableW(L"VEYRA_TEST_FG_FORCE_MULTIPLIER",nullptr,0)>0;
const bool aboveCapability=desc_.enableFg&&fgCaps.multiFrameCountMax<desc_.fgMultiplier-1;
if(aboveCapability&&forceAboveCapability){
veyra::log::warn("capability",std::format("test-only FG multiplier forced above capability request={} maxGeneratedFrames={}",desc_.fgMultiplier,fgCaps.multiFrameCountMax));
}
if(desc_.enableFg&&(desc_.fgMultiplier<2||desc_.fgMultiplier>6||(aboveCapability&&!forceAboveCapability))){
veyra::log::error("graph",std::format("requested MFG multiplier unsupported request={} maxGeneratedFrames={}",desc_.fgMultiplier,fgCaps.multiFrameCountMax));return false;}
对应地,src/engine/EngineController.cpp 的重建路径会打印报告里引用的那句降级日志:requested multiplier {} exceeds GPU capability maxGeneratedFrames={}; applying {}X with frame generation kept。
2.3 实测数字与它们的含义
报告给出的 6X 实测环境是 RTX 5070 / 驱动 616.56 / DLSSG 310.7.0.0:
| 场景 | 关键日志 | 计数 | 退出码 |
|---|---|---|---|
--fg-multiplier 6 |
FG capability available=true multiFrameMax=5、fg=1 |
445 真帧 / 2215 生成帧(每帧 5 张) | 0 |
模拟 40 系上限 VEYRA_TEST_FG_MULTIFRAME_MAX=1 |
requested multiplier 4 exceeds GPU capability maxGeneratedFrames=1; applying 2X with frame generation kept |
312 真帧 / 310 生成帧 | 0 |
这里有个容易误读的点:multiFrameMax=5 表示"每真实帧最多 5 张生成帧",也就是 UI 上的 6X。报告在另一处计划文档里把它写清了——MultiFrameCountMax 是生成数,不是总倍率。测试矩阵为:veyra_ui_contract_tests PASS、veyra_repair_contract_tests 146 项 0 失败(新增 5X/6X 合法、7X 拒绝)、veyra_repair_preset_tests 48 组 PASS、scripts/gates/delivery.ps1 23/23 PASS。
VEYRA_TEST_FG_MULTIFRAME_MAX 是一个仅测试变量,源码里注册在能力查询之后、日志之前(src/pipeline/EnhanceGraph.cpp),取值范围被限制在 0..5,并且明确注释"Never set by the product UI"。它存在的唯一理由是:让 50 系主机在不改运行库的前提下,验证 40 系上限下的 UI 与恢复路径。
三、XeSS MFG 解锁:五处字节补丁与事务化安装
3.1 移植来源与安全模型
XeSS 的官方多帧生成在非 Intel GPU 上是 2X,3X/4X 属于"实验解锁"。报告的改动项是新增 include/veyra/gfx/XessMfgUnlock.h 与 src/gfx/XessMfgUnlock.cpp,移植 OptiScaler(GPL-3.0,固定提交 70676c5f)的五处字节补丁(U1–U5),并加上 Veyra 自己的安全约束:
- 只改进程内已映射的镜像,不写磁盘、不改签名、不改文件名;
- 补丁前校验模块身份:大小 + SHA-256 + PE
TimeDateStamp/SizeOfImage,并逐处校验原始字节; - 全部位置先验证再写入,写入后回读校验,失败即回滚;
- XeFG/XeLL 上下文销毁后恢复原字节。
审计身份被硬编码为常量,这是"拒绝不猜"的具体形态:
// Audited provider identity (Intel libxess_fg.dll 1.3.1.78 shipped with Veyra).
static constexpr uint64_t kKnownProviderSize = 22957432ull;
static constexpr const char* kKnownProviderSha256 =
"EC5E0C65E075570C6EDE72618BB666D0BE0C2E10B2EA9762C0FE8CB8E375AB27";
static constexpr uint32_t kKnownTimeDateStamp = 0x69CB0F4Du;
static constexpr uint32_t kKnownSizeOfImage = 0x015ED000u;
同一个头文件还定义了 providerIsAudited():只读地检查磁盘上的 provider 是否就是这套字节表适用的构建,因此设置界面可以在会话尚未运行时就能决定要不要给 3X/4X 选项。
3.2 Presenter 侧的真实上限查询
解锁只是第一步,真正让 3X/4X 生效需要 Presenter 查询运行库上限并调用 setter。报告记录 XessPresenter 现在加载 xefgSwapChainGetProperties / xefgSwapChainSetNumInterpolatedFrames,src/gfx/XessPresenter.cpp 展示了完整顺序:先算 requestedGenerated = fgMultiplier-1,2X 时故意什么都不做,>2X 才 apply 解锁并安装节奏 hook:
p.requestedGenerated=fgMultiplier>1?fgMultiplier-1:0;
// 2X is the provider's stock behaviour: no unlock, no pacing, and the
// presenter must not treat "nothing to unlock" as a failure (that used to
// drop the whole XeSS session back to native presentation).
if(p.requestedGenerated>1){
const auto unlock=XessMfgUnlock::apply(p.fgDll,p.requestedGenerated);
...
if(!unlock.applied){ ...; return false; }
if(GetEnvironmentVariableW(L"VEYRA_DISABLE_XESS_PACING",nullptr,0)==0){
const auto pacing=XessPacing::install(p.fgDll,p.requestedGenerated);
上下文创建后再用 xefgSwapChainGetProperties 取 maxSupportedInterpolations,并把结果 reportRuntimeCeiling() 回写给设置层,最后用 SetNumInterpolatedFrames 落实请求(src/gfx/XessPresenter.cpp)。这段"查询在前、设置在后、请求高于上限即失败"的顺序,正是报告里"查询真实上限、设置 init.maxInterpolatedFrames 并调用 setter"的代码级还原。
3.3 UI 上限:为什么不能"会话一结束就收回 4X"
这是一个很典型的工程陷阱,报告表述为"UI 只在审计版运行库存在或会话已上报 >2X 时给出 XeSS 3X/4X"。今天的实现把它写成了更严谨的不变量(src/ui/bridge/FrameGeneration.cpp):
int xessCeiling(const engine::PlayerSnapshot& s) {
static const bool audited = gfx::XessMfgUnlock::providerIsAudited(
(runtime::localDataDirectory() / L"intel" / L"experimental" / L"libxess_fg.dll").wstring());
int cap = audited ? 4 : 2;
// A running context reports the count it was CREATED with (3X -> 2), not
// what the provider allows: it may raise the ceiling, never lower it.
static int seen = 0;
if (s.xessMaxInterpolatedFrames > 1) seen = std::max(seen, std::clamp(s.xessMaxInterpolatedFrames + 1, 2, 4));
return std::max(cap, seen);
}
关键洞察写在注释里:一个已创建的上下文上报的是它被创建时的插值数,用 3X 创建的上下文会报 2,如果直接用它当上限,4X 会在"先选 3X"之后从菜单里消失。所以这个上限只允许上调、不允许下调。这类细节如果不写下来,下一次重构几乎必然重犯。
3.4 实测证据
| 项 | 值 |
|---|---|
DLL 审计(随包 runtime_local/intel/experimental/libxess_fg.dll) |
1.3.1.78 / 22,957,432 字节 / SHA-256 EC5E0C65…AB27;TimeDateStamp 0x69CB0F4D、SizeOfImage 0x015ED000 |
| 五处原始字节 | U1–U5 全部匹配 |
--fg-xess --fg-multiplier 4(RTX 5070) |
maxInterpolatedFrames=3 unlockApplied=true => maxMultiplier=4、framesPresented=4、563 真帧 / 1677 生成帧、exit 0 |
| 退出行为 | unlock rolled back 5/5 patch(es) |
563 / 1677 的比例(约 1:3)与 framesPresented=4 一致,是"总倍率 4X"的自洽证据;rolled back 5/5 则是"进程内存修改、退出即恢复"的直接证明。第三方归属已按 GPLv3 义务登记在 THIRD_PARTY_NOTICES.md(含固定提交与 Magpie 结构参考)。
四、XeSS 节奏 hook(A-2):接管一个五字节 thunk
4.1 为什么 3X/4X 需要 hook
上游提供方"只调度一个 burst 的最后一帧",于是 3X/4X 下中间帧被背靠背 present,观感是"一簇 + 一段空档"。要修这个问题只能进入提供方内部调度器。报告为此先落地了通用 detour 基础设施,再按勘察坐标移植上游 XeFGPacing.h。
4.2 ThunkHook 的工作方式
include/veyra/ThunkHook.h 的设计说明值得完整理解:它只 hook "五字节 E9 rel32 + 0xCC 填充"这种规范跳转 thunk,因为可 hook 区域只有一条指令,不需要反汇编器、也不会切断指令边界;形状不符一律拒绝而不是猜。
// Requires target[0] == 0xE9 and `paddingBytes` 0xCC bytes after the jump.
// The replacement may live anywhere: the hook builds a nearby page holding
// an absolute-jump stub to the replacement plus the trampoline that
// continues to the original target.
Status install(void* target, void* replacement, size_t paddingBytes = 11);
实现层面(src/base/ThunkHook.cpp)分三步:校验 opcode 与逐字节填充;解析 rel32 得到原始目标;在目标 ±2GB 内扫描分配一页可执行内存(allocateNear,64KB 步进向外扩),页内放两个绝对跳转桩——trampoline 指回原目标、entry 指向替换函数。这样替换函数可以住在任意地址,不受 rel32 限制。写入走 writeVerified():VirtualProtect → memcpy → FlushInstructionCache → 恢复保护属性 → memcmp 回读校验。
单测(veyra_repair_contract_tests,报告当时 154 项 0 失败)覆盖五条契约:thunk 能到达原函数、安装 hook、替换函数执行并经 trampoline 转发、移除后恢复、非 thunk 目标被拒绝。
4.3 施工坐标表
报告给出的这张表是"下一轮可直接移植"的关键资料,也是本文最有检索价值的部分之一(针对 libxess_fg.dll 1.3.1.78 审计构建):
| 项 | 值 |
|---|---|
| Present thunk | RVA 0x25C0(jmp 0x21F730,后接 11 字节 0xCC 填充) |
| 原生 present 目标 | RVA 0x21F730 |
| 调度 thunk | RVA 0x3100(→ 0x21EE30) |
| 每帧间隔计算点 | RVA 0x220254(count=[r8+8]、div rcx、结果存 r12) |
| burst 循环 / 最后一帧调用 | RVA 0x2202E8(循环内);0x220462(最后一帧,arg7=0,入口 0x220467) |
| 限流块触发条件 | RVA 0x220317:[rsi+0x340]!=0、[r8+8]>2、[r8+0x28]==0 |
| 上下文偏移 | LimiterEnabled=0x340、SchedEnable=0x341、BurstGate=0xC0、Ring=0x168、BurstLimiterField=0x28 |
| ring 快照函数 | RVA 0x224CF0(经 0x4DA0 调用;调用点 0x22023D..0x22024B) |
| 上游实现要点 | 需要重建 present 调用的参数(上游用 1500 字节 helper 0x3F570);全局时序变量需按上下文管理;hook 回调不得抛异常或做大分配/同步日志 |
这些坐标在仓库中以具名常量固化,便于"结构不匹配就拒绝":include/veyra/gfx/XessPacing.h 把 kPresentThunkRva、kSchedFnRva、kBurstGateOffset 等一并声明,并附上同一份审计身份(大小/SHA-256/PE 标识),同时明确"2X 永不安装任何东西"。
4.4 实测与未移植部分
4K/30fps 素材 4X 实测(提交 ef016ba):refused=0、同一 burst 内间距 mean≈8.303ms(目标 33.33/4 = 8.33ms)、min≈8.14ms、max≈8.42ms,339 真实 / 1005 生成、exit 0。关掉 hook 的对照组里 4X 完全没有调度发生——这条对照比均值本身更有说服力,它证明了 hook 是生效条件而不是巧合。同一轮还顺带修掉了"XeSS 2X 静默退回原生呈现"的 bug(修后 280 真实 / 276 生成)。
报告同时明确未移植:上游的时间戳/截止时间层与墙钟回退。THIRD_PARTY_NOTICES.md 的表述与此一致——Veyra 保留自己的审计调用点 hook、增加同步统计与完整 gap 测量,但不移植上游时间戳 hook;只有提供方调度器不可用时才使用墙钟节流(有界 15 周期中位数)。诊断用变量是 VEYRA_DISABLE_XESS_PACING。
五、RTX 40/30 系的 DLSS MFG 解锁:两道架构门 + 一个中点修正
5.1 为什么"只改一处"会黑屏
include/veyra/ngx/AdaMfgUnlock.h 的注释把这个坑写得很清楚,值得逐条记住:
DLSSGInstanceManager::PopulateParameters把 NVAPI 架构 id 与0x1b0(Blackwell)比较,决定上报的MultiFrameCountMax;- 第二处对同一常量的比较驱动真正的能力标志——只补第一处会渲染黑屏;
- 插值 kernel 用编译期常量 0.5 混合,所以每张生成帧都落在时间中点(表现为"帧重复")。修法是把 PTX 解压、把 104 处中点乘法替换为 kernel 自己的时间参数,然后在该 PTX 条目后截断 fatbin,让驱动走 JIT 而不是加载预编译 cubin;
- DLSS-G 提供方的 count/index validator(移植自 dashdogy/RTX40MFG-Unlock v1.3.3)按运行时检测的架构限制
numFramesToGenerate,缺了它 Ada 会"声称支持多帧但拒绝生成第二张"。
5.2 三段哈希身份链
报告记录的三个场景(原版 apply/readBack/restored=1/1/1;篡改 fatbin 1 字节 → 干净拒绝+完整回滚;篡改 gate 模式 → 预检拒绝)背后是一条可复现的哈希链,在头文件里被固化为常量与"发布闸":
static constexpr const char* kExpectedSourceFatbinSha256 =
"5A8E0284AAB8AC14FC82B0504BBEEF25D2FCE1D13A1C11D8BDB3F91FEE8145FC";
static constexpr const char* kExpectedSourcePtxSha256 =
"46C05996A2EF199BBE39378681734ED5EE757655DE70410D9900D85BA91222F1";
static constexpr const char* kExpectedRebuiltFatbinSha256 =
"19FB3CD5500BFD1FC88F96C36B381E096D6AB1DFC7B1DB02A04D40A00849104B";
配置为 source fatbin (98408 B) → PTX (99362 B) → rebuilt fatbin (127200 B),重建结果的摘要与上游逐位一致才允许重定向描述符,否则整体回滚。安全规则同样硬编码:Blackwell 上永不应用(50 系走原生路径)、架构门站点数或 PTX 结构不符即拒绝并记录原因、kExpectedMidpoints = 104、kExpectedMfgGateSites = 1。
报告里还有一条很容易被忽略的修复:原版回滚路径会写只读页而崩溃,Veyra 的移植在回滚时一并修掉了这个问题。这类"只在失败路径上出现"的 bug,恰恰是"篡改 1 字节"这种负例测试的价值所在。
5.3 30 系的 sm_86 重建
30 系走的是更重的路径(提交 4154733 + 3dd5add)。include/veyra/ngx/AmpereMfgUnlock.h 说明了结构:提供方内嵌 69 个 fatbin,其中 25 个是 DLFG 程序槽(dlfg_kernel/main_kernel,各含一个 sm_89 PTX 条目),被 8 张 25 项 × 48 字节的注册表引用(8×25 = 200 槽指针);另有 38 个网络 + 6 个辅助 fatbin(44 处 LEA 引用)被清点。只有 25 个注册程序与被哈希识别的字体程序被重建,网络程序保持不动,字体原地替换以保住全部引用;架构门 0x1b0 → 0x170,其余不改。
产品接入方式是"在 FG 能力查询前自动应用,仅 RTX 30 窗口触发";provider 在 30 系仍报 FG 不可用(Ada/Blackwell 门控),当审计版解锁已安装时宽限继续,并把缺失的 MultiFrameCountMax 补为审计上限 5(显式更小的报告值仍被尊重)。probe 全周期 applied=1 readBack=1 restored=1。报告同时标注上游自述该路线"very early and experimental",属于应当如实转述的边界。
六、杜比 / DTS:先证明设备有没有位流,再谈直通
6.1 G-1:能力探测先于功能实现
报告在这一节的价值不在于"实现了 Atmos",而在于用一次实测否证了一个不可达目标。CaptureCardSource 现在会分类压缩音频 subtype 并输出每设备汇总行,实测结果为:
device bitstream types=0 [none] pcmTypes=15
即这张参考采集卡在硬件层就不提供任何杜比/DTS 位流,因此"支持 Atmos"在当前设备上不可达;位流直通必须先换支持位流的采集设备,或改走 HDMI 直通链路。
分类表在源码中是显式的 GUID Data1 映射(src/source/CaptureCardSource.cpp),与 src/sink/BitstreamAudio.cpp 的分类函数一一对应:
| subtype Data1 | 名称 | 归类 |
|---|---|---|
0x00000092 |
AC-3(SPDIF) | AC-3 |
0x00002000 |
AC-3(WAVEFORMATEXTENSIBLE) | AC-3 |
0x0000000A |
E-AC-3 / DD+ | E-AC-3 |
0x0000010A |
E-AC-3 / DD+ Atmos | E-AC-3 |
0x0000000C |
TrueHD / MLP(Atmos over TrueHD) | TrueHD |
0x00000008 |
DTS | DTS |
0x0000000B |
DTS-HD | DTS-HD |
0x0000010B / 0x0000030B |
DTS:X(扩展 1 / 2) | DTS-HD |
汇总行的构造位置在 src/source/CaptureCardSource.cpp,且每一条 subtype 命中都会单独打一行 (passthrough candidate)。这让"设备不支持"和"我们没尝试"在日志层可以区分——这是排障时最需要的那条信息。
6.2 G-2:解码保底与优先级
报告把 G-2 记为"解码保底已实现并本地验证(56bb0f6)":FFmpeg 解码 AC-3/E-AC-3(含 DD+ Atmos 载体)/DTS/DTS-HD,IEC 61937 解框;采集端在无 PCM 可用时按优先级走位流直通并解码进既有 5.1 管线,本地用真实 AC-3/E-AC-3 位流验证了 6 声道与幅度映射。
优先级是显式排序的,bitstreamPreferenceOrder() 给出 TrueHD(60) > E-AC-3(50) > DTS-HD(40) > DTS(30) > AC-3(20)(src/sink/BitstreamAudio.cpp)。IEC 61937 的帧结构也在同一文件里被定义为常量:4 字节同步 0xF8724E1F + 2 字节 data type + 2 字节长度(比特)+ 填充负载。
一个非常实用的细节在采集侧:src/source/CaptureCardSource.cpp 说明"16-bit 立体声引脚也可能承载 Dolby/DTS 的 IEC 61937"(例如 PS5 设为 Bitstream、而采集卡 USB 音频只有两声道),这种情况过去会被当噪声播放;现在的处理是解码它(5.1 保留人声所在的中置),而 PCM-only 模式保持每个字节原样。解码后的块会重新配置音频会话为 32-bit float,并记录 decoding {} carried in PCM: channels=... mask=... rate=... ok=...。
需要注意报告的边界:真实位流采集卡协商未验证(本机设备不提供位流)、TrueHD/DTS-HD 无真实素材。audioIngressMode 也提供了"仅 PCM"的强制档:手动选 PCM 而设备提供位流时,日志会写明"bitstream types are ignored even though the device offers them"(src/source/CaptureCardSource.cpp)。
七、AMD FSR:探针先证明 API 路径,再谈接入
7.1 探针结论(E/F 前置证据,ef0fb50)
tools/fsr_probe(CMake 目标 veyra_fsr_probe,见 CMakeLists.txt)加载 AMD FSR SDK 2.3.0 的签名 loader,在真实 D3D12 设备上枚举 provider 并创建帧生成代理交换链。本机 RTX 5070 的结果:
framegen-swapchain3.1.7、framegen3.1.6 被枚举(带真实 device 的版本变体同样);CreateContext(framegen swapchain for hwnd) = OK(返回非空 context 与代理交换链)、DestroyContext = OK;- 4.0.1(ML) 在这些 desc 类型下未被枚举,与"4.x 面向 AMD 支持列表"的分档假设一致,需 AMD 卡复测;
- 实现约束:loader 只在 DLL 所在目录可被搜索时才发现 provider——工作目录切到
signedbin才成功,仅用LOAD_LIBRARY_SEARCH_DLL_LOAD_DIR会得到NO_PROVIDER/ERROR_UNKNOWN_DESCTYPE。
最后一条约束是整篇报告里最容易踩、也最值得抄下来的一条:播放器集成必须显式把 AMD DLL 目录加入加载搜索路径。今天的 src/gfx/FsrFgPresenter.cpp 正是这么做的——用绝对路径 + LOAD_LIBRARY_SEARCH_DLL_LOAD_DIR | LOAD_LIBRARY_SEARCH_SYSTEM32 预加载 loader 与 provider,并保留模块引用(loadResidentModule 按绝对路径去重,避免重建时反复加载)。
7.2 接入结构(报告当时)
报告记录的新增组件是 FsrFgPresenter:FidelityFX loader + 代理交换链上下文 + 帧生成上下文 + 每帧 prepare/configure/插帧 dispatch + 提供方 present 回调(合成与真实/生成帧计数)。PresentSink/VideoPresenter/EnhanceGraph/EngineController/设置 UI/预设 schema v13 全部接入,命令行开关 --fg-fsr;导出与 XeSS 一样明确拒绝(交换链插帧没有编码器输出合同)。详细 API 顺序与失败模式见 FSR_FRAMEGEN_INTEGRATION_2026-09-16.md。
该接入记录里有三条"必须记住的 API 事实",属于踩过坑的经验:
- 版本描述必需:交换链上下文必须挂
ffxCreateContextDescFrameGenerationSwapChainVersionDX12; - 必须先 Configure 再 Query:交换链只在自身
frameGenerationEnabled为真时才返回插帧命令列表,顺序反了会拿到空命令列表,ffxDispatch返回ERROR_RUNTIME_ERROR; intra-frame尺寸关系:prepare.renderSize必须 ≤ 创建时的maxRenderSize,而播放器窗口缓冲常小于工作分辨率(contain 缩放),所以maxRenderSize取两者较大值。
7.3 源码现状:已经从"代理交换链"演进为"独立上下文"
这里必须做一次时间区分,否则会读错代码。报告(2026-09-16)描述的是代理交换链方案,并记录了它的已知约束:ffxDestroyContext 之后提供方不释放真实 DXGI 交换链,同一 HWND 无法再建交换链,因此代理交换链在窗口生命周期内保留(using the retained AMD proxy swapchain)。
而当前仓库中的 include/veyra/gfx/FsrFgPresenter.h 已明确写着"历史类名保留,但不再创建 HWND / 交换链 / 呈现 worker":
// AMD SDK frame interpolation into application-owned GPU textures. The
// historical class name is retained, but no HWND / swapchain / presentation
// worker is created. FrameBatch and VideoPresenter own timing/presentation.
bool initializeIndependent(ID3D12Device*, uint32_t width, uint32_t height,
DXGI_FORMAT, bool requireMl);
bool generate(ID3D12GraphicsCommandList*, ID3D12Resource* color,
ID3D12Resource* motion, ID3D12Resource* depth, ID3D12Resource* output,
bool reset, float elapsedMs);
也就是说,后续的 FG_FSR_XESS_EXECUTION_2026-09-30.md 把 FSR 从"接管交换链"改成"共享处理图 + 独立 effect context",从而支持同窗口热切换而不建副显示器/第二视频窗口。当前 generate() 的实现(src/gfx/FsrFgPresenter.cpp)是这个新合同的直接体现:
- 输入校验严格到格式级:motion 必须是
R16G16_FLOAT、depth 必须是R32_FLOAT、输出必须带ALLOW_UNORDERED_ACCESS; - 顺序是
Configure(带FFX_FRAMEGENERATION_FLAG_NO_SWAPCHAIN_CONTEXT_NOTIFY)→Dispatch prepare V2→Dispatch generate; dispatch.numGeneratedFrames固定为 1,这就是"上限实测为 2X"在代码里的落点;- 视频没有引擎相机,因此用"稳定的虚拟右手基"而非零向量(
cameraUp[1]、cameraRight[0]、cameraForward[2]各置 1),并在日志里标注这是估计 guidance; - transfer function 按格式分派:
R16G16B16A16_FLOAT → scRGB、R10G10B10A2_UNORM → PQ、其余sRGB; maxGeneratedFrames()返回值是available ? 1u : 0u,与 2X 上限自洽。
另外,provider 选择也是显式的:src/gfx/FsrFgPresenter.cpp 通过 ffxQueryDescGetVersions 枚举 inventory,按 requireMl ? "4.0." : "3.1." 做族匹配,找不到就直接失败并明确"no version fallback",创建后再用 GET_PROVIDER_VERSION 核对实际返回的 id 与版本名——报告里"不把 3.1 fallback 标为 FSR 4"的要求正是这一段的语义。
7.4 2X 上限与"真的带运动"验证
报告给出两条硬结论:
- 上限实测为 2X:请求 2 或 3 张生成帧时,present 回调仍只收到每真实帧 1 张(
logs/fsr/probe-3x-20260916.log、probe-4x-20260916.log)。引擎与预设据此把 FSR 倍率门限设为 2X,超过即拒绝而不是"标 4X 实际 2X"。对应实现见 src/engine/EngineController.cpp,状态文案是"AMD FSR 帧生成上限为 2X;请求未应用"。 - 生成帧带真实运动(E-1 门槛):探针
motion模式让白方块每帧移动 40 像素,回读插帧目标得到方块中心 1041.5,理论中点 1040.0(真实帧 1060、前一帧 1020)——不是重复帧也不是外推帧。同一探针的提交间隔均值 9.52ms、最大 15.57ms、<5ms 仅 3/47,没有成串突发(报告明确这是提供方提交节奏,不是屏幕扫描实测)。
motion 模式的意图写在探针源码里(tools/fsr_probe/main.cpp):移动已知像素数、回读插帧目标、检查生成帧是否真的落在两真实帧的时间中点。帧生成类功能最容易被"数字翻倍但画面不动"骗过,这个探针就是防这个的。
回归数据同时给出:DLSS 6X 875 生成/177 真实、XeSS 4X 639 生成/217 真实,均 exit 0,说明三条后端互不污染。
八、验收清单:把报告里的命令跑成证据
报告第三节给的是"建议顺序",把它按后端整理后可以直接当回归脚本用。注意命令中的 <视频> 为本地素材占位,--smoke-seconds 是短测时长。
8.1 前置检查
git log --oneline -12
# 期望:包含 merge 24e7de7(本分支全部提交);未推送、未发布
cmd.exe /c out\build\veyra-build-x64-release.cmd
# 期望:exit 0
# delivery 短测(分支 tip)
# 期望:PASS,结果在 logs/delivery/<run-id>/result.json
8.2 DLSS 6X
out\build\audio-continuity-repair-20260915\veyra.exe --fg-multiplier 6 --smoke-seconds 10 `
loop\local\fixed_clips\test_av_1080p.mp4
# 期望日志:maxMultiplier=6;generated ≈ 5×frames
# 期望 UI:补帧下拉出现「6X · 五张中间帧」
8.3 XeSS 4X
veyra.exe --fg-xess --fg-multiplier 4 --smoke-seconds 10 <视频>
# 期望日志:unlock applied / framesPresented=4 / pacing installed
# 期望退出:rolled back 5/5
# 4K/30fps 4X 实测:同 burst 间距 mean 8.303ms、refused=0(观感是否均匀需人工判断)
8.4 40 系 / 30 系
# 40 系:用 final-40x6x 包的 EXE(不再需要 VEYRA_TEST_FG_FORCE_MULTIPLIER)
veyra.exe --fg-multiplier 4 --smoke-seconds 15 <视频>
# 期望:[ada-mfg] ... unlock applied=1 gates=2 descriptors=8 kernel=1,且 multiFrameMax=5
# 30 系:用 final-30x86 系列包
# 期望:[ampere-mfg] 行 + 真实出帧
8.5 仅测试用的两个环境变量
# C-1:绕过"请求倍率超过上报上限"的拒绝(UI 不可达,仅测试)
$env:VEYRA_TEST_FG_FORCE_MULTIPLIER='1'
.\veyra.exe --fg-multiplier 4 --smoke-seconds 15 <一段本地视频>
# 期望日志:requested MFG multiplier unsupported / test-only FG multiplier forced above capability
# 观察 [app] smoke frames=... generated=... 与画面是否真的更顺(重复帧 = 数字翻倍但运动不增加)
# 模拟 40 系上限,验证降级路径保留补帧
$env:VEYRA_TEST_FG_MULTIFRAME_MAX='1'
.\veyra.exe --fg-multiplier 4 --smoke-seconds 15 <视频>
# 期望日志:requested multiplier 4 exceeds GPU capability maxGeneratedFrames=1;
# applying 2X with frame generation kept
报告对这两个变量的定位很严格:VEYRA_TEST_FG_FORCE_MULTIPLIER 只能用来观察未打补丁时的失败现象,40 系正式路径是解锁补丁,不应再依赖它。
8.6 AMD FSR
out\build\audio-continuity-repair-20260915\veyra.exe --fg-fsr --smoke-seconds 10 <视频>
# 期望日志:[fsr-fg] provider=3.1.6 / using the retained AMD proxy swapchain
# 期望结尾:generated ≈ frames(2X)且 exit 0
# 最近一次实跑:284 真实 / 280 生成(logs/fsr/smoke-fsr-final2.log)
# 同时检查:设置里「补帧方式」是否出现「AMD FSR 帧生成 · 2X」
需要提醒的是,当前仓库的设置面板已经移除了 FSR 帧生成的 UI 入口(apps/veyra/SettingsWindow.cpp):用户可能卡在该选项上(切回 DLSS 不会恢复),且结果未达可发布水准;后端仍保留在引擎中,仅通过 --fg-fsr 可达,用于诊断。FSR 超分是另一个特性,不受影响。所以在当前版本上照本节验收时,期望看到的是日志而不是下拉项——这条差异属于"报告时点"与"当前实现"的正常演进,不是文档错误。
8.7 杜比 / 位流
veyra.exe --smoke-seconds 10 <capture2:...>
# 期望日志:capture-audio-bitstream 行
# 直通路径:passthrough to receiver kind=...
# 回退路径:显示解码后的声道数("位流解码为 N 声道")
报告对这项验收的前提说得非常明确:必须在支持位流的采集卡上跑,因为参考设备实测是 bitstream types=0 [none] pcmTypes=15。
九、边界声明与可复用的工程经验
9.1 报告自己划定的边界
- 已合并 main(merge
24e7de7,tagcheckpoint/merged-framegen-20260916);未推送远端;未发布。 - 磁盘上的
libxess_fg.dll未修改(哈希与审计值一致);所有运行库修改仅在进程内存,退出即恢复。 - 隔离分支上 delivery 短测 23/23 通过,但实卡 40 系、XeSS 节奏、FSR、杜比直通均未验证,不作为已完成能力对外描述。
逐个功能的"未验证"清单同样值得完整保留:
| 功能 | 未验证项 |
|---|---|
| DLSS 6X | 无(50 系实机已测);40 系降级路径为模拟验证 |
| XeSS MFG | AMD 显卡实机;上游时间戳/截止时间层与墙钟回退未移植 |
| 40 系 DLSS MFG | 3X/4X/6X 是否真出运动帧;Ada 缺硬件 flip metering 是否冻结 |
| 30 系原生 DLSS-G | 实机行为(额外 gate、质量、性能、稳定性);上游自述 "very early and experimental" |
| AMD FSR 帧生成 | AMD 显卡实机、HDR10 输出、采集卡实时输入;FSR 4.0.1 ML 在本机未被枚举 |
| 杜比解码/直通 | 真实位流采集卡协商(本机设备不提供位流)、TrueHD/DTS-HD 无真实素材 |
9.2 三个可以迁移到其他项目的模式
模式一:能力上限驱动的三处一致。 UI 只列可行值、请求层拒绝并保留原值、后端失败按上限降级。三者中任何一处缺失,都会退化成"标签与实际不符"。Veyra 把这个模式同时用在 DLSS(MultiFrameCountMax+1)、XeSS(审计 provider 4X / 运行会话上限只升不降)、FSR(硬编码 2X)上。
模式二:字节级修改必须先证明身份,再事务化提交。 大小 + SHA-256 + PE TimeDateStamp/SizeOfImage 四元组前置校验、逐字节原始值校验、写后回读、失败全量回滚、会话结束恢复。XeSS 的 5 处补丁、Ada 的 3 段哈希链、Ampere 的 69 个 fatbin 用的是同一套骨架,区别只在"结构期望值"不同。
模式三:验收要能证伪。 4X 节奏 hook 的价值来自"关掉 hook 就完全没有调度"的对照组;FSR 插帧的价值来自 motion 探针回读中点 1041.5 vs 理论 1040.0;杜比能力的价值来自 bitstream types=0 这条"证明做不到"的日志。一个只有成功路径的验收清单,无法区分"功能生效"和"数字翻倍"。
十、延伸阅读
- 计划与决策依据:FRAMEGEN_FSR_DOLBY_PLAN_2026-09-16.md、FSR_UPSCALING_PLAN_2026-09-16.md
- 同期接入细节:FSR_FRAMEGEN_INTEGRATION_2026-09-16.md、AMD_FSR_SDK_2.3.0_LOCAL.md
- 后续演进:FG_FSR_XESS_EXECUTION_2026-09-30.md(FSR 改为独立 context、支持同窗口热切换)
- 施工日志与门禁数字:docs/WORKLOG.md、scripts/gates/delivery.ps1
- 核心实现:FsrFgPresenter.h、XessMfgUnlock.h、XessPacing.h、ThunkHook.h、AdaMfgUnlock.h、AmpereMfgUnlock.h、BitstreamAudio.cpp
- 测试与探针:FsrFgDispatchTests.cpp、RepairContractTests.cpp、tools/fsr_probe/main.cpp
- 第三方归属:THIRD_PARTY_NOTICES.md