@needle-tools/materialx 1.6.0 → 1.7.0-next.043f0c6

package/src/materialx.js

@@ -1,11 +1,37 @@
 import MaterialX from "../bin/JsMaterialXGenShader.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 { renderPMREMToEquirect, renderPMREMToPrefilteredEquirect } from "./utils.texture.js";
+import { CubeUVReflectionMapping, Light, Mesh, MeshBasicMaterial, Object3D, PlaneGeometry, PMREMGenerator, Scene, Texture } from "three";
 import { registerLights, getLightData } from "./materialx.helper.js";
 import { whiteTexture } from "./utils.texture.js";
 import { VERSION } from "./constants.js";
 
+/**
+ * Accept Texture instances from any Three.js copy. Tooling like the fidelity
+ * renderer can host scenes with a different Three.js module instance than this
+ * package, so `instanceof Texture` is too strict here.
+ * @param {unknown} value
+ * @returns {value is Texture}
+ */
+function isTextureLike(value) {
+    return !!value && typeof value === "object" && /** @type {{ isTexture?: unknown }} */(value).isTexture === true;
+}
+
+function isNodeRuntime() {
+    return !!globalThis.process?.versions?.node && globalThis.process?.type !== "renderer";
+}
+
+async function getNodePackageAssetPaths() {
+    const nodeUrlModule = "node:url";
+    const { fileURLToPath } = await import(/* @vite-ignore */ nodeUrlModule);
+    const binDirectory = ["..", "bin"].join("/") + "/";
+    return [
+        "JsMaterialXCore.wasm",
+        "JsMaterialXGenShader.wasm",
+        "JsMaterialXGenShader.data.txt",
+    ].map(fileName => fileURLToPath(new URL(binDirectory + fileName, import.meta.url)));
+}
+
 
 /**
  * Preloads the MaterialX WebAssembly module.
@@ -51,14 +77,17 @@ export async function ready() {
 
             // NOTE: This must be a plain string literal (not a template) so that the
             // makeFilesLocal Vite plugin can statically detect and localize this URL.
-            const defaultBaseUrl = "https://cdn.needle.tools/static/materialx/1.6.0/";
+            const defaultBaseUrl = "https://cdn.needle.tools/static/materialx/1.7.0/";
 
             /** @type {Array<string>} */
             let urls;
 
             const location = globalThis.NEEDLE_MATERIALX_LOCATION;
 
