wangdequan/workinf_Blender_Wasm
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
a27aa46d7c4cbacbd417c8fa7c1e593dc6baec9c
workinf_Blender_Wasm/docs/status/RE_PBR_RENDER_20261111.md
mes123456 d5dd647881
Some checks failed
M6 deployable RC / quick (push) Has been cancelled
Details
M6 deployable RC / chromium (push) Has been cancelled
Details
M6 deployable RC / release (push) Has been cancelled
Details
feat(web): finish RE 5000PBR lesson video and fix non-ASCII GLB import 
- Add 11:07 Chinese-narrated lesson video, VTT, poster and 13 chapter screenshots.
- Regenerate 20-render WebGL2 matrix and 15 operation captures on RTX 4060.
- Fix WASM staging for non-ASCII import filenames (猴头.glb); rebuild web_engine.
- Harden lesson video recording pipeline; fix stale lesson-link E2E selector.
- Add RE PBR derived libraries, lesson page, evidence and status report.

Co-Authored-By: Claude Code <noreply@anthropic.com>
2026-11-12 21:49:24 +08:00

8.6 KiB
Raw Blame History

Web Blender：RE 5000PBR × 猴头 GLB 渲染与初学者 HTML 教案

日期：2026-11-11 状态：功能实现完成；有头 Chromium 聚焦验证通过；整体产品验收仍由用户执行 后续：已知限制的修补与验证见 RE_PBR_LIMITS_20261112.md。 （IMPLEMENTED_NOT_USER_ACCEPTED）

交付内容

1. RE 5000PBR 派生资产库

  • tools/web/generate-re-pbr-library.py：从 re/5000PBR精简版/5000+ PBR catalog.blend 的工作副本派生 6 个材质；标记 5 个已标记材质 + 未标记的 Black_Anti_Slip_grip；统一挂到 Materials/RE5000PBR catalog。
  • 保留原节点图（FRAME、REROUTE、DISPLACEMENT、MAPPING、VALUE 与四张 IMAGE_TEXTURE）， 只把贴图降采样：Base Color/Normal 1024²，Roughness/Height 512²，并重新 pack 为 JPEG。
  • 产物：web/app/public/assets/re-pbr/
    • re-pbr-library.blend：6 个 MATERIAL，SHA-256 d67f5a058c154626dfc7171c5bc7fc254b8ee183fea8740261b9711b3309d782。
    • manifest.json、preview-manifest.json、desktop-canonical.json、blender_assets.cats.txt、 6 张 256² 预览。
    • 库大小 3.7 MiB，packed 贴图约 3.06 MiB（源 10.7 MiB）。
  • tools/web/check-re-pbr-library.mjs：校验 6 个材质、预览、SHA、尺寸、JPEG 格式、色彩空间， 并只读复检节点图仍包含 FRAME/REROUTE/DISPLACEMENT/MAPPING/VALUE 与四张贴图。

2. 多库播种与合并（资产面板 20 个资产）

  • web/protocol/asset-catalog-v2.ts：新增 mergeAssetCatalogManifests，按 catalog/asset/library id 去重追加、bump revision 并重新校验。
  • web/app/src/storage/asset-catalog-store.ts：新增 mergeAssetCatalogManifest，事务内重读原始行、 检测 revision 漂移、更新/删除预览回执，避免旧回执失效。
  • web/protocol/storage.ts、StorageClient.ts、storage.worker.ts：新增合并命令； seed/读取 manifest/预览的客户端超时提高到 30–60 s。
  • web/app/src/app/pbr-library-seed.ts：PBR_LIBRARY_SOURCES 支持 pbr-essentials-v1（14）与 re-pbr-v1（6）；首装先 seed 主库，再对缺失库 seed(repair=true) + merge；单库失败只降级该库并保留既有资产。
  • AssetLibraryPanel.tsx：卡片补 data-testid/data-asset-id/data-library；新增“资产来源”筛选； 缩略图改为 eager，20 张预览全部加载。
  • 既有 PBR 教程/测试的资产数从 14 更新到 20；PBR 教程原有 12 张渲染矩阵保持不变。

3. 渲染正确性修复

  • 快照后重绑纹理与环境：viewport-render.worker.ts 拆分 reapplyCurrentTextures()（只从已上传 store 重绑）与 applyTextureAssets()（upload + 重绑）； setSnapshot 末尾重绑，不再在每次分配材质时重新解码全部贴图。
  • HDRI 背景保护：只有 world 确有环境贴图时才让 applyEnvironment 覆盖背景， flat world color 不再覆盖已应用的 HDRI。
  • 纹理就绪屏障：offscreen-viewport.ts 增加按 snapshot revision 对齐的 whenTexturesReady()；renderStill 等待纹理与环境应用完成；空纹理也明确回传状态。 面板用该屏障替换固定 150 ms 延时。
  • 原生 reader：web_engine_blend_reader.cpp 不再把 NodeReroute/NodeFrame/ShaderNodeDisplacement 统一映射为 UNSUPPORTED，而是输出 REROUTE/FRAME/DISPLACEMENT。
  • 编译器归一化：compileMaterialGraph 渲染路径与 compileShaderGraph 共用 normalizeShaderGraph：折叠 REROUTE、移除 FRAME、删除 DISPLACEMENT 节点及全部连线； 对不含这些节点的图严格 no-op。
  • 编译器扩展：支持 IMAGE_TEXTURE → Roughness/Metallic/Alpha、IMAGE_TEXTURE → SEPARATE_COLOR、VALUE → MAPPING.Scale/Rotation/Location（标量广播）；Mapping 的 uvTransform 与原生 textureBindings 按 usage 合并，不再被原生绑定覆盖。
  • SceneIR 运行时校验同步允许 REROUTE/FRAME/DISPLACEMENT。
  • App.tsx 的材质分配在对象无槽时用 slotIndex=-1 追加槽，避免先创建空白材质导致 name.001 冲突；重开工程后材质槽保留。
  • web/app/public/engine-manifest.json 的 single 变体改指向重新构建的 /vendor/blender/web_engine.{js,wasm}，修复旧的 vendor/blender/single/web_engine.wasm 哈希不匹配（MANIFEST_REJECTED）。

