# RE 5000PBR 渲染已知限制：修补与验证记录

日期：2026-11-12
状态：**功能实现完成；有头 Chromium 聚焦验证通过；整体产品验收仍由用户执行**
（`IMPLEMENTED_NOT_USER_ACCEPTED`）

## 本轮决策

- **Chromium 限定**：只做 Chromium 硬件 GPU 与 SwiftShader 对照；Firefox/WebKit 按仓库铁律不启动、不纳入验收。
- **2048 高清验证 + 可选切换**：默认标准 1024/512；`re-pbr-hq` 2048 库按需加载，材质名带 `_HQ`。
- **诊断视图 + 教学曝光**：保留原材质，增加 Final/Base Color/Normal/Roughness 与 0/+1/+2 EV。
- **Displacement 渲染与交互视口都执行**：HEIGHT 绑定 + displacementMap；静帧有界细分，交互视口逐顶点位移。

## 逐条结果

### 1. Displacement / Height

- 原生 reader：从 `Material Output.Displacement` 读取 `ShaderNodeDisplacement`，解析 Height 图、`Midlevel=0.5`、`Scale=0.001`；
  输出 `usage:"HEIGHT"` binding 与 `displacementImageId/displacementMidlevel/displacementScale`。
  同时改为从 packed JPEG/PNG 头读取真实尺寸（`gen_x` 只有 1024 时仍能识别 HQ 2048）。
- 编译器：`DISPLACEMENT` 进入 allowlist；不再删除该节点；支持 `IMAGE_TEXTURE → DISPLACEMENT.Height`、
  `DISPLACEMENT → OUTPUT.Displacement`、`VALUE/MATH → Scale/Midlevel`；HEIGHT binding 带 `scale/midlevel/uvTransform`。
- Three.js：`applyMaterial` 设置 `displacementMap`、`displacementScale`、`displacementBias=-midlevel*scale`；
  HEIGHT 强制 Non-Color，禁止回退到 BASE_COLOR；原生/编译 binding 按 usage 合并。
- 几何：静帧渲染对 968 三角形猴头做 level 3 中点细分到 **61,952** 三角形；交互视口使用原几何逐顶点位移，
  编辑模式不细分，避免破坏拾取。
- 教学强度：1× 保留源 Scale；10×/100× 只乘渲染时 `displacementScale`，不写材质/.blend。
- 证据：`tests/golden/RE-PBR-LIMITS-001/displacement/report.json`
  （HEIGHT/scale/midlevel/bias、968→61,952、1×/100× PNG、mean 93.96/93.87、SHA 不同）。

### 2. 深色材质

- Rendering 面板增加“视图”：Final / Base Color / Normal / Roughness；只临时替换活动对象材质，地面保留 Final。
- 教学曝光 0/+1/+2 EV 只调整渲染曝光，不改变材质数据。
- 证据：`tests/golden/RE-PBR-LIMITS-001/diagnostics/report.json`（3 张诊断图、曝光差异 >1）。
- 桌面 EEVEE 参考脚本本轮未运行；EEVEE 不把 Material Output.Displacement 当几何位移，
  因此即使补参考也只用于颜色/灯光，不用于位移验收。

### 3. 视口相机

- 新增 `viewPreset`：`SCENE_CAMERA` 复用场景相机 `worldMatrix` 精确姿态；`COMPARISON` 以主体为中心
  yaw + π/6、pitch +0.18、distance ×1.1。
- PbrRenderPanel 增加“视角预设”；默认 SCENE_CAMERA；主视口 `ViewportNavigation` 不受影响。
- 证据：最终 20 张采集 `uniqueSha=20`；SCENE/VIEWPORT 成片不再重复；
  `tests/golden/RE-PBR-RENDER-001/report.json`。

### 4. 重开 `ready:0:0`

- 根因：重开时空 `textureAssets` 被当作 `textureExpected=false`，面板在 packed assets 到达前渲染并读取空状态；
  另有 worker 完成时重盖章 snapshot revision、`setSnapshot` 重发旧 `lastTextureStatus`。
- 修复：adapter 单调 `textureRevision` + `expectedAssets`；worker 丢弃旧上传、不重发旧状态；
  `still` 回传 `textureStatus`；面板从 still/最新状态取数；空列表且 expected>0 时 `pending`；
  `GPUTextureStore.upload(..., {replace})` 清旧纹理；PbrRenderPanel 对当前 snapshot 做一次自愈式 cache。
