@absolutejs/rendering 0.5.0 → 0.6.0

package/README.md

@@ -137,9 +137,24 @@ scene-dependent; the qualification uses software rendering, not a hardware FPS c
 `createThinFoliageMaterial({ leafTransmission: 0.35 })` creates a standard
 material with approximate thin-leaf backlighting. Transmission is a bounded
 fraction (0–1) of direct diffuse; zero retains standard lighting. The shader
-uses Three's shadowed incident light, preserving PBR specular, indirect lighting,
-fog and tone mapping. Area lights retain standard lighting. This is a lightweight
+uses Three's shadowed incident light, preserving PBR specular,
+fog and tone mapping. Area lights retain standard lighting; hemisphere lights and PMREM diffuse illumination transmit from the reverse side. This is a lightweight
 leaf approximation, not volumetric subsurface scattering or a complete grass
 renderer. Distribution, blade shape, wind and terrain integration remain the
 caller's responsibility. Compose custom shader hooks after the factory hook;
 use `cloneRenderMaterial` to preserve them when cloning.
+
+
+`withLeafLighting(fragmentShader, transmission)` and
+`withLeafTransmissionField(fragmentShader, identifier)` apply the same canonical
+thin-sheet model to an existing standard-material shader. The field form expects
+a declared scalar clamped to [0,1]. These helpers preserve the existing Three
+specular paths, including environment multiple-scattering compensation. Compose
+vertex deformation independently and include transmission policy in cache keys.
+An environment-lit leaf uses an additional reverse-normal irradiance lookup;
+this is not a free shader operation. No extra passes or geometry are added.
+
+Version 0.6 replaces the factory's view-dependent direct-scattering factor with
+the same thin-sheet diffuse weighting used by the lower-level hooks. Existing
+material colour/transmission settings remain valid, but direct backlighting can
+change. This release also adds sky transmission missing from 0.5.

package/dist/index.d.ts

@@ -14,5 +14,6 @@ export declare function cloneRenderMaterial<T extends Material>(source: T): T;
 export { renderTargetScope, readTargetPixelsScoped, readFloatTargetScoped, } from "./renderTargetScope.js";
 export { createObjectTriplanarMaterial } from "./objectTriplanar.js";
 export type { ObjectTriplanarProjection, ObjectTriplanarMaterialParameters, } from "./objectTriplanar.js";
-export { createThinFoliageMaterial } from './thinFoliage.js';
-export type { ThinFoliageMaterialParameters } from './thinFoliage.js';
+export { createThinFoliageMaterial } from "./thinFoliage.js";
+export type { ThinFoliageMaterialParameters } from "./thinFoliage.js";
+export { withLeafLighting, withLeafTransmissionField, leafLightingGLSL, } from "./leafLighting.js";

package/dist/index.js

@@ -77,4 +77,5 @@ export function cloneRenderMaterial(source) {
 }
 export { renderTargetScope, readTargetPixelsScoped, readFloatTargetScoped, } from "./renderTargetScope.js";
 export { createObjectTriplanarMaterial } from "./objectTriplanar.js";
-export { createThinFoliageMaterial } from './thinFoliage.js';
+export { createThinFoliageMaterial } from "./thinFoliage.js";
+export { withLeafLighting, withLeafTransmissionField, leafLightingGLSL, } from "./leafLighting.js";

package/dist/leafLighting.d.ts

@@ -0,0 +1,7 @@
+/** Bounded thin-sheet diffuse approximation. Thickness values are art calibration,
+ * not measured transmittance; direct-light color already includes Three's shadows. */
+export declare const leafLightingGLSL = "\nvec2 leafDiffuseWeights(float cosine, float transmission) {\n float t=clamp(transmission,0.,1.);\n return vec2(max(0.,cosine)*(1.-t),max(0.,-cosine)*t);\n}\nvoid RE_Direct_Leaf(const in IncidentLight light, const in vec3 position,\n const in vec3 normal, const in vec3 viewDirection, const in vec3 clearcoatNormal,\n const in PhysicalMaterial material, inout ReflectedLight reflectedLight) {\n vec3 previous=reflectedLight.directDiffuse;\n RE_Direct_Physical(light,position,normal,viewDirection,clearcoatNormal,material,reflectedLight);\n vec2 weights=leafDiffuseWeights(dot(normal,light.direction),LEAF_TRANSMISSION);\n reflectedLight.directDiffuse=previous+(reflectedLight.directDiffuse-previous)*(1.-LEAF_TRANSMISSION)\n  +light.color*material.diffuseColor*(RECIPROCAL_PI*weights.y);\n}\n#if NUM_HEMI_LIGHTS > 0\nvec3 getLeafHemisphereLightIrradiance(const in HemisphereLight light, const in vec3 normal) {\n return mix(getHemisphereLightIrradiance(light,normal),getHemisphereLightIrradiance(light,-normal),LEAF_TRANSMISSION);\n}\n#define getHemisphereLightIrradiance getLeafHemisphereLightIrradiance\n#endif\n#undef RE_Direct\n#define RE_Direct RE_Direct_Leaf\n";
+export declare function withLeafLighting(shader: string, transmission: number): string;
+/** Per-fragment transmission must already be clamped to [0,1] by its material.
+ * Accept a single declared identifier, never arbitrary injected shader text. */
+export declare function withLeafTransmissionField(shader: string, identifier: string): string;

