From e08056186fda427525315bc4965048ab5b0cd836 Mon Sep 17 00:00:00 2001
From: Lee Kerley <ld_kerley@icloud.com>
Date: Wed, 20 May 2026 17:40:28 -0700
Subject: [PATCH 1/2] Add version of UsdPreviewSurface with opacityMode as a
 string for compatibility.

Added unit tests for both modes.

Updated validation logic to allow for mis-matched types if enumeration is present
---
 libraries/bxdf/usd_preview_surface.mtlx       | 24 ++++++++++++++++++-
 .../usd_preview_surface_presence_int.mtlx     | 14 +++++++++++
 .../usd_preview_surface_presence_string.mtlx  | 14 +++++++++++
 .../usd_preview_surface_transparent_int.mtlx  | 14 +++++++++++
 ...sd_preview_surface_transparent_string.mtlx | 14 +++++++++++
 source/MaterialXCore/Element.cpp              | 13 +++++++++-
 source/MaterialXCore/Types.cpp                |  1 +
 source/MaterialXCore/Types.h                  |  1 +
 8 files changed, 93 insertions(+), 2 deletions(-)
 create mode 100644 resources/Materials/Examples/UsdPreviewSurface/usd_preview_surface_presence_int.mtlx
 create mode 100644 resources/Materials/Examples/UsdPreviewSurface/usd_preview_surface_presence_string.mtlx
 create mode 100644 resources/Materials/Examples/UsdPreviewSurface/usd_preview_surface_transparent_int.mtlx
 create mode 100644 resources/Materials/Examples/UsdPreviewSurface/usd_preview_surface_transparent_string.mtlx

diff --git a/libraries/bxdf/usd_preview_surface.mtlx b/libraries/bxdf/usd_preview_surface.mtlx
index f89e561c3d..3fdd429dfb 100644
--- a/libraries/bxdf/usd_preview_surface.mtlx
+++ b/libraries/bxdf/usd_preview_surface.mtlx
@@ -25,6 +25,25 @@
     <output name="out" type="surfaceshader" />
   </nodedef>
 
+  <nodedef name="ND_UsdPreviewSurface_surfaceshader_261" node="UsdPreviewSurface" nodegroup="pbr" doc="UsdPreviewSurface shader" version="2.6" isdefaultversion="true">
+    <input name="diffuseColor" type="color3" value="0.18, 0.18, 0.18" uimin="0,0,0" uimax="1,1,1" uiname="Diffuse Color" />
+    <input name="emissiveColor" type="color3" value="0, 0, 0" uimin="0,0,0" uisoftmax="1,1,1" uiname="Emissive Color" />
+    <input name="useSpecularWorkflow" type="integer" value="0" uimin="0" uimax="1" uistep="1" uiname="Use Specular Workflow" />
+    <input name="specularColor" type="color3" value="0, 0, 0" uimin="0,0,0" uimax="1,1,1" uiname="Specular Color" />
+    <input name="metallic" type="float" value="0" uimin="0.0" uimax="1.0" uiname="Metallic" />
+    <input name="roughness" type="float" value="0.5" uimin="0.0" uimax="1.0" uiname="Roughness" />
+    <input name="clearcoat" type="float" value="0" uimin="0.0" uimax="1.0" uiname="Clearcoat" />
+    <input name="clearcoatRoughness" type="float" value="0.01" uimin="0.0" uimax="1.0" uiname="Clearcoat Roughness" />
+    <input name="opacity" type="float" value="1" uimin="0.0" uimax="1.0" uiname="Opacity" />
+    <input name="opacityMode" type="string" enum="transparent,presence" value="transparent" uiname="Opacity Mode" />
+    <input name="opacityThreshold" type="float" value="0" uimin="0.0" uimax="1.0" uiname="Opacity Threshold" />
+    <input name="ior" type="float" value="1.5" uimin="0.0" uisoftmin="1.0" uisoftmax="3.0" uiname="Index of Refraction" />
+    <input name="normal" type="vector3" value="0, 0, 1" uimin="-1.0,-1.0,-1.0" uimax="1.0,1.0,1.0" uiname="Normal" />
+    <input name="displacement" type="float" value="0" uiname="Displacement" />
+    <input name="occlusion" type="float" value="1" uimin="0.0" uimax="1.0" uiname="Occlusion" />
+    <output name="out" type="surfaceshader" />
+  </nodedef>
+
   <!-- Node: UsdUVTexture -->
   <nodedef name="ND_UsdUVTexture" node="UsdUVTexture" nodegroup="texture2d" version="2.2" inherit="ND_UsdUVTexture_23">
     <output name="r" type="float" />
