Two.js CanvasRenderer 详解:场景图到 `<canvas />` 的 2D 渲染管线

原创2026-09-24 14:47:191,965 阅读
文章标签:图形学前端

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;
}
  1. 按 ratio 缩放上下文:当 ratio !== 1 时先 save 再 scale(ratio, ratio),让后续所有绘制都发生在逻辑坐标空间,避免逐对象换算;
  2. 按 overdraw 决定清屏:overdraw 为 false(默认)时用 clearRect(0, 0, width, height) 清空画布,保证上一帧内容不残留;为 true 时则不清屏,适合需要叠影/尾迹效果的场合;
  3. 递归渲染场景图:以 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 渲染效果的直观对照:

CanvasRenderer 渲染的圆形描边测试图

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 绘图代码。

登录后查看全文
two.js