Two.js CanvasRenderer 详解:场景图到 `<canvas />` 的 2D 渲染管线
Two.js CanvasRenderer 详解:场景图到 <canvas /> 的 2D 渲染管线
导读
Two.CanvasRenderer 是 Two.js 三大内置渲染器(Canvas2D、SVG、WebGL)之一,负责把 Two.js 的场景图(scenegraph)绘制到原生 <canvas /> 元素上,适用于不需要 GPU 加速、追求轻量兼容的 Web 绘图场景。本文以官方文档 wiki/docs/renderers/canvas/README.md 为核心骨架,结合 src/renderers/canvas.js 源码与 tests/suite/canvas.js 测试用例,完整讲解其构造参数、实例属性、静态工具集、尺寸管理、渲染流程与高清屏(HiDPI)适配,让你既能开箱即用地创建 Canvas 渲染实例,也能理解底层绘制调用的来龙去脉。
一、Two.CanvasRenderer 是什么
Two.CanvasRenderer 继承自 Two.Events,是一个事件驱动的渲染类。当用 new Two({ type: Two.Types.canvas }) 构造 Two.js 实例时,Two 会在内部实例化该渲染器,用它把场景图中所有形状、文字、渐变、纹理对象逐帧绘制到 <canvas /> 上。
在 src/constants.js 中,三种渲染器类型被统一定义:
Types: {
webgl: 'WebGLRenderer',
svg: 'SVGRenderer',
canvas: 'CanvasRenderer',
}
而 src/two.js 的构造函数中正是通过 new Twothis.type 完成渲染器的实例化。也就是说,Two.Types.canvas 与 Two.CanvasRenderer 是一一对应的关系:前者是配置入口,后者是实际执行者。
从整体架构看,Two.js 是渲染器无关(renderer agnostic)的 API:同一套场景图、同一套绘图指令(move/line/curve/arc/close),可以分别落到 Canvas2D、SVG 和 WebGL 三种后端。CanvasRenderer 就是其中面向 Canvas2D 的适配层,它不参与图形计算,只负责把 Two.js 对象的变换矩阵、填充描边、透明度等状态翻译成 Canvas2D 上下文对应的 API 调用。
二、构造函数与参数详解
文档将构造参数归纳为一张表,结合 src/renderers/canvas.js 的实现,可得到如下完整参数说明:
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
parameters |
Object |
— | 由 new Two(...) 构造时继承传入的对象 |
parameters.domElement |
Element |
自动新建 | 要绘制的 <canvas />;不传则内部 document.createElement('canvas') 新建一个 |
parameters.overdraw |
Boolean |
true(文档)/ false(源码兜底) |
决定每次绘制前是否清空画布背景 |
parameters.smoothing |
Boolean |
true |
决定是否抗锯齿;处理像素画(pixel art)时应设为 false,可换用更廉价的插值算法从而提升性能 |
构造函数源码揭示了这几个参数的实际落地方式:
constructor(params) {
super();
// GPU 背书的画布上平滑与否差别可能不大
const smoothing = params.smoothing !== false;
this.domElement = params.domElement || document.createElement('canvas');
this.ctx = this.domElement.getContext('2d');
this.overdraw = params.overdraw || false;
if (typeof this.ctx.imageSmoothingEnabled !== 'undefined') {
this.ctx.imageSmoothingEnabled = smoothing;
}
this.scene = new Group();
this.scene.parent = this;
}
几个值得注意的细节:
smoothing通过imageSmoothingEnabled落地:它控制的是位图缩放插值算法的选择。设为false时使用最邻近插值(nearest-neighbor),对像素画缩放能保持锐利边缘,同时插值成本更低;overdraw影响是否清屏:默认清屏(文档默认true),源码中params.overdraw || false是不传时走false的兜底,因此若想保留上一帧内容做叠加绘制,应显式传入overdraw: true;- 不传
domElement时渲染器会自建画布:随后可通过two.renderer.domElement把它挂载到页面任意节点上。
三、实例属性速览
文档定义了四个核心实例属性,均可在构造后直接读写:
| 属性 | 含义 | 源码位置 |
|---|---|---|
domElement |
与 Two.js 场景关联的 <canvas /> |
canvas.js#L1097-L1101 |
ctx |
画布对应的 2D 绘图上下文(CanvasRenderingContext2D) |
canvas.js#L1103-L1107 |
overdraw |
每次 draw call 是否清空画布背景 | canvas.js#L1109-L1114 |
scene |
场景图的根 Group,所有绘制对象都挂在其下 | canvas.js#L1120-L1125 |
其中 scene 尤其关键——它就是 two.scene 的同一份引用(src/two.js 中 this.scene = this.renderer.scene)。由于 Group 本身携带变换矩阵,你可以直接对 scene 施加整体位移、旋转或缩放,实现类似"反摄像机"的全局视角控制。
四、静态工具集 Utils:渲染分发中枢
文档将其描述为"一个庞大的、装满工具函数与属性的对象"。在源码中它以 static Utils = canvas(canvas.js#L1132)暴露,是一张"渲染分发表"。其内部结构(canvas.js#L27-L1078)包括:
isHidden:正则/(undefined|none|transparent)/i,用于判断填充/描边是否为不可见状态,避免无效绘制;alignments/baselines:把 Two.js 的left/middle/right对齐方式映射为 Canvas2D 的start/center/end,把top/middle/bottom/baseline映射为top/middle/bottom/alphabetic,供文字渲染使用;getRendererType(type):根据对象内部_renderer.type返回对应的渲染函数名,未知类型统一回退到path;group.render/group.renderChild:负责 Group 级联渲染——递归调用子对象的渲染函数,并在此处完成矩阵变换(ctx.transform)、透明度叠加(this._opacity * parent._renderer.opacity)以及遮罩(mask)处理;path.render:核心路径绘制函数,把 Two.js 的命令序列(Commands.move / line / curve / arc / close)逐一翻译为moveTo / lineTo / bezierCurveTo / closePath,并统一处理填充、描边、线宽、线帽、虚线(setLineDash)、裁剪(clip)与透明度(globalAlpha);points.render:以arc(x, y, radius, 0, TWO_PI)方式把点集渲染为一组圆点;text.render:把字体样式、对齐、基线、text-decoration 等翻译为fillText / strokeText / measureText调用;linear-gradient.render/radial-gradient.render:分别调用ctx.createLinearGradient与ctx.createRadialGradient,并把颜色 stops 转换为addColorStop;texture.render:调用ctx.createPattern生成填充纹理;renderSvgArcCommand:按 SVG 规范把椭圆弧参数还原为圆心、起止角并逐段折线近似。
这个 Utils 对象之所以是"静态的",是因为它不需要随实例复制——每个渲染实例共用同一套绘制函数,实例状态则存放在各对象自己的 _renderer 字段中。整个场景树的绘制,本质上就是一次从 scene 出发、沿着父子层级对 Utils 分发表的递归调用。
五、setSize 与 HiDPI 高清屏适配
setSize(width, height, ratio) 用于改变渲染器尺寸,并触发 event:resize 事件。文档给出的参数语义与源码实现(canvas.js#L1143-L1160)完全对应:
| 参数 | 说明 |
|---|---|
width |
渲染器的新宽度(逻辑像素) |
height |
渲染器的新高度(逻辑像素) |
ratio |
新的像素比(像素密度);不传时默认按用户屏幕像素密度计算 |
setSize(width, height, ratio) {
this.width = width;
this.height = height;
this.ratio = typeof ratio === 'undefined' ? getRatio(this.ctx) : ratio;
this.domElement.width = width * this.ratio;
this.domElement.height = height * this.ratio;
if (this.domElement.style) {
_.extend(this.domElement.style, {
width: width + 'px',
height: height + 'px',
});
}
return this.trigger(Events.Types.resize, width, height, ratio);
}
这里做的是标准的 HiDPI 双缓冲技巧:画布的实际位图尺寸放大为 width * ratio,而 CSS 尺寸保持 width px,从而在 Retina 屏上获得清晰锐利的矢量输出。ratio 的默认计算逻辑在 src/utils/device-pixel-ratio.js:
function getRatio(ctx) {
return devicePixelRatio / getBackingStoreRatio(ctx);
}
即"设备像素比 ÷ 画布后缓冲像素比"(backing store ratio 取各浏览器厂商前缀属性或兜底 1)。当两者都为 1 时,ratio 恒为 1,画布就是 1:1 位图,render() 中也就免去了缩放步骤。
六、render:一帧的完整绘制流程
render()(canvas.js#L1167-L1186)把当前场景绘制到画布上,流程分三步:
render() {
const isOne = this.ratio === 1;
if (!isOne) {
this.ctx.save();
this.ctx.scale(this.ratio, this.ratio);
}
if (!this.overdraw) {
this.ctx.clearRect(0, 0, this.width, this.height);
}
canvas.group.render.call(this.scene, this.ctx);
if (!isOne) {
this.ctx.restore();
}
return this;
}
- 按 ratio 缩放上下文:当
ratio !== 1时先save再scale(ratio, ratio),让后续所有绘制都发生在逻辑坐标空间,避免逐对象换算; - 按 overdraw 决定清屏:
overdraw为false(默认)时用clearRect(0, 0, width, height)清空画布,保证上一帧内容不残留;为true时则不清屏,适合需要叠影/尾迹效果的场合; - 递归渲染场景图:以
scene为入口调用Utils.group.render,沿 children 树一路递归到每个叶子对象。
整个链路在 Two.js 层面由 update() 与 render() 串联(src/two.js):update() 先统一完成位置、矩阵等计算并触发 update 事件,随后调用 render(),后者执行 this.renderer.render() 并触发 render 事件。若使用 autostart 或调用 two.play(),该链路会通过 requestAnimationFrame 自动循环,实现动画帧的持续输出。
七、实战示例:创建与使用 Canvas 渲染器
下面是创建一个 Canvas 渲染实例并追加图形的最简流程:
// 方式一:显式指定 type,渲染器自建 <canvas />
const two = new Two({
type: Two.Types.canvas,
width: 400,
height: 400,
smoothing: false, // 像素画场景可关闭抗锯齿以提升性能
});
// 方式二:传入已有 <canvas />,domElement 会覆盖 type 推断
// const elem = document.getElementById('drawing');
// const two = new Two({ domElement: elem, width: 400, height: 400 });
// 绘制内容
const circle = two.makeCircle(200, 200, 100);
circle.fill = '#4A90D9';
circle.stroke = '#333';
circle.linewidth = 4;
two.appendTo(document.body);
// 显式触发一帧
two.update();
要点说明:
width/height缺省时 Two 使用640 x 480(见 src/two.js);- 渲染器对象通过
two.renderer访问,two.renderer.domElement即为实际画布节点; - 若不传
domElement,可通过two.appendTo(...)把自建画布挂入 DOM; - 动画场景请使用
two.play()或autostart: true,让update → render自动循环。
在 tests/suite/canvas.js 中,官方测试全部采用同一模式验证各图形类型的 Canvas 渲染结果,例如:
var two = new Two({
type: Two.Types.canvas,
width: 400,
height: 400,
ratio: deviceRatio,
});
测试仓库 tests/images/canvas/ 下保存了各用例的渲染输出参考图。下图分别是 Circle 与 Text 用例的 1x/2x 输出,可作为 CanvasRenderer 渲染效果的直观对照:
此外,如需在 Node/无浏览器环境使用 Canvas 渲染器,项目 README(README.md)提供了基于 node-canvas 的 headless 方案:先用 createCanvas(width, height) 创建画布,再通过 Two.Utils.polyfill(canvas, Image) 注入环境,之后即可用同样的 Two.js 场景图 API 在服务端逐帧输出图片。
八、尺寸联动与事件机制
setSize 并非只由用户手动触发。Two.js 提供了三个自动联动入口(src/two.js):
- 构造阶段:传入
width/height时立即调用renderer.setSize(params.width, params.height, this.ratio)(src/two.js); fitted: true:监听父元素尺寸变化并同步setSize;fullscreen: true:跟随窗口尺寸变化同步setSize。
同时 Two 内部通过 this.renderer.bind(Events.Types.resize, updateDimensions.bind(this))(src/two.js)订阅 resize 事件,把渲染器的新尺寸回写到 Two 实例的 width/height,保证 Two 层与渲染器层尺寸始终一致。
九、使用注意事项
overdraw语义容易混淆:文档默认值为true(每次清屏),而源码兜底为false;实际行为以实例上的overdraw属性为准,需要叠加绘制时务必显式传入true;smoothing关闭的场景:像素画、复古风或需要对图片/纹理做最近邻缩放时再关闭,其余场景保持默认即可获得更平滑的视觉效果;ratio默认跟随屏幕:在 DPR=1 的普通屏上ratio恒为 1;跨设备分发图片内容(如测试中的 1x/2x 参考图)时,建议显式指定ratio以保证输出尺寸可控;- 绘图状态隔离:
CanvasRenderer在遇到非默认矩阵或存在 mask 时才会save/restore(canvas.js#L83-L112),这是性能上的有意取舍,正常使用不受影响。
综上,Two.CanvasRenderer 是一个职责单一、状态透明的渲染后端:构造参数直接映射到 Canvas2D 上下文的开关,实例属性完整暴露画布与场景根节点,静态 Utils 承担全部绘制翻译工作,而 setSize/render 则把 HiDPI 适配与逐帧绘制封装成两个干净的方法。理解了这条从 Two.js 场景图到 Canvas2D 的映射管线,你就能在 Canvas、SVG、WebGL 三种后端之间自如切换,并用最少的心智负担写出跨端一致的 2D 绘图代码。

