@needle-tools/materialx 1.2.1-next.bc1fa29 → 1.2.2-next.4c698a4

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.2.2] - 2025-07-24
+- Add: `preloadWasm` function with support to wait for network idle. This is automatically done for Needle Engine projects.
+
 ## [1.2.1] - 2025-07-23
 - Fix: error caused by scene.environment being null 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@needle-tools/materialx",
-  "version": "1.2.1-next.bc1fa29",
+  "version": "1.2.2-next.4c698a4",
   "type": "module",
   "main": "index.js",
   "types": "index.d.ts",

package/src/index.d.ts

@@ -1,4 +1,4 @@
-export { ready, type MaterialXContext } from "./materialx.js";
+export { ready, type MaterialXContext, preloadWasm } from "./materialx.js";
 export { MaterialXMaterial } from "./materialx.material.js";
 export { MaterialXLoader } from "./loader/loader.three.js";
 
@@ -10,5 +10,3 @@ declare const Experimental_API: {
 
 export { Experimental_API };
 
-
-export function preloadWasm(trigger: "immediately" | "network_idle"): Promise<void>;

package/src/index.js

@@ -1,38 +1,16 @@
 import { createMaterialXMaterial } from "./loader/loader.three.js";
-import { ready } from "./materialx.js";
-import { waitForNetworkIdle } from "./utils.js";
 
-
-export { ready } from "./materialx.js";
+export { ready, preloadWasm } from "./materialx.js";
 export { MaterialXMaterial } from "./materialx.material.js";
 export { MaterialXLoader } from "./loader/loader.three.js";
 
 
-/**
- * Preloads the MaterialX WebAssembly module.
- * @type {import("./index.js").preloadWasm}
- */
-export async function preloadWasm(trigger) {
-    if (trigger === "immediately") {
-        // Load the WASM module immediately
-        await ready();
-    } else if (trigger === "network_idle") {
-        // Wait for network to be idle before loading
-        await waitForNetworkIdle();
-        await ready();
-    }
-}
-
-
-
-
 /**
  * Experimental API for creating MaterialX materials.
  */
 const Experimental_API = {
     createMaterialXMaterial
-}
-
-export { Experimental_API }
+};
 
+export { Experimental_API };
 

package/src/loader/loader.needle.js

@@ -1,6 +1,7 @@
 import { addCustomExtensionPlugin, Context } from "@needle-tools/engine";
 import { useNeedleMaterialX as _useNeedleMaterialX } from "./loader.three.js";
 import { debug } from "../utils.js";
+import { preloadWasm } from "../materialx.js";
 
 /**
  * @typedef {import("@needle-tools/engine").INeedleGLTFExtensionPlugin} INeedleGLTFExtensionPlugin
@@ -58,5 +59,6 @@ export class MaterialXLoaderPlugin {
  * @returns {Promise<void>}
  */
 export async function useNeedleMaterialX() {
+    preloadWasm("network_idle");
     addCustomExtensionPlugin(new MaterialXLoaderPlugin());
 }

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

@@ -4,7 +4,7 @@ import { MaterialXContext } from "../materialx.js";
 import { MaterialXMaterial } from "../materialx.material.js";
 import { Callbacks } from "../materialx.helper.js";
 
