@plasius/gpu-lighting 0.1.19 → 0.2.2

package/CHANGELOG.md

@@ -20,6 +20,50 @@ The format is based on **[Keep a Changelog](https://keepachangelog.com/en/1.1.0/
 - **Security**
   - (placeholder)
 
+## [0.2.2] - 2026-06-11
+
+- **Added**
+  - Added `environmentMap`/`hdri` passthrough in wavefront lighting options so
+    renderers can use HDRI/equirectangular radiance textures as environment
+    light sources instead of relying primarily on static ambient colours.
+  - Added `sunlitBaseline` to environment lighting presets and wavefront
+    lighting options so renderers can apply a time-of-day daylight floor at
+    terminal path collisions without raising ambient residual colour.
+  - (placeholder)
+
+- **Changed**
+  - Reduced ambient residual strength for the grass-field, forest, warehouse,
+    and cavern environment preset families to avoid low-sample whitewash.
+
+- **Fixed**
+  - (placeholder)
+
+- **Security**
+  - (placeholder)
+
+## [0.2.0] - 2026-06-06
+
+- **Added**
+  - Added environment-light portal contracts to the reusable environment
+    lighting config so renderers can guide and gate sky/HDRI contribution
+    through room openings such as windows.
+  - Added grass-field, forest, warehouse, and cavern environment lighting
+    preset families with dawn, midday, dusk, and night variants plus normalized
+    light-source metadata for environment-miss inference.
+  - Added scene/time-of-day preset aliases so callers can request environments
+    with `scene` plus `timeOfDay` instead of only combined preset names.
+
+- **Changed**
+  - Pathtracer environment misses now resolve through non-null inferred
+    environment radiance, and emissive material hits contribute once before
+    terminating the active sample path.
+
+- **Fixed**
+  - (placeholder)
+
+- **Security**
+  - (placeholder)
+
 ## [0.1.19] - 2026-06-03
 
 - **Added**
@@ -331,3 +375,6 @@ The format is based on **[Keep a Changelog](https://keepachangelog.com/en/1.1.0/
 [0.1.16]: https://github.com/Plasius-LTD/gpu-lighting/releases/tag/v0.1.16
 [0.1.17]: https://github.com/Plasius-LTD/gpu-lighting/releases/tag/v0.1.17
 [0.1.19]: https://github.com/Plasius-LTD/gpu-lighting/releases/tag/v0.1.19
+[Unreleased]: https://github.com/Plasius-LTD/gpu-lighting/compare/v0.2.2...HEAD
+[0.2.0]: https://github.com/Plasius-LTD/gpu-lighting/releases/tag/v0.2.0
+[0.2.2]: https://github.com/Plasius-LTD/gpu-lighting/releases/tag/v0.2.2

package/README.md

@@ -114,18 +114,67 @@ import {
 } from "@plasius/gpu-lighting";
 
 const lighting = createEnvironmentLightingConfig({
-  preset: "product-studio",
+  scene: "forest",
+  timeOfDay: "dusk",
   intensity: 1.05,
+  environmentPortals: [
+    {
+      id: "north-window",
+      position: [0, 1.2, -2.4],
+      normal: [0, 0, 1],
+      tangent: [1, 0, 0],
+      width: 1.8,
+      height: 1.1,
+      intensity: 1.4,
+    },
+  ],
 });
 
 const wavefrontLighting = createWavefrontEnvironmentLightingOptions({
-  preset: "moonlit-harbor",
+  preset: "cavern-night",
 });
+
+console.log(lighting.environmentLightSources.map((source) => source.kind));
+console.log(wavefrontLighting.environmentMissLighting.startingPoint);
 ```
 
 `createEnvironmentLightingConfig(...)` owns the reusable sky/environment
 semantics: horizon and zenith colours, key-light direction, key-light colour,
-environment intensity, exposure, and ambient residual colour.
+environment intensity, exposure, ambient residual colour, and optional
+environment-light portals. The grass-field, forest, warehouse, and cavern
+families use restrained ambient residual scaling so low-sample renderers keep
+some final-bounce colour without washing dark materials toward white. They also
+publish `sunlitBaseline`, a scene-scaled time-of-day daylight floor that
+renderers can use at terminal path collisions without raising the global
+ambient colour.
+
+Preset families now cover:
+
+- `grass-field-{dawn,midday,dusk,night}`
+- `forest-{dawn,midday,dusk,night}`
+- `warehouse-{dawn,midday,dusk,night}`
+- `cavern-{dawn,midday,dusk,night}`
+
+Callers can pass the combined `preset` name directly or pass `scene` plus
+`timeOfDay`; scene-only aliases default to `midday`.
+
+Each preset publishes `scene`, `timeOfDay`, normalized
+`sunlitBaseline`, `environmentLightSources`, a `dominantLightSource`, and
+`environmentMissLighting`. Source metadata includes source kind, role, direction,
+position, colour, intensity, radiance, luminance, reach, and angular radius.
+Renderers can use `environmentMissLighting` when a path ray misses scene
+geometry: the miss has an inferred source colour/brightness and a stable
+`startingPoint` of `environment-miss` instead of an unbounded null/negative sky
+sample. Emissive material hits remain explicit light-source hits and should not
+be double-counted by environment inference. Callers can also pass an
+`environmentMap`/`hdri` descriptor; the lighting config preserves it in
+`createWavefrontEnvironmentLightingOptions(...)` so the wavefront renderer can
+sample an equirectangular radiance map for environment misses and ambient
+residuals instead of relying primarily on static ambient values.
+
+Portals describe physical openings such as windows where outside radiance can
+enter an interior. They are normalized as rectangle apertures with position,
+normal, tangent, dimensions, colour, and radiance scale.
 `createWavefrontEnvironmentLightingOptions(...)` projects that contract into the
 current `@plasius/gpu-renderer` wavefront renderer options without making the
 renderer depend on this package directly.