@ignifx/core 0.4.0 → 0.6.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,8 @@
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-R1ma_Lzv.js";
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";
2
+ import { _ as sign, a as approximately, c as degToRad, d as lerp, f as lerpAngleDegrees, g as repeat, h as radToDeg, i as RAD_TO_DEG, l as deltaAngleDegrees, m as pingPong, n as DEG_TO_RAD, o as clamp, p as moveTowards, r as EPSILON, s as clamp01, t as Color, u as inverseLerp, v as smoothStep, y as wrapAngleDegrees } from "./color-CpvebMIh.js";
3
3
  import { A as linkParent, B as tagNode, C as setMeshSubtreeVisible, D as updateMeshUvs$1, E as updateMeshPositions$1, F as readNodeTag, I as readWorldMatrix, L as reparentKeepingWorld, M as localRotation, N as localScale, O as createNode, P as parentNode, R as setNodeName, S as setMeshRenderOrder, T as updateMeshNormals$1, V as worldMatrixVersion, a as createCapsuleMesh, b as setMeshPickable, c as createMeshFromGeometry, d as createTorusMesh, g as removeMeshFromScene, h as recomputeMeshBounds, i as createBoxMesh, j as localPosition, k as disposeNode, l as createPlaneMesh, m as overrideSubtreeMaterials, n as cloneMeshUnderNode, o as createCylinderMesh, p as disposeMeshTemplate, r as collectSubtreeMeshes, s as createGroundMesh, t as addMeshToScene, u as createSphereMesh, v as setMeshId, w as updateMeshColors$1, x as setMeshReceiveShadows, y as setMeshMaterial, z as setNodeSelfVisible } from "./mesh-CnK_PX46.js";
4
- import { a as setSceneClearColor, c as setSceneFog, l as setSceneImageProcessingOptions, n as installSceneEnvironment, o as setSceneEnvironmentBlur, r as loadSceneEnvironment, s as setSceneEnvironmentRotation, t as TONE_MAPPING_NAMES } from "./environment-C_JfuAjj.js";
4
+ 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-CvVC1lPa.js";
5
5
  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-CTaWZXEk.js";
6
- import { t as Color } from "./color-DrR6GFTd.js";
7
6
  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
7
  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
8
  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, enableStandardSkeleton, forceWebGpuDeviceLossForTesting, getEffectiveAspectRatio, getFrameGraph, getProjectionMatrix, getRenderTaskGpuTimings, getViewMatrix, getViewProjectionMatrix, isShaderMaterial, loadTexture2D, onBeforeRender, pickAsync, pickWithRay, rebuildSceneRenderables, registerScene, registerSceneWithShadowSupport, releaseTexture, removeFromScene, resizeEngine, resolveCameraViewport, setGpuTimingEnabled, setShadowTaskCasterMeshes, setSubtreeVisible, setSurfaceSize, startEngine, stopEngine, updateStorageBuffer, updateTexture2DFromPixels } from "@babylonjs/lite";
@@ -7259,7 +7258,7 @@ const ENVIRONMENT_FILE_EXTENSION = ".environment.json";
7259
7258
  * @example
7260
7259
  * ```ts
7261
7260
  * const studio = await app.assets.loadAsync<EnvironmentAsset>("environments/studio.env");
7262
- * world.createEntity("Env").addComponent(Environment, { environment: studio.retain() });
7261
+ * world.createEntity("Env").addComponent(Environment, { environment: studio });
7263
7262
  * ```
7264
7263
  *
7265
7264
  * @public
@@ -7509,17 +7508,18 @@ const SKYBOX_SIZE_DEFAULT = 20;
7509
7508
  * ```ts
7510
7509
  * const studio = await app.assets.loadAsync<EnvironmentAsset>("environments/studio.env");
7511
7510
  * const env = world.createEntity("Environment").addComponent(Environment, {
7512
- * environment: studio.retain(),
7511
+ * environment: studio,
7513
7512
  * imageProcessing: { exposure: 1.2, contrast: 1, toneMapping: "aces" },
7514
7513
  * });
7515
7514
  * ```
7516
7515
  *
7517
7516
  * @example
7518
- * Switching environments at runtime. Both handles stay retained, so switching back costs nothing.
7517
+ * Switching environments at runtime. The field takes no reference of its own: both handles stay
7518
+ * loaded until you release them, so switching back costs nothing.
7519
7519
  *
7520
7520
  * ```ts
7521
7521
  * const night = await app.assets.loadAsync<EnvironmentAsset>("environments/night.env");
7522
- * env.environment = night.retain();
7522
+ * env.environment = night;
7523
7523
  * ```
7524
7524
  *
7525
7525
  * @public
@@ -7618,7 +7618,7 @@ var Environment = class Environment extends Component {
7618
7618
  return installed;
7619
7619
  }
