@ignifx/core 0.8.0 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.js CHANGED
@@ -1,9 +1,9 @@
1
1
  import { a as CORE_ERROR_MESSAGES, c as THIRD_PARTY_ERROR_PREFIX, i as isIgnifxError, l as isValidErrorCode, n as assertNever, o as CoreErrorCode, r as formatErrorMessage, s as ErrorRange, t as IgnifxError } from "./ignifx-error-CRh89KUJ.js";
2
2
  import { _ as smoothStep, a as clamp, c as deltaAngleDegrees, d as lerpAngleDegrees, f as moveTowards, g as sign, h as repeat, i as approximately, l as inverseLerp, m as radToDeg, n as EPSILON, o as clamp01, p as pingPong, r as RAD_TO_DEG, s as degToRad, t as DEG_TO_RAD, u as lerp, v as wrapAngleDegrees } from "./math-utils-BcDnL-gi.js";
3
- import { $ as basisToQuatToRef, A as setMeshReceiveShadows, B as localPosition, C as overrideSubtreeMaterials, D as setMeshId, E as setMeshBounds, F as updateMeshPositions$1, G as readWorldMatrix, H as localScale, I as updateMeshUvs$1, J as setNodeSelfVisible, K as reparentKeepingWorld, L as createNode, M as setMeshSubtreeVisible, N as updateMeshColors$1, O as setMeshMaterial, P as updateMeshNormals$1, Q as Mat4, R as disposeNode, S as disposeMeshTemplate, T as removeMeshFromScene, U as parentNode, V as localRotation, W as readNodeTag, X as worldMatrixVersion, Y as tagNode, Z as MAT4_IDENTITY, _ as createMeshFromGeometry, a as VEC3_ONE, b as createTorusMesh, c as VEC3_ZERO, d as cloneMeshUnderNode, f as collectSubtreeMeshes, g as createGroundMesh, h as createCylinderMesh, i as VEC3_LEFT, j as setMeshRenderOrder, k as setMeshPickable, l as Vec3, m as createCapsuleMesh, n as VEC3_DOWN, o as VEC3_RIGHT, p as createBoxMesh, q as setNodeName, r as VEC3_FORWARD, s as VEC3_UP, t as VEC3_BACKWARD, u as addMeshToScene, v as createPlaneMesh, w as recomputeMeshBounds, x as detachMeshBounds, y as createSphereMesh, z as linkParent } from "./vec3-B31o_KF_.js";
3
+ import { $ as basisToQuatToRef, A as setMeshReceiveShadows, B as localPosition, C as overrideSubtreeMaterials, D as setMeshId, E as setMeshBounds, F as updateMeshPositions$1, G as readWorldMatrix, H as localScale, I as updateMeshUvs$1, J as setNodeSelfVisible, K as reparentKeepingWorld, L as createNode, M as setMeshSubtreeVisible, N as updateMeshColors$1, O as setMeshMaterial, P as updateMeshNormals$1, Q as Mat4, R as disposeNode, S as disposeMeshTemplate, T as removeMeshFromScene, U as parentNode, V as localRotation, W as readNodeTag, X as worldMatrixVersion, Y as tagNode, Z as MAT4_IDENTITY, _ as createMeshFromGeometry, a as VEC3_ONE, b as createTorusMesh, c as VEC3_ZERO, d as cloneMeshUnderNode, f as collectSubtreeMeshes, g as createGroundMesh, h as createCylinderMesh, i as VEC3_LEFT, j as setMeshRenderOrder, k as setMeshPickable, l as Vec3, m as createCapsuleMesh, n as VEC3_DOWN, o as VEC3_RIGHT, p as createBoxMesh, q as setNodeName, r as VEC3_FORWARD, s as VEC3_UP, t as VEC3_BACKWARD, u as addMeshToScene, v as createPlaneMesh, w as recomputeMeshBounds, x as detachMeshBounds, y as createSphereMesh, z as linkParent } from "./vec3-T2PasQZv.js";
4
4
  import { t as Color } from "./color-DrR6GFTd.js";
5
5
  import { a as readSceneImageProcessing, c as setSceneEnvironmentRotation, l as setSceneFog, n as installSceneEnvironment, o as setSceneClearColor, r as loadSceneEnvironment, s as setSceneEnvironmentBlur, t as TONE_MAPPING_NAMES, u as setSceneImageProcessingOptions } from "./environment-mr5wp69e.js";
6
- import { a as defineMaterialPlugin, c as MATERIAL_ALPHA_MODES, d as createStandardMaterialFromProps, f as markMaterialDirty, g as setPbrMetallicRoughness, h as setPbrBaseColor, i as MATERIAL_PLUGIN_SAMPLER_BUDGET, l as createDefaultMaterial, m as setMaterialAlpha, n as MATERIAL_PLUGIN_DEFAULT_PRIORITY, o as isLiteMaterialPluginPoint, r as MATERIAL_PLUGIN_RESERVED_NAMES, t as LITE_MATERIAL_PLUGIN_POINTS, u as createPbrMaterialFromProps } from "./material-plugin-Cfw_h_Mg.js";
6
+ import { a as defineMaterialPlugin, c as MATERIAL_ALPHA_MODES, d as createStandardMaterialFromProps, f as markMaterialDirty, g as setPbrMetallicRoughness, h as setPbrBaseColor, i as MATERIAL_PLUGIN_SAMPLER_BUDGET, l as createDefaultMaterial, m as setMaterialAlpha, n as MATERIAL_PLUGIN_DEFAULT_PRIORITY, o as isLiteMaterialPluginPoint, r as MATERIAL_PLUGIN_RESERVED_NAMES, t as LITE_MATERIAL_PLUGIN_POINTS, u as createPbrMaterialFromProps } from "./material-plugin-BRnhfw7K.js";
7
7
  import { a as postEffectValuesCodec, i as declaredTextureBinding, n as POST_EFFECT_FUNCTION, o as asJsonArray, r as customEffect, s as asJsonObject, t as POST_EFFECT_BUILTIN_UNIFORMS } from "./post-effect-C42XJFmo.js";
