@ignifx/core 0.1.0 → 0.2.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.d.ts +171 -10
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +275 -24
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/dist/index.js
CHANGED
|
@@ -209,6 +209,8 @@ const CoreErrorCode = {
|
|
|
209
209
|
invalidAssetFile: "IGX-0709",
|
|
210
210
|
/** A `PostProcessStack` was attached without the `postProcessing` rendering feature. */
|
|
211
211
|
postProcessingFeatureOff: "IGX-0710",
|
|
212
|
+
/** An `Environment.skybox` asks for a background the environment it installed cannot draw. */
|
|
213
|
+
skyboxFixedAtLoad: "IGX-0711",
|
|
212
214
|
/** The host exposes no Web Crypto implementation. */
|
|
213
215
|
cryptoUnavailable: "IGX-1420",
|
|
214
216
|
/** A storage namespace name is not a legal namespace segment. */
|
|
@@ -306,6 +308,7 @@ const CORE_ERROR_MESSAGES = {
|
|
|
306
308
|
"IGX-0708": "{asset} declares the material kind {kind}, which this build cannot construct.",
|
|
307
309
|
"IGX-0709": "{file} is not an {format} file.",
|
|
308
310
|
"IGX-0710": "{entity} attached a PostProcessStack, but rendering.features.postProcessing is off.",
|
|
311
|
+
"IGX-0711": "{entity} asks for an Environment.skybox that {asset} was not loaded with; declare it in the .environment.json.",
|
|
309
312
|
"IGX-1420": "This host does not expose Web Crypto.",
|
|
310
313
|
"IGX-1421": "{namespace} is not a valid storage namespace.",
|
|
311
314
|
"IGX-1422": "That storage key is empty, too long, or contains a control character.",
|
|
@@ -8357,6 +8360,48 @@ function loadSceneEnvironment(scene, options) {
|
|
|
8357
8360
|
return loadEnvironment(scene, options.url, liteOptions);
|
|
8358
8361
|
}
|
|
8359
8362
|
/**
|
|
8363
|
+
* Views a scene through its undeclared environment slot.
|
|
8364
|
+
*
|
|
8365
|
+
* @param scene - The scene.
|
|
8366
|
+
* @returns The same object, typed so the slot is reachable.
|
|
8367
|
+
*/
|
|
8368
|
+
function environmentSlotOf(scene) {
|
|
8369
|
+
return scene;
|
|
8370
|
+
}
|
|
8371
|
+
/**
|
|
8372
|
+
* Points a scene at an already-loaded set of environment textures, without loading anything.
|
|
8373
|
+
*
|
|
8374
|
+
* @remarks
|
|
8375
|
+
* This is how an `Environment` component swaps environments at runtime: the textures belong to the
|
|
8376
|
+
* `EnvironmentAsset` that loaded them and stay alive as long as its handle is retained, so
|
|
8377
|
+
* switching between two loaded assets uploads nothing and frees nothing.
|
|
8378
|
+
*
|
|
8379
|
+
* The specular reflection follows only after the scene's material groups are rebuilt
|
|
8380
|
+
* (`rebuildRenderables` in `../shadow.ts`): a PBR bind group holds the cube map's `GPUTextureView`,
|
|
8381
|
+
* not the slot. The diffuse harmonics and the LOD scale follow immediately, because the render
|
|
8382
|
+
* task's scene-UBO cache is keyed on this object's identity.
|
|
8383
|
+
*
|
|
8384
|
+
* @param scene - The scene to light.
|
|
8385
|
+
* @param textures - The textures to light it with.
|
|
8386
|
+
* @returns `true` when the scene was lit by something else and now is not — the caller owes a
|
|
8387
|
+
* renderable rebuild; `false` when these textures were already installed and nothing was written.
|
|
8388
|
+
*
|
|
8389
|
+
* @example
|
|
8390
|
+
* ```ts
|
|
8391
|
+
* if (installSceneEnvironment(scene, asset.lite.textures)) {
|
|
8392
|
+
* await rebuildRenderables(scene);
|
|
8393
|
+
* }
|
|
8394
|
+
* ```
|
|
8395
|
+
*
|
|
8396
|
+
* @internal
|
|
8397
|
+
*/
|
|
8398
|
+
function installSceneEnvironment(scene, textures) {
|
|
8399
|
+
const slot = environmentSlotOf(scene);
|
|
8400
|
+
if (slot._envTextures === textures) return false;
|
|
8401
|
+
slot._envTextures = textures;
|
|
8402
|
+
return true;
|
|
8403
|
+
}
|
|
8404
|
+
/**
|
|
8360
8405
|
* Rotates the environment around the world Y axis.
|
|
8361
8406
|
*
|
|
8362
8407
|
* @param scene - The scene to rotate the environment of.
|
|
@@ -8977,6 +9022,11 @@ function environmentDefinition(overrides = {}) {
|
|
|
8977
9022
|
* both live under `src/render/gpu/` and are measured by the browser project rather than the Node
|
|
8978
9023
|
* coverage floor. Fog, the clear colour, and the "which asset is installed" bookkeeping are plain
|
|
8979
9024
|
* scene state and stay on the component, where Node tests reach them.
|
|
9025
|
+
*
|
|
9026
|
+
* {@link installLoadedEnvironment} is the runtime swap: it moves the scene onto an already-loaded
|
|
9027
|
+
* asset's cube map with no fetch, no decode, and no upload. It lives here because the textures it
|
|
9028
|
+
* installs only exist with a device, but the write itself is a plain field assignment, so a headless
|
|
9029
|
+
* test that hands it a fabricated handle still exercises it.
|
|
8980
9030
|
*/
|
|
8981
9031
|
/**
|
|
8982
9032
|
* Applies an environment's rotation and blur to the scene.
|
|
@@ -9009,6 +9059,26 @@ function applyEnvironmentOrientation(scene, rotationDegrees, blur) {
|
|
|
9009
9059
|
function applySceneImageProcessing(scene, exposure, contrast, toneMapping) {
|
|
9010
9060
|
return setSceneImageProcessingOptions(scene, exposure, contrast, toneMapping);
|
|
9011
9061
|
}
|
|
9062
|
+
/**
|
|
9063
|
+
* Moves a scene onto an already-loaded environment's textures.
|
|
9064
|
+
*
|
|
9065
|
+
* @remarks
|
|
9066
|
+
* The specular reflection follows only once the scene's material groups have been rebuilt — a PBR
|
|
9067
|
+
* bind group holds the cube map's texture view, not the scene's slot — so a `true` answer means the
|
|
9068
|
+
* caller owes a `rebuildSceneRenderables`. The `Environment` component discharges that by reporting
|
|
9069
|
+
* the install as a topology change, which the render-sync system coalesces with every other change
|
|
9070
|
+
* of the frame into one rebuild (`docs/architecture/07-rendering.md` §2.2, §2.5).
|
|
9071
|
+
*
|
|
9072
|
+
* @param scene - The render scene.
|
|
9073
|
+
* @param textures - The Lite handles the loaded `EnvironmentAsset` recorded.
|
|
9074
|
+
* @returns `true` when the scene was lit by something else and now is not; `false` when these
|
|
9075
|
+
* textures were already installed, in which case nothing was written.
|
|
9076
|
+
*
|
|
9077
|
+
* @internal
|
|
9078
|
+
*/
|
|
9079
|
+
function installLoadedEnvironment(scene, textures) {
|
|
9080
|
+
return installSceneEnvironment(scene, textures);
|
|
9081
|
+
}
|
|
9012
9082
|
//#endregion
|
|
9013
9083
|
//#region src/render/environment.ts
|
|
9014
9084
|
/**
|
|
@@ -9032,6 +9102,53 @@ function applySceneImageProcessing(scene, exposure, contrast, toneMapping) {
|
|
|
9032
9102
|
* becoming an unhandled rejection (coding standards §8). The visible consequence is that a script
|
|
9033
9103
|
* that ramps exposure every frame gets as many recompiles as the GPU can keep up with and no queue.
|
|
9034
9104
|
*
|
|
9105
|
+
* ## Switching environments at runtime
|
|
9106
|
+
*
|
|
9107
|
+
* An `.env` is loaded **onto the scene** by the asset loader, because that is the only shape Lite's
|
|
9108
|
+
* `loadEnvironment` has (`./environment-asset.ts` explains it at length). Until 2026-09-08 that
|
|
9109
|
+
* meant `environment` was effectively read-only after the first load: the component re-aimed what
|
|
9110
|
+
* the loader had installed and nothing more, so assigning a second loaded handle changed the
|
|
9111
|
+
* rotation and the blur and left the lighting alone. It now installs the asset's recorded handles
|
|
9112
|
+
* on the scene (`./gpu/environment-install.ts`) and reports the install as a **topology change**,
|
|
9113
|
+
* which the render-sync system coalesces into the frame's one `rebuildSceneRenderables` — the step
|
|
9114
|
+
* that makes every PBR material re-bind the new cube map, because a bind group holds the texture
|
|
9115
|
+
* view rather than the scene's slot. Two loaded handles can therefore be swapped back and forth for
|
|
9116
|
+
* free: the GPU resources belong to the assets, stay alive while their handles are retained, and are
|
|
9117
|
+
* released by the asset system exactly as before.
|
|
9118
|
+
*
|
|
9119
|
+
* Installing also re-applies rotation, blur, **and** image processing, because Lite's
|
|
9120
|
+
* `loadEnvironment` overwrites `scene.imageProcessing` (`toneMappingEnabled`, `exposure = 0.8`,
|
|
9121
|
+
* `contrast = 1.2`) as a side effect of every load.
|
|
9122
|
+
*
|
|
9123
|
+
* ## Assigning `null` leaves the scene lit
|
|
9124
|
+
*
|
|
9125
|
+
* Lite 1.27.0 has no inverse of `loadEnvironment` — no `unloadEnvironment`, no
|
|
9126
|
+
* `scene.environmentTexture` to clear — and clearing its slot by hand would leave every PBR
|
|
9127
|
+
* material bound to a cube map the scene no longer admits to having until the next renderable
|
|
9128
|
+
* rebuild. So `environment = null` is documented as "stop steering the environment", not "turn the
|
|
9129
|
+
* lights off": the last installed environment keeps lighting the scene, exactly as detaching the
|
|
9130
|
+
* component does. {@link Environment.installed} keeps naming it, because that is what the scene is
|
|
9131
|
+
* actually lit by. To change the lighting, install a different loaded environment.
|
|
9132
|
+
*
|
|
9133
|
+
* ## `skybox` is decided when the environment loads, not here
|
|
9134
|
+
*
|
|
9135
|
+
* Lite builds the background inside `loadEnvironment`, as a *feature-owned* `Renderable` pushed
|
|
9136
|
+
* onto the scene from a deferred builder that `registerScene` drains
|
|
9137
|
+
* (`lib/_chunks/env-helpers-*.js`). `Renderable` (`index.d.ts` 9678) is `{ order, isTransparent,
|
|
9138
|
+
* mesh?, bind }` — no visibility flag, no size, no handle — and Lite exposes no way to remove one,
|
|
9139
|
+
* so a background that has been built cannot be hidden, resized, or re-aimed at another cube map.
|
|
9140
|
+
* The `.environment.json` is therefore the authority: `skyboxEnabled`, `skybox` and `skyboxSize`
|
|
9141
|
+
* decide the background when the asset loads. The component's `skybox` record is read every frame
|
|
9142
|
+
* so that a value the installed environment cannot deliver is *reported* — `IGX-0711`, once per
|
|
9143
|
+
* component — rather than silently ignored, which is what it was until 2026-09-08. A field left at
|
|
9144
|
+
* its schema default never reports anything, so only a project that actually asked for a different
|
|
9145
|
+
* background hears about it.
|
|
9146
|
+
*
|
|
9147
|
+
* The one improvement that did fit: an environment with `skyboxEnabled` and no explicit `skybox`
|
|
9148
|
+
* now draws **its own** prefiltered cube map (`./loaders/environment-loader.ts`), where Lite's
|
|
9149
|
+
* default was a flat box painted in the clear colour. So a bare `.env` gets a real background, and
|
|
9150
|
+
* the component's default `skybox.enabled: true` agrees with it.
|
|
9151
|
+
*
|
|
9035
9152
|
* ## `ambientColor` does not exist
|
|
9036
9153
|
*
|
|
9037
9154
|
* §2.5 lists an `ambientColor` field. Babylon Lite 1.27.0 has no scene-level ambient term:
|
|
@@ -9059,17 +9176,32 @@ const FOG_MODE_NAMES = [
|
|
|
9059
9176
|
"exp2"
|
|
9060
9177
|
];
|
|
9061
9178
|
/**
|
|
9179
|
+
* Whether a background is drawn, when nothing says otherwise. It matches the `.environment.json`
|
|
9180
|
+
* default (`skyboxEnabled`), which is what makes the ordinary case agree with itself.
|
|
9181
|
+
*/
|
|
9182
|
+
const SKYBOX_ENABLED_DEFAULT = true;
|
|
9183
|
+
/** The background cube's default size in metres. It matches the file format's `skyboxSize`. */
|
|
9184
|
+
const SKYBOX_SIZE_DEFAULT = 20;
|
|
9185
|
+
/**
|
|
9062
9186
|
* The world's lighting environment (`docs/architecture/07-rendering.md` §2.5).
|
|
9063
9187
|
*
|
|
9064
9188
|
* @example
|
|
9065
9189
|
* ```ts
|
|
9066
9190
|
* const studio = await app.assets.loadAsync<EnvironmentAsset>("environments/studio.env");
|
|
9067
|
-
* world.createEntity("Environment").addComponent(Environment, {
|
|
9191
|
+
* const env = world.createEntity("Environment").addComponent(Environment, {
|
|
9068
9192
|
* environment: studio.retain(),
|
|
9069
9193
|
* imageProcessing: { exposure: 1.2, contrast: 1, toneMapping: "aces" },
|
|
9070
9194
|
* });
|
|
9071
9195
|
* ```
|
|
9072
9196
|
*
|
|
9197
|
+
* @example
|
|
9198
|
+
* Switching environments at runtime. Both handles stay retained, so switching back costs nothing.
|
|
9199
|
+
*
|
|
9200
|
+
* ```ts
|
|
9201
|
+
* const night = await app.assets.loadAsync<EnvironmentAsset>("environments/night.env");
|
|
9202
|
+
* env.environment = night.retain();
|
|
9203
|
+
* ```
|
|
9204
|
+
*
|
|
9073
9205
|
* @public
|
|
9074
9206
|
*/
|
|
9075
9207
|
var Environment = class Environment extends Component {
|
|
@@ -9090,18 +9222,27 @@ var Environment = class Environment extends Component {
|
|
|
9090
9222
|
#appliedClearColor = "";
|
|
9091
9223
|
#appliedImageProcessing = "";
|
|
9092
9224
|
#imageProcessingInFlight = false;
|
|
9093
|
-
#
|
|
9225
|
+
#trackedEnvironment = null;
|
|
9226
|
+
#installedEnvironment = null;
|
|
9227
|
+
#hasWarnedAboutSkybox = false;
|
|
9094
9228
|
/**
|
|
9095
|
-
* The environment asset this component installed
|
|
9229
|
+
* The environment asset this component installed on the scene.
|
|
9096
9230
|
*
|
|
9097
|
-
* @
|
|
9231
|
+
* @remarks
|
|
9232
|
+
* It stops at the **last installed** asset, which is what the scene is actually lit by: setting
|
|
9233
|
+
* `environment` back to `null` does not un-light the scene, because Lite has no inverse of
|
|
9234
|
+
* `loadEnvironment` (see the module remarks). Headless it names the asset too — what a headless
|
|
9235
|
+
* app skips is the cube map, not the bookkeeping.
|
|
9236
|
+
*
|
|
9237
|
+
* @returns The asset, or `null` when this component has never installed one.
|
|
9098
9238
|
*/
|
|
9099
9239
|
get installed() {
|
|
9100
|
-
return this.#
|
|
9240
|
+
return this.#installedEnvironment;
|
|
9101
9241
|
}
|
|
9102
9242
|
/** Records that the component exists; the scene is written on the first sync. */
|
|
9103
9243
|
onAttach() {
|
|
9104
|
-
this.#
|
|
9244
|
+
this.#trackedEnvironment = null;
|
|
9245
|
+
this.#installedEnvironment = null;
|
|
9105
9246
|
}
|
|
9106
9247
|
/**
|
|
9107
9248
|
* Leaves the scene as it is.
|
|
@@ -9113,21 +9254,27 @@ var Environment = class Environment extends Component {
|
|
|
9113
9254
|
* implies. The `PreRender` system re-picks the winner on the next frame.
|
|
9114
9255
|
*/
|
|
9115
9256
|
onDetach() {
|
|
9116
|
-
this.#
|
|
9257
|
+
this.#trackedEnvironment = null;
|
|
9258
|
+
this.#installedEnvironment = null;
|
|
9117
9259
|
}
|
|
9118
9260
|
/**
|
|
9119
9261
|
* Writes every field that changed onto the scene. The `PreRender` system calls it for the winning
|
|
9120
9262
|
* environment only.
|
|
9121
9263
|
*
|
|
9122
9264
|
* @param renderer - The rendering service, for the scene and the headless flag.
|
|
9265
|
+
* @returns `true` when a different environment was installed on the scene this frame, which is a
|
|
9266
|
+
* topology change: the render-sync system owes the frame one `rebuildSceneRenderables` so that
|
|
9267
|
+
* every PBR material re-binds the new cube map.
|
|
9123
9268
|
*
|
|
9124
9269
|
* @internal
|
|
9125
9270
|
*/
|
|
9126
9271
|
sync(renderer) {
|
|
9127
9272
|
this.#applyClearColor(renderer);
|
|
9128
9273
|
this.#applyFog(renderer);
|
|
9129
|
-
this.#applyEnvironment(renderer);
|
|
9274
|
+
const installed = this.#applyEnvironment(renderer);
|
|
9275
|
+
this.#reportSkybox(renderer);
|
|
9130
9276
|
this.#applyImageProcessing(renderer);
|
|
9277
|
+
return installed;
|
|
9131
9278
|
}
|
|
9132
9279
|
/**
|
|
9133
9280
|
* Writes the clear colour, decoded to linear.
|
|
@@ -9158,23 +9305,74 @@ var Environment = class Environment extends Component {
|
|
|
9158
9305
|
setSceneFog(renderer.scene, toFogMode(fog.mode), Color.srgbToLinear(fog.color.r), Color.srgbToLinear(fog.color.g), Color.srgbToLinear(fog.color.b), fog.density, fog.start, fog.end);
|
|
9159
9306
|
}
|
|
9160
9307
|
/**
|
|
9161
|
-
*
|
|
9308
|
+
* Installs a newly assigned environment on the scene, then applies its rotation and blur.
|
|
9309
|
+
*
|
|
9310
|
+
* @remarks
|
|
9311
|
+
* Three things happen only when the field moves to a *different* loaded asset, which is what
|
|
9312
|
+
* keeps the "write only what changed" discipline of `07-rendering.md` §2.2: the scene is pointed
|
|
9313
|
+
* at the asset's recorded Lite handles, the rotation and the blur are invalidated so they are
|
|
9314
|
+
* written against the new cube map, and the image-processing key is cleared — Lite's
|
|
9315
|
+
* `loadEnvironment` overwrote `scene.imageProcessing` while that asset was loading, so the
|
|
9316
|
+
* component's own exposure, contrast and curve have to be written again.
|
|
9317
|
+
*
|
|
9318
|
+
* A move to `null` is deliberately *not* an uninstall (see the module remarks): the field stops
|
|
9319
|
+
* steering, and the scene stays lit by whatever was installed last.
|
|
9162
9320
|
*
|
|
9163
9321
|
* @param renderer - The rendering service, for the scene.
|
|
9322
|
+
* @returns `true` when the scene's environment slot moved this frame.
|
|
9164
9323
|
*/
|
|
9165
9324
|
#applyEnvironment(renderer) {
|
|
9166
9325
|
const loaded = this.environment?.state === "loaded" ? this.environment.value : null;
|
|
9167
|
-
|
|
9168
|
-
|
|
9169
|
-
this.#
|
|
9170
|
-
this.#
|
|
9326
|
+
let installed = false;
|
|
9327
|
+
if (loaded !== this.#trackedEnvironment) {
|
|
9328
|
+
this.#trackedEnvironment = loaded;
|
|
9329
|
+
if (loaded !== null && loaded !== this.#installedEnvironment) {
|
|
9330
|
+
this.#installedEnvironment = loaded;
|
|
9331
|
+
this.#appliedRotation = NaN;
|
|
9332
|
+
this.#appliedBlur = NaN;
|
|
9333
|
+
this.#appliedImageProcessing = "";
|
|
9334
|
+
this.#hasWarnedAboutSkybox = false;
|
|
9335
|
+
const textures = loaded.lite.textures;
|
|
9336
|
+
installed = textures !== null && installLoadedEnvironment(renderer.scene, textures);
|
|
9337
|
+
}
|
|
9171
9338
|
}
|
|
9172
|
-
if (
|
|
9339
|
+
if (this.#installedEnvironment === null || renderer.isHeadless) return installed;
|
|
9173
9340
|
if (this.#appliedRotation !== this.rotation || this.#appliedBlur !== this.blur) {
|
|
9174
9341
|
this.#appliedRotation = this.rotation;
|
|
9175
9342
|
this.#appliedBlur = this.blur;
|
|
9176
9343
|
applyEnvironmentOrientation(renderer.scene, this.rotation, this.blur);
|
|
9177
9344
|
}
|
|
9345
|
+
return installed;
|
|
9346
|
+
}
|
|
9347
|
+
/**
|
|
9348
|
+
* Says once, at warning level, that the `skybox` record asks for a background the installed
|
|
9349
|
+
* environment was not loaded with.
|
|
9350
|
+
*
|
|
9351
|
+
* @remarks
|
|
9352
|
+
* The field cannot be honoured here and this is not an oversight: Lite 1.27.0 builds the
|
|
9353
|
+
* background inside `loadEnvironment`, as a `Renderable` with no visibility flag, no size and no
|
|
9354
|
+
* handle, and offers nothing that removes or re-aims one (see the module remarks). So the record
|
|
9355
|
+
* is compared with what the installed asset's declaration actually delivered, and a disagreement
|
|
9356
|
+
* is reported rather than dropped.
|
|
9357
|
+
*
|
|
9358
|
+
* A field still sitting at its schema default is **not** a disagreement, whatever the declaration
|
|
9359
|
+
* says. Otherwise every project whose `.environment.json` turns the background off would be told
|
|
9360
|
+
* off for never having touched a component field, which is the opposite of actionable. The
|
|
9361
|
+
* warning therefore means "you asked for something and did not get it", never "these two numbers
|
|
9362
|
+
* differ".
|
|
9363
|
+
*
|
|
9364
|
+
* @param renderer - The rendering service, for the log sink.
|
|
9365
|
+
*/
|
|
9366
|
+
#reportSkybox(renderer) {
|
|
9367
|
+
const installed = this.#installedEnvironment;
|
|
9368
|
+
if (installed === null || this.#hasWarnedAboutSkybox) return;
|
|
9369
|
+
const definition = installed.definition;
|
|
9370
|
+
const skybox = this.skybox;
|
|
9371
|
+
const askedForEnabled = skybox.enabled !== SKYBOX_ENABLED_DEFAULT && skybox.enabled !== definition.skyboxEnabled;
|
|
9372
|
+
const askedForSize = skybox.size !== SKYBOX_SIZE_DEFAULT && skybox.size !== definition.skyboxSize;
|
|
9373
|
+
if (!askedForEnabled && !askedForSize) return;
|
|
9374
|
+
this.#hasWarnedAboutSkybox = true;
|
|
9375
|
+
renderer.app.log.warn(`${CoreErrorCode.skyboxFixedAtLoad}: {entity} asks for skybox {requested}, but {asset} was loaded with {loaded} and Babylon Lite builds the background when the environment loads, with no handle to change it afterwards. Declare skyboxEnabled and skyboxSize in the .environment.json instead.`, this.entity.name, `{ enabled: ${String(skybox.enabled)}, size: ${String(skybox.size)} }`, installed.address, `{ enabled: ${String(definition.skyboxEnabled)}, size: ${String(definition.skyboxSize)} }`);
|
|
9178
9376
|
}
|
|
9179
9377
|
/**
|
|
9180
9378
|
* Fires the asynchronous image-processing update, at most one at a time.
|
|
@@ -9243,12 +9441,12 @@ function environmentSchema() {
|
|
|
9243
9441
|
tooltip: "How blurred the specular reflection is."
|
|
9244
9442
|
}),
|
|
9245
9443
|
skybox: record({
|
|
9246
|
-
enabled: bool(
|
|
9247
|
-
size: f32(
|
|
9444
|
+
enabled: bool(SKYBOX_ENABLED_DEFAULT, { tooltip: "Whether a skybox is drawn; set it in the .environment.json." }),
|
|
9445
|
+
size: f32(SKYBOX_SIZE_DEFAULT, {
|
|
9248
9446
|
min: .001,
|
|
9249
|
-
tooltip: "The skybox cube's size
|
|
9447
|
+
tooltip: "The skybox cube's size in metres; set it in the .environment.json."
|
|
9250
9448
|
})
|
|
9251
|
-
}, { tooltip: "The background the environment
|
|
9449
|
+
}, { tooltip: "The background, as the installed .environment.json declared it. Read-only in practice." }),
|
|
9252
9450
|
fog: record({
|
|
9253
9451
|
mode: enumOf(FOG_MODE_NAMES, "none", { tooltip: "Fog falloff, or none." }),
|
|
9254
9452
|
color: color("#c8c8c8", { tooltip: "The fog's sRGB colour." }),
|
|
@@ -11801,6 +11999,8 @@ var RendererImpl = class {
|
|
|
11801
11999
|
/** How many times the sync system has rebuilt the scene's renderables; a diagnostics counter. */
|
|
11802
12000
|
renderableRebuilds = 0;
|
|
11803
12001
|
#app;
|
|
12002
|
+
/** Probes registered by {@link RendererImpl.addCameraSource}, in registration order. */
|
|
12003
|
+
#cameraSources = [];
|
|
11804
12004
|
#features;
|
|
11805
12005
|
#counters;
|
|
11806
12006
|
#countersDrawCalls;
|
|
@@ -12083,6 +12283,36 @@ var RendererImpl = class {
|
|
|
12083
12283
|
this.#features[feature] = true;
|
|
12084
12284
|
}
|
|
12085
12285
|
/**
|
|
12286
|
+
* Registers a probe that answers whether another rendering context has a camera of its own.
|
|
12287
|
+
*
|
|
12288
|
+
* @param probe - Answers `true` while the caller has an active camera for the world.
|
|
12289
|
+
* @returns A function that removes the probe.
|
|
12290
|
+
*/
|
|
12291
|
+
addCameraSource(probe) {
|
|
12292
|
+
this.#cameraSources.push(probe);
|
|
12293
|
+
return () => {
|
|
12294
|
+
const index = this.#cameraSources.indexOf(probe);
|
|
12295
|
+
if (index >= 0) this.#cameraSources.splice(index, 1);
|
|
12296
|
+
};
|
|
12297
|
+
}
|
|
12298
|
+
/**
|
|
12299
|
+
* Whether any registered probe claims a camera for this world.
|
|
12300
|
+
*
|
|
12301
|
+
* @remarks
|
|
12302
|
+
* Asked by the render sync system only in a frame where no enabled `Camera` was found, which is
|
|
12303
|
+
* what keeps `IGX-0706` off a correct 2D-only scene without costing a well-formed 3D scene
|
|
12304
|
+
* anything (`docs/architecture/07-rendering.md` §2.1).
|
|
12305
|
+
*
|
|
12306
|
+
* @param world - The world being reconciled.
|
|
12307
|
+
* @returns `true` when something other than the render scene draws it.
|
|
12308
|
+
*
|
|
12309
|
+
* @internal
|
|
12310
|
+
*/
|
|
12311
|
+
hasExternalCamera(world) {
|
|
12312
|
+
for (let index = 0; index < this.#cameraSources.length; index += 1) if (this.#cameraSources[index]?.(world) === true) return true;
|
|
12313
|
+
return false;
|
|
12314
|
+
}
|
|
12315
|
+
/**
|
|
12086
12316
|
* The material a `MeshRenderer` draws with when it declares none
|
|
12087
12317
|
* (`docs/architecture/07-rendering.md` §2.3): a neutral, fully rough dielectric.
|
|
12088
12318
|
*
|
|
@@ -12799,6 +13029,14 @@ function lightSchema() {
|
|
|
12799
13029
|
* file (`docs/architecture/05-assets-and-loading.md` §5,
|
|
12800
13030
|
* `06-serialization-and-scene-format.md` §6).
|
|
12801
13031
|
*
|
|
13032
|
+
* ## The skybox is decided here, once
|
|
13033
|
+
*
|
|
13034
|
+
* Lite builds the background inside `loadEnvironment` and hands back no handle on it, so this is
|
|
13035
|
+
* the only place that can decide whether there is one: `Environment.skybox` can report a
|
|
13036
|
+
* disagreement (`IGX-0711`) but cannot change it. `skyboxEnabled: false` skips the background;
|
|
13037
|
+
* otherwise the declaration's `skybox` image is used, and when it names none the environment draws
|
|
13038
|
+
* **its own** prefiltered cube map (see {@link toLoadOptions}).
|
|
13039
|
+
*
|
|
12802
13040
|
* ## Two addresses, one asset type
|
|
12803
13041
|
*
|
|
12804
13042
|
* A bare `.env` address is the common case: load this IBL, take the BRDF table and the skybox from
|
|
@@ -12921,8 +13159,10 @@ function toLoadOptions(ctx, definition, brdfUrl) {
|
|
|
12921
13159
|
skipGround: true
|
|
12922
13160
|
};
|
|
12923
13161
|
if (!definition.skyboxEnabled) options.skipSkybox = true;
|
|
12924
|
-
else if (definition.skybox === "")
|
|
12925
|
-
|
|
13162
|
+
else if (definition.skybox === "") {
|
|
13163
|
+
options.skyboxUrl = options.url;
|
|
13164
|
+
options.skyboxSize = definition.skyboxSize;
|
|
13165
|
+
} else {
|
|
12926
13166
|
options.skyboxUrl = ctx.app.assets.resolveUrl(definition.skybox);
|
|
12927
13167
|
options.skyboxSize = definition.skyboxSize;
|
|
12928
13168
|
}
|
|
@@ -16007,7 +16247,7 @@ var RenderSyncSystem = class {
|
|
|
16007
16247
|
castersChanged = changed || castersChanged;
|
|
16008
16248
|
}
|
|
16009
16249
|
this.#selectCamera(world, cameras);
|
|
16010
|
-
this.#applyEnvironment(world);
|
|
16250
|
+
topologyChanged = this.#applyEnvironment(world) || topologyChanged;
|
|
16011
16251
|
this.#applyStacks(world);
|
|
16012
16252
|
this.#areCastersDirty = this.#areCastersDirty || castersChanged;
|
|
16013
16253
|
if (this.#isRebuildDue && !topologyChanged) {
|
|
@@ -16049,10 +16289,20 @@ var RenderSyncSystem = class {
|
|
|
16049
16289
|
/**
|
|
16050
16290
|
* Says once, at warning level, that the world renders nothing because no camera is enabled.
|
|
16051
16291
|
*
|
|
16292
|
+
* @remarks
|
|
16293
|
+
* Silent when another rendering context claims the frame through a camera of its own — a
|
|
16294
|
+
* `"sprite"`-mode `@ignifx/2d` world with a `Camera2D` and no 3D `Camera` is a correct scene, and
|
|
16295
|
+
* `Renderer.addCameraSource` is how it says so. The claim is re-asked every frame rather than
|
|
16296
|
+
* latched, so a world that later loses its `Camera2D` still gets the warning.
|
|
16297
|
+
*
|
|
16052
16298
|
* @param world - The world being reconciled.
|
|
16053
16299
|
*/
|
|
16054
16300
|
#warnAboutMissingCamera(world) {
|
|
16055
16301
|
const renderer = this.#renderer;
|
|
16302
|
+
if (renderer.hasExternalCamera(world)) {
|
|
16303
|
+
renderer.hasLoggedNoCamera = false;
|
|
16304
|
+
return;
|
|
16305
|
+
}
|
|
16056
16306
|
if (renderer.hasLoggedNoCamera) return;
|
|
16057
16307
|
renderer.hasLoggedNoCamera = true;
|
|
16058
16308
|
world.app.log.warn("IGX-0706: this world has no enabled camera, so nothing is drawn.");
|
|
@@ -16061,6 +16311,7 @@ var RenderSyncSystem = class {
|
|
|
16061
16311
|
* Applies the winning `Environment`, warning once when a world has more than one enabled.
|
|
16062
16312
|
*
|
|
16063
16313
|
* @param world - The world being reconciled.
|
|
16314
|
+
* @returns `true` when the winner installed a different environment on the scene this frame.
|
|
16064
16315
|
*/
|
|
16065
16316
|
#applyEnvironment(world) {
|
|
16066
16317
|
const environments = world.components(Environment);
|
|
@@ -16077,7 +16328,7 @@ var RenderSyncSystem = class {
|
|
|
16077
16328
|
world.app.log.warn("IGX-0705: {count} Environment components are enabled in this world; the most recent one wins.", enabledCount);
|
|
16078
16329
|
}
|
|
16079
16330
|
if (enabledCount <= 1) this.#hasLoggedMultipleEnvironments = false;
|
|
16080
|
-
winner?.sync(this.#renderer);
|
|
16331
|
+
return winner?.sync(this.#renderer) ?? false;
|
|
16081
16332
|
}
|
|
16082
16333
|
/**
|
|
16083
16334
|
* Reconciles every post-process stack.
|
|
@@ -32752,7 +33003,7 @@ function describeEnvironmentFileFormat() {
|
|
|
32752
33003
|
skybox: {
|
|
32753
33004
|
kind: "str",
|
|
32754
33005
|
default: "",
|
|
32755
|
-
description: "A .dds or .env skybox address; empty
|
|
33006
|
+
description: "A .dds or .env skybox address; empty draws this environment's own cube map."
|
|
32756
33007
|
},
|
|
32757
33008
|
skyboxSize: {
|
|
32758
33009
|
kind: "f32",
|
|
@@ -32762,7 +33013,7 @@ function describeEnvironmentFileFormat() {
|
|
|
32762
33013
|
skyboxEnabled: {
|
|
32763
33014
|
kind: "bool",
|
|
32764
33015
|
default: true,
|
|
32765
|
-
description: "Whether a skybox is drawn at all."
|
|
33016
|
+
description: "Whether a skybox is drawn at all; decided here, not on the component."
|
|
32766
33017
|
},
|
|
32767
33018
|
blur: {
|
|
32768
33019
|
kind: "f32",
|