# N-019 灯光与渲染

状态：`BLOCKED`（Camera/Light/World/Scene metadata、Camera/Light/World 有界 Main 写回、
Three exposure/shadow 映射和一条有界 Blender reference 图像指标闭环已落地；Scene 颜色管理
writer、全域渲染等价和高级后端仍未实现）

## 已验证切片

1. N-019-A（部分）：Camera 区分 Perspective/Orthographic/Panoramic/Custom，读取 sensor、
   shift、clip、panorama 和 DOF；Light 读取 energy/exposure/temperature/shadow/shape；World
   读取环境、exposure 和 mist；Scene 读取 render engine、display/view/look/exposure/gamma/白平衡。
2. N-019-A（部分）：Light 与 World 使用严格属性白名单写入真实 Main，覆盖 color、energy、
   exposure、temperature、shadow、World color/mist，已通过 undo/redo 与 save/reopen。
3. N-019-B（部分）：主线程和 OffscreenCanvas renderer 都优先使用 Scene color-management
   exposure，World exposure 仅作旧数据回退；Light exposure 转换为强度，`castsShadow:false`
   不再被 Three 强制打开。
4. N-019-B（部分）：World/Scene Main delta 保留版本化集合，主线程与 Offscreen renderer
   对环境颜色、曝光和 scene render settings 变更触发确定性的 renderer rebuild；未知 delta
   版本和重复 ID 继续拒绝。
5. 白平衡读取有完整性门：Main Light/World 重写若导致 Blender 5.2 tint 序列化为异常近零值，
   不暴露垃圾数值而返回 `whiteBalanceStatus: BLOCKED`。
6. Camera 严格白名单写回覆盖 Perspective/Orthographic、lens/sensor/sensor fit、shift、clip、
   ortho scale 和 DOF enable/focus distance/f-stop/blades/rotation/ratio；near/far 与范围在修改前
   拒绝，已通过 undo/redo 和 save/reopen。
7. N-019-B（色温部分）：`useTemperature:true` 时，共享 PBR 适配器把 800–20000 K 的有界
   黑体近似归一到 6500 K 中性白并转换为线性 RGB，再乘入 Light color；关闭色温时原始颜色
   保持不变。主线程与 Offscreen Worker 共用该实现，数值门和原生 temperature 保存重开通过。
8. M11-01 字段表：CameraIR、LightIR、WorldIR 及 Scene render/color-management 共 60 个叶字段
   已逐项标注 reader/writer/main viewport/Offscreen viewport 状态；AST checker 保证零漏项、零重复。
   当前 24 COMPLETE、17 PARTIAL、19 BLOCKED，未把 metadata-only 或近似映射提升为视觉 parity。
9. M11-02 字段闭环：支持的 Camera/Light/World writer 已在同一 Chromium 任务中完成 Main edit、
   revision 单调的 undo/redo、保存、全新 Worker 重开和共享 PBR 映射；水平/垂直 sensor fit、
   temperature linear RGB、shadow、spot/area 参数及 World 背景均有字段级断言。
10. M11-03 资源预算：主线程与 Offscreen 共用 schema 1 light/shadow/texture planner；WebGL2
    总预算为 16 lights、4 x 1024 shadow maps（均包含内置保留槽），纹理同时限制数量、单边、
    aggregate payload 与 decoded RGBA bytes。WebGPU 只冻结 64/8 x 2048 及 device-limit 下调合同，
    未把未安装的 WebGPU renderer 标为可用。
11. M11-04 有界实时 reference：Blender 5.2 Eevee 256×256 fixture 绑定 source/generator/image
    SHA-256；SRGB8/STRAIGHT RGBA 比较输出 MAE、RMS、P95 channel、坏像素比例、前景 IoU 和
    alpha 覆盖率。主线程与 Offscreen 生产 viewport 均为同一报告（MAE 2.0433、RMS 5.4490、
    P95 4、坏像素 0.004776、IoU 0.98534）；非空但错误构图负例稳定返回
    `RENDER_REFERENCE_MISMATCH`。
12. M11-05 最终渲染路由：schema 1 只让 bounded Eevee 的 WebGL2（以及 capability 全通过的
    WebGPU）进入 `WEB_LOCAL_BOUNDED`；Cycles、complex Eevee、Workbench 与 CUDA/OptiX/HIP/
    Metal/oneAPI 固定为 `SERVER_JOB`。默认 endpoint 未配置时返回 `SERVER_JOB_UNAVAILABLE`，
    未知 SceneIR render engine 返回 `PLATFORM_CAPABILITY_UNAVAILABLE`，均不产生本地等价成功。
13. M11-06 server render job：schema 1 请求绑定 source `.blend` SHA-256/byte length/revision、
    Blender 5.2 build SHA-256、规范化 render settings SHA-256 和 request SHA-256；成功结果
    绑定同一 provenance 并公开 output MIME/byte length/output SHA-256/result SHA-256。真实
    loopback server 由 Blender 5.2 headless 打开 fixture 并输出 PNG；source、settings、build
    和 output 篡改均在提交或消费前结构化拒绝。

## 仍然阻断

- N-019-A：Scene color-management writer；直接 DNA 写入会破坏 white balance，必须改接
  Blender/RNA 颜色管理 API 后才能开放。Camera writer 已完成。
- N-019-B/C：AgX/Standard/Raw 的视觉等价、Area spread、Mist、DOF、
  transparent sorting、probe 和高级 shadow 参数。
- N-019-D：M11-05 已冻结 Cycles/复杂 Eevee/硬件后端的 server-only 路由；M11-06 已完成
  有界 server-style submit 和 source/settings/build/output hash provenance；真实远程队列、
  进度、取消、Freestyle 和 denoise job 仍未完成。
- N-019-E：完整 desktop/Chromium 像素 parity、设备丢失和 1M triangles；M11-04 仅关闭固定
  fixture 的有界 reference 指标门，不代表全场景或全色彩管理等价。
- N-019-B/C/E（Volume）：Float32 NanoVDB WGSL 树遍历、有界积分、有限
  temperature/color/emission grid 语义和显式 GPU resident LRU 已有真实 Chromium 数值/图像专项门；
  自动缺页重绘、生产视口深度合成和 desktop/Chromium 三视角 golden 仍阻断，不能据此声明发布级体渲染。

## 验收

```bash
npm --prefix web run test:lighting-roundtrip
npm --prefix web run test:lighting-field-parity
WEB_TEST_PORT=5545 npm --prefix web run test:lighting-field-roundtrip
WEB_TEST_PORT=5548 npm --prefix web run test:render-resource-budget
WEB_TEST_PORT=5552 npm --prefix web run test:render-reference
WEB_TEST_PORT=5556 npm --prefix web run test:render-routing
WEB_TEST_PORT=5560 npm --prefix web run test:server-render-job
WEB_TEST_PORT=5319 npm --prefix web run test:e2e -- --grep "N-019 Scene exposure"
```