@needle-tools/materialx 1.6.0-next.2af5fc1 → 1.7.0-next.0d06218

package/src/materialx.types.d.ts

@@ -2,21 +2,44 @@
 
 
 export namespace MaterialX {
+    export type Collection<T> = T[] | {
+        size(): number;
+        get(index: number): T | null | undefined;
+    };
+
+    export type AttributeElement = {
+        getName?(): string;
+        getType?(): string;
+        getCategory?(): string;
+        getNodeString?(): string;
+        getNodeGroup?(): string;
+        getValueString?(): string;
+        getNodeName?(): string;
+        getInterfaceName?(): string;
+        getAttribute?(name: string): string | null | undefined;
+        hasAttribute?(name: string): boolean;
+        getAttributeNames?(): Iterable<string>;
+    };
+
+    export type VariableBlock = Collection<{
+        getPath?(): string;
+        getVariable?(): string;
+    }>;
 
     export type MODULE = {
-        ShaderInterfaceType: any;
-        HwSpecularEnvironmentMethod: any;
+        ShaderInterfaceType: Record<string, number>;
+        HwSpecularEnvironmentMethod: Record<string, number>;
         HwShaderGenerator: {
-            bindLightShader(def: any, id: number, genContext: GenContext): void;
-            unbindLightShaders(context: any): void;
+            bindLightShader(def: NodeDef, id: number, genContext: GenContext): void;
+            unbindLightShaders(context: GenContext): void;
         };
         createDocument(): Document;
         readFromXmlString(doc: Document, xml: string, searchPath?: string): void;
         loadStandardLibraries(genContext: GenContext): StandardLibrary;
-        isTransparentSurface(renderableElement: any, target: string): boolean;
+        isTransparentSurface(renderableElement: Node, target: string): boolean;
         /** Returns the alpha mode for a renderable element: "opaque", "mask", or "blend".
          * Inspects the shader node (and its nodegraph implementation) for alpha_mode inputs. */
-        getAlphaMode?(renderableElement: any, target: string): string;
+        getAlphaMode?(renderableElement: Node, target: string): string;
         /** Extracts a detailed error message from a WASM exception pointer, including error logs. */
         getExceptionDetailedMessage?(exceptionPtr: number): string;
         /** Extracts a basic error message from a WASM exception pointer. */
@@ -28,12 +51,13 @@ export namespace MaterialX {
     }
 
     export type StandardLibrary = {
-
+        getNodeDefs?(): Collection<NodeDef>;
+        getNodeGraphs?(): Collection<NodeGraph>;
     }
     
     // https://github.com/AcademySoftwareFoundation/MaterialX/blob/b74787db6544283dc32afc8085ebc93cabe937cb/source/MaterialXGenShader/ShaderStage.h#L56
     export type ShaderStage = {
-        getUniformBlocks(): Record<string, any>;
+        getUniformBlocks(): Record<string, VariableBlock>;
     }
 
     export type Document = {
@@ -43,10 +67,35 @@ export namespace MaterialX {
         validate?(): { valid: boolean; message: string };
 
         getNodes(): Node[];
+        getMaterialNodes(): MaterialXNode[];
+        getNodeGraphs(): NodeGraph[];
     }
 
-    export type Node = {
+    export type Input = AttributeElement;
+
+    export type Output = AttributeElement;
+
+    export type Node = AttributeElement & {
+        getName(): string;
         getType(): string;
+        getNodeDef?(): NodeDef | null;
+        getNodeDefString?(): string;
+        getInputs?(): Collection<Input>;
+        getOutputs?(): Collection<Output>;
+    }
+
+    export type NodeDef = AttributeElement & {
+        getName(): string;
+        getNodeString?(): string;
+        getActiveInputs?(): Collection<Input>;
+        getActiveOutputs?(): Collection<Output>;
+    }
+
+    export type NodeGraph = AttributeElement & {
+        getName(): string;
+        getNodes(): Node[];
+        getOutputs?(): Collection<Output>;
+        getNodeDefString?(): string;
     }
 
     export type Matrix = {
@@ -56,4 +105,10 @@ export namespace MaterialX {
         getItem(row: number, col: number): number;
     }
 
-}
+    export type MaterialXNode = Node & {
+        getNamePath?: () => string;
+    }
+
+    export type MaterilaXNode = MaterialXNode;
+
+}

package/src/utils.texture.d.ts

@@ -13,3 +13,14 @@ export function renderPMREMToEquirect(
     height?: number,
     renderTargetHeight?: number
 ): WebGLRenderTarget;
+
+/**
+ * Renders a PMREM environment map to an equirectangular texture with roughness encoded in mip levels.
+ */
+export function renderPMREMToPrefilteredEquirect(
+    renderer: WebGLRenderer,
+    pmremTexture: Texture,
+    width?: number,
+    height?: number,
+    renderTargetHeight?: number
+): WebGLRenderTarget;

package/src/utils.texture.js

@@ -1,12 +1,96 @@
-import { WebGLRenderer, Scene, WebGLRenderTarget, PlaneGeometry, OrthographicCamera, ShaderMaterial, RGBAFormat, FloatType, LinearFilter, Mesh, EquirectangularReflectionMapping, RepeatWrapping, LinearMipMapLinearFilter, Texture } from 'three';
+import { WebGLRenderer, Scene, WebGLRenderTarget, PlaneGeometry, OrthographicCamera, ShaderMaterial, RGBAFormat, FloatType, LinearFilter, Mesh, EquirectangularReflectionMapping, RepeatWrapping, LinearMipMapLinearFilter, DataTexture, UnsignedByteType, Vector4 } from 'three';
 import { getParam } from './utils.js';
 
 const debug = getParam("debugmaterialx");
+const _viewport = new Vector4();
 
-export const whiteTexture = new Texture();
+export const whiteTexture = new DataTexture(new Uint8Array([255, 255, 255, 255]), 1, 1, RGBAFormat, UnsignedByteType);
 whiteTexture.needsUpdate = true;
-whiteTexture.image = new Image();
-whiteTexture.image.src = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAgAAAAIAQMAAAD+wSzIAAAAAXNSR0IB2cksfwAAAAlwSFlzAAALEwAACxMBAJqcGAAAAANQTFRFr6+vGqg52AAAAAxJREFUeJxjZGBEgQAAWAAJLpjsTQAAAABJRU5ErkJggg=="
+
+function toGlslFloat(value) {
+    if (!Number.isFinite(value)) return "0.0";
+    const result = Number(value).toPrecision(12).replace(/\.?0+($|e)/, "$1");
+    return result.includes(".") || result.includes("e") ? result : result + ".0";
+}
+
+function getPMREMCubeUVSize(pmremTexture, renderTargetHeight) {
+    renderTargetHeight ??= pmremTexture?.userData?.pmremRenderTargetHeight;
+    if (Number.isFinite(renderTargetHeight) && renderTargetHeight > 0) {
+        const imageHeight = renderTargetHeight;
+        const maxMip = Math.max(0, Math.log2(imageHeight) - 2);
+        return {
+            imageHeight,
+            maxMip,
+            texelWidth: 1.0 / (3 * Math.max(Math.pow(2, maxMip), 7 * 16)),
+            texelHeight: 1.0 / imageHeight,
+        };
+    }
+    const imageHeight = pmremTexture.image?.height;
+    const resolvedImageHeight = Number.isFinite(imageHeight) && imageHeight > 0 ? imageHeight : 256;
+    const maxMip = Math.max(0, Math.log2(resolvedImageHeight) - 2);
+    return {
+        imageHeight: resolvedImageHeight,
+        maxMip,
+        texelWidth: 1.0 / (3 * Math.max(Math.pow(2, maxMip), 7 * 16)),
+        texelHeight: 1.0 / resolvedImageHeight,
+    };
+}
+
+function createPrefilteredEquirectMaterial(pmremTexture, cubeUVSize) {
+    return new ShaderMaterial({
+        defines: {
+            USE_ENVMAP: '',
+            ENVMAP_TYPE_CUBE_UV: '',
+            CUBEUV_TEXEL_WIDTH: toGlslFloat(cubeUVSize.texelWidth),
+            CUBEUV_TEXEL_HEIGHT: toGlslFloat(cubeUVSize.texelHeight),
+            CUBEUV_MAX_MIP: toGlslFloat(cubeUVSize.maxMip),
+        },
+        uniforms: {
+            envMap: { value: pmremTexture },
+            roughness: { value: 0.0 },
+        },
+        vertexShader: `
+            varying vec2 vUv;
+
+            void main() {
+                vUv = uv;
+                gl_Position = vec4(position.xy, 0.0, 1.0);
+            }
+        `,
+        fragmentShader: `
+            uniform sampler2D envMap;
+            uniform float roughness;
+            varying vec2 vUv;
+
+            #include <common>
+            #include <cube_uv_reflection_fragment>
+
+            vec3 materialXLatlongDirection(vec2 uv) {
+                float longitude = (uv.x - 0.5) * (2.0 * PI);
+                float latitude = (uv.y - 0.5) * PI;
+                float cosLatitude = cos(latitude);
+
+                return vec3(
+                    cosLatitude * sin(longitude),
+                    -sin(latitude),
+                    -cosLatitude * cos(longitude)
+                );
+            }
+
+            void main() {
+                vec3 direction = materialXLatlongDirection(vUv);
+
+                #ifdef ENVMAP_TYPE_CUBE_UV
+                    vec4 envColor = textureCubeUV(envMap, direction, roughness);
+                #else
+                    vec4 envColor = vec4(1.0, 0.0, 1.0, 1.0);
+                #endif
+
+                gl_FragColor = vec4(envColor.rgb, 1.0);
+            }
+        `
+    });
+}
 
 
 
@@ -37,21 +121,7 @@ export function renderPMREMToEquirect(renderer, pmremTexture, roughness = 0.0, w
     // TODO Validate inputs
     // console.log(renderer, pmremTexture);
 
-    // Calculate PMREM parameters
-    // For PMREM CubeUV layout, we need the cube face size to calculate proper parameters
-    // Use renderTargetHeight if provided, otherwise try to derive from texture
-    let imageHeight;
-    if (renderTargetHeight) {
-        imageHeight = renderTargetHeight;
-    } else if (pmremTexture.image) {
-        imageHeight = pmremTexture.image.height / 4; // Fallback: assume CubeUV layout height / 4
-    } else {
-        imageHeight = 256; // Final fallback
-    }
-
-    const maxMip = Math.log2(imageHeight) - 2;
-    const cubeUVHeight = imageHeight;
-    const cubeUVWidth = 3 * Math.max(Math.pow(2, maxMip), 7 * 16);
+    const cubeUVSize = getPMREMCubeUVSize(pmremTexture, renderTargetHeight);
 
     // Create render target for equirectangular output
     const renderTarget = new WebGLRenderTarget(width, height, {
@@ -63,7 +133,6 @@ export function renderPMREMToEquirect(renderer, pmremTexture, roughness = 0.0, w
         wrapS: RepeatWrapping,
         anisotropy: renderer.capabilities.getMaxAnisotropy(),
     });
-
     // Create fullscreen quad geometry and camera
     const geometry = new PlaneGeometry(2, 2);
     const camera = new OrthographicCamera(-1, 1, 1, -1, 0, 1);
@@ -73,9 +142,9 @@ export function renderPMREMToEquirect(renderer, pmremTexture, roughness = 0.0, w
         defines: {
             USE_ENVMAP: '',
             ENVMAP_TYPE_CUBE_UV: '',
-            CUBEUV_TEXEL_WIDTH: 1.0 / cubeUVWidth,
-            CUBEUV_TEXEL_HEIGHT: 1.0 / cubeUVHeight,
-            CUBEUV_MAX_MIP: (maxMip + 0) + '.0',
+            CUBEUV_TEXEL_WIDTH: toGlslFloat(cubeUVSize.texelWidth),
+            CUBEUV_TEXEL_HEIGHT: toGlslFloat(cubeUVSize.texelHeight),
+            CUBEUV_MAX_MIP: toGlslFloat(cubeUVSize.maxMip),
         },
         uniforms: {
             envMap: { value: pmremTexture },
@@ -98,21 +167,17 @@ export function renderPMREMToEquirect(renderer, pmremTexture, roughness = 0.0, w
             #include <cube_uv_reflection_fragment>
             
             void main() {
-                // Convert UV coordinates to equirectangular direction
-                vec2 uv = vUv;
-                
-                // Map UV (0,1) to spherical coordinates
-                // Longitude: -π to π, Latitude: 0 to π
-                float phi = uv.x * 2.0 * PI - PI; // Longitude (-π to π)
-                float theta = uv.y * PI;          // Latitude (0 to π)
-                // Rotate 90° around Y
-                phi -= PI / 2.0; // Adjust to match Three.js convention
-
-                // Convert spherical to cartesian coordinates
+                // Use the inverse of MaterialX's mx_latlong_projection().
+                // MaterialX samples u_envRadiance through mx_latlong_map_lookup,
+                // so this conversion must write the same latlong convention.
+                float longitude = (vUv.x - 0.5) * (2.0 * PI);
+                float latitude = (vUv.y - 0.5) * PI;
+                float cosLatitude = cos(latitude);
+
                 vec3 direction = vec3(
-                    sin(theta) * cos(phi),  // x
-                    cos(theta),             // y  
-                    sin(theta) * sin(phi)   // z
+                    cosLatitude * sin(longitude),
+                    -sin(latitude),
+                    -cosLatitude * cos(longitude)
                 );
                 
                 // Sample the PMREM cube texture using the direction and roughness
@@ -137,6 +202,7 @@ export function renderPMREMToEquirect(renderer, pmremTexture, roughness = 0.0, w
     const currentAutoClear = renderer.autoClear;
     const currentXrEnabled = renderer.xr.enabled;
     const currentShadowMapEnabled = renderer.shadowMap.enabled;
+    const currentViewport = renderer.getViewport(_viewport);
 
     renderTarget.texture.generateMipmaps = true;
 
@@ -147,12 +213,15 @@ export function renderPMREMToEquirect(renderer, pmremTexture, roughness = 0.0, w
 
         // Render to our target
         renderer.autoClear = true;
+        renderTarget.viewport.set(0, 0, width, height);
+        renderTarget.scissor.set(0, 0, width, height);
         renderer.setRenderTarget(renderTarget);
         renderer.clear(); // Explicitly clear the render target
         renderer.render(tempScene, camera);
     } finally {
         // Restore renderer state completely
         renderer.setRenderTarget(currentRenderTarget);
+        renderer.setViewport(currentViewport);
         renderer.autoClear = currentAutoClear;
         renderer.xr.enabled = currentXrEnabled;
         renderer.shadowMap.enabled = currentShadowMapEnabled;
@@ -176,3 +245,91 @@ export function renderPMREMToEquirect(renderer, pmremTexture, roughness = 0.0, w
 
     return renderTarget;
 }
+
+/**
+ * Renders a Three.js PMREM CubeUV texture to an equirectangular texture whose mip
+ * levels encode increasing roughness for MaterialX SPECULAR_ENVIRONMENT_PREFILTER.
+ * @param {WebGLRenderer} renderer
+ * @param {Texture} pmremTexture
+ * @param {number} [width=2048]
+ * @param {number} [height=1024]
+ * @param {number} [renderTargetHeight]
+ * @returns {WebGLRenderTarget}
+ */
+export function renderPMREMToPrefilteredEquirect(renderer, pmremTexture, width = 2048, height = 1024, renderTargetHeight) {
+    const cubeUVSize = getPMREMCubeUVSize(pmremTexture, renderTargetHeight);
+    const mipCount = Math.floor(Math.log2(Math.max(width, height))) + 1;
+    const materialXRadianceMipCount = Math.min(8, mipCount);
+
+    const renderTarget = new WebGLRenderTarget(width, height, {
+        format: RGBAFormat,
+        type: FloatType,
+        minFilter: LinearMipMapLinearFilter,
+        magFilter: LinearFilter,
+        generateMipmaps: false,
+        wrapS: RepeatWrapping,
+        anisotropy: renderer.capabilities.getMaxAnisotropy(),
+    });
+    renderTarget.texture.mipmaps = Array.from({ length: mipCount }, (_, mip) => ({
+        width: Math.max(1, width >> mip),
+        height: Math.max(1, height >> mip),
+    }));
+
+    const geometry = new PlaneGeometry(2, 2);
+    const camera = new OrthographicCamera(-1, 1, 1, -1, 0, 1);
+    const material = createPrefilteredEquirectMaterial(pmremTexture, cubeUVSize);
+
+    const tempScene = new Scene();
+    const mesh = new Mesh(geometry, material);
+    tempScene.add(mesh);
+
+    const currentRenderTarget = renderer.getRenderTarget();
+    const currentAutoClear = renderer.autoClear;
+    const currentXrEnabled = renderer.xr.enabled;
+    const currentShadowMapEnabled = renderer.shadowMap.enabled;
+    const currentViewport = renderer.getViewport(_viewport);
+
+    try {
+        renderer.xr.enabled = false;
+        renderer.shadowMap.enabled = false;
+        renderer.autoClear = true;
+
+        for (let mip = 0; mip < mipCount; mip++) {
+            const materialXMip = Math.min(mip, materialXRadianceMipCount - 1);
+            const lodBias = materialXMip / Math.max(1, materialXRadianceMipCount - 1);
+            const alpha = lodBias < 0.5 ? lodBias * lodBias : 2.0 * (lodBias - 0.375);
+            const roughness = Math.sqrt(Math.min(1, Math.max(0, alpha)));
+            const mipWidth = Math.max(1, width >> mip);
+            const mipHeight = Math.max(1, height >> mip);
+            material.uniforms.roughness.value = Math.min(1, Math.max(0, roughness));
+            renderTarget.viewport.set(0, 0, mipWidth, mipHeight);
+            renderTarget.scissor.set(0, 0, mipWidth, mipHeight);
+            renderer.setRenderTarget(renderTarget, 0, mip);
+            renderer.clear();
+            renderer.render(tempScene, camera);
+        }
+    } finally {
+        renderer.setRenderTarget(currentRenderTarget);
+        renderer.setViewport(currentViewport);
+        renderer.autoClear = currentAutoClear;
+        renderer.xr.enabled = currentXrEnabled;
+        renderer.shadowMap.enabled = currentShadowMapEnabled;
+
+        geometry.dispose();
+        material.dispose();
+        tempScene.remove(mesh);
+    }
+
+    renderTarget.texture.name = 'PMREM_Prefiltered_Equirectangular_Texture';
+    renderTarget.texture.mapping = EquirectangularReflectionMapping;
+    renderTarget.texture.generateMipmaps = false;
+    renderTarget.texture.userData.materialXRadianceMips = materialXRadianceMipCount;
+
+    if (debug) console.log('[MaterialX] PMREM to prefiltered equirect render target:', {
+        width: renderTarget.width,
+        height: renderTarget.height,
+        mipCount,
+    });
+
+    return renderTarget;
+}