package/dist/leafLighting.js

@@ -0,0 +1,64 @@
+import { ShaderChunk } from "three";
+/** Bounded thin-sheet diffuse approximation. Thickness values are art calibration,
+ * not measured transmittance; direct-light color already includes Three's shadows. */
+export const leafLightingGLSL = /* glsl */ `
+vec2 leafDiffuseWeights(float cosine, float transmission) {
+ float t=clamp(transmission,0.,1.);
+ return vec2(max(0.,cosine)*(1.-t),max(0.,-cosine)*t);
+}
+void RE_Direct_Leaf(const in IncidentLight light, const in vec3 position,
+ const in vec3 normal, const in vec3 viewDirection, const in vec3 clearcoatNormal,
+ const in PhysicalMaterial material, inout ReflectedLight reflectedLight) {
+ vec3 previous=reflectedLight.directDiffuse;
+ RE_Direct_Physical(light,position,normal,viewDirection,clearcoatNormal,material,reflectedLight);
+ vec2 weights=leafDiffuseWeights(dot(normal,light.direction),LEAF_TRANSMISSION);
+ reflectedLight.directDiffuse=previous+(reflectedLight.directDiffuse-previous)*(1.-LEAF_TRANSMISSION)
+  +light.color*material.diffuseColor*(RECIPROCAL_PI*weights.y);
+}
+#if NUM_HEMI_LIGHTS > 0
+vec3 getLeafHemisphereLightIrradiance(const in HemisphereLight light, const in vec3 normal) {
+ return mix(getHemisphereLightIrradiance(light,normal),getHemisphereLightIrradiance(light,-normal),LEAF_TRANSMISSION);
+}
+#define getHemisphereLightIrradiance getLeafHemisphereLightIrradiance
+#endif
+#undef RE_Direct
+#define RE_Direct RE_Direct_Leaf
+`;
+export function withLeafLighting(shader, transmission) {
+    if (!Number.isFinite(transmission) || transmission < 0 || transmission > 1)
+        throw Error("Leaf transmission must be in [0,1]");
+    return withLeafExpression(shader, transmission.toFixed(4));
+}
+/** Per-fragment transmission must already be clamped to [0,1] by its material.
+ * Accept a single declared identifier, never arbitrary injected shader text. */
+export function withLeafTransmissionField(shader, identifier) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(identifier) ||
+        identifier.startsWith("gl_"))
+        throw Error("Invalid leaf transmission field identifier");
+    return withLeafExpression(shader, identifier);
+}
+function withLeafExpression(shader, expression) {
+    const marker = "#include <lights_physical_pars_fragment>";
+    if (shader.split(marker).length !== 2)
+        throw Error("Three physical lighting hook missing");
+    // Three r186 shares irradiance with multiple-scattering specular compensation.
+    // Patch only its diffuse accumulation; changing getIBLIrradiance globally
+    // would also transmit a portion of the specular response through the leaf.
+    const diffuse = "vec3 indirectDiffuse = diffuse * cosineWeightedIrradiance;";
+    const physical = ShaderChunk.lights_physical_pars_fragment;
+    if (physical.split(diffuse).length !== 2)
+        throw Error("Three indirect diffuse hook missing");
+    return shader.replace(marker, "\n#define LEAF_TRANSMISSION " +
+        expression +
+        "\n" +
+        physical.replace(diffuse, `
+#ifdef USE_ENVMAP
+vec3 leafIrradiance = mix(irradiance, getIBLIrradiance(-geometryNormal), LEAF_TRANSMISSION);
+vec3 indirectDiffuse = diffuse * leafIrradiance * RECIPROCAL_PI;
+#else
+${diffuse}
+#endif
+`) +
+        "\n" +
+        leafLightingGLSL);
+}

package/dist/thinFoliage.d.ts

