+ 
-
+
- 
- 
- 
- 
+ 
+ 
+ 
+ 
- 
- 
+ 
+ 
+
**Figure 4:** The Open Chess Set, rendered in Karma XPU for Houdini
-
+
-### Pre-Built Binaries
+## Pre-Built Binaries
The following packages contain pre-built binaries for the latest release, including the MaterialX viewer, Python libraries, and example assets:
@@ -64,7 +76,7 @@ The following packages contain pre-built binaries for the latest release, includ
- [MacOS (Xcode 15, Python 3.12)](https://github.com/AcademySoftwareFoundation/MaterialX/releases/latest/download/MaterialX_MacOS_Xcode_15_Python312.zip)
- [Linux (GCC 14, Python 3.12)](https://github.com/AcademySoftwareFoundation/MaterialX/releases/latest/download/MaterialX_Linux_GCC_14_Python312.zip)
-### Additional Resources
+## Additional Resources
- The [Developer Guide](http://www.materialx.org/docs/api/index.html) contains a developer-oriented overview of MaterialX with API documentation.
- The [Python Scripts](python/Scripts) folder contains standalone examples of MaterialX Python code.
diff --git a/documents/DeveloperGuide/GraphEditor.md b/documents/DeveloperGuide/GraphEditor.md
index aaac7b75a2..394754c309 100644
--- a/documents/DeveloperGuide/GraphEditor.md
+++ b/documents/DeveloperGuide/GraphEditor.md
@@ -2,29 +2,30 @@
The MaterialX Graph Editor is an example application for visualizing, creating, and editing MaterialX graphs. It utilizes the ImGui framework as well as additional ImGui extensions such as the Node Editor.
-### Example Images
+## Example Images
**Figure 1:** MaterialX Graph Editor with procedural marble example
-
-## Building The MaterialX Graph Editor
+
+
+## Building the MaterialX Graph Editor
Select the `MATERIALX_BUILD_GRAPH_EDITOR` option in CMake to build the MaterialX Graph Editor. Installation will copy the **MaterialXGraphEditor** executable to a `/bin` directory within the selected install folder.
-### Summary of Graph Editor Features
+## Summary of Graph Editor Features
-1. **Load Material**: Load a material document in the MTLX format.
-2. **Save Material**: Save out a graph as a mterial document in MTLX format.
-3. **New Material**: Clear all information to set up for the creation of a new material
-4. **Node Property Editor**: View or edit properties of the selected node.
-5. **Render View**: View the rendered material.
+1. **`Load Material`**: Load a material document in the MTLX format.
+2. **`Save Material`**: Save out a graph as a mterial document in MTLX format.
+3. **`New Material`**: Clear all information to set up for the creation of a new material
+4. **`Node Property Editor`**: View or edit properties of the selected node.
+5. **`Render View`**: View the rendered material.
-### Buttons
+## Buttons
-To display a new material and graph, click the `Load Material` button and and navigate to the [Example Materials](../../resources/Materials/Examples) folder, which contains a selection of materials in the MTLX format, and select a document to load. The Graph Editor will display the graph hierarchy of the selected document for visualization and editing.
+To display a new material and graph, click the `Load Material` button and and navigate to the [Materials/Examples](https://github.com/AcademySoftwareFoundation/MaterialX/tree/main/resources/Materials/Examples) folder, which contains a selection of materials in the MTLX format, and select a document to load. The Graph Editor will display the graph hierarchy of the selected document for visualization and editing.
To save out changes to the graphs as MTLX files click the `Save Material` button. This will save the position of the nodes in the graph for future use as well.
-### Editor Window
+## Editor Window
The MaterialX document is displayed as nodes in the Editor window. When a file is intially loaded the material node, surface shader node, and any enclosing nodegraphs will be displayed. Double-clicking on a nodegraph, or any node defined as a subgraph, will display the contents of that graph.
@@ -40,19 +41,19 @@ Another type of node present in the `Add Node` pop-up is the group, or backgroun
To search the editor window for a specific node use `CTRL` + `F` to bring up the search bar.
-### Node Property Editor
+## Node Property Editor
When a node is selected in the graph, its information is displayed on the left-hand column in the `Node Property Editor`. This editor displays the name of the node, its category, its inputs, the input name, types and values. Inputs that are connected to other nodes will not display a value.
This is where a node's properties such as its name and input values can be adjusted. When an input value is changed the material is automatically updated to reflect that change. The node info button displays the `doc` string for the selected node and its inputs if they exist. This `doc` string is currently read only.
The show All Inputs checkbox displays all possible inputs for a node. With the box unchecked only inputs that have a connection or have had a value set will be shown. Only these inputs will be saved out when the graph is saved.
-### Render View
+## Render View
Above the `Node Property Editor`, the `Render View` displays the current material on the Arnold Shader Ball. If inside a subgraph it will display the material associated with that subgraph; otherwise it will display the output of the selected node. It automatically updates when any changes are made to the graph.
To adjust the relative sizes of the Node Property Editor and Render View windows, drag the separator between these windows in the application. The render view window camera can be changed using the left or right mouse buttons to manipulate the shader ball.
-### Keyboard Shortcuts
+## Keyboard Shortcuts
- `TAB`: Add Node Popup
- `Right Click`: pan along the editor
@@ -66,7 +67,7 @@ To adjust the relative sizes of the Node Property Editor and Render View windows
- `+` : Zoom in with the camera when mouse is over the Render View Window.
- `-` : Zoom out with the camera when mouse is over the Render View Window.
-### Command-Line Options
+## Command-Line Options
The following are common command-line options for MaterialXGraphEditor, and a complete list can be displayed with the `--help` option.
- `--material [FILENAME]` : Specify the filename of the MTLX document to be displayed in the graph editor
@@ -75,7 +76,7 @@ The following are common command-line options for MaterialXGraphEditor, and a co
- `--library [FILEPATH]` : Specify an additional data library folder (e.g. 'vendorlib', 'studiolib'). This relative path will be appended to each location in the data search path when loading data libraries.
- `--captureFilename [FILENAME]` : Specify the filename to which the first rendered frame should be written
-### Known Limitations
+## Known Limitations
- Creating new connections using the `channels` attribute of an input is not yet supported, though existing `channels` connections will be displayed in graphs.
- Assigning a new `colorspace` attribute to an input is not yet supported, though existing `colorspace` attributes on inputs will be respected by the render view.
diff --git a/documents/DeveloperGuide/MainPage.md b/documents/DeveloperGuide/MainPage.md
index 9cf0a0d8e0..155c58eb4d 100644
--- a/documents/DeveloperGuide/MainPage.md
+++ b/documents/DeveloperGuide/MainPage.md
@@ -2,14 +2,14 @@
MaterialX is an open standard for representing rich material and look-development content in computer graphics, enabling its platform-independent description and exchange across applications and renderers. Launched at [Industrial Light & Magic](https://www.ilm.com/) in 2012, MaterialX has been a key technology in their feature films and real-time experiences since _Star Wars: The Force Awakens_ and _Millennium Falcon: Smugglers Run_. The project was released as open source in 2017, with companies including Sony Pictures Imageworks, Pixar, Autodesk, Adobe, and SideFX contributing to its ongoing development. In 2021, MaterialX became the seventh hosted project of the [Academy Software Foundation](https://www.aswf.io/).
-### Quick Start for Developers
+## Quick Start for Developers
- Download the latest version of the [CMake](https://cmake.org/) build system.
- Point CMake to the root of the MaterialX library and generate C++ projects for your platform and compiler.
- Select the `MATERIALX_BUILD_PYTHON` option to build Python bindings.
- Select the `MATERIALX_BUILD_VIEWER` option to build the MaterialX viewer.
-### Supported Platforms
+## Supported Platforms
The MaterialX codebase requires a compiler with support for C++17, and can be built with any of the following:
@@ -19,9 +19,9 @@ The MaterialX codebase requires a compiler with support for C++17, and can be bu
The Python bindings for MaterialX are based on [PyBind11](https://github.com/pybind/pybind11), and support Python versions 3.6 and greater.
-### Building MaterialX
+## Building MaterialX
-#### Building MaterialX C++
+### Building MaterialX C++
The MaterialX C++ libraries are automatically included when building MaterialX through CMake.
@@ -32,7 +32,7 @@ To enable OpenImageIO support in MaterialX builds, the following additional opti
See the [MaterialX Unit Tests](https://github.com/AcademySoftwareFoundation/MaterialX/tree/main/source/MaterialXTest) page for documentation on shader generation and render testing in GLSL, OSL, and MDL.
-#### Building MaterialX Python
+### Building MaterialX Python
By default, the `MATERIALX_BUILD_PYTHON` option will use the active version of Python in the developer's path. To select a specific version of Python, use one or more of the following advanced options:
@@ -44,32 +44,32 @@ Additional options for the generation of MaterialX Python include the following:
- `MATERIALX_PYTHON_OCIO_DIR`: Path to a folder containing the default OCIO configuration to be packaged with MaterialX Python. The recommended OpenColorIO configuration for MaterialX is [ACES 1.2](https://github.com/colour-science/OpenColorIO-Configs/tree/feature/aces-1.2-config/aces_1.2).
- `MATERIALX_PYTHON_PYBIND11_DIR`: Path to a folder containing the PyBind11 source to be used in building MaterialX Python. Defaults to the included PyBind11 source.
-#### Building The MaterialX Viewer
+### Building The MaterialX Viewer
-Select the `MATERIALX_BUILD_VIEWER` option to build the MaterialX Viewer. Installation will copy the **MaterialXView** executable to a `bin/` directory within the selected install folder.
+Select the `MATERIALX_BUILD_VIEWER` option to build the MaterialX Viewer. Installation will copy the `MaterialXView` executable to a `bin/` directory within the selected install folder.
-#### Building API Documentation
+### Building API Documentation
To generate HTML documentation for the MaterialX C++ API, make sure a version of [Doxygen](https://www.doxygen.org/) is on your path, and select the advanced option `MATERIALX_BUILD_DOCS` in CMake. This option will add a target named `MaterialXDocs` to your project, which can be built as an independent step from your development environment.
-### Installing MaterialX
+## Installing MaterialX
Building the `install` target of your project will install the MaterialX C++ and Python libraries to the folder specified by the `CMAKE_INSTALL_PREFIX` setting, and will install MaterialX Python as a third-party library in your Python environment. Installation of MaterialX Python as a third-party library can be disabled by setting `MATERIALX_INSTALL_PYTHON` to `OFF`.
-### MaterialX Versioning
+## MaterialX Versioning
-The MaterialX codebase uses a modified semantic versioning system where the *major* and *minor* versions match that of the corresponding MaterialX [specification](https://github.com/AcademySoftwareFoundation/MaterialX/blob/main/documents/Specification/MaterialX.Specification.md), and the *build* version represents engineering advances within that specification version. MaterialX documents are similarly marked with the specification version they were authored in, and they are valid to load into any MaterialX codebase with an equal or higher specification version.
+The MaterialX codebase uses a modified semantic versioning system where the *major* and *minor* versions match that of the corresponding [MaterialX Specification](https://materialx.org/Specification.html), and the *build* version represents engineering advances within that specification version. MaterialX documents are similarly marked with the specification version they were authored in, and they are valid to load into any MaterialX codebase with an equal or higher specification version.
-Upgrading of MaterialX documents from earlier versions is handled at import time by the `Document::upgradeVersion` method, which applies the syntax and node interface upgrades that have occurred in previous specification revisions. This allows the syntax conventions of MaterialX and the names and interfaces of nodes to evolve over time, without invalidating documents from earlier versions.
+Upgrading of MaterialX documents from earlier versions is handled at import time by the `Document::upgradeVersion()` method, which applies the syntax and node interface upgrades that have occurred in previous specification revisions. This allows the syntax conventions of MaterialX and the names and interfaces of nodes to evolve over time, without invalidating documents from earlier versions.
-#### MaterialX API Changes
+### MaterialX API Changes
The following rules describe the categories of changes to the [MaterialX API](https://materialx.org/docs/api/classes.html) that are allowed in version upgrades:
- In *build* version upgrades, only non-breaking changes to the MaterialX API are allowed. For any API call that is modified in a build version upgrade, backwards compatibility should be maintained using deprecated C++ and Python wrappers for the original API call.
- In *minor* and *major* version upgrades, breaking changes to the MaterialX API are allowed, though their benefit should be carefully weighed against their cost. Any breaking changes to API calls should be highlighted in the release notes for the new version.
-#### MaterialX Data Library Changes
+### MaterialX Data Library Changes
The following rules describe the categories of changes to the [MaterialX Data Libraries](https://github.com/AcademySoftwareFoundation/MaterialX/tree/main/libraries) that are allowed in version upgrades:
@@ -77,7 +77,7 @@ The following rules describe the categories of changes to the [MaterialX Data Li
- In *minor* version upgrades, changes to the names and interfaces of MaterialX nodes are allowed, with the requirement that version upgrade logic be used to maintain the validity and visual interpretation of documents from earlier versions.
- In *major* version upgrades, changes to the syntax rules of MaterialX documents are allowed, with the requirement that version upgrade logic be used to maintain the validity and visual interpretation of documents from earlier versions. These changes usually require synchronized updates to both the MaterialX API and data libraries.
-### Additional Links
+## Additional Links
- The main [MaterialX website](http://www.materialx.org) provides background on the project's history, industry collaborations, and recent presentations.
- The [Python Scripts](https://github.com/materialx/MaterialX/tree/main/python/Scripts) folder contains standalone examples of MaterialX Python code.
diff --git a/documents/DeveloperGuide/ShaderGeneration.md b/documents/DeveloperGuide/ShaderGeneration.md
index 01bd823ec4..594715fb39 100644
--- a/documents/DeveloperGuide/ShaderGeneration.md
+++ b/documents/DeveloperGuide/ShaderGeneration.md
@@ -1,13 +1,13 @@
# Shader Generation
## 1.1 Scope
-A shader generation framework is implemented as part of MaterialX. This can help applications to transform the agnostic MaterialX data description into executable shader code for a specific renderer. A library module named MaterialXGenShader contains the core shader generation features, and support for specific languages resides in separate libraries, e.g. [MaterialXGenGlsl](/source/MaterialXGenGlsl), [MaterialXGenOsl](/source/MaterialXGenOsl).
+A shader generation framework is implemented as part of MaterialX. This can help applications to transform the agnostic MaterialX data description into executable shader code for a specific renderer. A library module named MaterialXGenShader contains the core shader generation features, and support for specific languages resides in separate libraries, e.g. [MaterialXGenGlsl](https://github.com/AcademySoftwareFoundation/MaterialX/tree/main/source/MaterialXGenGlsl), [MaterialXGenOsl](https://github.com/AcademySoftwareFoundation/MaterialX/tree/main/source/MaterialXGenOsl).
Note that this system has no runtime and the output produced is source code, not binary executable code. The source code produced needs to be compiled by a shading language compiler before being executed by the renderer. See Figure 1 for a high level overview of the system.
-
+
-**Figure 1**: Shader generation with multiple shader generators.
+**Figure 1:** Shader generation with multiple shader generators.
## 1.2 Languages and Shader Generators
The MaterialX description is free from device specific details and all implementation details needs to be taken care of by shader generators. There is one shader generator for each supported shading language. However for each language there can also be variations needed for different renderers. For example; OpenGL renderers supporting GLSL can use forward rendering or deferred rendering, each with very different requirements for how the shaders are constructed. Another example is different renderers supporting OSL but with different sets of closures or closure parameters. Hence a separate shader generator can be defined for each language/target combination.
@@ -28,11 +28,11 @@ In the following sub-sections each of these methods are explained. For all metho
### 1.3.1 Inline Expression
Provided code generators support a very simple expression language for inlining code. This is useful for simple nodes where the operation can be expressed as a single line of code. Inlining will reduce the number of function calls and produce more compact code. The syntax to use is the same as the target shading language, with the addition of using the node’s input ports as variables wrapped in double curly brackets: `{{input}}`. The code generator will replace these variables with values assigned or connected to the respective inputs. Figure 2 gives an example.
-Connecting the expression to the nodedef is done using an `
- 
- 
- 
- 
+
+
+
+
- 
- 
+
+