@ignifx/core 0.13.0 → 0.15.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.
Files changed (59) hide show
  1. package/dist/agx-tone-mapping-Cgt844j6.js +53 -0
  2. package/dist/agx-tone-mapping-Cgt844j6.js.map +1 -0
  3. package/dist/auto-exposure-uzPn0beO.js +246 -0
  4. package/dist/auto-exposure-uzPn0beO.js.map +1 -0
  5. package/dist/bloom-hdr-CLtQj-oY.js +315 -0
  6. package/dist/bloom-hdr-CLtQj-oY.js.map +1 -0
  7. package/dist/contact-shadows-T523EXaP.js +84 -0
  8. package/dist/contact-shadows-T523EXaP.js.map +1 -0
  9. package/dist/{environment-C9AjYJgV.js → environment-DPi0_0SP.js} +19 -5
  10. package/dist/environment-DPi0_0SP.js.map +1 -0
  11. package/dist/gtao-_nr0b6-E.js +630 -0
  12. package/dist/gtao-_nr0b6-E.js.map +1 -0
  13. package/dist/hdr-output-BrUvpAsE.js +525 -0
  14. package/dist/hdr-output-BrUvpAsE.js.map +1 -0
  15. package/dist/{ignifx-error-Dq2qJMkZ.js → ignifx-error-oYdVnT1S.js} +16 -1
  16. package/dist/ignifx-error-oYdVnT1S.js.map +1 -0
  17. package/dist/index.d.ts +753 -18
  18. package/dist/index.d.ts.map +1 -1
  19. package/dist/index.js +1679 -183
  20. package/dist/index.js.map +1 -1
  21. package/dist/{instanced-mesh-instance-DYwH0vLi.js → instanced-mesh-instance-NnODkvqK.js} +2 -2
  22. package/dist/{instanced-mesh-instance-DYwH0vLi.js.map → instanced-mesh-instance-NnODkvqK.js.map} +1 -1
  23. package/dist/mat4-D6exvAuO.js +949 -0
  24. package/dist/mat4-D6exvAuO.js.map +1 -0
  25. package/dist/material-CGk5mAah.js +204 -0
  26. package/dist/material-CGk5mAah.js.map +1 -0
  27. package/dist/{material-plugin-BOCB7Stt.js → material-plugin-BUlqLsap.js} +3 -204
  28. package/dist/material-plugin-BUlqLsap.js.map +1 -0
  29. package/dist/{post-effect-compiler-Dw6zW2cG.js → post-effect-compiler-CRek8VxQ.js} +2 -2
  30. package/dist/{post-effect-compiler-Dw6zW2cG.js.map → post-effect-compiler-CRek8VxQ.js.map} +1 -1
  31. package/dist/render-path-Be7WgN7r.js +166 -0
  32. package/dist/render-path-Be7WgN7r.js.map +1 -0
  33. package/dist/render-texture-C_TnaSz2.js +200 -0
  34. package/dist/render-texture-C_TnaSz2.js.map +1 -0
  35. package/dist/scene-color-passes-DlNr-qyZ.js +65 -0
  36. package/dist/scene-color-passes-DlNr-qyZ.js.map +1 -0
  37. package/dist/scene-inputs-BxGOsnIZ.js +318 -0
  38. package/dist/scene-inputs-BxGOsnIZ.js.map +1 -0
  39. package/dist/{shader-material-DRZmqA_S.js → shader-material-B6p66wB8.js} +18 -7
  40. package/dist/shader-material-B6p66wB8.js.map +1 -0
  41. package/dist/{shader-material-BxQn9FT4.js → shader-material-C0TAUr4t.js} +102 -4
  42. package/dist/shader-material-C0TAUr4t.js.map +1 -0
  43. package/dist/{shader-pragma-DrFm5f5m.js → shader-pragma-BKCoZTTA.js} +2 -2
  44. package/dist/{shader-pragma-DrFm5f5m.js.map → shader-pragma-BKCoZTTA.js.map} +1 -1
  45. package/dist/ssgi-Dm-maZrc.js +113 -0
  46. package/dist/ssgi-Dm-maZrc.js.map +1 -0
  47. package/dist/{surface-shader-BgZchRBe.js → surface-shader-BaK0kvBB.js} +5 -4
  48. package/dist/{surface-shader-BgZchRBe.js.map → surface-shader-BaK0kvBB.js.map} +1 -1
  49. package/dist/taa-BwBZLy11.js +480 -0
  50. package/dist/taa-BwBZLy11.js.map +1 -0
  51. package/dist/{vec3-T2PasQZv.js → vec3-D-0Y2mzE.js} +4 -948
  52. package/dist/vec3-D-0Y2mzE.js.map +1 -0
  53. package/package.json +1 -1
  54. package/dist/environment-C9AjYJgV.js.map +0 -1
  55. package/dist/ignifx-error-Dq2qJMkZ.js.map +0 -1
  56. package/dist/material-plugin-BOCB7Stt.js.map +0 -1
  57. package/dist/shader-material-BxQn9FT4.js.map +0 -1
  58. package/dist/shader-material-DRZmqA_S.js.map +0 -1
  59. package/dist/vec3-T2PasQZv.js.map +0 -1
package/dist/index.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { AnimationGroup, AssetContainer, DirectionalLight, EngineContext, EnvironmentTextures, Font, FreeCamera, HemisphericLight, Material, MaterialPlugin, Mesh, PbrMaterialProps, PickingInfo, PointLight, RenderTarget, SceneContext, SceneNode, ShaderAttributeName as ShaderAttributeName$1, ShaderMaterial, ShaderSystemUniformName, ShaderUniformType as ShaderUniformType$1, ShadowGenerator, Skeleton, SpotLight, StandardMaterialProps, StorageBuffer, Texture2D } from "@babylonjs/lite";
1
+ import { AnimationGroup, AssetContainer, DirectionalLight, EngineContext, EnvironmentTextures, Font, FreeCamera, HemisphericLight, Material, MaterialPlugin, Mesh, PbrMaterialProps, PickingInfo, PointLight, RenderTarget, RenderTargetTextureResult, SceneContext, SceneNode, ShaderAttributeName as ShaderAttributeName$1, ShaderMaterial, ShaderSystemUniformName, ShaderUniformType as ShaderUniformType$1, ShadowGenerator, Skeleton, SpotLight, StandardMaterialProps, StorageBuffer, Task, Texture2D } from "@babylonjs/lite";
2
2
  //#region src/errors/error-codes.d.ts
3
3
  /**
4
4
  * The error code registry data: the subsystem ranges from
@@ -187,6 +187,8 @@ export declare const CoreErrorCode: {
187
187
  readonly physicsCallbackOutsideFixedStep: "IGX-0409";
188
188
  /** A second, different simulation scene was handed to a world that already has one. */
189
189
  readonly simulationSceneAlreadySet: "IGX-0410";
190
+ /** One `Extension` object was handed to a second app while the first still runs it. */
191
+ readonly extensionInstalledTwice: "IGX-0411";
190
192
  /** An asset's value was read before the asset finished loading. */
191
193
  readonly assetNotLoaded: "IGX-0501";
192
194
  /** An asset load was aborted through its `AbortSignal`. */
