@absolutejs/rendering 0.3.0 → 0.5.0

package/README.md

@@ -87,3 +87,59 @@ React Spring peers are optional for the core material utilities, but required
 when using this subpath. `@react-spring/three` supplies host types only; it is not
 runtime-imported by this entry. The tested versions are React 19.3, Fiber 9.8.2,
 Three 0.186.1 and React Spring 10.1.2.
+
+## Rigid-object triplanar materials
+
+`createObjectTriplanarMaterial` keeps color, normal detail and roughness aligned
+without depending on mesh UVs. Coordinates remain local to the geometry, so a
+moving rigid object does not slide through a world-space texture field.
+
+```ts
+import { createObjectTriplanarMaterial } from '@absolutejs/rendering';
+import { RepeatWrapping, SRGBColorSpace, Vector2 } from 'three';
+
+for (const texture of [albedo, normal, roughness]) {
+  texture.wrapS = texture.wrapT = RepeatWrapping;
+}
+albedo.colorSpace = SRGBColorSpace; // normal and roughness remain non-color data
+const material = createObjectTriplanarMaterial({
+  map: albedo,
+  normalMap: normal,
+  roughnessMap: roughness,
+  normalScale: new Vector2(0.65, 0.65),
+  projection: { scale: 1, offset: [0, 0, 0], sharpness: 4 },
+});
+```
+
+Projection scale is repeats per geometry-local unit; UV texture matrices/repeat
+values are replaced by these controls. Offset and scale are copied at creation.
+Sharpness ranges from 1 to 16; scale must be finite, positive and at most 10,000.
+Color uses the texture's color space; roughness uses its green channel. Tangent
+normal maps, including packed RG and negative normal-Y scale, blend as surface
+slopes before perturbing the local normal. Neutral maps preserve base normals.
+
+Scope is opaque, rigid geometry. Mesh and non-sheared instanced transforms follow
+Three's normal-matrix conventions. Skinning, active morphs, displacement, bump maps,
+object-space normal maps and video albedo are rejected. Transparent, alpha-test,
+alpha-hash and alpha-to-coverage surfaces are rejected because they need matching
+shadow coverage shaders. Other StandardMaterial channels retain their normal Three
+behavior. The helper is for WebGLRenderer; it is not a WebGPU/TSL implementation.
+
+The material borrows textures and does not alter or dispose them. Use
+`cloneRenderMaterial` to retain shader hooks when cloning. Dispose material and
+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, indirect lighting,
+fog and tone mapping. Area lights retain standard lighting. 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.

package/dist/index.d.ts