@@ -112,8 +131,11 @@
   <!-- USD Preview Surface nodegraph implementations                            -->
   <!-- ======================================================================== -->
 
+  <implementation name="IMP_UsdPreviewSurface_surfaceshader" nodedef="ND_UsdPreviewSurface_surfaceshader" nodegraph="NG_UsdPreviewSurface_surfaceshader" />
+  <implementation name="IMP_UsdPreviewSurface_surfaceshader_261" nodedef="ND_UsdPreviewSurface_surfaceshader_261" nodegraph="NG_UsdPreviewSurface_surfaceshader" />
+
   <!-- Node: UsdPreviewSurface -->
-  <nodegraph name="IMP_UsdPreviewSurface_surfaceshader" nodedef="ND_UsdPreviewSurface_surfaceshader">
+  <nodegraph name="NG_UsdPreviewSurface_surfaceshader" >
 
     <convert name="use_specular_workflow_float" type="float">
       <input name="in" type="integer" interfacename="useSpecularWorkflow" />
diff --git a/resources/Materials/Examples/UsdPreviewSurface/usd_preview_surface_presence_int.mtlx b/resources/Materials/Examples/UsdPreviewSurface/usd_preview_surface_presence_int.mtlx
new file mode 100644
index 0000000000..e7d4309061
--- /dev/null
+++ b/resources/Materials/Examples/UsdPreviewSurface/usd_preview_surface_presence_int.mtlx
@@ -0,0 +1,14 @@
+<?xml version="1.0"?>
+<materialx version="1.39" colorspace="lin_rec709">
+  <UsdPreviewSurface name="SR_carpaint" type="surfaceshader">
+    <input name="diffuseColor" type="color3" value="0.0518895, 0.29606, 0.425324" />
+    <input name="roughness" type="float" value="0.4" />
+    <input name="clearcoat" type="float" value="1" />
+    <input name="clearcoatRoughness" type="float" value="0" />
+    <input name="opacity" type="float" value="0.2" />
+    <input name="opacityMode" type="integer" value="1" /> <!-- presence -->
+  </UsdPreviewSurface>
+  <surfacematerial name="USD_Car_Paint" type="material">
+    <input name="surfaceshader" type="surfaceshader" nodename="SR_carpaint" />
+  </surfacematerial>
+</materialx>
diff --git a/resources/Materials/Examples/UsdPreviewSurface/usd_preview_surface_presence_string.mtlx b/resources/Materials/Examples/UsdPreviewSurface/usd_preview_surface_presence_string.mtlx
new file mode 100644
index 0000000000..b2dedc9676
--- /dev/null
+++ b/resources/Materials/Examples/UsdPreviewSurface/usd_preview_surface_presence_string.mtlx
@@ -0,0 +1,14 @@
+<?xml version="1.0"?>
+<materialx version="1.39" colorspace="lin_rec709">
+  <UsdPreviewSurface name="SR_carpaint" type="surfaceshader">
+    <input name="diffuseColor" type="color3" value="0.0518895, 0.29606, 0.425324" />
+    <input name="roughness" type="float" value="0.4" />
+    <input name="clearcoat" type="float" value="1" />
+    <input name="clearcoatRoughness" type="float" value="0" />
+    <input name="opacity" type="float" value="0.2" />
+    <input name="opacityMode" type="string" value="presence" />
+  </UsdPreviewSurface>
+  <surfacematerial name="USD_Car_Paint" type="material">
+    <input name="surfaceshader" type="surfaceshader" nodename="SR_carpaint" />
+  </surfacematerial>
+</materialx>
diff --git a/resources/Materials/Examples/UsdPreviewSurface/usd_preview_surface_transparent_int.mtlx b/resources/Materials/Examples/UsdPreviewSurface/usd_preview_surface_transparent_int.mtlx
new file mode 100644
index 0000000000..26b7a1c80c
--- /dev/null
+++ b/resources/Materials/Examples/UsdPreviewSurface/usd_preview_surface_transparent_int.mtlx
@@ -0,0 +1,14 @@
+<?xml version="1.0"?>
+<materialx version="1.39" colorspace="lin_rec709">
+  <UsdPreviewSurface name="SR_carpaint" type="surfaceshader">
+    <input name="diffuseColor" type="color3" value="0.0518895, 0.29606, 0.425324" />
+    <input name="roughness" type="float" value="0.4" />
+    <input name="clearcoat" type="float" value="1" />
+    <input name="clearcoatRoughness" type="float" value="0" />
+    <input name="opacity" type="float" value="0.2" />
+    <input name="opacityMode" type="integer" value="0" /> <!-- transparent -->
+  </UsdPreviewSurface>
+  <surfacematerial name="USD_Car_Paint" type="material">
+    <input name="surfaceshader" type="surfaceshader" nodename="SR_carpaint" />
+  </surfacematerial>
+</materialx>
diff --git a/resources/Materials/Examples/UsdPreviewSurface/usd_preview_surface_transparent_string.mtlx b/resources/Materials/Examples/UsdPreviewSurface/usd_preview_surface_transparent_string.mtlx
new file mode 100644
index 0000000000..781953b8e1
--- /dev/null
+++ b/resources/Materials/Examples/UsdPreviewSurface/usd_preview_surface_transparent_string.mtlx
@@ -0,0 +1,14 @@
+<?xml version="1.0"?>
+<materialx version="1.39" colorspace="lin_rec709">
+  <UsdPreviewSurface name="SR_carpaint" type="surfaceshader">
+    <input name="diffuseColor" type="color3" value="0.0518895, 0.29606, 0.425324" />
+    <input name="roughness" type="float" value="0.4" />
+    <input name="clearcoat" type="float" value="1" />
+    <input name="clearcoatRoughness" type="float" value="0" />
+    <input name="opacity" type="float" value="0.2" />
+    <input name="opacityMode" type="string" value="transparent" />
+  </UsdPreviewSurface>
+  <surfacematerial name="USD_Car_Paint" type="material">
+    <input name="surfaceshader" type="surfaceshader" nodename="SR_carpaint" />
+  </surfacematerial>
+</materialx>
diff --git a/source/MaterialXCore/Element.cpp b/source/MaterialXCore/Element.cpp
index a074277aca..08cb41d270 100644
--- a/source/MaterialXCore/Element.cpp
+++ b/source/MaterialXCore/Element.cpp
@@ -827,7 +827,18 @@ bool ValueElement::validate(string* message) const
             validateRequire(valueElem != nullptr, res, message, "Interface name not found in referenced declaration");
             if (valueElem)
             {
-                validateRequire(getType() == valueElem->getType(), res, message, "Interface name refers to value element of a different type");
+                bool typesMatch = getType() == valueElem->getType();
+                if (!typesMatch)
+                {
+                    // if the types don't match - we might have an enumeration at the interface.
+                    if (valueElem->getType() == STRING_TYPE_STRING &&
+                        getType() == INTEGER_TYPE_STRING &&
+                        valueElem->hasAttribute(ValueElement::ENUM_ATTRIBUTE))
+                    {
+                        typesMatch = true;
+                    }
+                }
+                validateRequire(typesMatch, res, message, "Interface name refers to value element of a different type");
             }
         }
     }