- 证据：重开 E2E `data-texture-status=ready:5:0:`，`loaded===expected`；最终采集 reopen 同为 `ready:5:0:`。

### 5. 硬件 GPU / 2048 / 跨浏览器

- Playwright 与采集脚本支持 `GPU_MODE`/`--gpu hardware`；有头 Chromium 探测到
  `ANGLE (NVIDIA Corporation, NVIDIA GeForce RTX 4060 Laptop GPU/PCIe/SSE2, OpenGL 4.5.0)`；
  硬件 lane 若回退 SwiftShader/llvmpipe 失败关闭。
- 同一 1024 材质：硬件 mean 95.277/std 44.758，SwiftShader mean 95.332/std 44.724；
  硬件 E2E 27s，SwiftShader 参考 35.8s（`tests/golden/RE-PBR-LIMITS-001/gpu/batch0-gpu-enable.json`）。
- 2048 HQ：`re-pbr-hq` 10.8 MB、6 个 `_HQ` 材质、原始 packed JPEG；原生 reader 直接读 packed JPEG 尺寸，
  Height 图验证 2048×2048；GPU decoded 67,633,152 bytes（64.5 MiB）、payload 2,625,921 bytes、
  loaded 5/rejected 0，低于 512 MiB。
- 证据：`tests/golden/RE-PBR-LIMITS-001/hq/report.json`。
- 跨浏览器：仓库规则 Chromium-only，Firefox/WebKit 未运行，记为 policy-excluded，不是工程缺口。

## 验证结果

| 检查 | 结果 |
| --- | --- |
| `npm run typecheck` | 通过 |
| `node --test tests/unit/shader-compiler.test.mjs` | 13/13 通过（含 HEIGHT/DISPLACEMENT/Value→Mapping） |
| 有头 E2E 主流程（6 材质、位移 1×/100×、诊断、曝光、相机、重开） | 通过（3.6m） |
| 有头 E2E 截断 GLB 负例 | 通过 |
| 有头 E2E 原生 HEIGHT binding | 通过（scale 0.001、midlevel 0.5） |
| 有头 E2E HQ 原生 2048 尺寸 | 通过（Height 2048×2048） |
| 有头 E2E HQ 按需加载与渲染 | 通过（67,633,152 bytes、ready:5:0） |
| `check-re-pbr-limits.mjs` | PASS（位移/诊断/HQ/GPU/相机/重开） |
| 最终有头硬件采集 | 20/20、uniqueSha 20、15 steps、0 errors |
| `check-re-pbr-lesson.mjs` | PASS |
| `check-re-pbr-library.mjs --hq` | PASS（10.8 MB、6 材质、2048） |
| PBR 资产库回归（有头硬件） | 2/2 通过 |
| PBR 教程回归（有头硬件） | 通过（48.3s） |

## 证据路径

- 位移：`/home/mes123456/workinf_Blender_Wasm/tests/golden/RE-PBR-LIMITS-001/displacement/`
- 诊断/曝光：`/home/mes123456/workinf_Blender_Wasm/tests/golden/RE-PBR-LIMITS-001/diagnostics/`
- HQ 2048：`/home/mes123456/workinf_Blender_Wasm/tests/golden/RE-PBR-LIMITS-001/hq/`
- GPU 启用：`/home/mes123456/workinf_Blender_Wasm/tests/golden/RE-PBR-LIMITS-001/gpu/batch0-gpu-enable.json`
- 20 张硬件成片：`/home/mes123456/workinf_Blender_Wasm/tests/golden/RE-PBR-RENDER-001/`
- 统一检查器：`/home/mes123456/workinf_Blender_Wasm/tools/web/check-re-pbr-limits.mjs`
- 教案：`/home/mes123456/workinf_Blender_Wasm/web/app/public/tutorial/pbr/render-lesson.html`

## 未验证 / 限制

- 源 Displacement Scale=0.001；1× 很细微，100× 是教学放大，不代表源材质变强。
- 静帧细分到 61,952；交互视口是原几何逐顶点位移，未做交互细分。
- 未生成桌面 EEVEE 参考；EEVEE 不作为位移参考。
- 2048 HQ 的 mipmap 可能使实际显存比 base-level 预算高约 1/3；仅按需加载。
- 硬件 GPU lane 依赖 `DISPLAY=:1` 和 NVIDIA 驱动；无独显时需显式 SwiftShader。
- 未做 Firefox/WebKit；用户实际使用验收仍待执行。