@@ -1,11 +1,11 @@
-import { MeshStandardMaterial, type MeshStandardMaterialParameters } from 'three';
+import { MeshStandardMaterial, type MeshStandardMaterialParameters } from "three";
 export type ThinFoliageMaterialParameters = MeshStandardMaterialParameters & {
-    /** Fraction of direct diffuse allocated to approximate leaf transmission, 0..1. */
+    /** Fraction of diffuse illumination allocated to approximate leaf transmission, 0..1. */
     leafTransmission?: number;
 };
-/** Approximate thin-leaf backlighting using Three's already shadowed direct light.
+/** Approximate thin-leaf backlighting using Three's shadowed direct and directional sky light.
  * Not volumetric transmission. No extra render pass, texture, or animation loop.
- * Area-light and environment paths retain standard shading. Use
+ * Sky diffuse is transmitted; specular and area lights retain standard shading. Use
  * cloneRenderMaterial to preserve shader hooks when cloning.
  */
 export declare function createThinFoliageMaterial(options?: ThinFoliageMaterialParameters): MeshStandardMaterial;

package/dist/thinFoliage.js

@@ -1,34 +1,27 @@
-import { DoubleSide, MeshStandardMaterial } from 'three';
-/** Approximate thin-leaf backlighting using Three's already shadowed direct light.
+import { withLeafTransmissionField } from "./leafLighting.js";
+import { DoubleSide, MeshStandardMaterial, } from "three";
+/** Approximate thin-leaf backlighting using Three's shadowed direct and directional sky light.
  * Not volumetric transmission. No extra render pass, texture, or animation loop.
- * Area-light and environment paths retain standard shading. Use
+ * Sky diffuse is transmitted; specular and area lights retain standard shading. Use
  * cloneRenderMaterial to preserve shader hooks when cloning.
  */
 export function createThinFoliageMaterial(options = {}) {
     const { leafTransmission = 0.35, ...parameters } = options;
-    if (!Number.isFinite(leafTransmission) || leafTransmission < 0 || leafTransmission > 1)
-        throw Error('Invalid leaf transmission');
-    const material = new MeshStandardMaterial({ side: DoubleSide, roughness: 0.85, ...parameters });
-    material.onBeforeCompile = shader => {
-        const anchor = '#include <lights_physical_pars_fragment>';
-        if (shader.fragmentShader.split(anchor).length !== 2)
-            throw Error('Unsupported thin-foliage shader');
+    if (!Number.isFinite(leafTransmission) ||
+        leafTransmission < 0 ||
+        leafTransmission > 1)
+        throw Error("Invalid leaf transmission");
+    const material = new MeshStandardMaterial({
+        side: DoubleSide,
+        roughness: 0.85,
+        ...parameters,
+    });
+    material.onBeforeCompile = (shader) => {
         shader.uniforms.absLeafTransmission = { value: leafTransmission };
-        shader.fragmentShader = shader.fragmentShader.replace(anchor, `${anchor}
-uniform float absLeafTransmission;
-void absLeafDirect(const in IncidentLight light, const in vec3 p, const in vec3 n,
- const in vec3 v, const in vec3 coatN, const in PhysicalMaterial m, inout ReflectedLight result) {
- vec3 previousDiffuse=result.directDiffuse;
- RE_Direct_Physical(light,p,n,v,coatN,m,result);
- float through=max(0.,dot(-n,light.direction));
- float forward=max(0.,dot(v,-light.direction));
- vec3 transmitted=light.color*BRDF_Lambert(m.diffuseColor)*through*(.5+.5*forward*forward);
- result.directDiffuse=previousDiffuse+mix(result.directDiffuse-previousDiffuse,transmitted,absLeafTransmission);
-}
-#undef RE_Direct
-#define RE_Direct absLeafDirect
-`);
+        shader.fragmentShader =
+            "uniform float absLeafTransmission;\n" +
+                withLeafTransmissionField(shader.fragmentShader, "absLeafTransmission");
     };
-    material.customProgramCacheKey = () => `absolute-thin-foliage-1:${leafTransmission}`;
+    material.customProgramCacheKey = () => `absolute-thin-foliage-2:${leafTransmission}`;
     return material;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@absolutejs/rendering",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Three.js material ownership, destination coverage, rigid-object triplanar mapping and isolated React Spring hosts.",
   "type": "module",
   "main": "./dist/index.js",
@@ -39,7 +39,8 @@
     "test:browser": "bun scripts/verify-browser.cjs",
     "test:spring:browser": "bun scripts/verify-spring.cjs",
     "test:triplanar:browser": "bun scripts/verify-triplanar.cjs",
-    "test:foliage:browser": "bun scripts/verify-foliage.cjs"
+    "test:foliage:browser": "bun scripts/verify-foliage.cjs",
+    "test:foliage:environment": "bun scripts/verify-foliage-environment.cjs"
   },
   "peerDependencies": {
     "three": ">=0.186.0 <0.187.0",