fec-canvas-threejs · diff
git:20260607.44659b6 to git:20260611.9d7f5e4
21 added, 21 removed. Audit A to A.
---
name: fec-canvas-threejs
- description: Use when building or reviewing Canvas 2D, Three.js/WebGL, React Three Fiber, GLSL shaders, ShaderToy-to-WebGL adaptation, 2D/3D visualization, game rendering, animation loops, GPU resource cleanup, or rendering performance. Do not use for standard DOM UI, charts already covered by a chart library, or non-graphical performance work; Chinese triggers include Canvas, Three.js, WebGL, GLSL, Shader, 3D, 数据可视化, 游戏.
+ description: Use when building or reviewing Canvas 2D, Three.js/WebGL, React Three Fiber, GLSL shaders, ShaderToy-to-WebGL adaptation, 2D/3D visualization, game rendering, animation loops, GPU resource cleanup, or rendering performance. Do not use for standard DOM UI, charts already covered by a chart library, or non-graphical performance work; Chinese triggers include Canvas, Three.js, WebGL, GLSL, Shader, 3D, data visualization, games.
---
- # Canvas 与 Three.js
+ # Canvas and Three.js
## Purpose
- 在浏览器中实现高性能 2D/3D 图形渲染。
+ Enable high-performance 2D/3D graphics rendering in the browser.
## Procedure
- 1. 先选渲染层：标准 UI 用 DOM；简单 2D 图形/签名/粒子用 Canvas 2D；3D 模型、空间交互和复杂粒子用 Three.js/WebGL；React 项目中的声明式 3D 用 React Three Fiber。
- 2. 为渲染容器定义稳定尺寸、DPI 适配和 resize 行为；Canvas 不会自动随 CSS 清晰缩放。
- 3. 动画循环使用 `requestAnimationFrame`，不可见或无变化时暂停，卸载时取消。
- 4. Three.js 必须释放 geometry/material/texture/renderer，并移除事件监听和 observer。
- 5. Shader/WebGL 任务先识别是 SDF、ray marching、noise、particle、post-processing、multipass 还是调试问题，再决定是否需要原生 WebGL2、Three.js ShaderMaterial 或 R3F。
- 6. WebGL2 适配时检查 GLSL 版本、入口函数、varying/in-out、texture API、uniform 使用和函数声明顺序，避免白屏只留控制台错误。
- 7. 对不可访问的图形内容提供 `aria-label`、替代文本或 DOM 版摘要；交互式图形要有键盘兜底。
+ 1. First select the rendering layer: DOM for standard UI; Canvas 2D for simple 2D graphics/signatures/particles; Three.js/WebGL for 3D models, spatial interactions and complex particles; React Three Fiber for declarative 3D in React projects.
+ 2. Define stable size, DPI adaptation, and resize behavior for the render container; Canvas does not automatically scale cleanly with CSS.
+ 3. The animation loop uses `requestAnimationFrame`, which is paused when it is invisible or has no changes, and canceled when it is uninstalled.
+ 4. Three.js must release geometry/material/texture/renderer and remove event listeners and observers.
+ 5. Shader/WebGL tasks first identify whether it is an SDF, ray marching, noise, particle, post-processing, multipass or debugging issue, and then decide whether native WebGL2, Three.js ShaderMaterial or R3F is required.
+ 6. Check the GLSL version, entry function, varying/in-out, texture API, uniform usage and function declaration order when adapting to WebGL2 to avoid white screen leaving only console errors.
+ 7. Provide `aria-label`, alternative text or DOM summary for inaccessible graphic content; interactive graphics must have keyboard support.
## Core Patterns
```ts
const dpr = Math.min(window.devicePixelRatio || 1, 2);
canvas.width = width * dpr;
canvas.height = height * dpr;
canvas.style.width = `${width}px`;
canvas.style.height = `${height}px`;
ctx.scale(dpr, dpr);
```
```ts
let animationId = 0;
function animate() {
animationId = requestAnimationFrame(animate);
renderer.render(scene, camera);
}
return () => {
cancelAnimationFrame(animationId);
geometry.dispose();
material.dispose();
renderer.dispose();
};
```
- ## 详细参考
+ ## Detailed reference
- 涉及 Canvas 2D 绘图、动画循环、Three.js 场景搭建、React Three Fiber、InstancedMesh 和性能清理时，加载 [references/rendering-patterns.md](references/rendering-patterns.md)。
+ Load [references/rendering-patterns.md](references/rendering-patterns.md) when it comes to Canvas 2D drawing, animation loops, Three.js scene building, React Three Fiber, InstancedMesh, and performance cleanup.
- 涉及着色器路由、WebGL2 适配、GLSL 调试、多 pass 预算和视觉验证时，加载 [references/shader-webgl-patterns.md](references/shader-webgl-patterns.md)。
+ Load [references/shader-webgl-patterns.md](references/shader-webgl-patterns.md) when it comes to shader routing, WebGL2 adaptation, GLSL debugging, multi-pass budgeting, and visual verification.
## Constraints
- - Canvas/WebGL 内容对屏幕阅读器不可见，必须提供替代语义。
- - WebGL 消耗 GPU，低端设备需限制像素比、面数和纹理大小。
- - Three.js 资源不会自动释放，遗漏 `dispose()` 会造成 GPU 内存泄漏。
- - Canvas 响应式必须同步 CSS 尺寸、绘图尺寸和相机/viewport。
- - 复杂布局/路径规划可联用后台线程 workflow，但渲染本身仍在主线程/渲染线程协调。
- - Shader 主循环、采样层数和多 pass 数量必须有预算；低端设备上要降低 DPR、步数、粒子数或禁用重后处理。
- - 交付前必须确认 canvas 非空、尺寸正确、resize 后不拉伸、控制台无 shader compile/link 错误。
+ - Canvas/WebGL content is not visible to screen readers and alternative semantics must be provided.
+ - WebGL consumes GPU, and low-end devices need to limit the pixel ratio, number of faces and texture size.
+ - Three.js resources will not be released automatically, and missing `dispose()` will cause GPU memory leaks.
+ - Canvas responsive must synchronize CSS dimensions, drawing dimensions, and camera/viewport.
+ - Complex layout/path planning can be combined with the background thread workflow, but the rendering itself is still coordinated on the main thread/rendering thread.
+ - The Shader main loop, number of sampling layers, and number of multi-passes must be budgeted; on low-end devices, reduce the DPR, number of steps, number of particles, or disable heavy post-processing.
+ - Before delivery, you must confirm that the canvas is not empty, has the correct size, is not stretched after resize, and has no shader compile/link errors in the console.
## Expected Output
- 2D/3D 场景清晰、响应式、可清理，关键设备上接近 60fps；用户能通过替代文本或键盘路径理解/操作核心内容。
+ 2D/3D scenes are crisp, responsive, cleanable, and close to 60fps on key devices; users can understand/operate with core content via alt text or keyboard paths.