visual

一个 PixiJS 风格的 2D 渲染引擎。构建由图形组成的场景树，并通过三种后端之一（Canvas2D、WebGL 或 WebGPU）在运行时渲染。

引擎分层为 Application（生命周期 / 渲染循环）→ Renderer（渲染后端）→ 由 Container（组）组成的场景树 → Graphics（可绘制对象）。你把节点添加到 app.stage 上，渲染器就会绘制它们。

仅限浏览器。 ranuts/visual 需要真实的 HTMLCanvasElement 以及 GPU / Canvas 上下文，无法在 Node 中运行。

导入

import { Application, Graphics, Container } from 'ranuts/visual';

快速上手

创建一个 application，绘制一个带填充和描边的矩形以及一个圆形，然后启动渲染循环。

import { Application, Graphics, RENDERER_TYPE } from 'ranuts/visual';

const view = document.querySelector('canvas');

// Application.create 是异步的——WebGPU 后端的设备初始化是异步的，
// 必须在首次 render 之前完成。
const app = await Application.create({
  view,
  prefer: RENDERER_TYPE.CANVAS, // CANVAS | WEB_GL | WEB_GPU
  backgroundColor: '#1e1e1e',
});

// 一个矩形：红色填充 + 4px 蓝色描边。
const rect = new Graphics();
rect.beginFill('#ff0000');
rect.lineStyle(4, '#0000ff');
rect.drawRect(20, 20, 160, 100);
rect.endFill();

// 一个圆形。
const circle = new Graphics();
circle.beginFill('#00cc88', 0.8);
circle.drawCircle(300, 120, 60);
circle.endFill();

// 将可绘制对象添加到 stage 上——它是一切待渲染元素的祖先。
app.stage.addChild(rect);
app.stage.addChild(circle);

// 启动 requestAnimationFrame 渲染循环（或调用 app.render() 只渲染一帧）。
app.start();

API

Application

引擎入口。它持有 canvas、渲染器以及场景树的根节点（stage）。

推荐使用异步工厂 Application.create(...) 而非 new Application(...)：WebGPU 后端的设备初始化是异步的，必须在首次 render 之前完成。Canvas / WebGL 会立即 resolve，因此该工厂对所有后端都是安全且一致的。

Application.create(options)

static async。构造一个 Application 并等待渲染器完成异步初始化。

参数

返回

属性

方法

IApplicationOptions

Container

组节点，即场景树中的“组”概念。它持有子节点与变换状态，但自身不渲染任何内容；Graphics 等可绘制对象继承自它。用 Container 可以把需要一起平移 / 缩放 / 旋转的子树组合在一起。

方法

变换与显示属性

以下属性位于共享基类（Vertex）上，每个 Container / Graphics 都可用。

Graphics

继承自 Container 的可绘制对象。先设置填充 和/或 线条样式，再调用形状方法。大多数方法返回 this，可链式调用。

样式

形状

路径

IFillStyleOptions

ILineStyleOptions

继承 IFillStyleOptions，并增加：

枚举

RENDERER_TYPE

通过 IApplicationOptions.prefer 选择渲染后端。

SHAPE_TYPE

Graphics 绘制方法所产生的形状类型。

LINE_CAP

LINE_JOIN

常量

渲染后端

后端由 IApplicationOptions.prefer（一个 RENDERER_TYPE）决定；省略时默认使用 Canvas。

• CANVAS 直接通过 Canvas2D API 绘制（fillRect、arc、ctx.stroke() 等）。
• WEB_GL 和 WEB_GPU 共用同一套 BatchRenderer 管线：将形状三角化，打包进单个交错的顶点缓冲区，然后一次性绘制。

三种后端都接受任意 CSS 颜色：十六进制（#rgb / #rrggbb）、颜色名、rgb()、hsl() 都会被一致地解析。

描边几何因后端而异，这是设计使然。 线帽与线接在 Canvas 后端由浏览器原生的 ctx.stroke() 绘制，而在 WebGL / WebGPU 后端则由自定义三角化实现。两者并非逐像素一致。