@flare-engine/render-web

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

@flare- engine/ landers fram- landers 的 CanvasKit 备份网络渲染器

中文使用文档
文档目录9 节
  1. 安装
  2. 入境点
  3. loadCanvasKit —— 说 loader.ts
  4. createWebSurface —— 说 web-surface.ts
  5. createWebSkiaModule —— 说 web-skia-module.ts
  6. createPostFxSurface —— 说 postfx-surface.ts
  7. 背景损失和恢复
  8. 结构说明
  9. 许可证

@flare-engine/render-web (英语)

Canvas Kit 备份的网络渲染器 @flare-engine/render. 提供WebGL地表,被接通到CanvasKit原始物的帧-后置模块,以及带有完整的乒乓荫道管的后处理地表.

安装

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

canvaskit-wasm 是一个可选的同伴依赖性——只在网络环境中需要.

入境点

loadCanvasKit —— 说 loader.ts

装入 CanvasKit WASM 二进制并返回已准备好 CanvasKit 举个例子 将 URL/路径到 canvaskit.wasm 二进制( 需要), 可选 onProgress(fraction) 下载回调和可选 LoadCanvasKitOptions (单位:千美元)stallMs,默认为15000; deadlineMs,默认的4500 绑定负载.

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

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

一个成功的负载被缓存——后来调回同样的例子. A 类 失败 负载没有被缓存: 稍后的呼叫重试从头开始,而不是被困在更早的拒绝上.

createWebSurface —— 说 web-surface.ts

创建基于 WebGL 的 WebGL CanvasKit 表面从一个 HTMLCanvasElement 返回 a WebSurface 控件 : canvas 联合国 CanvasLike 页:1 Renderer.setCanvas(), (中文(简体) ), ckCanvas (屏幕上画布和CanvasKit一样) Canvas,用于 drawPicture, (中文(简体) ), flush() 财务报告和审定财务报表 dispose()。直到 flush(). 回归 null 当 WebGL 不可用时.

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

适应 a CanvasKit 实例 FrameRendererModule 接口 @flare-engine/render是因为 createFrameRenderer组合 PictureRecorder, (中文(简体) ), Paint, (中文(简体) ), RSXform, (中文(简体) ), XYWHRect和荫道的助手.

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

创建一个 PostFxSurface 它拥有一个外屏的场景帆布,一个乒乓球中间体,和一个上屏的WebGL表面. 时 composite() 它运行呼叫器的时间 EffectChain 通过编译的 SKSL 阴影并擦去结果来显示.

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();

通过空的 new EffectChain() 用于零头通过(没有阴影编译).

composite() 读取 chain.globalIntensity ——价值 EffectChain.setGlobalIntensity, (中文(简体) ), PostFxController.setMotionScale 编辑 @flare-engine/a11y 桥面写作——所以从相框到相框的减动尺度. 过 composite(k) 仅在您要将新的全球强度写入链条时; 调用 composite(1) 每个相框都会在传阅前取消11式设定.

背景损失和恢复

sceneCanvas() 财务报告和审定财务报表 onscreenCanvas() 返回时 Canvas | null 两者都是 null ,而WebGL 语境丢失. PostFxSurface 自愈: 打开 webglcontextlost 它自己标记丢失并停止接触GPU对象(clear编号 :fadeTrail编号 :composite编号 :flush 成为无操作); 上 webglcontextrestored 它重建上下文和表面 在同一画布上,并重新澄清到最后的背景。 票价 isLost() 以驱动主机侧倒计时, 等待恢复 :

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

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

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

结构说明

  • @flare-engine/postfx 后端中性; render-web 提供 CanvasKit shim (SkiaPostFxModuleLike路线 RuntimeEffect.Make 给CanvasKit.
  • 乒乓圈在热道上是无分配的:在地表创建时,子阵列和矩抓缓冲被预先分配.
  • buildPass 被称作每个帧( 没有记忆) 因为 EffectChain 没有突变信号; 未来 buildPassInto 零空格形式在 @flare-engine/postfx 正确的修复.

见 API 规格 财务报告和审定财务报表 结构 给整个输油管.

许可证

阿帕奇 - 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 是什么?

@flare- engine/ landers fram- landers 的 CanvasKit 备份网络渲染器

如何安装 @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 和提交记录判断。