@needle-tools/materialx 1.7.0-next.9ec2906 → 1.7.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@needle-tools/materialx",
   "description": "MaterialX material support for three.js and Needle Engine – render physically based MaterialX shaders in the browser via WebAssembly",
-  "version": "1.7.0-next.9ec2906",
+  "version": "1.7.1",
   "type": "module",
   "license": "PolyForm-Noncommercial-1.0.0",
   "main": "index.js",
@@ -27,7 +27,10 @@
     "three": ">=0.160.0"
   },
   "scripts": {
-    "test": "node --import=./tests/unit/register-json-loader.js --test tests/unit/**/*.test.js"
+    "test": "node --import=./tests/unit/register-json-loader.js --test tests/unit/**/*.test.js",
+    "test:runtime:node": "node tests/runtime/materialx-runtime-smoke.mjs",
+    "test:runtime:deno": "deno run --allow-read --no-lock --node-modules-dir=auto tests/runtime/materialx-runtime-smoke.mjs",
+    "test:runtime:bun": "bun tests/runtime/materialx-runtime-smoke.mjs"
   },
   "devDependencies": {
     "@needle-tools/engine": "4.x",
@@ -75,4 +78,4 @@
     "type": "git",
     "url": "https://github.com/needle-tools/needle-engine-materialx.git"
   }
-}
+}

package/src/loader/loader.three.d.ts