@@ -279,6 +281,14 @@ export declare const CoreErrorCode: {
279
281
  readonly instancingLodWithoutCulling: "IGX-0727";
280
282
  /** `app.renderer.openOverlay()` was called on a headless app, or before `app.start()` registered the render scene. */
281
283
  readonly overlayNeedsRenderScene: "IGX-0728";
284
+ /** A render texture was rendered into or read on a headless app, or before `app.start()` started the render loop. */
285
+ readonly renderTextureNeedsRenderLoop: "IGX-0729";
286
+ /** `app.renderer.createRenderTexture` was given a side that is not a whole number from 1 to 4096. */
287
+ readonly invalidRenderTextureSize: "IGX-0730";
288
+ /** A render texture was used after `dispose()`, or with another app's renderer. */
289
+ readonly renderTextureUnusable: "IGX-0731";
290
+ /** `app.renderer.renderToTexture` was given a camera that is not attached to an entity. */
291
+ readonly renderTextureCameraDetached: "IGX-0732";
282
292
  /** The host exposes no Web Crypto implementation. */
283
293
  readonly cryptoUnavailable: "IGX-1420";
284
294
  /** A storage namespace name is not a legal namespace segment. */
@@ -6615,6 +6625,11 @@ interface ShaderMaterialBuildOptions {
6615
6625
  readonly name: string;
6616
6626
  /** The WGSL source, handed to Lite as both the vertex and the fragment source. */
6617
6627
  readonly source: string;
6628
+ /**
6629
+ * Whether the scene renders through `rendering.hdr`, where the fragment's display colour is
6630
+ * decoded to linear before it is written (see {@link linearOutputFragment}). Absent means `false`.
6631
+ */
6632
+ readonly linearOutput?: boolean;
6618
6633
  /** The vertex attributes the vertex stage reads; `position` is mandatory. */
6619
6634
  readonly attributes: readonly ShaderAttributeName$1[];
6620
6635
  /** The system and custom uniforms, in binding-declaration order. */
@@ -7708,6 +7723,44 @@ export declare const CANVAS_ALPHA_MODES: readonly ["opaque", "premultiplied"];
7708
7723
  * @public
7709
7724
  */
7710
7725
  type CanvasAlphaMode = (typeof CANVAS_ALPHA_MODES)[number];
7726
+ /**
7727
+ * The ambient-occlusion qualities, in the order the inspector lists them: `"half"` computes GTAO at
7728
+ * half resolution with 2 slices of 4 steps a side, `"full"` at full resolution with 3 slices of 6.
7729
+ *
7730
+ * @public
7731
+ */
7732
+ export declare const AMBIENT_OCCLUSION_QUALITIES: readonly ["half", "full"];
7733
+ /**
7734
+ * The union of the ambient-occlusion qualities.
7735
+ *
7736
+ * @public
7737
+ */
7738
+ type AmbientOcclusionQuality = (typeof AMBIENT_OCCLUSION_QUALITIES)[number];
7739
+ /**
7740
+ * Screen-space ambient occlusion (GTAO) on indirect light: `rendering.ambientOcclusion`
7741
+ * (`docs/architecture/07-rendering.md` §2.14).
7742
+ *
7743
+ * @remarks
7744
+ * Off by default, and nothing of it loads while it is off. On, a compute pass estimates how much of
7745
+ * each pixel's hemisphere the depth buffer hides, a depth-aware blur smooths it, and every lit PBR
7746
+ * material multiplies its ambient occlusion by the result. It darkens environment (IBL) light only:
7747
+ * direct lights, emissive colour, Standard materials and custom shaders are unchanged, so a scene
7748
+ * with no `Environment` cube map shows no difference. Works with and without `rendering.hdr`.
7749
+ *
7750
+ * @public
7751
+ */
7752
+ interface AmbientOcclusionSettings {
7753
+ /** Turns the effect on. Read once, when the app starts. */
7754
+ readonly enabled: boolean;
7755
+ /** `"half"` (default) or `"full"` resolution, which also sets the slice and step counts. */
7756
+ readonly quality: AmbientOcclusionQuality;
7757
+ /** How far an occluder may be from the surface it darkens, in world units (metres). */
7758
+ readonly radius: number;
7759
+ /** An exponent on the visibility: 1 is physically based, larger is darker. */
7760
+ readonly intensity: number;
7761
+ /** The fraction of `radius`, from its far end, over which occluders fade out. 0 cuts off hard. */
7762
+ readonly falloff: number;
7763
+ }
7711
7764
  /**
7712
7765
  * The rendering features a project switches on (`docs/architecture/07-rendering.md` §1.1). Every one
7713
7766
  * of them changes what Lite compiles at `registerScene`, so they are declared up front and a late
@@ -7738,6 +7791,61 @@ interface RenderingFeatureSettings {
7738
7791
  /** Rebuild scenes and their resources after the WebGPU device is lost. */
7739
7792
  readonly deviceLostRecovery: boolean;
7740
7793
  }
7794
+ /**
7795
+ * Auto exposure under `rendering.hdr` (`docs/plan/2026-11-gi-phase-1-execution-plan.md`, step G14):
7796
+ * a compute pass meters the HDR scene and eases the exposure towards middle grey.
7797
+ *
7798
+ * @remarks
7799
+ * EV here is `log2` of the scene's metered luminance (the average of a `log2` luminance histogram,
7800
+ * the darkest 10% and brightest 10% dropped). The exposure maps that average to 0.18 and multiplies
7801
+ * the scene before the `Environment`'s own exposure and curve, so the two compose.
7802
+ *
7803
+ * @public
7804
+ */
7805
+ interface AutoExposureSettings {
7806
+ /** Meter the scene and adapt the exposure. Off by default; needs `rendering.hdr`. */
7807
+ readonly enabled: boolean;
7808
+ /** The darkest metered EV the exposure follows: a darker scene is not brightened further. */
7809
+ readonly minEv: number;
7810
+ /** The brightest metered EV the exposure follows: a brighter scene is not darkened further. */
7811
+ readonly maxEv: number;
7812
+ /** Adaptation rate, per second, when the scene gets brighter. */
7813
+ readonly speedUp: number;
7814
+ /** Adaptation rate, per second, when the scene gets darker. */
7815
+ readonly speedDown: number;
7816
+ /** Stops added to the computed exposure; positive is brighter. */
7817
+ readonly compensation: number;
7818
+ }
7819
+ /**
7820
+ * Temporal anti-aliasing, the `rendering.taa` record (`docs/architecture/07-rendering.md` §2.13).
7821
+ *
7822
+ * @remarks
7823
+ * Needs `rendering.hdr`: TAA runs on the linear scene colour between the scene pass and the HDR
7824
+ * output pass. With `hdr` off it stays off and the app logs a warning. Nothing of it loads while
7825
+ * `enabled` is `false`.
7826
+ *
7827
+ * @example
7828
+ * ```ts
7829
+ * const app = await createApp({ canvas, settings: { rendering: { hdr: true, taa: { enabled: true } } } });
7830
+ * ```
7831
+ *
7832
+ * @public
7833
+ */
7834
+ interface TaaSettings {
7835
+ /** Turn TAA on. Off by default. */
7836
+ readonly enabled: boolean;
7837
+ /** Weight of the current frame, 0.01–1. Lower is smoother but slower to follow change. Default 0.1. */
7838
+ readonly blend: number;
7839
+ /** Output sharpening, 0–1, to offset the softening TAA brings. Default 0. */
7840
+ readonly sharpness: number;
7841
+ /** Clip history to the current pixel's neighbourhood, which prevents ghosting. Default `true`. */
7842
+ readonly clamp: boolean;
7843
+ /**
7844
+ * How far, in world units, the camera may move in one frame before the history is dropped as a
7845
+ * camera cut. A turn of more than 60° in one frame is a cut too. Default 10.
7846
+ */
7847
+ readonly cutDistance: number;
7848
+ }
7741
7849
  /**
7742
7850
  * The resolved `rendering` settings section
7743
7851
  * (`docs/architecture/04-extensions.md` §5, `07-rendering.md` §1).
@@ -7786,6 +7894,31 @@ interface RenderingSettings {
7786
7894
  readonly clearColor: ColorLike;
7787
7895
  /** The address of the RGBD BRDF lookup table `loadEnvironment` requires. */
7788
7896
  readonly brdfLut: string;
7897
+ /**
7898
+ * Render the scene into a floating-point (`rgba16float`) target and tone map it in one final pass.
7899
+ *
7900
+ * @remarks
7901
+ * Off by default, and nothing of it loads while it is off. On, PBR materials keep their linear
7902
+ * colour, which may go above 1, and a final output pass applies the `Environment`'s exposure,
7903
+ * contrast and tone-mapping curve and encodes the result for the screen. Fog, Standard and unlit
7904
+ * materials, surface shaders, custom `.wgsl` materials (particles, foliage) and the `.env`/`.dds`
7905
+ * skybox are carried in linear colour too, and sprites draw after the output pass, so with the
7906
+ * default image processing a scene looks the same either way; under a tone-mapping curve, Standard
7907
+ * and custom-shader colour now goes through it as well. A `PostProcessStack`'s custom effects
7908
+ * ordered before any built-in one see linear colour. Lite's six-face `loadSkybox` cube is not
7909
+ * covered (`docs/architecture/07-rendering.md` §2.7). Later effects (HDR bloom, auto exposure)
7910
+ * need it on.
7911
+ */
7912
+ readonly hdr: boolean;
7913
+ /**
7914
+ * Auto exposure, read once at `app.start()`. Ignored unless {@link RenderingSettings.hdr} is on;
7915
+ * off, nothing of it loads.
7916
+ */
7917
+ readonly autoExposure: AutoExposureSettings;
7918
+ /** Screen-space ambient occlusion on indirect light (GTAO). Off by default. */
7919
+ readonly ambientOcclusion: AmbientOcclusionSettings;
7920
+ /** Temporal anti-aliasing; needs {@link RenderingSettings.hdr}. Off by default. */
7921
+ readonly taa: TaaSettings;
7789
7922
  }
7790
7923
  /**
7791
7924
  * The name the `rendering` project settings section is registered under.
@@ -7799,6 +7932,15 @@ export declare const RENDERING_SETTINGS_SECTION = "rendering";
7799
7932
  * @public
7800
7933
  */
7801
7934
  export declare const DEFAULT_BRDF_LUT_ADDRESS = "environments/brdf-lut.png";
