@needle-tools/materialx 1.6.0 → 1.7.0-next.57183d6

package/src/materialx.material.js

@@ -1,11 +1,299 @@
-import { BufferGeometry, Camera, FrontSide, GLSL3, Group, Matrix3, Matrix4, Object3D, Scene, ShaderMaterial, Texture, UniformsLib, Vector3, WebGLRenderer } from "three";
+import { BufferGeometry, Camera, Euler, FrontSide, GLSL3, Group, Matrix4, Object3D, Scene, ShaderMaterial, Texture, Vector3 } from "three";
 import { debug, getFrame, getTime } from "./utils.js";
 import { MaterialXEnvironment } from "./materialx.js";
 import { generateMaterialPropertiesForUniforms, getUniformValues, getLightTypeIds } from "./materialx.helper.js";
-import { cloneUniforms, cloneUniformsGroups, mergeUniforms } from "three/src/renderers/shaders/UniformsUtils.js";
+
+export const DEFAULT_ENVIRONMENT_RADIANCE_MODE = "three-pmrem";
 
 // Add helper matrices for uniform updates (similar to MaterialX example)
-const normalMat = new Matrix3();
+const worldInverseMat = new Matrix4();
+const worldTransposeMat = new Matrix4();
+const worldInverseTransposeMat = new Matrix4();
+const worldViewMat = new Matrix4();
+const worldViewProjectionMat = new Matrix4();
+const envMat = new Matrix4();
+const envRotation = new Euler();
+
+// Local copy of Three.js UniformsUtils.cloneUniforms from
+// three/src/renderers/shaders/UniformsUtils.js. Keep this in sync with the
+// minimum supported Three.js version when Three changes uniform cloning.
+function cloneUniforms(src) {
+    const dst = {};
+    for (const uniformName in src) {
+        dst[uniformName] = {};
+        for (const propertyName in src[uniformName]) {
+            const property = src[uniformName][propertyName];
+            if (property && (
+                property.isColor ||
+                property.isMatrix3 || property.isMatrix4 ||
+                property.isVector2 || property.isVector3 || property.isVector4 ||
+                property.isTexture || property.isQuaternion
+            )) {
+                dst[uniformName][propertyName] = property.isRenderTargetTexture ? null : property.clone();
+            }
+            else if (Array.isArray(property)) {
+                dst[uniformName][propertyName] = property.slice();
+            }
+            else {
+                dst[uniformName][propertyName] = property;
+            }
+        }
+    }
+    return dst;
+}
+
+// Local copy of Three.js UniformsUtils.mergeUniforms from
+// three/src/renderers/shaders/UniformsUtils.js. Copied to avoid importing from
+// three/src, which breaks package consumers using Three's public ESM surface.
+function mergeUniforms(uniforms) {
+    const merged = {};
+    for (const uniformSet of uniforms) {
+        const tmp = cloneUniforms(uniformSet);
+        for (const propertyName in tmp) {
+            merged[propertyName] = tmp[propertyName];
+        }
+    }
+    return merged;
+}
+
+// Local copy of Three.js UniformsUtils.cloneUniformsGroups from
+// three/src/renderers/shaders/UniformsUtils.js. Keep alongside cloneUniforms
+// and mergeUniforms so ShaderMaterial.clone() stays behavior-compatible.
+function cloneUniformsGroups(src) {
+    return src.map(group => group.clone());
+}
+
+function createThreeLightUniforms() {
+    return {
+        ambientLightColor: { value: [] },
+        lightProbe: { value: [] },
+        directionalLights: { value: [], properties: { direction: {}, color: {} } },
+        directionalLightShadows: { value: [], properties: { shadowIntensity: 1, shadowBias: {}, shadowNormalBias: {}, shadowRadius: {}, shadowMapSize: {} } },
+        directionalShadowMap: { value: [] },
+        directionalShadowMatrix: { value: [] },
+        spotLights: { value: [], properties: { color: {}, position: {}, direction: {}, distance: {}, coneCos: {}, penumbraCos: {}, decay: {} } },
+        spotLightShadows: { value: [], properties: { shadowIntensity: 1, shadowBias: {}, shadowNormalBias: {}, shadowRadius: {}, shadowMapSize: {} } },
+        spotLightMap: { value: [] },
+        spotShadowMap: { value: [] },
+        spotLightMatrix: { value: [] },
+        pointLights: { value: [], properties: { color: {}, position: {}, decay: {}, distance: {} } },
+        pointLightShadows: { value: [], properties: { shadowIntensity: 1, shadowBias: {}, shadowNormalBias: {}, shadowRadius: {}, shadowMapSize: {}, shadowCameraNear: {}, shadowCameraFar: {} } },
+        pointShadowMap: { value: [] },
+        pointShadowMatrix: { value: [] },
+        hemisphereLights: { value: [], properties: { direction: {}, skyColor: {}, groundColor: {} } },
+        rectAreaLights: { value: [], properties: { color: {}, position: {}, width: {}, height: {} } },
+        ltc_1: { value: null },
+        ltc_2: { value: null },
+        probesSH: { value: null },
+        probesMin: { value: new Vector3() },
+        probesMax: { value: new Vector3() },
+        probesResolution: { value: new Vector3() },
+    };
+}
+
+const CUBE_UV_REFLECTION_FUNCTIONS = `
+float mx_cubeuv_getFace(vec3 direction) {
+    vec3 absDirection = abs(direction);
+    float face = -1.0;
+    if (absDirection.x > absDirection.z) {
+        if (absDirection.x > absDirection.y)
+            face = direction.x > 0.0 ? 0.0 : 3.0;
+        else
+            face = direction.y > 0.0 ? 1.0 : 4.0;
+    } else {
+        if (absDirection.z > absDirection.y)
+            face = direction.z > 0.0 ? 2.0 : 5.0;
+        else
+            face = direction.y > 0.0 ? 1.0 : 4.0;
+    }
+    return face;
+}
+
+vec2 mx_cubeuv_getUV(vec3 direction, float face) {
+    vec2 uv;
+    if (face == 0.0) {
+        uv = vec2(direction.z, direction.y) / abs(direction.x);
+    } else if (face == 1.0) {
+        uv = vec2(-direction.x, -direction.z) / abs(direction.y);
+    } else if (face == 2.0) {
+        uv = vec2(-direction.x, direction.y) / abs(direction.z);
+    } else if (face == 3.0) {
+        uv = vec2(-direction.z, direction.y) / abs(direction.x);
+    } else if (face == 4.0) {
+        uv = vec2(-direction.x, direction.z) / abs(direction.y);
+    } else {
+        uv = vec2(direction.x, direction.y) / abs(direction.z);
+    }
+    return 0.5 * (uv + 1.0);
+}
+
+vec3 mx_cubeuv_bilinear(sampler2D envMap, vec3 direction, float mipInt) {
+    const float cubeUV_minMipLevel = 4.0;
+    const float cubeUV_minTileSize = 16.0;
+    float face = mx_cubeuv_getFace(direction);
+    float filterInt = max(cubeUV_minMipLevel - mipInt, 0.0);
+    mipInt = max(mipInt, cubeUV_minMipLevel);
+    float faceSize = exp2(mipInt);
+    highp vec2 uv = mx_cubeuv_getUV(direction, face) * (faceSize - 2.0) + 1.0;
+    if (face > 2.0) {
+        uv.y += faceSize;
+        face -= 3.0;
+    }
+    uv.x += face * faceSize;
+    uv.x += filterInt * 3.0 * cubeUV_minTileSize;
+    uv.y += 4.0 * (exp2(u_envRadianceCubeUVMaxMip) - faceSize);
+    uv.x *= u_envRadianceCubeUVTexelWidth;
+    uv.y *= u_envRadianceCubeUVTexelHeight;
+    return texture(envMap, uv).rgb;
+}
+
+float mx_cubeuv_roughnessToMip(float roughness) {
+    const float cubeUV_r0 = 1.0;
+    const float cubeUV_m0 = -2.0;
+    const float cubeUV_r1 = 0.8;
+    const float cubeUV_m1 = -1.0;
+    const float cubeUV_r4 = 0.4;
+    const float cubeUV_m4 = 2.0;
+    const float cubeUV_r5 = 0.305;
+    const float cubeUV_m5 = 3.0;
+    const float cubeUV_r6 = 0.21;
+    const float cubeUV_m6 = 4.0;
+    float mip = 0.0;
+    if (roughness >= cubeUV_r1) {
+        mip = (cubeUV_r0 - roughness) * (cubeUV_m1 - cubeUV_m0) / (cubeUV_r0 - cubeUV_r1) + cubeUV_m0;
+    } else if (roughness >= cubeUV_r4) {
+        mip = (cubeUV_r1 - roughness) * (cubeUV_m4 - cubeUV_m1) / (cubeUV_r1 - cubeUV_r4) + cubeUV_m1;
+    } else if (roughness >= cubeUV_r5) {
+        mip = (cubeUV_r4 - roughness) * (cubeUV_m5 - cubeUV_m4) / (cubeUV_r4 - cubeUV_r5) + cubeUV_m4;
+    } else if (roughness >= cubeUV_r6) {
+        mip = (cubeUV_r5 - roughness) * (cubeUV_m6 - cubeUV_m5) / (cubeUV_r5 - cubeUV_r6) + cubeUV_m5;
+    } else {
+        mip = -2.0 * log2(1.16 * roughness);
+    }
+    return mip;
+}
+
+vec4 mx_cubeuv_texture(sampler2D envMap, vec3 sampleDir, float roughness) {
+    float mip = clamp(mx_cubeuv_roughnessToMip(roughness), -2.0, u_envRadianceCubeUVMaxMip);
+    float mipF = fract(mip);
+    float mipInt = floor(mip);
+    vec3 color0 = mx_cubeuv_bilinear(envMap, sampleDir, mipInt);
+    if (mipF == 0.0) {
+        return vec4(color0, 1.0);
+    }
+    vec3 color1 = mx_cubeuv_bilinear(envMap, sampleDir, mipInt + 1.0);
+    return vec4(mix(color0, color1, mipF), 1.0);
+}
+`;
+
+const STANDARD_SURFACE_CLOSURE_GATES = [
+    { prefix: 'mx_dielectric_bsdf(closureData, coat,', predicate: 'coat >= M_FLOAT_EPS' },
+    { prefix: 'mx_conductor_bsdf(closureData, metalness,', predicate: 'metalness >= M_FLOAT_EPS' },
+    { prefix: 'mx_dielectric_bsdf(closureData, specular,', predicate: 'specular >= M_FLOAT_EPS' },
+    { prefix: 'mx_dielectric_bsdf(closureData, transmission,', predicate: 'transmission >= M_FLOAT_EPS' },
+    { prefix: 'mx_sheen_bsdf(closureData, sheen,', predicate: 'sheen >= M_FLOAT_EPS' },
+    { prefix: 'mx_translucent_bsdf(closureData, subsurface,', predicate: 'subsurface >= M_FLOAT_EPS' },
+    { prefix: 'mx_subsurface_bsdf(closureData, subsurface,', predicate: 'subsurface >= M_FLOAT_EPS' },
+    { prefix: 'mx_mix_bsdf(closureData, translucent_bsdf_out, subsurface_bsdf_out,', predicate: 'subsurface >= M_FLOAT_EPS' },
+    { prefix: 'mx_uniform_edf(closureData, emission_weight_out,', predicate: 'emission >= M_FLOAT_EPS' },
+    { prefix: 'mx_multiply_edf_color3(closureData, emission_edf_out,', predicate: 'emission >= M_FLOAT_EPS' },
+    { prefix: 'mx_generalized_schlick_edf(closureData, emission_color0_out,', predicate: 'emission >= M_FLOAT_EPS' },
+    { prefix: 'mx_mix_edf(closureData, coat_emission_edf_out, emission_edf_out,', predicate: 'emission >= M_FLOAT_EPS' },
+];
+
+/**
+ * MaterialX's optimized standard_surface graph still emits every closure call,
+ * even when a closure weight is a uniform that is zero for the whole draw. These
+ * uniform branches let ANGLE/Metal skip zero-weight branches before entering the
+ * heavier BSDF/EDF helpers.
+ * @param {string} fragmentShader
+ * @returns {string}
+ */
+export function optimizeMaterialXClosureBranches(fragmentShader) {
+    if (!fragmentShader.includes('NG_standard_surface_surfaceshader_optim')) return fragmentShader;
+
+    let optimized = fragmentShader;
+    for (const { prefix, predicate } of STANDARD_SURFACE_CLOSURE_GATES) {
+        optimized = gateClosureCall(optimized, prefix, predicate);
+    }
+    return optimized;
+}
+
+/**
+ * @param {string} source
+ * @param {string} callPrefix
+ * @param {string} predicate
+ * @returns {string}
+ */
+function gateClosureCall(source, callPrefix, predicate) {
+    const pattern = new RegExp(`^(\\s*)${escapeRegExp(callPrefix)}([^\\n]*\\);)$`, 'gm');
+    return source.replace(pattern, (_match, indent, rest) => {
+        return `${indent}if (${predicate}) {\n${indent}    ${callPrefix}${rest}\n${indent}}`;
+    });
+}
+
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+const TEXTURE_FLIP_Y_FUNCTIONS = `
+vec2 mx_three_flip_y(vec2 uv, bool flipY) {
+    return flipY ? vec2(uv.x, 1.0 - uv.y) : uv;
+}
+`;
+
+/**
+ * ShaderMaterial bypasses Three.js' built-in texture transform chunks, so
+ * MaterialX file texture samples need to account for THREE.Texture.flipY here.
+ * @param {string} fragmentShader
+ * @returns {string}
+ */
+function patchTextureFlipY(fragmentShader) {
+    const textureNames = [...fragmentShader.matchAll(/\buniform\s+sampler2D\s+([A-Za-z_][A-Za-z0-9_]*)\s*;/g)]
+        .map(match => match[1])
+        .filter(name => !name.startsWith('u_') && name !== 'albedoTable');
+
+    if (!textureNames.length) return fragmentShader;
+
+    for (const name of textureNames) {
+        const escapedName = escapeRegExp(name);
+        fragmentShader = fragmentShader.replace(
+            new RegExp(`\\btexture\\s*\\(\\s*${escapedName}\\s*,\\s*([^,\\)]+)\\)`, 'g'),
+            `texture(${name}, mx_three_flip_y($1, ${name}_flipY))`
+        );
+        fragmentShader = fragmentShader.replace(
+            new RegExp(`\\btextureLod\\s*\\(\\s*${escapedName}\\s*,\\s*([^,\\)]+)\\s*,`, 'g'),
+            `textureLod(${name}, mx_three_flip_y($1, ${name}_flipY),`
+        );
+    }
+
+    const uniforms = textureNames.map(name => `uniform bool ${name}_flipY;`).join('\n');
+    return fragmentShader.replace(
+        /(precision\s+\w+\s+float;)/,
+        `$1\n${uniforms}\n${TEXTURE_FLIP_Y_FUNCTIONS}`
+    );
+}
+
+/**
+ * The stock WebGL image node implementations rely on sampler wrapping, but the
+ * MaterialX "constant" address mode returns the node default outside [0, 1].
+ * @param {string} fragmentShader
+ * @returns {string}
+ */
+function patchImageAddressModes(fragmentShader) {
+    return fragmentShader.replace(
+        /(void\s+mx_image_\w+\([^)]*\bdefaultval\b[^)]*\buaddressmode\b[^)]*\bvaddressmode\b[^)]*\)\s*\{\s*vec2\s+uv\s*=\s*mx_transform_uv\(texcoord,\s*uv_scale,\s*uv_offset\);\s*)result\s*=\s*texture\(([^,]+),\s*uv\)(\.[A-Za-z]+)?;/g,
+        (_match, prefix, sampler, swizzle = "") => `${prefix}if ((uaddressmode == 0 && (uv.x < 0.0 || uv.x > 1.0)) || (vaddressmode == 0 && (uv.y < 0.0 || uv.y > 1.0))) {
+        result = defaultval;
+    } else {
+        result = texture(${sampler}, uv)${swizzle};
+    }`
+    );
+}
 
 /**
  * @typedef {Object} MaterialXMaterialInitParameters
@@ -15,6 +303,8 @@ const normalMat = new Matrix3();
  * @property {import('./materialx.helper.js').Callbacks} loaders
  * @property {import('./materialx.js').MaterialXContext} context
  * @property {import('three').MaterialParameters} [parameters] - Optional parameters
+ * @property {"three-pmrem" | "materialx-prefiltered" | "materialx-fis"} [environmentRadianceMode]
+ * @property {boolean} [specularAntialiasing] - Match Three.js glossy specular antialiasing. Defaults to true.
  * @property {boolean} [debug] - Debug flag
  */
 
