@flare-engine/render-web

中文文档
0.4.12发布于 2026/11/13Apache-2.0TypeScriptESM + CJS构建来源已验证近 30 天下载 1995

CanvasKit-backed web renderer for @flare-engine/render frame-renderer

原始使用文档
文档目录9 节
  1. Install
  2. Entry points
  3. loadCanvasKit — loader.ts
  4. createWebSurface — web-surface.ts
  5. createWebSkiaModule — web-skia-module.ts
  6. createPostFxSurface — postfx-surface.ts
  7. Context loss and restore
  8. Architecture notes
  9. License

@flare-engine/render-web

CanvasKit-backed web renderer for @flare-engine/render. Provides a WebGL surface, a frame-renderer module wired to CanvasKit primitives, and a post-processing surface with a full ping-pong shader pipeline.

Install

bun add @flare-engine/render-web canvaskit-wasm

canvaskit-wasm is an optional peer dependency — only required in web environments.

Entry points

loadCanvasKit — loader.ts

Loads the CanvasKit WASM binary and returns a ready CanvasKit instance. Takes the URL/path to the canvaskit.wasm binary (required), an optional onProgress(fraction) download callback, and an optional LoadCanvasKitOptions (stallMs, default 15000; deadlineMs, default 45000) bounding the load.

import { loadCanvasKit } from '@flare-engine/render-web';

const kit = await loadCanvasKit('/canvaskit.wasm', undefined, { stallMs: 10_000, deadlineMs: 30_000 });

A successful load is cached — later calls return the same instance. A failed load is not cached: a later call retries from scratch instead of being stranded on the earlier rejection.

createWebSurface — web-surface.ts