7935
+ /**
7936
+ * The auto exposure a project that names none gets: off, metering EV −6 to 6, adapting at 2 per
7937
+ * second towards brighter scenes and 1 towards darker ones, with no compensation.
7938
+ *
7939
+ * @returns A fresh record.
7940
+ *
7941
+ * @public
7942
+ */
7943
+ export declare function defaultAutoExposureSettings(): AutoExposureSettings;
7802
7944
  /**
7803
7945
  * The settings a project that declares no `rendering` section runs with: every feature off, Lite's
7804
7946
  * own swapchain defaults, and an unclamped device pixel ratio.
@@ -7818,6 +7960,51 @@ export declare const DEFAULT_BRDF_LUT_ADDRESS = "environments/brdf-lut.png";
7818
7960
  export declare function defaultRenderingSettings(): RenderingSettings;
7819
7961
  //#endregion
7820
7962
  //#region src/lite/gpu/render-path.d.ts
7963
+ /**
7964
+ * The HDR half of a presenter, when `rendering.hdr` built one (`./hdr-output.ts`).
7965
+ *
7966
+ * @internal
7967
+ */
7968
+ interface HdrOutputHandle {
7969
+ /** The scene's linear `rgba16float` colour, as a sampled texture. Values may exceed 1. */
7970
+ readonly sceneTexture: Texture2D;
7971
+ /** The render target behind {@link HdrOutputHandle.sceneTexture}, for a pass that writes it back (TAA). */
7972
+ readonly sceneTarget: RenderTarget;
7973
+ /** The `"scene"` render task, whose scene uniforms the TAA jitter offsets. */
7974
+ readonly sceneTask: Task;
7975
+ /**
7976
+ * The auto exposure result, a 1×1 `r32float` texture holding `log2` of the multiplier the output
7977
+ * pass applies (`./auto-exposure.ts`); `null` when `rendering.autoExposure` is off.
7978
+ */
7979
+ readonly exposureTexture: Texture2D | null;
7980
+ /**
7981
+ * The same target with its sampled facade and resize hook: what HDR bloom (step G12) samples,
7982
+ * writes back into, and rebinds on resize.
7983
+ */
7984
+ readonly sceneTargetTexture: RenderTargetTextureResult;
7985
+ /**
7986
+ * The per-frame work: uploads the scene's exposure, contrast and curve when they changed, and
7987
+ * gives every new PBR material the linear-output plugin.
7988
+ *
7989
+ * @param isSceneRegistered - Whether Lite has built the scene, so a patched material needs a
7990
+ * rebuild.
7991
+ */
7992
+ update(isSceneRegistered: boolean): void;
7993
+ /**
7994
+ * Puts a task between the scene pass and the output pass, where it reads and writes linear
7995
+ * colour: a `PostProcessStack`'s custom effects ordered before any built-in one (GI plan G3).
7996
+ *
7997
+ * @param task - The task; it must write an `rgba16float` target.
7998
+ * @param isFrameGraphBuilt - Whether the scene is registered, so the task has to be recorded now.
7999
+ */
8000
+ insertLinearTask(task: Task, isFrameGraphBuilt: boolean): void;
8001
+ /**
8002
+ * Points the output pass at another linear texture, or back at the scene's.
8003
+ *
8004
+ * @param texture - The last linear effect's output, or `null` for {@link HdrOutputHandle.sceneTexture}.
8005
+ */
8006
+ setOutputSource(texture: Texture2D | null): void;
8007
+ }
7821
8008
  /**
7822
8009
  * A scene's offscreen render path: the colour a `PostProcessStack` reads, and the compositing blit
7823
8010
  * it takes over from.
@@ -7840,6 +8027,94 @@ interface ScenePresenter {
7840
8027
  setPresentEnabled(enabled: boolean): void;
7841
8028
  /** Whether the compositing blit currently runs. */
7842
8029
  readonly isPresentEnabled: boolean;
8030
+ /** The HDR output pass, when `rendering.hdr` is on; `null` for the plain offscreen path. */
8031
+ readonly hdr: HdrOutputHandle | null;
8032
+ /**
8033
+ * The scene's render task and the single-sample colour target it ends in: {@link
8034
+ * ScenePresenter.sceneColor} on the plain path, the `rgba16float` target under `rendering.hdr`.
8035
+ * Scene-colour effects (contact shadows, SSGI) insert their tasks right after `task` and write their
8036
+ * result back into `target`, so everything downstream reads it.
8037
+ */
8038
+ readonly scenePass: ScenePass;
8039
+ }
8040
+ /**
8041
+ * The scene's render task and its resolved colour target.
8042
+ *
8043
+ * @internal
8044
+ */
8045
+ interface ScenePass {
8046
+ /** The task named `"scene"`. */
8047
+ readonly task: Task;
8048
+ /** The single-sample colour target the scene ends in; it carries `TEXTURE_BINDING` and `COPY_DST`. */
8049
+ readonly target: RenderTarget;
8050
+ /** That target's colour format. */
8051
+ readonly format: GPUTextureFormat;
8052
+ }
8053
+ //#endregion
8054
+ //#region src/lite/gpu/scene-inputs.d.ts
8055
+ /**
8056
+ * One user's lease on the shared scene inputs.
8057
+ *
8058
+ * @remarks
8059
+ * Every texture is sized like the surface (backing-store pixels) and holds this frame's values for
8060
+ * any task that runs after the inputs' tasks, which sit at the start of the frame graph. A resize or
8061
+ * a recovered device swaps the GPU textures behind the same objects; bind groups that captured a
8062
+ * view must be rebuilt in {@link SceneInputs.onChange}.
8063
+ *
8064
+ * @internal
8065
+ */
8066
+ interface SceneInputs {
8067
+ /** Scene depth, `depth32float`, reverse-Z (1 near, 0 far). Bind with `sampleType: "depth"`. */
8068
+ readonly depth: Texture2D;
8069
+ /**
8070
+ * The same depth as the single-sample `RenderTarget` it lives in, for Lite tasks that take a
8071
+ * `depthTexture` target (contact shadows, SSGI).
8072
+ */
8073
+ readonly depthTarget: RenderTarget;
8074
+ /** World-space normals, `rgba16float`, stored as `n * 0.5 + 0.5`; 0 where nothing was drawn. */
8075
+ readonly normals: Texture2D;
8076
+ /**
8077
+ * Screen-space motion, `rgba16float`: `xy = 0.5 * (previousNdc - currentNdc)`, so UV units with Y
8078
+ * up, pointing from where a pixel is now to where it was last frame; 0 where nothing was drawn.
8079
+ * Camera motion always counts. Object motion counts for Standard materials only: Lite 1.34's PBR
8080
+ * geometry view reprojects the current world position (`pbr-geometry-output-shader.js` line 41),
8081
+ * so a moving PBR mesh under a still camera reads 0.
8082
+ */
8083
+ readonly velocity: Texture2D;
8084
+ /**
8085
+ * The depth pyramid, `r32float`, every mip level; level `n` is the `max` of its four children in
8086
+ * level `n - 1`. Read with `textureLoad(tex, coord, mip)`. A resize or recovered device replaces
8087
+ * this object, so read it again after {@link SceneInputs.onChange}.
8088
+ */
8089
+ readonly depthPyramid: Texture2D;
8090
+ /** How many mip levels {@link SceneInputs.depthPyramid} has. */
8091
+ readonly depthPyramidMipCount: number;
8092
+ /** `true` once {@link SceneInputs.release} ran. */
8093
+ readonly isReleased: boolean;
8094
+ /**
8095
+ * Registers a callback for when the textures were reallocated (resize, recovered device).
8096
+ *
8097
+ * @param callback - Runs during the frame graph rebuild, before the next frame is recorded.
8098
+ * @returns A function that unregisters it.
8099
+ */
8100
+ onChange(callback: () => void): () => void;
8101
+ /** Ends this lease. The last release removes and disposes the tasks and targets. Idempotent. */
8102
+ release(): void;
8103
+ }
8104
+ //#endregion
8105
+ //#region src/lite/gpu/taa.d.ts
8106
+ /**
8107
+ * The installed TAA passes.
8108
+ *
8109
+ * @internal
8110
+ */
8111
+ interface TaaHandle {
8112
+ /** Drops the history on the next frame, as a camera cut does. */
8113
+ reset(): void;
8114
+ /** How many times history has been reset, first frame included; for tests and diagnostics. */
8115
+ readonly resetCount: number;
8116
+ /** The jitter of the last frame, in pixels, each in `[-0.5, 0.5)`. */
8117
+ readonly jitter: readonly [number, number];
7843
8118
  }
7844
8119
  //#endregion
7845
8120
  //#region src/lite/picking.d.ts
