@needle-tools/materialx 1.6.0-next.2af5fc1 → 1.7.0-next.0d06218

package/bin/revision.json

@@ -1,5 +1,5 @@
 {
-  "commit": "0e7685f37737511f2816949b9486d511a5fa71bd",
-  "version": "1.39.4",
-  "buildDate": "2026-04-01 14:56:42"
+  "commit": "ab218c56f016a9a2d398e8d306f3aeb439ae9e9e",
+  "version": "1.39.5",
+  "buildDate": "2026-05-21 15:22:48"
 }

package/package.json

@@ -1,20 +1,20 @@
 {
   "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.6.0-next.2af5fc1",
+  "version": "1.7.0-next.0d06218",
   "type": "module",
   "main": "index.js",
   "types": "index.d.ts",
   "exports": {
     ".": {
+      "types": "./index.d.ts",
       "import": "./index.js",
-      "require": "./index.js",
-      "types": "./index.d.ts"
+      "require": "./index.js"
     },
     "./needle": {
+      "types": "./needle.d.ts",
       "import": "./needle.js",
-      "require": "./needle.js",
-      "types": "./needle.d.ts"
+      "require": "./needle.js"
     },
     "./package.json": "./package.json",
     "./codegen/register_types.ts": {
@@ -66,5 +66,9 @@
     "pbr",
     "3d",
     "wasm"
-  ]
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/needle-tools/needle-engine-materialx.git"
+  }
 }

package/src/index.d.ts

@@ -1,4 +1,4 @@
-export { ready, type MaterialXContext, preloadWasm } from "./materialx.js";
+export { ready, type MaterialXContext, type MaterialXEnvironmentRadianceMode, preloadWasm } from "./materialx.js";
 export { MaterialXEnvironment } from "./materialx.js";
 export { MaterialXMaterial } from "./materialx.material.js";
 export { MaterialXLoader } from "./loader/loader.three.js";
@@ -10,4 +10,3 @@ declare const Experimental_API: {
 };
 
 export { Experimental_API };
-

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

@@ -1,6 +1,7 @@
 import { Material, MaterialParameters } from "three";
 import { GLTFLoader, GLTFLoaderPlugin, GLTFParser } from "three/examples/jsm/loaders/GLTFLoader.js";
 import { MaterialXContext } from "../materialx.js";
+import type { MaterialXEnvironmentRadianceMode } from "../materialx.js";
 import { MaterialXMaterial } from "../materialx.material.js";
 import { Callbacks } from "../materialx.helper.js";
 