diff --git a/source/MaterialXCore/Types.cpp b/source/MaterialXCore/Types.cpp
index 4b34e49295..3985d18505 100644
--- a/source/MaterialXCore/Types.cpp
+++ b/source/MaterialXCore/Types.cpp
@@ -11,6 +11,7 @@ const string DEFAULT_TYPE_STRING = "color3";
 const string FILENAME_TYPE_STRING = "filename";
 const string GEOMNAME_TYPE_STRING = "geomname";
 const string STRING_TYPE_STRING = "string";
+const string INTEGER_TYPE_STRING = "integer";
 const string BSDF_TYPE_STRING = "BSDF";
 const string EDF_TYPE_STRING = "EDF";
 const string VDF_TYPE_STRING = "VDF";
diff --git a/source/MaterialXCore/Types.h b/source/MaterialXCore/Types.h
index 4fd88cb127..ea684cef36 100644
--- a/source/MaterialXCore/Types.h
+++ b/source/MaterialXCore/Types.h
@@ -22,6 +22,7 @@ extern MX_CORE_API const string DEFAULT_TYPE_STRING;
 extern MX_CORE_API const string FILENAME_TYPE_STRING;
 extern MX_CORE_API const string GEOMNAME_TYPE_STRING;
 extern MX_CORE_API const string STRING_TYPE_STRING;