@@ -44,6 +44,8 @@ export interface MaterialXLoaderOptions {
     environmentRadianceMode?: MaterialXEnvironmentRadianceMode;
     /** Match Three.js glossy specular antialiasing. Defaults to true. */
     specularAntialiasing?: boolean;
+    /** Generate missing MikkTSpace tangents for tangent-dependent shaders. Defaults to true. */
+    generateTangents?: boolean;
     /** Flip texcoord V at the MaterialX texcoord node output. Defaults to false for standalone .mtlx creation and true for GLTFLoader integration. */
     hwTexcoordVerticalFlip?: boolean;
     /** Flip texcoord V inside MaterialX file texture sampling. Defaults to false for standalone .mtlx creation and true for GLTFLoader integration. */

package/src/loader/loader.three.js

@@ -358,6 +358,7 @@ export async function createMaterialXMaterial(mtlx, materialNodeNameOrIndex, loa
             context: context || {},
             environmentRadianceMode: options?.environmentRadianceMode,
             specularAntialiasing: options?.specularAntialiasing,
+            generateTangents: options?.generateTangents,
             parameters: {
                 // MASK uses discard; BLEND uses Three.js transparent sorting and blending.
                 transparent: renderAsTransparent,

package/src/materialx.helper.js

@@ -71,10 +71,22 @@ function fromMatrix(matrix, dimension) {
  * @property {(path: string) => Promise<THREE.Texture | null | void>} getTexture - Get a texture by path
  */
 
+/**
+ * @param {string} src
+ * @returns {HTMLImageElement | { src: string }}
+ */
+function createPortableImage(src) {
+    if (typeof Image !== 'undefined') {
+        const image = new Image();
+        image.src = src;
+        return image;
+    }
+    return { src };
+}
+
 const defaultTexture = new THREE.Texture();
 defaultTexture.needsUpdate = true;
-defaultTexture.image = new Image();
-defaultTexture.image.src = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAgAAAAIAQMAAAD+wSzIAAAAAXNSR0IB2cksfwAAAAlwSFlzAAALEwAACxMBAJqcGAAAAANQTFRFr6+vGqg52AAAAAxJREFUeJxjZGBEgQAAWAAJLpjsTQAAAABJRU5ErkJggg=="
+defaultTexture.image = createPortableImage("data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAgAAAAIAQMAAAD+wSzIAAAAAXNSR0IB2cksfwAAAAlwSFlzAAALEwAACxMBAJqcGAAAAANQTFRFr6+vGqg52AAAAAxJREFUeJxjZGBEgQAAWAAJLpjsTQAAAABJRU5ErkJggg==");
 // defaultTexture.image.src = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQBAMAAADt3eJSAAAAAXNSR0IB2cksfwAAAAlwSFlzAAALEwAACxMBAJqcGAAAAB5QTFRFAAAABAQEw8PD////v7+/vb29Xl5eQEBA+/v7PDw8GPBYkgAAAB1JREFUeJxjZGBgYFQSABIUMlxgDGMGBtaIAnIZAKwQCSDYUEZEAAAAAElFTkSuQmCC";
 // defaultTexture.wrapS = THREE.RepeatWrapping;
 // defaultTexture.wrapT = THREE.RepeatWrapping;
@@ -84,8 +96,7 @@ defaultTexture.image.src = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAgAAA
 
 const defaultNormalTexture = new THREE.Texture();
 defaultNormalTexture.needsUpdate = true;
-defaultNormalTexture.image = new Image();
-defaultNormalTexture.image.src = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAgAAAAIBAMAAAA2IaO4AAAAAXNSR0IB2cksfwAAAAlwSFlzAAALEwAACxMBAJqcGAAAABJQTFRFgYH4gIH4gYH3gIH3gIH5gID4m94ORAAAADFJREFUeJxjZBBkfMdo9P/BB0aBj/8FGB0ufghgFGT4r8wo+P8rD2Pgo3sMjIz8jAwAMLoN0ZjS5hgAAAAASUVORK5CYII=";
+defaultNormalTexture.image = createPortableImage("data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAgAAAAIBAMAAAA2IaO4AAAAAXNSR0IB2cksfwAAAAlwSFlzAAALEwAACxMBAJqcGAAAABJQTFRFgYH4gIH4gYH3gIH3gIH5gID4m94ORAAAADFJREFUeJxjZBBkfMdo9P/BB0aBj/8FGB0ufghgFGT4r8wo+P8rD2Pgo3sMjIz8jAwAMLoN0ZjS5hgAAAAASUVORK5CYII=");
 
 /**
  * @param {string} key
@@ -111,6 +122,75 @@ function addToCache(key, value) {
     if (debug) console.log('[MaterialX] Added to cache:', key, value);
 }
 
+/**
+ * @param {string} value
+ * @returns {boolean}
+ */
+function isAbsoluteTexturePath(value) {
+    return /^[a-z][a-z0-9+.-]*:/i.test(value) || value.startsWith("//") || value.startsWith("/");
+}
+
+/**
+ * @param {string} value
+ * @returns {boolean}
+ */
+function isAbsoluteUrl(value) {
+    return /^[a-z][a-z0-9+.-]*:\/\//i.test(value);
+}
+
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+function withTrailingSlash(value) {
+    return value.endsWith(IMAGE_PATH_SEPARATOR) ? value : `${value}${IMAGE_PATH_SEPARATOR}`;
+}
+
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+function normalizeRelativeTexturePath(value) {
+    const suffixStart = value.search(/[?#]/);
+    const path = suffixStart >= 0 ? value.slice(0, suffixStart) : value;
+    const suffix = suffixStart >= 0 ? value.slice(suffixStart) : "";
+    const hasLeadingSlash = path.startsWith(IMAGE_PATH_SEPARATOR);
+    const parts = [];
+
+    for (const part of path.split(IMAGE_PATH_SEPARATOR)) {
+        if (!part || part === ".") continue;
+        if (part === "..") {
+            const previous = parts[parts.length - 1];
+            if (previous && previous !== "..") parts.pop();
+            else if (!hasLeadingSlash) parts.push(part);
+            continue;
+        }
+        parts.push(part);
+    }
+
+    const normalizedPath = `${hasLeadingSlash ? IMAGE_PATH_SEPARATOR : ""}${parts.join(IMAGE_PATH_SEPARATOR)}`;
+    return `${normalizedPath}${suffix}`;
+}
+
+/**
+ * @param {string} searchPath
+ * @param {string} value
+ * @returns {string}
+ */
+function resolveTexturePath(searchPath, value) {
+    if (isAbsoluteTexturePath(value)) return value;
+    if (!searchPath) return value;
+
+    const normalizedSearchPath = searchPath.replace(/\/+$/, "");
+    if (!normalizedSearchPath) return value;
+
+    if (isAbsoluteUrl(normalizedSearchPath)) {
+        return new URL(value, withTrailingSlash(normalizedSearchPath)).href;
+    }
+
+    return normalizeRelativeTexturePath(`${normalizedSearchPath}${IMAGE_PATH_SEPARATOR}${value}`);
+}
+
 /**
  * Get Three uniform from MaterialX value
  * @param {any} uniforms
@@ -154,19 +234,19 @@ function toThreeUniform(threeUniforms, uniforms, type, value, name, loaders, sea
                 // Cache / reuse texture to avoid reload overhead.
                 // Note: that data blobs and embedded data textures are not cached as they are transient data.
                 let checkCache = true;
-                let texturePath = searchPath + IMAGE_PATH_SEPARATOR + value;
+                let texturePath = value;
                 if (value.startsWith('blob:')) {
-                    texturePath = value;
                     checkCache = false;
                 }
                 else if (value.startsWith('data:')) {
-                    texturePath = value;
                     checkCache = false;
                 }
                 else if (value.startsWith('http')) {
-                    texturePath = value;
                     checkCache = true;
                 }
+                else {
+                    texturePath = resolveTexturePath(searchPath, value);
+                }
 
                 const cacheKey = loaders.cacheKey?.length ? `${loaders.cacheKey}-${texturePath}` : texturePath;
                 const cacheValue = checkCache ? tryGetFromCache(cacheKey) : null;
@@ -236,7 +316,7 @@ function toThreeUniform(threeUniforms, uniforms, type, value, name, loaders, sea
         case 'displacementshader':
         case 'volumeshader':
         case 'lightshader':
-            // MaterialX closure/shader types — not real uniforms, skip silently
+            // MaterialX closure/shader types — not emitted uniforms, skip silently
             break;
         default:
             const key = type + ':' + name;

package/src/materialx.js

@@ -17,6 +17,21 @@ function isTextureLike(value) {
     return !!value && typeof value === "object" && /** @type {{ isTexture?: unknown }} */(value).isTexture === true;
 }
 
+function isNodeRuntime() {
+    return !!globalThis.process?.versions?.node && globalThis.process?.type !== "renderer";
+}
+
+async function getNodePackageAssetPaths() {
+    const nodeUrlModule = "node:url";
+    const { fileURLToPath } = await import(/* @vite-ignore */ nodeUrlModule);
+    const binDirectory = ["..", "bin"].join("/") + "/";
+    return [
+        "JsMaterialXCore.wasm",
+        "JsMaterialXGenShader.wasm",
+        "JsMaterialXGenShader.data.txt",
+    ].map(fileName => fileURLToPath(new URL(binDirectory + fileName, import.meta.url)));
+}
+
 
 /**
  * Preloads the MaterialX WebAssembly module.
@@ -69,7 +84,10 @@ export async function ready() {
 
             const location = globalThis.NEEDLE_MATERIALX_LOCATION;
 
-            if (location === "package" || location === "bin/" || location === "./bin/" || location === "../bin/") {
+            if (isNodeRuntime()) {
+                urls = await getNodePackageAssetPaths();
+            }
+            else if (location === "package" || location === "bin/" || location === "./bin/" || location === "../bin/") {
                 // Use local files from the @needle-tools/materialx npm package.
                 // Vite's ?url suffix copies these files to the output directory
                 // and returns their URL automatically — no CDN download needed.

package/src/materialx.material.d.ts

@@ -12,6 +12,7 @@ declare type MaterialXMaterialInitParameters = {
     parameters?: MaterialParameters;
     environmentRadianceMode?: MaterialXEnvironmentRadianceMode;
     specularAntialiasing?: boolean;
+    generateTangents?: boolean;
     debug?: boolean;
 }
 
@@ -38,6 +39,7 @@ export declare class MaterialXMaterial extends ShaderMaterial {
     envMapRotation: Euler;
     environmentRadianceMode: MaterialXEnvironmentRadianceMode;
     specularAntialiasing: boolean;
+    generateTangents: boolean;
     updateUniforms(environment: MaterialXEnvironment, _renderer: WebGLRenderer, object: Object3D, camera: Camera, time?: number, frame?: number): void;
 
     private updateEnvironmentUniforms(environment: MaterialXEnvironment, scene: Scene): void;

package/src/materialx.material.js

@@ -5,6 +5,11 @@ import { generateMaterialPropertiesForUniforms, getUniformValues, getLightTypeId
 
 export const DEFAULT_ENVIRONMENT_RADIANCE_MODE = "three-pmrem";
 
+/** @type {Promise<{ computeMikkTSpaceTangents: Function, MikkTSpace: any }> | null} */
+let mikkTSpaceTangentsPromise = null;
+/** @type {WeakMap<BufferGeometry, Promise<boolean>>} */
+const pendingTangentGenerations = new WeakMap();
+
 // Add helper matrices for uniform updates (similar to MaterialX example)
 const worldInverseMat = new Matrix4();
 const worldTransposeMat = new Matrix4();
@@ -91,6 +96,60 @@ function createThreeLightUniforms() {
     };
 }
 
+function getMikkTSpaceTangents() {
+    mikkTSpaceTangentsPromise ??= Promise.all([
+        import('three/examples/jsm/utils/BufferGeometryUtils.js'),
+        import('three/examples/jsm/libs/mikktspace.module.js'),
+    ]).then(async ([utils, MikkTSpace]) => {
+        await MikkTSpace.ready;
+        return {
+            computeMikkTSpaceTangents: utils.computeMikkTSpaceTangents,
+            MikkTSpace,
+        };
+    });
+    return mikkTSpaceTangentsPromise;
+}
+
+/**
+ * @param {BufferGeometry} geometry
+ * @returns {Promise<boolean>}
+ */
+function ensureGeometryTangents(geometry) {
+    if (geometry.attributes.tangent) return Promise.resolve(true);
+
+    let pending = pendingTangentGenerations.get(geometry);
+    if (pending) return pending;
+
+    pending = (async () => {
+        if (!geometry.attributes.position || !geometry.attributes.uv) {
+            console.warn('[MaterialX] Cannot generate tangents: geometry requires position and uv attributes.');
+            return false;
+        }
+
+        if (!geometry.attributes.normal) {
+            geometry.computeVertexNormals();
+        }
+
+        const { computeMikkTSpaceTangents, MikkTSpace } = await getMikkTSpaceTangents();
+        computeMikkTSpaceTangents(geometry, MikkTSpace);
+
+        if (geometry.attributes.tangent) {
+            geometry.attributes.tangent.needsUpdate = true;
+            return true;
+        }
+
+        return false;
+    })().catch(error => {
+        console.warn('[MaterialX] Failed to generate MikkTSpace tangents.', error);
+        return false;
+    }).finally(() => {
+        pendingTangentGenerations.delete(geometry);
+    });
+
+    pendingTangentGenerations.set(geometry, pending);
+    return pending;
+}
+
 const CUBE_UV_REFLECTION_FUNCTIONS = `
 float mx_cubeuv_getFace(vec3 direction) {
     vec3 absDirection = abs(direction);
@@ -305,6 +364,7 @@ function patchImageAddressModes(fragmentShader) {
  * @property {import('three').MaterialParameters} [parameters] - Optional parameters
  * @property {"three-pmrem" | "materialx-prefiltered" | "materialx-fis"} [environmentRadianceMode]
  * @property {boolean} [specularAntialiasing] - Match Three.js glossy specular antialiasing. Defaults to true.
+ * @property {boolean} [generateTangents] - Generate missing MikkTSpace tangents for tangent-dependent shaders. Defaults to true.
  * @property {boolean} [debug] - Debug flag
  */
 
@@ -336,6 +396,7 @@ export class MaterialXMaterial extends ShaderMaterial {
         this.envMapRotation.copy(source.envMapRotation);
         this.environmentRadianceMode = source.environmentRadianceMode;
         this.specularAntialiasing = source.specularAntialiasing;
+        this.generateTangents = source.generateTangents;
         this.ready = source.ready;
         generateMaterialPropertiesForUniforms(this, this._shader.getStage('pixel'));
         generateMaterialPropertiesForUniforms(this, this._shader.getStage('vertex'));
@@ -349,6 +410,8 @@ export class MaterialXMaterial extends ShaderMaterial {
     _shader = null;
     /** @type {boolean} */
     _needsTangents = false;
+    /** @type {WeakSet<BufferGeometry>} */
+    _pendingTangentGeometries = new WeakSet();
     /** @type {Promise<void>} */
     ready = Promise.resolve();
 
@@ -368,6 +431,7 @@ export class MaterialXMaterial extends ShaderMaterial {
         /** @type {"three-pmrem" | "materialx-prefiltered" | "materialx-fis"} */
         let environmentRadianceMode = DEFAULT_ENVIRONMENT_RADIANCE_MODE;
         let specularAntialiasing = true;
+        let generateTangents = true;
 
         if (init) {
 
@@ -423,6 +487,7 @@ export class MaterialXMaterial extends ShaderMaterial {
         // the same way MeshStandardMaterial does.
         fragmentShader = fragmentShader.replace(/\bu_envLightIntensity\b/g, 'envMapIntensity');
         specularAntialiasing = init.specularAntialiasing ?? true;
+        generateTangents = init.generateTangents ?? true;
         if (specularAntialiasing) {
             fragmentShader = patchEnvironmentSpecularAntialiasing(fragmentShader);
         }
@@ -698,6 +763,7 @@ $2`
         this._needsTangents = vertexShader.includes('in vec4 tangent;') || vertexShader.includes('in vec3 tangent;');
         this.environmentRadianceMode = environmentRadianceMode;
         this.specularAntialiasing = specularAntialiasing;
+        this.generateTangents = generateTangents;
 
         Object.assign(this.uniforms,
             // Three.js light uniforms (required when lights: true). These use
@@ -760,10 +826,23 @@ $2`
      */
     onBeforeRender(renderer, _scene, camera, geometry, object, _group) {
         if (this._needsTangents && !geometry.attributes.tangent) {
-            if (!this._missingTangentsWarned) {
+            if (this.generateTangents) {
+                if (!this._pendingTangentGeometries.has(geometry)) {
+                    this._pendingTangentGeometries.add(geometry);
+                    ensureGeometryTangents(geometry).then(generated => {
+                        if (generated) {
+                            this.needsUpdate = true;
+                        } else if (!this._missingTangentsWarned) {
+                            this._missingTangentsWarned = true;
+                            console.warn(`[MaterialX] Tangents are required for this material (${this.name}) but could not be generated for the geometry.`);
+                        }
+                    }).finally(() => {
+                        this._pendingTangentGeometries.delete(geometry);
+                    });
+                }
+            } else if (!this._missingTangentsWarned) {
                 this._missingTangentsWarned = true;
-                console.warn(`[MaterialX] Tangents are required for this material (${this.name}) but not present in the geometry.`);
-                // TODO: can we compute tangents here?
+                console.warn(`[MaterialX] Tangents are required for this material (${this.name}) but not present in the geometry. Automatic tangent generation is disabled.`);
             }
         }
         const time = this._context?.getTime?.() || getTime();
@@ -786,6 +865,8 @@ $2`
     environmentRadianceMode = DEFAULT_ENVIRONMENT_RADIANCE_MODE;
     /** @type {boolean} */
     specularAntialiasing = true;
+    /** @type {boolean} */
+    generateTangents = true;
 
     /**
      * @param {import("three").WebGLRenderer} _renderer

package/src/utils.js

@@ -7,7 +7,9 @@
  * @returns {boolean|string} Parameter value or false if not found
  */
 export function getParam(name) {
-    const urlParams = new URLSearchParams(window.location.search);
+    const search = globalThis.location?.search ?? globalThis.window?.location?.search;
+    if (!search) return false;
+    const urlParams = new URLSearchParams(search);
     const param = urlParams.get(name);
     if (param == null || param === "0" || param === "false") return false;
     if (param === "") return true;
@@ -35,22 +37,26 @@ export function getFrame() {
     return frame;
 }
 
-const performance = window.performance || /** @type {any} */ (window).webkitPerformance || /** @type {any} */ (window).mozPerformance;
+const performanceApi = globalThis.performance
+    || globalThis.window?.performance
+    || /** @type {any} */ (globalThis.window)?.webkitPerformance
+    || /** @type {any} */ (globalThis.window)?.mozPerformance
+    || { now: () => Date.now() };
 
 function updateTime() {
-    time = performance.now() / 1000; // Convert to seconds
+    time = performanceApi.now() / 1000; // Convert to seconds
     frame++;
-    window.requestAnimationFrame(updateTime);
+    globalThis.requestAnimationFrame?.(updateTime);
 }
 
-window.requestAnimationFrame(updateTime);
+globalThis.requestAnimationFrame?.(updateTime);
 
 
 
 
 export async function waitForNetworkIdle() {
-    if (typeof requestIdleCallback !== "undefined") {
-        return new Promise(res => requestIdleCallback(res));
+    if (typeof globalThis.requestIdleCallback !== "undefined") {
+        return new Promise(res => globalThis.requestIdleCallback(res));
     }
     else {
         console.debug("[MaterialX] Can not wait for network idle, using fallback");
@@ -61,5 +67,6 @@ export async function waitForNetworkIdle() {
 
 export function isDevEnvironment() {
     // check if we're in localhost or using an ip address
-    return window.location.hostname === "localhost" || /^\d{1,3}(\.\d{1,3}){3}$/.test(window.location.hostname);
-}
+    const hostname = globalThis.location?.hostname ?? globalThis.window?.location?.hostname;
+    return hostname === "localhost" || !!hostname && /^\d{1,3}(\.\d{1,3}){3}$/.test(hostname);
+}