8
8
  import { a as SHADER_BLEND_MODES, c as SHADER_KINDS, d as SURFACE_HOOK_NAMES, f as SURFACE_UNIFORM_BLOCK, i as SHADER_ATTRIBUTE_NAMES, l as SHADER_TEXTURE_FALLBACKS, o as SHADER_CULL_MODES, r as LITE_SYSTEM_UNIFORM_NAMES, s as SHADER_INSTANCING_MODES, t as IGNIFX_UNIFORM_NAMES, u as SHADER_UNIFORM_TYPES } from "./shader-declaration-5q__jycG.js";
9
9
  import { acquireTexture, addTask, addToScene, buildFrameGraphTask, captureScreenshot, cloneTransformNode, createBloomPostProcessTask, createCopyToTextureTask, createCsmDirectionalShadowGenerator, createDirectionalLight, createEngine, createEsmDirectionalShadowGenerator, createFontFromBuffer, createFreeCamera, createGpuPicker, createHemisphericLight, createImageProcessingTask, createMeshFromData, createNullEngine, createPcfDirectionalShadowGenerator, createPcfSpotlightShadowGenerator, createPointLight, createRenderTarget, createRenderTask, createSceneContext, createSmaaPostProcessTask, createSpotLight, createStorageBuffer, createTexture2DFromPixels, disableOrthographicCamera, disposeEngine, disposePicker, disposeScene, disposeStorageBuffer, enableBoneControl, enableDeviceLostSceneRecovery, enableMaterialPlugins, enableMaterialStencil, enableOrthographicCamera, enablePbrLightmap, enableSkeletonShadows, enableStandardSkeleton, forceWebGpuDeviceLossForTesting, getEffectiveAspectRatio, getFrameGraph, getProjectionMatrix, getRenderTaskGpuTimings, getViewMatrix, getViewProjectionMatrix, isPbrMaterial, isShaderMaterial, loadTexture2D, onBeforeRender, pickAsync, pickWithRay, rebuildSceneRenderables, registerScene, registerSceneWithShadowSupport, releaseTexture, removeFromScene, resizeEngine, resolveCameraViewport, setGpuTimingEnabled, setShadowTaskCasterMeshes, setSubtreeVisible, setSurfaceSize, startEngine, stopEngine, updateStorageBuffer, updateTexture2DFromPixels } from "@babylonjs/lite";
@@ -6900,7 +6900,7 @@ let layer = null;
6900
6900
  * @internal
6901
6901
  */
6902
6902
  async function loadInstancedMeshSupport() {
6903
- const loaded = layer ?? await import("./instanced-mesh-instance-gguMoIeZ.js");
6903
+ const loaded = layer ?? await import("./instanced-mesh-instance-DYwH0vLi.js");
6904
6904
  layer = loaded;
6905
6905
  return loaded;
6906
6906
  }