7620
7620
  /**
7621
- * Writes the clear colour, decoded to linear.
7621
+ * Writes the clear colour.
7622
7622
  *
7623
7623
  * @remarks
7624
7624
  * Nothing while the field is `null`, which is what leaves the `rendering.clearColor` setting
@@ -7641,11 +7641,11 @@ var Environment = class Environment extends Component {
7641
7641
  * Writes the fog record.
7642
7642
  *
7643
7643
  * @remarks
7644
- * The colour goes across **encoded**, unlike every other colour this component writes: Lite's fog
7645
- * block decodes it itself — `color = mix(pow(scene.vFogColor.rgb, vec3(2.2)), color, fogFactor)`
7644
+ * The colour goes across **encoded**: Lite's fog block decodes it itself —
7645
+ * `color = mix(pow(scene.vFogColor.rgb, vec3(2.2)), color, fogFactor)`
7646
7646
  * (`lib/material/pbr/pbr-fog-wgsl.js` 4) — so handing it a linear value decodes it twice and the
7647
- * fog reads far darker than the swatch. The clear colour, which the render pass consumes as a
7648
- * linear clear value, is decoded by `RendererImpl.applyClearColor` instead.
7647
+ * fog reads far darker than the swatch. The clear colour also goes across encoded, for its own
7648
+ * reason (`RendererImpl.applyClearColor`).
7649
7649
  *
7650
7650
  * @param renderer - The rendering service, for the scene.
7651
7651
  */
@@ -7829,7 +7829,7 @@ function environmentSchema() {
7829
7829
  }),
7830
7830
  toneMapping: enumOf(TONE_MAPPING_NAMES, "none", { tooltip: "The tone-mapping curve." })
7831
7831
  }, { tooltip: "Exposure, contrast, and tone mapping. Recompiles PBR pipelines when it changes." }),
7832
- clearColor: optional(color("#000000"), { tooltip: "The colour the scene is cleared to, in sRGB; null leaves the rendering.clearColor setting." })
7832
+ clearColor: optional(color("#000000"), { tooltip: "The sRGB colour the scene is cleared to, through imageProcessing; null leaves the rendering.clearColor setting." })
7833
7833
  });
7834
7834
  }
7835
7835
  //#endregion
@@ -7872,7 +7872,7 @@ let surfaceLayer = null;
7872
7872
  * @internal
7873
7873
  */
