@babylonjs/ lite- compat

一个 选择入巴比伦.js-形状相容层 已执行 巴比伦语Name 大众API. 它的存在是为了给巴比伦 低平滑道向巴比伦利特的WebGPU渲染器迁移.

import { WebGPUEngine, Scene, ArcRotateCamera, HemisphericLight, MeshBuilder, StandardMaterial, Vector3, Color3 } from "@babylonjs/lite-compat";

const engine = new WebGPUEngine(canvas);
await engine.initAsync();

const scene = new Scene(engine);
const camera = new ArcRotateCamera("cam", -Math.PI / 2, Math.PI / 2.5, 5, new Vector3(0, 0, 0), scene);
camera.attachControl(canvas, true);
new HemisphericLight("light", new Vector3(0, 1, 0), scene);

const box = MeshBuilder.CreateBox("box", { size: 1 }, scene);
const mat = new StandardMaterial("mat", scene);
mat.diffuseColor = new Color3(1, 0, 0);
box.material = mat;

engine.runRenderLoop(() => scene.render());

落地移民:保留你的巴比伦.js进口

如果你有一个已有的巴比伦.js应用,你不需要重写一个导入. 此软件包传送一个捆绑插件 重写 @babylonjs/* 导入到 构建时的相容层,所以你,你现在 @babylonjs/core, (中文(简体) ), @babylonjs/loaders, (中文(简体) ), @babylonjs/addons, (中文(简体) ), @babylonjs/materials,以及 @recast-navigation/* 进口 决 议 @babylonjs/lite-compat 换句话说.

// Your code stays exactly as it was — no edits needed:
import { Scene, ArcRotateCamera, MeshBuilder } from "@babylonjs/core";

添加您的捆绑器插件 :

维特

// vite.config.ts
import { defineConfig } from "vite";
import { liteCompat } from "@babylonjs/lite-compat/vite";

export default defineConfig({
    plugins: [liteCompat()],
});

滚动 (也与"滚下"合作)

// rollup.config.js
import { liteCompat } from "@babylonjs/lite-compat/rollup";

export default {
    plugins: [liteCompat()],
};

网络软件包 (也与Rspack合作)

// webpack.config.js
const { LiteCompatPlugin } = require("@babylonjs/lite-compat/webpack");

module.exports = {
    plugins: [new LiteCompatPlugin()],
};

兴建

import { build } from "esbuild";
import { liteCompat } from "@babylonjs/lite-compat/esbuild";

await build({
    plugins: [liteCompat()],
    // …
});

每个适配器共用一个重定向表,因此它们都同样地绘制出导入图. 指定者 在支持的表面之外(例如:. @babylonjs/gui)不受影响和决心 向真实的巴比伦.js软件包 — 所以无支持的API 响亮地失败而不是默默地失败 误作. 迁移完成后,您可以放下插件并从中导入 @babylonjs/lite-compat (或当地 @babylonjs/lite直接进行.

它是什么( 和不是)

• A 类 基于阶级,巴比伦.js-形状 在Lite的平面数据 + 工厂 API.
• 选入 : 输入它。 它安装不 BABYLON 全球,没有 模块级副作用,所以它从不膨胀不使用它的消费者.
• 诚实: 不支持的巴比伦。 js APIs 抛出 LiteCompatError 而不是说 使一些小错误.
• 没有 一个完整的巴比伦。 js 重新执行。 经典的必须粒子系统, GUI, WebXR, 标记, 以及巴比伦文中未包含的其他特性都超出了范围 (节点粒子编辑器图表部分支持).

支持的 API 一览

巴比伦.js 包和特色的高级视图显示相容层 盖被. 这是共同地表、个人属性和 支持区域内的超载可能仍然不存在.

@babylonjs/core

@babylonjs/loaders

glTF 等级 : result.meshes 是 GlTF 节点分级的平面视图(转换节点外加 在巴比伦,每个节点都有一个网点。 重现为 setParent()没有 .parent =, (中文(简体) ), 当你平地的时候,你看 glTF 导入等级和重命名。 。 。 .

@babylonjs/addons • 妇女 @recast-navigation/*

@babylonjs/materials

支持面外的指定器(例如). @babylonjs/gui, (中文(简体) ), @babylonjs/inspector) 被捆绑插件所保留,并决心 真实的巴比伦.js, 所以没有支持的API 响亮的失败 而不是错图.

设想的移徙途径是:

@babylonjs/core  →  @babylonjs/lite-compat  →  babylon-lite (native)

每层不透明

mesh.visibility 自动为普通的标准和PBR meshes工作,独立于 mesh.isVisible。它从不改变或复制材料,所以分享材料的 meshes 可以 独立淡出。 本地用户明确导入 setMeshOpacity 编号 : getMeshOpacity 从包根; comparat 不需要启用器.

mesh.visibility = 0.5; // Sorted blending, depth writes off.
mesh.visibility = 0; // No colour or geometry-output draws; still pickable.
mesh.visibility = 1; // Original material route.

• 获取器保留了原始的有限值; 渲染它为 [0, 1]. NaN和无限 掷出 RangeError (故意偏离巴比伦.js.
• 暗影仍然保持全能,包括0. 选取, isVisible状态 不变。 几何输出在其存在之前应用不透明 > 0.4 阿尔法门.
• 淡出节点/阴影/线性材料 LiteCompatError; 向已淡出者分配一个 网格在改变材料之前被否决. 待决 NodeMaterial 手柄为 拒绝。 允许将能见度重设为 1, 除非本地网格被处理 .
• 进口的glTF OPAQUE/MASK材料也刻意地淡出,与巴比伦不同. js的明显 透明模式行为。 MASK 截断使用原始的α 在此之前 不透明.
• 一个glTF-node 包装器在解剖学上更新了它的即时原始的 meshes,而不是孩子的 glTF 节点的原始. 可见度不是被继承的;合成根没有几何来淡出. 原始取出器属于指定的包装器,即使其原始包装器共用 产生本地渲染因子。 Clones复制了原始值并拥有新的GPU绑定.
• 微小的例子与他们的网状不透明相同. InstancedMesh.visibility, MeshLOD 不透明, 每分层不透明,每分层不透明不支持.

见 网格- 不透明架构 本地语言 合同和明确正常化的参考政策.

glTF 导入等级和重命名

巴比伦 Lite 保留了 glTF 节点等级: 每个 glTF 节点成为了变节点, 而它的网格中的每一个原始 变成网状 下级 那个节点 对于一个有单一原始的节点,巴比伦.js转而返回一个 Mesh 那个 搭载了节点变换和几何. 共通层重建了Lite的分层结构,作为Cononical 包裹和 返回其平整,按等级顺序,从 SceneLoader.ImportMeshAsync(...).meshes 财务报告和审定财务报表 AssetContainer.meshes数字 :

• 列表是对保留等级的平分观点,而不是独立可转换的介质列表. 父母总是 来到它的孩子们面前.
• 里面装有合成器 __root__ 在索引 0 中, 源 glTF 转换节点, 而原始的 meshes 下方 他们.
• 仅变形条目被包裹为 Mesh 也可以,但不带几何: getTotalVertices() === 0不治疗 条目作为几何 Mesh。 。 。 .

为什么每个入口 .parent 间断

mesh.parent = node 保持网状 当地 让世界在新父母的统治下改变. mesh.setParent(node) 保留它 世界 变身 都表现得像巴比伦 Js 但为巴比伦写的循环 经常指定 .parent 转到每个返回的条目 :

// Fine in Babylon.js. Under compat it detaches each primitive from the glTF node that carries its transform.
for (const mesh of result.meshes) {
    mesh.parent = applicationRoot;
}

在比对下,每个原始的网格 被移出上面的glTF节点 并且只保留自己的局部变换,所以 任何来自祖先节点的尺度、旋转或翻译都会丢失。 典型的案例是硬件资产模拟 以毫米表示的glTF节点大小 0.001:在环绕之后,它的原始体会使1000倍的体积太大,所以 40毫米接通器会变为40米,往往在相机范围以外.

按列表顺序烧烤失败 . bakeCurrentTransformIntoVertices() 烤的只有网状的 当地 变形:在一个仍然坐落在其glTF节点下的原始上,它留下了节点的缩放,并重设了节点 首先(在清单的前面)转变其子女在得到处理之前的继承.

安全图案

保留等级并移动整个导入 :

import { Mesh, SceneLoader } from "@babylonjs/lite-compat";

const result = await SceneLoader.ImportMeshAsync("", rootUrl, "model.glb", scene);
result.meshes[0]!.setParent(applicationRoot);

平平只放出可变的相片 保持它们现世的变迁. result.meshes 输入为 TransformNode[],将条目缩小到 Mesh 在使用只使用网格的方法之前:

const renderableMeshes = result.meshes.filter((mesh): mesh is Mesh => mesh instanceof Mesh && mesh.getTotalVertices() > 0);
for (const mesh of renderableMeshes) {
    mesh.setParent(applicationRoot);
}

把成份转换成几何 只能用来做狭义的入口胶片 为了这些,打电话 setParent() 首先,完全的分层构成的世界变换成为了网状的新的局部变换,然后烘焙:

// bakeableMeshes: the entries of renderableMeshes that meet every condition listed below.
for (const mesh of bakeableMeshes) {
    mesh.setParent(applicationRoot);
    mesh.bakeCurrentTransformIntoVertices();
}

只有在以下所有情况都坚守时,才能烤出网格。 否则就用平了 setParent() 或保持等级和 移动整个导入 :

• 无剪由变形而来. setParent() 保留精确的相邻局部矩阵,但 bakeCurrentTransformIntoVertices() 重建从位置、旋转和缩放的转换,但不能 快速剪线。 当祖先有非统一尺度,其下有子孙被旋转时,剪接出现: 例如,节点缩放 (2, 1, 1) 在Z周围旋转了45度 烧烤这样原始的一滴 剪接并改变几何形状.
• 紧凑的顶点数据. 烧烤取代顶点缓冲器 resizeMeshGeometry(),用于 相接相相接几何. 一个 glTF 原始负载只有在它至少有一个顶点属性出现时才互出 从缓冲维尤 byteStride 大于属性的元素大小,例如位置和常态 共享一个缓冲维尤 byteStride: 24,而Draco这样的加载器扩展已经解码了。 A 类 byteStride 等于元素大小,许多出口商在紧凑的缓冲图上写着,保持原始 在紧凑的道路上.
• 未变相几何. 面包师将基地位置,常态和切入态进行改造. 它不会改变 变形目标三角地,所以在烤出三角地后, 会在被烤到的空间中有所贡献: 0.001, 三角形 1 的贡献 0.001 烘焙前,还有 1 过后. 外皮的蛋白也没有覆盖 平地已经从上面的任何动画GlTF节点中解开一个原始的. 保持资产等级 变形目标,剥皮或节点动画必须继续工作.
• 只有位置,正常和第一个紫外线. 烧烤只能重新装入其CPU阵列的顶点属性 保留。 glTF 加载器上传 COLOR_0 财务报告和审定财务报表 TEXCOORD_1 不保留 CPU 副本,所以烘焙会降低顶点颜色 和第二套紫外线,它只保留在 enableGltfCpuTangents() 从 @babylonjs/lite 在装入前称为.
• 没有细小的例子. 包括glTF节点上的每个原始 EXT_mesh_gpu_instancing,装填器 绘制为细例:它们的矩阵留在节点的局部框上,而阴影器作曲 mesh.world * instanceWorld烧烤只变换了原型几何并重置了网状变形器,但不变了 实例矩阵,因此实例抵消最终会出现在烤制的空间中: 0.001,一个 实例翻译 (0, 1, 0) 贡献 0.001 烘焙前,还有 1 之后,副本散开。 平缓 如此纠结 setParent() 单独,或保持等级.
• 三角只列出. GLTF 装载器保留了线条、线条和三角线条原始的地貌,但是 面包师将每个索引缓冲器作为三角形列表. 当烘焙的变形镜 几何,它交换第二 和每组3人的第三指数保持风向。 将 glTF 在身份下导入 applicationRoot 包括它的合成手性根的镜像, 所以一个行列表 [0, 1, 2, 3, 4, 5] 变成 [0, 2, 1, 3, 5, 4] 并连接到其他顶点;条条以同样的方式失去连接. 平线和条形 原始人拥有 setParent() 一个人.

setParent() 还保留了镜像变相,包括glTF导入的合成活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性活性.

缺少一个API你需要吗?

适应现实世界的移徙需要,比较表层会扩大。 如果你打了一个 巴比伦.js API还没有包裹(或扔出) LiteCompatError, (中文(简体) ), 在巴比伦语中打开一个问题 并添加 compat 标签。 描述 API 和您的使用案例 页:1 compat 标签直接输入层的维护工作流程.