渲染器与设备

Engine 创建并终身持有一个 Canvas 和一个原生 THREE.WebGLRenderer：

const engine = createEngine();

document.querySelector('#host')!.append(engine.canvas);
engine.renderer.setClearColor(0x111827, 1);
engine.start();

没有 Engine Renderer wrapper。业务可以直接使用 Three.js renderer API，但设备级 mutation 仍由 Engine 负责。

所有权边界

Engine 负责：

• 创建唯一 Canvas 与 WebGLRenderer；
• 监听 Canvas content-box、window resize 和设备 DPR；
• 调用 renderer.setPixelRatio / setSize；
• 管理唯一 RAF 与 Three.js Timer；
• 在 Pipeline 边界设置 render target、viewport、scissor；
• 最后调用 renderer.dispose()。

业务负责：

• 把 Canvas 放入 DOM 并设置 CSS 布局；
• Scene、Object3D、Camera 的业务参数；
• 自定义 Camera 的 projection/world matrix；
• 不与 Engine frame 同步冲突地使用其他 renderer API。

不要替换 Canvas/context/outputBufferType，不要在 Engine render 中并发驱动同一 renderer，也不要依赖 Pipeline 执行前残留的 viewport/render target 状态。

CSS 尺寸与 DPR

Canvas 的 CSS content-box 是逻辑尺寸事实。Engine 暴露冻结快照：

console.log(engine.size);
// { width, height, pixelRatio }

renderer.setSize(..., false) 只更新 drawing buffer，不改写业务 CSS。Canvas 应获得明确的 CSS 宽高，例如：

.viewer {
  height: 480px;
}

.viewer > canvas {
  display: block;
  height: 100%;
  width: 100%;
}

DPR 策略

createEngine({ pixelRatio: 1 });
createEngine({ pixelRatio: 'device' });
createEngine({ pixelRatio: [1, 2] });

区间策略参考 TresJS 的 DPR 保护方式，只把设备 DPR clamp 到 [min, max]。它不读取帧率、不维护性能窗口，也不会因为短时或持续掉帧触发 DPR resize。

帧循环

createEngine() 初始 stopped：

engine.start(); // 测量 Canvas，然后请求 RAF
engine.stop();  // 取消后续 RAF，保留场景与 GPU 资源

每次 start/resume 的第一帧 delta = 0。若任一同步 frame callback 抛错，Engine 停止后续帧并原样暴露错误；不自动 recovery。

Engine 当前使用 browser RAF，而不是 renderer.setAnimationLoop。业务无需依赖这个内部选择；公开契约只有 start/stop/running。

Camera 规则

默认 Camera 由 Engine 创建。只有以下变化会自动更新它的 aspect：

• Canvas 逻辑尺寸变化；
• 精确的默认 RenderView viewport 变化。

额外 View 的 Camera 是 borrowed native identity。业务必须在 viewport、尺寸或 Camera transform 改变后自行调用：

camera.updateProjectionMatrix();
camera.updateMatrixWorld(true);

Pointer 与渲染都读取 Camera 已提交的 stored matrices，不会为业务 Camera 隐式修复。

透明输出

renderer 默认 alpha: true、antialias: false。固定的默认 main 把 View 渲染到 Pipeline 离屏目标，并保留每个 View 原生的 Scene background、color/depth clear 与覆盖顺序；auto 模式随后由固定 OutputPass 上屏。没有 View 时，Pipeline 会在必要时清掉旧 Canvas 内容。

Canvas antialias 只控制默认 framebuffer，不能改善离屏 Composer 内容；Pipeline render target 的 samples 默认也为 0，且不会根据 Canvas 配置自动推导。业务可以分别显式开启两者，但常规 Pipeline 路径只需选择离屏 MSAA 或 FXAA，避免重复采样成本。

下一步

• createEngine
• RenderView
• Pipeline
• 资源与所有权