@needle-tools/materialx 1.1.0-next.bc1b608 → 1.1.0

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.bc1b608",
+  "version": "1.1.0",
   "type": "module",
   "main": "index.ts",
   "exports": {
@@ -20,7 +20,7 @@
   },
   "peerDependencies": {
     "@needle-tools/engine": "4.x || ^4.6.0-0",
-    "three": "npm:@needle-tools/three@^0.169.5"
+    "three": ">=0.169.0"
   },
   "devDependencies": {
     "@needle-tools/engine": "4.x",
@@ -42,4 +42,4 @@
     "mtlx",
     "rendering"
   ]
-}
+}

package/src/loader/loader.needle.ts

@@ -2,8 +2,9 @@ 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";
 
 
 export class MaterialXLoaderPlugin implements INeedleGLTFExtensionPlugin {
@@ -13,13 +14,14 @@ 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"],
+            }
+        }, {
             getTime: () => context.time.time,
             getFrame: () => context.time.frame,
-            getScene: () => context.scene,
-            getRenderer: () => context.renderer,
-        }, {
-            cacheKey: url
         });
     };
 
@@ -36,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

@@ -1,4 +1,4 @@
-import { Material, MeshStandardMaterial, DoubleSide, FrontSide } from "three";
+import { Material, MeshStandardMaterial, DoubleSide, FrontSide, MaterialParameters } from "three";
 import { GLTFLoader, GLTFLoaderPlugin, GLTFParser } from "three/examples/jsm/loaders/GLTFLoader.js";
 import { ready, state, MaterialXContext } from "../materialx.js";
 import { debug } from "../utils.js";
@@ -28,6 +28,14 @@ type MaterialDefinition = {
     },
 }
 
