@needle-tools/materialx 1.2.2 → 1.3.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.3.0] - 2025-08-12
+- Change: Refactor extension to use a documents array instead of a single document, backwards compatibility is maintained
+
 ## [1.2.2] - 2025-07-24
 - Add: `preloadWasm` function with support to wait for network idle. This is automatically done for Needle Engine projects.
 

package/README.md

@@ -1,6 +1,63 @@
 # Needle MaterialX
 
-Web runtime support to load and display MaterialX materials in Needle Engine and three.js
+Web runtime support to load and display MaterialX materials in Needle Engine and three.js via the MaterialX WebAssembly library. glTF files containing the `NEEDLE_materials_mtlx` extension can be loaded with this package. There is also experimental support for loading raw MaterialX XML files.
+
+> [!TIP]
+> When using Needle Engine for Unity, this package can be added to your project via the Needle Engine component. Add it to the "NpmDef Dependencies" field. MaterialX files will then be automatically generated from compatible Shader Graphs with the "MaterialX" export type.    
+> [Learn more in the Needle Engine documentation](https://engine.needle.tools/docs/materialx.html).
+
+## Extension Design
+
+There is a root level glTF extension, `NEEDLE_materials_mtlx`, which contains an array of documents. Each document contains a MaterialX xml string, and information about textures and materials used in the document, so they can be resolved from inside the glTF buffers.
+
+The `textures` array is used to resolve texture paths from inside the MaterialX document to texture pointers in the glTF file.
+
+### Root-level extension
+```json
+{
+    ...
+    "extensions": {
+        "NEEDLE_materials_mtlx": {
+            "documents": [
+                {
+                    "name": "Perforated_Metal",
+                    "version": "1.38",
+                    "xml": "<?xml version='1.0' encoding='UTF-8'?><materialx version=\"1.38\">...</materialx>",
+                    "textures": [
+                        {
+                            "pointer": "/textures/0",
+                            "name": "Perforated_Metal_diffuse"
+                        },
+                        {
+                            "pointer": "/textures/1",
+                            "name": "Perforated_Metal_normal"
+                        }
+                    ],
+                    "shaders": [ // optional ]
+                }
+            ]
+        }
+    }
+}
+```
+
+### Material-level extension
+```json
+{
+    "materials": [
+        {
+            "name": "Perforated Metal",
+            "extensions": {
+                "NEEDLE_materials_mtlx": {
+                    "name": "Perforated_Metal",
+                    "document": 0,
+                    "shader": 0
+                }
+            }
+        }
+    ]
+}
+```
 
 ## Installation
 `npm i @needle-tools/materialx`  

package/package.json

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

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.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";