jhaizhou-ops

gfx-triage

S2Arm 画面问题分诊与根修:拿到「花屏 / 贴图错 / 闪烁」「不满屏 / 宽屏两侧异常 / 拉伸」「没走直连 / 直连异常」任一类问题时先读本 skill。按症状分到三份排查手册,读 host.log 指定行定位,再按先红后绿写单测、根修。

jhaizhou-ops 3,444 595 Updated 1w ago
GitHub

Install

npx skillscat add jhaizhou-ops/s2arm/gfx-triage

Install via the SkillsCat registry.

SKILL.md

画面问题分诊(gfx-triage)

你在帮 S2Arm 定位并根修一个画面问题。原则:先看读数再猜原因,先写会红的单测再改代码,修机制不修症状。三份手册是知识库,本文件只管分诊顺序。

0. 先确认三件事(每一件都看 host.log,不靠印象)

  1. 图形模式:grep 图形模式:。是「没有直连库」→ 直接去 直连异常与退回通用。
  2. 屏幕比例与宽屏开关:grep 宽屏: 和 出图层已挂到根视图。问题只在两侧条带,或者整幅比例不对 → 去 不满屏与宽屏异常。
  3. 新红行:grep 【红】。任何新出现的红行先读完再往下走。

都不是 → 去 花屏与贴图错。

1. 症状 → 手册 → 先看哪几行

症状 手册 先看
切场景后整屏发白 / 背景成片噪点 花屏 开 DM_NVN_NONFINITE_FILL=1 做反证,能复现就是旧字节 Inf/NaN
高光 / 反射逐帧闪 花屏 same-pass feedback sampling up to frame …;用 DM_NVN_SHOT 连拍,按块量或直接看连续帧
远景糊 / 锐不对,日志里大量重新登记 花屏 sampler pool up to frame … registered again
isnan 挡不住的黑块 / 白块 花屏 graphics/metal/tests/t_mathmode.m,编译数学模式
整局 16:9 加黑边 宽屏 总开关:环境变量 > 用户设置 > 包内能力清单 > widen_verified.tsv
某页两侧残留旧帧 宽屏 截图帧号在不在「出图原比例居中 / 离开原比例页」区间里;「其中纯色 / 小图层按原样铺满」计数
暗化 / 模糊底只盖中间 宽屏 被采样的贴图有没有登记成整屏副本(定因中,见手册)
整幅横拉 宽屏 是不是 Vulkan / GL 直连(第三层做不到)
图形模式:没有直连库 / 起局报「游戏文件缺失」 直连 图形模式:没有直连库(依据 …) 行与上面的【红】(链号不符、缺 shader_map.tsv / lib.idx);entry*.direct_missing。11-07 起没有通用模式可退,导出诊断包反馈
首遇卡顿 直连 直连着色器现编汇总、shader loads: 行
GPU 线程异常 / 着色器取码报红 直连 S2AShaderFault 红行的地址链 ①②③

2. 复现

  • 优先在 Mac 局上复现:同一套通用自动玩家(AI 看屏驾驶,学过的路线自动回放)、同一个屏幕尺寸(S2A_SCREEN_W / S2A_SCREEN_H)、同一个开关。
  • 修前在同配置下必须能复现。复现不了就写明「本机型复现不了」,交给能复现的设备复验,不要宣称修好。
  • Mac 局截图拿到的是出图窗口,宽屏两侧可能截不到,这时以诊断行读数或真机截图为准。

3. 定因

  • 把出错的那一笔 / 那一张贴图定位到具体对象:序号、池、偏移、格式、它是谁写的(拷贝 / 渲染 / 计算 / CPU)。
  • 临时诊断行放在临时分支上,带环境变量开关,不合入。
  • 一个假设一局:一次只差一个变量。

4. 根修(先红后绿)

  1. 写单测,期望值不跑被测实现就能算出来。修前红,红的原因必须是被测缺陷本身。
  2. 改代码,只改根因那一层。同类问题出现第二次,就改机制,不逐个补洞。
  3. 单测转绿,再加一个负对照(关掉修复必红)。
  4. 回到复现局验:期望 → 实测表,写局数、帧数、设备。

单测样板:

  • 采样器 ABI:graphics/nvn/tests/t_nvn_samp.c
  • 偏置 / 归约模拟:graphics/nvn/tests/t_nvn_red.m
  • 编译数学模式:graphics/metal/tests/t_mathmode.m
  • 着色器并发加载:graphics/nvn/tests/t_nvn_shader_flight.m
  • 宽屏核心:tests/visual/widen_unit/
  • 着色器取码防线:tests/shader_garbage_guard_test.sh

5. 判据会绿着失效,报绿时一并报射程

  • 满屏验收只认纯黑边:两侧残留会被判「过」。满屏以看图为准。
  • 整幅亮度均值量不到局部闪烁。
  • 金样漂移要二分到提交、写明原因再重登记,不准放宽界限。
  • 失败记录被缓存时,一次基础设施失败可能被冻结成「判据不过」。

6. 交付

PR 写清问题、根因、改动、实测(期望 → 实测表)、限制,并贴 bash tools/contrib_check.sh 摘要。新踩的坑按 AGENTS.md 追加到 docs/坑记录.md。

NVN 接线(给一款新游戏做直连接线)另见 nvn-wire。

Categories