@@ -8174,12 +8449,12 @@ interface RenderTaskTiming {
8174
8449
  */
8175
8450
  interface RenderTaskTimings {
8176
8451
  /**
8177
- * Whether the numbers mean anything: `"unsupported"` on a device with no timestamp queries — the
8178
- * CI software adapter is one — `"disabled"` until `profileTasks` is on, `"pending"` until the
8179
- * first readback lands, `"error"` when it failed, `"ok"` otherwise.
8452
+ * Whether the numbers mean anything: `"unsupported"` on a device with no timestamp queries,
8453
+ * `"disabled"` until `profileTasks` is on, `"pending"` until the first readback lands, `"error"`
8454
+ * when it failed, `"available"` otherwise.
8180
8455
  */
8181
8456
  readonly status: string;
8182
- /** The tasks, in frame execution order. Empty unless `status` is `"ok"`. */
8457
+ /** The tasks, in frame execution order. Empty unless `status` is `"available"`. */
8183
8458
  readonly tasks: readonly RenderTaskTiming[];
8184
8459
  }
8185
8460
  /**
@@ -8331,12 +8606,69 @@ interface Renderer {
8331
8606
  * would never settle.
8332
8607
  */
8333
8608
  captureScreenshot(): Promise<RenderCapture>;
8609
+ /**
8610
+ * Creates an offscreen texture a camera can render into, beside the main view
8611
+ * (`docs/architecture/07-rendering.md` §2.11).
8612
+ *
8613
+ * @remarks
8614
+ * Fill it once with {@link Renderer.renderToTexture}, or every frame by setting a camera's
8615
+ * `renderTarget`. Its GPU pass and target are created on the first render or read, so creating
8616
+ * one costs nothing until then, and a headless app may create one (it can never fill it).
8617
+ *
8618
+ * @param width - The width, in pixels: a whole number from 1 to 4096.
8619
+ * @param height - The height, in pixels: a whole number from 1 to 4096.
8620
+ * @returns The texture. Dispose it when done; `app.dispose()` disposes any still open.
8621
+ * @throws IgnifxError with code `IGX-0730` for a side out of range, and `IGX-0106` once the app is
8622
+ * disposed.
8623
+ *
8624
+ * @beta
8625
+ */
8626
+ createRenderTexture(width: number, height: number): RenderTexture;
8627
+ /**
8628
+ * Renders the scene through a camera into a texture on the next frame, beside the main view
8629
+ * (`docs/architecture/07-rendering.md` §2.11).
8630
+ *
8631
+ * @remarks
8632
+ * The camera need not be the main one, and stays a candidate for it. Requests queued for the
8633
+ * same texture render one camera per frame, oldest first. The camera's aspect is the texture's.
8634
+ * Read the result with {@link RenderTexture.readPixels}.
8635
+ *
8636
+ * @param camera - A camera attached to an entity of this app's world.
8637
+ * @param texture - A texture from this renderer's {@link Renderer.createRenderTexture}.
8638
+ * @returns A promise that settles once the frame that rendered it has been submitted.
8639
+ * @throws IgnifxError with code `IGX-0729` on a headless app or while no render loop runs,
8640
+ * `IGX-0731` for a disposed or foreign texture, and `IGX-0732` for a detached camera.
8641
+ *
8642
+ * @example
8643
+ * ```ts
8644
+ * const texture = app.renderer.createRenderTexture(128, 128);
8645
+ * await app.renderer.renderToTexture(previewCamera, texture);
8646
+ * const { data } = await texture.readPixels();
8647
+ * ```
8648
+ *
8649
+ * @beta
8650
+ */
8651
+ renderToTexture(camera: Camera, texture: RenderTexture): Promise<void>;
8334
8652
  /**
8335
8653
  * The latest per-task GPU timing snapshot. Check `status` before reading `tasks`.
8336
8654
  *
8337
8655
  * @returns The snapshot.
8338
8656
  */
8339
8657
  taskTimings(): RenderTaskTimings;
8658
+ /**
8659
+ * Drops the temporal anti-aliasing history, so the next frame starts fresh.
8660
+ *
8661
+ * @remarks
8662
+ * Call it on a camera cut the automatic detection misses (`rendering.taa.cutDistance`): a switch
8663
+ * to another camera nearby, or a scene change under a still camera. Does nothing while
8664
+ * `rendering.taa` is off.
8665
+ *
8666
+ * @example
8667
+ * ```ts
8668
+ * app.renderer.resetTemporalHistory();
8669
+ * ```
8670
+ */
8671
+ resetTemporalHistory(): void;
8340
8672
  /**
8341
8673
  * Declares that a rendering feature must be on — what an extension calls from `register`
8342
8674
  * (`docs/architecture/07-rendering.md` §1.1).
@@ -8482,6 +8814,49 @@ declare class RendererImpl implements Renderer {
8482
8814
  * @returns The presenter, or `null`.
8483
8815
  */
8484
8816
  get presenter(): ScenePresenter | null;
8817
+ /**
8818
+ * Leases the shared scene inputs — depth, normals, velocity and a depth pyramid from one geometry
8819
+ * pass (`docs/architecture/07-rendering.md` §2.12) — for a screen-space effect.
8820
+ *
8821
+ * @remarks
8822
+ * The first call loads the `scene-inputs` chunk and adds the pass to the frame graph; the last
8823
+ * `release()` removes it. Nothing is loaded or added until an effect calls this.
8824
+ *
8825
+ * @returns The lease, or `null` under the null engine or once the renderer is disposed.
8826
+ *
8827
+ * @internal
8828
+ */
8829
+ acquireSceneInputs(): Promise<SceneInputs | null>;
8830
+ /**
8831
+ * Installs temporal anti-aliasing when `rendering.taa.enabled` is on (GI plan steps G5–G6).
8832
+ *
8833
+ * @remarks
8834
+ * Loads the `taa` chunk and leases the scene inputs only then. TAA needs the HDR render path;
8835
+ * without `rendering.hdr` it logs a warning and stays off. `app.initialize()` calls it once, after
8836
+ * the engine exists and before the scene is registered.
8837
+ *
8838
+ * @returns A promise that settles once the passes are in the frame graph, or at once when off.
8839
+ *
8840
+ * @internal
8841
+ */
8842
+ installTemporalAntiAliasing(): Promise<void>;
8843
+ /**
8844
+ * The TAA passes, when installed.
8845
+ *
8846
+ * @returns The handle, or `null`.
8847
+ *
8848
+ * @internal
8849
+ */
8850
+ get taa(): TaaHandle | null;
8851
+ resetTemporalHistory(): void;
8852
+ /**
8853
+ * How many scene-input leases are live; `0` before the first acquire.
8854
+ *
8855
+ * @returns The count.
8856
+ *
8857
+ * @internal
8858
+ */
8859
+ get sceneInputsUserCount(): number;
8485
8860
  /**
8486
8861
  * Whether `app.start()` has registered the render scene, after which Lite has compiled what it is
8487
8862
  * going to compile.
@@ -8626,6 +9001,33 @@ declare class RendererImpl implements Renderer {
8626
9001
  * @throws IgnifxError with code `IGX-0707` when no render loop is running.
8627
9002
  */
8628
9003
  captureScreenshot(): Promise<RenderCapture>;
9004
+ /**
9005
+ * Creates an offscreen texture a camera can render into.
9006
+ *
9007
+ * @param width - The width, in pixels.
9008
+ * @param height - The height, in pixels.
9009
+ * @returns The texture.
9010
+ * @throws IgnifxError with code `IGX-0730` for a side out of range, `IGX-0106` once disposed.
9011
+ */
9012
+ createRenderTexture(width: number, height: number): RenderTexture;
9013
+ /**
9014
+ * Renders the scene through a camera into a texture on the next frame.
9015
+ *
9016
+ * @param camera - The camera.
9017
+ * @param texture - The texture.
9018
+ * @returns A promise that settles once the frame has been submitted.
9019
+ * @throws IgnifxError with code `IGX-0729`, `IGX-0731` or `IGX-0732`; see the interface.
9020
+ */
9021
+ renderToTexture(camera: Camera, texture: RenderTexture): Promise<void>;
9022
+ /**
9023
+ * Points every render texture's pass at this frame's camera. The `PreRender` sync calls it after
9024
+ * the main camera is chosen.
9025
+ *
9026
+ * @param cameras - Every camera in the world, in creation order.
9027
+ *
9028
+ * @internal
9029
+ */
9030
+ syncRenderTextures(cameras: readonly Camera[]): void;
8629
9031
  /**
8630
9032
  * The latest per-task GPU timing snapshot.
8631
9033
  *
@@ -8735,6 +9137,21 @@ declare class RendererImpl implements Renderer {
8735
9137
  * @internal
8736
9138
  */
8737
9139
  attachHandles(engine: LiteEngine, scene: LiteScene, presenter?: ScenePresenter | null): void;
9140
+ /**
9141
+ * The GTAO pass's per-frame work: gives new PBR materials the AO plugin. The `PreRender` system
9142
+ * calls it every frame; it does nothing while `rendering.ambientOcclusion` is off.
9143
+ *
9144
+ * @internal
9145
+ */
9146
+ updateAmbientOcclusion(): void;
9147
+ /**
9148
+ * Whether the GTAO pass is built and running.
9149
+ *
9150
+ * @returns `true` once `rendering.ambientOcclusion` has installed it.
9151
+ *
9152
+ * @internal
9153
+ */
9154
+ get isAmbientOcclusionActive(): boolean;
8738
9155
  /**
8739
9156
  * Writes an sRGB colour onto the render scene's clear colour, so it presents as authored.
8740
9157
  *
@@ -8767,6 +9184,7 @@ declare class RendererImpl implements Renderer {
8767
9184
  applyClearColor(value: ColorLike): void;
8768
9185
  /**
8769
9186
  * Re-applies the clear colour when the scene's image processing changed since it was written.
9187
+ * With `rendering.hdr` on it runs the HDR output pass's per-frame update instead.
8770
9188
  *
8771
9189
  * @remarks
8772
9190
  * The `PreRender` system calls it every frame, after the `Environment` has written its image
@@ -8874,8 +9292,8 @@ declare class RendererImpl implements Renderer {
8874
9292
  */
8875
9293
  takeHeldChanges(): (() => void)[];
8876
9294
  /**
8877
- * Releases the open overlays, the picker and the warm-up probes. The core extension registers it
8878
- * as a disposer.
9295
+ * Releases the open overlays, the picker, the warm-up probes and the scene inputs. The core
9296
+ * extension registers it as a disposer.
8879
9297
  *
8880
9298
  * @internal
8881
9299
  */
@@ -8938,6 +9356,63 @@ export declare function forceRendererDeviceLossForTesting(renderer: Renderer): v
8938
9356
  */
8939
9357
  type LiteCamera = FreeCamera;
8940
9358
  //#endregion
9359
+ //#region src/render/render-texture.d.ts
9360
+ /**
9361
+ * The largest side of a render texture, in pixels.
9362
+ *
9363
+ * @public
9364
+ */
9365
+ export declare const RENDER_TEXTURE_MAX_SIZE = 4096;
9366
+ /**
9367
+ * The Babylon Lite `metadata` key that keeps a render-scene mesh out of every render texture.
9368
+ *
9369
+ * @remarks
9370
+ * A mesh whose `metadata[EDITOR_ONLY_METADATA_KEY]` is `true` draws in the main view but never in
9371
+ * a {@link RenderTexture}: an editor's grid or helper that must not show in its game view or
9372
+ * thumbnails. Set it on a mesh reached through a `.lite` escape hatch, such as
9373
+ * `RenderOverlay.lite.mainScene` (no stability guarantee, `CONSTITUTION.md` §3.4).
9374
+ *
9375
+ * @beta
9376
+ */
9377
+ export declare const EDITOR_ONLY_METADATA_KEY = "ignifxEditorOnly";
9378
+ /**
9379
+ * An offscreen colour target a camera renders into (`docs/architecture/07-rendering.md` §2.11).
9380
+ *
9381
+ * @remarks
9382
+ * Create one with `app.renderer.createRenderTexture(width, height)`. Fill it once with
9383
+ * `app.renderer.renderToTexture(camera, texture)`, or every frame by setting a camera's
9384
+ * `renderTarget`. It holds a GPU pass of the render scene and its target from the first render
9385
+ * on; `dispose()` frees both, and `app.dispose()` disposes every texture still open.
9386
+ *
9387
+ * @example
9388
+ * ```ts
9389
+ * const texture = app.renderer.createRenderTexture(256, 256);
9390
+ * await app.renderer.renderToTexture(minimapCamera, texture);
9391
+ * const pixels = await texture.readPixels();
9392
+ * texture.dispose();
9393
+ * ```
9394
+ *
9395
+ * @beta
9396
+ */
9397
+ interface RenderTexture {
9398
+ /** The width, in pixels. */
9399
+ readonly width: number;
9400
+ /** The height, in pixels. */
9401
+ readonly height: number;
9402
+ /** Whether `dispose()` has run. */
9403
+ readonly isDisposed: boolean;
9404
+ /**
9405
+ * Reads the texture as the last rendered frame left it.
9406
+ *
9407
+ * @returns Tightly packed RGBA8, top row first. All zeros before anything was rendered into it.
9408
+ * @throws IgnifxError with code `IGX-0729` on a headless app or while no render loop runs, and
9409
+ * `IGX-0731` once the texture is disposed.
9410
+ */
9411
+ readPixels(): Promise<RenderCapture>;
9412
+ /** Frees the texture's GPU pass and target. Idempotent; a camera rendering into it stops. */
9413
+ dispose(): void;
9414
+ }
9415
+ //#endregion
8941
9416
  //#region src/math/mat4.d.ts
8942
9417
  /**
8943
9418
  * The backing store of a {@link Mat4}: a `Float32Array` of exactly 16 elements, in column-major
@@ -9482,6 +9957,26 @@ export declare class Camera extends Component implements ComponentHooks {
9482
9957
  };
9483
9958
  clearColor: ColorLike | null;
9484
9959
  priority: number;
9960
+ /**
9961
+ * The texture this camera renders into every frame, instead of the canvas, or `null` for the
9962
+ * canvas (`docs/architecture/07-rendering.md` §2.11).
9963
+ *
9964
+ * @remarks
9965
+ * A camera with a render target is never the main camera, whatever its `priority`; it draws the
9966
+ * same scene from its own view into the texture, at the texture's aspect, in every frame it is
9967
+ * enabled. Runtime state: it is not serialized. Create the texture with
9968
+ * `app.renderer.createRenderTexture`.
9969
+ *
9970
+ * @example
9971
+ * ```ts
9972
+ * const minimap = app.renderer.createRenderTexture(256, 256);
9973
+ * overhead.renderTarget = minimap;
9974
+ * const pixels = await minimap.readPixels();
9975
+ * ```
9976
+ *
9977
+ * @beta
9978
+ */
9979
+ renderTarget: RenderTexture | null;
9485
9980
  /** Applies the schema defaults, exactly as `Component.define` would. */
9486
9981
  constructor();
9487
9982
  /**
@@ -13630,7 +14125,8 @@ interface App {
13630
14125
  */
13631
14126
  registerComponents(types: readonly ConcreteComponentType[]): void;
13632
14127
  /**
13633
- * Runs extension `onStart` hooks and starts the frame loop.
14128
+ * Runs extension `onStart` hooks and starts the frame loop. A no-op while running; after `stop()`
14129
+ * it restarts the loop without running `onStart` again.
13634
14130
  *
13635
14131
  * @returns A promise that settles once the first frame has been submitted.
13636
14132
  */
@@ -13924,7 +14420,8 @@ interface Extension {
13924
14420
  */
13925
14421
  register(ctx: ExtensionContext): void | Promise<void>;
13926
14422
  /**
13927
- * Runs after every extension registered and the Lite engine exists, before the first frame.
14423
+ * Runs after every extension registered and the Lite engine exists, before the first frame. It
14424
+ * runs once: a start after `app.stop()` does not run it again.
13928
14425
  *
13929
14426
  * @param app - The app being started.
13930
14427
  * @returns Nothing, or a promise `app.start()` awaits.
@@ -15683,11 +16180,12 @@ export declare class Vec4 {
15683
16180
  */
15684
16181
  type LiteEnvironmentTextures = EnvironmentTextures;
15685
16182
  /**
15686
- * The tone-mapping curves `docs/architecture/07-rendering.md` §2.5 exposes.
16183
+ * The tone-mapping curves `docs/architecture/07-rendering.md` §2.5 exposes. `"agx"` is ignifx's
16184
+ * own Lite curve (`./agx-tone-mapping.ts`); the others are Lite's built-ins.
15687
16185
  *
15688
16186
  * @public
15689
16187
  */
15690
- export declare const TONE_MAPPING_NAMES: readonly ["none", "standard", "aces", "neutral"];
16188
+ export declare const TONE_MAPPING_NAMES: readonly ["none", "standard", "aces", "neutral", "agx"];
15691
16189
  //#endregion
15692
16190
  //#region src/render/environment-asset.d.ts
15693
16191
  /**
@@ -16313,6 +16811,21 @@ interface LightShadowSettings {
16313
16811
  cascades: number;
16314
16812
  /** The distance beyond which nothing is shadowed, in metres; `0` takes Lite's default. */
16315
16813
  maxDistance: number;
16814
+ /**
16815
+ * Whether cascades use a stable sphere fit, CSM only. `true` stops shadow edges shimmering as the
16816
+ * camera moves, at the cost of some resolution. Default `false`.
16817
+ */
16818
+ stabilizeCascades: boolean;
16819
+ /**
16820
+ * How the cascade splits are spaced, CSM only, from `0` (even) to `1` (logarithmic: more detail
16821
+ * near the camera). Default `0.5`.
16822
+ */
16823
+ cascadeLambda: number;
16824
+ /**
16825
+ * The fraction of each cascade that cross-fades into the next, CSM only, from `0` to `1`; `0`
16826
+ * turns blending off and shows hard seams. Default `0.1`.
16827
+ */
16828
+ cascadeBlend: number;
16316
16829
  }
16317
16830
  /**
16318
16831
  * A light source (`docs/architecture/07-rendering.md` §2.2).
@@ -18219,6 +18732,46 @@ export declare class Model extends Component implements ComponentHooks {
18219
18732
  consumeCasterChange(): boolean;
18220
18733
  }
18221
18734
  //#endregion
18735
+ //#region src/lite/gpu/bloom-hdr.d.ts
18736
+ /**
18737
+ * The tuning a `PostProcessStack`'s `bloom` record feeds the chain.
18738
+ *
18739
+ * @internal
18740
+ */
18741
+ interface HdrBloomTuning {
18742
+ /** How much glow is mixed in, 0–1. */
18743
+ readonly intensity: number;
18744
+ /** How far the glow spreads, 0–1: the weight of each lower mip when it is upsampled. */
18745
+ readonly radius: number;
18746
+ /** The linear luminance below which nothing glows; `0` lets every pixel contribute. */
18747
+ readonly threshold: number;
18748
+ }
18749
+ /**
18750
+ * A recorded HDR bloom chain.
18751
+ *
18752
+ * @internal
18753
+ */
18754
+ interface HdrBloom {
18755
+ /** The mip chain, largest first. */
18756
+ readonly mips: readonly Texture2D[];
18757
+ /** How many frame-graph tasks it recorded. */
18758
+ readonly taskCount: number;
18759
+ /**
18760
+ * Switches every task of the chain on or off.
18761
+ *
18762
+ * @param enabled - `false` to skip the chain; the HDR target then reaches the output pass as is.
18763
+ */
18764
+ setEnabled(enabled: boolean): void;
18765
+ /**
18766
+ * Uploads the tuning, when it changed.
18767
+ *
18768
+ * @param tuning - The values.
18769
+ */
18770
+ apply(tuning: HdrBloomTuning): void;
18771
+ /** Disables the tasks, makes them inert to a rebuild, and frees the mips and effects. */
18772
+ dispose(): void;
18773
+ }
18774
+ //#endregion
18222
18775
  //#region src/render/post-process-stack.d.ts
18223
18776
  /**
18224
18777
  * The `PostProcessStack` component (`docs/architecture/07-rendering.md` §2.7): the three effects the
@@ -18291,23 +18844,36 @@ export declare class Model extends Component implements ComponentHooks {
18291
18844
  /**
18292
18845
  * The `bloom` record a `PostProcessStack` declares (`docs/architecture/07-rendering.md` §2.7).
18293
18846
  *
18847
+ * @remarks
18848
+ * Two bloom passes share the record. Without `rendering.hdr` it is Lite's LDR bloom, recorded in the
18849
+ * chain after tone mapping, and `order`, `weight`, `kernel`, `threshold`, `exposure` and `scale`
18850
+ * apply. With `rendering.hdr` the HDR bloom **replaces** it: a downsample/upsample chain on the
18851
+ * linear scene colour, always before the output pass whatever `order` says, tuned by `intensity`,
18852
+ * `radius` and `hdrThreshold` (GI plan step G12).
18853
+ *
18294
18854
  * @public
18295
18855
  */
18296
18856
  interface BloomEffectSettings {
18297
18857
  /** Whether the glow pass runs. */
18298
18858
  enabled: boolean;
18299
- /** Position in the chain; lower runs first. */
18859
+ /** Position in the chain; lower runs first. LDR bloom only. */
18300
18860
  order: number;
18301
- /** How strongly the glow is mixed back in. */
18861
+ /** How strongly the glow is mixed back in. LDR bloom only. */
18302
18862
  weight: number;
18303
- /** The blur kernel width, in pixels. */
18863
+ /** The blur kernel width, in pixels. LDR bloom only. */
18304
18864
  kernel: number;
18305
- /** The luminance above which a pixel glows. */
18865
+ /** The luminance above which a pixel glows. LDR bloom only; HDR bloom reads `hdrThreshold`. */
18306
18866
  threshold: number;
18307
- /** An exposure applied while extracting highlights. */
18867
+ /** An exposure applied while extracting highlights. LDR bloom only. */
18308
18868
  exposure: number;
18309
- /** The fraction of full resolution the blur runs at. */
18869
+ /** The fraction of full resolution the blur runs at. LDR bloom only. */
18310
18870
  scale: number;
18871
+ /** HDR bloom: how much glow is mixed into the frame, 0–1. */
18872
+ intensity: number;
18873
+ /** HDR bloom: how far the glow spreads, 0 (tight) to 1 (wide). */
18874
+ radius: number;
18875
+ /** HDR bloom: the linear luminance below which nothing glows; `0`, the default, lets every pixel glow by its energy. */
18876
+ hdrThreshold: number;
18311
18877
  }
18312
18878
  /**
18313
18879
  * The `smaa` record a `PostProcessStack` declares (`docs/architecture/07-rendering.md` §2.7).
@@ -18340,6 +18906,50 @@ interface ImageProcessingEffectSettings {
18340
18906
  /** Position in the chain; lower runs first. */
18341
18907
  order: number;
18342
18908
  }
