-
Notifications
You must be signed in to change notification settings - Fork 0
/
MainPage.html
247 lines (206 loc) · 21.1 KB
/
MainPage.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
<!DOCTYPE html>
<html lang="en" data-content_root="./">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>MaterialX Overview — MaterialX 1.39.2 documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=b20cc3f5" />
<link rel="stylesheet" type="text/css" href="_static/basic.css?v=686e5160" />
<link rel="stylesheet" type="text/css" href="_static/alabaster.css?v=d8f72ed4" />
<script src="_static/documentation_options.js?v=e2b5d38d"></script>
<script src="_static/doctools.js?v=9bcbadda"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="MaterialX Graph Editor" href="GraphEditor.html" />
<link rel="prev" title="MaterialX Python API Documentation" href="index.html" />
<link rel="stylesheet" href="_static/custom.css" type="text/css" />
</head><body>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="materialx-overview">
<h1>MaterialX Overview<a class="headerlink" href="#materialx-overview" title="Link to this heading">¶</a></h1>
<p>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 <a class="reference external" href="https://www.ilm.com/">Industrial Light & Magic</a> in 2012, MaterialX has been a key technology in their feature films and real-time experiences since <em>Star Wars: The Force Awakens</em> and <em>Millennium Falcon: Smugglers Run</em>. 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 <a class="reference external" href="https://www.aswf.io/">Academy Software Foundation</a>.</p>
<section id="quick-start-for-developers">
<h2>Quick Start for Developers<a class="headerlink" href="#quick-start-for-developers" title="Link to this heading">¶</a></h2>
<ul class="simple">
<li><p>Download the latest version of the <a class="reference external" href="https://cmake.org/">CMake</a> build system.</p></li>
<li><p>Point CMake to the root of the MaterialX library and generate C++ projects for your platform and compiler.</p></li>
<li><p>Select the <code class="docutils literal notranslate"><span class="pre">MATERIALX_BUILD_PYTHON</span></code> option to build Python bindings.</p></li>
<li><p>Select the <code class="docutils literal notranslate"><span class="pre">MATERIALX_BUILD_VIEWER</span></code> option to build the MaterialX viewer.</p></li>
</ul>
</section>
<section id="supported-platforms">
<h2>Supported Platforms<a class="headerlink" href="#supported-platforms" title="Link to this heading">¶</a></h2>
<p>The MaterialX codebase requires a compiler with support for C++17, and can be built with any of the following:</p>
<ul class="simple">
<li><p>Microsoft Visual Studio 2017 or newer</p></li>
<li><p>GCC 8 or newer</p></li>
<li><p>Clang 5 or newer</p></li>
</ul>
<p>The Python bindings for MaterialX are based on <a class="reference external" href="https://github.com/pybind/pybind11">PyBind11</a>, and support Python versions 3.6 and greater.</p>
</section>
<section id="building-materialx">
<h2>Building MaterialX<a class="headerlink" href="#building-materialx" title="Link to this heading">¶</a></h2>
<section id="building-materialx-c">
<h3>Building MaterialX C++<a class="headerlink" href="#building-materialx-c" title="Link to this heading">¶</a></h3>
<p>The MaterialX C++ libraries are automatically included when building MaterialX through CMake.</p>
<p>To enable OpenImageIO support in MaterialX builds, the following additional options may be used:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">MATERIALX_BUILD_OIIO</span></code>: Requests that MaterialXRender be built with OpenImageIO in addition to stb_image, extending the set of supported image formats.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">MATERIALX_OIIO_DIR</span></code>: Path to the root folder of an OpenImageIO installation. If MATERIALX_BUILD_OIIO has been enabled, then this option may be used to select which installation is used.</p></li>
</ul>
<p>See the <a class="reference external" href="https://github.com/AcademySoftwareFoundation/MaterialX/tree/main/source/MaterialXTest">MaterialX Unit Tests</a> page for documentation on shader generation and render testing in GLSL, OSL, and MDL.</p>
</section>
<section id="building-materialx-python">
<h3>Building MaterialX Python<a class="headerlink" href="#building-materialx-python" title="Link to this heading">¶</a></h3>
<p>By default, the <code class="docutils literal notranslate"><span class="pre">MATERIALX_BUILD_PYTHON</span></code> 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:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">MATERIALX_PYTHON_VERSION</span></code>: Python version to be used in building the MaterialX Python package (e.g. <code class="docutils literal notranslate"><span class="pre">3.9</span></code>)</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">MATERIALX_PYTHON_EXECUTABLE</span></code>: Python executable to be used in building the MaterialX Python package (e.g. <code class="docutils literal notranslate"><span class="pre">C:/Python39/python.exe</span></code>)</p></li>
</ul>
<p>Additional options for the generation of MaterialX Python include the following:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">MATERIALX_PYTHON_OCIO_DIR</span></code>: Path to a folder containing the default OCIO configuration to be packaged with MaterialX Python. The recommended OpenColorIO configuration for MaterialX is <a class="reference external" href="https://github.com/colour-science/OpenColorIO-Configs/tree/feature/aces-1.2-config/aces_1.2">ACES 1.2</a>.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">MATERIALX_PYTHON_PYBIND11_DIR</span></code>: Path to a folder containing the PyBind11 source to be used in building MaterialX Python. Defaults to the included PyBind11 source.</p></li>
</ul>
</section>
<section id="building-the-materialx-viewer">
<h3>Building The MaterialX Viewer<a class="headerlink" href="#building-the-materialx-viewer" title="Link to this heading">¶</a></h3>
<p>Select the <code class="docutils literal notranslate"><span class="pre">MATERIALX_BUILD_VIEWER</span></code> option to build the MaterialX Viewer. Installation will copy the <code class="docutils literal notranslate"><span class="pre">MaterialXView</span></code> executable to a <code class="docutils literal notranslate"><span class="pre">bin/</span></code> directory within the selected install folder.</p>
</section>
<section id="building-api-documentation">
<h3>Building API Documentation<a class="headerlink" href="#building-api-documentation" title="Link to this heading">¶</a></h3>
<p>To generate HTML documentation for the MaterialX C++ API, make sure a version of <a class="reference external" href="https://www.doxygen.org/">Doxygen</a> is on your path, and select the advanced option <code class="docutils literal notranslate"><span class="pre">MATERIALX_BUILD_DOCS</span></code> in CMake. This option will add a target named <code class="docutils literal notranslate"><span class="pre">MaterialXDocs</span></code> to your project, which can be built as an independent step from your development environment.</p>
<p>To generate HTML documentation for the MaterialX Python API, make sure a version of <a class="reference external" href="https://www.sphinx-doc.org/">Sphinx</a> is on your path, and select the advanced option <code class="docutils literal notranslate"><span class="pre">MATERIALX_BUILD_PYTHON_DOCS</span></code> in CMake. This option will add a target named <code class="docutils literal notranslate"><span class="pre">MaterialXDocsPython</span></code> to your project, which can be built as an independent step from your development environment.</p>
</section>
</section>
<section id="installing-materialx">
<h2>Installing MaterialX<a class="headerlink" href="#installing-materialx" title="Link to this heading">¶</a></h2>
<p>Building the <code class="docutils literal notranslate"><span class="pre">install</span></code> target of your project will install the MaterialX C++ and Python libraries to the folder specified by the <code class="docutils literal notranslate"><span class="pre">CMAKE_INSTALL_PREFIX</span></code> 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 <code class="docutils literal notranslate"><span class="pre">MATERIALX_INSTALL_PYTHON</span></code> to <code class="docutils literal notranslate"><span class="pre">OFF</span></code>.</p>
</section>
<section id="materialx-versioning">
<h2>MaterialX Versioning<a class="headerlink" href="#materialx-versioning" title="Link to this heading">¶</a></h2>
<p>The MaterialX codebase uses a modified semantic versioning system where the <em>major</em> and <em>minor</em> versions match that of the corresponding <a class="reference external" href="https://materialx.org/Specification.html">MaterialX Specification</a>, and the <em>build</em> 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.</p>
<p>Upgrading of MaterialX documents from earlier versions is handled at import time by the <code class="docutils literal notranslate"><span class="pre">Document::upgradeVersion()</span></code> 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.</p>
<section id="materialx-api-changes">
<h3>MaterialX API Changes<a class="headerlink" href="#materialx-api-changes" title="Link to this heading">¶</a></h3>
<p>The following rules describe the categories of changes to the <a class="reference external" href="https://materialx.org/docs/api/classes.html">MaterialX API</a> that are allowed in version upgrades:</p>
<ul class="simple">
<li><p>In <em>build</em> 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.</p></li>
<li><p>In <em>minor</em> and <em>major</em> 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.</p></li>
</ul>
</section>
<section id="materialx-data-library-changes">
<h3>MaterialX Data Library Changes<a class="headerlink" href="#materialx-data-library-changes" title="Link to this heading">¶</a></h3>
<p>The following rules describe the categories of changes to the <a class="reference external" href="https://github.com/AcademySoftwareFoundation/MaterialX/tree/main/libraries">MaterialX Data Libraries</a> that are allowed in version upgrades:</p>
<ul class="simple">
<li><p>In <em>build</em> 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.</p></li>
<li><p>In <em>minor</em> 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.</p></li>
<li><p>In <em>major</em> 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.</p></li>
</ul>
</section>
</section>
<section id="additional-links">
<h2>Additional Links<a class="headerlink" href="#additional-links" title="Link to this heading">¶</a></h2>
<ul class="simple">
<li><p>The main <a class="reference external" href="http://www.materialx.org">MaterialX website</a> provides background on the project’s history, industry collaborations, and recent presentations.</p></li>
<li><p>The <a class="reference external" href="https://github.com/materialx/MaterialX/tree/main/python/Scripts">Python Scripts</a> folder contains standalone examples of MaterialX Python code.</p></li>
<li><p>The <a class="reference external" href="https://github.com/materialx/MaterialX/tree/main/source/MaterialXTest">MaterialX Unit Tests</a> folder contains examples of useful patterns for MaterialX C++.</p></li>
<li><p>The <a class="reference external" href="https://github.com/materialx/MaterialX/blob/main/documents/DeveloperGuide/Viewer.md">MaterialX Viewer</a> is a complete, cross-platform C++ application based upon <a class="reference external" href="https://github.com/materialx/MaterialX/blob/main/documents/DeveloperGuide/ShaderGeneration.md">MaterialX Shader Generation</a></p></li>
</ul>
</section>
</section>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="Main">
<div class="sphinxsidebarwrapper">
<p class="logo">
<a href="index.html">
<img class="logo" src="_static/MaterialXLogo_200x155.png" alt="Logo" />
</a>
</p>
<p class="blurb">
<b>MaterialX</b> – An open standard for the exchange of rich material and
look-development content across applications and renderers.
<p>
<a title="MaterialX on GitHub" class="blueButton" href="https://github.com/AcademySoftwareFoundation/MaterialX">GitHub</a>
<a title="MaterialX on Mastodon" class="blueButton" href="https://mastodon.social/@MaterialX@fosstodon.org">
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"
alt="MaterialX on Mastodon" title="MaterialX on Mastodon" viewBox="0 0 24 24"
width="16" height="16" style="vertical-align: text-top;">
<title>MaterialX on Mastodon</title>
<g transform="translate(-1, 0) scale(0.32, 0.32)" fill="#d2dbde">
<path d="M74.7135 16.6043C73.6199 8.54587 66.5351 2.19527 58.1366 0.964691C56.7196 0.756754 51.351 0 38.9148 0H38.822C26.3824 0 23.7135 0.756754 22.2966 0.964691C14.1319 2.16118 6.67571 7.86752 4.86669 16.0214C3.99657 20.0369 3.90371 24.4888 4.06535 28.5726C4.29578 34.4289 4.34049 40.275 4.877 46.1075C5.24791 49.9817 5.89495 53.8251 6.81328 57.6088C8.53288 64.5968 15.4938 70.4122 22.3138 72.7848C29.6155 75.259 37.468 75.6697 44.9919 73.971C45.8196 73.7801 46.6381 73.5586 47.4475 73.3063C49.2737 72.7302 51.4164 72.086 52.9915 70.9542C53.0131 70.9384 53.0308 70.9178 53.0433 70.8942C53.0558 70.8706 53.0628 70.8445 53.0637 70.8179V65.1661C53.0634 65.1412 53.0574 65.1167 53.0462 65.0944C53.035 65.0721 53.0189 65.0525 52.9992 65.0371C52.9794 65.0218 52.9564 65.011 52.9318 65.0056C52.9073 65.0002 52.8819 65.0003 52.8574 65.0059C48.0369 66.1472 43.0971 66.7193 38.141 66.7103C29.6118 66.7103 27.3178 62.6981 26.6609 61.0278C26.1329 59.5842 25.7976 58.0784 25.6636 56.5486C25.6622 56.5229 25.667 56.4973 25.6775 56.4738C25.688 56.4502 25.7039 56.4295 25.724 56.4132C25.7441 56.397 25.7678 56.3856 25.7931 56.3801C25.8185 56.3746 25.8448 56.3751 25.8699 56.3816C30.6101 57.5151 35.4693 58.0873 40.3455 58.086C41.5183 58.086 42.6876 58.086 43.8604 58.0553C48.7647 57.919 53.9339 57.6701 58.7591 56.7361C58.8794 56.7123 58.9998 56.6918 59.103 56.6611C66.7139 55.2124 73.9569 50.665 74.6929 39.1501C74.7204 38.6967 74.7892 34.4016 74.7892 33.9312C74.7926 32.3325 75.3085 22.5901 74.7135 16.6043ZM62.9996 45.3371H54.9966V25.9069C54.9966 21.8163 53.277 19.7302 49.7793 19.7302C45.9343 19.7302 44.0083 22.1981 44.0083 27.0727V37.7082H36.0534V27.0727C36.0534 22.1981 34.124 19.7302 30.279 19.7302C26.8019 19.7302 25.0651 21.8163 25.0617 25.9069V45.3371H17.0656V25.3172C17.0656 21.2266 18.1191 17.9769 20.2262 15.568C22.3998 13.1648 25.2509 11.9308 28.7898 11.9308C32.8859 11.9308 35.9812 13.492 38.0447 16.6111L40.036 19.9245L42.0308 16.6111C44.0943 13.492 47.1896 11.9308 51.2788 11.9308C54.8143 11.9308 57.6654 13.1648 59.8459 15.568C61.9529 17.9746 63.0065 21.2243 63.0065 25.3172L62.9996 45.3371Z"></path>
</g>
</svg>
</a>
</p>
</p>
<h3>Navigation</h3>
<ul class="current">
<li class="toctree-l1 current"><a class="current reference internal" href="#">MaterialX Overview</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#quick-start-for-developers">Quick Start for Developers</a></li>
<li class="toctree-l2"><a class="reference internal" href="#supported-platforms">Supported Platforms</a></li>
<li class="toctree-l2"><a class="reference internal" href="#building-materialx">Building MaterialX</a></li>
<li class="toctree-l2"><a class="reference internal" href="#installing-materialx">Installing MaterialX</a></li>
<li class="toctree-l2"><a class="reference internal" href="#materialx-versioning">MaterialX Versioning</a></li>
<li class="toctree-l2"><a class="reference internal" href="#additional-links">Additional Links</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="GraphEditor.html">MaterialX Graph Editor</a></li>
<li class="toctree-l1"><a class="reference internal" href="Viewer.html">MaterialX Viewer</a></li>
<li class="toctree-l1"><a class="reference internal" href="ShaderGeneration.html">Shader Generation</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">MaterialX Python Modules:</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="generated/PyMaterialXCore.html">PyMaterialXCore</a></li>
<li class="toctree-l1"><a class="reference internal" href="generated/PyMaterialXFormat.html">PyMaterialXFormat</a></li>
<li class="toctree-l1"><a class="reference internal" href="generated/PyMaterialXGenShader.html">PyMaterialXGenShader</a></li>
<li class="toctree-l1"><a class="reference internal" href="generated/PyMaterialXGenGlsl.html">PyMaterialXGenGlsl</a></li>
<li class="toctree-l1"><a class="reference internal" href="generated/PyMaterialXGenOsl.html">PyMaterialXGenOsl</a></li>
<li class="toctree-l1"><a class="reference internal" href="generated/PyMaterialXGenMdl.html">PyMaterialXGenMdl</a></li>
<li class="toctree-l1"><a class="reference internal" href="generated/PyMaterialXGenMsl.html">PyMaterialXGenMsl</a></li>
<li class="toctree-l1"><a class="reference internal" href="generated/PyMaterialXRender.html">PyMaterialXRender</a></li>
<li class="toctree-l1"><a class="reference internal" href="generated/PyMaterialXRenderGlsl.html">PyMaterialXRenderGlsl</a></li>
<li class="toctree-l1"><a class="reference internal" href="generated/PyMaterialXRenderOsl.html">PyMaterialXRenderOsl</a></li>
<li class="toctree-l1"><a class="reference internal" href="generated/PyMaterialXRenderMsl.html">PyMaterialXRenderMsl</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="genindex.html">Index</a></li>
</ul>
<hr />
<ul>
<li class="toctree-l1"><a href="https://materialx.org/">MaterialX.org</a></li>
<li class="toctree-l1"><a href="https://materialx.org/docs/api/index.html">MaterialX C++ API Docs</a></li>
<li class="toctree-l1"><a href="https://materialx.org/Specification.html">MaterialX Specification</a></li>
</ul>
<search id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</search>
<script>document.getElementById('searchbox').style.display = "block"</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
©2024 MaterialX Authors.
|
Powered by <a href="https://www.sphinx-doc.org/">Sphinx 8.1.2</a>
& <a href="https://alabaster.readthedocs.io">Alabaster 1.0.0</a>
|
<a href="_sources/MainPage.md.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>