7874
7874
  async function loadShaderSupport() {
7875
- const loaded = shaderLayer ?? await import("./shader-material-DssOqsvZ.js").then((n) => n.n);
7875
+ const loaded = shaderLayer ?? await import("./shader-material-fOI9Upt3.js").then((n) => n.n);
7876
7876
  shaderLayer = loaded;
7877
7877
  await loaded.loadShaderMaterialAdapter();
7878
7878
  return loaded;
@@ -7895,7 +7895,7 @@ function shaderSupport() {
7895
7895
  * @internal
7896
7896
  */
7897
7897
  async function loadSurfaceShaderSupport() {
7898
- const loaded = surfaceLayer ?? await import("./surface-shader-C2HtysNN.js");
7898
+ const loaded = surfaceLayer ?? await import("./surface-shader-fJ2MOez0.js");
7899
7899
  surfaceLayer = loaded;
7900
7900
  return loaded;
7901
7901
  }
@@ -8940,9 +8940,11 @@ const FLOATS_PER_COLOR$1 = 4;
8940
8940
  *
8941
8941
  * @example
8942
8942
  * ```ts
8943
- * using box = MeshAsset.box(app, { size: 2 });
8943
+ * const box = MeshAsset.box(app, { size: 2 }); // one reference, owned by this code
8944
8944
  * const cube = app.world.createEntity("Cube");
8945
- * cube.addComponent(MeshRenderer, { mesh: box.retain() });
8945
+ * cube.addComponent(MeshRenderer, { mesh: box }); // the field takes no reference
8946
+ * // Once nothing draws the box any more:
8947
+ * box.release();
8946
8948
  * ```
8947
8949
  *
8948
8950
  * @public
@@ -10269,6 +10271,175 @@ function readTaskTimings(engine) {
10269
10271
  };
10270
10272
  }
10271
10273
  //#endregion
10274
+ //#region src/render/image-processing-color.ts
10275
+ /** Lite's gamma: a plain 2.2 power, not the piecewise sRGB curve. */
10276
+ const GAMMA = 2.2;
10277
+ /**
10278
+ * Whether image processing leaves an encoded colour unchanged.
10279
+ *
10280
+ * @param state - The image processing.
10281
+ * @returns `true` for exposure 1, contrast 1 and no curve, where decode and encode cancel out.
10282
+ *
10283
+ * @internal
10284
+ */
10285
+ function isIdentityImageProcessing(state) {
10286
+ return state.exposure === 1 && state.contrast === 1 && state.curve === "none";
10287
+ }
10288
+ /**
10289
+ * Whether two image-processing states are the same.
10290
+ *
10291
+ * @param left - One state.
10292
+ * @param right - The other.
10293
+ * @returns `true` when every field matches.
10294
+ *
10295
+ * @internal
10296
+ */
10297
+ function sameImageProcessing(left, right) {
10298
+ return left.exposure === right.exposure && left.contrast === right.contrast && left.curve === right.curve;
10299
+ }
10300
+ /**
10301
+ * Applies Lite's PBR image processing to an sRGB colour, as a fully fogged fragment of that colour
10302
+ * would receive it.
10303
+ *
10304
+ * @param r - The sRGB red component, 0 to 1.
10305
+ * @param g - The sRGB green component, 0 to 1.
10306
+ * @param b - The sRGB blue component, 0 to 1.
10307
+ * @param a - The alpha, passed through.
10308
+ * @param state - The image processing to apply.
10309
+ * @param out - Receives the processed sRGB colour.
10310
+ * @returns `out`.
10311
+ *
10312
+ * @internal
10313
+ */
10314
+ function imageProcessedColor(r, g, b, a, state, out) {
10315
+ out.a = a;
10316
+ if (isIdentityImageProcessing(state)) {
10317
+ out.r = r;
10318
+ out.g = g;
10319
+ out.b = b;
10320
+ return out;
10321
+ }
10322
+ out.r = decode(r) * state.exposure;
10323
+ out.g = decode(g) * state.exposure;
10324
+ out.b = decode(b) * state.exposure;
10325
+ applyCurve(state.curve, out);
10326
+ out.r = finish(out.r, state.contrast);
10327
+ out.g = finish(out.g, state.contrast);
10328
+ out.b = finish(out.b, state.contrast);
10329
+ return out;
10330
+ }
10331
+ /**
10332
+ * Lite's fog-colour decode.
10333
+ *
10334
+ * @param value - The encoded channel.
10335
+ * @returns The linear channel.
10336
+ */
10337
+ function decode(value) {
10338
+ return Math.max(value, 0) ** GAMMA;
10339
+ }
10340
+ /**
10341
+ * Encodes, clamps and applies contrast, the steps every PBR fragment ends with.
10342
+ *
10343
+ * @param value - The tone-mapped linear channel.
10344
+ * @param contrast - The contrast multiplier.
10345
+ * @returns The presented channel, 0 to 1.
10346
+ */
10347
+ function finish(value, contrast) {
10348
+ const encoded = Math.min(Math.max(Math.max(value, 0) ** (1 / GAMMA), 0), 1);
10349
+ const high = encoded * encoded * (3 - 2 * encoded);
10350
+ const contrasted = contrast < 1 ? .5 + (encoded - .5) * contrast : encoded + (high - encoded) * (contrast - 1);
10351
+ return Math.max(contrasted, 0);
10352
+ }
10353
+ /**
10354
+ * Applies a tone-mapping curve in place, to an already exposed linear colour.
10355
+ *
10356
+ * @param curve - The curve.
10357
+ * @param color - The colour; overwritten.
10358
+ */
10359
+ function applyCurve(curve, color) {
10360
+ switch (curve) {
10361
+ case "none": return;
10362
+ case "standard":
10363
+ color.r = standard(color.r);
10364
+ color.g = standard(color.g);
10365
+ color.b = standard(color.b);
10366
+ return;
10367
+ case "aces":
10368
+ aces(color);
10369
+ return;
10370
+ case "neutral":
10371
+ neutral(color);
10372
+ return;
10373
+ default: assertNever(curve, "tone mapping");
10374
+ }
10375
+ }
10376
+ /**
10377
+ * Lite's `StandardToneMapping` (`lib/material/pbr/tone-mapping.js`).
10378
+ *
10379
+ * @param value - The exposed channel.
10380
+ * @returns The tone-mapped channel.
10381
+ */
10382
+ function standard(value) {
10383
+ return 1 - 2 ** (-1.590579 * value);
10384
+ }
10385
+ /**
10386
+ * Lite's `AcesToneMapping`, the fitted RRT + ODT (`lib/material/pbr/pbr-aces-wgsl.js`).
10387
+ *
10388
+ * @param color - The exposed colour; overwritten.
10389
+ */
10390
+ function aces(color) {
10391
+ const r = .59719 * color.r + .35458 * color.g + .04823 * color.b;
10392
+ const g = .076 * color.r + .90834 * color.g + .01566 * color.b;
10393
+ const b = .0284 * color.r + .13383 * color.g + .83777 * color.b;
10394
+ const fr = rrtAndOdtFit(r);
10395
+ const fg = rrtAndOdtFit(g);
10396
+ const fb = rrtAndOdtFit(b);
10397
+ color.r = saturate(1.60475 * fr - .53108 * fg - .07367 * fb);
10398
+ color.g = saturate(-.10208 * fr + 1.10813 * fg - .00605 * fb);
10399
+ color.b = saturate(-.00327 * fr - .07276 * fg + 1.07602 * fb);
10400
+ }
10401
+ /**
10402
+ * The rational fit inside ACES.
10403
+ *
10404
+ * @param value - One channel in the ACES working space.
10405
+ * @returns The fitted channel.
10406
+ */
10407
+ function rrtAndOdtFit(value) {
10408
+ return (value * (value + .0245786) - 90537e-9) / (value * (.983729 * value + .432951) + .238081);
10409
+ }
10410
+ /**
10411
+ * Lite's `NeutralToneMapping`, Khronos PBR Neutral (`lib/material/pbr/pbr-neutral-wgsl.js`).
10412
+ *
10413
+ * @param color - The exposed colour; overwritten.
10414
+ */
10415
+ function neutral(color) {
10416
+ const startCompression = .76;
10417
+ const desaturation = .15;
10418
+ const lowest = Math.min(color.r, color.g, color.b);
10419
+ const offset = lowest < .08 ? lowest - 6.25 * lowest * lowest : .04;
10420
+ color.r -= offset;
10421
+ color.g -= offset;
10422
+ color.b -= offset;
10423
+ const peak = Math.max(color.r, color.g, color.b);
10424
+ if (peak < startCompression) return;
10425
+ const d = .24;
10426
+ const newPeak = 1 - d * d / (peak + d - startCompression);
10427
+ const scale = newPeak / peak;
10428
+ const blend = 1 - 1 / (desaturation * (peak - newPeak) + 1);
10429
+ color.r = color.r * scale + (newPeak - color.r * scale) * blend;
10430
+ color.g = color.g * scale + (newPeak - color.g * scale) * blend;
10431
+ color.b = color.b * scale + (newPeak - color.b * scale) * blend;
10432
+ }
10433
+ /**
10434
+ * Clamps to `[0, 1]`.
10435
+ *
10436
+ * @param value - The value.
10437
+ * @returns The clamped value.
10438
+ */
10439
+ function saturate(value) {
10440
+ return Math.min(Math.max(value, 0), 1);
10441
+ }
10442
+ //#endregion
10272
10443
  //#region src/render/rendering-settings.ts
10273
10444
  /**
10274
10445
  * The `rendering` project settings section (`docs/architecture/04-extensions.md` §5,
@@ -10539,6 +10710,8 @@ var RendererImpl = class {
10539
10710
  needsRenderableRebuild = false;
10540
10711
  /** `true` once a `castShadows` or caster-set change needs the caster lists rebuilt this frame. */
10541
10712
  needsCasterRebuild = false;
10713
+ /** `true` once a light gained or lost a shadow generator, so the next rebuild needs fresh layouts. */
10714
+ needsShadowLayoutReset = false;
10542
10715
  /** `true` once a camera was added, removed, enabled, disabled, or re-prioritised. */
10543
10716
  needsCameraSelect = true;
10544
10717
  /** `true` once the world has been told it has no enabled camera, so `IGX-0706` is logged once. */
@@ -10569,6 +10742,32 @@ var RendererImpl = class {
10569
10742
  #profileTasks = false;
10570
10743
  #isSceneRegistered = false;
10571
10744
  #isLoopRunning = false;
10745
+ /** The clear colour as authored, in sRGB, before image processing. */
10746
+ #authoredClear = {
10747
+ r: 0,
10748
+ g: 0,
10749
+ b: 0,
10750
+ a: 1
10751
+ };
10752
+ /** The image processing the clear colour was last written with. */
10753
+ #clearProcessing = {
10754
+ exposure: 1,
10755
+ contrast: 1,
10756
+ curve: "none"
10757
+ };
10758
+ /** Scratch for {@link RendererImpl.refreshClearColor}'s per-frame read. */
10759
+ #processingScratch = {
10760
+ exposure: 1,
10761
+ contrast: 1,
10762
+ curve: "none"
10763
+ };
10764
+ /** Scratch for the processed clear colour. */
10765
+ #processedClear = {
10766
+ r: 0,
10767
+ g: 0,
10768
+ b: 0,
10769
+ a: 1
10770
+ };
10572
10771
  /**
10573
10772
  * Creates the rendering service.
10574
10773
  *
@@ -10949,7 +11148,7 @@ var RendererImpl = class {
10949
11148
  this.applyClearColor(this.settings.clearColor);
10950
11149
  }
10951
11150
  /**
10952
- * Writes an sRGB colour onto the render scene's clear colour, decoded to linear.
11151
+ * Writes an sRGB colour onto the render scene's clear colour, so it presents as authored.
10953
11152
  *
10954
11153
  * @remarks
10955
11154
  * The one place `scene.clearColor` is written, so the precedence
@@ -10966,15 +11165,52 @@ var RendererImpl = class {
10966
11165
  * ignifx default is opaque black (`src/render/rendering-settings.ts`), so Lite's grey is only
10967
11166
  * ever seen by code that bypasses `createApp`.
10968
11167
  *
10969
- * Colours are stored in sRGB in every settings section and every component field, and Lite's
10970
- * `scene.clearColor` is linear, so each component is decoded on the way through.
11168
+ * Colours are stored in sRGB in every settings section and every component field. The clear goes
11169
+ * through the same exposure, curve and contrast as every PBR fragment, applied here on the CPU,
11170
+ * so a fully fogged floor and a clear colour of the fog's colour present as the same bytes. With
11171
+ * no image processing (exposure 1, contrast 1, curve `"none"`) an sRGB `0.5` presents as byte
11172
+ * `128`; under ACES it presents as byte `104`. The value is decoded only for an `*-srgb` surface
11173
+ * view (`rendering.srgb: true`), which encodes it again on write (`setSceneClearColor`).
10971
11174
  *
10972
11175
  * @param value - The sRGB colour, `0` to `1` per channel.
10973
11176
  *
10974
11177
  * @internal
10975
11178
  */