@@ -39,6 +40,14 @@ export interface MaterialXLoaderOptions {
     cacheKey?: string;
     /** Parameters for the MaterialX loader */
     parameters?: Pick<MaterialParameters, "precision">;
+    /** Environment radiance backend. Defaults to direct Three.js CubeUV PMREM sampling. */
+    environmentRadianceMode?: MaterialXEnvironmentRadianceMode;
+    /** Match Three.js glossy specular antialiasing. Defaults to true. */
+    specularAntialiasing?: 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. */
+    fileTextureVerticalFlip?: boolean;
 }
 
 export declare class MaterialXLoader implements GLTFLoaderPlugin {
@@ -71,7 +80,7 @@ export declare function useNeedleMaterialX(
 export declare function createMaterialXMaterial(
     mtlx: string, 
     materialNodeName: string | number, 
-    loaders: Callbacks, 
+    loaders?: Callbacks,
     options?: MaterialXLoaderOptions, 
     context?: MaterialXContext
 ): Promise<Material>;

package/src/loader/loader.three.js

@@ -61,7 +61,11 @@ export class MaterialXLoader {
      */
     constructor(parser, options, context) {
         this.parser = parser;
-        this.options = options;
+        this.options = {
+            ...options,
+            hwTexcoordVerticalFlip: options?.hwTexcoordVerticalFlip ?? true,
+            fileTextureVerticalFlip: options?.fileTextureVerticalFlip ?? true,
+        };
         this.context = context;
 
         if (debug) console.log("MaterialXLoader created for parser");
@@ -182,7 +186,7 @@ export function useNeedleMaterialX(loader, options, context) {
 /**
  * Parse the MaterialX document once and cache it
  * @param {string} mtlx
- * @returns {Promise<any>}
+ * @returns {Promise<import("../materialx.types.js").MaterialX.Document>}
  */
 async function load(mtlx) {
     // Ensure MaterialX is initialized
@@ -202,7 +206,7 @@ async function load(mtlx) {
 /**
  * @param {string} mtlx
  * @param {string | number} materialNodeNameOrIndex
- * @param {import('../materialx.helper.js').Callbacks} loaders
+ * @param {import('../materialx.helper.js').Callbacks} [loaders]
  * @param {MaterialXLoaderOptions} [options]
  * @param {import('../materialx.js').MaterialXContext} [context]
  * @returns {Promise<Material>}
@@ -210,6 +214,10 @@ async function load(mtlx) {
 export async function createMaterialXMaterial(mtlx, materialNodeNameOrIndex, loaders, options, context) {
     try {
         if (debug) console.log(`Creating MaterialX material: ${materialNodeNameOrIndex}`);
+        loaders ??= {
+            getTexture: async () => null,
+        };
+
 
         const doc = await load(mtlx);
 
@@ -234,7 +242,7 @@ export async function createMaterialXMaterial(mtlx, materialNodeNameOrIndex, loa
         for (let i = 0; i < materialNodes.length; ++i) {
             const materialNode = materialNodes[i];
             if (materialNode) {
-                const name = materialNode.getNamePath();
+                const name = materialNode.getNamePath?.();
                 if (debug) console.log(`[MaterialX] Scan material[${i}]: ${name}`);
 
                 // Find the matching material
@@ -320,25 +328,21 @@ export async function createMaterialXMaterial(mtlx, materialNodeNameOrIndex, loa
             : (state.materialXModule.isTransparentSurface(renderableElement, target) ? "blend" : "opaque");
         const isMask = alphaMode === "mask";
         const isBlend = alphaMode === "blend";
+        const renderAsTransparent = isBlend;
         // Both MASK and BLEND need alpha handling in the generated shader.
         const needsAlpha = isMask || isBlend;
 
-        // Emscripten's getOptions() returns a temporary wrapper — property writes
-        // don't persist across separate getOptions() calls. Set all options that
-        // matter for generation in a single block right before generate().
+        // Emscripten's getOptions() returns a temporary wrapper; set all options
+        // that matter for generation in one block right before generate().
         {
             const opts = state.materialXGenContext.getOptions();
             // MASK and BLEND need alpha handling in the generated shader.
             opts.hwTransparency = needsAlpha;
-            // three.js provides UVs in glTF convention (V=0 top), MaterialX expects
-            // OpenGL convention (V=0 bottom). Flip at the texcoord node output so all
-            // UV logic (comparisons, noise, displacement) works correctly.
-            opts.hwTexcoordVerticalFlip = true;
-            // three.js GLTFLoader sets texture.flipY=false — textures are in glTF
-            // convention. With hwTexcoordVerticalFlip flipping UV data, texture
-            // sampling needs to flip back to match. fileTextureVerticalFlip does
-            // this inside mx_transform_uv.
-            opts.fileTextureVerticalFlip = true;
+            opts.hwTexcoordVerticalFlip = options?.hwTexcoordVerticalFlip ?? false;
+            opts.fileTextureVerticalFlip = options?.fileTextureVerticalFlip ?? false;
+            opts.hwSpecularEnvironmentMethod = options?.environmentRadianceMode === "materialx-fis"
+                ? state.materialXModule.HwSpecularEnvironmentMethod.SPECULAR_ENVIRONMENT_FIS
+                : state.materialXModule.HwSpecularEnvironmentMethod.SPECULAR_ENVIRONMENT_PREFILTER;
         }
 
         // Generate shaders using the element's name path
@@ -348,19 +352,22 @@ export async function createMaterialXMaterial(mtlx, materialNodeNameOrIndex, loa
         const shader = state.materialXGenerator.generate(elementName, renderableElement, state.materialXGenContext);
 
         const shaderMaterial = new MaterialXMaterial({
-            name: materialNodeNameOrIndex,
+            name: typeof elementName === "string" ? elementName : `MaterialX_${materialNodeNameOrIndex}`,
             shaderName: null, //shaderInfo?.originalName || shaderInfo?.name || null,
             shader,
             context: context || {},
+            environmentRadianceMode: options?.environmentRadianceMode,
+            specularAntialiasing: options?.specularAntialiasing,
             parameters: {
-                // MASK mode: no GL blending (discard handles cutout), BLEND mode: GL blending
-                transparent: isBlend,
+                // MASK uses discard; BLEND uses Three.js transparent sorting and blending.
+                transparent: renderAsTransparent,
                 // For MASK mode, set alphaTest so Three.js enables alpha testing
                 alphaTest: isMask ? 0.0001 : 0,
                 ...options?.parameters,
             },
             loaders: loaders,
         });
+        await shaderMaterial.ready;
 
         // Add debugging to see if the material compiles correctly
         if (debug) console.log("[MaterialX]  material created:", shaderMaterial.name);

package/src/materialx.d.ts

@@ -34,13 +34,14 @@ export type MaterialXContext = {
 type EnvironmentTextureSet = {
     radianceTexture: Texture | null;
     irradianceTexture: Texture | null;
+    dispose?: () => void;
 }
 
 export declare const state: {
     materialXModule: MX.MODULE | null;
-    materialXGenerator: any | null;
-    materialXGenContext: any | null;
-    materialXStdLib: any | null;
+    materialXGenerator: MX.MODULE["HwShaderGenerator"] | null;
+    materialXGenContext: MX.GenContext | null;
+    materialXStdLib: MX.StandardLibrary | null;
     materialXInitPromise: Promise<void> | null;
 };
 
@@ -83,8 +84,11 @@ export declare class MaterialXEnvironment {
 
     private _pmremGenerator: any | null;
     private _renderer: WebGLRenderer | null;
-    private _texturesCache: Map<Texture | null, EnvironmentTextureSet>;
+    private _texturesCache: Map<Texture | null, Map<string, EnvironmentTextureSet>>;
     private _initialize(renderer: WebGLRenderer): Promise<boolean>;
-    private _getTextures(texture: Texture | null | undefined): EnvironmentTextureSet;
+    private _getTextures(texture: Texture | null | undefined, radianceMode?: MaterialXEnvironmentRadianceMode): EnvironmentTextureSet;
+    private _getPMREMGenerator(): any;
     private updateLighting(collectLights?: boolean): void;
 }
+
+export type MaterialXEnvironmentRadianceMode = "three-pmrem" | "materialx-prefiltered" | "materialx-fis";

package/src/materialx.helper.d.ts

@@ -28,6 +28,6 @@ export function registerLights(mx: any, genContext: any): Promise<void>;
 
 export function getLightData(lights: Array<THREE.Light>, genContext: any): { lightData: LightData[], lightCount: number };
 
-export function getUniformValues(shaderStage: any, loaders: Callbacks, searchPath: string): Record<string, THREE.Uniform>;
+export function getUniformValues(shaderStage: any, loaders?: Callbacks, searchPath?: string): Record<string, THREE.Uniform>;
 
 export function generateMaterialPropertiesForUniforms(material: THREE.ShaderMaterial, shaderStage: any): void;

package/src/materialx.helper.js

@@ -36,17 +36,11 @@ export function prepareEnvTexture(texture, capabilities) {
  * @returns {Array<number>}
  */
 function fromVector(value, dimension) {
-    let outValue;
-    if (value) {
-        outValue = [...value.data()];
-    }
-    else {
-        outValue = [];
-        for (let i = 0; i < dimension; ++i)
-            outValue.push(0.0);
-    }
-
-    return outValue;
+    if (!value) return Array(dimension).fill(0.0);
+    if (typeof value.data === "function") return [...value.data()];
+    if (typeof value.getData === "function") return fromVector(value.getData(), dimension);
+    if (typeof value !== "string" && typeof value[Symbol.iterator] === "function") return [...value];
+    return Array(dimension).fill(0.0);
 }
 
 /**
@@ -56,7 +50,7 @@ function fromVector(value, dimension) {
  * @returns {Array<number>}
  */
 function fromMatrix(matrix, dimension) {
-    const vec = new Array(dimension);
+    const vec = [];
     if (matrix) {
         for (let i = 0; i < matrix.numRows(); ++i) {
             for (let k = 0; k < matrix.numColumns(); ++k) {
@@ -125,9 +119,10 @@ function addToCache(key, value) {
  * @param {string} name
  * @param {Callbacks} loaders
  * @param {string} searchPath
+ * @param {Array<Promise<unknown>>} [pendingTextureLoads]
  * @returns {THREE.Uniform}
  */
-function toThreeUniform(uniforms, type, value, name, loaders, searchPath) {
+function toThreeUniform(threeUniforms, uniforms, type, value, name, loaders, searchPath, pendingTextureLoads) {
 
     const uniform = new THREE.Uniform(/** @type {any} */(null));
 
@@ -178,13 +173,22 @@ function toThreeUniform(uniforms, type, value, name, loaders, searchPath) {
                 if (cacheValue) {
                     if (debug) console.log('[MaterialX] Use cached texture: ', cacheKey, cacheValue);
                     if (cacheValue instanceof Promise) {
-                        cacheValue.then(res => {
-                            if (res) uniform.value = res;
+                        const trackedLoad = cacheValue.then(res => {
+                            if (res) {
+                                uniform.value = res;
+                                if (threeUniforms[name + "_flipY"]) threeUniforms[name + "_flipY"].value = !!res.flipY;
+                            }
                             else console.warn(`[MaterialX] Failed to load texture ${name} '${texturePath}'`);
+                            return res;
+                        }).catch(err => {
+                            console.error(`[MaterialX] Failed to load texture ${name} '${texturePath}'`, err);
+                            return null;
                         });
+                        pendingTextureLoads?.push(trackedLoad);
                     }
                     else {
                         uniform.value = cacheValue;
+                        if (threeUniforms[name + "_flipY"]) threeUniforms[name + "_flipY"].value = !!cacheValue.flipY;
                     }
                 }
                 else {
@@ -197,9 +201,9 @@ function toThreeUniform(uniforms, type, value, name, loaders, searchPath) {
                     const promise = loaders.getTexture(texturePath)
                         ?.then(res => {
                             if (res) {
-                                res = res.clone(); // we need to clone the texture once to avoid colorSpace issues with other materials
                                 res.colorSpace = THREE.LinearSRGBColorSpace;
                                 setTextureParameters(res, name, uniforms);
+                                res.needsUpdate = true;
                             }
                             return res;
                         })
@@ -210,15 +214,21 @@ function toThreeUniform(uniforms, type, value, name, loaders, searchPath) {
 
                     if (checkCache) addToCache(cacheKey, promise);
 
-                    promise?.then(res => {
+                    const trackedLoad = promise?.then(res => {
                         // Replace Promise cache entry with the resolved texture value.
                         // This avoids keeping long-lived promise/closure graphs in THREE.Cache.
                         if (checkCache && res) addToCache(cacheKey, res);
-                        if (res) uniform.value = /** @type {any} */ (res);
+                        if (res) {
+                            uniform.value = /** @type {any} */ (res);
+                            if (threeUniforms[name + "_flipY"]) threeUniforms[name + "_flipY"].value = !!res.flipY;
+                        }
                         else console.warn(`[MaterialX] Failed to load texture ${name} '${texturePath}'`);
+                        return res;
                     });
+                    if (trackedLoad) pendingTextureLoads?.push(trackedLoad);
                 }
             }
+            threeUniforms[name + "_flipY"] = new THREE.Uniform(!!uniform.value?.flipY);
             break;
         case 'samplerCube':
         case 'string':
@@ -248,23 +258,69 @@ const valueTypeWarningMap = new Map();
  * @param {number} mode
  * @returns {THREE.Wrapping}
  */
+function getAddressMode(mode) {
+    if (typeof mode === "number") return mode;
+    switch (String(mode ?? "").toLowerCase()) {
+        case "constant":
+            return 0;
+        case "clamp":
+            return 1;
+        case "periodic":
+            return 2;
+        case "mirror":
+            return 3;
+        default:
+            return 2;
+    }
+}
+
+/**
+ * Get Three wrapping mode
+ * @param {unknown} mode
+ * @returns {THREE.Wrapping}
+ */
 function getWrapping(mode) {
-    let wrap;
-    switch (mode) {
+    switch (getAddressMode(mode)) {
+        case 0:
         case 1:
-            wrap = THREE.ClampToEdgeWrapping;
-            break;
-        case 2:
-            wrap = THREE.RepeatWrapping;
-            break;
+            return THREE.ClampToEdgeWrapping;
         case 3:
-            wrap = THREE.MirroredRepeatWrapping;
-            break;
+            return THREE.MirroredRepeatWrapping;
+        case 2:
         default:
-            wrap = THREE.RepeatWrapping;
-            break;
+            return THREE.RepeatWrapping;
+    }
+}
+
+/**
+ * @param {unknown} mode
+ * @returns {number}
+ */
+function getFilterType(mode) {
+    if (typeof mode === "number") return mode;
+    switch (String(mode ?? "").toLowerCase()) {
+        case "closest":
+            return 0;
+        case "linear":
+            return 1;
+        default:
+            return -1;
     }
-    return wrap;
+}
+
+/**
+ * @param {any} uniforms
+ * @param {string} name
+ * @param {any} defaultValue
+ * @returns {any}
+ */
+function getUniformData(uniforms, name, defaultValue) {
+    const uniform = uniforms?.find?.(name);
+    const value = uniform?.getValue?.();
+    if (!value) return defaultValue;
+    if (typeof value.getData === "function") return value.getData();
+    if (typeof value.data === "function") return value.data();
+    return defaultValue;
 }
 
 /**
@@ -278,22 +334,18 @@ function setTextureParameters(texture, name, uniforms, generateMipmaps = true) {
     const idx = name.lastIndexOf(IMAGE_PROPERTY_SEPARATOR);
     const base = name.substring(0, idx) || name;
 
-    if (uniforms.find(base + UADDRESS_MODE_SUFFIX)) {
-        const uaddressmode = uniforms.find(base + UADDRESS_MODE_SUFFIX).getValue().getData();
-        texture.wrapS = getWrapping(uaddressmode);
-    }
-
-    if (uniforms.find(base + VADDRESS_MODE_SUFFIX)) {
-        const vaddressmode = uniforms.find(base + VADDRESS_MODE_SUFFIX).getValue().getData();
-        texture.wrapT = getWrapping(vaddressmode);
-    }
+    texture.wrapS = getWrapping(getUniformData(uniforms, base + UADDRESS_MODE_SUFFIX, 2));
+    texture.wrapT = getWrapping(getUniformData(uniforms, base + VADDRESS_MODE_SUFFIX, 2));
 
-    const mxFilterType = uniforms.find(base + FILTER_TYPE_SUFFIX) ? uniforms.get(base + FILTER_TYPE_SUFFIX).value : -1;
+    const mxFilterType = getFilterType(getUniformData(uniforms, base + FILTER_TYPE_SUFFIX, -1));
     let minFilter = generateMipmaps ? THREE.LinearMipMapLinearFilter : THREE.LinearFilter;
+    let magFilter = THREE.LinearFilter;
     if (mxFilterType === 0) {
         minFilter = /** @type {any} */ (generateMipmaps ? THREE.NearestMipMapNearestFilter : THREE.NearestFilter);
+        magFilter = THREE.NearestFilter;
     }
     texture.minFilter = minFilter;
+    texture.magFilter = magFilter;
 }
 
 /**
@@ -528,9 +580,12 @@ export function getLightData(lights, genContext) {
  * @param {any} shaderStage
  * @param {Callbacks} loaders
  * @param {string} searchPath
+ * @param {Array<Promise<unknown>>} [pendingTextureLoads]
  * @returns {Object<string, THREE.Uniform>}
  */
-export function getUniformValues(shaderStage, loaders, searchPath) {
+export function getUniformValues(shaderStage, loaders, searchPath, pendingTextureLoads) {
+    loaders ??= { getTexture: async () => null };
+    searchPath ??= "";
     /** @type {Object<string, THREE.Uniform>} */
     const threeUniforms = {};
 
@@ -545,7 +600,7 @@ export function getUniformValues(shaderStage, loaders, searchPath) {
                 const value = variable.getValue()?.getData();
                 const uniformName = variable.getVariable();
                 const type = variable.getType().getName();
-                threeUniforms[uniformName] = toThreeUniform(uniforms, type, value, uniformName, loaders, searchPath);
+                threeUniforms[uniformName] = toThreeUniform(threeUniforms, uniforms, type, value, uniformName, loaders, searchPath, pendingTextureLoads);
                 if (debug) console.log("Adding uniform", { path: variable.getPath(), type: type, name: uniformName, value: threeUniforms[uniformName], },);
             }
         }