@@ -6951,7 +6951,7 @@ function shaderSupport() {
6951
6951
  * @internal
6952
6952
  */
6953
6953
  async function loadSurfaceShaderSupport() {
6954
- const loaded = surfaceLayer ?? await import("./surface-shader-DAWIDdaa.js");
6954
+ const loaded = surfaceLayer ?? await import("./surface-shader-Br17yysO.js");
6955
6955
  surfaceLayer = loaded;
6956
6956
  return loaded;
6957
6957
  }
@@ -8883,25 +8883,26 @@ function canWarmUp(material) {
8883
8883
  *
8884
8884
  * Everything here is `@internal`.
8885
8885
  *
8886
- * ## Why the render layer has to know (verified against `@babylonjs/lite@1.27.0`)
8886
+ * ## Why the render layer has to know (verified against `@babylonjs/lite@1.34.0`)
8887
8887
  *
8888
8888
  * Lite registers the PBR skinning and morph-target shader fragments only inside a full build of
8889
8889
  * the PBR group, and only when that build contains a skinned or morphed mesh (`buildPbrRenderables`,
8890
- * `lib/material/pbr/pbr-renderable.js` 114-117). A mesh added after `registerScene` to a PBR group
8890
+ * `lib/material/pbr/pbr-renderable.js` 112). A mesh added after `registerScene` to a PBR group
8891
8891
  * that already exists is built at once by the group's `rebuildSingle` instead
8892
- * (`processMaterialSwaps`, `lib/scene/scene-material-swap.js` 22-45), and that never registers
8892
+ * (`processMaterialSwaps`, `lib/scene/scene-material-swap.js` 4-45), and that never registers
8893
8893
  * them. ignifx's warm-up builds the PBR group at start whenever the scene has a light (ADR-0014).
8894
8894
  *
8895
8895
  * So the first skinned model a page adds after `app.start()` is composed without its skinning
8896
8896
  * fragment, and Lite caches that bind-group layout under a key that does not say which fragments
8897
- * were registered (`getOrCreatePbrBindings`, `lib/material/pbr/pbr-pipeline.js` 33-36). The next
8897
+ * were registered (`getOrCreatePbrBindings`, `lib/material/pbr/pbr-pipeline.js` 59-63). The next
8898
8898
  * renderable rebuild registers the fragment, reuses the cached layout, and builds a bind group with
8899
8899
  * one more entry than it: WebGPU rejects every frame from then on ("Binding entry sampler not set",
8900
8900
  * group 1, entries[3]) and the canvas stays black. The fragments are registered process-wide, so
8901
8901
  * every later app in the page was fine.
8902
8902
  *
8903
8903
  * The render sync system compares what this reports with what a full build has already composed,
8904
- * and clears Lite's layout caches before the rebuild that first sees a new kind. Until that
8904
+ * and clears Lite's layout caches (`forgetMaterialBindingLayouts`, `./shadow.ts`) before the
8905
+ * rebuild that first sees a new kind. Until that
8905
8906
  * rebuild, one frame after the mesh arrives, a skinned mesh draws in its bind pose; a morphed one
8906
8907
  * gets a shader that does not compile, so WebGPU rejects that frame or two.
8907
8908
  */
@@ -9293,6 +9294,310 @@ function disposeSceneOnly(scene) {
9293
9294
  disposeScene(scene);
9294
9295
  }
9295
9296
  //#endregion
9297
+ //#region src/lite/shadow.ts
9298
+ /**
9299
+ * The shadow techniques Lite offers, in the order `docs/architecture/07-rendering.md` §2.2 lists them.
9300
+ *
9301
+ * @public
9302
+ */
9303
+ const SHADOW_TECHNIQUES = [
9304
+ "esm",
9305
+ "pcf",
9306
+ "csm"
9307
+ ];
9308
+ /**
9309
+ * Refuses to build a shadow generator for a light kind Lite cannot shadow.
9310
+ *
9311
+ * @remarks
9312
+ * Lite has no point-light (cube) shadow generator and no area lights
9313
+ * (`docs/architecture/07-rendering.md` §8). Hemispheric lights have no position or frustum at all.
9314
+ *
9315
+ * @param lightType - The Lite `lightType` discriminant of the light.
9316
+ * @throws IgnifxError with code `IGX-0703` for any light kind other than `directional` or `spot`.
9317
+ *
9318
+ * @example
9319
+ * ```ts
9320
+ * assertShadowsSupported(light.lightType); // throws IGX-0703 for "point"
9321
+ * ```
9322
+ *
9323
+ * @internal
9324
+ */
9325
+ function assertShadowsSupported(lightType) {
9326
+ if (lightType === "directional" || lightType === "spot") return;
9327
+ throw new IgnifxError(CoreErrorCode.shadowsUnsupportedForLight, `Babylon Lite has no shadow generator for a ${lightType} light.`, {
9328
+ context: { lightType },
9329
+ hint: "Cast shadows from a directional or spot light instead."
9330
+ });
9331
+ }
9332
+ /**
9333
+ * Turns shadows on for a light by attaching its generator.
9334
+ *
9335
+ * @param light - The light that should cast shadows.
9336
+ * @param generator - A generator built for that light by `./gpu/shadow-generator.ts`.
9337
+ *
9338
+ * @internal
9339
+ */
9340
+ function attachShadowGenerator(light, generator) {
9341
+ light.shadowGenerator = generator;
9342
+ }
9343
+ /**
9344
+ * Turns shadows off for a light.
9345
+ *
9346
+ * @remarks
9347
+ * This only breaks the link. The generator's GPU resources are released when the scene disposes it
9348
+ * through {@link disposeShadowGenerator}.
9349
+ *
9350
+ * @param light - The light that should stop casting shadows.
9351
+ *
9352
+ * @internal
9353
+ */
9354
+ function detachShadowGenerator(light) {
9355
+ delete light.shadowGenerator;
9356
+ }
9357
+ /**
9358
+ * Replaces the list of meshes a generator renders into its shadow map.
9359
+ *
9360
+ * @remarks
9361
+ * Lite keys the list by array identity and re-preloads the shadow pipeline every time a **new**
9362
+ * array arrives, skipping the generator until that finishes. Callers therefore build the list once
9363
+ * per change, never per frame.
9364
+ *
9365
+ * @param generator - The shadow generator.
9366
+ * @param casters - The meshes that cast into it.
9367
+ *
9368
+ * @internal
9369
+ */
9370
+ function setShadowCasters(generator, casters) {
9371
+ setShadowTaskCasterMeshes(generator, casters);
9372
+ }
9373
+ /**
9374
+ * Creates an empty record of a scene's material cache resets.
9375
+ *
9376
+ * @returns The record; install it with {@link trackMaterialCacheResets}.
9377
+ *
9378
+ * @internal
9379
+ */
9380
+ function createMaterialCacheResets() {
9381
+ return {
9382
+ found: /* @__PURE__ */ new Set(),
9383
+ seen: /* @__PURE__ */ new WeakSet(),
9384
+ unconfirmed: false
9385
+ };
9386
+ }
9387
+ /**
9388
+ * Starts recording what the scene's disposer list is handed, for the scene's lifetime.
9389
+ *
9390
+ * @remarks
9391
+ * Call it before the scene is registered, so the builds `registerScene` runs are seen too. It is
9392
+ * idempotent. An own `push` shadows `Array.prototype.push` on that one array; Lite only ever appends
9393
+ * to it with `push`.
9394
+ *
9395
+ * @param scene - The scene.
9396
+ * @param resets - Where to record.
9397
+ *
9398
+ * @internal
9399
+ */
9400
+ function trackMaterialCacheResets(scene, resets) {
9401
+ const disposables = scene._disposables;
9402
+ if (disposables === void 0 || Object.hasOwn(disposables, "push")) return;
9403
+ Object.defineProperty(disposables, "push", {
9404
+ configurable: true,
9405
+ writable: true,
9406
+ value: (...items) => {
9407
+ for (const item of items) if (disposables.includes(item)) resets.found.add(item);
9408
+ else if (!resets.seen.has(item)) {
9409
+ resets.seen.add(item);
9410
+ resets.unconfirmed = true;
9411
+ }
9412
+ return Array.prototype.push.apply(disposables, items);
9413
+ }
9414
+ });
9415
+ }
9416
+ /**
9417
+ * Rebuilds every material group of a registered scene so renderables pick up the current light and
9418
+ * shadow topology.
9419
+ *
9420
+ * @remarks
9421
+ * Renderables bake the per-mesh light index list, the single- versus multi-light shader
9422
+ * permutation, and each generator's shadow bind group at build time; none of that follows a light
9423
+ * being added, removed, or given a generator (`rebuildSceneRenderables`, `index.d.ts` 11165). The
9424
+ * call is a no-op before the scene's first build, and it is expensive, so the component layer
9425
+ * coalesces every topology change in a frame into one call.
9426
+ *
9427
+ * With `resets`, a rebuild that built a material family for the first time rebuilds once more
9428
+ * straight away, so the family's cache reset is known before anything needs it; see
9429
+ * {@link MaterialCacheResets}.
9430
+ *
9431
+ * @param scene - The scene to rebuild.
9432
+ * @param resets - The scene's record of cache resets.
9433
+ * @returns A promise that resolves when the rebuild has finished.
9434
+ *
9435
+ * @internal
9436
+ */
9437
+ async function rebuildRenderables(scene, resets) {
9438
+ if (resets === void 0) {
9439
+ await rebuildSceneRenderables(scene);
9440
+ return;
9441
+ }
9442
+ trackMaterialCacheResets(scene, resets);
9443
+ takeUnconfirmed(resets);
9444
+ await rebuildSceneRenderables(scene);
9445
+ if (takeUnconfirmed(resets)) await rebuildSceneRenderables(scene);
9446
+ }
9447
+ /**
9448
+ * Reads and clears {@link MaterialCacheResets.unconfirmed}.
9449
+ *
9450
+ * @param resets - The record.
9451
+ * @returns Whether a never-seen function was pushed since the flag was last cleared.
9452
+ */
9453
+ function takeUnconfirmed(resets) {
9454
+ const unconfirmed = resets.unconfirmed;
9455
+ resets.unconfirmed = false;
9456
+ return unconfirmed;
9457
+ }
9458
+ /**
9459
+ * Rebuilds a freshly registered scene once when its registration built anything, so Lite pushes
9460
+ * its cache resets again and {@link forgetMaterialBindingLayouts} can call them from the first
9461
+ * frame on.
9462
+ *
9463
+ * @remarks
9464
+ * Nothing has changed since registration, so every pipeline and layout comes from Lite's caches and
9465
+ * the rebuild only re-creates uniform buffers and bind groups.
9466
+ *
9467
+ * @param scene - The registered scene.
9468
+ * @param resets - The scene's record, installed with {@link trackMaterialCacheResets} before
9469
+ * registration.
9470
+ * @returns A promise that resolves when the rebuild has finished.
9471
+ *
9472
+ * @internal
9473
+ */
9474
+ async function learnMaterialCacheResets(scene, resets) {
9475
+ if (resets.unconfirmed) await rebuildRenderables(scene, resets);
9476
+ }
9477
+ /**
9478
+ * How many times the scene's materials have been rebuilt.
9479
+ *
9480
+ * @remarks
9481
+ * An ESM generator keeps the caster views it built for a caster array until it is handed a
9482
+ * different array, whatever happens to the materials (`ensureEsmShadowTaskState`,
9483
+ * `lib/shadow/esm-directional-shadow-generator.js` 121-126; PCF and CSM compare each material's
9484
+ * `_csmGen` instead). So a surface shader switched on or off went on drawing the old shape into an
9485
+ * ESM map. The render sync system re-supplies the caster lists whenever this moves.
9486
+ *
9487
+ * @param scene - The scene.
9488
+ * @returns The counter; `0` before anything was built.
9489
+ *
9490
+ * @internal
9491
+ */
9492
+ function readMaterialEpoch(scene) {
9493
+ return scene._materialEpoch ?? 0;
9494
+ }
9495
+ /**
9496
+ * Makes the next renderable rebuild create fresh bind-group layouts for every material.
9497
+ *
9498
+ * @remarks
9499
+ * Call it before {@link rebuildRenderables} whenever a light gained or lost a shadow generator,
9500
+ * and when the scene gained its first skinned or morphed PBR mesh (`./pbr-deformers.ts`).
9501
+ * Lite caches a PBR material's bindings, shadow bind-group layout included, under a key that does
9502
+ * not name the shadow maps (`getOrCreatePbrBindings`, `lib/material/pbr/pbr-pipeline.js` 59-63).
9503
+ * So after the number of shadow-casting lights changes, a rebuild reuses a layout sized for the old
9504
+ * number and builds a bind group for the new one, and WebGPU rejects every frame ("Number of
9505
+ * entries (3) did not match the expected number of entries (6)"). Clearing the caches costs one
9506
+ * pipeline rebuild per material, only on a frame whose shadow casters changed.
9507
+ *
9508
+ * @param resets - The resets the scene's rebuilds identified; see {@link MaterialCacheResets}.
9509
+ *
9510
+ * @internal
9511
+ */
9512
+ function forgetMaterialBindingLayouts(resets) {
9513
+ for (const reset of resets.found) reset();
9514
+ }
9515
+ /**
9516
+ * Releases a shadow generator's GPU resources and unlinks it from its light.
9517
+ *
9518
+ * @remarks
9519
+ * `removeFromScene` recognises a shadow generator by its private `_shadowType`/`_light` fields
9520
+ * (`lib/scene/scene-remove.js`), clears `light.shadowGenerator`, marks the scene's light topology
9521
+ * dirty, and queues the generator's task for disposal after the GPU has drained.
9522
+ *
9523
+ * @param scene - The scene the generator was rendering into.
9524
+ * @param generator - The generator to release.
9525
+ *
9526
+ * @internal
9527
+ */
9528
+ function disposeShadowGenerator(scene, generator) {
9529
+ removeFromScene(scene, generator);
9530
+ }
9531
+ /**
9532
+ * Maps the shared settings onto an exponential shadow map's configuration.
9533
+ *
9534
+ * @param settings - The declared settings.
9535
+ * @returns Lite's configuration, with every field the caller left out omitted.
9536
+ *
9537
+ * @internal
9538
+ */
9539
+ function toEsmConfig(settings) {
9540
+ const config = {};
9541
+ if (settings.mapSize !== void 0) config.mapSize = settings.mapSize;
9542
+ if (settings.bias !== void 0) config.bias = settings.bias;
9543
+ if (settings.darkness !== void 0) config.darkness = settings.darkness;
9544
+ return config;
9545
+ }
9546
+ /**
9547
+ * Maps the shared settings onto a percentage-closer-filtered directional shadow map's configuration.
9548
+ *
9549
+ * @param settings - The declared settings.
9550
+ * @returns Lite's configuration.
9551
+ *
9552
+ * @internal
9553
+ */
9554
+ function toPcfConfig(settings) {
9555
+ const config = {};
9556
+ if (settings.mapSize !== void 0) config.mapSize = settings.mapSize;
9557
+ if (settings.bias !== void 0) config.bias = settings.bias;
9558
+ if (settings.normalBias !== void 0) config.normalBias = settings.normalBias;
9559
+ if (settings.darkness !== void 0) config.darkness = settings.darkness;
9560
+ return config;
9561
+ }
9562
+ /**
9563
+ * Maps the shared settings onto a cascaded shadow map's configuration.
9564
+ *
9565
+ * @remarks
9566
+ * `cascades` becomes `numCascades` and `maxDistance` becomes `shadowMaxZ`; Lite clamps the cascade
9567
+ * count to four (`index.d.ts` 3515).
9568
+ *
9569
+ * @param settings - The declared settings.
9570
+ * @returns Lite's configuration.
9571
+ *
9572
+ * @internal
9573
+ */
9574
+ function toCsmConfig(settings) {
9575
+ const config = {};
9576
+ if (settings.mapSize !== void 0) config.mapSize = settings.mapSize;
9577
+ if (settings.bias !== void 0) config.bias = settings.bias;
9578
+ if (settings.darkness !== void 0) config.darkness = settings.darkness;
9579
+ if (settings.cascades !== void 0) config.numCascades = settings.cascades;
9580
+ if (settings.maxDistance !== void 0) config.shadowMaxZ = settings.maxDistance;
9581
+ return config;
9582
+ }
9583
+ /**
9584
+ * Maps the shared settings onto a spot light's shadow configuration.
9585
+ *
9586
+ * @param settings - The declared settings.
9587
+ * @returns Lite's configuration.
9588
+ *
9589
+ * @internal
9590
+ */
9591
+ function toSpotConfig(settings) {
9592
+ const config = {};
9593
+ if (settings.mapSize !== void 0) config.mapSize = settings.mapSize;
9594
+ if (settings.bias !== void 0) config.bias = settings.bias;
9595
+ if (settings.normalBias !== void 0) config.normalBias = settings.normalBias;
9596
+ if (settings.darkness !== void 0) config.darkness = settings.darkness;
9597
+ if (settings.maxDistance !== void 0) config.far = settings.maxDistance;
9598
+ return config;
9599
+ }
9600
+ //#endregion
9296
9601
  //#region src/render/gpu/renderer-gpu.ts
9297
9602
  /**
9298
9603
  * The device-only half of `app.renderer` (`docs/architecture/07-rendering.md` §1, §3, §5).
@@ -9853,6 +10158,8 @@ var RendererImpl = class {
9853
10158
  * this engine. A kind missing from it gets fresh layouts on its first rebuild (`../lite/pbr-deformers.ts`).
9854
10159
  */
9855
10160
  builtPbrDeformers = 0;
10161
+ /** Lite's material cache resets, as this scene's rebuilds identified them (`../lite/shadow.ts`). */
10162
+ materialCacheResets = createMaterialCacheResets();
9856
10163
  /** `true` once a camera was added, removed, enabled, disabled, or re-prioritised. */
9857
10164
  needsCameraSelect = true;
9858
10165
  /** `true` once the world has been told it has no enabled camera, so `IGX-0706` is logged once. */
@@ -11096,10 +11403,10 @@ function createHemisphericLightInWorld(intensity) {
11096
11403
  * from, in the one place every consumer reads them.
11097
11404
  *
11098
11405
  * @remarks
11099
- * The light's world matrix is its local matrix (there is no parent), so `worldMatrix[8..10]` — what
11100
- * the shader reads as the direction — is exactly what was written to `direction`,
11101
- * `worldMatrix[12..14]` — what a spot light reports as its position — is exactly `position`, and
11102
- * `computeDirectionalLightMatrix` fits the shadow frustum from the same two vectors.
11406
+ * The light has no parent and an identity rotation, so its world matrix is a pure translation:
11407
+ * the world direction Lite derives from `direction` is `direction` itself, and `worldMatrix[12..14]`
11408
+ * — where a point or spot light shines from, and where the shadow frustum is fitted from — is
11409
+ * exactly `position`.
11103
11410
  *
11104
11411
  * Each kind is written only what it uses, and each kind reads a different axis of the entity:
11105
11412
  *
@@ -11109,8 +11416,8 @@ function createHemisphericLightInWorld(intensity) {
11109
11416
  * | `point` | — | yes |
11110
11417
  * | `hemispheric` | the entity's world **up**: it is a sky direction, not a beam | — |
11111
11418
  *
11112
- * Both writes fire `ObservableVec3`'s dirty hook, so the lights uniform buffer re-uploads without a
11113
- * separate {@link markLightTransformDirty}.
11419
+ * Both writes bump the light's `_lightVersion`, so the lights uniform buffer re-uploads and a
11420
+ * shadow refits without a separate {@link markLightTransformDirty}.
11114
11421
  *
11115
11422
  * @param light - The light to pose.
11116
11423
  * @param forwardX - The entity's world-space forward x.
@@ -11251,7 +11558,7 @@ function setSpotExponent(light, exponent) {
11251
11558
  *
11252
11559
  * @remarks
11253
11560
  * Lite matches on `Mesh.id`, a string a loader or the adapter assigns; the include list wins over
11254
- * the exclude list when both are present (`lib/render/lights-ubo.js`, `affectsMesh`).
11561
+ * the exclude list when both are present (`lib/render/mesh-light-selection.js`, `affectsMesh`).
11255
11562
  *
11256
11563
  * @param light - The light to restrict.
11257
11564
  * @param meshIds - The mesh ids that may be lit, or `null` to light everything.
@@ -11324,227 +11631,6 @@ function markLightDirty(light) {
11324
11631
  }
11325
11632
  }
11326
11633
  //#endregion
11327
- //#region src/lite/shadow.ts
11328
- /**
11329
- * The shadow techniques Lite offers, in the order `docs/architecture/07-rendering.md` §2.2 lists them.
11330
- *
11331
- * @public
11332
- */
11333
- const SHADOW_TECHNIQUES = [
11334
- "esm",
11335
- "pcf",
11336
- "csm"
11337
- ];
11338
- /**
11339
- * Refuses to build a shadow generator for a light kind Lite cannot shadow.
11340
- *
11341
- * @remarks
11342
- * Lite has no point-light (cube) shadow generator and no area lights
11343
- * (`docs/architecture/07-rendering.md` §8). Hemispheric lights have no position or frustum at all.
11344
- *
11345
- * @param lightType - The Lite `lightType` discriminant of the light.
11346
- * @throws IgnifxError with code `IGX-0703` for any light kind other than `directional` or `spot`.
11347
- *
11348
- * @example
11349
- * ```ts
11350
- * assertShadowsSupported(light.lightType); // throws IGX-0703 for "point"
11351
- * ```
11352
- *
11353
- * @internal
11354
- */
11355
- function assertShadowsSupported(lightType) {
11356
- if (lightType === "directional" || lightType === "spot") return;
11357
- throw new IgnifxError(CoreErrorCode.shadowsUnsupportedForLight, `Babylon Lite has no shadow generator for a ${lightType} light.`, {
11358
- context: { lightType },
11359
- hint: "Cast shadows from a directional or spot light instead."
11360
- });
11361
- }
11362
- /**
11363
- * Turns shadows on for a light by attaching its generator.
11364
- *
11365
- * @param light - The light that should cast shadows.
11366
- * @param generator - A generator built for that light by `./gpu/shadow-generator.ts`.
11367
- *
11368
- * @internal
11369
- */
11370
- function attachShadowGenerator(light, generator) {
11371
- light.shadowGenerator = generator;
11372
- }
11373
- /**
11374
- * Turns shadows off for a light.
11375
- *
11376
- * @remarks
11377
- * This only breaks the link. The generator's GPU resources are released when the scene disposes it
11378
- * through {@link disposeShadowGenerator}.
11379
- *
11380
- * @param light - The light that should stop casting shadows.
11381
- *
11382
- * @internal
11383
- */
11384
- function detachShadowGenerator(light) {
11385
- delete light.shadowGenerator;
11386
- }
11387
- /**
11388
- * Replaces the list of meshes a generator renders into its shadow map.
11389
- *
11390
- * @remarks
11391
- * Lite keys the list by array identity and re-preloads the shadow pipeline every time a **new**
11392
- * array arrives, skipping the generator until that finishes. Callers therefore build the list once
11393
- * per change, never per frame.
11394
- *
11395
- * @param generator - The shadow generator.
11396
- * @param casters - The meshes that cast into it.
11397
- *
11398
- * @internal
11399
- */
11400
- function setShadowCasters(generator, casters) {
11401
- setShadowTaskCasterMeshes(generator, casters);
11402
- }
11403
- /**
11404
- * Rebuilds every material group of a registered scene so renderables pick up the current light and
11405
- * shadow topology.
11406
- *
11407
- * @remarks
11408
- * Renderables bake the per-mesh light index list, the single- versus multi-light shader
11409
- * permutation, and each generator's shadow bind group at build time; none of that follows a light
11410
- * being added, removed, or given a generator (`index.d.ts` 9465). The call is a no-op before the
11411
- * scene's first build, and it is expensive, so the component layer coalesces every topology change
11412
- * in a frame into one call.
11413
- *
11414
- * @param scene - The scene to rebuild.
11415
- * @returns A promise that resolves when the rebuild has finished.
11416
- *
11417
- * @internal
11418
- */
11419
- function rebuildRenderables(scene) {
11420
- return rebuildSceneRenderables(scene);
11421
- }
11422
- /**
11423
- * How many times the scene's materials have been rebuilt.
11424
- *
11425
- * @remarks
11426
- * An ESM generator keeps the caster views it built for a caster array until it is handed a
11427
- * different array, whatever happens to the materials (`ensureEsmShadowTaskState`,
11428
- * `lib/shadow/esm-directional-shadow-generator.js` 121-126; PCF and CSM compare each material's
11429
- * `_csmGen` instead). So a surface shader switched on or off went on drawing the old shape into an
11430
- * ESM map. The render sync system re-supplies the caster lists whenever this moves.
11431
- *
11432
- * @param scene - The scene.
11433
- * @returns The counter; `0` before anything was built.
11434
- *
11435
- * @internal
11436
- */
11437
- function readMaterialEpoch(scene) {
11438
- return scene._materialEpoch ?? 0;
11439
- }
11440
- /**
11441
- * Makes the next renderable rebuild create fresh bind-group layouts for every material.
11442
- *
11443
- * @remarks
11444
- * Call it before {@link rebuildRenderables} whenever a light gained or lost a shadow generator,
11445
- * and when the scene gained its first skinned or morphed PBR mesh (`./pbr-deformers.ts`).
11446
- * Lite caches a material's bindings, shadow bind-group layout included, under a key that does not
11447
- * name the shadow maps (`getOrCreatePbrBindings`, `lib/material/pbr/pbr-pipeline.js` 36). So after
11448
- * the number of shadow-casting lights changes, a rebuild reuses a layout sized for the old number
11449
- * and builds a bind group for the new one, and WebGPU rejects every frame ("Number of entries (3)
11450
- * did not match the expected number of entries (6)"). Clearing the cache costs one pipeline
11451
- * rebuild per material, only on a frame whose shadow casters changed.
11452
- *
11453
- * @param engine - The engine whose caches to clear.
11454
- *
11455
- * @internal
11456
- */
11457
- function forgetMaterialBindingLayouts(engine) {
11458
- const resets = engine;
11459
- resets._pbrCleanup?.();
11460
- resets._standardCleanup?.();
11461
- }
11462
- /**
11463
- * Releases a shadow generator's GPU resources and unlinks it from its light.
11464
- *
11465
- * @remarks
11466
- * `removeFromScene` recognises a shadow generator by its private `_shadowType`/`_light` fields
11467
- * (`lib/scene/scene-remove.js`), clears `light.shadowGenerator`, marks the scene's light topology
11468
- * dirty, and queues the generator's task for disposal after the GPU has drained.
11469
- *
11470
- * @param scene - The scene the generator was rendering into.
11471
- * @param generator - The generator to release.
11472
- *
11473
- * @internal
11474
- */
11475
- function disposeShadowGenerator(scene, generator) {
11476
- removeFromScene(scene, generator);
11477
- }
11478
- /**
11479
- * Maps the shared settings onto an exponential shadow map's configuration.
11480
- *
11481
- * @param settings - The declared settings.
11482
- * @returns Lite's configuration, with every field the caller left out omitted.
11483
- *
11484
- * @internal
11485
- */
11486
- function toEsmConfig(settings) {
11487
- const config = {};
11488
- if (settings.mapSize !== void 0) config.mapSize = settings.mapSize;
11489
- if (settings.bias !== void 0) config.bias = settings.bias;
11490
- if (settings.darkness !== void 0) config.darkness = settings.darkness;
11491
- return config;
11492
- }
11493
- /**
11494
- * Maps the shared settings onto a percentage-closer-filtered directional shadow map's configuration.
11495
- *
11496
- * @param settings - The declared settings.
11497
- * @returns Lite's configuration.
11498
- *
11499
- * @internal
11500
- */
11501
- function toPcfConfig(settings) {
11502
- const config = {};
11503
- if (settings.mapSize !== void 0) config.mapSize = settings.mapSize;
11504
- if (settings.bias !== void 0) config.bias = settings.bias;
11505
- if (settings.normalBias !== void 0) config.normalBias = settings.normalBias;
11506
- if (settings.darkness !== void 0) config.darkness = settings.darkness;
11507
- return config;
11508
- }
11509
- /**
11510
- * Maps the shared settings onto a cascaded shadow map's configuration.
11511
- *
11512
- * @remarks
11513
- * `cascades` becomes `numCascades` and `maxDistance` becomes `shadowMaxZ`; Lite clamps the cascade
11514
- * count to four (`index.d.ts` 3515).
11515
- *
11516
- * @param settings - The declared settings.
11517
- * @returns Lite's configuration.
11518
- *
11519
- * @internal
11520
- */
11521
- function toCsmConfig(settings) {
11522
- const config = {};
11523
- if (settings.mapSize !== void 0) config.mapSize = settings.mapSize;
11524
- if (settings.bias !== void 0) config.bias = settings.bias;
11525
- if (settings.darkness !== void 0) config.darkness = settings.darkness;
11526
- if (settings.cascades !== void 0) config.numCascades = settings.cascades;
11527
- if (settings.maxDistance !== void 0) config.shadowMaxZ = settings.maxDistance;
11528
- return config;
11529
- }
11530
- /**
11531
- * Maps the shared settings onto a spot light's shadow configuration.
11532
- *
11533
- * @param settings - The declared settings.
11534
- * @returns Lite's configuration.
11535
- *
11536
- * @internal
11537
- */
11538
- function toSpotConfig(settings) {
11539
- const config = {};
11540
- if (settings.mapSize !== void 0) config.mapSize = settings.mapSize;
11541
- if (settings.bias !== void 0) config.bias = settings.bias;
11542
- if (settings.normalBias !== void 0) config.normalBias = settings.normalBias;
11543
- if (settings.darkness !== void 0) config.darkness = settings.darkness;
11544
- if (settings.maxDistance !== void 0) config.far = settings.maxDistance;
11545
- return config;
11546
- }
11547
- //#endregion
11548
11634
  //#region src/lite/shadow-caster-shapes.ts
11549
11635
  /**
11550
11636
  * Tracks the bone poses and shader uniforms of one shadow generator's casters.
@@ -16323,6 +16409,7 @@ var RenderSyncSystem = class {
16323
16409
  renderer.refreshClearColor();
16324
16410
  this.#applyStacks(world);
16325
16411
  this.#areCastersDirty = this.#areCastersDirty || castersChanged;
16412
+ if (renderer.materialCacheResets.unconfirmed && !this.#isRebuildDue && !this.#isRebuildInFlight) this.#rebuildRenderables();
16326
16413
  if (this.#isRebuildDue && !topologyChanged) {
16327
16414
  this.#isRebuildDue = false;
16328
16415
  this.#rebuildRenderables();
@@ -16575,9 +16662,9 @@ var RenderSyncSystem = class {
16575
16662
  const deformers = readPbrDeformers(renderer.scene);
16576
16663
  if (renderer.needsShadowLayoutReset || (deformers & ~renderer.builtPbrDeformers) !== 0) {
16577
16664
  renderer.needsShadowLayoutReset = false;
16578
- forgetMaterialBindingLayouts(renderer.engine);
16665
+ forgetMaterialBindingLayouts(renderer.materialCacheResets);
16579
16666
  }
16580
- await rebuildRenderables(renderer.scene);
16667
+ await rebuildRenderables(renderer.scene, renderer.materialCacheResets);
16581
16668
  renderer.builtPbrDeformers |= deformers;
16582
16669
  } catch (error) {
16583
16670
  renderer.app.onError.emit({
@@ -31937,7 +32024,10 @@ var AppImpl = class {
31937
32024
  const world = this.#world;
31938
32025
  if (world !== null) renderer.syncBeforeRegister(world);
31939
32026
  renderer.warmUpAtStart();
32027
+ trackMaterialCacheResets(handles.scene, renderer.materialCacheResets);
31940
32028
  await registerRenderScene(handles.scene, { shadows: features.shadows });
32029
+ await learnMaterialCacheResets(handles.scene, renderer.materialCacheResets);
32030
+ renderer.needsCasterRebuild = true;
31941
32031
  renderer.markSceneRegistered();
31942
32032
  }
31943
32033
  /** Stops the Lite loop, detaches the browser listeners, and runs `onStop` in reverse order. */