@preference-sl/pref-viewer 2.17.0-beta.3 → 2.17.0-beta.4

package/README.md

@@ -88,8 +88,8 @@ viewer.setOptions({
     intensity: 1,
     shadows: true,
   },
-  lighting: {
-    timeOfDay: 0.5,
+  render: {
+    lightingTimeOfDay: 0.5,
   },
 });
 ```
@@ -501,6 +501,23 @@ Render settings are persisted in `localStorage` under the `pref-viewer/render-se
 
 The showroom daylight background uses a shared linear HDR color calibrated with exposure and ACES tone mapping for the current light studio gray target, `#d9d9d9`, in a scene-less view. Both the static look and time-of-day cycle use this same daylight value; the cycle retains its dark night endpoint. Scene geometry can cover the background. The internal `BabylonJSController.config.look.showroom.backgroundDay` value is not a public background-color option and must be recalibrated if tone mapping or exposure changes.
 
+## Environment map and scene lights
+
+`options.ibl.url` accepts two formats, chosen by the URL's extension (query and hash ignored):
+
+| Extension | Loaded as | Notes |
+| --- | --- | --- |
+| `.env` | Prefiltered Babylon environment (`CubeTexture.CreateFromPrefilteredData`) | No prefiltering in the browser; a 4K environment is typically under 1 MB. |
+| anything else | Radiance HDR (`HDRCubeTexture`) | Prefiltered on load, which costs time and memory for large files. |
+
+Either file is downloaded once, cached in IndexedDB, and reused across reloads.
+
+Directional and spot lights that come with the scene glTF (`KHR_lights_punctual`) cast shadows when `render.shadowsEnabled` is `true` and `ibl.shadows` is off, alongside the built-in light's. Every scene and model mesh casts unless its node sets `extras.castShadows: false`, and receives unless it sets `extras.receiveShadows: false`. A light's shadow darkness comes from its node's `extras.shadowDarkness`, from `0` (black) to `1` (no shadow), and is `0.5` when absent:
+
+```json
+{ "name": "Sun", "rotation": [-0.5, 0, 0, 0.866], "extras": { "shadowDarkness": 0.15 }, "extensions": { "KHR_lights_punctual": { "light": 0 } } }
+```
+
 ## Runtime styles
 
 Runtime styles can be passed through the `styles` attribute, the `styles` property setter, `setStyles(styles)`, or `loadConfig({ styles })`.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@preference-sl/pref-viewer",