@@ -43,6 +333,10 @@ export class MaterialXMaterial extends ShaderMaterial {
         this.uniformsGroups = cloneUniformsGroups(source.uniformsGroups);
         this.envMapIntensity = source.envMapIntensity;
         this.envMap = source.envMap;
+        this.envMapRotation.copy(source.envMapRotation);
+        this.environmentRadianceMode = source.environmentRadianceMode;
+        this.specularAntialiasing = source.specularAntialiasing;
+        this.ready = source.ready;
         generateMaterialPropertiesForUniforms(this, this._shader.getStage('pixel'));
         generateMaterialPropertiesForUniforms(this, this._shader.getStage('vertex'));
         this.needsUpdate = true;
@@ -55,6 +349,8 @@ export class MaterialXMaterial extends ShaderMaterial {
     _shader = null;
     /** @type {boolean} */
     _needsTangents = false;
+    /** @type {Promise<void>} */
+    ready = Promise.resolve();
 
     /**
      * @param {MaterialXMaterialInitParameters} [init]
@@ -69,6 +365,9 @@ export class MaterialXMaterial extends ShaderMaterial {
         let fragmentShader = "";
         /** @type {Record<string, string>} */
         let defines = {};
+        /** @type {"three-pmrem" | "materialx-prefiltered" | "materialx-fis"} */
+        let environmentRadianceMode = DEFAULT_ENVIRONMENT_RADIANCE_MODE;
+        let specularAntialiasing = true;
 
         if (init) {
 
@@ -79,6 +378,9 @@ export class MaterialXMaterial extends ShaderMaterial {
 
         vertexShader = vertexShader.replace(/^#version.*$/gm, '').trim();
         fragmentShader = fragmentShader.replace(/^#version.*$/gm, '').trim();
+        fragmentShader = optimizeMaterialXClosureBranches(fragmentShader);
+        fragmentShader = patchImageAddressModes(fragmentShader);
+        fragmentShader = patchTextureFlipY(fragmentShader);
 
         // MaterialX uses different attribute names than js defaults,
         // so we patch the MaterialX shaders to match the js standard names.
@@ -120,6 +422,14 @@ export class MaterialXMaterial extends ShaderMaterial {
         // This lets us combine material.envMapIntensity * scene.environmentIntensity
         // the same way MeshStandardMaterial does.
         fragmentShader = fragmentShader.replace(/\bu_envLightIntensity\b/g, 'envMapIntensity');
+        specularAntialiasing = init.specularAntialiasing ?? true;
+        if (specularAntialiasing) {
+            fragmentShader = patchEnvironmentSpecularAntialiasing(fragmentShader);
+        }
+        environmentRadianceMode = normalizeEnvironmentRadianceMode(init.environmentRadianceMode);
+        if (environmentRadianceMode === "three-pmrem") {
+            fragmentShader = patchPrefilteredEnvironmentLookup(fragmentShader);
+        }
 
         // Capture some vertex shader properties
         // Detect whether each UV was originally vec2 or vec3 before removing declarations.
@@ -177,6 +487,10 @@ export class MaterialXMaterial extends ShaderMaterial {
                 const isVec3 = new RegExp(`\\bvec3\\s+${name}\\b`).test(shader);
                 return isVec3 ? `${name} = vec3(${uvName}, 0.0);` : match;
             });
+            shader = shader.replace(new RegExp(`(\\w+) = vec2\\(${uvName}\\.x,\\s*1\\.0 - ${uvName}\\.y\\);`, 'g'), (match, name) => {
+                const isVec3 = new RegExp(`\\bvec3\\s+${name}\\b`).test(shader);
+                return isVec3 ? `${name} = vec3(${uvName}.x, 1.0 - ${uvName}.y, 0.0);` : match;
+            });
             return shader;
         }
         vertexShader = patchUvAssignments(vertexShader, 'uv');
@@ -354,7 +668,7 @@ $2`
         );
         } // end hasShadowUniforms
 
-        const isTransparent = init.parameters?.transparent ?? false;
+        const threeParameters = { ...init.parameters };
         materialParameters = {
             name: init.name,
             uniforms: {},
@@ -362,10 +676,9 @@ $2`
             fragmentShader: fragmentShader,
             glslVersion: GLSL3,
             depthTest: true,
-            depthWrite: !isTransparent,
             defines: defines,
             lights: true, // Enable Three.js light uniforms
-            ...init.parameters, // Spread any additional parameters passed to the material
+            ...threeParameters, // Spread any additional parameters passed to the material
         };
         }
 
@@ -377,34 +690,49 @@ $2`
         }
 
         const searchPath = ""; // Could be derived from the asset path if needed
+        /** @type {Array<Promise<unknown>>} */
+        const pendingTextureLoads = [];
         this.shaderName = init.shaderName || null;
         this._context = init.context;
         this._shader = init.shader;
         this._needsTangents = vertexShader.includes('in vec4 tangent;') || vertexShader.includes('in vec3 tangent;');
-
-        Object.assign(this.uniforms, {
-            // Three.js light uniforms (required when lights: true)
-            ...UniformsLib.lights,
-
-            ...getUniformValues(init.shader.getStage('vertex'), init.loaders, searchPath),
-            ...getUniformValues(init.shader.getStage('pixel'), init.loaders, searchPath),
-
-            u_worldMatrix: { value: new Matrix4() },
-            u_viewProjectionMatrix: { value: new Matrix4() },
-            u_viewPosition: { value: new Vector3() },
-            u_worldInverseTransposeMatrix: { value: new Matrix4() },
-
-            u_envMatrix: { value: new Matrix4() },
-            u_envRadiance: { value: null, type: 't' },
-            u_envRadianceMips: { value: 8, type: 'i' },
-            // TODO we need to figure out how we can set a PMREM here... doing many texture samples is prohibitively expensive
-            u_envRadianceSamples: { value: 8, type: 'i' },
-            u_envIrradiance: { value: null, type: 't' },
-            envMapIntensity: { value: 1.0 },
-            u_refractionEnv: { value: true },
-            u_numActiveLightSources: { value: 0 },
-            u_lightData: { value: [], needsUpdate: false }, // Array of light data. We need to set needsUpdate to false until we actually update it
-        });
+        this.environmentRadianceMode = environmentRadianceMode;
+        this.specularAntialiasing = specularAntialiasing;
+
+        Object.assign(this.uniforms,
+            // Three.js light uniforms (required when lights: true). These use
+            // Three's merge/clone semantics; generated MaterialX texture
+            // uniforms below must keep their original object identity so async
+            // texture resolution updates the same uniform object.
+            mergeUniforms([createThreeLightUniforms()]),
+            getUniformValues(init.shader.getStage('vertex'), init.loaders, searchPath, pendingTextureLoads),
+            getUniformValues(init.shader.getStage('pixel'), init.loaders, searchPath, pendingTextureLoads),
+            {
+                u_worldMatrix: { value: new Matrix4() },
+                u_worldInverseMatrix: { value: new Matrix4() },
+                u_worldTransposeMatrix: { value: new Matrix4() },
+                u_worldInverseTransposeMatrix: { value: new Matrix4() },
+                u_worldViewMatrix: { value: new Matrix4() },
+                u_viewProjectionMatrix: { value: new Matrix4() },
+                u_worldViewProjectionMatrix: { value: new Matrix4() },
+                u_viewPosition: { value: new Vector3() },
+
+                u_envMatrix: { value: new Matrix4() },
+                u_envRadiance: { value: null, type: 't' },
+                u_envRadianceMips: { value: 8, type: 'i' },
+                u_envRadianceCubeUVTexelWidth: { value: 1 / 768 },
+                u_envRadianceCubeUVTexelHeight: { value: 1 / 1024 },
+                u_envRadianceCubeUVMaxMip: { value: 8 },
+                // TODO we need to figure out how we can set a PMREM here... doing many texture samples is prohibitively expensive
+                u_envRadianceSamples: { value: 8, type: 'i' },
+                u_envIrradiance: { value: null, type: 't' },
+                envMapIntensity: { value: 1.0 },
+                u_refractionEnv: { value: true },
+                u_refractionTwoSided: { value: false },
+                u_numActiveLightSources: { value: 0 },
+                u_lightData: { value: [], needsUpdate: false }, // Array of light data. We need to set needsUpdate to false until we actually update it
+            });
+        this.ready = Promise.all(pendingTextureLoads).then(() => undefined);
 
         generateMaterialPropertiesForUniforms(this, init.shader.getStage('pixel'));
         generateMaterialPropertiesForUniforms(this, init.shader.getStage('vertex'));
@@ -423,7 +751,7 @@ $2`
     _missingTangentsWarned = false;
 
     /**
-     * @param {WebGLRenderer} renderer
+     * @param {import("three").WebGLRenderer} renderer
      * @param {Scene} _scene
      * @param {Camera} camera
      * @param {BufferGeometry} geometry
@@ -452,9 +780,15 @@ $2`
     envMapIntensity = 1.0; // Default intensity for environment map
     /** @type {Texture | null} */
     envMap = null; // Environment map texture, can be set externally
+    /** @type {Euler} */
+    envMapRotation = new Euler();
+    /** @type {"three-pmrem" | "materialx-prefiltered" | "materialx-fis"} */
+    environmentRadianceMode = DEFAULT_ENVIRONMENT_RADIANCE_MODE;
+    /** @type {boolean} */
+    specularAntialiasing = true;
 
     /**
-     * @param {WebGLRenderer} _renderer
+     * @param {import("three").WebGLRenderer} _renderer
      * @param {Object3D} object
      * @param {Camera} camera
      * @param {number} [time]
@@ -473,6 +807,18 @@ $2`
             uniforms.u_worldMatrix.needsUpdate = true;
         }
 
+        if (uniforms.u_worldInverseMatrix) {
+            uniforms.u_worldInverseMatrix.value.copy(worldInverseMat.copy(object.matrixWorld).invert());
+            // @ts-ignore
+            uniforms.u_worldInverseMatrix.needsUpdate = true;
+        }
+
+        if (uniforms.u_worldTransposeMatrix) {
+            uniforms.u_worldTransposeMatrix.value.copy(worldTransposeMat.copy(object.matrixWorld).transpose());
+            // @ts-ignore
+            uniforms.u_worldTransposeMatrix.needsUpdate = true;
+        }
+
         // Update view position
         if (uniforms.u_viewPosition) {
             uniforms.u_viewPosition.value.setFromMatrixPosition(camera.matrixWorld);
@@ -486,8 +832,21 @@ $2`
             uniforms.u_viewProjectionMatrix.needsUpdate = true;
         }
 
+        if (uniforms.u_worldViewMatrix) {
+            uniforms.u_worldViewMatrix.value.copy(worldViewMat.multiplyMatrices(camera.matrixWorldInverse, object.matrixWorld));
+            // @ts-ignore
+            uniforms.u_worldViewMatrix.needsUpdate = true;
+        }
+
+        if (uniforms.u_worldViewProjectionMatrix) {
+            worldViewMat.multiplyMatrices(camera.matrixWorldInverse, object.matrixWorld);
+            uniforms.u_worldViewProjectionMatrix.value.copy(worldViewProjectionMat.multiplyMatrices(camera.projectionMatrix, worldViewMat));
+            // @ts-ignore
+            uniforms.u_worldViewProjectionMatrix.needsUpdate = true;
+        }
+
         if (uniforms.u_worldInverseTransposeMatrix) {
-            uniforms.u_worldInverseTransposeMatrix.value.setFromMatrix3(normalMat.getNormalMatrix(object.matrixWorld));
+            uniforms.u_worldInverseTransposeMatrix.value.copy(worldInverseTransposeMat.copy(object.matrixWorld).invert().transpose());
             // @ts-ignore
             uniforms.u_worldInverseTransposeMatrix.needsUpdate = true;
         }
@@ -549,7 +908,18 @@ $2`
             if (prev != textures.radianceTexture) uniforms.u_envRadiance.needsUpdate = true;
         }
         if (uniforms.u_envRadianceMips) {
-            uniforms.u_envRadianceMips.value = Math.trunc(Math.log2(Math.max(textures.radianceTexture?.source.data.width ?? 0, textures.radianceTexture?.source.data.height ?? 0))) + 1;
+            const radianceWidth = textures.radianceTexture?.source.data.width ?? textures.radianceTexture?.image?.width ?? 0;
+            const radianceHeight = textures.radianceTexture?.source.data.height ?? textures.radianceTexture?.image?.height ?? 0;
+            const materialXRadianceMips = textures.radianceTexture?.userData?.materialXRadianceMips;
+            uniforms.u_envRadianceMips.value = Number.isFinite(materialXRadianceMips)
+                ? Math.max(1, Math.trunc(materialXRadianceMips))
+                : Math.max(1, Math.trunc(Math.log2(Math.max(radianceWidth, radianceHeight, 1))) + 1);
+        }
+        if (uniforms.u_envRadianceCubeUVTexelWidth || uniforms.u_envRadianceCubeUVTexelHeight || uniforms.u_envRadianceCubeUVMaxMip) {
+            const cubeUVSize = getCubeUVSize(textures.radianceTexture);
+            if (uniforms.u_envRadianceCubeUVTexelWidth) uniforms.u_envRadianceCubeUVTexelWidth.value = cubeUVSize.texelWidth;
+            if (uniforms.u_envRadianceCubeUVTexelHeight) uniforms.u_envRadianceCubeUVTexelHeight.value = cubeUVSize.texelHeight;
+            if (uniforms.u_envRadianceCubeUVMaxMip) uniforms.u_envRadianceCubeUVMaxMip.value = cubeUVSize.maxMip;
         }
         if (uniforms.u_envIrradiance) {
             const prev = uniforms.u_envIrradiance.value;
@@ -557,6 +927,23 @@ $2`
             // @ts-ignore
             if (prev != textures.irradianceTexture) uniforms.u_envIrradiance.needsUpdate = true;
         }
+        if (uniforms.u_envMatrix) {
+            const rotation = scene.environment && !this.envMap ? scene.environmentRotation : this.envMapRotation;
+            const texture = scene.environment && !this.envMap ? scene.environment : this.envMap;
+            envRotation.copy(rotation);
+            // Match Three.js WebGLMaterials: environment rotations are applied in
+            // the shader after converting from Three's left-handed env frame.
+            envRotation.x *= -1;
+            envRotation.y *= -1;
+            envRotation.z *= -1;
+            if (texture?.isCubeTexture && texture.isRenderTargetTexture === false) {
+                envRotation.y *= -1;
+                envRotation.z *= -1;
+            }
+            uniforms.u_envMatrix.value.copy(envMat.makeRotationFromEuler(envRotation));
+            // @ts-ignore
+            uniforms.u_envMatrix.needsUpdate = true;
+        }
 
         // Sync environment intensity: combine per-material envMapIntensity with scene.environmentIntensity
         // (mirrors MeshStandardMaterial behaviour in Three.js)
@@ -569,3 +956,196 @@ $2`
         this.uniformsNeedUpdate = true;
     }
 }
+
+/**
+ * MaterialX's "prefiltered" GLSL target expects a latlong texture with roughness
+ * in mip levels. Three.js already stores the scene environment as a prefiltered
+ * CubeUV PMREM, so sample that texture directly and translate MaterialX's lod
+ * back to the alpha/roughness value that produced it.
+ * @param {string} fragmentShader
+ * @returns {string}
+ */
+function patchPrefilteredEnvironmentLookup(fragmentShader) {
+    if (!fragmentShader.includes('mx_latlong_alpha_to_lod') || !fragmentShader.includes('mx_latlong_map_lookup')) {
+        return fragmentShader;
+    }
+
+    const uniforms = `
+uniform float u_envRadianceCubeUVTexelWidth;
+uniform float u_envRadianceCubeUVTexelHeight;
+uniform float u_envRadianceCubeUVMaxMip;
+`;
+    fragmentShader = fragmentShader.replace(/(uniform\s+sampler2D\s+u_envRadiance;\s*)/, `$1${uniforms}`);
+    fragmentShader = fragmentShader.replace(
+        /(vec3 mx_latlong_map_lookup\(vec3 dir, mat4 transform, float lod, sampler2D tex_sampler\)\s*\{[\s\S]*?\n\})/,
+        `$1
+
+${CUBE_UV_REFLECTION_FUNCTIONS}
+float mx_materialx_lod_to_alpha(float lod)
+{
+    float lodBias = lod / max(float(u_envRadianceMips - 1), 1.0);
+    return (lodBias < 0.5) ? lodBias * lodBias : 2.0 * (lodBias - 0.375);
+}
+
+vec3 mx_cubeuv_map_lookup(vec3 dir, mat4 transform, float lod, sampler2D tex_sampler)
+{
+    vec3 envDir = normalize((transform * vec4(dir, 0.0)).xyz);
+    float roughness = sqrt(clamp(mx_materialx_lod_to_alpha(lod), 0.0, 1.0));
+    return mx_cubeuv_texture(tex_sampler, envDir, roughness).rgb;
+}
+
+vec3 mx_cubeuv_irradiance_map_lookup(vec3 dir, mat4 transform, float lod, sampler2D tex_sampler)
+{
+    vec3 envDir = normalize((transform * vec4(dir, 0.0)).xyz);
+    return mx_cubeuv_texture(u_envRadiance, envDir, 1.0).rgb;
+}`
+    );
+    fragmentShader = replaceCubeUVLatlongLookups(fragmentShader);
+    return fragmentShader;
+}
+
+/**
+ * Three.js avoids sharp IBL aliasing on smooth glossy silhouettes by applying a
+ * minimum environment roughness and derivative-based geometry roughness before
+ * sampling the prefiltered environment. MaterialX receives squared roughness
+ * (alpha) at this point, so convert to roughness, apply the same adjustment,
+ * and square it again for the stock MaterialX environment code.
+ * @param {string} fragmentShader
+ * @returns {string}
+ */
+function patchEnvironmentSpecularAntialiasing(fragmentShader) {
+    if (fragmentShader.includes('mx_three_antialias_specular_alpha')) {
+        return fragmentShader;
+    }
+
+    const helper = `vec2 mx_three_antialias_specular_alpha(vec3 N, vec2 alpha)
+{
+    vec3 normal = normalize(N);
+    vec3 dxy = max(abs(dFdx(normal)), abs(dFdy(normal)));
+    float geometryRoughness = max(max(dxy.x, dxy.y), dxy.z);
+    vec2 roughness = sqrt(clamp(alpha, vec2(0.0), vec2(1.0)));
+    roughness = min(vec2(1.0), max(roughness, vec2(0.0525)) + vec2(geometryRoughness));
+    return roughness * roughness;
+}
+
+`;
+
+    const patched = fragmentShader.replace(
+        /\bvec2\s+safeAlpha\s*=\s*clamp\(roughness,\s*M_FLOAT_EPS,\s*1\.0\);/g,
+        'vec2 safeAlpha = mx_three_antialias_specular_alpha(N, clamp(roughness, M_FLOAT_EPS, 1.0));'
+    );
+    if (patched === fragmentShader) {
+        return fragmentShader;
+    }
+
+    const precisionMatch = patched.match(/precision\s+\w+\s+float;\s*/);
+    if (!precisionMatch || precisionMatch.index === undefined) {
+        return helper + patched;
+    }
+
+    const insertAt = precisionMatch.index + precisionMatch[0].length;
+    return patched.slice(0, insertAt) + '\n' + helper + patched.slice(insertAt);
+}
+
+/**
+ * In direct mode both specular radiance and diffuse irradiance should sample the
+ * same Three.js CubeUV PMREM. Radiance uses MaterialX's requested lod; irradiance
+ * samples the fully-blurred roughness-1 level, matching Three.js IBL behavior.
+ * @param {string} source
+ * @returns {string}
+ */
+function replaceCubeUVLatlongLookups(source) {
+    const needle = 'mx_latlong_map_lookup(';
+    let result = '';
+    let offset = 0;
+
+    while (offset < source.length) {
+        const start = source.indexOf(needle, offset);
+        if (start === -1) {
+            result += source.slice(offset);
+            break;
+        }
+
+        const argsStart = start + needle.length;
+        const end = findMatchingParen(source, argsStart - 1);
+        if (end === -1) {
+            result += source.slice(offset);
+            break;
+        }
+
+        const args = splitTopLevelArguments(source.slice(argsStart, end));
+        const samplerName = args.at(-1)?.trim();
+        let functionName = 'mx_latlong_map_lookup';
+        if (samplerName === 'u_envRadiance') {
+            functionName = 'mx_cubeuv_map_lookup';
+        } else if (samplerName === 'u_envIrradiance') {
+            functionName = 'mx_cubeuv_irradiance_map_lookup';
+        }
+
+        result += source.slice(offset, start) + functionName + source.slice(start + 'mx_latlong_map_lookup'.length, end + 1);
+        offset = end + 1;
+    }
+
+    return result;
+}
+
+/**
+ * @param {string} source
+ * @param {number} openParenIndex
+ * @returns {number}
+ */
+function findMatchingParen(source, openParenIndex) {
+    let depth = 0;
+    for (let i = openParenIndex; i < source.length; i++) {
+        const char = source[i];
+        if (char === '(') depth++;
+        else if (char === ')') {
+            depth--;
+            if (depth === 0) return i;
+        }
+    }
+    return -1;
+}
+
+/**
+ * @param {string} source
+ * @returns {string[]}
+ */
+function splitTopLevelArguments(source) {
+    const args = [];
+    let depth = 0;
+    let start = 0;
+    for (let i = 0; i < source.length; i++) {
+        const char = source[i];
+        if (char === '(') depth++;
+        else if (char === ')') depth--;
+        else if (char === ',' && depth === 0) {
+            args.push(source.slice(start, i));
+            start = i + 1;
+        }
+    }
+    args.push(source.slice(start));
+    return args;
+}
+
+/**
+ * @param {Texture | null | undefined} texture
+ */
+function getCubeUVSize(texture) {
+    const imageHeight = texture?.image?.height ?? texture?.source?.data?.height ?? 1024;
+    const maxMip = Math.max(0, Math.log2(imageHeight) - 2);
+    return {
+        maxMip,
+        texelHeight: 1 / imageHeight,
+        texelWidth: 1 / (3 * Math.max(Math.pow(2, maxMip), 7 * 16)),
+    };
+}
+
+/**
+ * @param {unknown} value
+ * @returns {"three-pmrem" | "materialx-prefiltered" | "materialx-fis"}
+ */
+function normalizeEnvironmentRadianceMode(value) {
+    if (value === "materialx-fis") return "materialx-fis";
+    return value === "materialx-prefiltered" ? "materialx-prefiltered" : DEFAULT_ENVIRONMENT_RADIANCE_MODE;
+}