-            if (location === "package" || location === "bin/" || location === "./bin/" || location === "../bin/") {
+            if (isNodeRuntime()) {
+                urls = await getNodePackageAssetPaths();
+            }
+            else if (location === "package" || location === "bin/" || location === "./bin/" || location === "../bin/") {
                 // Use local files from the @needle-tools/materialx npm package.
                 // Vite's ?url suffix copies these files to the output directory
                 // and returns their URL automatically — no CDN download needed.
@@ -121,7 +150,7 @@ export async function ready() {
             // SPECULAR_ENVIRONMENT_NONE: Do not use specular environment maps.
             // SPECULAR_ENVIRONMENT_FIS: Use Filtered Importance Sampling for specular environment/indirect lighting.
             // SPECULAR_ENVIRONMENT_PREFILTER: Use pre-filtered environment maps for specular environment/indirect lighting.
-            state.materialXGenContext.getOptions().hwSpecularEnvironmentMethod = state.materialXModule.HwSpecularEnvironmentMethod.SPECULAR_ENVIRONMENT_FIS;
+            state.materialXGenContext.getOptions().hwSpecularEnvironmentMethod = state.materialXModule.HwSpecularEnvironmentMethod.SPECULAR_ENVIRONMENT_PREFILTER;
 
             // TRANSMISSION_REFRACTION: Use a refraction approximation for transmission rendering.
             // TRANSMISSION_OPACITY: Use opacity for transmission rendering.
@@ -161,6 +190,7 @@ export async function ready() {
  * @typedef {Object} EnvironmentTextureSet
  * @property {Texture | null} radianceTexture
  * @property {Texture | null} irradianceTexture
+ * @property {() => void} [dispose]
  */
 
 /**
@@ -217,7 +247,7 @@ export class MaterialXEnvironment {
 
     /**
      * Initialize with Needle Engine context
-     * @param {WebGLRenderer} renderer
+     * @param {import("three").WebGLRenderer} renderer
      * @returns {Promise<boolean>}
      */
     async initialize(renderer) {
@@ -231,7 +261,7 @@ export class MaterialXEnvironment {
     /**
      * @param {number} frame
      * @param {Scene} scene
-     * @param {WebGLRenderer} renderer
+     * @param {import("three").WebGLRenderer} renderer
      */
     update(frame, scene, renderer) {
         if (!this._initializePromise) {
@@ -285,9 +315,10 @@ export class MaterialXEnvironment {
         this._pmremGenerator?.dispose();
         this._pmremGenerator = null;
         this._renderer = null;
-        for (const textureSet of this._texturesCache.values()) {
-            textureSet.radianceTexture?.dispose();
-            textureSet.irradianceTexture?.dispose();
+        for (const textureModeMap of this._texturesCache.values()) {
+            for (const textureSet of textureModeMap.values()) {
+                textureSet.dispose?.();
+            }
         }
         this._texturesCache.clear();
     }
@@ -304,34 +335,34 @@ export class MaterialXEnvironment {
      * @param {import("./materialx.material.js").MaterialXMaterial} material
      */
     getTextures(material) {
+        const radianceMode = material.environmentRadianceMode ?? "three-pmrem";
         if (material.envMap) {
             // If the material has its own envMap, we don't use the irradiance texture
-            return this._getTextures(material.envMap);
+            return this._getTextures(material.envMap, radianceMode);
         }
 
         // Use the scene background for lighting if no environment is available
         // If we don't do this we don't see the correct lighting for scenes exported with 'Environment Lighting: Color' and 'Environment Reflections: Skybox'  
         const skybox = this._scene.environment || this._scene.background;
-        if (skybox instanceof Texture) {
-            return this._getTextures(skybox);
+        if (isTextureLike(skybox)) {
+            return this._getTextures(skybox, radianceMode);
         }
-        return this._getTextures(null);
+        return this._getTextures(null, radianceMode);
     }
 
     /** @type {PMREMGenerator | null} */
     _pmremGenerator = null;
-    /** @type {WebGLRenderer | null} */
+    /** @type {import("three").WebGLRenderer | null} */
     _renderer = null;
-    /** @type {Map<Texture | null, EnvironmentTextureSet>} */
+    /** @type {Map<Texture | null, Map<string, EnvironmentTextureSet>>} */
     _texturesCache = new Map();
 
     /**
-     * @param {WebGLRenderer} renderer
+     * @param {import("three").WebGLRenderer} renderer
      * @returns {Promise<boolean>}
      */
     async _initialize(renderer) {
         this._isInitialized = false;
-        this._pmremGenerator = new PMREMGenerator(renderer);
         this._renderer = renderer;
         this.updateLighting(true);
         this._isInitialized = true;
@@ -340,30 +371,65 @@ export class MaterialXEnvironment {
 
     /**
      * @param {Texture | null | undefined} texture
-     * @returns {{radianceTexture: Texture | null, irradianceTexture: Texture | null}}
+     * @param {"three-pmrem" | "materialx-prefiltered" | "materialx-fis"} [radianceMode]
+     * @returns {EnvironmentTextureSet}
      */
-    _getTextures(texture) {
+    _getTextures(texture, radianceMode = "three-pmrem") {
 
         // Fallback to white texture if no texture is provided
         if (!texture) {
             texture = whiteTexture;
         }
 
+        const cacheKey = texture || null;
+        let textureModeMap = this._texturesCache.get(cacheKey);
+        if (!textureModeMap) {
+            textureModeMap = new Map();
+            this._texturesCache.set(cacheKey, textureModeMap);
+        }
+
         /** @type {EnvironmentTextureSet | undefined} */
-        let res = this._texturesCache.get(texture || null);
+        let res = textureModeMap.get(radianceMode);
         if (res) {
             return res;
         }
 
-        if (this._scene && this._pmremGenerator && this._renderer && texture) {
+        const isPmremTexture = texture.mapping === CubeUVReflectionMapping || texture.isRenderTargetTexture === true;
+
+        if (this._scene && this._renderer && texture) {
             if (debug) console.log("[MaterialX] Generating environment textures", texture.name);
-            const target = this._pmremGenerator.fromEquirectangular(texture);
-            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();
+            let radianceRenderTarget;
+            let irradianceRenderTarget;
+
+            if (isPmremTexture) {
+                // Scene.environment is often already PMREM-processed (CubeUV layout).
+                // Running PMREMGenerator on it again corrupts the sampling layout.
+                radianceRenderTarget = radianceMode === "materialx-prefiltered"
+                    ? renderPMREMToPrefilteredEquirect(this._renderer, texture)
+                    : radianceMode === "materialx-fis"
+                        ? renderPMREMToEquirect(this._renderer, texture, 0.0, 1024, 512)
+                        : null;
+                irradianceRenderTarget = renderPMREMToEquirect(this._renderer, texture, 1.0, 32, 16);
+            } else {
+                const target = this._getPMREMGenerator().fromEquirectangular(texture);
+                radianceRenderTarget = radianceMode === "materialx-prefiltered"
+                    ? renderPMREMToPrefilteredEquirect(this._renderer, target.texture, undefined, undefined, target.height)
+                    : radianceMode === "three-pmrem"
+                        ? target
+                        : null;
+                irradianceRenderTarget = renderPMREMToEquirect(this._renderer, target.texture, 1.0, 32, 16, target.height);
+                if (radianceMode !== "three-pmrem") {
+                    target.dispose();
+                }
+            }
+
             res = {
-                radianceTexture: radianceRenderTarget.texture,
-                irradianceTexture: irradianceRenderTarget.texture
+                radianceTexture: radianceRenderTarget?.texture ?? texture,
+                irradianceTexture: irradianceRenderTarget.texture,
+                dispose: () => {
+                    radianceRenderTarget?.dispose();
+                    irradianceRenderTarget?.dispose();
+                },
             }
         }
         else {
@@ -372,10 +438,21 @@ export class MaterialXEnvironment {
                 irradianceTexture: null
             }
         }
-        this._texturesCache.set(texture || null, res);
+        textureModeMap.set(radianceMode, res);
         return res;
     }
 
+    /**
+     * @returns {PMREMGenerator}
+     */
+    _getPMREMGenerator() {
+        if (!this._renderer) {
+            throw new Error("[MaterialX] Cannot create PMREMGenerator before renderer initialization.");
+        }
+        this._pmremGenerator ??= new PMREMGenerator(this._renderer);
+        return this._pmremGenerator;
+    }
+
     /**
      * @param {boolean} collectLights
      */

package/src/materialx.material.d.ts

@@ -1,5 +1,6 @@
-import { BufferGeometry, Camera, Group, IUniform, MaterialParameters, Object3D, Scene, ShaderMaterial, Texture, WebGLRenderer } from "three";
+import { BufferGeometry, Camera, Euler, Group, IUniform, MaterialParameters, Object3D, Scene, ShaderMaterial, Texture, WebGLRenderer } from "three";
 import { MaterialXContext, MaterialXEnvironment } from "./materialx.js";
+import type { MaterialXEnvironmentRadianceMode } from "./materialx.js";
 import { Callbacks } from "./materialx.helper.js";
 
 declare type MaterialXMaterialInitParameters = {
@@ -9,6 +10,8 @@ declare type MaterialXMaterialInitParameters = {
     loaders: Callbacks;
     context: MaterialXContext;
     parameters?: MaterialParameters;
+    environmentRadianceMode?: MaterialXEnvironmentRadianceMode;
+    specularAntialiasing?: boolean;
     debug?: boolean;
 }
 
@@ -17,6 +20,7 @@ type Precision = "highp" | "mediump" | "lowp";
 
 export declare class MaterialXMaterial extends ShaderMaterial {
     readonly shaderName: string | null;
+    readonly ready: Promise<void>;
 
     copy(source: MaterialXMaterial): this;
 
@@ -31,7 +35,12 @@ export declare class MaterialXMaterial extends ShaderMaterial {
 
     envMapIntensity: number;
     envMap: Texture | null;
+    envMapRotation: Euler;
+    environmentRadianceMode: MaterialXEnvironmentRadianceMode;
+    specularAntialiasing: boolean;
     updateUniforms(environment: MaterialXEnvironment, _renderer: WebGLRenderer, object: Object3D, camera: Camera, time?: number, frame?: number): void;
 
-    private updateEnvironmentUniforms(environment: MaterialXEnvironment): void;
+    private updateEnvironmentUniforms(environment: MaterialXEnvironment, scene: Scene): void;
 }
+
+export declare const DEFAULT_ENVIRONMENT_RADIANCE_MODE: MaterialXEnvironmentRadianceMode;