@absolutejs/rendering 0.4.0 → 0.6.0

package/README.md

@@ -131,3 +131,30 @@ owned textures separately. Standard lighting, shadows and geometry stay intact.
 With color, normal and roughness present, the shader uses nine texture samples
 instead of three UV samples, with no extra draw or render pass. Hardware cost is
 scene-dependent; the qualification uses software rendering, not a hardware FPS claim.
+
+### Thin foliage
+
+`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,
+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,3 +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 { withLeafLighting, withLeafTransmissionField, leafLightingGLSL, } from "./leafLighting.js";

package/dist/index.js

@@ -77,3 +77,5 @@ export function cloneRenderMaterial(source) {
 }
 export { renderTargetScope, readTargetPixelsScoped, readFloatTargetScoped, } from "./renderTargetScope.js";
 export { createObjectTriplanarMaterial } from "./objectTriplanar.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

@@ -0,0 +1,11 @@
+import { MeshStandardMaterial, type MeshStandardMaterialParameters } from "three";
+export type ThinFoliageMaterialParameters = MeshStandardMaterialParameters & {
+    /** Fraction of diffuse illumination allocated to approximate leaf transmission, 0..1. */
+    leafTransmission?: number;
+};
+/** Approximate thin-leaf backlighting using Three's shadowed direct and directional sky light.
+ * Not volumetric transmission. No extra render pass, texture, or animation loop.
+ * 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

@@ -0,0 +1,27 @@
+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.
+ * 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) => {
+        shader.uniforms.absLeafTransmission = { value: leafTransmission };
+        shader.fragmentShader =
+            "uniform float absLeafTransmission;\n" +
+                withLeafTransmissionField(shader.fragmentShader, "absLeafTransmission");
+    };
+    material.customProgramCacheKey = () => `absolute-thin-foliage-2:${leafTransmission}`;
+    return material;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@absolutejs/rendering",
-  "version": "0.4.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",
@@ -38,7 +38,9 @@
     "check:package": "bun run build && bun run test",
     "test:browser": "bun scripts/verify-browser.cjs",
     "test:spring:browser": "bun scripts/verify-spring.cjs",
-    "test:triplanar:browser": "bun scripts/verify-triplanar.cjs"
+    "test:triplanar:browser": "bun scripts/verify-triplanar.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",