Implementation

Insight into how this site was generated is shown here to demonstrate how a user can enhance documentation and learning workflows for MaterialX by adding tools on top of MaterialX itself. The following color coding is used in the diagrams provided:

  • Red: Items not available in core or not started yet
  • Orange: Items in progress
  • Blue: Items which are available as part of MaterialX core
  • Green: Items available as additional tools

Note that something like 'Doxygen' was tried but not used as it was not flexible enough to generated the customizations required of an shader node library. One alternative was to generate actual C++ or Python classes for node definitions and run Doxygen. This is a possible project but is not being pursued at the current time.

Overview

The following diagram outlines the setup for generating documentation from MaterialX. The main utilities were written using the Python wrappers for MaterialX:

  • Diagram generation ('mxgraphio'): This can produce Mermaid diagrams based on MaterialX input. The standard library graphs are generated this way, but any MaterialX graph can be used as input.

  • Sampling graphs for rendering ('genMaterialsFromDefs'): All definitions in the MaterialX library had instance graphs created as separate MaterialX files. These files are rendered using the custom GLSL Python renderer (`mxrenderer`) provided on this site via the `renderDocuments` Python utility command.
    Note that any renderer that can consume MaterialX can be used.

  • Documentation and indexing generation ('mxdoclib'): This extracted al data from the MaterialX definition libraries to generate all library pages. images were converted to webp for non-rendered images using Google cwebp utility. Both Markdown and HTML output is supported.

    Dependents such as 'Bootstrap', 'Mermaid' 'model-viewer', and 'Google Fonts' are automatically included.

  • Document comparison: This utility ('compareVersions') analyzes the differences between two MaterialX set of definition libraries and generates Markdown or HTML output. The HTML output is available under the Reference->Library Revisions menu.

  • Interactive Viewing: Currently both direct MaterialX as well as glTF versions of MaterialX shaders is under investigation. As the goal is to have an interactive viewer the native viewing will be the target. Currently only glTF PBR is available for viewing with a few input parameters available for editing.

These utilities are accessible from the "Utilities" section of this site and added to MaterialX core distribution.


Web Utilities

A number of Javascript utilities were written to handle:

  • Graph Rendering: Additional Javascript logic is added as part of the generation process. Interactive Mermaid graph (svg) generation from text was added as the performance cost to generate all hundreds of graphs can slow down page load speed. It was additionally necessary to workaround a Bootstrap / Mermaid issue where graphs under hidden elements don't render properly -- in which case all tab sections on documentation pages require dynamic generation. The same logic is used for the 'Graph Visualizer' utility.

  • Node Definition Creation: Simple utilities for creating definitions from nodegraphs is used for the corresponding utility pages.
  • Graph Copying / Saving: Graph text copying utilities were added to allow extraction of the mermaid text and for conversion from Mermaid text to SVG.

Overview

For API learning, the setup is shown below, with the ability to host interactive tutorials and utilities using MaterialX either: via Jupyter notebooks and directly on via Web pages.

Executable notebooks have been exported to both HTML and Python for availability for off-line usage. HTML references are accessible under the "Examples" menu, and Python examples via the site's Github repository.

Local interactive sessions can run using these notebooks currently. ability to host remotely via Google Colab, VSCode / Github code spaces.

Web based utilities are use enhanced core and additional utility MaterialX Javascript modules to provide core, graph, shading and rendering. The core module is available separately from code generation online starting with version 1.38.9.

Possible future tracks that folks could explore include: interactive Python on Web pages, and Jupyter notebooks using Javascript (using Node.js).