@@ -12,3 +12,7 @@ export declare function bindAlphaToCoverageDestination(material: Material, enabl
  * cannot alter another. No source material is mutated. */
 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';

package/dist/index.js

@@ -76,3 +76,5 @@ export function cloneRenderMaterial(source) {
     return copy;
 }
 export { renderTargetScope, readTargetPixelsScoped, readFloatTargetScoped, } from "./renderTargetScope.js";
+export { createObjectTriplanarMaterial } from "./objectTriplanar.js";
+export { createThinFoliageMaterial } from './thinFoliage.js';

package/dist/objectTriplanar.d.ts

@@ -0,0 +1,18 @@
+import { MeshStandardMaterial, type MeshStandardMaterialParameters } from "three";
+export type ObjectTriplanarProjection = {
+    /** Repeats per geometry-local unit; does not swim when an object moves. */
+    scale?: number;
+    /** Stable geometry-local phase, shared by color, normal and roughness. */
+    offset?: readonly [number, number, number];
+    /** Axis blending exponent. One is broad; larger values favor the dominant axis. */
+    sharpness?: number;
+};
+export type ObjectTriplanarMaterialParameters = MeshStandardMaterialParameters & {
+    projection?: ObjectTriplanarProjection;
+};
+/** UV-independent color, tangent-normal and roughness projection for rigid meshes.
+ * Borrows textures. Uses MeshStandardMaterial lighting/shadows and one draw.
+ * Instancing follows Three's non-sheared instance normal transform. Skinning,
+ * active morphs and displacement are outside this material's rigid-object scope.
+ * Use cloneRenderMaterial when cloning so the authored shader hooks are retained. */
+export declare function createObjectTriplanarMaterial(options?: ObjectTriplanarMaterialParameters): MeshStandardMaterial;

package/dist/objectTriplanar.js

@@ -0,0 +1,149 @@
+import { MeshStandardMaterial, TangentSpaceNormalMap, Vector3, } from "three";
+const revision = "absolute-object-triplanar-1";
+function replaceOnce(source, anchor, replacement) {
+    if (source.split(anchor).length !== 2)
+        throw Error(`Unsupported Three shader anchor: ${anchor}`);
+    return source.replace(anchor, replacement);
+}
+const varying = `
+varying vec3 absTriPosition;
+varying vec3 absTriObjectNormal;
+varying mat3 absTriNormalToView;
+`;
+const functions = `
+${varying}
+uniform float absTriScale;
+uniform vec3 absTriOffset;
+uniform float absTriSharpness;
+vec4 absTriSample(sampler2D tex, vec3 p, vec3 dx, vec3 dy, vec3 w) {
+ return textureGrad(tex,p.yz,dx.yz,dy.yz)*w.x
+      +textureGrad(tex,p.xz,dx.xz,dy.xz)*w.y
+      +textureGrad(tex,p.xy,dx.xy,dy.xy)*w.z;
+}
+#ifdef USE_NORMALMAP_TANGENTSPACE
+vec2 absTriSlope(vec3 encoded) {
+ vec3 n=encoded*2.-1.;
+ #ifdef USE_PACKED_NORMALMAP
+ n.z=sqrt(max(0.,1.-dot(n.xy,n.xy)));
+ #endif
+ return -n.xy*normalScale/max(n.z,.1);
+}
+vec3 absTriGradient(vec3 p,vec3 dx,vec3 dy,vec3 w) {
+ vec2 x=absTriSlope(textureGrad(normalMap,p.yz,dx.yz,dy.yz).xyz);
+ vec2 y=absTriSlope(textureGrad(normalMap,p.xz,dx.xz,dy.xz).xyz);
+ vec2 z=absTriSlope(textureGrad(normalMap,p.xy,dx.xy,dy.xy).xyz);
+ return vec3(0.,x.x,x.y)*w.x+vec3(y.x,0.,y.y)*w.y+vec3(z.x,z.y,0.)*w.z;
+}
+#endif
+`;
+const prepare = `
+vec3 absTriN=normalize(absTriObjectNormal);
+#ifdef FLAT_SHADED
+vec3 absTriArea=cross(dFdx(absTriPosition),dFdy(absTriPosition));
+if(dot(absTriArea,absTriArea)>1e-20) {
+ absTriArea=normalize(absTriArea);
+ absTriN=dot(absTriArea,absTriN)<0.?-absTriArea:absTriArea;
+}
+#endif
+vec3 absTriW=pow(abs(absTriN),vec3(absTriSharpness));
+absTriW/=max(dot(absTriW,vec3(1.)),1e-20);
+vec3 absTriP=absTriPosition*absTriScale+absTriOffset;
+vec3 absTriDx=dFdx(absTriP),absTriDy=dFdy(absTriP);
+`;
+/** UV-independent color, tangent-normal and roughness projection for rigid meshes.
+ * Borrows textures. Uses MeshStandardMaterial lighting/shadows and one draw.
+ * Instancing follows Three's non-sheared instance normal transform. Skinning,
+ * active morphs and displacement are outside this material's rigid-object scope.
+ * Use cloneRenderMaterial when cloning so the authored shader hooks are retained. */
+export function createObjectTriplanarMaterial(options = {}) {
+    const { projection = {}, ...parameters } = options;
+    const scale = projection.scale ?? 1;
+    const sharpness = projection.sharpness ?? 4;
+    const offset = [...(projection.offset ?? [0, 0, 0])];
+    if (!Number.isFinite(scale) || scale <= 0 || scale > 10000)
+        throw Error("Invalid triplanar scale");
+    if (!Number.isFinite(sharpness) || sharpness < 1 || sharpness > 16)
+        throw Error("Invalid triplanar sharpness");
+    if (offset.length !== 3 ||
+        offset.some((v) => !Number.isFinite(v) || Math.abs(v) > 1e6))
+        throw Error("Invalid triplanar offset");
+    if (parameters.bumpMap ||
+        parameters.displacementMap ||
+        (parameters.normalMapType !== undefined &&
+            parameters.normalMapType !== TangentSpaceNormalMap) ||
+        parameters.map?.isVideoTexture)
+        throw Error("Unsupported object-triplanar map type");
+    if (parameters.transparent ||
+        parameters.alphaHash ||
+        parameters.alphaToCoverage ||
+        (parameters.alphaTest ?? 0) > 0)
+        throw Error("Object triplanar mapping requires opaque coverage");
+    const material = new MeshStandardMaterial(parameters);
+    material.customProgramCacheKey = () => revision;
+    material.onBeforeRender = function (_renderer, _scene, _camera, _geometry, object) {
+        if (this.transparent ||
+            this.alphaHash ||
+            this.alphaToCoverage ||
+            this.alphaTest > 0)
+            throw Error("Object triplanar mapping requires opaque coverage");
+        if (this.bumpMap ||
+            this.displacementMap ||
+            this.normalMapType !== TangentSpaceNormalMap ||
+            this.map?.isVideoTexture)
+            throw Error("Unsupported object-triplanar map type");
+        const mesh = object;
+        if (mesh.isSkinnedMesh ||
+            mesh.morphTargetInfluences?.some((value) => value !== 0))
+            throw Error("Object triplanar mapping requires rigid geometry");
+    };
+    material.onBeforeCompile = (shader) => {
+        shader.uniforms.absTriScale = { value: scale };
+        shader.uniforms.absTriSharpness = { value: sharpness };
+        shader.uniforms.absTriOffset = {
+            value: new Vector3(offset[0], offset[1], offset[2]),
+        };
+        shader.vertexShader = replaceOnce(shader.vertexShader, "#include <common>", `#include <common>\n${varying}`);
+        shader.vertexShader = replaceOnce(shader.vertexShader, "#include <defaultnormal_vertex>", `#include <defaultnormal_vertex>
+mat3 absTriFrame=mat3(1.);
+#ifdef USE_BATCHING
+absTriFrame=mat3(bm[0]/dot(bm[0],bm[0]),bm[1]/dot(bm[1],bm[1]),bm[2]/dot(bm[2],bm[2]))*absTriFrame;
+#endif
+#ifdef USE_INSTANCING
+absTriFrame=mat3(im[0]/dot(im[0],im[0]),im[1]/dot(im[1],im[1]),im[2]/dot(im[2],im[2]))*absTriFrame;
+#endif
+absTriNormalToView=normalMatrix*absTriFrame;
+absTriObjectNormal=objectNormal;
+`);
+        shader.vertexShader = replaceOnce(shader.vertexShader, "#include <begin_vertex>", "#include <begin_vertex>\nabsTriPosition=transformed;");
+        // Normal-map declarations precede helper functions that use their uniforms.
+        shader.fragmentShader = replaceOnce(shader.fragmentShader, "#include <normalmap_pars_fragment>", `#include <normalmap_pars_fragment>\n${functions}`);
+        shader.fragmentShader = replaceOnce(shader.fragmentShader, "#include <map_fragment>", `${prepare}
+#ifdef USE_MAP
+diffuseColor*=absTriSample(map,absTriP,absTriDx,absTriDy,absTriW);
+#endif
+`);
+        shader.fragmentShader = replaceOnce(shader.fragmentShader, "#include <roughnessmap_fragment>", `
+float roughnessFactor=roughness;
+#ifdef USE_ROUGHNESSMAP
+roughnessFactor*=absTriSample(roughnessMap,absTriP,absTriDx,absTriDy,absTriW).g;
+#endif
+`);
+        shader.fragmentShader = replaceOnce(shader.fragmentShader, "#include <normal_fragment_maps>", `
+#ifdef USE_NORMALMAP_TANGENTSPACE
+vec3 absTriG=absTriGradient(absTriP,absTriDx,absTriDy,absTriW);
+vec3 absTriSurfaceG=absTriG-absTriN*dot(absTriG,absTriN);
+if(dot(absTriSurfaceG,absTriSurfaceG)>1e-20) {
+ vec3 absTriBumped=normalize(absTriNormalToView*(absTriN-absTriSurfaceG));
+ #ifdef FLIP_SIDED
+ absTriBumped=-absTriBumped;
+ #endif
+ #ifdef DOUBLE_SIDED
+ absTriBumped*=faceDirection;
+ #endif
+ normal=absTriBumped;
+}
+#endif
+`);
+    };
+    return material;
+}

package/dist/thinFoliage.d.ts

@@ -0,0 +1,11 @@
+import { MeshStandardMaterial, type MeshStandardMaterialParameters } from 'three';
+export type ThinFoliageMaterialParameters = MeshStandardMaterialParameters & {
+    /** Fraction of direct diffuse allocated to approximate leaf transmission, 0..1. */
+    leafTransmission?: number;
+};
+/** Approximate thin-leaf backlighting using Three's already shadowed direct light.
+ * Not volumetric transmission. No extra render pass, texture, or animation loop.
+ * Area-light and environment paths 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,34 @@
+import { DoubleSide, MeshStandardMaterial } from 'three';
+/** Approximate thin-leaf backlighting using Three's already shadowed direct light.
+ * Not volumetric transmission. No extra render pass, texture, or animation loop.
+ * Area-light and environment paths 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');
+        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
+`);
+    };
+    material.customProgramCacheKey = () => `absolute-thin-foliage-1:${leafTransmission}`;
+    return material;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@absolutejs/rendering",
-  "version": "0.3.0",
-  "description": "Render-destination coverage policies and callback-preserving material ownership for Three.js applications.",
+  "version": "0.5.0",
+  "description": "Three.js material ownership, destination coverage, rigid-object triplanar mapping and isolated React Spring hosts.",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -37,7 +37,9 @@
     "test": "bun test ./tests",
     "check:package": "bun run build && bun run test",
     "test:browser": "bun scripts/verify-browser.cjs",
-    "test:spring:browser": "bun scripts/verify-spring.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"
   },
   "peerDependencies": {
     "three": ">=0.186.0 <0.187.0",