@needle-tools/materialx 1.1.0-next.0aa8b46 → 1.1.0-next.2d4dc5e

package/CHANGELOG.md

@@ -4,6 +4,9 @@ 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.1.0] - 2025-07-15
+- Add: `useNeedleMaterialX` hooks for vanilla three.js and Needle Engine
+
 ## [1.0.6] - 2025-07-15
 - Fix: texture/environment sampling on some Android devices
 

package/README.md

@@ -1,18 +1,32 @@
 # Needle MaterialX
 
-Web runtime support to load and display MaterialX materials in Needle Engine
+Web runtime support to load and display MaterialX materials in Needle Engine and three.js
 
 ## Installation
 `npm i @needle-tools/materialx`  
 
+## Examples
+- [three.js Example on Stackblitz](https://stackblitz.com/edit/needle-materialx-example?file=main.js,package.json,index.html)
+
 ## How to use
 
-To use with Needle Engine simply import the module
+### Use with Needle Engine
+
+```ts
+import { useNeedleMaterialX } from "@needle-tools/materialx/needle";
+// Simply call this function in global scope as soon as possible
+useNeedleMaterialX();
+```
+
+### Use with three.js
 
 ```ts
-import "@needle-tools/materialx"
+import { useNeedleMaterialX } from "@needle-tools/materialx";
+// Call the function with your GLTFLoader instance
+useNeedleMaterialX(<yourGltfLoaderInstance>);
 ```
 
+
 <br />
 
 # Contact ✒️

package/index.ts

@@ -1,2 +1,2 @@
 export * from "./src/index.js";
-export { addPluginForThree } from "./src/loader/loader.three.js";
+export { useNeedleMaterialX } from "./src/loader/loader.three.js";

package/needle.ts

@@ -1,2 +1,2 @@
 export * from "./src/index.js";
-export { addPluginForNeedleEngine } from "./src/loader/loader.needle.js";
+export { useNeedleMaterialX } from "./src/loader/loader.needle.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@needle-tools/materialx",
-  "version": "1.1.0-next.0aa8b46",
+  "version": "1.1.0-next.2d4dc5e",
   "type": "module",
   "main": "index.ts",
   "exports": {

package/src/loader/loader.needle.ts

@@ -2,7 +2,7 @@ import { addCustomExtensionPlugin } from "@needle-tools/engine";
 import { Context, GLTF, INeedleGLTFExtensionPlugin } from "@needle-tools/engine";
 import type { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader.js";
 import type { GLTFExporter } from "three/examples/jsm/exporters/GLTFExporter.js";
-import { addPluginForThree, MaterialXLoader } from "./loader.three.js";
+import { useNeedleMaterialX as _useNeedleMaterialX, MaterialXLoader } from "./loader.three.js";
 import { debug } from "../utils.js";
 import { MaterialParameters } from "three";
 
@@ -14,7 +14,7 @@ export class MaterialXLoaderPlugin implements INeedleGLTFExtensionPlugin {
 
     onImport = (loader: GLTFLoader, url: string, context: Context) => {
         if (debug) console.log("MaterialXLoaderPlugin: Registering MaterialX extension for", url);
-        addPluginForThree(loader, {
+        _useNeedleMaterialX(loader, {
             cacheKey: url,
             parameters: {
                 precision: context.renderer.capabilities.getMaxPrecision("highp") as MaterialParameters["precision"],
@@ -38,6 +38,6 @@ export class MaterialXLoaderPlugin implements INeedleGLTFExtensionPlugin {
 /**
  * Add the MaterialXLoaderPlugin to the Needle Engine.
  */
-export async function addPluginForNeedleEngine() {
+export async function useNeedleMaterialX() {
     addCustomExtensionPlugin(new MaterialXLoaderPlugin());
 }

package/src/loader/loader.three.ts

@@ -309,9 +309,9 @@ export class MaterialXLoader implements GLTFLoaderPlugin {
 
 
 /**
- * Add the MaterialXLoaderPlugin to the Needle Engine.
+ * Add the MaterialXLoader to the GLTFLoader instance.
  */
-export function addPluginForThree(loader: GLTFLoader, options?: MaterialXLoaderOptions, context?: MaterialXContext) {
+export function useNeedleMaterialX(loader: GLTFLoader, options?: MaterialXLoaderOptions, context?: MaterialXContext) {
     loader.register(p => {
         const loader = new MaterialXLoader(p, options || {}, context || {});
         return loader;

package/src/materialx.helper.ts

@@ -466,12 +466,57 @@ export function getUniformValues(shaderStage: MaterialX.ShaderStage, loaders: Lo
             for (let i = 0; i < uniforms.size(); ++i) {
                 const variable = uniforms.get(i);
                 const value = variable.getValue()?.getData();
-                const name = variable.getVariable();
-                if (debug) console.log("Adding uniform", { path: variable.getPath(), name: name, value: value, type: variable.getType().getName() });
-                threeUniforms[name] = toThreeUniform(uniforms, variable.getType().getName(), value, name, loaders, searchPath);
+                const uniformName = variable.getVariable();
+                const type = variable.getType().getName();
+                if (debug) console.log("Adding uniform", { path: variable.getPath(), name: uniformName, value: value, type: type });
+                threeUniforms[uniformName] = toThreeUniform(uniforms, type, value, uniformName, loaders, searchPath);
             }
         }
     }
 
     return threeUniforms;
 }
+
+export function generateMaterialPropertiesForUniforms(material: THREE.ShaderMaterial, shaderStage: MaterialX.ShaderStage) {
+
+    const uniformBlocks = shaderStage.getUniformBlocks()
+    for (const [blockName, uniforms] of Object.entries(uniformBlocks)) {
+        // Seems struct uniforms (like in LightData) end up here as well, we should filter those out.
+        if (blockName === "LightData") continue;
+
+        if (!uniforms.empty()) {
+            for (let i = 0; i < uniforms.size(); ++i) {
+                const variable = uniforms.get(i);
+                const uniformName = variable.getVariable();
+                let key = variable.getPath().split('/').pop();
+                switch (key) {
+                    case "_Color":
+                        key = "color";
+                        break;
+                    case "_Roughness":
+                        key = "roughness";
+                        break;
+                    case "_Metallic":
+                        key = "metalness";
+                        break;
+                }
+                if (key) {
+                    Object.defineProperty(material, key, {
+                        get: () => {
+                            return material.uniforms?.[uniformName].value
+                        },
+                        set: (v) => {
+                            const uniforms = material.uniforms;
+                            if (!uniforms || !uniforms[uniformName]) {
+                                console.warn(`[MaterialX] Uniform ${uniformName} not found in ${material.name} uniforms`);
+                                return;
+                            }
+                            material.uniforms[uniformName].value = v;
+                            material.uniformsNeedUpdate = true;
+                        }
+                    });
+                }
+            }
+        }
+    }
+}

package/src/materialx.material.ts

@@ -1,7 +1,7 @@
 import { BufferGeometry, Camera, FrontSide, GLSL3, Group, IUniform, MaterialParameters, Matrix3, Matrix4, Object3D, Scene, ShaderMaterial, Texture, Vector3, WebGLRenderer } from "three";
 import { debug, getFrame, getTime } from "./utils.js";
 import { MaterialXContext, MaterialXEnvironment } from "./materialx.js";
-import { getUniformValues, Loaders } from "./materialx.helper.js";
+import { generateMaterialPropertiesForUniforms, getUniformValues, Loaders } from "./materialx.helper.js";
 
 
 // Add helper matrices for uniform updates (similar to MaterialX example)
@@ -137,6 +137,7 @@ export class MaterialXMaterial extends ShaderMaterial {
             depthWrite: !isTransparent,
             defines: defines,
         });
+        this._context = init.context;
 
         Object.assign(this.uniforms, {
             ...getUniformValues(init.shader.getStage('vertex'), init.loaders, searchPath),
@@ -158,7 +159,9 @@ export class MaterialXMaterial extends ShaderMaterial {
             u_lightData: { value: [], needsUpdate: false }, // Array of light data. We need to set needsUpdate to false until we actually update it
         });
 
-        this._context = init.context;
+        generateMaterialPropertiesForUniforms(this, init.shader.getStage('pixel'));
+        generateMaterialPropertiesForUniforms(this, init.shader.getStage('vertex'));
+
 
         if (debug) {
             // Get lighting and environment data from MaterialX environment
@@ -216,7 +219,7 @@ export class MaterialXMaterial extends ShaderMaterial {
             if (frame === undefined) frame = getFrame();
             uniforms.u_frame.value = frame;
         }
-        
+
         // Update light uniforms
         this.updateEnvironmentUniforms(environment);