-    "version": "2.17.0-beta.3",
+    "version": "2.17.0-beta.4",
     "description": "Web Component to preview GLTF models with Babylon.js",
     "author": "Alex Moreno Palacio <amoreno@preference.es>",
     "scripts": {

package/src/babylonjs-controller.js

@@ -1,4 +1,4 @@
-import { ArcRotateCamera, AssetContainer, BRDFTextureTools, Camera, Color3, Color4, DefaultRenderingPipeline, DirectionalLight, Engine, FreeCamera, HDRCubeTexture, HemisphericLight, IblShadowsRenderPipeline, ImageProcessingConfiguration, LoadAssetContainerAsync, Material, Matrix, MeshBuilder, PBRMaterial, PointerEventTypes, PointLight, RenderTargetTexture, Scene, ShadowGenerator, SpotLight, SSAORenderingPipeline, Texture, Tools, UniversalCamera, Vector3, WebXRDefaultExperience, WebXRFeatureName, WebXRSessionManager, WebXRState, WhenTextureReadyAsync } from "@babylonjs/core";
+import { ArcRotateCamera, AssetContainer, BRDFTextureTools, Camera, Color3, Color4, CubeTexture, DefaultRenderingPipeline, DirectionalLight, Engine, FreeCamera, HDRCubeTexture, HemisphericLight, IblShadowsRenderPipeline, ImageProcessingConfiguration, LoadAssetContainerAsync, Material, Matrix, MeshBuilder, PBRMaterial, PointerEventTypes, PointLight, RenderTargetTexture, Scene, ShadowGenerator, SpotLight, SSAORenderingPipeline, Texture, Tools, UniversalCamera, Vector3, WebXRDefaultExperience, WebXRFeatureName, WebXRSessionManager, WebXRState, WhenTextureReadyAsync } from "@babylonjs/core";
 import { DracoCompression } from "@babylonjs/core/Meshes/Compression/dracoCompression.js";
 import "@babylonjs/loaders";
 import "@babylonjs/loaders/glTF/2.0/Extensions/KHR_draco_mesh_compression.js";
@@ -1334,7 +1334,7 @@ export default class BabylonJSController {
      * @returns {Promise<boolean>} Returns true if the environment texture was changed, false if it was already up to date or failed to load.
      * @description
      * Lifecycle implemented here:
-     * 1. If `options.ibl.cachedUrl` exists, create `HDRCubeTexture` from it.
+     * 1. If `options.ibl.cachedUrl` exists, create `HDRCubeTexture` from it (a prefiltered `CubeTexture` when `options.ibl.url` is a `.env`).
      * 2. Wait for readiness, clone it into `#hdrTexture` for reuse.
      * 3. Call `options.ibl.consumeCachedUrl(true)` to revoke temporary object URLs and clear `cachedUrl`.
      * 4. On following reloads, if `options.ibl.valid === true` and no `cachedUrl` is present, use `#hdrTexture.clone()`.
@@ -1348,8 +1348,13 @@ export default class BabylonJSController {
         let hdrTexture = null;
         if (this.#options.ibl?.cachedUrl) {
             const hdrTextureURI = this.#options.ibl.cachedUrl;
-            const envTextureSize = BabylonJSController.config.quality.environmentTextureSize || 1024;
-            hdrTexture = new HDRCubeTexture(hdrTextureURI, this.#scene, envTextureSize, false, false, false, true, undefined, undefined, false, true, true);
+            if (/\.env$/i.test(String(this.#options.ibl.url ?? "").split(/[?#]/)[0])) {
+                // The cached file is a blob: URL with no extension, so the loader is told it is a .env.
+                hdrTexture = CubeTexture.CreateFromPrefilteredData(hdrTextureURI, this.#scene, ".env");
+            } else {
+                const envTextureSize = BabylonJSController.config.quality.environmentTextureSize || 1024;
+                hdrTexture = new HDRCubeTexture(hdrTextureURI, this.#scene, envTextureSize, false, false, false, true, undefined, undefined, false, true, true);
+            }
         } else if (this.#hdrTexture && this.#options.ibl?.valid === true) {
             hdrTexture = this.#hdrTexture.clone();
         } else {
@@ -1586,7 +1591,7 @@ export default class BabylonJSController {
             return generator.getLight()?.name === "PrefViewerDirLight";
         });
 
-        this.#containers.environment?.AssetContainer?.lights.forEach((light) => {
+        this.#containers.environment?.assetContainer?.lights.forEach((light) => {
             // Only shadows for DirectionalLight and SpotLight types
             if (!(light instanceof DirectionalLight || light instanceof SpotLight)) {
                 return;
@@ -1595,7 +1600,9 @@ export default class BabylonJSController {
             const shadowGenerator = new ShadowGenerator(1024, light);
             shadowGenerator.useBlurExponentialShadowMap = true;
             shadowGenerator.blurKernel = 16;
-            shadowGenerator.darkness = 0.5;
+            // KHR_lights_punctual parents the light to its glTF node, which carries the node's extras.
+            const extrasShadowDarkness = light.parent?.metadata?.gltf?.extras?.shadowDarkness;
+            shadowGenerator.darkness = typeof extrasShadowDarkness === "number" && Number.isFinite(extrasShadowDarkness) ? Math.min(Math.max(extrasShadowDarkness, 0), 1) : 0.5;
             shadowGenerator.bias = 0.0005;
             shadowGenerator.normalBias = 0.02;
             shadowGenerator.getShadowMap().refreshRate = RenderTargetTexture.REFRESHRATE_RENDER_ONCE;