18909
+ /**
18910
+ * The `contactShadows` record a `PostProcessStack` declares (GI plan step G10,
18911
+ * `docs/architecture/07-rendering.md` §2.7): Lite's screen-space contact shadows towards the main
18912
+ * directional light, fed from the shared scene-input depth.
18913
+ *
18914
+ * @public
18915
+ */
18916
+ interface ContactShadowsEffectSettings {
18917
+ /** Whether the pass runs. */
18918
+ enabled: boolean;
18919
+ /** How dark a contact gets, 0 to 4. */
18920
+ intensity: number;
18921
+ /** How far each ray marches towards the light, in world units. */
18922
+ length: number;
18923
+ /** How thick a surface is assumed to be behind its depth, in world units. */
18924
+ thickness: number;
18925
+ /** March steps per pixel, 1 to 64. */
18926
+ samples: number;
18927
+ }
18928
+ /**
18929
+ * The `ssgi` record a `PostProcessStack` declares (GI plan step G11,
18930
+ * `docs/architecture/07-rendering.md` §2.7): Lite's `@beta` screen-space global illumination, one
18931
+ * bounce of the lit scene colour. Desktop tier.
18932
+ *
18933
+ * @beta
18934
+ */
18935
+ interface SsgiEffectSettings {
18936
+ /** Whether the pass runs. */
18937
+ enabled: boolean;
18938
+ /** How strongly the bounce is added, 0 to 4. */
18939
+ intensity: number;
18940
+ /** How far each ray marches, in world units. */
18941
+ radius: number;
18942
+ /** March steps per ray, 1 to 64. */
18943
+ samples: number;
18944
+ /** Whether rays are traced at half resolution. A change rebuilds the pass. */
18945
+ halfResolution: boolean;
18946
+ /**
18947
+ * How much of the environment's diffuse light remains while SSGI runs, 0 to 1, so the bounce is
18948
+ * not counted twice. Needs `rendering.hdr` or the `materialPlugins` feature; without either the
18949
+ * environment is left as it is.
18950
+ */
18951
+ environmentDiffuse: number;
18952
+ }
18343
18953
  /**
18344
18954
  * One instance of a post-process chain, attached to the main camera's entity
18345
18955
  * (`docs/architecture/07-rendering.md` §2.7).
@@ -18374,6 +18984,13 @@ export declare class PostProcessStack extends Component implements ComponentHook
18374
18984
  smaa: SmaaEffectSettings;
18375
18985
  imageProcessing: ImageProcessingEffectSettings;
18376
18986
  custom: CustomEffectSettings[];
18987
+ contactShadows: ContactShadowsEffectSettings;
18988
+ /**
18989
+ * Screen-space global illumination; see {@link SsgiEffectSettings}.
18990
+ *
18991
+ * @beta
18992
+ */
18993
+ ssgi: SsgiEffectSettings;
18377
18994
  /** Applies the schema defaults, exactly as `Component.define` would. */
