Add Perfetto tracing and a test output directory option (#2742)

This PR adds a new `MaterialXTrace` module with optional Perfetto tracing infrastructure, plus a configurable test output directory, laying the groundwork for performance analysis and optimization work.

Author: ppenenko

.github/workflows/main.yml

@@ -31,6 +31,7 @@ jobs:
           compiler: gcc
           compiler_version: "14"
           python: 3.13
+          extended_build_perfetto: ON
 
         - name: Linux_GCC_14_Python314
           os: ubuntu-24.04
@@ -206,6 +207,9 @@ jobs:
           if [ "${{ matrix.extended_build_mdl_sdk }}" == "ON" -a "${{ runner.os }}" == "Windows" ]; then
             EXTENDED_BUILD_CONFIG="$EXTENDED_BUILD_CONFIG -DVCPKG_TARGET_TRIPLET=x64-windows-release -DMATERIALX_MDL_SDK_DIR=C:/vcpkg/installed/x64-windows-release"
           fi
+          if [ "${{ matrix.extended_build_perfetto }}" == "ON" ]; then
+            EXTENDED_BUILD_CONFIG="$EXTENDED_BUILD_CONFIG -DMATERIALX_BUILD_PERFETTO_TRACING=ON"
+          fi
         fi
         TEST_RENDER_CONFIG="-DMATERIALX_TEST_RENDER=OFF"
         if [ "${{ matrix.test_render }}" == "ON" ]; then
@@ -266,7 +270,7 @@ jobs:
       run: |
         sudo apt-get install gcovr
         mkdir coverage
-        gcovr --html --html-details --output coverage/index.html --exclude .*\/External\/.* --root .. .
+        gcovr --html --html-details --output coverage/index.html --exclude .*\/External\/.* --exclude .*perfetto.* --root .. .
       working-directory: build
 
     - name: Static Analysis Tests
@@ -277,7 +281,7 @@ jobs:
         else
           brew install cppcheck
         fi
-        cppcheck --project=build/compile_commands.json --error-exitcode=1 --suppress=normalCheckLevelMaxBranches --suppress=*:*/External/* --suppress=*:*/NanoGUI/*
+        cppcheck --project=build/compile_commands.json --error-exitcode=1 --suppress=normalCheckLevelMaxBranches --suppress=*:*/External/* --suppress=*:*/NanoGUI/* --suppress=*:*perfetto*
 
     - name: Setup Rendering Environment (Linux)
       if: matrix.test_render == 'ON' && runner.os == 'Linux'
@@ -358,6 +362,14 @@ jobs:
         name: MaterialX_Coverage
         path: build/coverage
 
+    - name: Upload Perfetto Traces
+      uses: actions/upload-artifact@v4
+      if: matrix.extended_build_perfetto == 'ON' && env.IS_EXTENDED_BUILD == 'true'
+      with:
+        name: Traces_${{ matrix.name }}
+        path: build/**/*.perfetto-trace
+        if-no-files-found: ignore
+
   javascript:
     name: JavaScript
     runs-on: ubuntu-latest

CMakeLists.txt

@@ -51,6 +51,7 @@ option(MATERIALX_BUILD_OCIO "Build OpenColorIO support for shader generators." O
 option(MATERIALX_BUILD_TESTS "Build unit tests." OFF)
 option(MATERIALX_BUILD_BENCHMARK_TESTS "Build benchmark tests." OFF)
 option(MATERIALX_BUILD_OSOS "Build OSL .oso's of standard library shaders for the OSL Network generator" OFF)
+option(MATERIALX_BUILD_PERFETTO_TRACING "Build with Perfetto tracing support for performance analysis." OFF)
 
 option(MATERIALX_BUILD_SHARED_LIBS "Build MaterialX libraries as shared rather than static." OFF)
 option(MATERIALX_BUILD_DATA_LIBRARY "Build generated products from the MaterialX data library." OFF)
@@ -228,6 +229,41 @@ mark_as_advanced(MATERIALX_MDL_BINARY_TESTRENDER)
 mark_as_advanced(MATERIALX_MDL_MODULE_PATHS)
 mark_as_advanced(MATERIALX_MDL_SDK_DIR)
 mark_as_advanced(MATERIALX_SLANG_RHI_SOURCE_DIR)
+mark_as_advanced(MATERIALX_BUILD_PERFETTO_TRACING)
+
+# Perfetto tracing support
+if(MATERIALX_BUILD_PERFETTO_TRACING)
+    include(FetchContent)
+    FetchContent_Declare(
+        perfetto
+        GIT_REPOSITORY https://android.googlesource.com/platform/external/perfetto
+        GIT_TAG v43.0
+        GIT_SHALLOW TRUE
+    )
+    # Only fetch the SDK, not the full Perfetto source
+    set(PERFETTO_SDK_INCLUDE_DIR "${CMAKE_BINARY_DIR}/_deps/perfetto-src/sdk")
+    FetchContent_MakeAvailable(perfetto)
+    add_definitions(-DMATERIALX_BUILD_PERFETTO_TRACING)
+    
+    # Define compile flags for perfetto.cc (Perfetto SDK triggers various warnings)
+    # These variables are used in source/CMakeLists.txt (monolithic) and MaterialXTrace (non-monolithic)
+    # Note: set_source_files_properties is directory-scoped, so we define variables here
+    # but apply them in the directories where targets are created.
+    if(MSVC)
+        set(MATERIALX_PERFETTO_COMPILE_DEFINITIONS "NOMINMAX;WIN32_LEAN_AND_MEAN" CACHE INTERNAL "")
+        # /bigobj: perfetto.cc has too many sections for default MSVC object format
+        # /W0: disable all warnings for third-party Perfetto SDK code
+        # /WX-: disable warnings-as-errors (overrides project-level /WX)
+        set(MATERIALX_PERFETTO_COMPILE_FLAGS "/bigobj /W0 /WX-" CACHE INTERNAL "")
+    else()
+        set(MATERIALX_PERFETTO_COMPILE_DEFINITIONS "" CACHE INTERNAL "")
+        # -Wno-error: Don't treat warnings as errors (Perfetto has shadowing issues)
+        # -Wno-shadow: Suppress shadow warnings (kDevNull shadows global)
+        set(MATERIALX_PERFETTO_COMPILE_FLAGS "-Wno-error -Wno-shadow" CACHE INTERNAL "")
+    endif()
+    
+    message(STATUS "Perfetto tracing support enabled")
+endif()
 
 if (MATERIALX_BUILD_USE_CCACHE)
     # Setup CCache for C/C++ compilation
@@ -491,6 +527,9 @@ endif()
 # Add core subdirectories
 add_subdirectory(source/MaterialXCore)
 add_subdirectory(source/MaterialXFormat)
+if(MATERIALX_BUILD_PERFETTO_TRACING)
+    add_subdirectory(source/MaterialXTrace)
+endif()
 
 # Add shader generation subdirectories
 add_subdirectory(source/MaterialXGenShader)

resources/Materials/TestSuite/_options.mtlx

@@ -70,5 +70,19 @@
          but requiring a more powerful GPU and longer CPU render times.
     -->
     <input name="enableReferenceQuality" type="boolean" value="false" />
+
+    <!-- Base directory for all test output artifacts (shaders, images, logs).
+         If empty (default), artifacts are written to their default locations
+         (CWD for logs, alongside source materials for shaders/images).
+         Supports absolute paths or paths relative to the test working directory.
+         The directory will be created if it doesn't exist.
+    -->
+    <input name="outputDirectory" type="string" value="" />
+
+    <!-- Enable Perfetto tracing during render tests (requires MATERIALX_BUILD_TRACING).
+         When enabled, generates .perfetto-trace files in outputDirectory.
+         Default is false to avoid overhead when not profiling.
+    -->
+    <input name="enableTracing" type="boolean" value="true" />
   </nodedef>
 </materialx>

source/CMakeLists.txt

@@ -5,6 +5,15 @@ if (MATERIALX_BUILD_MONOLITHIC)
     # such that the individual module would have been built if not in monolithic build mode
     add_library(${MATERIALX_MODULE_NAME} "" "" )
 
+    # Apply Perfetto compile flags for monolithic builds
+    # (set_source_files_properties is directory-scoped, must be called here)
+    if(MATERIALX_BUILD_PERFETTO_TRACING)
+        set_source_files_properties("${perfetto_SOURCE_DIR}/sdk/perfetto.cc"
+            PROPERTIES
+            COMPILE_DEFINITIONS "${MATERIALX_PERFETTO_COMPILE_DEFINITIONS}"
+            COMPILE_FLAGS "${MATERIALX_PERFETTO_COMPILE_FLAGS}")
+    endif()
+
     set_target_properties(${MATERIALX_MODULE_NAME} PROPERTIES CXX_VISIBILITY_PRESET hidden)
     set_target_properties(${MATERIALX_MODULE_NAME} PROPERTIES CMAKE_VISIBILITY_INLINES_HIDDEN 1)
 

source/MaterialXTest/CMakeLists.txt

@@ -40,6 +40,9 @@ add_subdirectory(MaterialXCore)
 target_link_libraries(MaterialXTest MaterialXCore)
 add_subdirectory(MaterialXFormat)
 target_link_libraries(MaterialXTest MaterialXFormat)
+if(MATERIALX_BUILD_PERFETTO_TRACING)
+    target_link_libraries(MaterialXTest MaterialXTrace)
+endif()
 
 add_subdirectory(MaterialXGenShader)
 target_link_libraries(MaterialXTest MaterialXGenShader)

source/MaterialXTest/MaterialXGenShader/GenShaderUtil.cpp

@@ -23,7 +23,10 @@
 #include <MaterialXCore/Material.h>
 #include <MaterialXCore/Unit.h>
 
+#include <MaterialXTrace/Tracing.h>
+
 #include <iostream>
+#include <optional>
 
 namespace mx = MaterialX;
 
@@ -652,24 +655,36 @@ void ShaderGeneratorTester::registerLights(mx::DocumentPtr doc, const std::vecto
 
 void ShaderGeneratorTester::validate(const mx::GenOptions& generateOptions, const std::string& optionsFilePath)
 {
-    // Start logging
-    _logFile.open(_logFilePath);
-
-    // Check for an option file
+    // Check for an option file first (before opening log) so we can use outputDirectory
     TestSuiteOptions options;
     if (!options.readOptions(optionsFilePath))
     {
-        _logFile << "Cannot read options file: " << optionsFilePath << ". Skipping test." << std::endl;
-        _logFile.close();
+        std::cerr << "Cannot read options file: " << optionsFilePath << ". Skipping test." << std::endl;
         return;
     }
     // Test has been turned off so just do nothing.
     if (!runTest(options))
     {
-        _logFile << "Target: " << _targetString << " not set to run. Skipping test." << std::endl;
-        _logFile.close();
+        std::cerr << "Target: " << _targetString << " not set to run. Skipping test." << std::endl;
         return;
     }
+
+#ifdef MATERIALX_BUILD_PERFETTO_TRACING
+    // Set up Perfetto tracing if enabled
+    std::optional<mx::Tracing::Dispatcher::ShutdownGuard> tracingGuard;
+    if (options.enableTracing)
+    {
+        mx::FilePath tracePath = options.resolveOutputPath(_shaderGenerator->getTarget() + "_gen_trace.perfetto-trace");
+        mx::Tracing::Dispatcher::getInstance().setSink(
+            mx::Tracing::createPerfettoSink(tracePath.asString()));
+        tracingGuard.emplace();
+    }
+#endif
+
+    // Start logging - use outputDirectory if set
+    mx::FilePath logPath = options.resolveOutputPath(_logFilePath);
+    _logFile.open(logPath.asString());
+
     options.print(_logFile);
 
     // Add files to override the files in the test suite to be examined.
@@ -839,7 +854,11 @@ void ShaderGeneratorTester::validate(const mx::GenOptions& generateOptions, cons
                     _logFile << "------------ Run validation with element: " << namePath << "------------" << std::endl;
 
                     mx::StringVec sourceCode;
-                    const bool generatedCode = generateCode(context, elementName, element, _logFile, _testStages, sourceCode);
+                    bool generatedCode = false;
+                    {
+                        MX_TRACE_SCOPE(mx::Tracing::Category::ShaderGen, elementName.c_str());
+                        generatedCode = generateCode(context, elementName, element, _logFile, _testStages, sourceCode);
+                    }
 
                     // Record implementations tested
                     if (options.checkImplCount)
@@ -879,6 +898,17 @@ void ShaderGeneratorTester::validate(const mx::GenOptions& generateOptions, cons
                             path = searchPath.isEmpty() ? mx::FilePath() : searchPath[0];
                         }
 
+                        // Redirect to outputDirectory if set
+                        if (!options.outputDirectory.isEmpty())
+                        {
+                            mx::FilePath materialDir = path.getBaseName();
+                            path = options.outputDirectory / materialDir;
+                            if (!path.exists())
+                            {
+                                path.createDirectory();
+                            }
+                        }
+
                         std::vector<mx::FilePath> sourceCodePaths;
                         if (sourceCode.size() > 1)
                         {
@@ -939,6 +969,12 @@ void ShaderGeneratorTester::validate(const mx::GenOptions& generateOptions, cons
     {
         _logFile.close();
     }
+
+    // Print effective output directory for easy access (clickable in terminals)
+    if (!options.outputDirectory.isEmpty())
+    {
+        std::cout << std::endl << "Test artifacts written to: " << options.outputDirectory.asString() << std::endl;
+    }
 }
 
 void TestSuiteOptions::print(std::ostream& output) const
@@ -968,6 +1004,8 @@ void TestSuiteOptions::print(std::ostream& output) const
     output << "\tExtra library paths: " << extraLibraryPaths.asString() << std::endl;
     output << "\tRender test paths: " << renderTestPaths.asString() << std::endl;
     output << "\tEnable Reference Quality: " << enableReferenceQuality << std::endl;
+    output << "\tOutput Directory: " << (outputDirectory.isEmpty() ? "(default)" : outputDirectory.asString()) << std::endl;
+    output << "\tEnable Tracing: " << enableTracing << std::endl;
 }
 
 bool TestSuiteOptions::readOptions(const std::string& optionFile)
@@ -993,6 +1031,8 @@ bool TestSuiteOptions::readOptions(const std::string& optionFile)
     const std::string EXTRA_LIBRARY_PATHS("extraLibraryPaths");
     const std::string RENDER_TEST_PATHS("renderTestPaths");
     const std::string ENABLE_REFERENCE_QUALITY("enableReferenceQuality");
+    const std::string OUTPUT_DIRECTORY_STRING("outputDirectory");
+    const std::string ENABLE_TRACING_STRING("enableTracing");
 
     overrideFiles.clear();
     dumpGeneratedCode = false;
@@ -1091,6 +1131,23 @@ bool TestSuiteOptions::readOptions(const std::string& optionFile)
                     {
                         enableReferenceQuality = val->asA<bool>();
                     }
+                    else if (name == OUTPUT_DIRECTORY_STRING)
+                    {
+                        std::string dirPath = p->getValueString();
+                        if (!dirPath.empty())
+                        {
+                            outputDirectory = mx::FilePath(dirPath);
+                            // Create the directory if it doesn't exist
+                            if (!outputDirectory.exists())
+                            {
+                                outputDirectory.createDirectory();
+                            }
+                        }
+                    }
+                    else if (name == ENABLE_TRACING_STRING)
+                    {
+                        enableTracing = val->asA<bool>();
+                    }
                 }
             }
         }

source/MaterialXTest/MaterialXGenShader/GenShaderUtil.h

@@ -118,6 +118,27 @@ class TestSuiteOptions
     // Enable reference quality rendering. Default is false.
     bool enableReferenceQuality;
 
+    // Base directory for all test output artifacts (shaders, images, logs).
+    // If empty, use default locations. If set, all artifacts go to this directory.
+    mx::FilePath outputDirectory;
+
+    // Enable Perfetto tracing during render tests (requires MATERIALX_BUILD_PERFETTO_TRACING).
+    // Default is false to avoid overhead when not profiling.
+    bool enableTracing = false;
+
+    // Helper to resolve output path for an artifact.
+    // If outputDirectory is set, returns outputDirectory/filename.
+    // Otherwise returns the original path unchanged.
+    mx::FilePath resolveOutputPath(const mx::FilePath& path) const
+    {
+        if (outputDirectory.isEmpty())
+        {
+            return path;
+        }
+        // Extract just the filename and place it in outputDirectory
+        return outputDirectory / path.getBaseName();
+    }
+
     // Bake parameters
     struct BakeSetting
     {