Creates a WebGL-backed CanvasKit surface from an HTMLCanvasElement and returns a WebSurface handle: canvas (a CanvasLike for Renderer.setCanvas()), ckCanvas (the same on-screen canvas as CanvasKit's Canvas, for drawPicture), flush() and dispose(). Nothing appears on screen until flush(). Returns null when WebGL is unavailable.

import type { CanvasKit } from 'canvaskit-wasm';
import { createWebSurface } from '@flare-engine/render-web';

declare const kit: CanvasKit;
declare const canvasEl: HTMLCanvasElement;

const web = createWebSurface(kit, canvasEl);
if (!web) throw new Error('WebGL unavailable');

// ...draw through web.canvas / web.ckCanvas each frame...
web.flush();    // present

// Teardown:
web.dispose();

createWebSkiaModule — web-skia-module.ts

Adapts a CanvasKit instance into the FrameRendererModule interface consumed by @flare-engine/render's createFrameRenderer. Wraps PictureRecorder, Paint, RSXform, XYWHRect, and shader helpers.

import type { CanvasKit } from 'canvaskit-wasm';
import type { SkImageLike } from '@flare-engine/assets';
import type { SpriteDrawCommand } from '@flare-engine/render';
import { createWebSkiaModule, createWebSurface } from '@flare-engine/render-web';
import { createFrameRenderer } from '@flare-engine/render';

declare const kit: CanvasKit;
declare const width: number;
declare const height: number;
declare const atlasImage: SkImageLike;
declare const commands: SpriteDrawCommand[];
declare const canvasEl: HTMLCanvasElement;

const mod = createWebSkiaModule(kit);
const renderer = createFrameRenderer(mod);

// Present onto a WebGL-backed CanvasKit surface.
const web = createWebSurface(kit, canvasEl);
if (!web) throw new Error('WebGL unavailable');
const canvas = web.ckCanvas;

renderer.beginFrame(width, height, 0, 1);
renderer.drawAtlas(atlasImage, commands);
const picture = renderer.endFrame();
// endFrame() returns the backend-neutral PictureLike; cast to CanvasKit's Picture to present.
// The caller owns the picture: delete it once drawn, or each frame leaks a WASM-side object.
if (picture) {
  const ckPicture = picture as Parameters<typeof canvas.drawPicture>[0];
  canvas.drawPicture(ckPicture);
  ckPicture.delete();
}
web.flush();

createPostFxSurface — postfx-surface.ts

Creates a PostFxSurface that owns an offscreen scene canvas, a ping-pong intermediate, and an onscreen WebGL surface. At composite() time it runs the caller-supplied EffectChain through compiled SkSL shaders and blits the result to screen.

import type { Canvas, CanvasKit } from 'canvaskit-wasm';
import { createPostFxSurface } from '@flare-engine/render-web';
import { EffectChain, createVignette, createBloom } from '@flare-engine/postfx';

declare const kit: CanvasKit;
declare const canvasEl: HTMLCanvasElement;
declare const newW: number;
declare const newH: number;
declare function drawHud(canvas: Canvas): void;

const chain = new EffectChain();
chain.add(createVignette('vig', { intensity: 0.6, radius: 0.8 }));
chain.add(createBloom('bloom', { threshold: 0.5, intensity: 0.9 }));

const surface = createPostFxSurface(kit, canvasEl, chain);
if (!surface) throw new Error('WebGL unavailable');

// Game loop:
surface.clear([0, 0, 0]);
// ...draw to surface.sceneCanvas()...
surface.composite();        // runs the shader chain at chain.globalIntensity, presents to onscreenCanvas()

// Draw crisp overlays AFTER composite() but BEFORE flush(). Null while the context is lost.
const overlay = surface.onscreenCanvas();
if (overlay) drawHud(overlay);

surface.flush();            // present the frame

// On resize:
surface.resize(newW, newH);
surface.clear([0, 0, 0]);

// Teardown:
surface.dispose();

Pass an empty new EffectChain() for a zero-overhead passthrough (no shader compilation).

composite() reads chain.globalIntensity — the value EffectChain.setGlobalIntensity, PostFxController.setMotionScale and the @flare-engine/a11y bridge write — so a reduced-motion scale holds from frame to frame. Pass composite(k) only when you mean to write a new global intensity into the chain; calling composite(1) every frame would undo the a11y setting before the pass reads it.

Context loss and restore

sceneCanvas() and onscreenCanvas() return Canvas | null — both are null while the WebGL context is lost. PostFxSurface self-heals: on webglcontextlost it marks itself lost and stops touching GPU objects (clear/fadeTrail/composite/flush become no-ops); on webglcontextrestored it rebuilds the context and surfaces on the same canvas and re-clears to the last background. Poll isLost() to drive a host-side fallback while recovery is pending:

import type { PostFxSurface } from '@flare-engine/render-web';

declare const surface: PostFxSurface;
declare function showStaticFallback(): void;

if (surface.isLost()) showStaticFallback();

Architecture notes

  • @flare-engine/postfx is backend-neutral; render-web provides the CanvasKit shim (SkiaPostFxModuleLike) that routes RuntimeEffect.Make to CanvasKit.
  • The ping-pong loop is allocation-free in the hot path: the children array and rect scratch buffer are pre-allocated at surface creation.
  • buildPass is called every frame (no memoization) because EffectChain has no mutation signal; a future buildPassInto zero-alloc form in @flare-engine/postfx is the correct fix.

See API spec and architecture for the full rendering pipeline.

License

Apache-2.0

版本与发布记录

@flare-engine/render-web 共发布 16 个版本,首次发布于 2026/07/01;过去 12 个月发布了 16 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.4.12latest2026/11/133 天前
0.4.112026/11/123 天前
0.4.102026/11/087 天前
0.4.82026/11/0610 天前
0.4.72026/11/0411 天前
0.4.62026/10/3115 天前

关于 @flare-engine/render-web 的常见问题

@flare-engine/render-web 是什么?

CanvasKit-backed web renderer for @flare-engine/render frame-renderer

如何安装 @flare-engine/render-web?

在项目目录运行 npm install @flare-engine/render-web,或使用 pnpm add / yarn add / bun add。

@flare-engine/render-web 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@flare-engine/render-web 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@flare-engine/render-web 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=20。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@flare-engine/render-web 可以商用吗?

@flare-engine/render-web 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@flare-engine/render-web 的下载量有多少?

根据 npm 官方下载统计,@flare-engine/render-web 在 2026/10/15 – 2026/11/13 这 30 天内被下载 1,995 次,日均约 67 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@flare-engine/render-web 还在维护吗?

最新版本 0.4.12 发布于 2026/11/13(3 天前);至今共发布 16 个版本,其中过去 12 个月发布了 16 个;首次发布于 2026/07/01。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。