10976
11179
  applyClearColor(value) {
10977
- setSceneClearColor(this.scene, Color.srgbToLinear(value.r), Color.srgbToLinear(value.g), Color.srgbToLinear(value.b), value.a);
11180
+ const authored = this.#authoredClear;
11181
+ authored.r = value.r;
11182
+ authored.g = value.g;
11183
+ authored.b = value.b;
11184
+ authored.a = value.a;
11185
+ this.#writeClearColor(readSceneImageProcessing(this.scene, this.#processingScratch));
11186
+ }
11187
+ /**
11188
+ * Re-applies the clear colour when the scene's image processing changed since it was written.
11189
+ *
11190
+ * @remarks
11191
+ * The `PreRender` system calls it every frame, after the `Environment` has written its image
11192
+ * processing. Lite's `loadEnvironment` changes image processing too, which is why the scene is
11193
+ * read rather than the component.
11194
+ *
11195
+ * @internal
11196
+ */
11197
+ refreshClearColor() {
11198
+ const current = readSceneImageProcessing(this.scene, this.#processingScratch);
11199
+ if (!sameImageProcessing(current, this.#clearProcessing)) this.#writeClearColor(current);
11200
+ }
11201
+ /**
11202
+ * Writes the authored clear colour, processed with `processing`, onto the scene.
11203
+ *
11204
+ * @param processing - The scene's current image processing.
11205
+ */
11206
+ #writeClearColor(processing) {
11207
+ const applied = this.#clearProcessing;
11208
+ applied.exposure = processing.exposure;
11209
+ applied.contrast = processing.contrast;
11210
+ applied.curve = processing.curve;
11211
+ const authored = this.#authoredClear;
11212
+ const out = imageProcessedColor(authored.r, authored.g, authored.b, authored.a, processing, this.#processedClear);
11213
+ setSceneClearColor(this.scene, out.r, out.g, out.b, out.a);
10978
11214
  }
10979
11215
  /**
10980
11216
  * Reconciles the world with the Lite scene once, before the scene is registered.
@@ -11218,9 +11454,9 @@ function noMatrices() {
11218
11454
  *
11219
11455
  * @example
11220
11456
  * ```ts
11221
- * using box = MeshAsset.box(app, { size: 0.5 });
11457
+ * const box = MeshAsset.box(app, { size: 0.5 }); // release it once nothing draws it
11222
11458
  * const field = world.createEntity("Asteroids");
11223
- * const renderer = field.addComponent(InstancedMeshRenderer, { mesh: box.retain(), capacity: 20_000 });
11459
+ * const renderer = field.addComponent(InstancedMeshRenderer, { mesh: box, capacity: 20_000 });
11224
11460
  *
11225
11461
  * const slab = new Float32Array(20_000 * 16);
11226
11462
  * // ... write 16 column-major floats per instance ...
@@ -12019,6 +12255,45 @@ function rebuildRenderables(scene) {
12019
12255
  return rebuildSceneRenderables(scene);
12020
12256
  }
12021
12257
  /**
12258
+ * How many times the scene's materials have been rebuilt.
12259
+ *
12260
+ * @remarks
12261
+ * An ESM generator keeps the caster views it built for a caster array until it is handed a
12262
+ * different array, whatever happens to the materials (`ensureEsmShadowTaskState`,
12263
+ * `lib/shadow/esm-directional-shadow-generator.js` 121-126; PCF and CSM compare each material's
12264
+ * `_csmGen` instead). So a surface shader switched on or off went on drawing the old shape into an
12265
+ * ESM map. The render sync system re-supplies the caster lists whenever this moves.
12266
+ *
12267
+ * @param scene - The scene.
12268
+ * @returns The counter; `0` before anything was built.
12269
+ *
12270
+ * @internal
12271
+ */
12272
+ function readMaterialEpoch(scene) {
12273
+ return scene._materialEpoch ?? 0;
12274
+ }
12275
+ /**
12276
+ * Makes the next renderable rebuild create fresh bind-group layouts for every material.
12277
+ *
12278
+ * @remarks
12279
+ * Call it before {@link rebuildRenderables} whenever a light gained or lost a shadow generator.
12280
+ * Lite caches a material's bindings, shadow bind-group layout included, under a key that does not
12281
+ * name the shadow maps (`getOrCreatePbrBindings`, `lib/material/pbr/pbr-pipeline.js` 36). So after
12282
+ * the number of shadow-casting lights changes, a rebuild reuses a layout sized for the old number
12283
+ * and builds a bind group for the new one, and WebGPU rejects every frame ("Number of entries (3)
12284
+ * did not match the expected number of entries (6)"). Clearing the cache costs one pipeline
12285
+ * rebuild per material, only on a frame whose shadow casters changed.
12286
+ *
12287
+ * @param engine - The engine whose caches to clear.
12288
+ *
12289
+ * @internal
12290
+ */
12291
+ function forgetMaterialBindingLayouts(engine) {
12292
+ const resets = engine;
12293
+ resets._pbrCleanup?.();
12294
+ resets._standardCleanup?.();
12295
+ }
12296
+ /**
12022
12297
  * Releases a shadow generator's GPU resources and unlinks it from its light.
12023
12298
  *
12024
12299
  * @remarks
@@ -12146,11 +12421,40 @@ function recordReplacedShadowTaskStates(generator) {
12146
12421
  hooks._ensureShadowTaskState = (engine, scene, casterMeshes) => {
12147
12422
  const previous = hooks._shadowTaskState;
12148
12423
  const state = ensure(engine, scene, casterMeshes);
12424
+ if (state !== previous && casterMeshes.length === 0) stopMirroringEmptyStates(scene, state);
12149
12425
  if (previous !== void 0 && state !== previous && state._casterMeshes === previous._casterMeshes) state._task.record();
12150
12426
  return state;
12151
12427
  };
12152
12428
  }
12153
12429
  /**
12430
+ * Keeps a shadow task state built for no casters from drawing the scene's renderables.
12431
+ *
12432
+ * @remarks
12433
+ * Each render task records against an empty renderable list, and its mirroring flag is cleared
12434
+ * afterwards so a later change to the scene's renderables does not copy them in either. The pass
12435
+ * then only clears the map. See the module header.
12436
+ *
12437
+ * @param scene - The scene the state belongs to.
12438
+ * @param state - A state whose caster list is empty.
12439
+ */
12440
+ function stopMirroringEmptyStates(scene, state) {
12441
+ const renderables = scene;
12442
+ const tasks = state._tasks ?? [state._task];
12443
+ for (const task of tasks) {
12444
+ const record = task.record.bind(task);
12445
+ task.record = () => {
12446
+ const all = renderables._renderables;
12447
+ renderables._renderables = [];
12448
+ try {
12449
+ record();
12450
+ } finally {
12451
+ renderables._renderables = all;
12452
+ }
12453
+ task._af = false;
12454
+ };
12455
+ }
12456
+ }
12457
+ /**
12154
12458
  * Builds the directional generator for a technique.
12155
12459
  *
12156
12460
  * @param engine - The engine that owns the shadow map.
@@ -12275,6 +12579,9 @@ const TRANSLATION_COLUMN = 12;
12275
12579
  * local `+Z`, a point light sits at its origin, and a hemispheric light's sky direction is its local
12276
12580
  * `+Y`.
12277
12581
  *
12582
+ * A disabled light, or one on an inactive entity, contributes nothing: its intensity reaches Lite
12583
+ * as `0` and its shadow generator is released. Enabling it again restores both on the next frame.
12584
+ *
12278
12585
  * @example
12279
12586
  * ```ts
12280
12587
  * const sun = world.createEntity("Sun");
@@ -12325,7 +12632,7 @@ var Light = class Light extends Component {
12325
12632
  }
12326
12633
  /**
12327
12634
  * Whether this light currently casts shadows — which needs the `shadows` rendering feature, a
12328
- * light kind Lite can shadow, and `shadows.enabled`.
12635
+ * light kind Lite can shadow, `shadows.enabled`, and the light enabled in the hierarchy.
12329
12636
  *
12330
12637
  * @returns `true` when a shadow generator is attached.
12331
12638
  */
@@ -12342,7 +12649,8 @@ var Light = class Light extends Component {
12342
12649
  }
12343
12650
  /**
12344
12651
  * Writes every field that changed onto the Lite light, keeps the lights uniform buffer honest for
12345
- * a moving parent, and re-fits a shadow frustum that follows one. The `PreRender` system calls it.
12652
+ * a moving parent, and re-fits a shadow frustum that follows one. The `PreRender` system calls it
12653
+ * for every light, enabled or not, because a disabled light is dimmed to `0` rather than skipped.
12346
12654
  *
12347
12655
  * @param renderer - The rendering service, for the scene and the feature flags.
12348
12656
  * @returns `true` when the call changed the scene's light topology, which the system coalesces
@@ -12388,12 +12696,13 @@ var Light = class Light extends Component {
12388
12696
  const type = this.type;
12389
12697
  if (this.#appliedType === type && this.#light !== null) return false;
12390
12698
  this.#teardown(renderer);
12391
- const light = createLightOfType(type, this.intensity);
12699
+ const intensity = this.#effectiveIntensity();
12700
+ const light = createLightOfType(type, intensity);
12392
12701
  this.#light = light;
12393
12702
  this.#appliedType = type;
12394
12703
  this.#appliedColor = "";
12395
12704
  this.#appliedGroundColor = "";
12396
- this.#appliedIntensity = this.intensity;
12705
+ this.#appliedIntensity = intensity;
12397
12706
  this.#appliedRange = NaN;
12398
12707
  this.#appliedSpotAngle = NaN;
12399
12708
  this.#appliedSpotExponent = NaN;
@@ -12425,9 +12734,10 @@ var Light = class Light extends Component {
12425
12734
  * @param light - The Lite light.
12426
12735
  */
12427
12736
  #applyScalars(light) {
12428
- if (this.#appliedIntensity !== this.intensity) {
12429
- this.#appliedIntensity = this.intensity;
12430
- setLightIntensity(light, this.intensity);
12737
+ const intensity = this.#effectiveIntensity();
12738
+ if (this.#appliedIntensity !== intensity) {
12739
+ this.#appliedIntensity = intensity;
12740
+ setLightIntensity(light, intensity);
12431
12741
  }
12432
12742
  if (isRanged(light) && this.#appliedRange !== this.range) {
12433
12743
  this.#appliedRange = this.range;
@@ -12444,6 +12754,18 @@ var Light = class Light extends Component {
12444
12754
  }
12445
12755
  }
12446
12756
  /**
12757
+ * The intensity Lite should use: the field, or `0` while the component or its entity is disabled.
12758
+ *
12759
+ * @remarks
12760
+ * Dimming keeps the light in the scene. Removing it would change the light count every compiled
12761
+ * PBR permutation bakes in, and so cost a renderable rebuild on every toggle.
12762
+ *
12763
+ * @returns The intensity to apply.
12764
+ */
12765
+ #effectiveIntensity() {
12766
+ return this.isEnabledInHierarchy ? this.intensity : 0;
12767
+ }
12768
+ /**
12447
12769
  * Rebuilds the include and exclude mesh-id sets when either list changed length.
12448
12770
  *
12449
12771
  * @remarks
@@ -12471,7 +12793,7 @@ var Light = class Light extends Component {
12471
12793
  */
12472
12794
  #applyShadows(renderer) {
12473
12795
  const light = this.#light;
12474
- const wanted = this.shadows.enabled && renderer.features.shadows && !renderer.isHeadless;
12796
+ const wanted = this.shadows.enabled && this.isEnabledInHierarchy && renderer.features.shadows && !renderer.isHeadless;
12475
12797
  if (light === null || wanted === this.#appliedShadows) {
12476
12798
  this.#warnAboutShadows(renderer);
12477
12799
  return false;
@@ -12482,6 +12804,7 @@ var Light = class Light extends Component {
12482
12804
  return true;
12483
12805
  }
12484
12806
  this.#generator = attachShadows(renderer.engine, light, this.shadows);
12807
+ renderer.needsShadowLayoutReset = true;
12485
12808
  return true;
12486
12809
  }
12487
12810
  /**
@@ -12522,7 +12845,10 @@ var Light = class Light extends Component {
12522
12845
  const generator = this.#generator;
12523
12846
  const light = this.#light;
12524
12847
  this.#generator = null;
12525
- if (generator !== null) detachShadows(renderer.scene, light, generator);
12848
+ if (generator !== null) {
12849
+ detachShadows(renderer.scene, light, generator);
12850
+ renderer.needsShadowLayoutReset = true;
12851
+ }
12526
12852
  }
12527
12853
  /**
12528
12854
  * Removes the light and its generator from the scene.
@@ -13926,7 +14252,7 @@ let effectLayer = null;
13926
14252
  * @internal
13927
14253
  */
13928
14254
  async function loadPostEffectSupport() {
13929
- const [compiler, effects] = await Promise.all([compilerLayer ?? import("./post-effect-compiler-DTlkT1si.js"), effectLayer ?? import("./effect-task-CMbuO6Kb.js")]);
14255
+ const [compiler, effects] = await Promise.all([compilerLayer ?? import("./post-effect-compiler-Cq6cshjL.js"), effectLayer ?? import("./effect-task-CMbuO6Kb.js")]);
13930
14256
  compilerLayer = compiler;
13931
14257
  effectLayer = effects;
13932
14258
  }
@@ -14858,9 +15184,9 @@ function asMesh(node) {
14858
15184
  *
14859
15185
  * @example
14860
15186
  * ```ts
14861
- * using box = MeshAsset.box(app, { size: 1 });
15187
+ * const box = MeshAsset.box(app, { size: 1 }); // release it once nothing draws it
14862
15188
  * const cube = world.createEntity("Cube");
14863
- * cube.addComponent(MeshRenderer, { mesh: box.retain(), castShadows: true });
15189
+ * cube.addComponent(MeshRenderer, { mesh: box, castShadows: true });
14864
15190
  * ```
14865
15191
  *
14866
15192
  * @public
@@ -15235,7 +15561,7 @@ const NO_SKELETONS = Object.freeze([]);
15235
15561
  * ```ts
15236
15562
  * const hero = await app.assets.loadAsync<ModelAsset>("models/hero.glb");
15237
15563
  * const entity = world.createEntity("Hero");
15238
- * const model = entity.addComponent(Model, { model: hero.retain() });
15564
+ * const model = entity.addComponent(Model, { model: hero });
15239
15565
  * model.attachToNode("hand.R", sword);
15240
15566
  * ```
15241
15567
  *
@@ -16540,6 +16866,8 @@ var RenderSyncSystem = class {
16540
16866
  /** A rebuild asked for while one was already running; it is run once the in-flight one lands. */
16541
16867
  #isRebuildPending = false;
16542
16868
  #areCastersDirty = false;
16869
+ /** The scene's material epoch when the ESM caster lists were last handed over. */
16870
+ #materialEpoch = 0;
16543
16871
  /**
16544
16872
  * Creates the system.
16545
16873
  *
@@ -16607,8 +16935,10 @@ var RenderSyncSystem = class {
16607
16935
  topologyChanged = changed || topologyChanged;
16608
16936
  castersChanged = changed || castersChanged;
16609
16937
  }
16938
+ castersChanged = this.#hasEsmMaterialChanged(lights) || castersChanged;
16610
16939
  this.#selectCamera(world, cameras);
16611
16940
  topologyChanged = this.#applyEnvironment(world) || topologyChanged;
16941
+ renderer.refreshClearColor();
16612
16942
  this.#applyStacks(world);
16613
16943
  this.#areCastersDirty = this.#areCastersDirty || castersChanged;
16614
16944
  if (this.#isRebuildDue && !topologyChanged) {
@@ -16748,6 +17078,25 @@ var RenderSyncSystem = class {
16748
17078
  }
16749
17079
  }
16750
17080
  /**
17081
+ * Whether a material was rebuilt since the caster lists were last handed over, while an ESM light
17082
+ * is casting.
17083
+ *
17084
+ * @remarks
17085
+ * An ESM generator only rebuilds its caster views for a new caster array (`readMaterialEpoch`), so
17086
+ * a fresh array is what makes it draw a rebuilt material's new shape. PCF and CSM notice material
17087
+ * changes themselves, which is why nothing is re-supplied without an ESM light.
17088
+ *
17089
+ * @param lights - The world's lights.
17090
+ * @returns `true` when the caster lists should be rebuilt.
17091
+ */
17092
+ #hasEsmMaterialChanged(lights) {
17093
+ const epoch = readMaterialEpoch(this.#renderer.scene);
17094
+ if (epoch === this.#materialEpoch) return false;
17095
+ this.#materialEpoch = epoch;
17096
+ for (let index = 0; index < lights.length; index += 1) if (isEsmCaster(lights[index])) return true;
17097
+ return false;
17098
+ }
17099
+ /**
16751
17100
  * Collects one renderer's casters into the full list and, unless it draws with a shader
16752
17101
  * material, into the ESM list too. A shader-material caster under an ESM light is reported once
16753
17102
  * with `IGX-0724` (Babylon Lite 1.27.0 has no ESM view for the shader family).
@@ -16841,6 +17190,10 @@ var RenderSyncSystem = class {
16841
17190
  do {
16842
17191
  if (renderer.isHeadless || !renderer.isSceneRegistered) return;
16843
17192
  try {
17193
+ if (renderer.needsShadowLayoutReset) {
17194
+ renderer.needsShadowLayoutReset = false;
17195
+ forgetMaterialBindingLayouts(renderer.engine);
17196
+ }
16844
17197
  await rebuildRenderables(renderer.scene);
16845
17198
  } catch (error) {
16846
17199
  renderer.app.onError.emit({
@@ -28900,12 +29253,32 @@ function applyComponentInit(component, schema, init, typeName) {
28900
29253
  issues: issues.length
28901
29254
  } });
28902
29255
  const target = component;
28903
- for (const name of Object.keys(schema)) {
29256
+ for (const [name, field] of Object.entries(schema)) {
28904
29257
  const value = values[name];
28905
- if (value !== void 0) target[name] = value;
29258
+ if (value !== void 0) target[name] = withRecordDefaults(field, value);
28906
29259
  }
28907
29260
  }
28908
29261
  /**
29262
+ * Fills the fields a partial `record` value leaves out with their schema defaults, at any depth, as
29263
+ * reading a scene file does.
29264
+ *
29265
+ * @param field - The field the value is for.
29266
+ * @param value - The caller's validated value.
29267
+ * @returns A fresh record for a `record` field (or an `optional` one holding a record), otherwise
29268
+ * `value` itself.
29269
+ */
29270
+ function withRecordDefaults(field, value) {
29271
+ const spec = field.spec;
29272
+ if (spec.kind === "optional") return value === null ? value : withRecordDefaults(spec.inner, value);
29273
+ if (spec.kind !== "record" || !isPlainObject(value)) return value;
29274
+ const merged = {};
29275
+ for (const [name, inner] of Object.entries(spec.fields)) {
29276
+ const given = value[name];
29277
+ merged[name] = given === void 0 ? inner.createDefault() : withRecordDefaults(inner, given);
29278
+ }
29279
+ return merged;
29280
+ }
29281
+ /**
28909
29282
  * Builds the "used after destroy" error.
28910
29283
  *
28911
29284
  * @param uid - The destroyed entity's identifier.