@needle-tools/materialx 1.1.1-next.714bc32 → 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.714bc32",
+  "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.ts → index.js}

@@ -1,13 +1,11 @@
-export { ready, type MaterialXContext } from "./materialx.js";
+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 }
+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.ts → loader.three.js}

@@ -1,61 +1,55 @@
-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 { 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";
-import { Callbacks as callbacks } from "../materialx.helper.js";
-
-// TypeScript interfaces matching the C# data structures
-export type MaterialX_root_extension = {
-    /** e.g. 1.39 */
-    version: string;
-    /** e.g. "Material" */
-    name: string;
-    /** MaterialX xml content */
-    mtlx: string;
-    /** MaterialX texture pointers */
-    textures: Array<{ name: string, pointer: string }>;
-    shaders?: Array<{
-        /** The materialx node name */
-        name: string,
-        /** The original name of the shader */
-        originalName: string,
-    }>,
-}
 
-export type MaterialX_material_extension = {
-    /** The MaterialX material name */
-    name: string;
-    /** The index of the shader in the shaders array of the root extension. */
-    shader?: number;
-}
+/**
+ * @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
+ */
 
-type MaterialDefinition = {
-    name?: string; // Optional name for the material
-    doubleSided?: boolean; // Whether the material is double-sided
-    extensions?: {
-        [key: string]: any; // Extensions for the material, including MaterialX
-    },
-}
+/**
+ * @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
+ */
 
-// 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">;
-}
+/**
+ * @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 implements GLTFLoaderPlugin {
-    readonly name = "NEEDLE_materials_mtlx";
+export class MaterialXLoader {
+    /** @readonly */
+    name = "NEEDLE_materials_mtlx";
 
-    private readonly _generatedMaterials: MaterialXMaterial[] = [];
+    /** @type {MaterialXMaterial[]} */
+    _generatedMaterials = [];
 
-    private _documentReadyPromise: Promise<any> | null = null;
+    /** @type {Promise<any> | null} */
+    _documentReadyPromise = null;
 
     get materialX_root_data() {
-        return this.parser.json.extensions?.[this.name] as MaterialX_root_extension | null;
+        return /** @type {MaterialX_root_extension | null} */ (this.parser.json.extensions?.[this.name]) || null;
     }
 
     /** Generated materialX materials */
@@ -65,15 +59,15 @@ export class MaterialXLoader implements GLTFLoaderPlugin {
 
     /**
      * MaterialXLoader constructor
-     * @param parser The GLTFParser instance
-     * @param cacheKey The URL of the GLTF file
-     * @param context The context for the GLTF loading process
+     * @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(
-        private parser: GLTFParser,
-        private options: MaterialXLoaderOptions,
-        private context: MaterialXContext
-    ) {
+    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) {
@@ -81,8 +75,11 @@ export class MaterialXLoader implements GLTFLoaderPlugin {
         }
     }
 
-
-    loadMaterial(materialIndex: number): Promise<Material> | null {
+    /**
+     * @param {number} materialIndex
+     * @returns {Promise<Material> | null}
+     */
+    loadMaterial(materialIndex) {
         const materialDef = this.parser.json.materials?.[materialIndex];
         if (!materialDef?.extensions?.[this.name]) {
             return null;
@@ -91,20 +88,27 @@ export class MaterialXLoader implements GLTFLoaderPlugin {
         return this._loadMaterialAsync(materialIndex);
     }
 
+    /**
+     * @private
+     * @param {number} materialIndex
+     * @returns {Promise<Material>}
+     */
+    async _loadMaterialAsync(materialIndex) {
 
-    private async _loadMaterialAsync(materialIndex: number): Promise<Material> {
-
-        const materialDef = this.parser.json.materials?.[materialIndex] as MaterialDefinition;
+        /** @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
-        const ext = materialDef.extensions?.[this.name] as MaterialX_material_extension;
+        /** @type {MaterialX_material_extension} */
+        const ext = materialDef.extensions?.[this.name];
 
         const mtlx = this.materialX_root_data?.mtlx;
 
         if (ext && mtlx) {
 
-            const materialOptions: MaterialXMaterialOptions = {
+            /** @type {MaterialXMaterialOptions} */
+            const materialOptions = {
                 ...this.options,
             }
 
@@ -162,29 +166,27 @@ export class MaterialXLoader implements GLTFLoaderPlugin {
         fallbackMaterial.name = "MaterialX_Fallback";
         return fallbackMaterial;
     }
-
-}
-
-
-type MaterialXMaterialOptions = {
-    parameters?: MaterialParameters;
 }
 
 /**
  * Add the MaterialXLoader to the GLTFLoader instance.
+ * @param {GLTFLoader} loader
+ * @param {MaterialXLoaderOptions} [options]
+ * @param {import('../materialx.js').MaterialXContext} [context]
  */
-export function useNeedleMaterialX(loader: GLTFLoader, options?: MaterialXLoaderOptions, context?: MaterialXContext) {
+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
-async function load(mtlx: string): Promise<any> {
+/**
+ * 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) {
@@ -199,7 +201,15 @@ async function load(mtlx: string): Promise<any> {
     return doc;
 }
 
-export async function createMaterialXMaterial(mtlx: string, materialNodeName: string, loaders: callbacks, options?: MaterialXLoaderOptions, context?: MaterialXContext): Promise<Material> {
+/**
+ * @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}`);
 
@@ -213,7 +223,7 @@ export async function createMaterialXMaterial(mtlx: string, materialNodeName: st
         }
 
         // Find the renderable element following MaterialX example pattern exactly
-        let renderableElement: any = null;
+        let renderableElement = null;
         let foundRenderable = false;
 
         if (debug) console.log("[MaterialX] document", doc);
@@ -288,10 +298,10 @@ export async function createMaterialXMaterial(mtlx: string, materialNodeName: st
         */
 
         if (!renderableElement) {
-            console.warn(`[MaterialX] No renderable element found in MaterialX document (${name})`);
+            console.warn(`[MaterialX] No renderable element found in MaterialX document (${materialNodeName})`);
             const fallbackMaterial = new MeshStandardMaterial();
             fallbackMaterial.color.set(0xff00ff);
-            fallbackMaterial.name = `MaterialX_NoRenderable_${name}`;
+            fallbackMaterial.name = `MaterialX_NoRenderable_${materialNodeName}`;
             return fallbackMaterial;
         }
 
@@ -303,7 +313,7 @@ export async function createMaterialXMaterial(mtlx: string, materialNodeName: st
 
         // Generate shaders using the element's name path
         if (debug) console.log("[MaterialX] Generating MaterialX shaders...");
-        const elementName = (renderableElement as any).getNamePath ? (renderableElement as any).getNamePath() : (renderableElement as any).getName();
+        const elementName = renderableElement.getNamePath ? renderableElement.getNamePath() : renderableElement.getName();
 
         const shader = state.materialXGenerator.generate(elementName, renderableElement, state.materialXGenContext);
 
@@ -331,11 +341,11 @@ export async function createMaterialXMaterial(mtlx: string, materialNodeName: st
 
     } catch (error) {
         // This is a wasm error (an int) that we need to resolve
-        console.error(`[MaterialX] Error creating MaterialX material (${name}):`, error);
+        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_${name}`;
+        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;