-export interface MaterialX_root_extension {
+export interface MaterialX_root_document {
     /** e.g. 1.39 */
     version: string;
     /** e.g. "Material" */
@@ -21,9 +21,15 @@ export interface MaterialX_root_extension {
     }>;
 }
 
+export interface MaterialX_root_extension {
+    documents: Array<MaterialX_root_document>;
+}
+
 export interface MaterialX_material_extension {
     /** The MaterialX material name */
     name: string;
+    /** The index of the document in the documents array of the root extension. */
+    document?: number;
     /** The index of the shader in the shaders array of the root extension. */
     shader?: number;
 }

package/src/loader/loader.three.js

@@ -31,8 +31,17 @@ export class MaterialXLoader {
     /** @type {Promise<any> | null} */
     _documentReadyPromise = null;
 
+    /**
+     * @returns {MaterialX_root_extension | null}
+     */
     get materialX_root_data() {
-        return /** @type {MaterialX_root_extension | null} */ (this.parser.json.extensions?.[this.name]) || null;
+        const ext = this.parser.json.extensions?.[this.name];
+        let result = null;
+        if ("documents" in ext && Array.isArray(ext.documents))
+            result = ext.documents;
+        else
+            result = [ext];
+        return result;
     }
 
     /** Generated materialX materials */
@@ -85,8 +94,9 @@ export class MaterialXLoader {
         // Handle different types of MaterialX data
         /** @type {MaterialX_material_extension} */
         const ext = materialDef.extensions?.[this.name];
-
-        const mtlx = this.materialX_root_data?.mtlx;
+        const documentIndex = ext.document || 0;
+        const materialX_root_data = this.materialX_root_data?.[documentIndex];
+        const mtlx = materialX_root_data.mtlx || null;
 
         if (ext && mtlx) {
 
@@ -108,8 +118,8 @@ export class MaterialXLoader {
                     const filenameWithoutExt = url.split('/').pop()?.split('.').shift() || '';
 
                     // Resolve the texture from the MaterialX root extension
-                    if (this.materialX_root_data) {
-                        const textures = this.materialX_root_data.textures || [];
+                    if (materialX_root_data) {
+                        const textures = materialX_root_data.textures || [];
                         let index = -1;
                         for (const texture of textures) {
                             // Find the texture by name and use the pointer string to get the index
@@ -300,12 +310,6 @@ export async function createMaterialXMaterial(mtlx, materialNodeName, loaders, o
 
         const shader = state.materialXGenerator.generate(elementName, renderableElement, state.materialXGenContext);
 
-        // const rootExtension = this.materialX_root_data;
-
-        // const shaderInfo = rootExtension && material_extension.shader !== undefined && material_extension.shader >= 0
-        //     ? rootExtension.shaders?.[material_extension.shader]
-        //     : null;
-
         const shaderMaterial = new MaterialXMaterial({
             name: materialNodeName,
             shaderName: null, //shaderInfo?.originalName || shaderInfo?.name || null,

package/src/materialx.d.ts

@@ -1,6 +1,8 @@
 import { Light, Scene, Texture, WebGLRenderer } from "three";
 import type { MaterialX as MX } from "./materialx.types.js";
 
+export function preloadWasm(trigger: "immediately" | "network_idle"): Promise<void>;
+
 export type MaterialXContext = {
     getTime?(): number;
     getFrame?(): number;

package/src/materialx.js

@@ -1,10 +1,27 @@
 import MaterialX from "../bin/JsMaterialXGenShader.js";
-import { debug } from "./utils.js";
+import { debug, waitForNetworkIdle } from "./utils.js";
 import { renderPMREMToEquirect } from "./utils.texture.js";
 import { Light, Mesh, MeshBasicMaterial, Object3D, PlaneGeometry, PMREMGenerator, Scene, Texture, WebGLRenderer } from "three";
 import { registerLights, getLightData } from "./materialx.helper.js";
 import { whiteTexture } from "./utils.texture.js";
 
+
+/**
+ * Preloads the MaterialX WebAssembly module.
+ * @type {import("./materialx.js").preloadWasm}
+ */
+export async function preloadWasm(trigger) {
+    if (trigger === "immediately") {
+        // Load the WASM module immediately
+        return ready();
+    } else if (trigger === "network_idle") {
+        // Wait for network to be idle before loading
+        return waitForNetworkIdle().then(ready);
+    }
+}
+
+
+
 export const state = new class {
     /** @type {import("./materialx.types.js").MaterialX.MODULE | null} */
     materialXModule = null;

package/src/materialx.material.js

@@ -87,6 +87,11 @@ export class MaterialXMaterial extends ShaderMaterial {
         vertexShader = vertexShader.replace(/\bi_texcoord_3\b/g, 'uv3');
         vertexShader = vertexShader.replace(/\bi_tangent\b/g, 'tangent');
         vertexShader = vertexShader.replace(/\bi_color_0\b/g, 'color');
+        // TODO: do we need to add depthbuffer fragments? https://discourse.threejs.org/t/shadermaterial-render-order-with-logarithmicdepthbuffer-is-wrong/49221/4
+        // Add logdepthbuf_pars_vertex at the beginning of the vertex shader before main()
+        // vertexShader = vertexShader.replace(/void\s+main\s*\(\s*\)\s*{/, `#include <logdepthbuf_pars_vertex>\nvoid main() {`);
+        // // Add logdepthbuf_vertex to vertex shader if not present at end of main()
+        // vertexShader = vertexShader.replace(/void\s+main\s*\(\s*\)\s*{/, `void main() {\n    #include <logdepthbuf_vertex>\n`);
 
         // Patch fragmentShader
         const precision = init.parameters?.precision || "highp";