+// init.context.getRenderer().capabilities.getMaxPrecision("highp")
+export type MaterialXLoaderOptions = {
+    /** The URL of the GLTF file being loaded */
+    cacheKey?: string;
+    /** Parameters for the MaterialX loader */
+    parameters?: Pick<MaterialParameters, "precision">;
+}
+
 // MaterialX loader extension for js GLTFLoader
 export class MaterialXLoader implements GLTFLoaderPlugin {
     readonly name = "NEEDLE_materials_mtlx";
@@ -51,7 +59,11 @@ export class MaterialXLoader implements GLTFLoaderPlugin {
      * @param cacheKey The URL of the GLTF file
      * @param context The context for the GLTF loading process
      */
-    constructor(private parser: GLTFParser, private cacheKey: string, private context: MaterialXContext) {
+    constructor(
+        private parser: GLTFParser,
+        private options: MaterialXLoaderOptions,
+        private context: MaterialXContext
+    ) {
         if (debug) console.log("MaterialXLoader created for parser");
         // Start loading of MaterialX environment if the root extension exists
         if (this.materialX_root_data) {
@@ -233,8 +245,9 @@ export class MaterialXLoader implements GLTFLoaderPlugin {
                 transparent: isTransparent,
                 side: material_def.doubleSided ? DoubleSide : FrontSide,
                 context: this.context,
+                precision: this.options.parameters?.precision,
                 loaders: {
-                    cacheKey: this.cacheKey,
+                    cacheKey: this.options.cacheKey || "",
                     getTexture: async url => {
                         // Find the index of the texture in the parser
                         const filenameWithoutExt = url.split('/').pop()?.split('.').shift() || '';
@@ -296,11 +309,11 @@ export class MaterialXLoader implements GLTFLoaderPlugin {
 
 
 /**
- * Add the MaterialXLoaderPlugin to the Needle Engine.
+ * Add the MaterialXLoader to the GLTFLoader instance.
  */
-export function addPluginForThree(loader: GLTFLoader, context: MaterialXContext, options: { cacheKey?: string } = {}) {
+export function useNeedleMaterialX(loader: GLTFLoader, options?: MaterialXLoaderOptions, context?: MaterialXContext) {
     loader.register(p => {
-        const loader = new MaterialXLoader(p, options.cacheKey || "", context);
+        const loader = new MaterialXLoader(p, options || {}, context || {});
         return loader;
     });
 }

package/src/materialx.material.ts

@@ -1,22 +1,22 @@
 import { BufferGeometry, Camera, FrontSide, GLSL3, Group, IUniform, MaterialParameters, Matrix3, Matrix4, Object3D, Scene, ShaderMaterial, Texture, Vector3, WebGLRenderer } from "three";
-import { debug } from "./utils.js";
+import { debug, getFrame, getTime } from "./utils.js";
 import { MaterialXContext, MaterialXEnvironment } from "./materialx.js";
 import { getUniformValues, Loaders } from "./materialx.helper.js";
 
 
 // Add helper matrices for uniform updates (similar to MaterialX example)
-const identityMatrix = new Matrix4();
 const normalMat = new Matrix3();
-const viewProjMat = new Matrix4();
 const worldViewPos = new Vector3();
 
 declare type MaterialXMaterialInitParameters = {
     name: string,
     shader: any,
     loaders: Loaders,
+    context: MaterialXContext,
+    // Optional parameters
     transparent?: boolean,
     side?: MaterialParameters['side'],
-    context: MaterialXContext,
+    precision?: MaterialParameters['precision'],
 }
 
 type Uniforms = Record<string, IUniform & { needsUpdate?: boolean }>;
@@ -63,7 +63,7 @@ export class MaterialXMaterial extends ShaderMaterial {
         vertexShader = vertexShader.replace(/\bi_color_0\b/g, 'color');
 
         // Patch fragmentShader
-        const precision = init.context.getRenderer().capabilities.getMaxPrecision("highp") as Precision;
+        const precision = init.precision || "highp" as Precision;
         fragmentShader = fragmentShader.replace(/precision mediump float;/g, `precision ${precision} float;`);
         fragmentShader = fragmentShader.replace(/#define M_FLOAT_EPS 1e-8/g, precision === "highp" ? `#define M_FLOAT_EPS 1e-8` : `#define M_FLOAT_EPS 1e-3`);
 
@@ -170,19 +170,19 @@ export class MaterialXMaterial extends ShaderMaterial {
     }
 
     onBeforeRender(_renderer: WebGLRenderer, _scene: Scene, camera: Camera, _geometry: BufferGeometry, object: Object3D, _group: Group): void {
-        if (this._context) {
-            const env = MaterialXEnvironment.get(this._context);
-            if (env) {
-                env.update(this._context.getFrame(), this._context.getScene());
-                this.updateUniforms(env, object, camera);
-            }
+        const time = this._context?.getTime?.() || getTime();
+        const frame = this._context?.getFrame?.() || getFrame();
+        const env = MaterialXEnvironment.get(_scene);
+        if (env) {
+            env.update(frame, _scene, _renderer);
+            this.updateUniforms(env, object, camera, time, frame);
         }
     }
 
 
     envMapIntensity: number = 1.0; // Default intensity for environment map
     envMap: Texture | null = null; // Environment map texture, can be set externally
-    updateUniforms = (environment: MaterialXEnvironment, object: Object3D, camera: Camera) => {
+    updateUniforms = (environment: MaterialXEnvironment, object: Object3D, camera: Camera, time?: number, frame?: number) => {
 
         const uniforms = this.uniforms as Uniforms;
 
@@ -208,15 +208,15 @@ export class MaterialXMaterial extends ShaderMaterial {
         }
 
         // Update time uniforms
-        if (this._context) {
-            if (uniforms.u_time) {
-                uniforms.u_time.value = this._context.getTime();
-            }
-            if (uniforms.u_frame) {
-                uniforms.u_frame.value = this._context.getFrame();
-            }
+        if (uniforms.u_time) {
+            if (time === undefined) time = getTime();
+            uniforms.u_time.value = time;
         }
-
+        if (uniforms.u_frame) {
+            if (frame === undefined) frame = getFrame();
+            uniforms.u_frame.value = frame;
+        }
+        
         // Update light uniforms
         this.updateEnvironmentUniforms(environment);
 

package/src/materialx.ts

@@ -7,10 +7,8 @@ import { registerLights, getLightData, LightData } from "./materialx.helper.js";
 import type { MaterialXMaterial } from "./materialx.material.js";
 
 export type MaterialXContext = {
-    getTime(): number,
-    getFrame(): number,
-    getScene(): Scene,
-    getRenderer(): WebGLRenderer,
+    getTime?(): number,
+    getFrame?(): number,
 }
 
 
@@ -114,23 +112,21 @@ type EnvironmentTextureSet = {
 }
 
 
-
-type EnvironmentContext = Pick<MaterialXContext, "getRenderer" | "getScene">;
 /**
  * MaterialXEnvironment manages the environment settings for MaterialX materials.
  */
 export class MaterialXEnvironment {
 
-    static get(context: EnvironmentContext): MaterialXEnvironment | null {
-        return this.getEnvironment(context);
+    static get(scene: Scene): MaterialXEnvironment | null {
+        return this.getEnvironment(scene);
     }
-    private static _environments: WeakMap<EnvironmentContext, MaterialXEnvironment> = new Map();
-    private static getEnvironment(context: EnvironmentContext): MaterialXEnvironment {
-        if (this._environments.has(context)) {
-            return this._environments.get(context)!;
+    private static _environments: WeakMap<Scene, MaterialXEnvironment> = new Map();
+    private static getEnvironment(scene: Scene): MaterialXEnvironment {
+        if (this._environments.has(scene)) {
+            return this._environments.get(scene)!;
         }
-        const env = new MaterialXEnvironment(context);
-        this._environments.set(context, env);
+        const env = new MaterialXEnvironment(scene);
+        this._environments.set(scene, env);
         return env;
     }
 
@@ -143,22 +139,22 @@ export class MaterialXEnvironment {
     private _isInitialized: boolean = false;
     private _lastUpdateFrame: number = -1;
 
-    constructor(private _context: EnvironmentContext) {
+    constructor(private _scene: Scene) {
         if (debug) console.log("[MaterialX] Environment created");
     }
 
     // Initialize with Needle Engine context
-    async initialize(): Promise<boolean> {
+    async initialize(renderer: WebGLRenderer): Promise<boolean> {
         if (this._initializePromise) {
             return this._initializePromise;
         }
-        this._initializePromise = this._initialize();
+        this._initializePromise = this._initialize(renderer);
         return this._initializePromise;
     }
 
-    update(frame: number, scene: Scene) {
+    update(frame: number, scene: Scene, renderer: WebGLRenderer): void {
         if (!this._initializePromise) {
-            this.initialize();
+            this.initialize(renderer);
             return;
         }
         if (!this._isInitialized) {
@@ -205,6 +201,7 @@ export class MaterialXEnvironment {
         this._lightCount = 0;
         this._pmremGenerator?.dispose();
         this._pmremGenerator = null;
+        this._renderer = null;
         for (const textureSet of this._texturesCache.values()) {
             textureSet.radianceTexture?.dispose();
             textureSet.irradianceTexture?.dispose();
@@ -221,15 +218,17 @@ export class MaterialXEnvironment {
             // If the material has its own envMap, we don't use the irradiance texture
             return this._getTextures(material.envMap);
         }
-        return this._getTextures(this._context?.getScene().environment);
+        return this._getTextures(this._scene.environment);
     }
 
     private _pmremGenerator: PMREMGenerator | null = null;
+    private _renderer: WebGLRenderer | null = null;
     private readonly _texturesCache: Map<Texture | null, EnvironmentTextureSet> = new Map();
 
-    private async _initialize(): Promise<boolean> {
+    private async _initialize(renderer: WebGLRenderer): Promise<boolean> {
         this._isInitialized = false;
-        this._pmremGenerator = new PMREMGenerator(this._context.getRenderer());
+        this._pmremGenerator = new PMREMGenerator(renderer);
+        this._renderer = renderer;
         this.updateLighting(true);
         this._isInitialized = true;
         return true;
@@ -244,11 +243,11 @@ export class MaterialXEnvironment {
             return res;
         }
 
-        if (this._context && this._pmremGenerator && texture) {
+        if (this._scene && this._pmremGenerator && this._renderer && texture) {
             if (debug) console.log("[MaterialX] Generating environment textures", texture.name);
             const target = this._pmremGenerator.fromEquirectangular(texture);
-            const radianceRenderTarget = renderPMREMToEquirect(this._context.getRenderer(), target.texture, 0.0, 1024, 512, target.height);
-            const irradianceRenderTarget = renderPMREMToEquirect(this._context.getRenderer(), target.texture, 1.0, 32, 16, target.height);
+            const radianceRenderTarget = renderPMREMToEquirect(this._renderer, target.texture, 0.0, 1024, 512, target.height);
+            const irradianceRenderTarget = renderPMREMToEquirect(this._renderer, target.texture, 1.0, 32, 16, target.height);
             target.dispose();
             res = {
                 radianceTexture: radianceRenderTarget.texture,
@@ -266,11 +265,11 @@ export class MaterialXEnvironment {
     }
 
     private updateLighting = (collectLights: boolean = false) => {
-        if (!this._context) return;
+        if (!this._scene) return;
         // Find lights in scene
         if (collectLights) {
             const lights = new Array<Light>();
-            this._context.getScene().traverse((object: Object3D) => {
+            this._scene.traverse((object: Object3D) => {
                 if ((object as Light).isLight && object.visible)
                     lights.push(object as Light);
             });

package/src/utils.ts

@@ -10,70 +10,20 @@ export const debug = getParam("debugmaterialx");
 export const debugUpdate = debug === "update";
 
 
-/**
- * =====================================
- * Unused
- */
-
-// Patch WebGL2 methods for debugging purposes
-
-// const patchWebGL2 = () => {
-//     const getUniformLocation = WebGL2RenderingContext.prototype.getUniformLocation;
-//     const programAndNameToUniformLocation = new WeakMap<WebGLUniformLocation, { program: WebGLProgram, name: string }>();
-//     WebGL2RenderingContext.prototype.getUniformLocation = function (program: WebGLProgram, name: string) {
-//         const location = getUniformLocation.call(this, program, name);
-//         if (location) {
-//             programAndNameToUniformLocation.set(location, { program, name });
-//         }
-//         return location;
-//     };
-
-//     const uniform4fv = WebGL2RenderingContext.prototype.uniform4fv;
-//     WebGL2RenderingContext.prototype.uniform4fv = function (location: WebGLUniformLocation | null, v: Float32Array | number[]) {
-//         if (location) {
-//             const uniformName = programAndNameToUniformLocation.get(location);
-//             if (true) console.log("Calling uniform4fv", { location, v, name: uniformName?.name });
-//         }
-//         return uniform4fv.call(this, location, v);
-//     };
-
-//     const uniform3fv = WebGL2RenderingContext.prototype.uniform3fv;
-//     WebGL2RenderingContext.prototype.uniform3fv = function (location: WebGLUniformLocation | null, v: Float32Array | number[]) {
-//         if (location) {
-//             const uniformName = programAndNameToUniformLocation.get(location);
-//             if (true) console.log("Calling uniform3fv", { location, v, name: uniformName?.name });
-//         }
-//         return uniform3fv.call(this, location, v);
-//     };
-
-//     const uniform3iv = WebGL2RenderingContext.prototype.uniform3iv;
-//     WebGL2RenderingContext.prototype.uniform3iv = function (location: WebGLUniformLocation | null, v: Int32Array | number[]) {
-//         if (location) {
-//             const uniformName = programAndNameToUniformLocation.get(location);
-//             if (true) console.log("Calling uniform3iv", { location, v, name: uniformName?.name });
-//         }
-//         return uniform3iv.call(this, location, v);
-//     };
-
-//     const uniform3uiv = WebGL2RenderingContext.prototype.uniform3uiv;
-//     WebGL2RenderingContext.prototype.uniform3uiv = function (location: WebGLUniformLocation | null, v: Uint32Array | number[]) {
-//         if (location) {
-//             const uniformName = programAndNameToUniformLocation.get(location);
-//             if (true) console.log("Calling uniform3uiv", { location, v, name: uniformName?.name });
-//         }
-//         return uniform3uiv.call(this, location, v);
-//     };
+let time = 0;
+export function getTime() {
+    return time;
+}
+let frame = 0;
+export function getFrame() {
+    return frame;
+}
 
-//     const uniform3f = WebGL2RenderingContext.prototype.uniform3f;
-//     WebGL2RenderingContext.prototype.uniform3f = function (location: WebGLUniformLocation
-//         | null, x: number, y: number, z: number) {
-//         if (location) {
-//             const uniformName = programAndNameToUniformLocation.get(location);
-//             if (uniformName?.name !== "diffuse")
-//                 if (true) console.log("Calling uniform3f", { location, x, y, z, name: uniformName?.name });
-//         }
-//         return uniform3f.call(this, location, x, y, z);
-//     };
-// };
-// // patchWebGL2();
+const performance = window.performance || (window as any).webkitPerformance || (window as any).mozPerformance;
+function updateTime() {
+    time = performance.now() / 1000; // Convert to seconds
+    frame++;
+    window.requestAnimationFrame(updateTime);
+}
+window.requestAnimationFrame(updateTime);