Merge

CHANGELOG.md

@@ -2,6 +2,42 @@
 
 ## [1.38.9] - Development
 
+### Added
+
+- Added a [non-photorealistic rendering](https://github.com/AcademySoftwareFoundation/MaterialX/pull/1631) data library to MaterialX, initially supporting the 'viewdirection' and 'facingratio' nodes.
+- Added support for the generation of [pre-filtered environment maps](https://github.com/AcademySoftwareFoundation/MaterialX/pull/1420) in MaterialX GLSL and MSL.
+- Added support for the [creatematrix node](https://github.com/AcademySoftwareFoundation/MaterialX/pull/1553) in shader generation.
+- Added [floating popups](https://github.com/AcademySoftwareFoundation/MaterialX/pull/1565) for hovered pins in the MaterialX Graph Editor.
+- Added support for [UI attributes](https://github.com/AcademySoftwareFoundation/MaterialX/pull/1623) and [enumerated values](https://github.com/AcademySoftwareFoundation/MaterialX/pull/1632) in the MaterialX Web Viewer.
+- Added [UI ranges](https://github.com/AcademySoftwareFoundation/MaterialX/pull/1646) to the 'useSpecularWorkflow' and 'normal' inputs of the UsdPreviewSurface shading model.
+- Added [versioning rules](https://github.com/AcademySoftwareFoundation/MaterialX/pull/1664) for the MaterialX API and data libraries to the developer guide.
+- Added initial C++ [fuzz tests](https://github.com/AcademySoftwareFoundation/MaterialX/pull/1605) and [coverage tests](https://github.com/AcademySoftwareFoundation/MaterialX/pull/1548) to GitHub Actions CI.
+- Added [GCC 13, Clang 15](https://github.com/AcademySoftwareFoundation/MaterialX/pull/1602), and [Python 3.12](https://github.com/AcademySoftwareFoundation/MaterialX/pull/1588) builds to GitHub Actions CI.
+
+### Changed
+
+- Improved the logic for [connecting pins](https://github.com/AcademySoftwareFoundation/MaterialX/pull/1569) in the MaterialX Graph Editor.
+- Improved the robustness of [type pointer comparisons](https://github.com/AcademySoftwareFoundation/MaterialX/pull/1665) in shader generation.
+- Improved the handling of [filename inputs](https://github.com/AcademySoftwareFoundation/MaterialX/pull/1547) in OSL shader generation.
+- Reduced the size of the MaterialX data libraries, improving the use of [graph definitions](https://github.com/AcademySoftwareFoundation/MaterialX/pull/1653) and merging [duplicate implementations](https://github.com/AcademySoftwareFoundation/MaterialX/pull/1642).
+- Updated the MaterialX Web Viewer to [three.js r152](https://github.com/AcademySoftwareFoundation/MaterialX/pull/1615).
+- Switched to a more efficient representation of [HDR images](https://github.com/AcademySoftwareFoundation/MaterialX/pull/1616) in the MaterialX Web Viewer.
+- Raised the minimum CMake version to [CMake 3.16](https://github.com/AcademySoftwareFoundation/MaterialX/pull/1607).
+- Updated the C++ unit test library to [Catch 2.13.10](https://github.com/AcademySoftwareFoundation/MaterialX/pull/1566).
+
+### Fixed
+
+- Fixed the attenuation of [coated emission](https://github.com/AcademySoftwareFoundation/MaterialX/pull/1534) in the Standard Surface shading model.
+- Fixed the implementation of the [overlay node](https://github.com/AcademySoftwareFoundation/MaterialX/pull/1539) in shader generation.
+- Fixed an edge case for [transform nodes](https://github.com/AcademySoftwareFoundation/MaterialX/pull/1560) in GLSL and MSL shader generation.
+- Fixed the implementation of [mx_hsvtorgb](https://github.com/AcademySoftwareFoundation/MaterialX/pull/1584) in MDL shader generation.
+- Fixed [scroll wheel interactions](https://github.com/AcademySoftwareFoundation/MaterialX/pull/1578) across windows of the MaterialX Graph Editor.
+- Fixed the generation of unused [imgui.ini files](https://github.com/AcademySoftwareFoundation/MaterialX/pull/1570) in the MaterialX Graph Editor.
+- Fixed a dependency on [module import order](https://github.com/AcademySoftwareFoundation/MaterialX/pull/1595) in MaterialX Python.
+- Fixed an [off-by-one index check](https://github.com/AcademySoftwareFoundation/MaterialX/pull/1582) in Element::setChildIndex.
+- Fixed a [missing null check](https://github.com/AcademySoftwareFoundation/MaterialX/pull/1601) in Graph::propertyEditor.
+- Fixed cases where [absolute paths](https://github.com/AcademySoftwareFoundation/MaterialX/pull/1603) were stored in MaterialXConfig.cmake.
+
 ## [1.38.8] - 2023-09-08
 
 ### Added

documents/DeveloperGuide/MainPage.md

@@ -58,9 +58,24 @@ Building the `install` target of your project will install the MaterialX C++ and
 
 ### 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://www.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.
+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.
 
-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
+
+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
+
+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:
+
+- In *build* version upgrades, only additive changes and fixes to the MaterialX data libraries are allowed.  Additive changes are allowed to introduce new nodes, node versions, and node inputs with backwards-compatible default values.  Data library fixes are allowed to update a node implementation to improve its alignment with the specification, without making any changes to its name or interface.
+- 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
 

documents/Specification/MaterialX.Specification.md

@@ -1084,6 +1084,12 @@ Math nodes have one or two spatially-varying inputs, and are used to perform a m
     * `in1` (float or color<em>N</em> or vector<em>N</em>): the value or nodename for the primary input
     * `in2` (same type as `in1` or float): the modulo value or nodename to divide by, cannot be 0 in any channel; default is 1.0 in all channels, which effectively returns the fractional part of a float value
 
+<a id="node-invert"> </a>
+
+* **`invert`**: subtract the incoming float/color/vector from "amount" in all channels, outputting: `amount - in`.
+    * `in` (float or color<em>N</em> or vector<em>N</em>): the value or nodename for the primary input
+    * `amount` (same type as `in` or float): the value or nodename to subtract from; default is 1.0 in all channels
+
 <a id="node-absval"> </a>
 
 * **`absval`**: the per-channel absolute value of the incoming float/color/vector.

javascript/MaterialXTest/browser/esslShaderGenerator.spec.js

@@ -1,6 +1,6 @@
 // MaterialX is served through a script tag in the test setup.
 
-function createStandardSurfaceMaterial(mx) 
+function createStandardSurfaceMaterial(mx)
 {
     const doc = mx.createDocument();
     const ssName = 'SR_default';
@@ -15,19 +15,21 @@ function createStandardSurfaceMaterial(mx)
     return doc;
 }
 
-describe('Generate ESSL Shaders', function () 
+describe('Generate ESSL Shaders', function ()
 {
     let mx;
     const canvas = document.createElement('canvas');
     const gl = canvas.getContext('webgl2');
-    
+
     this.timeout(60000);
 
-    before(async function () {
+    before(async function ()
+    {
         mx = await MaterialX();
     });
 
-    it('Compile Shaders', () => {
+    it('Compile Shaders', () =>
+    {
         const doc = createStandardSurfaceMaterial(mx);
 
         const gen = new mx.EsslShaderGenerator();
@@ -37,7 +39,7 @@ describe('Generate ESSL Shaders', function ()
         doc.importLibrary(stdlib);
 
         const elem = mx.findRenderableElement(doc);
-        try 
+        try
         {
             const mxShader = gen.generate(elem.getNamePath(), elem, genContext);
 
@@ -47,7 +49,7 @@ describe('Generate ESSL Shaders', function ()
             const glVertexShader = gl.createShader(gl.VERTEX_SHADER);
             gl.shaderSource(glVertexShader, vShader);
             gl.compileShader(glVertexShader);
-            if (!gl.getShaderParameter(glVertexShader, gl.COMPILE_STATUS)) 
+            if (!gl.getShaderParameter(glVertexShader, gl.COMPILE_STATUS))
             {
                 console.error("-------- VERTEX SHADER FAILED TO COMPILE: ----------------");
                 console.error("--- VERTEX SHADER LOG ---");
@@ -61,7 +63,7 @@ describe('Generate ESSL Shaders', function ()
             const glPixelShader = gl.createShader(gl.FRAGMENT_SHADER);
             gl.shaderSource(glPixelShader, fShader);
             gl.compileShader(glPixelShader);
-            if (!gl.getShaderParameter(glPixelShader, gl.COMPILE_STATUS)) 
+            if (!gl.getShaderParameter(glPixelShader, gl.COMPILE_STATUS))
             {
                 console.error("-------- PIXEL SHADER FAILED TO COMPILE: ----------------");
                 console.error("--- PIXEL SHADER LOG ---");
@@ -75,7 +77,7 @@ describe('Generate ESSL Shaders', function ()
         catch (errPtr)
         {
             console.error("-------- Failed code generation: ----------------");
-            console.error(mx.getExceptionMessage(errPtr));   
+            console.error(mx.getExceptionMessage(errPtr));
         }
     });
 });

javascript/MaterialXTest/browser/karma.conf.js

@@ -1,10 +1,11 @@
-module.exports = function(config) {
+module.exports = function (config)
+{
     config.set({
         basePath: '../', // base is the javascript folder
         files: [
             { pattern: '_build/JsMaterialXGenShader.js', watched: false, included: true, served: true },
             { pattern: '_build/JsMaterialXGenShader.wasm', watched: false, included: false, served: true },
-             {pattern: '_build/JsMaterialXGenShader.data', watched: false, included: false, served: true, nocache: true },
+            { pattern: '_build/JsMaterialXGenShader.data', watched: false, included: false, served: true, nocache: true },
             { pattern: 'browser/*.spec.js', watched: true, included: true, served: true },
         ],
         mime: {

javascript/MaterialXTest/codeExamples.spec.js

@@ -2,8 +2,10 @@ import { expect } from 'chai';
 import Module from './_build/JsMaterialXCore.js';
 import { getMtlxStrings } from './testHelpers';
 
-describe('Code Examples', () => {
-    it('Building a MaterialX Document', async () => {
+describe('Code Examples', () =>
+{
+    it('Building a MaterialX Document', async () =>
+    {
         const mx = await Module();
         // Create a document.
         const doc = mx.createDocument();
@@ -76,7 +78,8 @@ describe('Code Examples', () => {
         // expect(roughness.getBoundValue(material).getValueString()).to.equal('0.5');
     });
 
-    it('Traversing a Document Tree', async () => {
+    it('Traversing a Document Tree', async () =>
+    {
         const xmlStr = getMtlxStrings(
             ['standard_surface_greysphere_calibration.mtlx'],
             '../../resources/Materials/Examples/StandardSurface'
@@ -92,13 +95,16 @@ describe('Code Examples', () => {
         let elementCount = 0;
         let nodeCount = 0;
         let fileCount = 0;
-        for(let elem of elements) {
+        for (let elem of elements)
+        {
             elementCount++;
             // Display the filename of each image node.
-            if (elem.isANode('image')) {
+            if (elem.isANode('image'))
+            {
                 nodeCount++;
                 const input = elem.getInput('file');
-                if (input) {
+                if (input)
+                {
                     fileCount++;
                     const filename = input.getValueString();
                     expect(elem.getName()).to.equal('image1');
@@ -111,7 +117,8 @@ describe('Code Examples', () => {
         expect(fileCount).to.equal(1);
     });
 
-    it('Building a MaterialX Document', async () => {
+    it('Building a MaterialX Document', async () =>
+    {
         const xmlStr = getMtlxStrings(['standard_surface_marble_solid.mtlx'], '../../resources/Materials/Examples/StandardSurface')[0];
         const mx = await Module();
 

javascript/MaterialXTest/customBindings.spec.js

@@ -2,15 +2,18 @@ import { expect } from 'chai';
 import Module from './_build/JsMaterialXCore.js';
 import { getMtlxStrings } from './testHelpers';
 
-describe('Custom Bindings', () => {
+describe('Custom Bindings', () =>
+{
     const examplesPath = '../../resources/Materials/Examples/StandardSurface';
 
-    let mx; 
-    before(async () => {
+    let mx;
+    before(async () =>
+    {
         mx = await Module();
     });
 
-    it('Optional parameters work as expected', () => {
+    it('Optional parameters work as expected', () =>
+    {
         const doc = mx.createDocument();
         // Call a method without optional argument
         const nodeGraph = doc.addNodeGraph();
@@ -29,7 +32,8 @@ describe('Custom Bindings', () => {
         expect(() => { nodeGraph.addNode(); }).to.throw;
     });
 
-    it('Vector <-> Array conversion', () => {
+    it('Vector <-> Array conversion', () =>
+    {
         // Functions that return vectors in C++ should return an array in JS
         const doc = mx.createDocument();
         const nodeGraph = doc.addNodeGraph();
@@ -66,7 +70,8 @@ describe('Custom Bindings', () => {
         expect(nodes[2].getName()).to.equal('anotherNode'); // Name set explicitly at creation time
     });
 
-    it('C++ exception handling', () => {
+    it('C++ exception handling', () =>
+    {
         // Exceptions that are thrown and caught in C++ shouldn't bubble up to JS
         const doc = mx.createDocument();
         const nodeGraph1 = doc.addNodeGraph();
@@ -79,15 +84,18 @@ describe('Custom Bindings', () => {
         // Exceptions that are not caught in C++ should throw with an exception pointer
         nodeGraph1.addNode('node', 'node1');
         expect(() => { nodeGraph1.addNode('node', 'node1'); }).to.throw;
-        try {
+        try
+        {
             nodeGraph1.addNode('node', 'node1');
-        } catch (errPtr) {
+        } catch (errPtr)
+        {
             expect(errPtr).to.be.a('number');
             expect(mx.getExceptionMessage(errPtr)).to.be.a('string');
         }
     });
 
-    it('getReferencedSourceUris', async () => {
+    it('getReferencedSourceUris', async () =>
+    {
         const doc = mx.createDocument();
         const filename = 'standard_surface_look_brass_tiled.mtlx';
         await mx.readFromXmlFile(doc, filename, examplesPath);
@@ -98,7 +106,8 @@ describe('Custom Bindings', () => {
         expect(sourceUris.includes('standard_surface_brass_tiled.mtlx')).to.be.true;
     });
 
-    it('Should invoke correct instance of \'validate\'', () => {
+    it('Should invoke correct instance of \'validate\'', () =>
+    {
         // We check whether the correct function is called by provoking an error message that is specific to the
         // function that we expect to be called.
         const message = {};
@@ -126,7 +135,8 @@ describe('Custom Bindings', () => {
         expect(message.message).to.include('Unit type definition does not exist in document')
     });
 
-    it('StringResolver name substitution getters', () => {
+    it('StringResolver name substitution getters', () =>
+    {
         const fnTestData = {
             fnKey: 'fnValue',
             fnKey1: 'fnValue1'
@@ -156,7 +166,8 @@ describe('Custom Bindings', () => {
         expect(gnSubs).to.deep.equal(gnTestData);
     });
 
-    it('getShaderNodes', async () => {
+    it('getShaderNodes', async () =>
+    {
         const doc = mx.createDocument();
         const fileNames = ['standard_surface_marble_solid.mtlx'];
         const mtlxStrs = getMtlxStrings(fileNames, examplesPath);
@@ -175,14 +186,16 @@ describe('Custom Bindings', () => {
         expect(shaderNodes.length).to.equal(0);
     });
 
-    it('createValidName', () => {
+    it('createValidName', () =>
+    {
         const testString = '_Note_:Please,turn.this+-into*1#valid\nname for_me';
         const replaceRegex = /[^a-zA-Z0-9_:]/g
         expect(mx.createValidName(testString)).to.equal(testString.replace(replaceRegex, '_'));
         expect(mx.createValidName(testString, '-')).to.equal(testString.replace(replaceRegex, '-'));
     });
 
-    it('getVersionIntegers', () => {
+    it('getVersionIntegers', () =>
+    {
         const versionStringArr = mx.getVersionString().split('.').map((value) => parseInt(value, 10));
 
         // Global getVersionIntegers

javascript/MaterialXTest/document.spec.js

@@ -1,30 +1,37 @@
 import { expect } from 'chai';
 import Module from './_build/JsMaterialXCore.js';
 
-describe('Document', () => {
+describe('Document', () =>
+{
     let mx, doc;
-    before(async () => {
+    before(async () =>
+    {
         mx = await Module();
         // Create a document.
         doc = mx.createDocument();
     });
 
-    function expectError(type, cb) {
-        try {
+    function expectError(type, cb)
+    {
+        try
+        {
             cb();
             throw new Error('Expected function to throw!');
-        } catch (exceptionPtr) {
+        } catch (exceptionPtr)
+        {
             const message = mx.getExceptionMessage(exceptionPtr);
             expect(message.indexOf(type) !== -1).to.be.true;
         }
     }
 
     let nodeGraph;
-    it('Build document', () => {
+    it('Build document', () =>
+    {
         // Create a node graph with constant and image sources.
         nodeGraph = doc.addNodeGraph();
         expect(nodeGraph).to.exist;
-        expectError('Child name is not unique: nodegraph1', () => {
+        expectError('Child name is not unique: nodegraph1', () =>
+        {
             doc.addNodeGraph(nodeGraph.getName());
         });
         const constant = nodeGraph.addNode('constant');