18378
18995
  constructor();
18379
18996
  /**
@@ -18383,6 +19000,15 @@ export declare class PostProcessStack extends Component implements ComponentHook
18383
19000
  * `postProcessing` rendering feature is off.
18384
19001
  */
18385
19002
  get taskCount(): number;
19003
+ /**
19004
+ * The HDR bloom chain, once it is recorded.
19005
+ *
19006
+ * @returns The chain, or `null` without `rendering.hdr`, before bloom was enabled, or while its
19007
+ * chunk loads.
19008
+ *
19009
+ * @internal
19010
+ */
19011
+ get hdrBloom(): HdrBloom | null;
18386
19012
  /** Nothing to do at attach: the chain is built on the first sync that wants an effect. */
18387
19013
  onAttach(): void;
18388
19014
  /** Disables and disposes every task the stack recorded. */
@@ -18564,6 +19190,115 @@ type EntityOverrideField = "name" | "active" | "static" | "layer" | "tags";
18564
19190
  */
18565
19191
  export declare function parseOverridePath(path: string): OverridePath;
18566
19192
  //#endregion
19193
+ //#region src/serialization/prefab-overrides.d.ts
19194
+ /**
19195
+ * Which overrides of an instance {@link applyOverridesToAsset} and {@link revertOverrides} act on.
19196
+ *
19197
+ * @public
19198
+ */
19199
+ interface PrefabOverrideSelection {
19200
+ /**
19201
+ * Override paths to act on. A path selects every override at that path or below it, so
19202
+ * `"<entityUid>"` selects everything on that entity and `"<entityUid>/components/<componentUid>"`
19203
+ * selects a component's removal, its `enabled` flag, and its props. An `add` to
19204
+ * `<entityUid>/components` sits at `<entityUid>/components/<addedUid>`. Omitted, every override
19205
+ * is selected.
19206
+ */
19207
+ readonly paths?: readonly string[];
19208
+ }
19209
+ /**
19210
+ * An override {@link applyOverridesToAsset} left on the instance, and why.
19211
+ *
19212
+ * @public
19213
+ */
19214
+ interface PrefabOverrideSkip {
19215
+ /** The override, as the instance entry holds it. */
19216
+ readonly override: SceneFileOverride;
19217
+ /** Why it could not be written into the prefab file. */
19218
+ readonly reason: string;
19219
+ }
19220
+ /**
19221
+ * What {@link applyOverridesToAsset} returns.
19222
+ *
19223
+ * @public
19224
+ */
19225
+ interface PrefabApplyResult {
19226
+ /** The new prefab file, with the applied overrides written into it. */
19227
+ readonly asset: SceneFile;
19228
+ /** The content hash of {@link PrefabApplyResult.asset}, as {@link computeSceneHash} writes it. */
19229
+ readonly hash: string;
19230
+ /**
19231
+ * The instance entry without the applied overrides, recording {@link PrefabApplyResult.hash}. It
19232
+ * expands to the same values it did before the apply; a component an applied `add` brought now
19233
+ * comes from the prefab, so like every prefab component it gets a fresh uid per instance.
19234
+ */
19235
+ readonly instance: SceneFileInstance;
19236
+ /** The overrides written into the prefab, in instance order. */
19237
+ readonly applied: readonly SceneFileOverride[];
19238
+ /** The selected overrides that stay on the instance, in instance order. */
19239
+ readonly skipped: readonly PrefabOverrideSkip[];
19240
+ }
19241
+ /**
19242
+ * Writes an instance's overrides into the prefab file it instances, so every instance of the prefab
19243
+ * gets them — Unity's "Apply to prefab" (ADR-0005).
19244
+ *
19245
+ * @remarks
19246
+ * A pure function over the two files: nothing is loaded, and the same input always gives
19247
+ * byte-identical output through {@link stringifySceneFile}. The rules:
19248
+ *
19249
+ * - Property, `enabled`, transform, and entity-field overrides change the prefab's record. An `add`
19250
+ * appends the component, keeping its uid; a `remove` deletes the component.
19251
+ * - On a prefab with exactly one root, the instance root's own `name`, `transform`, and other entity
19252
+ * fields are its placement, not prefab content, so overrides of the root's entity fields and
19253
+ * transform are skipped.
19254
+ * - Overrides reach only the prefab's own entities. Content of a scene the prefab itself instances
19255
+ * is not addressable by an override path, so a nested prefab is never edited: an override that
19256
+ * names something the prefab file does not hold is skipped.
19257
+ * - An override is skipped when an earlier override that stays on the instance overlaps its path, so
19258
+ * the instance keeps the value it had.
19259
+ * - A skipped override stays on the returned instance. The instance's own `components` are not
19260
+ * overrides and are not touched.
19261
+ * - Other instances of the prefab keep their overrides, which still win over the new prefab values
19262
+ * at the same path. Record {@link PrefabApplyResult.hash} on them, or loading them logs `IGX-0604`.
19263
+ * - References inside added components (`$entity`, `$component`) are copied unchanged.
19264
+ *
19265
+ * @param instance - The instance entry whose overrides to apply; its `scene` should name `asset`.
19266
+ * @param asset - The prefab file the entry instances.
19267
+ * @param selection - Which overrides to apply; all of them by default.
19268
+ * @returns The new prefab file and its hash, the instance entry without the applied overrides, and
19269
+ * what was applied or skipped.
19270
+ * @throws IgnifxError with code `IGX-0609` when a selected override path is outside the grammar.
19271
+ *
19272
+ * @example
19273
+ * ```ts
19274
+ * const result = await applyOverridesToAsset(spawn.instance, prefabFile);
19275
+ * await app.storage.write("prefabs/enemy.prefab.json", stringifySceneFile(result.asset));
19276
+ * ```
19277
+ *
19278
+ * @public
19279
+ */
19280
+ export declare function applyOverridesToAsset(instance: SceneFileInstance, asset: SceneFile, selection?: PrefabOverrideSelection): Promise<PrefabApplyResult>;
19281
+ /**
19282
+ * Drops an instance's overrides so it follows its prefab again — Unity's "Revert".
19283
+ *
19284
+ * @remarks
19285
+ * A pure function: the entry's `scene` and `hash` are kept, and `overrides` is omitted when none
19286
+ * remain. Reverting an `add` also reverts the overrides below the added component when the
19287
+ * selection path covers them (`<entityUid>/components/<addedUid>` does).
19288
+ *
19289
+ * @param instance - The instance entry.
19290
+ * @param selection - Which overrides to drop; all of them by default.
19291
+ * @returns The entry without the selected overrides, or `instance` itself when none was selected.
19292
+ *
19293
+ * @example
19294
+ * ```ts
19295
+ * const reverted = revertOverrides(spawn.instance, { paths: [`${rootUid}/components/${aiUid}`] });
19296
+ * ```
19297
+ *
19298
+ * @public
19299
+ */
19300
+ export declare function revertOverrides(instance: SceneFileInstance, selection?: PrefabOverrideSelection): SceneFileInstance;
19301
+ //#endregion
18567
19302
  //#region src/serialization/scene-loader.d.ts
