# @babylonjs/lite-gl 中文文档

规范地址：https://npmcn.com/package/%40babylonjs/lite-gl/

版本：1\.20\.1
npm 元数据更新时间：2026-11-04T18:24:32.922Z
中文译文更新时间：2026-11-07T17:43:29.554Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40babylonjs/lite-gl
原文对照：https://npmcn.com/package/%40babylonjs/lite-gl/?lang=original
项目主页：https://github.com/BabylonJS/Babylon-Lite/tree/main/packages/babylon-lite-gl
源码仓库：https://github.com/BabylonJS/Babylon-Lite

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.1 MB，113 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-06-25T14:20:17.248Z
- 最新版本发布：2026-11-04T18:24:32.726Z
- 近 30 天下载量：3585（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：26（近 12 个月 26 个）

## 中文简介

基于函数,可树可摇动的WebGL2微引擎用于全屏效果,斯匹特和动态纹理——由@babylonjs/lite的WebGL对应.

## 安装

```sh
npm install @babylonjs/lite-gl
```

也可以使用：`pnpm add @babylonjs/lite-gl`、`yarn add @babylonjs/lite-gl`、`bun add @babylonjs/lite-gl`

## README

# @babylonjs/lite-gl (英语)

一点点, **基于函数的可树动WebGL2微引擎** 用于全屏 阴影效应、图示和动态纹理——WebGL对应的 [`@babylonjs/lite`](https://github.com/BabylonJS/Babylon-Lite)没有上课,没有 场景图: 您在不透明的情况下调用普通函数 `GLEngineContext`,所以一个 绑匪只保留你进口的东西.

这是Babylon.js 渲染出原始物的焦点子集 **几乎相同** (在±1–2 LSB ANGLE / SwiftShader 编码源噪声内) 巴比伦的 `ThinEngine` 编号 : `EffectRenderer` 编号 : `SpriteRenderer` 编号 : `HtmlElementTexture` 路径 – 每个功能都有相邻对等场景 : `tests/gl/parity/` (和, 下游,是"NeonBrush效应套房". 盗用 `@babylonjs/core` (单位:克) 通常缩小效应的运出捆绑 **~10–16x (英语)** (XQQ4-6 KB gzip vs (原始内容存档于2018-10-28). QQ40–80 KB.

> **仅WebGL2.** 创建背景 `canvas.getContext("webgl2")`。 。 。 .

## 安装

```bash
npm install @babylonjs/lite-gl
```

## 快速启动——动画全屏效果

```ts
import { createGLEngine, createEffectWrapper, applyEffectWrapper, drawEffect, setViewport, setEffectFloat, runRenderLoop, resizeGLEngine } from "@babylonjs/lite-gl";

const canvas = document.getElementById("renderCanvas") as HTMLCanvasElement;
const engine = createGLEngine(canvas, { alpha: false });

// The wrapper compiles + owns the effect. `vertexSource` defaults to a built-in
// fullscreen-quad shader (exposing a `vUv` varying), so only `fragmentSource`
// is required.
const wrapper = createEffectWrapper(engine, {
    name: "gradient",
    fragmentSource: `#version 300 es
        precision highp float;
        in vec2 vUv;
        out vec4 glFragColor;
        uniform float uTime;
        void main() {
            glFragColor = vec4(0.5 + 0.5 * cos(uTime + vUv.xyx + vec3(0.0, 2.0, 4.0)), 1.0);
        }`,
    uniformNames: ["uTime"],
});

const start = performance.now();
runRenderLoop(engine, () => {
    resizeGLEngine(engine);
    setViewport(engine);
    // false (and nothing bound) until the shaders finish compiling asynchronously
    if (!applyEffectWrapper(wrapper)) return;
    setEffectFloat(wrapper.effect, "uTime", (performance.now() - start) / 1000);
    drawEffect(engine);
});
```

## 效果准备和错误

`createEffect` 编号 : `createEffectWrapper` 提交汇编和链接而无需 询问结果 。 与 `KHR_parallel_shader_compile`,准备状态检查 在检查链接状态前完成投票。 阴影状态和信息日志为 仅在链接失败后询问, 避免过早的编译停顿 . 没有扩展,检查链接状态可以被屏蔽.

手动保留投票时间:打电话 `isEffectReady(effect)` 在你身边 进行循环检查 `getEffectCompilationError(effect)` 当它 返回错误。 误入误入误入误入误入误入误入误入误入误入误入误入误入误入误入误入误入误入误入误入误入误入误入误入误入误入误入误入误入误入误入误入误入误入误入误入误入误入误入误入误入误入误入误入误入误入误入误入误入误出误入误入误入误入误入误入误入误入误入误入误入误入误入误入误入误出误入误入误入误入误入误入误入误入误入误入误出误入误入误入误入误出误入误入误入误入误入误入误入误入误出误入误入误入误入误入误入误入误入误入误入误入误入误入误入误入误入误入误入误入误入误入误入误入误入误入误入误入误入误入误入误入误入误入误入误入误入误; `null` 这意味着没有失败 被记录,不一定 效果已经就绪。 错误包括: 程序日志和失败的阴影级日志并被记录一次 。 不是这个 访问者或 `executeWhenCompiled` 开始自动投票.

要等待启动渲染回路, 请选择可树动的帮助 :

```ts
import { waitForEffect } from "@babylonjs/lite-gl";

const controller = new AbortController();
try {
    await waitForEffect(wrapper.effect, { signal: controller.signal });
    // The effect is finalized; rendering can now start.
} catch (error) {
    console.error("Effect could not become ready:", error);
}
```

每个动画框的助推投票一次,没有记录渲染回路. 它拒绝在编译/链接/恢复失败、上下文损失、处置(下一次) 或通过 `controller.abort()`,并清理其框架和 每个出口都有听众 取消等待不会处理共享效果 . 在进行上下文修复后,再打电话等待替换程序. 已经准备好的效应在未安排框架的情况下解决;仅限消费者 使用人工投票船 没有帮助者列表代码.

**移徙:** 阴影语法错误不再同步抛出 `createEffect` 或者说 `createEffectWrapper`. Poll (英语) `isEffectReady` 检查 `getEffectCompilationError`,或者抓一个被拒绝的 `waitForEffect` 答应我. 包装,通过 `wrapper.effect` 这些准备/反应的API. 阴影/ 程序分配失败仍然同步抛出 .

### 升级: 更改类型检查器无法抓取

大部分接收器先重塑表面作为编译错误. 这些变化 仍在编译但改变行为,所以用手检查:

-   **`applyEffectWrapper(wrapper)` 返回时 `boolean`。 。 。 .** 打开 `false` (还在) 编译、失败、处置或上下文丢失) 设置和 `drawEffect`,或针对当前程序 从前 lite-gl 故意不为您清除程序, 所以主机 共享上下文保留他们的 GL 状态.
-   **`createHtmlElementTexture` 默认为无 mips 的线性过滤** (原为TRILINEAR + mips.). 以 `{ ...getSamplingModeFilters(GLSamplingMode.TRILINEAR, true) }` 打电话 `generateTextureMipMaps(tex)`。 。 。 .
-   **`updateHtmlElementTexture`是因为 `invertY` 原生为 `UNPACK_FLIP_Y`视频 包含.** 巴比伦翻转视频 `!invertY`;这些调用为 `{ invertY: !invertY }`。 。 。 .

## 入境点

整个公共API可以从单曲中获取 `@babylonjs/lite-gl` 条目 : 引擎 + 渲染回路、 效果和统一设置、 纹理( 包括浮点/ HDR +) 动态) `EffectWrapper` 全屏正方形渲染器,制成目标,网点/ 顶点-索引缓冲器 + 令人不快,深度 / stencil / 彩色-mask / clear, scissor,, 混合模式、图示渲染器和HTML元素纹理。 软件包是 `sideEffects: false`因此,一个捆绑的树摇走 无论你没有的特性 使用时.

### 核心 API (`@babylonjs/lite-gl`(中文(简体) )

-   **发动机/生命周期** —— 说 `createGLEngine`, (中文(简体) ), `disposeGLEngine`, (中文(简体) ), `resizeGLEngine`, (中文(简体) ), `getRenderWidth`, (中文(简体) ), `getRenderHeight`, (中文(简体) ), `get/setHardwareScalingLevel`, (中文(简体) ), `getRenderingCanvas`,以及 `on/offContextLost` + 键 `on/offContextRestored` (文字-损失处理:效果和纹理在恢复时重建).
-   **渲染循环** —— 说 `runRenderLoop`, (中文(简体) ), `stopRenderLoop`附加时 `beginFrame` 编号 : `endFrame` 为驱动自己帧的宿主.
-   **GPU 帧时间( 可选)** —— 说 `captureGPUFrameTime`, (中文(简体) ), `getGPUFrameTimeCounter` (单位:千美元)`EXT_disjoint_timer_query_webgl2`巴比伦的 `ThinEngine` API,除被导入外为树形).
-   **效果** —— 说 `createEffect`, (中文(简体) ), `isEffectReady`, (中文(简体) ), `getEffectCompilationError`, (中文(简体) ), `executeWhenCompiled`, (中文(简体) ), `waitForEffect` (可选择的准备承诺), `useEffect`, (中文(简体) ), `disposeEffect`,以及缓存的制服设置 `setEffectFloat` 编号 : `…Float2` 编号 : `…Float3` 编号 : `…Float4` 编号 : `…Int` 编号 : `…Color3` 编号 : `…Color4` 编号 : `…Texture`。 。 。 .
-   **全屏渲染器** —— 说 `createEffectWrapper`, (中文(简体) ), `applyEffectWrapper`, (中文(简体) ), `drawEffect`, (中文(简体) ), `setViewport`, (中文(简体) ), `disposeEffectWrapper`包装纸总是 效果( 没有) `setEffectWrapper`(三); `applyEffectWrapper` 返回时 `false` 并没有任何束缚 直到效果准备好, 所以跳过框的设置和 提取 `false`。 。 。 . `drawEffect` 懒惰地创造和束缚着共同的四角本身, 因此,可以不带包装就可以绘制出现有的效果: `isEffectReady` → `useEffect` \* 设置 \* `drawEffect`。 。 。 .
-   **纹理** —— 说 `createRawTexture` (类型-阵列上传, LDR 字节格式), `createTextureFromSource` (从已解码的位图/ canvases/图像上传), `createTexture3DFromPixels` + 键 `setEffectTexture3D` (可选本地 RGBA8) 具有三线性采样和零2D只捆绑成本的LUT卷, `createFloatTexture` (浮动/半浮动人类发展报告选入), `generateTextureMipMaps`, (中文(简体) ), `loadTexture2D` (使用 1×1 个占位符同步 URL上传), `bindTexture`, (中文(简体) ), `disposeTexture`, (中文(简体) ), `isTextureReady`附加时 `updateRawTexture`, (中文(简体) ), `updateTextureSamplingMode` (草过滤器), `updateTextureSamplingPreset` (婴儿预设 + `generateMipMaps`, (中文(简体) ), `updateTextureWrapMode`, (中文(简体) ), `createTextureFromHandle`。每个纹理创建者 一样 `GLTextureOptions` (单位:千美元)`invertY`, (中文(简体) ), `premultiplyAlpha`过滤器 / 包装)。 巴比伦式 `GLSamplingMode` 预设解析 选入 `getSamplingModeFilters`· ; `generateTextureMipMaps` 建立链条 并保持其在后上传和上下文恢复时的电流.
-   **动态纹理** —— 说 `createDynamicTexture`, (中文(简体) ), `updateDynamicTexture`, (中文(简体) ), `clearDynamicTextureSource` (保留来源在上下文重放). `updateRawTexture` 编号 : `updateDynamicTexture` 编号 : `updateHtmlElementTexture` 带 选项 `GLTextureUpdateOptions` (单位:千美元)`invertY`, (中文(简体) ), `premultiplyAlpha`) (中文(简体) ).
-   **目标** —— 说 `createRenderTarget` (RGBA8 FBO,或单/双通道) `R8` 编号 : `RG8` 通过 `format: gl.RED` 编号 : `gl.RG`,带有可采样的颜色 `GLTexture` + 可选深度 / 质地缓冲器 , `createFloatRenderTarget` (浮动/半浮动人类发展报告选入), `bindRenderTarget` (划)/(划) `restoreDefaultFramebuffer` (回到画布上), `resizeRenderTarget`, (中文(简体) ), `generateRenderTargetMipMaps`, (中文(简体) ), `readRenderTargetPixels` (CPU回读 选项 `{ x, y, width, height, into, format }` 默认整个目标, 财务报告和审定财务报表 `format` 读取 `RED` 编号 : `RG` 目标紧凑, `readRenderTargetPixelsToBuffer` (同为一 `PIXEL_PACK_BUFFER` 在一个字节 `offset`, (中文(简体) ), `disposeRenderTarget`。 。 。 .
-   **Meshes / 缓冲器** —— 说 `createVertexBuffer`, (中文(简体) ), `updateVertexBuffer`, (中文(简体) ), `createIndexBuffer`, (中文(简体) ), `bindAttributes`, (中文(简体) ), `drawIndexed` (已执行), `disposeBuffer`。 。 。 .
-   **深度 / stencil / 剪切器** —— 说 `setDepthState`, (中文(简体) ), `setStencilState`, (中文(简体) ), `setStencilOpSeparate` (独立前后行动), `setCullState`, (中文(简体) ), `setColorMask`, (中文(简体) ), `clearEngine`· ; `setScissor`, (中文(简体) ), `disableScissor`。 。 。 .
-   **组合** —— 说 `setBlendMode` + 键 `GLBlendMode` (单位:千美元)`DISABLE` 编号 : `ADD` 编号 : `ALPHA` 编号 : `PREMULTIPLIED`),匹配巴比伦语 `setAlphaMode` 参数.
-   **文本( 块)** ——解析,解析独立 glyph 渲染,WebGL2 与Lite的对应 `TextRenderer`数字 : `loadFont` 编号 : `createFontFromBuffer`, (中文(简体) ), `createDefaultTextData` 编号 : `updateDefaultTextData` 编号 : `disposeDefaultTextData` (形状+提取+包在一个呼叫中),或 `createGlyphStorage` + 键 `createTextData` 编号 : `updateTextData` 编号 : `disposeTextData` 驱动自己的布局; `createTextLayer` 编号 : `setTextLayerPosition`, (中文(简体) ), `createTextRenderer`, (中文(简体) ), `registerTextRenderer` 编号 : `unregisterTextRenderer` 编号 : `renderText` 编号 : `isTextRendererReady`,以及可选的合成-重量设置器 `setFontWeightOffset` (它的遮蔽器只在您导入时被捆绑). 文本使用 `text-shaper` 用于塑造;是一种依赖,而不是由 从未导入文本 API 的消费者。 见 [文本](https://npmcn.com/package/%40babylonjs/lite-gl/#readme-text-slug) 见下文.

### 文本( 块)

```ts
import { createGLEngine, loadFont, createDefaultTextData, createTextLayer, createTextRenderer, registerTextRenderer } from "@babylonjs/lite-gl";

const engine = createGLEngine(canvas);
const font = await loadFont("/fonts/Inter-Regular.ttf");
const data = createDefaultTextData(font, 48, "Hello, WebGL2", [1, 1, 1, 1]);
const layer = createTextLayer(data, { positionPx: { x: 24, y: 80 } });
const renderer = createTextRenderer(engine, { layers: [layer], clearValue: { r: 0.1, g: 0.1, b: 0.12 } });
registerTextRenderer(renderer); // draws every frame; unregisterTextRenderer to stop
```

Glyph 轮廓作为四相曲线存储在有空间的浮纹理中 带索引在一个 `rg32uint` 纹理; 碎片阴影器解析分析 覆盖每个像素,所以文本在任何尺度或旋转时都保持尖锐. 文本数据 (及其甘油储存)由地层和出料器借用——处理 {\\fn黑体\\fs20\\shad2\\2ah82\\3ah20\\4ah33\\fscx95\\3ch592001\\be1}你对你的爱 `disposeDefaultTextData` 编号 : `disposeTextData`一个甘油存储器 只能由单一引擎绘制。 文本以预多倍形式混合 源取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取.

### 已解码的纹理

```ts
import { createTextureFromSource, disposeTexture } from "@babylonjs/lite-gl";

const texture = createTextureFromSource(engine, bitmap);
// One texImage2D upload, linear filtering and clamp-to-edge by default.
// Later, release the GPU resource:
disposeTexture(texture);
```

工厂接受 `TexImageSource` (包括 `ImageBitmap`, (中文(简体) ), `ImageData`, (中文(简体) ), 画布/外屏画布、已解码的图像、录像和录像框 内在大小,不首先执行占位符或空白分配. 视频元素必须有一个已解码的当前框架( Name`readyState >= 2`, (中文(简体) ), `HAVE_CURRENT_DATA`),而不仅仅是带有正维度的元数据. 保留 失去当前框架的视频用已登录的图像恢复为透明黑色 错误, 和其他无法使用的保留来源一样 . `GLTextureSourceOptions` 配置过滤/包装和打包旗. 对于 `ImageBitmap`,WebGL 忽略了可拆开的翻转/相乘;选择这些 解码时设置。 转换 SVG 或 密度选择( E)`srcset`(中文(简体) ) 图像到一个 `ImageBitmap` 首先,由于WebGL可能以其他大小上传它们 比他们自然的大小.

为默认自动恢复上下文保留源, 因此保留 保留位图/框在纹理活化时打开 。 过 `{ retainSource: false }` 当您的应用程序拥有恢复时:来源 上传后删除引用, 可关闭, 但上下文恢复 产生出一种现成的透明黑色纹理,原尺寸. 重新创建 恢复后的纹理(例如从 `onContextRestored`恢复其 内容。 可变保留源重放当前像素和内在 尺寸。 如果保留源已关闭, 请恢复日志错误并掉入 回到透明的黑色 只为纹理。 请求的Mipmaps与 `generateTextureMipMaps` 在恢复的上传后重建。 没有来源 由lite -gl关闭.

## 演示文稿

Repo GL 中每个特性的可运行场景 **实验室** (单位:千美元)`lab/gl/`——全屏效果,纹理相通,相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相相通相通相通相通相通相相通相通相通相相通相通相相通相通相通相相相通相通相通相相通相通相相通相相相通相相通相相通相相相相通相通相相相相相相相通相相通相, HTML元素纹理和渲染到纹理回转. 独立 `/gl/texture-3d-test.html` 源测试( e)`lab/gl/src/texture-3d-test.ts`检查 本地的3D Texel 地址和三线性过滤,没有画廊演示.

## 许可证

阿帕奇 - 2.0

## 常见问题

### @babylonjs/lite-gl 是什么？

基于函数,可树可摇动的WebGL2微引擎用于全屏效果,斯匹特和动态纹理——由@babylonjs/lite的WebGL对应\.

### 如何安装 @babylonjs/lite-gl？

在项目目录运行 npm install @babylonjs/lite-gl，或使用 pnpm add / yarn add / bun add。

### @babylonjs/lite-gl 支持 TypeScript 吗？

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

### @babylonjs/lite-gl 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @babylonjs/lite-gl 可以商用吗？

@babylonjs/lite-gl 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @babylonjs/lite-gl 的下载量有多少？

根据 npm 官方下载统计，@babylonjs/lite-gl 在 2026/10/08 – 2026/11/06 这 30 天内被下载 3,585 次，日均约 120 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @babylonjs/lite-gl 还在维护吗？

最新版本 1\.20\.1 发布于 2026/11/05（3 天前）；至今共发布 26 个版本，其中过去 12 个月发布了 26 个；首次发布于 2026/06/25。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。