4. 有头 Chromium 测试与 20 张成片

  • web/tests/e2e/re-pbr-render-workflow.spec.ts：
    • 打开摄影棚 → 导入 monkey-head.glb → Shading 20 卡/6 个 RE 材质 → 逐个分配 6 材质 → 材质球 COMPILED → 1024/场景渲染 → data-texture-status ready → PNG 下载 → 保存 .blend → 重开并确认材质槽仍存在。
    • 截断 GLB 负例：对象数不变。
  • tools/web/capture-re-pbr-lesson.mjs：有头 Chromium（headless:false）生成
    • tests/golden/RE-PBR-RENDER-001/renders/*.png：6 材质 ×（1024 场景 + 1024 视口 + 512 场景）
      • 未分配基线 + 保存重开复渲染 = 20 张；
    • web/app/public/tutorial/pbr/lesson/renders/*.jpg 与 steps/*.jpg、landing.jpg；
    • report.json（尺寸、SHA、mean/std、textureStatus、材质、相机、浏览器/DISPLAY）。
  • tools/web/check-re-pbr-lesson.mjs：PASS（20 张、6 材质 SHA 两两不同、基线不同、 PNG 尺寸、textureStatus ready、GLB SHA、教案 HTML 无 inline script/style/on*、无远程 URL、 所有图片存在）。

5. 初学者 HTML 教案

  • web/app/public/tutorial/pbr/render-lesson.html + render-lesson.css
    • 12 节：目标、术语、准备、导入 GLB、资产库、六种材质逐课、渲染设置、下载/保存/重开、 20 张矩阵、黑图排查、限制、附录。
    • 静态 HTML；外链 CSS；无 inline <style>/<script>/on*；同源图片；打印样式。
    • 所有截图来自本次有头 Chromium 实际操作；20 张成片全部标注 Web/WebGL2。
  • React 入口：
    • PbrLessonPanel.tsx 挂在 Rendering 工作区：打开图文教案、载入练习摄影棚、导入猴头 GLB、 显示 20 资产 / 6 个 RE 材质。
    • TutorialCourse.lessonUrl；PBR 落地页导航增加“渲染图文教案”；帮助菜单增加“PBR 渲染教案”。

验证结果

检查 结果
node tools/web/check-re-pbr-library.mjs PASS（6 材质、6 预览、SHA/尺寸/JPEG/节点图）
node --test web/tests/unit/shader-compiler.test.mjs 13/13 通过（含 REROUTE/FRAME/DISPLACEMENT、Value→Mapping、Roughness/Metallic 新用例）
npm run typecheck 通过
npm run build 通过
npx playwright test --headed tests/e2e/re-pbr-render-workflow.spec.ts 2/2 通过（有头 Chromium）
npx playwright test --headed tests/e2e/pbr-asset-library-production.spec.ts tests/e2e/wbv2-pbr-tutorial-production.spec.ts 3/3 通过（20 资产回归）
node tools/web/check-re-pbr-lesson.mjs PASS（20 张 / 15 步 / 6 材质 / 基线均值 94.60）
部署服务器 + 有头 Chromium 打开 render-lesson.html 标题、35 张图片（eager/decode 后）全部加载；无 4xx；CSP 头生效

证据路径

  • 20 张渲染：/home/mes123456/workinf_Blender_Wasm/tests/golden/RE-PBR-RENDER-001/renders/
  • 采集报告：/home/mes123456/workinf_Blender_Wasm/tests/golden/RE-PBR-RENDER-001/report.json
  • 教案：/home/mes123456/workinf_Blender_Wasm/web/app/public/tutorial/pbr/render-lesson.html
  • 教案截图：/home/mes123456/workinf_Blender_Wasm/web/app/public/tutorial/pbr/lesson/
  • 派生库：/home/mes123456/workinf_Blender_Wasm/web/app/public/assets/re-pbr/
  • GLB fixture：/home/mes123456/workinf_Blender_Wasm/tests/files/web/pbr-render-lesson/monkey-head.glb （SHA-256 60267d607b63ceb5bfc972342a9ff17310d6978ff632f240ecb963c4d5a7e003）
  • 引擎 wasm：web_engine.wasm SHA-256 909290259e2911af49f1d6f308e1e05e01f62aa1841847b878bcd3191b98c24c

已知限制 / 未验证项

  • Web 渲染器不执行 Displacement；Height 贴图保留但不产生位移。
  • 六种 RE 材质都是深色砖石/防滑表面；成片整体偏暗是材质本身，不是黑图。
  • 当前视口相机默认与场景相机对齐，所以 1024 场景/视口成片可能相同；移动视口后再渲染即可看到差异。
  • 保存重开后 data-texture-status 的诊断字符串曾出现 ready:0:0（图像本身与保存前一致）； 这是诊断计数时序问题，已记录，不影响重开渲染结果。
  • 派生贴图为 1024/512；未做 2048 原始贴图对照。
  • 未做硬件 GPU（非 SwiftShader）对照、Firefox/WebKit、移动端。
  • 未验证用户实际使用验收；不把本次单测/E2E/采集 PASS 当作整体产品验收。
Reference in New Issue View Git Blame Copy Permalink