@needle-tools/materialx 1.0.0 → 1.0.1-next.2ca9014

package/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+All notable changes to this package will be documented in this file.
+
+The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
+and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
+
+## [1.0.1] - 2025-07-08
+- Initial release

package/README.md

@@ -1 +1,23 @@
+# Needle MaterialX
+
+## Installation
+`npm i @needle-tools/materialx@stable`  
+
+## How to use
+
+To use with Needle Engine simply import the module
+
+```ts
+import "@needle-tools/materialx"
+```
+
+<br />
+
+# Contact ✒️
+<b>[🌵 Needle](https://needle.tools)</b> • 
+[Github](https://github.com/needle-tools) • 
+[Twitter](https://twitter.com/NeedleTools) • 
+[Discord](https://discord.needle.tools) • 
+[Forum](https://forum.needle.tools) • 
+[Youtube](https://www.youtube.com/@needle-tools)
 

package/package.json

@@ -1,20 +1,38 @@
 {
   "name": "@needle-tools/materialx",
-  "version": "1.0.0",
+  "version": "1.0.1-next.2ca9014",
   "type": "module",
   "main": "index.ts",
-  "dependencies": {},
+  "exports": {
+    ".": {
+      "import": "./index.ts",
+      "require": "./index.js"
+    },
+    "./package.json": "./package.json"
+  },
   "peerDependencies": {
     "@needle-tools/engine": "4.x",
     "three": "npm:@needle-tools/three@^0.169.5"
   },
   "devDependencies": {
     "@needle-tools/engine": "4.x",
+    "@types/three": "0.169.0",
     "three": "npm:@needle-tools/three@^0.169.5",
-    "@types/three": "0.169.0"
+    "vite": "^7.0.3"
   },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
-  }
+  },
+  "keywords": [
+    "needle",
+    "materialx",
+    "material",
+    "shader",
+    "threejs",
+    "three.js",
+    "webgl",
+    "mtlx",
+    "rendering"
+  ]
 }

package/src/helper.js

@@ -3,7 +3,7 @@
 // SPDX-License-Identifier: Apache-2.0
 //
 
-import { getParam } from '@needle-tools/engine';
+import { getParam, getWorldDirection } from '@needle-tools/engine';
 import * as THREE from 'three';
 
 const debug = getParam("debugmaterialx");
@@ -301,10 +301,14 @@ export function findLights(doc)
 export async function registerLights(mx, lights, genContext)
 {
     mx.HwShaderGenerator.unbindLightShaders(genContext);
+    // TODO Remove, not sure why we need that – something resets the value inbetween calls to registerLights
+    genContext.getOptions().hwMaxActiveLightSources = 4;
 
     const lightTypesBound = {};
     const lightData = [];
     let lightId = 1;
+    let lightCount = 0;
+    const maxLightCount = genContext.getOptions().hwMaxActiveLightSources;
 
     // All light types so that we have NodeDefs for them
     const defaultLightRigXml = `<?xml version="1.0"?>
@@ -331,6 +335,9 @@ export async function registerLights(mx, lights, genContext)
     const defaultLights = findLights(document);
     if (debug) console.log("Default lights in MaterialX document", defaultLights);
 
+    // Loading a document seems to reset this option for some reason, so we set it again
+    genContext.getOptions().hwMaxActiveLightSources = maxLightCount;
+
     // Register types only – we get these from the default light rig XML above
     // This is needed to ensure that the light shaders are bound for each light type
     for (let light of defaultLights)
@@ -414,18 +421,44 @@ export async function registerLights(mx, lights, genContext)
             mx.HwShaderGenerator.bindLightShader(nodeDef, lightId++, genContext);
         }
 
+        const wp = light.getWorldPosition(new THREE.Vector3());
+        const wd = getWorldDirection(light, new THREE.Vector3(0,0,-1));
         lightData.push({
             type: lightTypesBound[lightDefinitionName],
-            direction: light.direction?.clone() || new THREE.Vector3(0, -1, 0),
+            position: wp.clone(),
+            direction: wd.clone(),
             color: new THREE.Vector3().fromArray(light.color.toArray()),
-            intensity: light.intensity,
+            intensity: light.intensity, // Scale intensity for spot lights
+            decay_rate: 2.0, // physically-based default decay rate
+            inner_angle: 1.0,
+            outer_angle: 2.0,
         });
     }
 
-    // Make sure max light count is large enough
-    genContext.getOptions().hwMaxActiveLightSources = Math.max(genContext.getOptions().hwMaxActiveLightSources, lightData.length);
+    // Count the number of lights that are not empty
+    lightCount = lightData.length;
+
+    // If we don't have enough entries in lightData, fill with empty lights
+    if (lightData.length < maxLightCount)
+    {
+        const emptyLight = {
+            type: 0, // Default light type
+            position: new THREE.Vector3(0, 0, 0),
+            direction: new THREE.Vector3(0, 0, -1),
+            color: new THREE.Vector3(0, 0, 0),
+            intensity: 0,
+            decay_rate: 2,
+            inner_angle: 0,
+            outer_angle: 0,
+        };
+        while (lightData.length < maxLightCount) {
+            lightData.push(emptyLight);
+        }
+    }
+
+    if (debug) console.log("Registered lights in MaterialX context", lightTypesBound, lightData);
 
-    return lightData;
+    return { lightData, lightCount };
 }
 
 /**

package/src/loader/loader.three.ts

@@ -1,5 +1,5 @@
 import { Context } from "@needle-tools/engine";
-import { RawShaderMaterial, Material, MeshStandardMaterial, LoadingManager, TextureLoader, Texture, NearestFilter, Matrix4, GLSL3, AddEquation, OneMinusSrcAlphaFactor, SrcAlphaFactor, DoubleSide, Matrix3, Vector3, Object3D, Camera } from "three";
+import { ShaderMaterial, Material, MeshStandardMaterial, LoadingManager, TextureLoader, Texture, NearestFilter, Matrix4, GLSL3, AddEquation, OneMinusSrcAlphaFactor, SrcAlphaFactor, DoubleSide, Matrix3, Vector3, Object3D, Camera } from "three";
 import { GLTFLoaderPlugin, GLTFParser } from "three/examples/jsm/loaders/GLTFLoader.js";
 import { getUniformValues } from "../helper.js";
 import { initializeMaterialX, MaterialXEnvironment, state } from "../materialx.js";
@@ -25,7 +25,7 @@ export class MaterialXLoader implements GLTFLoaderPlugin {
     private documentParsePromise: Promise<any> | null = null;
     private rootDataInitialized = false;
     private environmentInitialized = false;
-    private generatedMaterials: RawShaderMaterial[] = [];
+    private generatedMaterials: ShaderMaterial[] = [];
 
     constructor(private parser: GLTFParser, private context: Context) {
         if (debug) console.log("MaterialXLoader created for parser");
@@ -247,23 +247,23 @@ export class MaterialXLoader implements GLTFLoaderPlugin {
             // Check transparency and set context options like the reference
             let isTransparent = state.materialXModule.isTransparentSurface(renderableElement, state.materialXGenerator.getTarget());
             state.materialXGenContext.getOptions().hwTransparency = isTransparent;
-            state.materialXGenContext.getOptions().shaderInterfaceType = state.materialXModule.ShaderInterfaceType.SHADER_INTERFACE_COMPLETE;
-            state.materialXGenContext.getOptions().hwSrgbEncodeOutput = true; // Like the reference
-
+            
             // Generate shaders using the element's name path
             if (debug) console.log("Generating MaterialX shaders...");
             const elementName = (renderableElement as any).getNamePath ? (renderableElement as any).getNamePath() : (renderableElement as any).getName();
 
             const shader = state.materialXGenerator.generate(elementName, renderableElement, state.materialXGenContext);
 
-            // Get vertex and fragment shader source
-            // Remove #version directive for newer js. It's added by RawShaderMaterial glslVersion.
+            // Get vertex and fragment shader source, and remove #version directive for newer js. 
+            // It's added by three.js glslVersion.
             let vertexShader = shader.getSourceCode("vertex").replace(/^#version.*$/gm, '').trim();
             let fragmentShader = shader.getSourceCode("pixel").replace(/^#version.*$/gm, '').trim();
 
             // MaterialX uses different attribute names than js defaults,
             // so we patch the MaterialX shaders to match the js standard names.
-            // Otherwise, we'd have to modify the mesh attributes (see below).
+            // Otherwise, we'd have to modify the mesh attributes (see original MaterialX for reference).
+            
+            // Patch vertexShader
             vertexShader = vertexShader.replace(/\bi_position\b/g, 'position');
             vertexShader = vertexShader.replace(/\bi_normal\b/g, 'normal');
             vertexShader = vertexShader.replace(/\bi_texcoord_0\b/g, 'uv');
@@ -271,6 +271,7 @@ export class MaterialXLoader implements GLTFLoaderPlugin {
             vertexShader = vertexShader.replace(/\bi_tangent\b/g, 'tangent');
             vertexShader = vertexShader.replace(/\bi_color_0\b/g, 'color');
 
+            // Patch fragmentShader
             fragmentShader = fragmentShader.replace(/\bi_position\b/g, 'position');
             fragmentShader = fragmentShader.replace(/\bi_normal\b/g, 'normal');
             fragmentShader = fragmentShader.replace(/\bi_texcoord_0\b/g, 'uv');
@@ -278,16 +279,27 @@ export class MaterialXLoader implements GLTFLoaderPlugin {
             fragmentShader = fragmentShader.replace(/\bi_tangent\b/g, 'tangent');
             fragmentShader = fragmentShader.replace(/\bi_color_0\b/g, 'color');
 
-            // From the original code:
-
-            /* PATCHING THE SHADER IS BETTER – THIS IS JUST FOR REFERENCE 
-            // Use default MaterialX naming convention.
-            var startStreamTime = performance.now();
-            child.geometry.attributes.i_position = child.geometry.attributes.position;
-            child.geometry.attributes.i_normal = child.geometry.attributes.normal;
-            child.geometry.attributes.i_tangent = child.geometry.attributes.tangent;
-            child.geometry.attributes.i_texcoord_0 = child.geometry.attributes.uv;
-            */
+            // Remove `in vec3 position;` and so on since they're already declared by ShaderMaterial
+            vertexShader = vertexShader.replace(/in\s+vec3\s+position;/g, '');
+            vertexShader = vertexShader.replace(/in\s+vec3\s+normal;/g, '');
+            vertexShader = vertexShader.replace(/in\s+vec3\s+uv;/g, '');
+            vertexShader = vertexShader.replace(/in\s+vec3\s+uv1;/g, '');
+            vertexShader = vertexShader.replace(/in\s+vec4\s+tangent;/g, '');
+            vertexShader = vertexShader.replace(/in\s+vec4\s+color;/g, '');
+
+            // Patch uv 2-component to 3-component (`texcoord_0 = uv;` needs to be replaced with `texcoord_0 = vec3(uv, 0.0);`)
+            // TODO what if we actually have a 3-component UV? Not sure what three.js does then
+            vertexShader = vertexShader.replace(/texcoord_0 = uv;/g, 'texcoord_0 = vec3(uv, 0.0);');
+
+            // Add tonemapping and colorspace handling
+            // Replace `out vec4 out1;` with `out vec4 gl_FragColor;`
+            fragmentShader = fragmentShader.replace(/out\s+vec4\s+out1;/, 'layout(location = 0) out vec4 pc_fragColor;\n#define gl_FragColor pc_fragColor');
+            // Replace `out1 = vec4(<CAPTURE>)` with `gl_FragColor = vec4(<CAPTURE>)` and tonemapping/colorspace handling
+            fragmentShader = fragmentShader.replace(/^\s*out1\s*=\s*vec4\((.*)\);/gm,
+            `
+    gl_FragColor = vec4($1);
+    #include <tonemapping_fragment>
+    #include <colorspace_fragment>`);
 
             if (debug) {
                 console.group("Material: ", materialXData.name);
@@ -402,7 +414,7 @@ export class MaterialXLoader implements GLTFLoaderPlugin {
             // console.log("Generated fragment shader:", fragmentShader.substring(0, 500) + "...");
 
             // Create js RawShaderMaterial (with GLSL3 for MaterialX compatibility)
-            const shaderMaterial = new RawShaderMaterial({
+            const shaderMaterial = new ShaderMaterial({
                 uniforms: uniforms,
                 vertexShader: vertexShader,
                 fragmentShader: fragmentShader,
@@ -499,8 +511,8 @@ export class MaterialXLoader implements GLTFLoaderPlugin {
     updateLightingFromEnvironment(environment: MaterialXEnvironment): void {
 
         // Get lighting data from environment
-        // const lights = environment.getLights() || [];
         const lightData = environment.getLightData() || null;
+        const lightCount = environment.getLightCount() || 0;
         const radianceTexture = environment.getRadianceTexture() || null;
         const irradianceTexture = environment.getIrradianceTexture() || null;
 
@@ -513,8 +525,8 @@ export class MaterialXLoader implements GLTFLoaderPlugin {
             if (!material.uniforms) return;
 
             // Update light count
-            if (material.uniforms.u_numActiveLightSources && lightData) {
-                material.uniforms.u_numActiveLightSources.value = lightData.length;
+            if (material.uniforms.u_numActiveLightSources && lightCount >= 0) {
+                material.uniforms.u_numActiveLightSources.value = lightCount;
             }
 
             // Update light data if we have lights
@@ -523,6 +535,7 @@ export class MaterialXLoader implements GLTFLoaderPlugin {
                     material.uniforms.u_lightData = { value: null };
                 }
                 material.uniforms.u_lightData.value = lightData;
+                if (debug) console.log("Updated light data for material", material.name, lightData, material.uniforms, );
             }
 
             // Update environment uniforms

package/src/materialx.ts

@@ -1,28 +1,10 @@
-import { Context, delay, isDevEnvironment, ObjectUtils } from "@needle-tools/engine";
+import { Context, delay, isDevEnvironment, ObjectUtils, GameObject } from "@needle-tools/engine";
 import MaterialX from "../bin/JsMaterialXGenShader.js";
 import { debug } from "./utils.js";
 import { renderPMREMToEquirect } from "./textureHelper.js";
 import { Light, MeshBasicMaterial, Object3D, PMREMGenerator } from "three";
 import { registerLights } from "./helper.js";
 
-// Configure MaterialX with the correct path for its data files
-const materialXConfig = {
-    locateFile: (path: string, scriptDirectory: string) => {
-        if (debug) console.debug("MaterialX locateFile called:", { path, scriptDirectory });
-
-        // Return the correct path for MaterialX data files
-        if (path.endsWith('.data') || path.endsWith('.wasm')) {
-            // For Vite dev server, we need to use the correct module path
-            const correctPath = new URL(`../bin/${path}`, import.meta.url).href;
-            if (debug) console.log("Resolved path:", correctPath);
-            return correctPath;
-        }
-        return scriptDirectory + path;
-    },
-    // Add buffer allocation to handle the data file properly
-    wasmBinary: null,
-    wasmMemory: null
-};
 
 // Global MaterialX module instance - initialized lazily
 export const state = new class {
@@ -40,7 +22,6 @@ export const state = new class {
     }
 }
 
-
 // Initialize MaterialX WASM module lazily
 export async function initializeMaterialX(): Promise<void> {
     if (state.materialXInitPromise) {
@@ -50,7 +31,34 @@ export async function initializeMaterialX(): Promise<void> {
         if (state.materialXModule) return; // Already initialized
         if (debug) console.log("Initializing MaterialX WASM module...");
         try {
-            const module = await MaterialX(materialXConfig);
+
+            const urls: Array<string> = await Promise.all([
+                /** @ts-ignore */
+                import(`../bin/JsMaterialXCore.wasm?url`).then(m => m.default || m),
+                /** @ts-ignore */
+                import(`../bin/JsMaterialXGenShader.wasm?url`).then(m => m.default || m),
+                /** @ts-ignore */
+                import(`../bin/JsMaterialXGenShader.data.txt?url`).then(m => m.default || m),
+            ]);
+            const [JsMaterialXCore, JsMaterialXGenShader, JsMaterialXGenShader_data] = urls;
+
+            const module = await MaterialX({
+                locateFile: (path: string, scriptDirectory: string) => {
+                    if (debug) console.debug("MaterialX locateFile called:", { path, scriptDirectory });
+
+                    if (path.includes("JsMaterialXCore.wasm")) {
+                        return JsMaterialXCore; // Use the URL for the core WASM file
+                    }
+                    else if (path.includes("JsMaterialXGenShader.wasm")) {
+                        return JsMaterialXGenShader; // Use the URL for the shader WASM file
+                    }
+                    else if (path.includes("JsMaterialXGenShader.data")) {
+                        return JsMaterialXGenShader_data; // Use the URL for the shader data file
+                    }
+
+                    return scriptDirectory + path;
+                },
+            });
             if (debug) console.log("MaterialXLoader module loaded", module);
             state.materialXModule = module;
 
@@ -63,16 +71,29 @@ export async function initializeMaterialX(): Promise<void> {
             state.materialXStdLib = module.loadStandardLibraries(state.materialXGenContext);
             tempDoc.setDataLibrary(state.materialXStdLib);
 
-            // Initialize basic lighting with default light rig
-            const defaultLightRigXml = `<?xml version="1.0"?>
-<materialx version="1.39">
-  <!-- Default directional light -->
-  <directional_light name="default_light" type="lightshader">
-    <input name="direction" type="vector3" value="0.0, -1.0, -0.5" />
-    <input name="color" type="color3" value="1.0, 1.0, 1.0" />
-    <input name="intensity" type="float" value="1.0" />
-  </directional_light>
-</materialx>`;
+            // TODO ShaderInterfaceType.SHADER_INTERFACE_REDUCED would be better, but doesn't actually seem to be supported in the MaterialX javascript bindings
+            const options = state.materialXGenContext.getOptions();
+            state.materialXGenContext.getOptions().shaderInterfaceType = state.materialXModule.ShaderInterfaceType.SHADER_INTERFACE_COMPLETE;
+            
+            // SPECULAR_ENVIRONMENT_NONE: Do not use specular environment maps.
+            // SPECULAR_ENVIRONMENT_FIS: Use Filtered Importance Sampling for specular environment/indirect lighting.
+            // SPECULAR_ENVIRONMENT_PREFILTER: Use pre-filtered environment maps for specular environment/indirect lighting.
+            state.materialXGenContext.getOptions().hwSpecularEnvironmentMethod = state.materialXModule.HwSpecularEnvironmentMethod.SPECULAR_ENVIRONMENT_FIS;
+            
+            // TRANSMISSION_REFRACTION: Use a refraction approximation for transmission rendering.
+            // TRANSMISSION_OPACITY: Use opacity for transmission rendering.
+            // state.materialXGenContext.getOptions().hwTransmissionRenderMethod = state.materialXModule.HwTransmissionRenderMethod.TRANSMISSION_REFRACTION;
+
+            // Turned off because we're doing color space conversion the three.js way
+            state.materialXGenContext.getOptions().hwSrgbEncodeOutput = false;
+
+            // Enables the generation of a prefiltered environment map.
+            // TODO Would be great to use but requires setting more uniforms (like u_envPrefilterMip).
+            // When set to true, the u_envRadiance map is expected to be a prefiltered environment map.
+            // state.materialXGenContext.getOptions().hwWriteEnvPrefilter = true;
+
+            // Set a reasonable default for max active lights
+            state.materialXGenContext.getOptions().hwMaxActiveLightSources = 4;
 
             // This prewarms the shader generation context to have all light types
             await registerLights(state.materialXModule, [], state.materialXGenContext);
@@ -87,8 +108,8 @@ export async function initializeMaterialX(): Promise<void> {
 
 // MaterialX Environment Manager - handles lighting and environment setup
 export class MaterialXEnvironment {
-    private lights: any[] = [];
     private lightData: any = null;
+    private lightCount: number = 0;
     private radianceTexture: any = null;
     private irradianceTexture: any = null;
     private context: Context | null = null;
@@ -102,18 +123,6 @@ export class MaterialXEnvironment {
         this.context = context;
     }
 
-    /*
-    // Initialize MaterialX lighting system based on the reference implementation
-    async initializeLighting(lightRigXml: string, renderer?: any, radianceTexture?: any, irradianceTexture?: any): Promise<void> {
-        if (!materialXModule || !materialXGenContext) {
-            console.warn("MaterialX module not initialized, skipping lighting setup");
-            return;
-        }
-
-        registerLights(materialXModule, this.lights, materialXGenContext);
-    }
-    */
-
     // Initialize with Needle Engine context
     async initializeFromContext(): Promise<void> {
         if (!this.context) {
@@ -185,17 +194,20 @@ export class MaterialXEnvironment {
         // Find lights in scene
         let lights = new Array<Light>();
         this.context.scene.traverse((object: Object3D) => {
-            if ((object as Light).isLight) lights.push(object as Light);
+            if ((object as Light).isLight && GameObject.isActiveInHierarchy(object))
+                lights.push(object as Light);
         });
 
-        this.lightData = await registerLights(state.materialXModule, lights, state.materialXGenContext);
+        const { lightData, lightCount } = await registerLights(state.materialXModule, lights, state.materialXGenContext);
+        this.lightData = lightData;
+        this.lightCount = lightCount;
 
         // Mark as initialized
         this.initialized = true;
     }
 
-    // getLights() { return this.lights; }
     getLightData() { return this.lightData; }
+    getLightCount() { return this.lightCount; }
     getRadianceTexture() { return this.radianceTexture; }
     getIrradianceTexture() { return this.irradianceTexture; }
 

package/bin/README.md

@@ -1,5 +0,0 @@
-Source: https://github.com/AcademySoftwareFoundation/MaterialX/tree/gh-pages
-
-Edits:
-
-- `JsMaterialXGenShader.js` added `export default MaterialX;` at bottom