@needle-tools/materialx 1.1.1-next.623fc20 → 1.1.1-next.8e8afe1

package/bin/.gitattributes

@@ -0,0 +1,4 @@
+# ensure LF line endings
+*.data binary
+*.data.txt binary
+*.wasm binary

package/{index.ts → index.d.ts}

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

package/index.js

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

package/{needle.ts → needle.d.ts}

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

package/needle.js

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

package/package.json

@@ -1,21 +1,24 @@
 {
   "name": "@needle-tools/materialx",
-  "version": "1.1.1-next.623fc20",
+  "version": "1.1.1-next.8e8afe1",
   "type": "module",
-  "main": "index.ts",
+  "main": "index.js",
+  "types": "index.d.ts",
   "exports": {
     ".": {
-      "import": "./index.ts",
-      "require": "./index.js"
+      "import": "./index.js",
+      "require": "./index.js",
+      "types": "./index.d.ts"
+    },
+    "./needle": {
+      "import": "./needle.js",
+      "require": "./needle.js",
+      "types": "./needle.d.ts"
     },
     "./package.json": "./package.json",
     "./codegen/register_types.ts": {
       "import": "./codegen/register_types.ts",
       "require": "./codegen/register_types.js"
-    },
-    "./needle": {
-      "import": "./needle.ts",
-      "require": "./needle.js"
     }
   },
   "peerDependencies": {

package/src/index.d.ts

@@ -0,0 +1,11 @@
+export { ready, type MaterialXContext } from "./materialx.js";
+export { MaterialXMaterial } from "./materialx.material.js";
+export { MaterialXLoader } from "./loader/loader.three.js";
+
+import { createMaterialXMaterial } from "./loader/loader.three.js";
+
+declare const Experimental_API: {
+    createMaterialXMaterial: typeof createMaterialXMaterial;
+};
+
+export { Experimental_API };

package/src/index.js

@@ -0,0 +1,11 @@
+export { ready } from "./materialx.js";
+export { MaterialXMaterial } from "./materialx.material.js";
+export { MaterialXLoader } from "./loader/loader.three.js";
+
+import { createMaterialXMaterial } from "./loader/loader.three.js";
+
+const Experimental_API = {
+    createMaterialXMaterial
+}
+
+export { Experimental_API }

package/src/loader/loader.needle.d.ts

@@ -0,0 +1,15 @@
+import { Context, GLTF, INeedleGLTFExtensionPlugin } from "@needle-tools/engine";
+import { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader.js";
+import { GLTFExporter } from "three/examples/jsm/exporters/GLTFExporter.js";
+import { MaterialXLoader } from "./loader.three.js";
+
+export declare class MaterialXLoaderPlugin implements INeedleGLTFExtensionPlugin {
+    readonly name: "MaterialXLoaderPlugin";
+    private loader: MaterialXLoader | null;
+
+    onImport(loader: GLTFLoader, url: string, context: Context): void;
+    onLoaded(url: string, gltf: GLTF, _context: Context): void;
+    onExport(_exporter: GLTFExporter, _context: Context): void;
+}
+
+export declare function useNeedleMaterialX(): Promise<void>;

package/src/loader/loader.needle.js

@@ -0,0 +1,62 @@
+import { addCustomExtensionPlugin, Context } from "@needle-tools/engine";
+import { useNeedleMaterialX as _useNeedleMaterialX } from "./loader.three.js";
+import { debug } from "../utils.js";
+
+/**
+ * @typedef {import("@needle-tools/engine").INeedleGLTFExtensionPlugin} INeedleGLTFExtensionPlugin
+ */
+
+/**
+ * MaterialX Loader Plugin for Needle Engine
+ * @implements {INeedleGLTFExtensionPlugin}
+ */
+export class MaterialXLoaderPlugin {
+    /** @readonly */
+    name = "MaterialXLoaderPlugin";
+
+    /** @type {import("./loader.three.d.ts").MaterialXLoader | null} */
+    loader = null;
+
+    /**
+     * @param {import('three/examples/jsm/loaders/GLTFLoader.js').GLTFLoader} loader
+     * @param {string} url
+     * @param {Context} context
+     */
+    onImport = (loader, url, context) => {
+        if (debug) console.log("MaterialXLoaderPlugin: Registering MaterialX extension for", url);
+        _useNeedleMaterialX(loader, {
+            cacheKey: url,
+            parameters: {
+                precision: /** @type {import('three').MaterialParameters["precision"]} */ (context.renderer.capabilities.getMaxPrecision("highp")),
+            }
+        }, {
+            getTime: () => context.time.time,
+            getFrame: () => context.time.frame,
+        });
+    };
+
+    /**
+     * @param {string} url
+     * @param {import("@needle-tools/engine").GLTF} gltf
+     * @param {Context} _context
+     */
+    onLoaded = (url, gltf, _context) => {
+        if (debug) console.log("[MaterialX] MaterialXLoaderPlugin: glTF loaded", { url, scene: gltf.scene, materialX_root_data: this.loader?.materialX_root_data });
+    };
+
+    /**
+     * @param {import('three/examples/jsm/exporters/GLTFExporter.js').GLTFExporter} _exporter
+     * @param {Context} _context
+     */
+    onExport = (_exporter, _context) => {
+        console.warn("[MaterialX] Export is not supported");
+    };
+}
+
+/**
+ * Add the MaterialXLoaderPlugin to the Needle Engine.
+ * @returns {Promise<void>}
+ */
+export async function useNeedleMaterialX() {
+    addCustomExtensionPlugin(new MaterialXLoaderPlugin());
+}

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

@@ -0,0 +1,61 @@
+import { Material, MaterialParameters } from "three";
+import { GLTFLoader, GLTFLoaderPlugin, GLTFParser } from "three/examples/jsm/loaders/GLTFLoader.js";
+import { MaterialXContext } from "../materialx.js";
+import { MaterialXMaterial } from "../materialx.material.js";
+import { Callbacks } from "../materialx.helper.js";
+
+export interface MaterialX_root_extension {
+    version: string;
+    name: string;
+    mtlx: string;
+    textures: Array<{ name: string, pointer: string }>;
+    shaders?: Array<{
+        name: string;
+        originalName: string;
+    }>;
+}
+
+export interface MaterialX_material_extension {
+    name: string;
+    shader?: number;
+}
+
+export interface MaterialXLoaderOptions {
+    cacheKey?: string;
+    parameters?: Pick<MaterialParameters, "precision">;
+}
+
+export declare class MaterialXLoader implements GLTFLoaderPlugin {
+    readonly name: "NEEDLE_materials_mtlx";
+    private readonly _generatedMaterials: MaterialXMaterial[];
+    private _documentReadyPromise: Promise<any> | null;
+    private parser: GLTFParser;
+    private options: MaterialXLoaderOptions;
+    private context: MaterialXContext;
+
+    get materialX_root_data(): MaterialX_root_extension | null;
+    get materials(): MaterialXMaterial[];
+
+    constructor(
+        parser: GLTFParser,
+        options: MaterialXLoaderOptions,
+        context: MaterialXContext
+    );
+
+    loadMaterial(materialIndex: number): Promise<Material> | null;
+    private _loadMaterialAsync(materialIndex: number): Promise<Material>;
+}
+
+export declare function useNeedleMaterialX(
+    loader: GLTFLoader, 
+    options?: MaterialXLoaderOptions, 
+    context?: MaterialXContext
+): void;
+
+export declare function createMaterialXMaterial(
+    mtlx: string, 
+    materialNodeName: string, 
+    loaders: Callbacks, 
+    options?: MaterialXLoaderOptions, 
+    context?: MaterialXContext
+): Promise<Material>;

package/src/loader/loader.three.js

@@ -0,0 +1,351 @@
+import { Material, MeshStandardMaterial, DoubleSide, FrontSide } from "three";
+import { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader.js";
+import { ready, state } from "../materialx.js";
+import { debug } from "../utils.js";
+import { MaterialXMaterial } from "../materialx.material.js";
+
+/**
+ * @typedef {Object} MaterialX_root_extension
+ * @property {string} version - e.g. 1.39
+ * @property {string} name - e.g. "Material"  
+ * @property {string} mtlx - MaterialX xml content
+ * @property {Array<{name: string, pointer: string}>} textures - MaterialX texture pointers
+ * @property {Array<{name: string, originalName: string}>} [shaders] - MaterialX shaders
+ */
+
+/**
+ * @typedef {Object} MaterialX_material_extension
+ * @property {string} name - The MaterialX material name
+ * @property {number} [shader] - The index of the shader in the shaders array of the root extension
+ */
+
+/**
+ * @typedef {Object} MaterialDefinition
+ * @property {string} [name] - Optional name for the material
+ * @property {boolean} [doubleSided] - Whether the material is double-sided
+ * @property {Object<string, any>} [extensions] - Extensions for the material, including MaterialX
+ */
+
+/**
+ * @typedef {Object} MaterialXLoaderOptions
+ * @property {string} [cacheKey] - The URL of the GLTF file being loaded
+ * @property {import('three').MaterialParameters} [parameters] - Parameters for the MaterialX loader
+ */
+
+/**
+ * @typedef {Object} MaterialXMaterialOptions
+ * @property {import('three').MaterialParameters} [parameters]
+ */
+
+// MaterialX loader extension for js GLTFLoader
+export class MaterialXLoader {
+    /** @readonly */
+    name = "NEEDLE_materials_mtlx";
+
+    /** @type {MaterialXMaterial[]} */
+    _generatedMaterials = [];
+
+    /** @type {Promise<any> | null} */
+    _documentReadyPromise = null;
+
+    get materialX_root_data() {
+        return /** @type {MaterialX_root_extension | null} */ (this.parser.json.extensions?.[this.name]) || null;
+    }
+
+    /** Generated materialX materials */
+    get materials() {
+        return this._generatedMaterials;
+    }
+
+    /**
+     * MaterialXLoader constructor
+     * @param {import('three/examples/jsm/loaders/GLTFLoader.js').GLTFParser} parser - The GLTFParser instance
+     * @param {MaterialXLoaderOptions} options - The loader options
+     * @param {import('../materialx.js').MaterialXContext} context - The context for the GLTF loading process
+     */
+    constructor(parser, options, context) {
+        this.parser = parser;
+        this.options = options;
+        this.context = context;
+        
+        if (debug) console.log("MaterialXLoader created for parser");
+        // Start loading of MaterialX environment if the root extension exists
+        if (this.materialX_root_data) {
+            ready();
+        }
+    }
+
+    /**
+     * @param {number} materialIndex
+     * @returns {Promise<Material> | null}
+     */
+    loadMaterial(materialIndex) {
+        const materialDef = this.parser.json.materials?.[materialIndex];
+        if (!materialDef?.extensions?.[this.name]) {
+            return null;
+        }
+        // Wrap the async implementation
+        return this._loadMaterialAsync(materialIndex);
+    }
+
+    /**
+     * @private
+     * @param {number} materialIndex
+     * @returns {Promise<Material>}
+     */
+    async _loadMaterialAsync(materialIndex) {
+
+        /** @type {MaterialDefinition} */
+        const materialDef = this.parser.json.materials?.[materialIndex];
+        if (debug) console.log("[MaterialX] extension found in material:", materialDef.extensions?.[this.name]);
+
+        // Handle different types of MaterialX data
+        /** @type {MaterialX_material_extension} */
+        const ext = materialDef.extensions?.[this.name];
+
+        const mtlx = this.materialX_root_data?.mtlx;
+
+        if (ext && mtlx) {
+
+            /** @type {MaterialXMaterialOptions} */
+            const materialOptions = {
+                ...this.options,
+            }
+
+            if (!materialOptions.parameters) materialOptions.parameters = {};
+
+            if (materialOptions.parameters?.side === undefined && materialDef.doubleSided !== undefined) {
+                materialOptions.parameters.side = materialDef.doubleSided ? DoubleSide : FrontSide;
+            }
+
+            return createMaterialXMaterial(mtlx, ext.name, {
+                cacheKey: this.options.cacheKey || "",
+                getTexture: async url => {
+                    // Find the index of the texture in the parser
+                    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 || [];
+                        let index = -1;
+                        for (const texture of textures) {
+                            // Find the texture by name and use the pointer string to get the index
+                            if (texture.name === filenameWithoutExt) {
+                                const ptr = texture.pointer;
+                                const indexStr = ptr.substring("/textures/".length);
+                                index = parseInt(indexStr);
+
+                                if (isNaN(index) || index < 0) {
+                                    console.error("[MaterialX] Invalid texture index in pointer:", ptr);
+                                    return;
+                                }
+                                else {
+                                    if (debug) console.log("[MaterialX] Texture index found:", index, "for", filenameWithoutExt);
+                                }
+                            }
+                        }
+
+                        if (index < 0) {
+                            console.error("[MaterialX] Texture not found in parser:", filenameWithoutExt, this.parser.json);
+                            return;
+                        }
+                        return this.parser.getDependency("texture", index);
+                    }
+                    return null;
+                }
+            }, materialOptions, this.context)
+                // Cache and return the generated material
+                .then(mat => {
+                    if (mat instanceof MaterialXMaterial) this._generatedMaterials.push(mat);
+                    return mat;
+                })
+        }
+
+        // Return fallback material instead of null
+        const fallbackMaterial = new MeshStandardMaterial();
+        fallbackMaterial.name = "MaterialX_Fallback";
+        return fallbackMaterial;
+    }
+}
+
+/**
+ * Add the MaterialXLoader to the GLTFLoader instance.
+ * @param {GLTFLoader} loader
+ * @param {MaterialXLoaderOptions} [options]
+ * @param {import('../materialx.js').MaterialXContext} [context]
+ */
+export function useNeedleMaterialX(loader, options, context) {
+    loader.register(p => {
+        const loader = new MaterialXLoader(p, options || {}, context || {});
+        return loader;
+    });
+}
+
+/**
+ * Parse the MaterialX document once and cache it
+ * @param {string} mtlx
+ * @returns {Promise<any>}
+ */
+async function load(mtlx) {
+    // Ensure MaterialX is initialized
+    await ready();
+    if (!state.materialXModule) {
+        throw new Error("[MaterialX] module failed to initialize");
+    }
+    // Create MaterialX document and parse ALL the XML data from root
+    const doc = state.materialXModule.createDocument();
+    doc.setDataLibrary(state.materialXStdLib);
+    // Parse all MaterialX XML strings from the root data
+    await state.materialXModule.readFromXmlString(doc, mtlx, "");
+    if (debug) console.log("[MaterialX] root document parsed successfully");
+    return doc;
+}
+
+/**
+ * @param {string} mtlx
+ * @param {string} materialNodeName
+ * @param {import('../materialx.helper.js').Callbacks} loaders
+ * @param {MaterialXLoaderOptions} [options]
+ * @param {import('../materialx.js').MaterialXContext} [context]
+ * @returns {Promise<Material>}
+ */
+export async function createMaterialXMaterial(mtlx, materialNodeName, loaders, options, context) {
+    try {
+        if (debug) console.log(`Creating MaterialX material: ${materialNodeName}`);
+
+        const doc = await load(mtlx);
+
+        if (!state.materialXModule || !state.materialXGenerator || !state.materialXGenContext) {
+            console.warn("[MaterialX] WASM module not ready, returning fallback material");
+            const fallbackMaterial = new MeshStandardMaterial();
+            fallbackMaterial.name = `MaterialX_Fallback_${materialNodeName}`;
+            return fallbackMaterial;
+        }
+
+        // Find the renderable element following MaterialX example pattern exactly
+        let renderableElement = null;
+        let foundRenderable = false;
+
+        if (debug) console.log("[MaterialX] document", doc);
+
+        // Search for material nodes first (following the reference pattern)
+        const materialNodes = doc.getMaterialNodes();
+        if (debug) console.log(`[MaterialX] Found ${materialNodes.length} material nodes in document`, materialNodes);
+
+        // Handle both array and vector-like APIs
+        for (let i = 0; i < materialNodes.length; ++i) {
+            const materialNode = materialNodes[i];
+            if (materialNode) {
+                const name = materialNode.getNamePath();
+                if (debug) console.log(`[MaterialX] Scan material[${i}]: ${name}`);
+
+                // Find the matching material
+                if (materialNodes.length === 1 || name == materialNodeName) {
+                    materialNodeName = name;
+                    renderableElement = materialNode;
+                    foundRenderable = true;
+                    if (debug) console.log(`[MaterialX] Use material node: '${name}'`);
+                    break;
+                }
+            }
+        }
+
+        /*
+        // If no material nodes found, search nodeGraphs
+        if (!foundRenderable) {
+            const nodeGraphs = doc.getNodeGraphs();
+            console.log(`Found ${nodeGraphs.length} node graphs in document`);
+            const nodeGraphsLength = nodeGraphs.length;
+            for (let i = 0; i < nodeGraphsLength; ++i) {
+                const nodeGraph = nodeGraphs[i];
+                if (nodeGraph) {
+                    // Skip any nodegraph that has nodedef or sourceUri
+                    if ((nodeGraph as any).hasAttribute('nodedef') || (nodeGraph as any).hasSourceUri()) {
+                        continue;
+                    }
+                    // Skip any nodegraph that is connected to something downstream
+                    if ((nodeGraph as any).getDownstreamPorts().length > 0) {
+                        continue;
+                    }
+                    const outputs = (nodeGraph as any).getOutputs();
+                    for (let j = 0; j < outputs.length; ++j) {
+                        const output = outputs[j];
+                        if (output && !foundRenderable) {
+                            renderableElement = output;
+                            foundRenderable = true;
+                            break;
+                        }
+                    }
+                    if (foundRenderable) break;
+                }
+            }
+        }
+         
+        // If still no element found, search document outputs
+        if (!foundRenderable) {
+            const outputs = doc.getOutputs();
+            console.log(`Found ${outputs.length} output nodes in document`);
+            const outputsLength = outputs.length;
+            for (let i = 0; i < outputsLength; ++i) {
+                const output = outputs[i];
+                if (output && !foundRenderable) {
+                    renderableElement = output;
+                    foundRenderable = true;
+                    break;
+                }
+            }
+        }
+        */
+
+        if (!renderableElement) {
+            console.warn(`[MaterialX] No renderable element found in MaterialX document (${materialNodeName})`);
+            const fallbackMaterial = new MeshStandardMaterial();
+            fallbackMaterial.color.set(0xff00ff);
+            fallbackMaterial.name = `MaterialX_NoRenderable_${materialNodeName}`;
+            return fallbackMaterial;
+        }
+
+        if (debug) console.log("[MaterialX] Using renderable element for shader generation");
+
+        // Check transparency and set context options like the reference
+        const isTransparent = state.materialXModule.isTransparentSurface(renderableElement, state.materialXGenerator.getTarget());
+        state.materialXGenContext.getOptions().hwTransparency = isTransparent;
+
+        // Generate shaders using the element's name path
+        if (debug) console.log("[MaterialX] Generating MaterialX shaders...");
+        const elementName = renderableElement.getNamePath ? renderableElement.getNamePath() : renderableElement.getName();
+
+        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,
+            shader,
+            context: context || {},
+            parameters: {
+                transparent: isTransparent,
+                ...options?.parameters,
+            },
+            loaders: loaders,
+        });
+
+        // Add debugging to see if the material compiles correctly
+        if (debug) console.log("[MaterialX]  material created:", shaderMaterial.name);
+        return shaderMaterial;
+
+    } catch (error) {
+        // This is a wasm error (an int) that we need to resolve
+        console.error(`[MaterialX] Error creating MaterialX material (${materialNodeName}):`, error);
+        // Return a fallback material with stored MaterialX data
+        const fallbackMaterial = new MeshStandardMaterial();
+        fallbackMaterial.color.set(0xff00ff);
+        fallbackMaterial.name = `MaterialX_Error_${materialNodeName}`;
+        return fallbackMaterial;
+    }
+}

package/src/materialx.d.ts

@@ -0,0 +1,60 @@
+import { Light, Scene, Texture, WebGLRenderer } from "three";
+import type { MaterialX as MX } from "./materialx.types.js";
+
+export type MaterialXContext = {
+    getTime?(): number;
+    getFrame?(): number;
+}
+
+type EnvironmentTextureSet = {
+    radianceTexture: Texture | null;
+    irradianceTexture: Texture | null;
+}
+
+export declare const state: {
+    materialXModule: MX.MODULE | null;
+    materialXGenerator: any | null;
+    materialXGenContext: any | null;
+    materialXStdLib: any | null;
+    materialXInitPromise: Promise<void> | null;
+};
+
+/** 
+ * Wait for the MaterialX WASM module to be ready.
+ */
+export declare function ready(): Promise<void>;
+
+/**
+ * MaterialXEnvironment manages the environment settings for MaterialX materials.
+ */
+export declare class MaterialXEnvironment {
+    static get(scene: Scene): MaterialXEnvironment | null;
+    private static _environments: WeakMap<Scene, MaterialXEnvironment>;
+    private static getEnvironment(scene: Scene): MaterialXEnvironment;
+
+    private _lights: Array<Light>;
+    private _lightData: any[] | null;
+    private _lightCount: number;
+    private _initializePromise: Promise<boolean> | null;
+    private _isInitialized: boolean;
+    private _lastUpdateFrame: number;
+    private _scene: Scene;
+
+    constructor(_scene: Scene);
+
+    initialize(renderer: WebGLRenderer): Promise<boolean>;
+    update(frame: number, scene: Scene, renderer: WebGLRenderer): void;
+    reset(): void;
+
+    get lights(): Array<Light>;
+    get lightData(): any[] | null;
+    get lightCount(): number;
+    getTextures(material: any): EnvironmentTextureSet;
+
+    private _pmremGenerator: any | null;
+    private _renderer: WebGLRenderer | null;
+    private _texturesCache: Map<Texture | null, EnvironmentTextureSet>;
+    private _initialize(renderer: WebGLRenderer): Promise<boolean>;
+    private _getTextures(texture: Texture | null | undefined): EnvironmentTextureSet;
+    private updateLighting(collectLights?: boolean): void;
+}

package/src/materialx.helper.d.ts

@@ -0,0 +1,31 @@
+import * as THREE from 'three';
+
+export interface Callbacks {
+    readonly cacheKey?: string;
+    readonly getTexture: (path: string) => Promise<THREE.Texture | null | void>;
+}
+
+export interface LightData {
+    type: number;
+    position: THREE.Vector3;
+    direction: THREE.Vector3;
+    color: THREE.Color;
+    intensity: number;
+    decay_rate: number;
+    inner_angle: number;
+    outer_angle: number;
+}
+
+export function prepareEnvTexture(texture: THREE.Texture, capabilities: any): THREE.Texture;
+
+export function getLightRotation(): THREE.Matrix4;
+
+export function findLights(doc: any): Array<any>;
+
+export function registerLights(mx: any, genContext: any): Promise<void>;
+
+export function getLightData(lights: Array<THREE.Light>, genContext: any): { lightData: LightData[], lightCount: number };
+
+export function getUniformValues(shaderStage: any, loaders: Callbacks, searchPath: string): Record<string, THREE.Uniform>;
+
+export function generateMaterialPropertiesForUniforms(material: THREE.ShaderMaterial, shaderStage: any): void;