18568
19303
  /**
18569
19304
  * Options accepted by {@link createSceneLoader}.
@@ -19669,5 +20404,5 @@ export declare function transformSchema(): Schema;
19669
20404
  */
19670
20405
  export declare const TWEEN_SYSTEM_ORDER = -100;
19671
20406
  //#endregion
19672
- export type { AddComponentFromRecordOptions, App, AppEvents, AppLiteHandles, AppSettings, ArrayFieldSpec, AssetFieldSpec, AssetHandle, AssetLoadErrorOptions, AssetLoader, AssetManifest, AssetManifestEntry, AssetProgress, AssetRef, AssetRefValue, AssetState, AssetTypeDefinition, AssetTypeToken, Assets, AssetsCreateOptions, AssetsSettings, BatchHandle, BloomEffectSettings, BoolFieldSpec, BoxMeshOptions, CameraProjection, CanvasAlphaMode, CapsuleMeshOptions, Clock, ColorFieldSpec, ColorLike, ComponentBuildResult, ComponentClassInfo, ComponentDefinition, ComponentHandle, ComponentHooks, ComponentInit, ComponentInitValue, ComponentRefFieldSpec, ComponentReplacement, ComponentStatics, ComponentType, ComponentTypeToken, ConcreteComponentType, ConnectOptions, ConsoleLike, ConsoleSinkOptions, Coroutine, CoroutineHandle, CoroutineHost, CoroutineYield, CreateAppOptions, CreateEntityOptions, CreateSceneOptions, CurveFieldSpec, CurveKey, CurveValue, CustomEffectInit, CustomEffectSettings, CustomFieldCodec, CustomFieldSpec, CylinderMeshOptions, DecodeResult, DeferredQueue, DeviceLostInfo, DiagnosticsGroup, DiagnosticsOptions, Disconnect, EasingFunction, EasingName, EntityHandle, EntityOverrideField, EntityPrefabLink, EntityRefFieldSpec, EnumFieldSpec, EnvironmentAssetLiteHandles, EnvironmentDefinition, EnvironmentFogMode, EnvironmentFogSettings, EnvironmentSkyboxSettings, ErrorCode, ErrorCodeDescription, ErrorCodeRegistry, ErrorContext, ErrorFormatMode, ErrorReport, Extension, ExtensionContext, FetchLike, FieldDefinition, FieldOptions, FieldSpec, FieldsOf, FileStorageOptions, FontAssetLiteHandles, FrameSample, FrameState, GpuAdapterInfo, GroundMeshOptions, HotReloadHost, HotReloadKind, HotReloadModule, HotReloadOptions, HotReloadPolicy, HotReloadReport, HotReloadStatics, IgnifxErrorOptions, IgnifxUniformName, ImageProcessingEffectSettings, ImageProcessingSettings, InstanceRange, InstancedMeshLod, InstancedMeshRendererLiteHandles, InstantiateOptions, InstantiateSceneOptions, JsonArray, JsonObject, JsonSchemaObject, JsonValue, LayerMaskFieldSpec, LayersSettings, LightShadowSettings, LightType, LiteAnimationGroup, LiteAssetContainer, LiteCamera, LiteEngine, LiteEnvironmentTextures, LiteFont, AdapterLight as LiteLight, LiteMaterial, LiteMaterialPluginPoint, LiteMesh, LitePbrMaterial, LiteScene, LiteSceneNode, LiteShaderMaterial, LiteShadowGenerator, LiteSkeleton, LiteStandardMaterial, LiteStorageBuffer, LiteSystemUniformName, LiteTexture2D, LoadOptions, LoadProgress, LoadSceneDependenciesOptions, LoadSceneFileOptions, LoadSceneOptions, LoaderContext, LogRecord, LogSink, LogThreshold, Logger, LoggerOptions, ManualClock, MapFieldSpec, Mat4Elements, Mat4Like, MaterialAlphaMode, MaterialAssetLiteHandles, MaterialDefinition, MaterialKind, MaterialPluginDefinition, MaterialPluginDefinitionInit, MemorySink, MeshAssetLiteHandles, MeshGeometryData, MeshOptionKind, MeshPrimitive, MeshPrimitiveDefinition, MeshPrimitiveOptionKinds, ModelAssetLiteHandles, ModelInstantiation, MutableQuat, MutableVec2, MutableVec3, MutableVec4, NumberFieldSpec, OptionalFieldSpec, OverridePath, PartialFieldsOf, PbrMaterialDefinition, PhaseIndex, PixelTextureOptions, PlaneMeshOptions, PlatformInfo, PlatformKind, PlatformOs, ProfileScope, QuatLike, RandomSource, Ray, RayVector, RecordFieldSpec, ReferenceDecoder, ReferenceEncoder, RegisterAssetOptions, RegisterComponentOptions, RegisterSystemOptions, RenderCapture, RenderOverlay, RenderOverlayLiteHandles, RenderPick, RenderPickIgnore, RenderPickOptions, RenderSurface, RenderTaskTiming, RenderTaskTimings, Renderer, RenderingFeature, RenderingFeatureSettings, RenderingSettings, SceneAsset, SceneBuildResult, SceneFile, SceneFileAssetRef, SceneFileComponent, SceneFileEntity, SceneFileInstance, SceneFileIssue, SceneFileOverride, SceneFileTransform, SceneLoadIssue, SceneLoaderOptions, Schema, SchemaDescription, SchemaDescriptionMeta, SchemaFieldDescription, SchemaIssue, ScriptCallbacks, ScriptClassInfo, ScriptDefinition, ScriptStatics, SerializeIssue, SerializeSceneOptions, ServiceClassKey, ServiceKey, ServiceNameKey, ServiceRegistry, SetParentOptions, SettingsInput, ShaderAttributeName, ShaderBlendMode, ShaderCullMode, ShaderDeclaration, ShaderDefineDeclaration, ShaderInstancingMode, ShaderKind, ShaderMaterialDefinition, ShaderMaterialDefinitionInput, ShaderPipelineState, ShaderStorageDeclaration, ShaderTextureDeclaration, ShaderTextureFallback, ShaderUniformDeclaration, ShaderUniformType, ShadowTechniqueName, SignalHandler, SignalLike, SignalOptions, SignalOwner, SmaaEffectSettings, SortingLayersSettings, SphereMeshOptions, StandardMaterialDefinition, Storage, StorageBackend, StorageBufferAssetLiteHandles, StoredValue, StoredValueKind, StringFieldSpec, SurfaceHookName, SurfaceHostCapabilities, SurfaceHostFamily, SurfaceShaderBinding, SurfaceShaderInit, SurfaceShaderReference, System, SystemContext, SystemEditMode, TextureAssetLiteHandles, TextureImportOptions, Time, TimeSettings, ToneMappingCurve, TorusMeshOptions, TweenOptions, TweenProps, TweenTargetValue, TweenValueKind, TweenableValue, Tweens, UlidFactoryOptions, Vec2Like, Vec3Like, Vec4Like, VectorFieldSpec, WaitInstruction, WebGpuInfo, WorldLiteHandles };
20407
+ export type { AddComponentFromRecordOptions, AmbientOcclusionQuality, AmbientOcclusionSettings, App, AppEvents, AppLiteHandles, AppSettings, ArrayFieldSpec, AssetFieldSpec, AssetHandle, AssetLoadErrorOptions, AssetLoader, AssetManifest, AssetManifestEntry, AssetProgress, AssetRef, AssetRefValue, AssetState, AssetTypeDefinition, AssetTypeToken, Assets, AssetsCreateOptions, AssetsSettings, AutoExposureSettings, BatchHandle, BloomEffectSettings, BoolFieldSpec, BoxMeshOptions, CameraProjection, CanvasAlphaMode, CapsuleMeshOptions, Clock, ColorFieldSpec, ColorLike, ComponentBuildResult, ComponentClassInfo, ComponentDefinition, ComponentHandle, ComponentHooks, ComponentInit, ComponentInitValue, ComponentRefFieldSpec, ComponentReplacement, ComponentStatics, ComponentType, ComponentTypeToken, ConcreteComponentType, ConnectOptions, ConsoleLike, ConsoleSinkOptions, ContactShadowsEffectSettings, Coroutine, CoroutineHandle, CoroutineHost, CoroutineYield, CreateAppOptions, CreateEntityOptions, CreateSceneOptions, CurveFieldSpec, CurveKey, CurveValue, CustomEffectInit, CustomEffectSettings, CustomFieldCodec, CustomFieldSpec, CylinderMeshOptions, DecodeResult, DeferredQueue, DeviceLostInfo, DiagnosticsGroup, DiagnosticsOptions, Disconnect, EasingFunction, EasingName, EntityHandle, EntityOverrideField, EntityPrefabLink, EntityRefFieldSpec, EnumFieldSpec, EnvironmentAssetLiteHandles, EnvironmentDefinition, EnvironmentFogMode, EnvironmentFogSettings, EnvironmentSkyboxSettings, ErrorCode, ErrorCodeDescription, ErrorCodeRegistry, ErrorContext, ErrorFormatMode, ErrorReport, Extension, ExtensionContext, FetchLike, FieldDefinition, FieldOptions, FieldSpec, FieldsOf, FileStorageOptions, FontAssetLiteHandles, FrameSample, FrameState, GpuAdapterInfo, GroundMeshOptions, HotReloadHost, HotReloadKind, HotReloadModule, HotReloadOptions, HotReloadPolicy, HotReloadReport, HotReloadStatics, IgnifxErrorOptions, IgnifxUniformName, ImageProcessingEffectSettings, ImageProcessingSettings, InstanceRange, InstancedMeshLod, InstancedMeshRendererLiteHandles, InstantiateOptions, InstantiateSceneOptions, JsonArray, JsonObject, JsonSchemaObject, JsonValue, LayerMaskFieldSpec, LayersSettings, LightShadowSettings, LightType, LiteAnimationGroup, LiteAssetContainer, LiteCamera, LiteEngine, LiteEnvironmentTextures, LiteFont, AdapterLight as LiteLight, LiteMaterial, LiteMaterialPluginPoint, LiteMesh, LitePbrMaterial, LiteScene, LiteSceneNode, LiteShaderMaterial, LiteShadowGenerator, LiteSkeleton, LiteStandardMaterial, LiteStorageBuffer, LiteSystemUniformName, LiteTexture2D, LoadOptions, LoadProgress, LoadSceneDependenciesOptions, LoadSceneFileOptions, LoadSceneOptions, LoaderContext, LogRecord, LogSink, LogThreshold, Logger, LoggerOptions, ManualClock, MapFieldSpec, Mat4Elements, Mat4Like, MaterialAlphaMode, MaterialAssetLiteHandles, MaterialDefinition, MaterialKind, MaterialPluginDefinition, MaterialPluginDefinitionInit, MemorySink, MeshAssetLiteHandles, MeshGeometryData, MeshOptionKind, MeshPrimitive, MeshPrimitiveDefinition, MeshPrimitiveOptionKinds, ModelAssetLiteHandles, ModelInstantiation, MutableQuat, MutableVec2, MutableVec3, MutableVec4, NumberFieldSpec, OptionalFieldSpec, OverridePath, PartialFieldsOf, PbrMaterialDefinition, PhaseIndex, PixelTextureOptions, PlaneMeshOptions, PlatformInfo, PlatformKind, PlatformOs, PrefabApplyResult, PrefabOverrideSelection, PrefabOverrideSkip, ProfileScope, QuatLike, RandomSource, Ray, RayVector, RecordFieldSpec, ReferenceDecoder, ReferenceEncoder, RegisterAssetOptions, RegisterComponentOptions, RegisterSystemOptions, RenderCapture, RenderOverlay, RenderOverlayLiteHandles, RenderPick, RenderPickIgnore, RenderPickOptions, RenderSurface, RenderTaskTiming, RenderTaskTimings, RenderTexture, Renderer, RenderingFeature, RenderingFeatureSettings, RenderingSettings, SceneAsset, SceneBuildResult, SceneFile, SceneFileAssetRef, SceneFileComponent, SceneFileEntity, SceneFileInstance, SceneFileIssue, SceneFileOverride, SceneFileTransform, SceneLoadIssue, SceneLoaderOptions, Schema, SchemaDescription, SchemaDescriptionMeta, SchemaFieldDescription, SchemaIssue, ScriptCallbacks, ScriptClassInfo, ScriptDefinition, ScriptStatics, SerializeIssue, SerializeSceneOptions, ServiceClassKey, ServiceKey, ServiceNameKey, ServiceRegistry, SetParentOptions, SettingsInput, ShaderAttributeName, ShaderBlendMode, ShaderCullMode, ShaderDeclaration, ShaderDefineDeclaration, ShaderInstancingMode, ShaderKind, ShaderMaterialDefinition, ShaderMaterialDefinitionInput, ShaderPipelineState, ShaderStorageDeclaration, ShaderTextureDeclaration, ShaderTextureFallback, ShaderUniformDeclaration, ShaderUniformType, ShadowTechniqueName, SignalHandler, SignalLike, SignalOptions, SignalOwner, SmaaEffectSettings, SortingLayersSettings, SphereMeshOptions, SsgiEffectSettings, StandardMaterialDefinition, Storage, StorageBackend, StorageBufferAssetLiteHandles, StoredValue, StoredValueKind, StringFieldSpec, SurfaceHookName, SurfaceHostCapabilities, SurfaceHostFamily, SurfaceShaderBinding, SurfaceShaderInit, SurfaceShaderReference, System, SystemContext, SystemEditMode, TaaSettings, TextureAssetLiteHandles, TextureImportOptions, Time, TimeSettings, ToneMappingCurve, TorusMeshOptions, TweenOptions, TweenProps, TweenTargetValue, TweenValueKind, TweenableValue, Tweens, UlidFactoryOptions, Vec2Like, Vec3Like, Vec4Like, VectorFieldSpec, WaitInstruction, WebGpuInfo, WorldLiteHandles };
19673
20408
  //# sourceMappingURL=index.d.ts.map