@absolutejs/rendering 0.3.0 → 0.4.0

package/README.md

@@ -87,3 +87,47 @@ 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.

package/dist/index.d.ts

@@ -12,3 +12,5 @@ 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";

package/dist/index.js

@@ -76,3 +76,4 @@ export function cloneRenderMaterial(source) {
     return copy;
 }
 export { renderTargetScope, readTargetPixelsScoped, readFloatTargetScoped, } from "./renderTargetScope.js";
+export { createObjectTriplanarMaterial } from "./objectTriplanar.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/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.4.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,8 @@
     "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"
   },
   "peerDependencies": {
     "three": ">=0.186.0 <0.187.0",