+extern MX_CORE_API const string INTEGER_TYPE_STRING;
 extern MX_CORE_API const string BSDF_TYPE_STRING;
 extern MX_CORE_API const string EDF_TYPE_STRING;
 extern MX_CORE_API const string VDF_TYPE_STRING;

From 282ad111b08a55c7f4c5a759dd0608077d652b7e Mon Sep 17 00:00:00 2001
From: Lee Kerley <ld_kerley@icloud.com>
Date: Thu, 28 May 2026 08:45:22 -0700
Subject: [PATCH 2/2] Consolidate unit tests

---
 .../usd_preview_surface_presence.mtlx         | 52 +++++++++++++++++++
 .../usd_preview_surface_presence_int.mtlx     | 14 -----
 .../usd_preview_surface_presence_string.mtlx  | 14 -----
 .../usd_preview_surface_transparent_int.mtlx  | 14 -----
 ...sd_preview_surface_transparent_string.mtlx | 14 -----
 5 files changed, 52 insertions(+), 56 deletions(-)
 create mode 100644 resources/Materials/Examples/UsdPreviewSurface/usd_preview_surface_presence.mtlx
 delete mode 100644 resources/Materials/Examples/UsdPreviewSurface/usd_preview_surface_presence_int.mtlx
 delete mode 100644 resources/Materials/Examples/UsdPreviewSurface/usd_preview_surface_presence_string.mtlx
 delete mode 100644 resources/Materials/Examples/UsdPreviewSurface/usd_preview_surface_transparent_int.mtlx
 delete mode 100644 resources/Materials/Examples/UsdPreviewSurface/usd_preview_surface_transparent_string.mtlx

