docs: add --report output reference with shader gen transparency analysis

Comprehensive documentation of the --report JSON output format, covering:
- JSON schema for validation errors and renderable analysis
- How isTransparentSurface() works and its concrete rendering impact
- Lit vs unlit surface shader alpha code paths
- The hint system for custom nodedef transparency inputs
- Two distinct threshold mechanisms: alpha_cutoff (graph-level) vs u_alphaThreshold (render-time)
- Per-shader alpha mode detection (gltf_pbr, UsdPreviewSurface, standard_surface, open_pbr_surface, surface_unlit)
- Surface shader nodedef reference table
- Cutout roundtrip validation guide

feat: add --report flag with structured validation and renderable analysis

Add --report [text|json] to MaterialXView and MaterialXGraphEditor for headless material validation and shader analysis. Includes ValidationError structs, RenderableAnalysis with shaderNode/shaderNodeDef/shaderNodeDefVersion/isUnlit/transparency/alphaMode/alphaCutoff/transparencyInputs, per-shader alpha mode detection (gltf_pbr 3 modes, UsdPreviewSurface cutout-only, hint-based open_pbr), and materialXVersion at root level.

refactor again to clean up and minimize code impact

Author: hybridherbst

.gitignore

@@ -1,3 +1,5 @@
 build
 dist
 .DS_Store
+python/MaterialX/__pycache__
+python/MaterialX/*.so

source/MaterialXCore/Element.cpp

@@ -12,6 +12,11 @@
 
 MATERIALX_NAMESPACE_BEGIN
 
+namespace
+{
+thread_local Element::ValidationErrors* g_validationErrors = nullptr;
+} // anonymous namespace
+
 const string Element::NAME_ATTRIBUTE = "name";
 const string Element::FILE_PREFIX_ATTRIBUTE = "fileprefix";
 const string Element::GEOM_PREFIX_ATTRIBUTE = "geomprefix";
@@ -627,9 +632,87 @@ void Element::validateRequire(bool expression, bool& res, string* message, const
         res = false;
         if (message)
         {
-            *message += errorDesc + ": " + asString() + "\n";
+            string location = getNamePath();
+            const string& sourceUri = getActiveSourceUri();
+            if (!sourceUri.empty())
+            {
+                location += " (file=" + sourceUri + ")";
+            }
+            *message += errorDesc + " at " + location + ": " + asString() + "\n";
+        }
+        if (g_validationErrors)
+        {
+            ValidationError err;
+            err.message = errorDesc;
+            err.path = getNamePath();
+            err.source = asString();
+            err.file = getActiveSourceUri();
+            err.severity = ValidationSeverity::ERROR;
+            g_validationErrors->push_back(err);
+        }
+    }
+}
+
+Element::ValidationErrorScope::ValidationErrorScope(ValidationErrors* errors)
+{
+    _prev = g_validationErrors;
+    g_validationErrors = errors;
+}
+
+Element::ValidationErrorScope::~ValidationErrorScope()
+{
+    g_validationErrors = _prev;
+}
+
+const char* Element::validationSeverityToString(ValidationSeverity severity)
+{
+    switch (severity)
+    {
+        case ValidationSeverity::ERROR: return "error";
+        case ValidationSeverity::WARNING: return "warning";
+        case ValidationSeverity::HINT: return "hint";
+        default: return "error";
+    }
+}
+
+string Element::formatValidationErrorsJson(const ValidationErrors& errors)
+{
+    string json = "[";
+    for (size_t i = 0; i < errors.size(); i++)
+    {
+        if (i > 0)
+        {
+            json += ",";
+        }
+        json += "{\"message\":\"" + escapeJsonString(errors[i].message) + "\"";
+        json += ",\"path\":\"" + escapeJsonString(errors[i].path) + "\"";
+        json += ",\"source\":\"" + escapeJsonString(errors[i].source) + "\"";
+        json += ",\"file\":\"" + escapeJsonString(errors[i].file) + "\"";
+        json += ",\"severity\":\"" + string(validationSeverityToString(errors[i].severity)) + "\"}";
+    }
+    json += "]";
+    return json;
+}
+
+string Element::escapeJsonString(const string& input)
+{
+    string out;
+    out.reserve(input.size());
+    for (char c : input)
+    {
+        switch (c)
+        {
+            case '"': out += "\\\""; break;
+            case '\\': out += "\\\\"; break;
+            case '\b': out += "\\b"; break;
+            case '\f': out += "\\f"; break;
+            case '\n': out += "\\n"; break;
+            case '\r': out += "\\r"; break;
+            case '\t': out += "\\t"; break;
+            default: out += c; break;
         }
     }
+    return out;
 }
 
 //

source/MaterialXCore/Element.h

@@ -15,6 +15,8 @@
 #include <MaterialXCore/Util.h>
 #include <MaterialXCore/Value.h>
 
+#include <vector>
+
 MATERIALX_NAMESPACE_BEGIN
 
 class Element;
@@ -754,6 +756,40 @@ class MX_CORE_API Element : public std::enable_shared_from_this<Element>
     /// @name Validation
     /// @{
 
+    enum class ValidationSeverity
+    {
+        ERROR,
+        WARNING,
+        HINT
+    };
+
+    struct ValidationError
+    {
+        string message;
+        string path;
+        string source;
+        string file;
+        ValidationSeverity severity = ValidationSeverity::ERROR;
+    };
+
+    using ValidationErrors = vector<ValidationError>;
+
+    class MX_CORE_API ValidationErrorScope
+    {
+        public:
+            explicit ValidationErrorScope(ValidationErrors* errors);
+            ~ValidationErrorScope();
+
+        private:
+            ValidationErrors* _prev = nullptr;
+    };
+
+    static const char* validationSeverityToString(ValidationSeverity severity);
+    static string formatValidationErrorsJson(const ValidationErrors& errors);
+
+    /// Escape a string for safe inclusion in JSON output.
+    static string escapeJsonString(const string& input);
+
     /// Validate that the given element tree, including all descendants, is
     /// consistent with the MaterialX specification.
     virtual bool validate(string* message = nullptr) const;