@plasius/gpu-lighting 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -20,6 +20,27 @@ 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**
@@ -354,5 +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.0...HEAD
+[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

@@ -141,7 +141,12 @@ 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, ambient residual colour, and optional
-environment-light portals.
+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:
 
@@ -154,14 +159,18 @@ 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
-`environmentLightSources`, a `dominantLightSource`, and
+`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.
+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,

package/dist/index.cjs

@@ -235,9 +235,37 @@ var lightingDistanceBands = Object.freeze([
 ]);
 var lightingWorkerQueueClass = "lighting";
 var lightingDebugOwner = "lighting";
+var environmentPresetAmbientScales = Object.freeze({
+  "grass-field": 0.78,
+  forest: 0.78,
+  warehouse: 0.82,
+  cavern: 0.78
+});
+var environmentSunlitBaselineByTimeOfDay = Object.freeze({
+  dawn: 0.18,
+  midday: 0.28,
+  dusk: 0.14,
+  night: 0.035
+});
+var environmentSunlitBaselineSceneScales = Object.freeze({
+  "grass-field": 1,
+  forest: 0.78,
+  warehouse: 0.62,
+  cavern: 0.42,
+  harbor: 0.85,
+  studio: 0.58
+});
 function freezeVec4(value) {
   return Object.freeze([value[0], value[1], value[2], value[3] ?? 1]);
 }
+function scaleVec4(value, scale) {
+  return [
+    value[0] * scale,
+    value[1] * scale,
+    value[2] * scale,
+    value[3] ?? 1
+  ];
+}
 function normalizeVector3(value, fallback) {
   if (!Array.isArray(value) || value.length < 3) {
     return [...fallback];
@@ -402,6 +430,22 @@ function normalizeEnvironmentPortals(value) {
   }
   return Object.freeze(value.map(normalizeEnvironmentPortal));
 }
+function normalizeEnvironmentMap(value) {
+  if (value == null) {
+    return null;
+  }
+  if (!value || typeof value !== "object") {
+    throw new Error("environmentMap must be an object when provided.");
+  }
+  return Object.freeze({
+    ...value,
+    id: typeof value.id === "string" && value.id.length > 0 ? value.id : "environment-map",
+    projection: typeof value.projection === "string" && value.projection.length > 0 ? value.projection : "equirectangular",
+    intensity: readPositiveFinite(value.intensity ?? value.radianceScale, 1),
+    rotationRadians: readFinite(value.rotationRadians ?? value.rotation, 0),
+    ambientStrength: Math.max(0, readFinite(value.ambientStrength, 0.32))
+  });
+}
 function freezeLightSourceSpec(source) {
   return Object.freeze({
     ...source,
@@ -411,15 +455,27 @@ function freezeLightSourceSpec(source) {
   });
 }
 function defineEnvironmentPreset(spec) {
+  const scene = spec.scene ?? "studio";
+  const timeOfDay = spec.timeOfDay ?? "midday";
+  const ambientScale = Math.max(
+    0,
+    readFinite(spec.ambientScale, environmentPresetAmbientScales[scene] ?? 1)
+  );
+  const defaultSunlitBaseline = (environmentSunlitBaselineByTimeOfDay[timeOfDay] ?? environmentSunlitBaselineByTimeOfDay.midday) * (environmentSunlitBaselineSceneScales[scene] ?? 0.58);
+  const sunlitBaseline = Math.max(
+    0,
+    readFinite(spec.sunlitBaseline, defaultSunlitBaseline)
+  );
   return Object.freeze({
     ...spec,
-    scene: spec.scene ?? "studio",
-    timeOfDay: spec.timeOfDay ?? "midday",
+    scene,
+    timeOfDay,
     horizonColor: freezeVec4(spec.horizonColor),
     zenithColor: freezeVec4(spec.zenithColor),
     sunDirection: Object.freeze(normalizeVector3(spec.sunDirection, [0, 1, 0])),
     sunColor: freezeVec4(spec.sunColor),
-    ambientColor: freezeVec4(spec.ambientColor),
+    ambientColor: freezeVec4(scaleVec4(spec.ambientColor, ambientScale)),
+    sunlitBaseline,
     environmentLightSources: Object.freeze(
       (spec.environmentLightSources ?? []).map(freezeLightSourceSpec)
     )
@@ -947,6 +1003,9 @@ function createEnvironmentLightingConfig(options = {}) {
   const environmentPortals = normalizeEnvironmentPortals(
     options.environmentPortals ?? options.portals
   );
+  const environmentMap = normalizeEnvironmentMap(
+    options.environmentMap ?? options.hdri ?? preset.environmentMap
+  );
   const environmentPortalMode = normalizeEnvironmentPortalMode(
     options.environmentPortalMode ?? options.portalMode,
     environmentPortals.length > 0
@@ -970,8 +1029,13 @@ function createEnvironmentLightingConfig(options = {}) {
     ),
     sunColor: readColor(options.sunColor, preset.sunColor),
     ambientColor: readColor(options.ambientColor, preset.ambientColor),
+    sunlitBaseline: Math.max(
+      0,
+      readFinite(options.sunlitBaseline ?? options.daylightBaseline, preset.sunlitBaseline)
+    ),
     environmentPortalMode,
-    environmentPortals
+    environmentPortals,
+    environmentMap
   };
   const environmentLightSources = normalizeEnvironmentLightSources(
     options.environmentLightSources ?? options.lightSources,
@@ -999,8 +1063,10 @@ function createEnvironmentLightingConfig(options = {}) {
     wavefront: Object.freeze({
       environmentColor,
       ambientColor: config.ambientColor,
+      sunlitBaseline: config.sunlitBaseline,
       environmentPortalMode: config.environmentPortalMode,
       environmentPortals: config.environmentPortals,
+      environmentMap: config.environmentMap,
       environmentLightSources: config.environmentLightSources,
       lightSources: config.environmentLightSources,
       dominantLightSource,
@@ -1013,8 +1079,10 @@ function createEnvironmentLightingConfig(options = {}) {
         intensity: config.environmentIntensity,
         mode: config.environmentMode,
         exposure: config.exposure,
+        sunlitBaseline: config.sunlitBaseline,
         environmentPortalMode: config.environmentPortalMode,
         environmentPortalCount: config.environmentPortals.length,
+        environmentMap: config.environmentMap,
         environmentLightSources: config.environmentLightSources,
         environmentLightSourceCount: config.environmentLightSources.length,
         dominantLightSource,
@@ -1028,8 +1096,10 @@ function createWavefrontEnvironmentLightingOptions(options = {}) {
   return Object.freeze({
     environmentColor: config.wavefront.environmentColor,
     ambientColor: config.wavefront.ambientColor,
+    sunlitBaseline: config.wavefront.sunlitBaseline,
     environmentPortalMode: config.wavefront.environmentPortalMode,
     environmentPortals: config.wavefront.environmentPortals,
+    environmentMap: config.wavefront.environmentMap,
     environmentLightSources: config.wavefront.environmentLightSources,
     lightSources: config.wavefront.environmentLightSources,
     dominantLightSource: config.wavefront.dominantLightSource,