diff --git a/resources/Materials/Examples/UsdPreviewSurface/usd_preview_surface_presence.mtlx b/resources/Materials/Examples/UsdPreviewSurface/usd_preview_surface_presence.mtlx
new file mode 100644
index 0000000000..e3e03a5659
--- /dev/null
+++ b/resources/Materials/Examples/UsdPreviewSurface/usd_preview_surface_presence.mtlx
@@ -0,0 +1,52 @@
+<?xml version="1.0"?>
+<materialx version="1.39" colorspace="lin_rec709">
+
+  <UsdPreviewSurface name="SR_USD_opacityMode_transparent_int" type="surfaceshader">
+    <input name="diffuseColor" type="color3" value="0.0518895, 0.29606, 0.425324" />
+    <input name="roughness" type="float" value="0.4" />
+    <input name="clearcoat" type="float" value="1" />
+    <input name="clearcoatRoughness" type="float" value="0" />
+    <input name="opacity" type="float" value="0.2" />
+    <input name="opacityMode" type="integer" value="0" /> <!-- transparent -->
+  </UsdPreviewSurface>
+  <surfacematerial name="USD_opacityMode_transparent_int" type="material">
+    <input name="surfaceshader" type="surfaceshader" nodename="SR_USD_opacityMode_transparent_int" />
+  </surfacematerial>
+
+  <UsdPreviewSurface name="SR_USD_opacityMode_presence_int" type="surfaceshader">
+    <input name="diffuseColor" type="color3" value="0.0518895, 0.29606, 0.425324" />
+    <input name="roughness" type="float" value="0.4" />
+    <input name="clearcoat" type="float" value="1" />
+    <input name="clearcoatRoughness" type="float" value="0" />
+    <input name="opacity" type="float" value="0.2" />
+    <input name="opacityMode" type="integer" value="1" /> <!-- presence -->
+  </UsdPreviewSurface>
+  <surfacematerial name="USD_opacityMode_presence_int" type="material">
+    <input name="surfaceshader" type="surfaceshader" nodename="SR_USD_opacityMode_presence_int" />
+  </surfacematerial>
+
+  <UsdPreviewSurface name="SR_USD_opacityMode_transparent_string" type="surfaceshader">
+    <input name="diffuseColor" type="color3" value="0.0518895, 0.29606, 0.425324" />
+    <input name="roughness" type="float" value="0.4" />
+    <input name="clearcoat" type="float" value="1" />
+    <input name="clearcoatRoughness" type="float" value="0" />
+    <input name="opacity" type="float" value="0.2" />
+    <input name="opacityMode" type="string" value="transparent" />
+  </UsdPreviewSurface>
+  <surfacematerial name="USD_opacityMode_transparent_string" type="material">
+    <input name="surfaceshader" type="surfaceshader" nodename="SR_USD_opacityMode_transparent_string" />
+  </surfacematerial>
+
+  <UsdPreviewSurface name="SR_USD_opacityMode_presence_string" type="surfaceshader">
+    <input name="diffuseColor" type="color3" value="0.0518895, 0.29606, 0.425324" />
+    <input name="roughness" type="float" value="0.4" />
+    <input name="clearcoat" type="float" value="1" />
+    <input name="clearcoatRoughness" type="float" value="0" />
+    <input name="opacity" type="float" value="0.2" />
+    <input name="opacityMode" type="string" value="presence" />
+  </UsdPreviewSurface>
+  <surfacematerial name="USD_opacityMode_presence_string" type="material">
+    <input name="surfaceshader" type="surfaceshader" nodename="SR_USD_opacityMode_presence_string" />
+  </surfacematerial>
+
+</materialx>
diff --git a/resources/Materials/Examples/UsdPreviewSurface/usd_preview_surface_presence_int.mtlx b/resources/Materials/Examples/UsdPreviewSurface/usd_preview_surface_presence_int.mtlx
deleted file mode 100644
index e7d4309061..0000000000
--- a/resources/Materials/Examples/UsdPreviewSurface/usd_preview_surface_presence_int.mtlx
+++ /dev/null
@@ -1,14 +0,0 @@
-<?xml version="1.0"?>
-<materialx version="1.39" colorspace="lin_rec709">
-  <UsdPreviewSurface name="SR_carpaint" type="surfaceshader">
-    <input name="diffuseColor" type="color3" value="0.0518895, 0.29606, 0.425324" />
-    <input name="roughness" type="float" value="0.4" />
-    <input name="clearcoat" type="float" value="1" />
-    <input name="clearcoatRoughness" type="float" value="0" />
-    <input name="opacity" type="float" value="0.2" />
-    <input name="opacityMode" type="integer" value="1" /> <!-- presence -->
-  </UsdPreviewSurface>
-  <surfacematerial name="USD_Car_Paint" type="material">
-    <input name="surfaceshader" type="surfaceshader" nodename="SR_carpaint" />
-  </surfacematerial>
-</materialx>
diff --git a/resources/Materials/Examples/UsdPreviewSurface/usd_preview_surface_presence_string.mtlx b/resources/Materials/Examples/UsdPreviewSurface/usd_preview_surface_presence_string.mtlx
deleted file mode 100644
index b2dedc9676..0000000000
--- a/resources/Materials/Examples/UsdPreviewSurface/usd_preview_surface_presence_string.mtlx
+++ /dev/null
@@ -1,14 +0,0 @@
-<?xml version="1.0"?>
-<materialx version="1.39" colorspace="lin_rec709">
-  <UsdPreviewSurface name="SR_carpaint" type="surfaceshader">
-    <input name="diffuseColor" type="color3" value="0.0518895, 0.29606, 0.425324" />
-    <input name="roughness" type="float" value="0.4" />
-    <input name="clearcoat" type="float" value="1" />
-    <input name="clearcoatRoughness" type="float" value="0" />
-    <input name="opacity" type="float" value="0.2" />
-    <input name="opacityMode" type="string" value="presence" />
-  </UsdPreviewSurface>
-  <surfacematerial name="USD_Car_Paint" type="material">
-    <input name="surfaceshader" type="surfaceshader" nodename="SR_carpaint" />
-  </surfacematerial>
-</materialx>
diff --git a/resources/Materials/Examples/UsdPreviewSurface/usd_preview_surface_transparent_int.mtlx b/resources/Materials/Examples/UsdPreviewSurface/usd_preview_surface_transparent_int.mtlx
deleted file mode 100644
index 26b7a1c80c..0000000000
--- a/resources/Materials/Examples/UsdPreviewSurface/usd_preview_surface_transparent_int.mtlx
+++ /dev/null
@@ -1,14 +0,0 @@
-<?xml version="1.0"?>
-<materialx version="1.39" colorspace="lin_rec709">
-  <UsdPreviewSurface name="SR_carpaint" type="surfaceshader">
-    <input name="diffuseColor" type="color3" value="0.0518895, 0.29606, 0.425324" />
-    <input name="roughness" type="float" value="0.4" />
-    <input name="clearcoat" type="float" value="1" />
-    <input name="clearcoatRoughness" type="float" value="0" />
-    <input name="opacity" type="float" value="0.2" />
-    <input name="opacityMode" type="integer" value="0" /> <!-- transparent -->
-  </UsdPreviewSurface>
-  <surfacematerial name="USD_Car_Paint" type="material">
-    <input name="surfaceshader" type="surfaceshader" nodename="SR_carpaint" />
-  </surfacematerial>
-</materialx>
diff --git a/resources/Materials/Examples/UsdPreviewSurface/usd_preview_surface_transparent_string.mtlx b/resources/Materials/Examples/UsdPreviewSurface/usd_preview_surface_transparent_string.mtlx
deleted file mode 100644
index 781953b8e1..0000000000
--- a/resources/Materials/Examples/UsdPreviewSurface/usd_preview_surface_transparent_string.mtlx
+++ /dev/null
@@ -1,14 +0,0 @@
-<?xml version="1.0"?>
-<materialx version="1.39" colorspace="lin_rec709">
-  <UsdPreviewSurface name="SR_carpaint" type="surfaceshader">
-    <input name="diffuseColor" type="color3" value="0.0518895, 0.29606, 0.425324" />
-    <input name="roughness" type="float" value="0.4" />
-    <input name="clearcoat" type="float" value="1" />
-    <input name="clearcoatRoughness" type="float" value="0" />
-    <input name="opacity" type="float" value="0.2" />
-    <input name="opacityMode" type="string" value="transparent" />
-  </UsdPreviewSurface>
-  <surfacematerial name="USD_Car_Paint" type="material">
-    <input name="surfaceshader" type="surfaceshader" nodename="SR_carpaint" />
-  </surfacematerial>
-</materialx>