2522 lines
191 KiB
HTML
2522 lines
191 KiB
HTML
<html><head><meta charset="utf-8">
|
|
|
|
<style>img { max-width: 100%; }</style>
|
|
|
|
</head><body style="visibility: visible;"><meta charset="UTF-8"><meta http-equiv="content-type" content="text/html;charset=UTF-8"><style>body{max-width:680px;margin:auto;padding:20px;text-align:justify;line-height:140%; -webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale;font-smoothing:antialiased;color:#222;font-family:Palatino,Georgia,"Times New Roman",serif}</style><style>body{counter-reset: h1 h2 h3 h4 h5 h6 paragraph}@page{margin:0;size:auto}.md code,pre{font-family:Menlo,Consolas,monospace;font-size:13.099975100467727px;line-height:140%}.md div.title{font-size:26px;font-weight:800;line-height:120%;text-align:center}.md div.afterTitles{height:10px}.md div.subtitle{text-align:center}.md .image{display:inline-block}.md img{max-width:100%;page-break-inside:avoid}.md li{text-align:left;text-indent:0}.md pre.listing {tab-size:4;-moz-tab-size:4;-o-tab-size:4;counter-reset:line}.md pre.listing .linenumbers span.line:before{width:30px;margin-left:-52px;font-size:80%;text-align:right;counter-increment:line;content:counter(line);display:inline-block;padding-right:13px;margin-right:8px;color:#ccc}.md div.tilde{margin:20px 0 -10px;text-align:center}.md div.imagecaption,.md div.tablecaption,.md div.listingcaption{margin:7px 5px 12px;text-align: justify;font-style:italic}.md div.imagecaption{margin-bottom:0}.md blockquote.fancyquote{margin:25px 0 25px;text-align:left;line-height:160%}.md blockquote.fancyquote::before{content:"“";color:#DDD;font-family:Times New Roman;font-size:45px;line-height:0;margin-right:6px;vertical-align:-0.3em}.md span.fancyquote{font-size:118%;color:#777;font-style:italic}.md span.fancyquote::after{content:"”";font-style:normal;color:#DDD;font-family:Times New Roman;font-size:45px;line-height:0;margin-left:6px;vertical-align:-0.3em}.md blockquote.fancyquote .author{width:100%;margin-top:10px;display:inline-block;text-align:right}.md small{font-size:60%}.md big{font-size:150%}.md div.title,contents,.md .tocHeader,h1,h2,h3,h4,h5,h6,.md .shortTOC,.md .mediumTOC,.nonumberh1,.nonumberh2,.nonumberh3,.nonumberh4,.nonumberh5,.nonumberh6{font-family:Verdana,Helvetica,Arial,sans-serif;margin:13.4px 0 13.4px;padding:15px 0 3px;border-top:none;clear:both}.md h1,.md h2,.md h3,.md h4,.md h5,.md h6,.md .nonumberh1,.md .nonumberh2,.md .nonumberh3,.md .nonumberh4,.md .nonumberh5,.md .nonumberh6{page-break-after:avoid;break-after:avoid}.md svg.diagram{display:block;font-family:Menlo,Consolas,monospace;font-size:13.099975100467727px;text-align:center;stroke-linecap:round;stroke-width:2px;page-break-inside:avoid;stroke:#000;fill:#000}.md svg.diagram .opendot{fill:#FFF}.md svg.diagram text{stroke:none}@media print{@page{margin:1in 5mm;transform: scale(150%)}}@media print{.md .pagebreak{page-break-after:always;visibility:hidden}}.md a{font-family:Georgia,Palatino,'Times New Roman'}.md h1,.md .tocHeader,.md .nonumberh1{border-bottom:3px solid;font-size:20px;font-weight:bold;}.md h1,.md .nonumberh1{counter-reset: h2 h3 h4 h5 h6}.md h2,.md .nonumberh2{counter-reset: h3 h4 h5 h6;border-bottom:2px solid #999;color:#555;font-weight:bold;font-size:18px;}.md h3,.md h4,.md h5,.md h6,.md .nonumberh3,.md .nonumberh4,.md .nonumberh5,.md .nonumberh6{font-family:Helvetica,Arial,sans-serif;color:#555;font-size:16px;}.md h3{counter-reset:h4 h5 h6}.md h4{counter-reset:h5 h6}.md h5{counter-reset:h6}.md div.table{margin:16px 0 16px 0}.md table{border-collapse:collapse;line-height:140%;page-break-inside:avoid}.md table.table{margin:auto}.md table.calendar{width:100%;margin:auto;font-size:11px;font-family:Helvetica,Arial,sans-serif}.md table.calendar th{font-size:16px}.md .today{background:#ECF8FA}.md .calendar .parenthesized{color:#999;font-style:italic}.md div.tablecaption{text-align:center}.md table.table th{color:#FFF;background-color:#AAA;border:1px solid #888;padding:8px 15px 8px 15px}.md table.table td{padding:5px 15px 5px 15px;border:1px solid #888}.md table.table tr:nth-child(even){background:#EEE}.md pre.tilde{border-top: 1px solid #CCC;border-bottom: 1px solid #CCC;padding: 5px 0 5px 20px;margin:0 0 0 0;background:#FCFCFC;page-break-inside:avoid}.md a.target{width:0px;height:0px;visibility:hidden;font-size:0px;display:inline-block}.md a:link, .md a:visited{color:#38A;text-decoration:none}.md a:link:hover{text-decoration:underline}.md dt{font-weight:700}.md dl>dd{margin-top:-8px; margin-bottom:8px}.md dl>table{margin:35px 0 30px}.md code{white-space:pre-wrap;overflow-wrap:break-word;text-align:left;page-break-inside:avoid}.md .endnote{font-size:13px;line-height:15px;padding-left:10px;text-indent:-10px}.md .bib{padding-left:80px;text-indent:-80px;text-align:left}.markdeepFooter{font-size:9px;text-align:right;padding-top:80px;color:#999}.md .mediumTOC{float:right;font-size:12px;line-height:15px;border-left:1px solid #CCC;padding-left:15px;margin:15px 0px 15px 25px}.md .mediumTOC .level1{font-weight:600}.md .longTOC .level1{font-weight:600;display:block;padding-top:12px;margin:0 0 -20px}.md .shortTOC{text-align:center;font-weight:bold;margin-top:15px;font-size:14px}.md .admonition{position:relative;margin:1em 0;padding:.4rem 1rem;border-radius:.2rem;border-left:2.5rem solid rgba(68,138,255,.4);background-color:rgba(68,138,255,.15);}.md .admonition-title{font-weight:bold;border-bottom:solid 1px rgba(68,138,255,.4);padding-bottom:4px;margin-bottom:4px;margin-left: -1rem;padding-left:1rem;margin-right:-1rem;border-color:rgba(68,138,255,.4)}.md .admonition.tip{border-left:2.5rem solid rgba(50,255,90,.4);background-color:rgba(50,255,90,.15)}.md .admonition.tip::before{content:"\24d8";font-weight:bold;font-size:150%;position:relative;top:3px;color:rgba(26,128,46,.8);left:-2.95rem;display:block;width:0;height:0}.md .admonition.tip>.admonition-title{border-color:rgba(50,255,90,.4)}.md .admonition.warn,.md .admonition.warning{border-left:2.5rem solid rgba(255,145,0,.4);background-color:rgba(255,145,0,.15)}.md .admonition.warn::before,.md .admonition.warning::before{content:"\26A0";font-weight:bold;font-size:150%;position:relative;top:2px;color:rgba(128,73,0,.8);left:-2.95rem;display:block;width:0;height:0}.md .admonition.warn>.admonition-title,.md .admonition.warning>.admonition-title{border-color:rgba(255,145,0,.4)}.md .admonition.error{border-left: 2.5rem solid rgba(255,23,68,.4);background-color:rgba(255,23,68,.15)}.md .admonition.error>.admonition-title{border-color:rgba(255,23,68,.4)}.md .admonition.error::before{content: "\2612";font-family:"Arial";font-size:200%;position:relative;color:rgba(128,12,34,.8);top:-2px;left:-3rem;display:block;width:0;height:0}.md .admonition p:last-child{margin-bottom:0}.md li.checked,.md li.unchecked{list-style:none;overflow:visible;text-indent:-1.2em}.md li.checked:before,.md li.unchecked:before{content:"\2611";display:block;float:left;width:1em;font-size:120%}.md li.unchecked:before{content:"\2610"}</style><style>.md h1::before {
|
|
content:counter(h1) " ";
|
|
counter-increment: h1;margin-right:10px}.md h2::before {
|
|
content:counter(h1) "."counter(h2) " ";
|
|
counter-increment: h2;margin-right:10px}.md h3::before {
|
|
content:counter(h1) "."counter(h2) "."counter(h3) " ";
|
|
counter-increment: h3;margin-right:10px}.md h4::before {
|
|
content:counter(h1) "."counter(h2) "."counter(h3) "."counter(h4) " ";
|
|
counter-increment: h4;margin-right:10px}.md h5::before {
|
|
content:counter(h1) "."counter(h2) "."counter(h3) "."counter(h4) "."counter(h5) " ";
|
|
counter-increment: h5;margin-right:10px}.md h6::before {
|
|
content:counter(h1) "."counter(h2) "."counter(h3) "."counter(h4) "."counter(h5) "."counter(h6) " ";
|
|
counter-increment: h6;margin-right:10px}</style><style>.hljs{display:block;overflow-x:auto;padding:0.5em;background:#fff;color:#000;-webkit-text-size-adjust:none}.hljs-comment{color:#006a00}.hljs-keyword{color:#02E}.hljs-literal,.nginx .hljs-title{color:#aa0d91}.method,.hljs-list .hljs-title,.hljs-tag .hljs-title,.setting .hljs-value,.hljs-winutils,.tex .hljs-command,.http .hljs-title,.hljs-request,.hljs-status,.hljs-name{color:#008}.hljs-envvar,.tex .hljs-special{color:#660}.hljs-string{color:#c41a16}.hljs-tag .hljs-value,.hljs-cdata,.hljs-filter .hljs-argument,.hljs-attr_selector,.apache .hljs-cbracket,.hljs-date,.hljs-regexp{color:#080}.hljs-sub .hljs-identifier,.hljs-pi,.hljs-tag,.hljs-tag .hljs-keyword,.hljs-decorator,.ini .hljs-title,.hljs-shebang,.hljs-prompt,.hljs-hexcolor,.hljs-rule .hljs-value,.hljs-symbol,.hljs-symbol .hljs-string,.hljs-number,.css .hljs-function,.hljs-function .hljs-title,.coffeescript .hljs-attribute{color:#A0C}.hljs-function .hljs-title{font-weight:bold;color:#000}.hljs-class .hljs-title,.smalltalk .hljs-class,.hljs-type,.hljs-typename,.hljs-tag .hljs-attribute,.hljs-doctype,.hljs-class .hljs-id,.hljs-built_in,.setting,.hljs-params,.clojure .hljs-attribute{color:#5c2699}.hljs-variable{color:#3f6e74}.css .hljs-tag,.hljs-rule .hljs-property,.hljs-pseudo,.hljs-subst{color:#000}.css .hljs-class,.css .hljs-id{color:#9b703f}.hljs-value .hljs-important{color:#ff7700;font-weight:bold}.hljs-rule .hljs-keyword{color:#c5af75}.hljs-annotation,.apache .hljs-sqbracket,.nginx .hljs-built_in{color:#9b859d}.hljs-preprocessor,.hljs-preprocessor *,.hljs-pragma{color:#643820}.tex .hljs-formula{background-color:#eee;font-style:italic}.diff .hljs-header,.hljs-chunk{color:#808080;font-weight:bold}.diff .hljs-change{background-color:#bccff9}.hljs-addition{background-color:#baeeba}.hljs-deletion{background-color:#ffc8bd}.hljs-comment .hljs-doctag{font-weight:bold}.method .hljs-id{color:#000}</style><style>div.title { padding-top: 40px; } div.afterTitles { height: 15px; }</style><meta charset="utf-8">
|
|
|
|
<style>img { max-width: 100%; }</style>
|
|
|
|
<script type="text/x-mathjax-config">MathJax.Hub.Config({ TeX: { equationNumbers: {autoNumber: "AMS"} } });</script><span style="display:none">$$\newcommand{\n}{\hat{n}}\newcommand{\thetai}{\theta_\mathrm{i}}\newcommand{\thetao}{\theta_\mathrm{o}}\newcommand{\d}[1]{\mathrm{d}#1}\newcommand{\w}{\hat{\omega}}\newcommand{\wi}{\w_\mathrm{i}}\newcommand{\wo}{\w_\mathrm{o}}\newcommand{\wh}{\w_\mathrm{h}}\newcommand{\Li}{L_\mathrm{i}}\newcommand{\Lo}{L_\mathrm{o}}\newcommand{\Le}{L_\mathrm{e}}\newcommand{\Lr}{L_\mathrm{r}}\newcommand{\Lt}{L_\mathrm{t}}\newcommand{\O}{\mathrm{O}}\newcommand{\degrees}{{^{\large\circ}}}\newcommand{\T}{\mathsf{T}}\newcommand{\mathset}[1]{\mathbb{#1}}\newcommand{\Real}{\mathset{R}}\newcommand{\Integer}{\mathset{Z}}\newcommand{\Boolean}{\mathset{B}}\newcommand{\Complex}{\mathset{C}}\newcommand{\un}[1]{\,\mathrm{#1}}$$
|
|
</span>
|
|
<span class="md"><p><title>Filament Materials Guide</title></p><div class="title"> Filament Materials Guide </div>
|
|
|
|
<div class="afterTitles"></div>
|
|
|
|
<p></p><p>
|
|
|
|
</p><center><a href="images/filament_logo.png" target="_blank"><img class="markdeep" src="images/filament_logo.png"></a></center>
|
|
|
|
<p></p>
|
|
<div class="longTOC"><div class="tocHeader">Contents</div><p><a href="#about" class="level1"><span class="tocNumber">1  </span>About</a><br>
|
|
  <a href="#about/authors" class="level2"><span class="tocNumber">1.1  </span>Authors</a><br>
|
|
<a href="#overview" class="level1"><span class="tocNumber">2  </span>Overview</a><br>
|
|
  <a href="#overview/coreconcepts" class="level2"><span class="tocNumber">2.1  </span>Core concepts</a><br>
|
|
<a href="#materialmodels" class="level1"><span class="tocNumber">3  </span>Material models</a><br>
|
|
  <a href="#materialmodels/litmodel" class="level2"><span class="tocNumber">3.1  </span>Lit model</a><br>
|
|
    <a href="#materialmodels/litmodel/basecolor" class="level3"><span class="tocNumber">3.1.1  </span>Base color</a><br>
|
|
    <a href="#materialmodels/litmodel/metallic" class="level3"><span class="tocNumber">3.1.2  </span>Metallic</a><br>
|
|
    <a href="#materialmodels/litmodel/roughness" class="level3"><span class="tocNumber">3.1.3  </span>Roughness</a><br>
|
|
    <a href="#materialmodels/litmodel/non-metals" class="level3"><span class="tocNumber">3.1.4  </span>Non-metals</a><br>
|
|
    <a href="#materialmodels/litmodel/metals" class="level3"><span class="tocNumber">3.1.5  </span>Metals</a><br>
|
|
    <a href="#materialmodels/litmodel/refraction" class="level3"><span class="tocNumber">3.1.6  </span>Refraction</a><br>
|
|
    <a href="#materialmodels/litmodel/reflectance" class="level3"><span class="tocNumber">3.1.7  </span>Reflectance</a><br>
|
|
    <a href="#materialmodels/litmodel/clearcoat" class="level3"><span class="tocNumber">3.1.8  </span>Clear coat</a><br>
|
|
    <a href="#materialmodels/litmodel/clearcoatroughness" class="level3"><span class="tocNumber">3.1.9  </span>Clear coat roughness</a><br>
|
|
    <a href="#materialmodels/litmodel/anisotropy" class="level3"><span class="tocNumber">3.1.10  </span>Anisotropy</a><br>
|
|
    <a href="#materialmodels/litmodel/anisotropydirection" class="level3"><span class="tocNumber">3.1.11  </span>Anisotropy direction</a><br>
|
|
    <a href="#materialmodels/litmodel/ambientocclusion" class="level3"><span class="tocNumber">3.1.12  </span>Ambient occlusion</a><br>
|
|
    <a href="#materialmodels/litmodel/normal" class="level3"><span class="tocNumber">3.1.13  </span>Normal</a><br>
|
|
    <a href="#materialmodels/litmodel/bentnormal" class="level3"><span class="tocNumber">3.1.14  </span>Bent normal</a><br>
|
|
    <a href="#materialmodels/litmodel/clearcoatnormal" class="level3"><span class="tocNumber">3.1.15  </span>Clear coat normal</a><br>
|
|
    <a href="#materialmodels/litmodel/emissive" class="level3"><span class="tocNumber">3.1.16  </span>Emissive</a><br>
|
|
    <a href="#materialmodels/litmodel/post-lightingcolor" class="level3"><span class="tocNumber">3.1.17  </span>Post-lighting color</a><br>
|
|
    <a href="#materialmodels/litmodel/indexofrefraction" class="level3"><span class="tocNumber">3.1.18  </span>Index of refraction</a><br>
|
|
    <a href="#materialmodels/litmodel/transmission" class="level3"><span class="tocNumber">3.1.19  </span>Transmission</a><br>
|
|
    <a href="#materialmodels/litmodel/absorption" class="level3"><span class="tocNumber">3.1.20  </span>Absorption</a><br>
|
|
    <a href="#materialmodels/litmodel/micro-thicknessandthickness" class="level3"><span class="tocNumber">3.1.21  </span>Micro-thickness and thickness</a><br>
|
|
  <a href="#materialmodels/subsurfacemodel" class="level2"><span class="tocNumber">3.2  </span>Subsurface model</a><br>
|
|
    <a href="#materialmodels/subsurfacemodel/thickness" class="level3"><span class="tocNumber">3.2.1  </span>Thickness</a><br>
|
|
    <a href="#materialmodels/subsurfacemodel/subsurfacecolor" class="level3"><span class="tocNumber">3.2.2  </span>Subsurface color</a><br>
|
|
    <a href="#materialmodels/subsurfacemodel/subsurfacepower" class="level3"><span class="tocNumber">3.2.3  </span>Subsurface power</a><br>
|
|
  <a href="#materialmodels/clothmodel" class="level2"><span class="tocNumber">3.3  </span>Cloth model</a><br>
|
|
    <a href="#materialmodels/clothmodel/sheencolor" class="level3"><span class="tocNumber">3.3.1  </span>Sheen color</a><br>
|
|
    <a href="#materialmodels/clothmodel/subsurfacecolor" class="level3"><span class="tocNumber">3.3.2  </span>Subsurface color</a><br>
|
|
  <a href="#materialmodels/unlitmodel" class="level2"><span class="tocNumber">3.4  </span>Unlit model</a><br>
|
|
  <a href="#materialmodels/specularglossiness" class="level2"><span class="tocNumber">3.5  </span>Specular glossiness</a><br>
|
|
<a href="#materialdefinitions" class="level1"><span class="tocNumber">4  </span>Material definitions</a><br>
|
|
  <a href="#materialdefinitions/format" class="level2"><span class="tocNumber">4.1  </span>Format</a><br>
|
|
    <a href="#materialdefinitions/format/differenceswithjson" class="level3"><span class="tocNumber">4.1.1  </span>Differences with JSON</a><br>
|
|
    <a href="#materialdefinitions/format/example" class="level3"><span class="tocNumber">4.1.2  </span>Example</a><br>
|
|
  <a href="#materialdefinitions/materialblock" class="level2"><span class="tocNumber">4.2  </span>Material block</a><br>
|
|
    <a href="#materialdefinitions/materialblock/general:name" class="level3"><span class="tocNumber">4.2.1  </span>General: name</a><br>
|
|
    <a href="#materialdefinitions/materialblock/general:shadingmodel" class="level3"><span class="tocNumber">4.2.2  </span>General: shadingModel</a><br>
|
|
    <a href="#materialdefinitions/materialblock/general:parameters" class="level3"><span class="tocNumber">4.2.3  </span>General: parameters</a><br>
|
|
    <a href="#materialdefinitions/materialblock/general:variantfilter" class="level3"><span class="tocNumber">4.2.4  </span>General: variantFilter</a><br>
|
|
    <a href="#materialdefinitions/materialblock/general:flipuv" class="level3"><span class="tocNumber">4.2.5  </span>General: flipUV</a><br>
|
|
    <a href="#materialdefinitions/materialblock/vertexandattributes:requires" class="level3"><span class="tocNumber">4.2.6  </span>Vertex and attributes: requires</a><br>
|
|
    <a href="#materialdefinitions/materialblock/vertexandattributes:variables" class="level3"><span class="tocNumber">4.2.7  </span>Vertex and attributes: variables</a><br>
|
|
    <a href="#materialdefinitions/materialblock/vertexandattributes:vertexdomain" class="level3"><span class="tocNumber">4.2.8  </span>Vertex and attributes: vertexDomain</a><br>
|
|
    <a href="#materialdefinitions/materialblock/vertexandattributes:interpolation" class="level3"><span class="tocNumber">4.2.9  </span>Vertex and attributes: interpolation</a><br>
|
|
    <a href="#materialdefinitions/materialblock/blendingandtransparency:blending" class="level3"><span class="tocNumber">4.2.10  </span>Blending and transparency: blending</a><br>
|
|
    <a href="#materialdefinitions/materialblock/blendingandtransparency:postlightingblending" class="level3"><span class="tocNumber">4.2.11  </span>Blending and transparency: postLightingBlending</a><br>
|
|
    <a href="#materialdefinitions/materialblock/blendingandtransparency:transparency" class="level3"><span class="tocNumber">4.2.12  </span>Blending and transparency: transparency</a><br>
|
|
    <a href="#materialdefinitions/materialblock/blendingandtransparency:maskthreshold" class="level3"><span class="tocNumber">4.2.13  </span>Blending and transparency: maskThreshold</a><br>
|
|
    <a href="#materialdefinitions/materialblock/blendingandtransparency:refractionmode" class="level3"><span class="tocNumber">4.2.14  </span>Blending and transparency: refractionMode</a><br>
|
|
    <a href="#materialdefinitions/materialblock/blendingandtransparency:refractiontype" class="level3"><span class="tocNumber">4.2.15  </span>Blending and transparency: refractionType</a><br>
|
|
    <a href="#materialdefinitions/materialblock/rasterization:culling" class="level3"><span class="tocNumber">4.2.16  </span>Rasterization: culling</a><br>
|
|
    <a href="#materialdefinitions/materialblock/rasterization:colorwrite" class="level3"><span class="tocNumber">4.2.17  </span>Rasterization: colorWrite</a><br>
|
|
    <a href="#materialdefinitions/materialblock/rasterization:depthwrite" class="level3"><span class="tocNumber">4.2.18  </span>Rasterization: depthWrite</a><br>
|
|
    <a href="#materialdefinitions/materialblock/rasterization:depthculling" class="level3"><span class="tocNumber">4.2.19  </span>Rasterization: depthCulling</a><br>
|
|
    <a href="#materialdefinitions/materialblock/rasterization:doublesided" class="level3"><span class="tocNumber">4.2.20  </span>Rasterization: doubleSided</a><br>
|
|
    <a href="#materialdefinitions/materialblock/lighting:shadowmultiplier" class="level3"><span class="tocNumber">4.2.21  </span>Lighting: shadowMultiplier</a><br>
|
|
    <a href="#materialdefinitions/materialblock/lighting:clearcoatiorchange" class="level3"><span class="tocNumber">4.2.22  </span>Lighting: clearCoatIorChange</a><br>
|
|
    <a href="#materialdefinitions/materialblock/lighting:multibounceambientocclusion" class="level3"><span class="tocNumber">4.2.23  </span>Lighting: multiBounceAmbientOcclusion</a><br>
|
|
    <a href="#materialdefinitions/materialblock/lighting:specularambientocclusion" class="level3"><span class="tocNumber">4.2.24  </span>Lighting: specularAmbientOcclusion</a><br>
|
|
    <a href="#materialdefinitions/materialblock/anti-aliasing:specularantialiasing" class="level3"><span class="tocNumber">4.2.25  </span>Anti-aliasing: specularAntiAliasing</a><br>
|
|
    <a href="#materialdefinitions/materialblock/anti-aliasing:specularantialiasingvariance" class="level3"><span class="tocNumber">4.2.26  </span>Anti-aliasing: specularAntiAliasingVariance</a><br>
|
|
    <a href="#materialdefinitions/materialblock/anti-aliasing:specularantialiasingthreshold" class="level3"><span class="tocNumber">4.2.27  </span>Anti-aliasing: specularAntiAliasingThreshold</a><br>
|
|
  <a href="#materialdefinitions/vertexblock" class="level2"><span class="tocNumber">4.3  </span>Vertex block</a><br>
|
|
    <a href="#materialdefinitions/vertexblock/materialvertexinputs" class="level3"><span class="tocNumber">4.3.1  </span>Material vertex inputs</a><br>
|
|
  <a href="#materialdefinitions/fragmentblock" class="level2"><span class="tocNumber">4.4  </span>Fragment block</a><br>
|
|
    <a href="#materialdefinitions/fragmentblock/preparematerialfunction" class="level3"><span class="tocNumber">4.4.1  </span>prepareMaterial function</a><br>
|
|
    <a href="#materialdefinitions/fragmentblock/materialfragmentinputs" class="level3"><span class="tocNumber">4.4.2  </span>Material fragment inputs</a><br>
|
|
  <a href="#materialdefinitions/shaderpublicapis" class="level2"><span class="tocNumber">4.5  </span>Shader public APIs</a><br>
|
|
    <a href="#materialdefinitions/shaderpublicapis/types" class="level3"><span class="tocNumber">4.5.1  </span>Types</a><br>
|
|
    <a href="#materialdefinitions/shaderpublicapis/math" class="level3"><span class="tocNumber">4.5.2  </span>Math</a><br>
|
|
    <a href="#materialdefinitions/shaderpublicapis/matrices" class="level3"><span class="tocNumber">4.5.3  </span>Matrices</a><br>
|
|
    <a href="#materialdefinitions/shaderpublicapis/frameconstants" class="level3"><span class="tocNumber">4.5.4  </span>Frame constants</a><br>
|
|
    <a href="#materialdefinitions/shaderpublicapis/vertexonly" class="level3"><span class="tocNumber">4.5.5  </span>Vertex only</a><br>
|
|
    <a href="#materialdefinitions/shaderpublicapis/fragmentonly" class="level3"><span class="tocNumber">4.5.6  </span>Fragment only</a><br>
|
|
<a href="#compilingmaterials" class="level1"><span class="tocNumber">5  </span>Compiling materials</a><br>
|
|
  <a href="#compilingmaterials/shadervalidation" class="level2"><span class="tocNumber">5.1  </span>Shader validation</a><br>
|
|
  <a href="#compilingmaterials/flags" class="level2"><span class="tocNumber">5.2  </span>Flags</a><br>
|
|
    <a href="#compilingmaterials/flags/—platform" class="level3"><span class="tocNumber">5.2.1  </span>—platform</a><br>
|
|
    <a href="#compilingmaterials/flags/—api" class="level3"><span class="tocNumber">5.2.2  </span>—api</a><br>
|
|
    <a href="#compilingmaterials/flags/—optimize-size" class="level3"><span class="tocNumber">5.2.3  </span>—optimize-size</a><br>
|
|
    <a href="#compilingmaterials/flags/—reflect" class="level3"><span class="tocNumber">5.2.4  </span>—reflect</a><br>
|
|
    <a href="#compilingmaterials/flags/—variant-filter" class="level3"><span class="tocNumber">5.2.5  </span>—variant-filter</a><br>
|
|
<a href="#handlingcolors" class="level1"><span class="tocNumber">6  </span>Handling colors</a><br>
|
|
  <a href="#handlingcolors/linearcolors" class="level2"><span class="tocNumber">6.1  </span>Linear colors</a><br>
|
|
  <a href="#handlingcolors/pre-multipliedalpha" class="level2"><span class="tocNumber">6.2  </span>Pre-multiplied alpha</a><br>
|
|
</p></div><a class="target" name="about"> </a><a class="target" name="about"> </a><a class="target" name="toc1"> </a><h1>About</h1>
|
|
<p>
|
|
|
|
|
|
This document is part of the <a href="https://github.com/google/filament">Filament project</a>. To report errors in this document please use the <a href="https://github.com/google/filament/issues">project's issue tracker</a>.
|
|
|
|
</p>
|
|
<a class="target" name="authors"> </a><a class="target" name="about/authors"> </a><a class="target" name="toc1.1"> </a><h2>Authors</h2>
|
|
<p>
|
|
|
|
|
|
|
|
</p><ul>
|
|
<li class="minus"><a href="https://github.com/romainguy">Romain Guy</a>, <a href="https://twitter.com/romainguy">@romainguy</a>
|
|
</li>
|
|
<li class="minus"><a href="https://github.com/pixelflinger">Mathias Agopian</a>, <a href="https://twitter.com/darthmoosious">@romainguy</a></li></ul>
|
|
|
|
<p></p>
|
|
<a class="target" name="overview"> </a><a class="target" name="overview"> </a><a class="target" name="toc2"> </a><h1>Overview</h1>
|
|
<p>
|
|
|
|
|
|
Filament is a physically based rendering (PBR) engine for Android. Filament offers a customizable
|
|
material system that you can use to create both simple and complex materials. This document
|
|
describes all the features available to materials and how to create your own material.
|
|
|
|
</p>
|
|
<a class="target" name="coreconcepts"> </a><a class="target" name="overview/coreconcepts"> </a><a class="target" name="toc2.1"> </a><h2>Core concepts</h2>
|
|
<p>
|
|
|
|
|
|
</p><dl><dt>Material</dt><dd><p> A material defines the visual appearance of a surface. To completely describe and render a
|
|
surface, a material provides the following information:
|
|
|
|
</p><p>
|
|
|
|
</p><ul>
|
|
<li class="minus">Material model
|
|
</li>
|
|
<li class="minus">Set of use-controllable named parameters
|
|
</li>
|
|
<li class="minus">Raster state (blending mode, backface culling, etc.)
|
|
</li>
|
|
<li class="minus">Vertex shader code
|
|
</li>
|
|
<li class="minus">Fragment shader code</li></ul>
|
|
|
|
<p></p></dd><dt>Material model</dt><dd><p> Also called <em class="underscore">shading model</em> or <em class="underscore">lighting model</em>, the material model defines the intrinsic
|
|
properties of a surface. These properties have a direct influence on the way lighting is
|
|
computed and therefore on the appearance of a surface.
|
|
|
|
</p></dd><dt>Material definition</dt><dd><p> A text file that describes all the information required by a material. This is the file that you
|
|
will directly author to create new materials.
|
|
|
|
</p></dd><dt>Material package</dt><dd><p> At runtime, materials are loaded from <em class="underscore">material packages</em> compiled from material definitions
|
|
using the <code>matc</code> tool. A material package contains all the information required to describe a
|
|
material, and shaders generated for the target runtime platforms. This is necessary because
|
|
different platforms (Android, macOS, Linux, etc.) use different graphics APIs or different
|
|
variants of similar graphics APIs (OpenGL vs OpenGL ES for instance).
|
|
|
|
</p></dd><dt>Material instance</dt><dd><p> A material instance is a reference to a material and a set of values for the different values of
|
|
that material. Material instances are not covered in this document as they are created and
|
|
manipulated directly from code using Filament's APIs.
|
|
|
|
</p></dd></dl><p></p>
|
|
<a class="target" name="materialmodels"> </a><a class="target" name="materialmodels"> </a><a class="target" name="toc3"> </a><h1>Material models</h1>
|
|
<p>
|
|
|
|
|
|
Filament materials can use one of the following material models:
|
|
|
|
</p><p>
|
|
|
|
</p><ul>
|
|
<li class="minus">Lit (or standard)
|
|
</li>
|
|
<li class="minus">Subsurface
|
|
</li>
|
|
<li class="minus">Cloth
|
|
</li>
|
|
<li class="minus">Unlit
|
|
</li>
|
|
<li class="minus">Specular glossiness (legacy)</li></ul>
|
|
|
|
<p></p>
|
|
<a class="target" name="litmodel"> </a><a class="target" name="materialmodels/litmodel"> </a><a class="target" name="toc3.1"> </a><h2>Lit model</h2>
|
|
<p>
|
|
|
|
|
|
The lit model is Filament's standard material model. This physically-based shading model was
|
|
designed after to offer good interoperability with other common tools and engines such as <em class="underscore">Unity 5</em>,
|
|
<em class="underscore">Unreal Engine 4</em>, <em class="underscore">Substance Designer</em> or <em class="underscore">Marmoset Toolbag</em>.
|
|
|
|
</p><p>
|
|
|
|
This material model can be used to describe a large number of non-metallic surfaces (<em class="underscore">dielectrics</em>)
|
|
or metallic surfaces (<em class="underscore">conductors</em>).
|
|
|
|
</p><p>
|
|
|
|
The appearance of a material using the standard model is controlled using the properties described
|
|
in <a href="#table_standardproperties">table 1</a>.
|
|
|
|
</p><p>
|
|
|
|
</p><div class="table">
|
|
<table class="table"><tbody><tr><th style="text-align:right"> Property </th><th style="text-align:left"> Definition </th></tr>
|
|
<tr><td style="text-align:right"> <strong class="asterisk">baseColor</strong> </td><td style="text-align:left"> Diffuse albedo for non-metallic surfaces, and specular color for metallic surfaces </td></tr>
|
|
<tr><td style="text-align:right"> <strong class="asterisk">metallic</strong> </td><td style="text-align:left"> Whether a surface appears to be dielectric (0.0) or conductor (1.0). Often used as a binary value (0 or 1) </td></tr>
|
|
<tr><td style="text-align:right"> <strong class="asterisk">roughness</strong> </td><td style="text-align:left"> Perceived smoothness (1.0) or roughness (0.0) of a surface. Smooth surfaces exhibit sharp reflections </td></tr>
|
|
<tr><td style="text-align:right"> <strong class="asterisk">reflectance</strong> </td><td style="text-align:left"> Fresnel reflectance at normal incidence for dielectric surfaces. This directly controls the strength of the reflections </td></tr>
|
|
<tr><td style="text-align:right"> <strong class="asterisk">clearCoat</strong> </td><td style="text-align:left"> Strength of the clear coat layer </td></tr>
|
|
<tr><td style="text-align:right"> <strong class="asterisk">clearCoatRoughness</strong> </td><td style="text-align:left"> Perceived smoothness or roughness of the clear coat layer </td></tr>
|
|
<tr><td style="text-align:right"> <strong class="asterisk">anisotropy</strong> </td><td style="text-align:left"> Amount of anisotropy in either the tangent or bitangent direction </td></tr>
|
|
<tr><td style="text-align:right"> <strong class="asterisk">anisotropyDirection</strong> </td><td style="text-align:left"> Local surface direction </td></tr>
|
|
<tr><td style="text-align:right"> <strong class="asterisk">ambientOcclusion</strong> </td><td style="text-align:left"> Defines how much of the ambient light is accessible to a surface point. It is a per-pixel shadowing factor between 0.0 and 1.0 </td></tr>
|
|
<tr><td style="text-align:right"> <strong class="asterisk">normal</strong> </td><td style="text-align:left"> A detail normal used to perturb the surface using <em class="underscore">bump mapping</em> (<em class="underscore">normal mapping</em>) </td></tr>
|
|
<tr><td style="text-align:right"> <strong class="asterisk">bentNormal</strong> </td><td style="text-align:left"> A normal pointing in the average unoccluded direction. Can be used to improve indirect lighting quality </td></tr>
|
|
<tr><td style="text-align:right"> <strong class="asterisk">clearCoatNormal</strong> </td><td style="text-align:left"> A detail normal used to perturb the clear coat layer using <em class="underscore">bump mapping</em> (<em class="underscore">normal mapping</em>) </td></tr>
|
|
<tr><td style="text-align:right"> <strong class="asterisk">emissive</strong> </td><td style="text-align:left"> Additional diffuse albedo to simulate emissive surfaces (such as neons, etc.) This property is mostly useful in an HDR pipeline with a bloom pass </td></tr>
|
|
<tr><td style="text-align:right"> <strong class="asterisk">postLightingColor</strong> </td><td style="text-align:left"> Additional color that can be blended with the result of the lighting computations. See <code>postLightingBlending</code> </td></tr>
|
|
<tr><td style="text-align:right"> <strong class="asterisk">ior</strong> </td><td style="text-align:left"> Index of refraction for refractive objects </td></tr>
|
|
<tr><td style="text-align:right"> <strong class="asterisk">transmission</strong> </td><td style="text-align:left"> Defines how much of the diffuse light of a dielectric is transmitted through the object, in other words this defines how transparent an object is </td></tr>
|
|
<tr><td style="text-align:right"> <strong class="asterisk">absorption</strong> </td><td style="text-align:left"> Absorption factor for refractive objects </td></tr>
|
|
<tr><td style="text-align:right"> <strong class="asterisk">microThickness</strong> </td><td style="text-align:left"> Thickness of the thin layer of refractive objects </td></tr>
|
|
<tr><td style="text-align:right"> <strong class="asterisk">thickness</strong> </td><td style="text-align:left"> Thickness of the solid volume of refractive objects </td></tr>
|
|
</tbody></table><div class="tablecaption"><a class="target" name="table_standardproperties"> </a><b style="font-style:normal;">Table 1:</b> Properties of the standard model</div></div>
|
|
|
|
<p></p><p>
|
|
|
|
The type and range of each property is described in <a href="#table_standardpropertiestypes">table 2</a>.
|
|
</p><div class="table">
|
|
<table class="table"><tbody><tr><th style="text-align:right"> Property </th><th style="text-align:center"> Type </th><th style="text-align:center"> Range </th><th style="text-align:left"> Note </th></tr>
|
|
<tr><td style="text-align:right"> <strong class="asterisk">baseColor</strong> </td><td style="text-align:center"> float4 </td><td style="text-align:center"> [0..1] </td><td style="text-align:left"> Pre-multiplied linear RGB </td></tr>
|
|
<tr><td style="text-align:right"> <strong class="asterisk">metallic</strong> </td><td style="text-align:center"> float </td><td style="text-align:center"> [0..1] </td><td style="text-align:left"> Should be 0 or 1 </td></tr>
|
|
<tr><td style="text-align:right"> <strong class="asterisk">roughness</strong> </td><td style="text-align:center"> float </td><td style="text-align:center"> [0..1] </td><td style="text-align:left">   </td></tr>
|
|
<tr><td style="text-align:right"> <strong class="asterisk">reflectance</strong> </td><td style="text-align:center"> float </td><td style="text-align:center"> [0..1] </td><td style="text-align:left"> Prefer values > 0.35 </td></tr>
|
|
<tr><td style="text-align:right"> <strong class="asterisk">clearCoat</strong> </td><td style="text-align:center"> float </td><td style="text-align:center"> [0..1] </td><td style="text-align:left"> Should be 0 or 1 </td></tr>
|
|
<tr><td style="text-align:right"> <strong class="asterisk">clearCoatRoughness</strong> </td><td style="text-align:center"> float </td><td style="text-align:center"> [0..1] </td><td style="text-align:left">   </td></tr>
|
|
<tr><td style="text-align:right"> <strong class="asterisk">anisotropy</strong> </td><td style="text-align:center"> float </td><td style="text-align:center"> [−1..1] </td><td style="text-align:left"> Anisotropy is in the tangent direction when this value is positive </td></tr>
|
|
<tr><td style="text-align:right"> <strong class="asterisk">anisotropyDirection</strong> </td><td style="text-align:center"> float3 </td><td style="text-align:center"> [0..1] </td><td style="text-align:left"> Linear RGB, encodes a direction vector in tangent space </td></tr>
|
|
<tr><td style="text-align:right"> <strong class="asterisk">ambientOcclusion</strong> </td><td style="text-align:center"> float </td><td style="text-align:center"> [0..1] </td><td style="text-align:left">   </td></tr>
|
|
<tr><td style="text-align:right"> <strong class="asterisk">normal</strong> </td><td style="text-align:center"> float3 </td><td style="text-align:center"> [0..1] </td><td style="text-align:left"> Linear RGB, encodes a direction vector in tangent space </td></tr>
|
|
<tr><td style="text-align:right"> <strong class="asterisk">bentNormal</strong> </td><td style="text-align:center"> float3 </td><td style="text-align:center"> [0..1] </td><td style="text-align:left"> Linear RGB, encodes a direction vector in tangent space </td></tr>
|
|
<tr><td style="text-align:right"> <strong class="asterisk">clearCoatNormal</strong> </td><td style="text-align:center"> float3 </td><td style="text-align:center"> [0..1] </td><td style="text-align:left"> Linear RGB, encodes a direction vector in tangent space </td></tr>
|
|
<tr><td style="text-align:right"> <strong class="asterisk">emissive</strong> </td><td style="text-align:center"> float4 </td><td style="text-align:center"> rgb=[0..1], a=[-n..n] </td><td style="text-align:left"> Alpha is the exposure compensation </td></tr>
|
|
<tr><td style="text-align:right"> <strong class="asterisk">postLightingColor</strong> </td><td style="text-align:center"> float4 </td><td style="text-align:center"> [0..1] </td><td style="text-align:left"> Pre-multiplied linear RGB </td></tr>
|
|
<tr><td style="text-align:right"> <strong class="asterisk">ior</strong> </td><td style="text-align:center"> float </td><td style="text-align:center"> [1..n] </td><td style="text-align:left"> Optional, usually deduced from the reflectance </td></tr>
|
|
<tr><td style="text-align:right"> <strong class="asterisk">transmission</strong> </td><td style="text-align:center"> float </td><td style="text-align:center"> [0..1] </td><td style="text-align:left">   </td></tr>
|
|
<tr><td style="text-align:right"> <strong class="asterisk">absorption</strong> </td><td style="text-align:center"> float3 </td><td style="text-align:center"> [0..n] </td><td style="text-align:left">   </td></tr>
|
|
<tr><td style="text-align:right"> <strong class="asterisk">microThickness</strong> </td><td style="text-align:center"> float </td><td style="text-align:center"> [0..n] </td><td style="text-align:left">   </td></tr>
|
|
<tr><td style="text-align:right"> <strong class="asterisk">thickness</strong> </td><td style="text-align:center"> float </td><td style="text-align:center"> [0..n] </td><td style="text-align:left">   </td></tr>
|
|
</tbody></table><div class="tablecaption"><a class="target" name="table_standardpropertiestypes"> </a><b style="font-style:normal;">Table 2:</b> Range and type of the standard model's properties</div></div>
|
|
|
|
<p></p><p>
|
|
|
|
</p><div class="admonition note"><div class="admonition-title"> About linear RGB</div>
|
|
|
|
<p></p><p>
|
|
|
|
Several material model properties expect RGB colors. Filament materials use RGB colors in linear
|
|
space and you must take proper care of supplying colors in that space. See the <a href="#linearcolors">Linear colors</a> section for more information.</p></div>
|
|
|
|
<p></p><p>
|
|
|
|
</p><div class="admonition note"><div class="admonition-title"> About pre-multiplied RGB</div>
|
|
|
|
<p></p><p>
|
|
|
|
Filament materials expect colors to use pre-multiplied alpha. See the <a href="#pre-multipliedalpha">Pre-multiplied alpha</a> section for more information.</p></div>
|
|
|
|
<p></p><p>
|
|
|
|
</p><div class="admonition note"><div class="admonition-title"> About <code>absorption</code></div>
|
|
|
|
<p></p><p>
|
|
|
|
The light attenuation through the material is defined as \(e^{-absorption \cdot distance}\),
|
|
and the distance depends on the <code>thickness</code> parameter. If <code>thickness</code> is not provided, then
|
|
the <code>absorption</code> parameter is used directly and the light attenuation through the material
|
|
becomes \(1 - absorption\). To obtain a certain color at a desired distance, the above
|
|
equation can be inverted such as \(absorption = -\frac{ln(color)}{distance}\).</p></div>
|
|
|
|
<p></p><p>
|
|
|
|
</p><div class="admonition note"><div class="admonition-title"> About <code>ior</code> and <code>reflectance</code></div>
|
|
|
|
<p></p><p>
|
|
|
|
The index of refraction (IOR) and the reflectance represent the same physical attribute,
|
|
therefore they don't need to be both specified. Typically, only the reflectance is specified
|
|
and the IOR is deduced automatically. When only the IOR is specified, the reflectance is then
|
|
deduced automatically. It is possible to specify both, in which case their values are kept
|
|
as-is, which can lead to physically impossible materials, however, this might be desirable
|
|
for artistic reasons.</p></div>
|
|
|
|
<p></p><p>
|
|
|
|
</p><div class="admonition note"><div class="admonition-title"> About <code>thickness</code> and <code>microThickness</code> for refraction</div>
|
|
|
|
<p></p><p>
|
|
|
|
<code>thickness</code> represents the thickness of solid objects in the direction of the normal, for
|
|
satisfactory results, this should be provided per fragment (e.g.: as a texture) or at least per
|
|
vertex. <code>microThickness</code> represent the thickness of the thin layer of an object, and can
|
|
generally be provided as a constant value. For example, a 1mm thin hollow sphere of radius 1m,
|
|
would have a <code>thickness</code> of 1 and a <code>microThickness</code> of 0.001. Currently <code>thickness</code> is not
|
|
used when <code>refractionType</code> is set to <code>thin</code>.</p></div>
|
|
|
|
<p></p>
|
|
<a class="target" name="basecolor"> </a><a class="target" name="materialmodels/litmodel/basecolor"> </a><a class="target" name="toc3.1.1"> </a><h3>Base color</h3>
|
|
<p>
|
|
|
|
|
|
The <code>baseColor</code> property defines the perceived color of an object (sometimes called albedo). The
|
|
effect of <code>baseColor</code> depends on the nature of the surface, controlled by the <code>metallic</code> property
|
|
explained in the <a href="#metallic">Metallic</a> section.
|
|
|
|
</p><p>
|
|
|
|
</p><dl><dt>Non-metals (dielectrics)</dt><dd><p> Defines the diffuse color of the surface. Real-world values are typically found in the range
|
|
\([10..240]\) if the value is encoded between 0 and 255, or in the range \([0.04..0.94]\) between 0
|
|
and 1. Several examples of base colors for non-metallic surfaces can be found in
|
|
<a href="#table_basecolorsdielectrics">table 3</a>.
|
|
|
|
</p></dd></dl><div class="table">
|
|
<table class="table"><tbody><tr><th style="text-align:right"> Metal </th><th style="text-align:center"> sRGB </th><th style="text-align:center"> Hexadecimal </th><th style="text-align:left"> Color </th></tr>
|
|
<tr><td style="text-align:right"> Coal </td><td style="text-align:center"> 0.19, 0.19, 0.19 </td><td style="text-align:center"> #323232 </td><td style="text-align:left"> <div style="background-color: #323232; width: 60px"> </div> </td></tr>
|
|
<tr><td style="text-align:right"> Rubber </td><td style="text-align:center"> 0.21, 0.21, 0.21 </td><td style="text-align:center"> #353535 </td><td style="text-align:left"> <div style="background-color: #353535; width: 60px"> </div> </td></tr>
|
|
<tr><td style="text-align:right"> Mud </td><td style="text-align:center"> 0.33, 0.24, 0.19 </td><td style="text-align:center"> #553d31 </td><td style="text-align:left"> <div style="background-color: #875c3c; width: 60px"> </div> </td></tr>
|
|
<tr><td style="text-align:right"> Wood </td><td style="text-align:center"> 0.53, 0.36, 0.24 </td><td style="text-align:center"> #875c3c </td><td style="text-align:left"> <div style="background-color: #c4c6c6; width: 60px"> </div> </td></tr>
|
|
<tr><td style="text-align:right"> Vegetation </td><td style="text-align:center"> 0.48, 0.51, 0.31 </td><td style="text-align:center"> #7b824e </td><td style="text-align:left"> <div style="background-color: #7b824e; width: 60px"> </div> </td></tr>
|
|
<tr><td style="text-align:right"> Brick </td><td style="text-align:center"> 0.58, 0.49, 0.46 </td><td style="text-align:center"> #947d75 </td><td style="text-align:left"> <div style="background-color: #947d75; width: 60px"> </div> </td></tr>
|
|
<tr><td style="text-align:right"> Sand </td><td style="text-align:center"> 0.69, 0.66, 0.52 </td><td style="text-align:center"> #b1a884 </td><td style="text-align:left"> <div style="background-color: #b1a884; width: 60px"> </div> </td></tr>
|
|
<tr><td style="text-align:right"> Concrete </td><td style="text-align:center"> 0.75, 0.75, 0.73 </td><td style="text-align:center"> #c0bfbb </td><td style="text-align:left"> <div style="background-color: #c0bfbb; width: 60px"> </div> </td></tr>
|
|
</tbody></table><div class="tablecaption"><a class="target" name="table_basecolorsdielectrics"> </a><b style="font-style:normal;">Table 3:</b> <code>baseColor</code> for common non-metals</div></div>
|
|
|
|
<p></p><p>
|
|
|
|
</p><dl><dt>Metals (conductors)</dt><dd><p> Defines the specular color of the surface. Real-world values are typically found in the range
|
|
\([170..255]\) if the value is encoded between 0 and 255, or in the range \([0.66..1.0]\) between 0 and
|
|
1. Several examples of base colors for metallic surfaces can be found in <a href="#table_basecolorsconductors">table 4</a>.
|
|
|
|
</p></dd></dl><div class="table">
|
|
<table class="table"><tbody><tr><th style="text-align:right"> Metal </th><th style="text-align:center"> sRGB </th><th style="text-align:center"> Hexadecimal </th><th style="text-align:left"> Color </th></tr>
|
|
<tr><td style="text-align:right"> Silver </td><td style="text-align:center"> 0.97, 0.96, 0.91 </td><td style="text-align:center"> #f7f4e8 </td><td style="text-align:left"> <div style="background-color: #faf9f5; width: 60px"> </div> </td></tr>
|
|
<tr><td style="text-align:right"> Aluminum </td><td style="text-align:center"> 0.91, 0.92, 0.92 </td><td style="text-align:center"> #e8eaea </td><td style="text-align:left"> <div style="background-color: #f4f5f5; width: 60px"> </div> </td></tr>
|
|
<tr><td style="text-align:right"> Titanium </td><td style="text-align:center"> 0.76, 0.73, 0.69 </td><td style="text-align:center"> #c1baaf </td><td style="text-align:left"> <div style="background-color: #cec8c2; width: 60px"> </div> </td></tr>
|
|
<tr><td style="text-align:right"> Iron </td><td style="text-align:center"> 0.77, 0.78, 0.78 </td><td style="text-align:center"> #c4c6c6 </td><td style="text-align:left"> <div style="background-color: #c0bdba; width: 60px"> </div> </td></tr>
|
|
<tr><td style="text-align:right"> Platinum </td><td style="text-align:center"> 0.83, 0.81, 0.78 </td><td style="text-align:center"> #d3cec6 </td><td style="text-align:left"> <div style="background-color: #d6d1c8; width: 60px"> </div> </td></tr>
|
|
<tr><td style="text-align:right"> Gold </td><td style="text-align:center"> 1.00, 0.85, 0.57 </td><td style="text-align:center"> #ffd891 </td><td style="text-align:left"> <div style="background-color: #fedc9d; width: 60px"> </div> </td></tr>
|
|
<tr><td style="text-align:right"> Brass </td><td style="text-align:center"> 0.98, 0.90, 0.59 </td><td style="text-align:center"> #f9e596 </td><td style="text-align:left"> <div style="background-color: #f4e4ad; width: 60px"> </div> </td></tr>
|
|
<tr><td style="text-align:right"> Copper </td><td style="text-align:center"> 0.97, 0.74, 0.62 </td><td style="text-align:center"> #f7bc9e </td><td style="text-align:left"> <div style="background-color: #fbd8b8; width: 60px"> </div> </td></tr>
|
|
</tbody></table><div class="tablecaption"><a class="target" name="table_basecolorsconductors"> </a><b style="font-style:normal;">Table 4:</b> <code>baseColor</code> for common metals</div></div>
|
|
|
|
<p></p>
|
|
<a class="target" name="metallic"> </a><a class="target" name="materialmodels/litmodel/metallic"> </a><a class="target" name="toc3.1.2"> </a><h3>Metallic</h3>
|
|
<p>
|
|
|
|
|
|
The <code>metallic</code> property defines whether the surface is a metallic (<em class="underscore">conductor</em>) or a non-metallic
|
|
(<em class="underscore">dielectric</em>) surface. This property should be used as a binary value, set to either 0 or 1.
|
|
Intermediate values are only truly useful to create transitions between different types of surfaces
|
|
when using textures.
|
|
|
|
</p><p>
|
|
|
|
This property can dramatically change the appearance of a surface. Non-metallic surfaces have
|
|
chromatic diffuse reflection and achromatic specular reflection (reflected light does not change
|
|
color). Metallic surfaces do not have any diffuse reflection and chromatic specular reflection
|
|
(reflected light takes on the color of the surfaced as defined by <code>baseColor</code>).
|
|
|
|
</p><p>
|
|
|
|
The effect of <code>metallic</code> is shown in <a href="#figure_metallicproperty">figure 1</a> (click on the image to see a
|
|
larger version).
|
|
|
|
</p><p>
|
|
|
|
</p><center><div class="image" style><a href="images/materials/metallic.png" target="_blank"><img class="markdeep" src="images/materials/metallic.png"></a><div class="imagecaption"><a class="target" name="figure_metallicproperty"> </a><b style="font-style:normal;">Figure 1:</b> <code>metallic</code> varying from 0.0
|
|
(left) to 1.0 (right)</div></div></center>
|
|
|
|
<p></p>
|
|
<a class="target" name="roughness"> </a><a class="target" name="materialmodels/litmodel/roughness"> </a><a class="target" name="toc3.1.3"> </a><h3>Roughness</h3>
|
|
<p>
|
|
|
|
|
|
The <code>roughness</code> property controls the perceived smoothness of the surface. When <code>roughness</code> is set
|
|
to 0, the surface is perfectly smooth and highly glossy. The rougher a surface is, the “blurrier”
|
|
the reflections are. This property is often called <em class="underscore">glossiness</em> in other engines and tools, and is
|
|
simply the opposite of the roughness (<code>roughness = 1 - glossiness</code>).
|
|
|
|
</p>
|
|
<a class="target" name="non-metals"> </a><a class="target" name="materialmodels/litmodel/non-metals"> </a><a class="target" name="toc3.1.4"> </a><h3>Non-metals</h3>
|
|
<p>
|
|
|
|
|
|
The effect of <code>roughness</code> on non-metallic surfaces is shown in <a href="#figure_roughnessproperty">figure 2</a> (click
|
|
on the image to see a larger version).
|
|
|
|
</p><p>
|
|
|
|
</p><center><div class="image" style><a href="images/materials/dielectric_roughness.png" target="_blank"><img class="markdeep" src="images/materials/dielectric_roughness.png"></a><div class="imagecaption"><a class="target" name="figure_roughnessproperty"> </a><b style="font-style:normal;">Figure 2:</b> Dielectric <code>roughness</code> varying from 0.0
|
|
(left) to 1.0 (right)</div></div></center>
|
|
|
|
<p></p>
|
|
<a class="target" name="metals"> </a><a class="target" name="materialmodels/litmodel/metals"> </a><a class="target" name="toc3.1.5"> </a><h3>Metals</h3>
|
|
<p>
|
|
|
|
|
|
The effect of <code>roughness</code> on metallic surfaces is shown in <a href="#figure_roughnessconductorproperty">figure 3</a>
|
|
(click on the image to see a larger version).
|
|
|
|
</p><p>
|
|
|
|
</p><center><div class="image" style><a href="images/materials/conductor_roughness.png" target="_blank"><img class="markdeep" src="images/materials/conductor_roughness.png"></a><div class="imagecaption"><a class="target" name="figure_roughnessconductorproperty"> </a><b style="font-style:normal;">Figure 3:</b> Conductor <code>roughness</code> varying from 0.0
|
|
(left) to 1.0 (right)</div></div></center>
|
|
|
|
<p></p>
|
|
<a class="target" name="refraction"> </a><a class="target" name="materialmodels/litmodel/refraction"> </a><a class="target" name="toc3.1.6"> </a><h3>Refraction</h3>
|
|
<p>
|
|
|
|
|
|
When refraction through an object is enabled (using a <code>refractonType</code> of <code>thin</code> or <code>solid</code>), the
|
|
<code>roughness</code> property will also affect the refractions, as shown in <a href="#figure_roughnessrefractionproperty">figure 4</a> (click on the image to see a larger version).
|
|
|
|
</p><p>
|
|
|
|
</p><center><div class="image" style><a href="images/materials/refraction_roughness.png" target="_blank"><img class="markdeep" src="images/materials/refraction_roughness.png"></a><div class="imagecaption"><a class="target" name="figure_roughnessrefractionproperty"> </a><b style="font-style:normal;">Figure 4:</b> Refractive sphere with <code>roughness</code> varying from 0.0
|
|
(left) to 1.0 (right)</div></div></center>
|
|
|
|
<p></p>
|
|
<a class="target" name="reflectance"> </a><a class="target" name="materialmodels/litmodel/reflectance"> </a><a class="target" name="toc3.1.7"> </a><h3>Reflectance</h3>
|
|
<p>
|
|
|
|
|
|
The <code>reflectance</code> property only affects non-metallic surfaces. This property can be used to control
|
|
the specular intensity and index of refraction of materials. This value is defined
|
|
between 0 and 1 and represents a remapping of a percentage of reflectance. For instance, the
|
|
default value of 0.5 corresponds to a reflectance of 4%. Values below 0.35 (2% reflectance) should
|
|
be avoided as no real-world materials have such low reflectance.
|
|
|
|
</p><p>
|
|
|
|
The effect of <code>reflectance</code> on non-metallic surfaces is shown in <a href="#figure_reflectanceproperty">figure 5</a>
|
|
(click on the image to see a larger version).
|
|
|
|
</p><p>
|
|
|
|
</p><center><div class="image" style><a href="images/materials/reflectance.png" target="_blank"><img class="markdeep" src="images/materials/reflectance.png"></a><div class="imagecaption"><a class="target" name="figure_reflectanceproperty"> </a><b style="font-style:normal;">Figure 5:</b> <code>reflectance</code> varying from 0.0 (left)
|
|
to 1.0 (right)</div></div></center>
|
|
|
|
<p></p><p>
|
|
|
|
<a href="#figure_reflectance">Figure 6</a> shows common values and how they relate to the mapping function.
|
|
|
|
</p><p>
|
|
|
|
</p><center><div class="image" style><a href="images/diagram_reflectance.png" target="_blank"><img class="markdeep" src="images/diagram_reflectance.png"></a><div class="imagecaption"><a class="target" name="figure_reflectance"> </a><b style="font-style:normal;">Figure 6:</b> Common reflectance values</div></div></center>
|
|
|
|
<p></p><p>
|
|
|
|
<a href="#table_commonmatreflectance">Table 5</a> describes acceptable reflectance values for various types of materials
|
|
(no real world material has a value under 2%).
|
|
|
|
</p><p>
|
|
|
|
</p><div class="table">
|
|
<table class="table"><tbody><tr><th style="text-align:right"> Material </th><th style="text-align:left"> Reflectance </th><th style="text-align:left"> IOR </th><th style="text-align:left"> Linear value </th></tr>
|
|
<tr><td style="text-align:right"> Water </td><td style="text-align:left"> 2% </td><td style="text-align:left"> 1.33 </td><td style="text-align:left"> 0.35 </td></tr>
|
|
<tr><td style="text-align:right"> Fabric </td><td style="text-align:left"> 4% to 5.6% </td><td style="text-align:left"> 1.5 to 1.62 </td><td style="text-align:left"> 0.5 to 0.59 </td></tr>
|
|
<tr><td style="text-align:right"> Common liquids </td><td style="text-align:left"> 2% to 4% </td><td style="text-align:left"> 1.33 to 1.5 </td><td style="text-align:left"> 0.35 to 0.5 </td></tr>
|
|
<tr><td style="text-align:right"> Common gemstones </td><td style="text-align:left"> 5% to 16% </td><td style="text-align:left"> 1.58 to 2.33 </td><td style="text-align:left"> 0.56 to 1.0 </td></tr>
|
|
<tr><td style="text-align:right"> Plastics, glass </td><td style="text-align:left"> 4% to 5% </td><td style="text-align:left"> 1.5 to 1.58 </td><td style="text-align:left"> 0.5 to 0.56 </td></tr>
|
|
<tr><td style="text-align:right"> Other dielectric materials </td><td style="text-align:left"> 2% to 5% </td><td style="text-align:left"> 1.33 to 1.58 </td><td style="text-align:left"> 0.35 to 0.56 </td></tr>
|
|
<tr><td style="text-align:right"> Eyes </td><td style="text-align:left"> 2.5% </td><td style="text-align:left"> 1.38 </td><td style="text-align:left"> 0.39 </td></tr>
|
|
<tr><td style="text-align:right"> Skin </td><td style="text-align:left"> 2.8% </td><td style="text-align:left"> 1.4 </td><td style="text-align:left"> 0.42 </td></tr>
|
|
<tr><td style="text-align:right"> Hair </td><td style="text-align:left"> 4.6% </td><td style="text-align:left"> 1.55 </td><td style="text-align:left"> 0.54 </td></tr>
|
|
<tr><td style="text-align:right"> Teeth </td><td style="text-align:left"> 5.8% </td><td style="text-align:left"> 1.63 </td><td style="text-align:left"> 0.6 </td></tr>
|
|
<tr><td style="text-align:right"> Default value </td><td style="text-align:left"> 4% </td><td style="text-align:left"> 1.5 </td><td style="text-align:left"> 0.5 </td></tr>
|
|
</tbody></table><div class="tablecaption"><a class="target" name="table_commonmatreflectance"> </a><b style="font-style:normal;">Table 5:</b> Reflectance of common materials</div></div>
|
|
|
|
<p></p><p>
|
|
|
|
Note that the <code>reflectance</code> property also defines the index of refraction of the surface.
|
|
When this property is defined it is not necessary to define the <code>ior</code> property. Setting
|
|
either of these properties will automatically compute the other property. It is possible
|
|
to specify both, in which case their values are kept as-is, which can lead to physically
|
|
impossible materials, however, this might be desirable for artistic reasons.
|
|
|
|
</p><p>
|
|
|
|
The <code>reflectance</code> property is designed as a normalized property in the range 0..1 which makes
|
|
it easy to define from a texture.
|
|
|
|
</p><p>
|
|
|
|
See the Index of <a href="#refraction">refraction</a> section for more information about the <code>ior</code> property and refractive
|
|
indices.
|
|
|
|
</p>
|
|
<a class="target" name="clearcoat"> </a><a class="target" name="materialmodels/litmodel/clearcoat"> </a><a class="target" name="toc3.1.8"> </a><h3>Clear coat</h3>
|
|
<p>
|
|
|
|
|
|
Multi-layer materials are fairly common, particularly materials with a thin translucent
|
|
layer over a base layer. Real world examples of such materials include car paints, soda cans,
|
|
lacquered wood and acrylic.
|
|
|
|
</p><p>
|
|
|
|
The <code>clearCoat</code> property can be used to describe materials with two layers. The clear coat layer
|
|
will always be isotropic and dielectric.
|
|
|
|
</p><p>
|
|
|
|
</p><center><div class="image" style><a href="images/material_carbon_fiber.png" target="_blank"><img class="markdeep" src="images/material_carbon_fiber.png"></a><div class="imagecaption"><a class="target" name="figure_clearcoat"> </a><b style="font-style:normal;">Figure 7:</b> Comparison of a carbon-fiber material under the standard material model
|
|
(left) and the clear coat model (right)</div></div></center>
|
|
|
|
<p></p><p>
|
|
|
|
The <code>clearCoat</code> property controls the strength of the clear coat layer. This should be treated as a
|
|
binary value, set to either 0 or 1. Intermediate values are useful to control transitions between
|
|
parts of the surface that have a clear coat layers and parts that don't.
|
|
|
|
</p><p>
|
|
|
|
The effect of <code>clearCoat</code> on a rough metal is shown in <a href="#figure_clearcoatproperty">figure 8</a>
|
|
(click on the image to see a larger version).
|
|
|
|
</p><p>
|
|
|
|
</p><center><div class="image" style><a href="images/materials/clear_coat.png" target="_blank"><img class="markdeep" src="images/materials/clear_coat.png"></a><div class="imagecaption"><a class="target" name="figure_clearcoatproperty"> </a><b style="font-style:normal;">Figure 8:</b> <code>clearCoat</code> varying from 0.0
|
|
(left) to 1.0 (right)</div></div></center>
|
|
|
|
<p></p><p>
|
|
|
|
</p><div class="admonition warning">The clear coat layer effectively doubles the cost of specular computations. Do not assign a
|
|
value, even 0.0, to the clear coat property if you don't need this second layer.</div>
|
|
|
|
<p></p>
|
|
<a class="target" name="clearcoatroughness"> </a><a class="target" name="materialmodels/litmodel/clearcoatroughness"> </a><a class="target" name="toc3.1.9"> </a><h3>Clear coat roughness</h3>
|
|
<p>
|
|
|
|
|
|
The <code>clearCoatRoughness</code> property is similar to the <code>roughness</code> property but applies only to the
|
|
clear coat layer.
|
|
|
|
</p><p>
|
|
|
|
The effect of <code>clearCoatRoughness</code> on a rough metal is shown in <a href="#figure_clearcoatroughnessproperty">figure 9</a>
|
|
(click on the image to see a larger version).
|
|
|
|
</p><p>
|
|
|
|
</p><center><div class="image" style><a href="images/materials/clear_coat_roughness.png" target="_blank"><img class="markdeep" src="images/materials/clear_coat_roughness.png"></a><div class="imagecaption"><a class="target" name="figure_clearcoatroughnessproperty"> </a><b style="font-style:normal;">Figure 9:</b> <code>clearCoatRoughness</code> varying from 0.0
|
|
(left) to 1.0 (right)</div></div></center>
|
|
|
|
<p></p>
|
|
<a class="target" name="anisotropy"> </a><a class="target" name="materialmodels/litmodel/anisotropy"> </a><a class="target" name="toc3.1.10"> </a><h3>Anisotropy</h3>
|
|
<p>
|
|
|
|
|
|
Many real-world materials, such as brushed metal, can only be replicated using an anisotropic
|
|
reflectance model. A material can be changed from the default isotropic model to an anisotropic
|
|
model by using the <code>anisotropy</code> property.
|
|
|
|
</p><p>
|
|
|
|
</p><center><div class="image" style><a href="images/material_anisotropic.png" target="_blank"><img class="markdeep" src="images/material_anisotropic.png"></a><div class="imagecaption"><a class="target" name="figure_anisotropic"> </a><b style="font-style:normal;">Figure 10:</b> Comparison of isotropic material
|
|
(left) and anistropic material (right)</div></div></center>
|
|
|
|
<p></p><p>
|
|
|
|
The effect of <code>anisotropy</code> on a rough metal is shown in <a href="#figure_anisotropyproperty">figure 11</a>
|
|
(click on the image to see a larger version).
|
|
|
|
</p><p>
|
|
|
|
</p><center><div class="image" style><a href="images/materials/anisotropy.png" target="_blank"><img class="markdeep" src="images/materials/anisotropy.png"></a><div class="imagecaption"><a class="target" name="figure_anisotropyproperty"> </a><b style="font-style:normal;">Figure 11:</b> <code>anisotropy</code> varying from 0.0
|
|
(left) to 1.0 (right)</div></div></center>
|
|
|
|
<p></p><p>
|
|
|
|
The <a href="#figure_anisotropydir">figure 12</a> below shows how the direction of the anisotropic highlights can be
|
|
controlled by using either positive or negative values: positive values define anisotropy in the
|
|
tangent direction and negative values in the bitangent direction.
|
|
|
|
</p><p>
|
|
|
|
</p><center><div class="image" style><a href="images/screenshot_anisotropy_direction.png" target="_blank"><img class="markdeep" src="images/screenshot_anisotropy_direction.png"></a><div class="imagecaption"><a class="target" name="figure_anisotropydir"> </a><b style="font-style:normal;">Figure 12:</b> Positive (left) vs negative
|
|
(right) <code>anisotropy</code> values</div></div></center>
|
|
|
|
<p></p><p>
|
|
|
|
</p><div class="admonition tip">The anisotropic material model is slightly more expensive than the standard material model. Do
|
|
not assign a value (even 0.0) to the <code>anisotropy</code> property if you don't need anisotropy.</div>
|
|
|
|
<p></p>
|
|
<a class="target" name="anisotropydirection"> </a><a class="target" name="materialmodels/litmodel/anisotropydirection"> </a><a class="target" name="toc3.1.11"> </a><h3>Anisotropy direction</h3>
|
|
<p>
|
|
|
|
|
|
The <code>anisotropyDirection</code> property defines the direction of the surface at a given point and thus
|
|
control the shape of the specular highlights. It is specified as vector of 3 values that usually
|
|
come from a texture, encoding the directions local to the surface.
|
|
|
|
</p><p>
|
|
|
|
The effect of <code>anisotropyDirection</code> on a metal is shown in <a href="#figure_anisotropydirectionproperty">figure 14</a>
|
|
(click on the image to see a larger version).
|
|
|
|
</p><p>
|
|
|
|
</p><center><div class="image" style><a href="images/screenshot_anisotropy.png" target="_blank"><img class="markdeep" src="images/screenshot_anisotropy.png"></a><div class="imagecaption"><a class="target" name="figure_anisotropydirectionproperty"> </a><b style="font-style:normal;">Figure 13:</b> Anisotropic metal rendered
|
|
with a direction map</div></div></center>
|
|
|
|
<p></p><p>
|
|
|
|
The result shown in <a href="#figure_anisotropydirectionproperty">figure 14</a> was obtained using the direction map shown
|
|
in <a href="#figure_anisotropydirectionproperty">figure 14</a>.
|
|
|
|
</p><p>
|
|
|
|
</p><center><div class="image" style><a href="images/screenshot_anisotropy_map.jpg" target="_blank"><img class="markdeep" src="images/screenshot_anisotropy_map.jpg"></a><div class="imagecaption"><a class="target" name="figure_anisotropydirectionproperty"> </a><b style="font-style:normal;">Figure 14:</b> Example of a direction map</div></div></center>
|
|
|
|
<p></p>
|
|
<a class="target" name="ambientocclusion"> </a><a class="target" name="materialmodels/litmodel/ambientocclusion"> </a><a class="target" name="toc3.1.12"> </a><h3>Ambient occlusion</h3>
|
|
<p>
|
|
|
|
|
|
The <code>ambientOcclusion</code> property defines how much of the ambient light is accessible to a surface
|
|
point. It is a per-pixel shadowing factor between 0.0 (fully shadowed) and 1.0 (fully lit). This
|
|
property only affects diffuse indirect lighting (image-based lighting), not direct lights such as
|
|
directional, point and spot lights, nor specular lighting.
|
|
|
|
</p><p>
|
|
|
|
</p><center><div class="image" style><a href="images/screenshot_ao.jpg" target="_blank"><img class="markdeep" src="images/screenshot_ao.jpg"></a><div class="imagecaption"><a class="target" name="figure_aoexample"> </a><b style="font-style:normal;">Figure 15:</b> Comparison of materials without diffuse ambient occlusion
|
|
(left) and with (right)</div></div></center>
|
|
|
|
<p></p>
|
|
<a class="target" name="normal"> </a><a class="target" name="materialmodels/litmodel/normal"> </a><a class="target" name="toc3.1.13"> </a><h3>Normal</h3>
|
|
<p>
|
|
|
|
|
|
The <code>normal</code> property defines the normal of the surface at a given point. It usually comes from a
|
|
<em class="underscore">normal map</em> texture, which allows to vary the property per-pixel. The normal is supplied in tangent
|
|
space, which means that +Z points outside of the surface.
|
|
|
|
</p><p>
|
|
|
|
For example, let's imagine that we want to render a piece of furniture covered in tufted leather.
|
|
Modeling the geometry to accurately represent the tufted pattern would require too many triangles
|
|
so we instead bake a high-poly mesh into a normal map. Once the base map is applied to a simplified
|
|
mesh, we get the result in <a href="#figure_normalmapped">figure 16</a>.
|
|
|
|
</p><p>
|
|
|
|
Note that the <code>normal</code> property affects the <em class="underscore">base layer</em> and not the clear coat layer.
|
|
|
|
</p><p>
|
|
|
|
</p><center><div class="image" style><a href="images/screenshot_normal_mapping.jpg" target="_blank"><img class="markdeep" src="images/screenshot_normal_mapping.jpg"></a><div class="imagecaption"><a class="target" name="figure_normalmapped"> </a><b style="font-style:normal;">Figure 16:</b> Low-poly mesh without normal mapping (left)
|
|
and with (right)</div></div></center>
|
|
|
|
<p></p><p>
|
|
|
|
</p><div class="admonition warning">Using a normal map increases the runtime cost of the material model.</div>
|
|
|
|
<p></p>
|
|
<a class="target" name="bentnormal"> </a><a class="target" name="materialmodels/litmodel/bentnormal"> </a><a class="target" name="toc3.1.14"> </a><h3>Bent normal</h3>
|
|
<p>
|
|
|
|
|
|
The <code>bentNormal</code> property defines the average unoccluded direction at a point on the surface. It is
|
|
used to improve the accuracy of indirect lighting. Bent normals also improve the quality of
|
|
specular ambient occlusion (see section <a href="#toc4.2.24">4.2.24</a> about
|
|
<code>specularAmbientOcclusion</code>).
|
|
|
|
</p><p>
|
|
|
|
Bent normals can greatly increase the visual fidelity of an asset with various cavities and concave
|
|
areas, as shown in <a href="#figure_bentnormalmapped">figure 17</a>. See the areas of the ears, nostrils and eyes for
|
|
instance.
|
|
|
|
</p><p>
|
|
|
|
</p><center><div class="image" style><a href="images/material_bent_normal.gif" target="_blank"><img class="markdeep" src="images/material_bent_normal.gif"></a><div class="imagecaption"><a class="target" name="figure_bentnormalmapped"> </a><b style="font-style:normal;">Figure 17:</b> Example of a model rendered with and without a bent normal map. Both
|
|
versions use the same ambient occlusion map.</div></div></center>
|
|
|
|
<p></p><p>
|
|
|
|
</p><div class="admonition warning">Using a bent normal map increases the runtime cost of the material, particularly when
|
|
<code>specularAmbientOcclusion</code> is turned on.</div>
|
|
|
|
<p></p>
|
|
<a class="target" name="clearcoatnormal"> </a><a class="target" name="materialmodels/litmodel/clearcoatnormal"> </a><a class="target" name="toc3.1.15"> </a><h3>Clear coat normal</h3>
|
|
<p>
|
|
|
|
|
|
The <code>clearCoatNormal</code> property defines the normal of the clear coat layer at a given point. It
|
|
behaves otherwise like the <code>normal</code> property.
|
|
|
|
</p><p>
|
|
|
|
</p><center><div class="image" style><a href="images/screenshot_clear_coat_normal.jpg" target="_blank"><img class="markdeep" src="images/screenshot_clear_coat_normal.jpg"></a><div class="imagecaption"><a class="target" name="figure_clearcoatnormalmapped"> </a><b style="font-style:normal;">Figure 18:</b> A material with a clear coat normal
|
|
map and a surface normal map</div></div></center>
|
|
|
|
<p></p><p>
|
|
|
|
</p><div class="admonition warning">Using a clear coat normal map increases the runtime cost of the material model.</div>
|
|
|
|
<p></p>
|
|
<a class="target" name="emissive"> </a><a class="target" name="materialmodels/litmodel/emissive"> </a><a class="target" name="toc3.1.16"> </a><h3>Emissive</h3>
|
|
<p>
|
|
|
|
|
|
The <code>emissive</code> property can be used to simulate additional light emitted by the surface. It is
|
|
defined as a <code>float4</code> value that contains an RGB color (in linear space) as well as an exposure
|
|
compensation value (in the alpha channel).
|
|
|
|
</p><p>
|
|
|
|
Even though an exposure value actually indicates combinations of camera settings, it is often used
|
|
by photographers to describe light intensity. This is why cameras let photographers apply an
|
|
exposure compensation to over or under-expose an image. This setting can be used for artistic
|
|
control but also to achieve proper exposure (snow for instance will be exposed for as
|
|
18% middle-grey).
|
|
|
|
</p><p>
|
|
|
|
The exposure compensation value of the emissive property can be used to force the emissive color
|
|
to be brighter (positive values) or darker (negative values) than the current exposure. If the bloom
|
|
effect is enabled, using a positive exposure compensation can force the surface to bloom.
|
|
|
|
</p>
|
|
<a class="target" name="post-lightingcolor"> </a><a class="target" name="materialmodels/litmodel/post-lightingcolor"> </a><a class="target" name="toc3.1.17"> </a><h3>Post-lighting color</h3>
|
|
<p>
|
|
|
|
|
|
The <code>postLightingColor</code> can be used to modify the surface color after lighting computations. This
|
|
property has no physical meaning and only exists to implement specific effects or to help with
|
|
debugging. This property is defined as a <code>float4</code> value containing a pre-multiplied RGB color in
|
|
linear space.
|
|
|
|
</p><p>
|
|
|
|
The post-lighting color is blended with the result of lighting according to the blending mode
|
|
specified by the <code>postLightingBlending</code> material option. Please refer to the documentation of
|
|
this option for more information.
|
|
|
|
</p><p>
|
|
|
|
</p><div class="admonition tip"><code>postLightingColor</code> can be used as a simpler <code>emissive</code> property by setting
|
|
<code>postLightingBlending</code> to <code>add</code> and by providing an RGB color with alpha set to <code>0.0</code>.</div>
|
|
|
|
<p></p>
|
|
<a class="target" name="indexofrefraction"> </a><a class="target" name="materialmodels/litmodel/indexofrefraction"> </a><a class="target" name="toc3.1.18"> </a><h3>Index of refraction</h3>
|
|
<p>
|
|
|
|
|
|
The <code>ior</code> property only affects non-metallic surfaces. This property can be used to control the
|
|
index of refraction and the specular intensity of materials. The <code>ior</code> property is intended to
|
|
be used with refractive (transmissive) materials, which are enabled when the <code>refractionMode</code> is
|
|
set to <code>cubemap</code> or <code>screenspace</code>.
|
|
|
|
</p><p>
|
|
|
|
The index of refraction (or refractive index) of a material is a dimensionless number that describes
|
|
how fast light travels through that material. The higher the number, the slower light travels
|
|
through the medium. More importantly for rendering materials, the refractive index determines how
|
|
the path light travels is bent when entering the material. Higher indices of refraction will cause
|
|
light to bend further away from the initial path.
|
|
|
|
</p><p>
|
|
|
|
<a href="#table_commonmatior">Table 6</a> describes acceptable refractive indices for various types of materials.
|
|
</p><div class="table">
|
|
<table class="table"><tbody><tr><th style="text-align:right"> Material </th><th style="text-align:left"> IOR </th></tr>
|
|
<tr><td style="text-align:right"> Air </td><td style="text-align:left"> 1.0 </td></tr>
|
|
<tr><td style="text-align:right"> Water </td><td style="text-align:left"> 1.33 </td></tr>
|
|
<tr><td style="text-align:right"> Common liquids </td><td style="text-align:left"> 1.33 to 1.5 </td></tr>
|
|
<tr><td style="text-align:right"> Common gemstones </td><td style="text-align:left"> 1.58 to 2.33 </td></tr>
|
|
<tr><td style="text-align:right"> Plastics, glass </td><td style="text-align:left"> 1.5 to 1.58 </td></tr>
|
|
<tr><td style="text-align:right"> Other dielectric materials </td><td style="text-align:left"> 1.33 to 1.58 </td></tr>
|
|
</tbody></table><div class="tablecaption"><a class="target" name="table_commonmatior"> </a><b style="font-style:normal;">Table 6:</b> Index of refraction of common materials</div></div>
|
|
|
|
<p></p><p>
|
|
|
|
The appearance of a refractive material will greatly depend on the <code>refractionType</code> and
|
|
<code>refractionMode</code> settings of the material. Refer to the <a href="#blendingandtransparency:refractiontype">Blending and transparency: refractionType</a> section and the <a href="#blendingandtransparency:refractionmode">Blending and transparency: refractionMode</a> section for more information.
|
|
|
|
</p><p>
|
|
|
|
The effect of <code>ior</code> when <code>refractionMode</code> is set to <code>cubemap</code> and <code>refractionType</code> is set to <code>solid</code>
|
|
can be seen in <a href="#figure_iorproperty2">figure 19</a> (click on the image to see a larger version).
|
|
|
|
</p><p>
|
|
|
|
</p><center><div class="image" style><a href="images/materials/ior.png" target="_blank"><img class="markdeep" src="images/materials/ior.png"></a><div class="imagecaption"><a class="target" name="figure_iorproperty2"> </a><b style="font-style:normal;">Figure 19:</b> <code>transmission</code> varying from 1.0
|
|
(left) to 1.5 (right)</div></div></center>
|
|
|
|
<p></p><p>
|
|
|
|
<a href="#figure_iorproperty">Figure 20</a> shows the comparison of a sphere of <code>ior</code> 1.0 with a sphere of <code>ior</code> 1.33, with
|
|
the <code>refractionMode</code> set to <code>screenspace</code> and the <code>refractionType</code> set to <code>solid</code>
|
|
(click on the image to see a larger version).
|
|
|
|
</p><p>
|
|
|
|
</p><center><div class="image" style><a href="images/material_ior.png" target="_blank"><img class="markdeep" src="images/material_ior.png"></a><div class="imagecaption"><a class="target" name="figure_iorproperty"> </a><b style="font-style:normal;">Figure 20:</b> <code>ior</code> of 1.0 (left) and 1.33 (right)</div></div></center>
|
|
|
|
<p></p><p>
|
|
|
|
Note that the <code>ior</code> property also defines the reflectance (or specular intensity) of the surface.
|
|
When this property is defined it is not necessary to define the <code>reflectance</code> property. Setting
|
|
either of these properties will automatically compute the other property. It is possible to specify
|
|
both, in which case their values are kept as-is, which can lead to physically impossible materials,
|
|
however, this might be desirable for artistic reasons.
|
|
|
|
</p><p>
|
|
|
|
See the <a href="#reflectance">Reflectance</a> section for more information on the <code>reflectance</code> property.
|
|
|
|
</p><p>
|
|
|
|
</p><div class="admonition tip">Refractive materials are affected by the <code>roughness</code> property. Rough materials will scatter
|
|
light, creating a diffusion effect useful to recreate “blurry” appearances such as frosted
|
|
glass, certain plastics, etc.</div>
|
|
|
|
<p></p>
|
|
<a class="target" name="transmission"> </a><a class="target" name="materialmodels/litmodel/transmission"> </a><a class="target" name="toc3.1.19"> </a><h3>Transmission</h3>
|
|
<p>
|
|
|
|
|
|
The <code>transmission</code> property defines what ratio of diffuse light is transmitted through a refractive
|
|
material. This property only affects materials with a <code>refractionMode</code> set to <code>cubemap</code> or
|
|
<code>screenspace</code>.
|
|
|
|
</p><p>
|
|
|
|
When <code>transmission</code> is set to 0, no amount of light is transmitted and the diffuse component of
|
|
the surface is 100% visible. When <code>transmission</code> is set to 1, all the light is transmitted and the
|
|
diffuse component is not visible anymore, only the specular component is.
|
|
|
|
</p><p>
|
|
|
|
The effect of <code>transmission</code> on a glossy dielectric (<code>ior</code> of 1.5, <code>refractionMode</code> set to
|
|
<code>cubemap</code>, <code>refractionType</code> set to <code>solid</code>) is shown in <a href="#figure_transmissionproperty">figure 21</a>
|
|
(click on the image to see a larger version).
|
|
|
|
</p><p>
|
|
|
|
</p><center><div class="image" style><a href="images/materials/transmission.png" target="_blank"><img class="markdeep" src="images/materials/transmission.png"></a><div class="imagecaption"><a class="target" name="figure_transmissionproperty"> </a><b style="font-style:normal;">Figure 21:</b> <code>transmission</code> varying from 0.0
|
|
(left) to 1.0 (right)</div></div></center>
|
|
|
|
<p></p><p>
|
|
|
|
</p><div class="admonition tip">The <code>transmission</code> property is useful to create decals, paint, etc. at the surface of refractive
|
|
materials.</div>
|
|
|
|
<p></p>
|
|
<a class="target" name="absorption"> </a><a class="target" name="materialmodels/litmodel/absorption"> </a><a class="target" name="toc3.1.20"> </a><h3>Absorption</h3>
|
|
<p>
|
|
|
|
|
|
The <code>absorption</code> property defines the absorption coefficients of light transmitted through the
|
|
material. <a href="#figure_absorptionexample">Figure 22</a> shows the effect of <code>absorption</code> on a refracting object with
|
|
an index of refraction of 1.5 and a base color set to white.
|
|
|
|
</p><p>
|
|
|
|
</p><center><div class="image" style><a href="images/material_absorption.png" target="_blank"><img class="markdeep" src="images/material_absorption.png"></a><div class="imagecaption"><a class="target" name="figure_absorptionexample"> </a><b style="font-style:normal;">Figure 22:</b> Refracting object without (left)
|
|
and with (right) absorption</div></div></center>
|
|
|
|
<p></p><p>
|
|
|
|
Transmittance through a volume is exponential with respect to the optical depth (defined either
|
|
with <code>microThickness</code> or <code>thickness</code>). The computed color follows the following formula:
|
|
|
|
</p><p>
|
|
|
|
$$color \cdot e^{-absorption \cdot distance}$$
|
|
|
|
</p><p>
|
|
|
|
Where <code>distance</code> is either <code>microThickness</code> or <code>thickness</code>, that is the distance light will travel
|
|
through the material at a given point. If no thickness/distance is specified, the computed color
|
|
follows this formula instead:
|
|
|
|
</p><p>
|
|
|
|
$$color \cdot (1 - absorption)$$
|
|
|
|
</p><p>
|
|
|
|
The effect of varying the <code>absorption</code> coefficients is shown in <a href="#figure_absorptionproperty">figure 23</a>
|
|
(click on the image to see a larger version). In this picture, the object has a fixed <code>thickness</code>
|
|
of 4.5 and an index of refraction set to 1.3.
|
|
|
|
</p><p>
|
|
|
|
</p><center><div class="image" style><a href="images/materials/absorption.png" target="_blank"><img class="markdeep" src="images/materials/absorption.png"></a><div class="imagecaption"><a class="target" name="figure_absorptionproperty"> </a><b style="font-style:normal;">Figure 23:</b> <code>absorption</code> varying from (0.0, 0.02, 0.14)
|
|
(left) to (0.0, 0.36, 2.3) (right)</div></div></center>
|
|
|
|
<p></p><p>
|
|
|
|
Setting the absorption coefficients directly can be unintuitive which is why we recommend working
|
|
with a <em class="underscore">transmittance color</em> and a <em class="underscore">“at distance”</em> factor instead. These two parameters allow an
|
|
artist to specify the precise color the material should have at a specified distance through the
|
|
volume. The value to pass to <code>absorption</code> can be computed this way:
|
|
|
|
</p><p>
|
|
|
|
$$absorption = -\frac{ln(transmittanceColor)}{atDistance}$$
|
|
|
|
</p><p>
|
|
|
|
While this computation can be done in the material itself we recommend doing it offline whenever
|
|
possible. Filament provides an API for this purpose, <code>Color::absorptionAtDistance()</code>.
|
|
|
|
</p>
|
|
<a class="target" name="micro-thicknessandthickness"> </a><a class="target" name="materialmodels/litmodel/micro-thicknessandthickness"> </a><a class="target" name="toc3.1.21"> </a><h3>Micro-thickness and thickness</h3>
|
|
<p>
|
|
|
|
|
|
The <code>microThickness</code> and <code>thickness</code> properties define the optical depth of the material of a
|
|
refracting object. <code>microThickness</code> is used when <code>refractionType</code> is set to <code>thin</code>, and <code>thickness</code>
|
|
is used when <code>refractionType</code> is set to <code>volume</code>.
|
|
|
|
</p><p>
|
|
|
|
<code>thickness</code> represents the thickness of solid objects in the direction of the normal, for
|
|
satisfactory results, this should be provided per fragment (e.g.: as a texture) or at least per
|
|
vertex.
|
|
|
|
</p><p>
|
|
|
|
<code>microThickness</code> represent the thickness of the thin layer (shell) of an object, and can generally
|
|
be provided as a constant value. For example, a 1mm thin hollow sphere of radius 1m, would have a
|
|
<code>thickness</code> of 1 and a <code>microThickness</code> of 0.001. Currently <code>thickness</code> is not used when
|
|
<code>refractionType</code> is set to <code>thin</code>. Both properties are made available for possible future use.
|
|
|
|
</p><p>
|
|
|
|
Both <code>thickness</code> and <code>microThickness</code> are used to compute the transmitted color of the material
|
|
when the <code>absorption</code> property is set. In solid volumes, <code>thickness</code> will also affect how light
|
|
rays are refracted.
|
|
|
|
</p><p>
|
|
|
|
The effect <code>thickness</code> in a solid volume with <code>refractionMode</code> set to <code>screenSpace</code> is shown in
|
|
<a href="#figure_thicknessproperty">figure 24</a> (click on the image to see a larger version). Note how the <code>thickness</code>
|
|
value not only changes the effect of <code>absorption</code> but also modifies the direction of the refracted
|
|
light.
|
|
|
|
</p><p>
|
|
|
|
</p><center><div class="image" style><a href="images/materials/thickness.png" target="_blank"><img class="markdeep" src="images/materials/thickness.png"></a><div class="imagecaption"><a class="target" name="figure_thicknessproperty"> </a><b style="font-style:normal;">Figure 24:</b> <code>thickness</code> varying from 0.0
|
|
(left) to 2.0 (right)</div></div></center>
|
|
|
|
<p></p><p>
|
|
|
|
<a href="#figure_varyingthickness">Figure 25</a> shows what a prism with spatially varying <code>thickness</code> looks like when
|
|
the <code>refractionType</code> is set to <code>solid</code> and <code>absorption</code> coefficients are set.
|
|
|
|
</p><p>
|
|
|
|
</p><center><div class="image" style><a href="images/material_thickness.png" target="_blank"><img class="markdeep" src="images/material_thickness.png"></a><div class="imagecaption"><a class="target" name="figure_varyingthickness"> </a><b style="font-style:normal;">Figure 25:</b> <code>thickness</code> varying from 0.0 at the top of the prism to 3.0 at the
|
|
bottom of the prism</div></div></center>
|
|
|
|
<p></p>
|
|
<a class="target" name="subsurfacemodel"> </a><a class="target" name="materialmodels/subsurfacemodel"> </a><a class="target" name="toc3.2"> </a><h2>Subsurface model</h2>
|
|
|
|
<a class="target" name="thickness"> </a><a class="target" name="materialmodels/subsurfacemodel/thickness"> </a><a class="target" name="toc3.2.1"> </a><h3>Thickness</h3>
|
|
|
|
<a class="target" name="subsurfacecolor"> </a><a class="target" name="materialmodels/subsurfacemodel/subsurfacecolor"> </a><a class="target" name="toc3.2.2"> </a><h3>Subsurface color</h3>
|
|
|
|
<a class="target" name="subsurfacepower"> </a><a class="target" name="materialmodels/subsurfacemodel/subsurfacepower"> </a><a class="target" name="toc3.2.3"> </a><h3>Subsurface power</h3>
|
|
|
|
<a class="target" name="clothmodel"> </a><a class="target" name="materialmodels/clothmodel"> </a><a class="target" name="toc3.3"> </a><h2>Cloth model</h2>
|
|
<p>
|
|
|
|
|
|
All the material models described previously are designed to simulate dense surfaces, both at a
|
|
macro and at a micro level. Clothes and fabrics are however often made of loosely connected threads
|
|
that absorb and scatter incident light. When compared to hard surfaces, cloth is characterized by
|
|
a softer specular lob with a large falloff and the presence of fuzz lighting, caused by
|
|
forward/backward scattering. Some fabrics also exhibit two-tone specular colors
|
|
(velvets for instance).
|
|
|
|
</p><p>
|
|
|
|
<a href="#figure_materialcloth">Figure 26</a> shows how the standard material model fails to capture the appearance of a
|
|
sample of denim fabric. The surface appears rigid (almost plastic-like), more similar to a tarp
|
|
than a piece of clothing. This figure also shows how important the softer specular lobe caused by
|
|
absorption and scattering is to the faithful recreation of the fabric.
|
|
|
|
</p><p>
|
|
|
|
</p><center><div class="image" style><a href="images/screenshot_cloth.png" target="_blank"><img class="markdeep" src="images/screenshot_cloth.png"></a><div class="imagecaption"><a class="target" name="figure_materialcloth"> </a><b style="font-style:normal;">Figure 26:</b> Comparison of denim fabric rendered using the standard model
|
|
(left) and the cloth model (right)</div></div></center>
|
|
|
|
<p></p><p>
|
|
|
|
Velvet is an interesting use case for a cloth material model. As shown in <a href="#figure_materialvelvet">figure 27</a>
|
|
this type of fabric exhibits strong rim lighting due to forward and backward scattering. These
|
|
scattering events are caused by fibers standing straight at the surface of the fabric. When the
|
|
incident light comes from the direction opposite to the view direction, the fibers will forward
|
|
scatter the light. Similarly, when the incident light from the same direction as the view
|
|
direction, the fibers will scatter the light backward.
|
|
|
|
</p><p>
|
|
|
|
</p><center><div class="image" style><a href="images/screenshot_cloth_velvet.png" target="_blank"><img class="markdeep" src="images/screenshot_cloth_velvet.png"></a><div class="imagecaption"><a class="target" name="figure_materialvelvet"> </a><b style="font-style:normal;">Figure 27:</b> Velvet fabric showcasing forward and
|
|
backward scattering</div></div></center>
|
|
|
|
<p></p><p>
|
|
|
|
It is important to note that there are types of fabrics that are still best modeled by hard surface
|
|
material models. For instance, leather, silk and satin can be recreated using the standard or
|
|
anisotropic material models.
|
|
|
|
</p><p>
|
|
|
|
The cloth material model encompasses all the parameters previously defined for the standard
|
|
material mode except for <em class="underscore">metallic</em> and <em class="underscore">reflectance</em>. Two extra parameters described in
|
|
<a href="#table_clothproperties">table 7</a> are also available.
|
|
|
|
</p><p>
|
|
|
|
</p><div class="table">
|
|
<table class="table"><tbody><tr><th style="text-align:right"> Parameter </th><th style="text-align:left"> Definition </th></tr>
|
|
<tr><td style="text-align:right"> <strong class="asterisk">sheenColor</strong> </td><td style="text-align:left"> Specular tint to create two-tone specular fabrics (defaults to \(\sqrt{baseColor}\)) </td></tr>
|
|
<tr><td style="text-align:right"> <strong class="asterisk">subsurfaceColor</strong> </td><td style="text-align:left"> Tint for the diffuse color after scattering and absorption through the material </td></tr>
|
|
</tbody></table><div class="tablecaption"><a class="target" name="table_clothproperties"> </a><b style="font-style:normal;">Table 7:</b> Cloth model parameters</div></div>
|
|
|
|
<p></p><p>
|
|
|
|
The type and range of each property is described in <a href="#table_clothpropertiestypes">table 8</a>.
|
|
</p><div class="table">
|
|
<table class="table"><tbody><tr><th style="text-align:right"> Property </th><th style="text-align:center"> Type </th><th style="text-align:center"> Range </th><th style="text-align:left"> Note </th></tr>
|
|
<tr><td style="text-align:right"> <strong class="asterisk">sheenColor</strong> </td><td style="text-align:center"> float3 </td><td style="text-align:center"> [0..1] </td><td style="text-align:left"> Linear RGB </td></tr>
|
|
<tr><td style="text-align:right"> <strong class="asterisk">subsurfaceColor</strong> </td><td style="text-align:center"> float3 </td><td style="text-align:center"> [0..1] </td><td style="text-align:left"> Linear RGB </td></tr>
|
|
</tbody></table><div class="tablecaption"><a class="target" name="table_clothpropertiestypes"> </a><b style="font-style:normal;">Table 8:</b> Range and type of the cloth model's properties</div></div>
|
|
|
|
<p></p><p>
|
|
|
|
To create a velvet-like material, the base color can be set to black (or a dark color).
|
|
Chromaticity information should instead be set on the sheen color. To create more common fabrics
|
|
such as denim, cotton, etc. use the base color for chromaticity and use the default sheen color
|
|
or set the sheen color to the luminance of the base color.
|
|
|
|
</p><p>
|
|
|
|
</p><div class="admonition tip">To see the effect of the <code>roughness</code> parameter make sure the <code>sheenColor</code> is brighter than
|
|
<code>baseColor</code>. This can be used to create a fuzz effect. Taking the luminance of <code>baseColor</code>
|
|
as the <code>sheenColor</code> will produce a fairly natural effect that works for common cloth. A dark
|
|
<code>baseColor</code> combined with a bright/saturated <code>sheenColor</code> can be used to create velvet.</div>
|
|
|
|
<p></p><p>
|
|
|
|
</p><div class="admonition tip">The <code>subsurfaceColor</code> parameter should be used with care. High values can interfere with shadows
|
|
in some areas. It is best suited for subtle transmission effects through the material.</div>
|
|
|
|
<p></p>
|
|
<a class="target" name="sheencolor"> </a><a class="target" name="materialmodels/clothmodel/sheencolor"> </a><a class="target" name="toc3.3.1"> </a><h3>Sheen color</h3>
|
|
<p>
|
|
|
|
|
|
The <code>sheenColor</code> property can be used to directly modify the specular reflectance. It offers
|
|
better control over the appearance of cloth and gives give the ability to create
|
|
two-tone specular materials.
|
|
|
|
</p><p>
|
|
|
|
The effect of <code>sheenColor</code> is shown in <a href="#figure_materialclothsheen">figure 28</a>
|
|
(click on the image to see a larger version).
|
|
|
|
</p><p>
|
|
|
|
</p><center><div class="image" style><a href="images/screenshot_cloth_sheen.png" target="_blank"><img class="markdeep" src="images/screenshot_cloth_sheen.png"></a><div class="imagecaption"><a class="target" name="figure_materialclothsheen"> </a><b style="font-style:normal;">Figure 28:</b> Blue fabric without (left) and with (right) sheen</div></div></center>
|
|
|
|
<p></p>
|
|
<a class="target" name="subsurfacecolor"> </a><a class="target" name="materialmodels/clothmodel/subsurfacecolor"> </a><a class="target" name="toc3.3.2"> </a><h3>Subsurface color</h3>
|
|
<p>
|
|
|
|
|
|
The <code>subsurfaceColor</code> property is not physically-based and can be used to simulate the scattering,
|
|
partial absorption and re-emission of light in certain types of fabrics. This is particularly
|
|
useful to create softer fabrics.
|
|
|
|
</p><p>
|
|
|
|
</p><div class="admonition warning">The cloth material model is more expensive to compute when the <code>subsurfaceColor</code> property is used.</div>
|
|
|
|
<p></p><p>
|
|
|
|
The effect of <code>subsurfaceColor</code> is shown in <a href="#figure_materialclothsubsurface">figure 29</a>
|
|
(click on the image to see a larger version).
|
|
|
|
</p><p>
|
|
|
|
</p><center><div class="image" style><a href="images/screenshot_cloth_subsurface.png" target="_blank"><img class="markdeep" src="images/screenshot_cloth_subsurface.png"></a><div class="imagecaption"><a class="target" name="figure_materialclothsubsurface"> </a><b style="font-style:normal;">Figure 29:</b> White cloth (left column) vs white cloth with
|
|
brown subsurface scatting (right)</div></div></center>
|
|
|
|
<p></p>
|
|
<a class="target" name="unlitmodel"> </a><a class="target" name="materialmodels/unlitmodel"> </a><a class="target" name="toc3.4"> </a><h2>Unlit model</h2>
|
|
<p>
|
|
|
|
|
|
The unlit material model can be used to turn off all lighting computations. Its primary purpose is
|
|
to render pre-lit elements such as a cubemap, external content (such as a video or camera stream),
|
|
user interfaces, visualization/debugging etc. The unlit model exposes only two properties described
|
|
in <a href="#table_unlitproperties">table 9</a>.
|
|
</p><div class="table">
|
|
<table class="table"><tbody><tr><th style="text-align:right"> Property </th><th style="text-align:left"> Definition </th></tr>
|
|
<tr><td style="text-align:right"> <strong class="asterisk">baseColor</strong> </td><td style="text-align:left"> Surface diffuse color </td></tr>
|
|
<tr><td style="text-align:right"> <strong class="asterisk">emissive</strong> </td><td style="text-align:left"> Additional diffuse color to simulate emissive surfaces. This property is mostly useful in an HDR pipeline with a bloom pass </td></tr>
|
|
<tr><td style="text-align:right"> <strong class="asterisk">postLightingColor</strong> </td><td style="text-align:left"> Additional color to blend with base color and emissive </td></tr>
|
|
</tbody></table><div class="tablecaption"><a class="target" name="table_unlitproperties"> </a><b style="font-style:normal;">Table 9:</b> Properties of the standard model</div></div>
|
|
|
|
<p></p><p>
|
|
|
|
The type and range of each property is described in <a href="#table_unlitpropertiestypes">table 10</a>.
|
|
</p><div class="table">
|
|
<table class="table"><tbody><tr><th style="text-align:right"> Property </th><th style="text-align:center"> Type </th><th style="text-align:center"> Range </th><th style="text-align:left"> Note </th></tr>
|
|
<tr><td style="text-align:right"> <strong class="asterisk">baseColor</strong> </td><td style="text-align:center"> float4 </td><td style="text-align:center"> [0..1] </td><td style="text-align:left"> Pre-multiplied linear RGB </td></tr>
|
|
<tr><td style="text-align:right"> <strong class="asterisk">emissive</strong> </td><td style="text-align:center"> float4 </td><td style="text-align:center"> rgb=[0..1], a=N/A </td><td style="text-align:left"> Pre-multiplied linear RGB, alpha is ignored </td></tr>
|
|
<tr><td style="text-align:right"> <strong class="asterisk">postLightingColor</strong> </td><td style="text-align:center"> float4 </td><td style="text-align:center"> [0..1] </td><td style="text-align:left"> Pre-multiplied linear RGB </td></tr>
|
|
</tbody></table><div class="tablecaption"><a class="target" name="table_unlitpropertiestypes"> </a><b style="font-style:normal;">Table 10:</b> Range and type of the unlit model's properties</div></div>
|
|
|
|
<p></p><p>
|
|
|
|
The value of <code>emissive</code> is simply added to <code>baseColor</code> when present. The main use of <code>emissive</code>
|
|
is to force an unlit surface to bloom if the HDR pipeline is configured with a bloom pass. The value
|
|
of <code>postLightingColor</code> is blended with the sum of <code>emissive</code> and <code>baseColor</code> according to the
|
|
blending mode specified by the <code>postLightingBlending</code> material option.
|
|
|
|
</p><p>
|
|
|
|
<a href="#figure_materialunlit">Figure 30</a> shows an example of the unlit material model
|
|
(click on the image to see a larger version).
|
|
|
|
</p><p>
|
|
|
|
</p><center><div class="image" style><a href="images/screenshot_unlit.jpg" target="_blank"><img class="markdeep" src="images/screenshot_unlit.jpg"></a><div class="imagecaption"><a class="target" name="figure_materialunlit"> </a><b style="font-style:normal;">Figure 30:</b> The unlit model is used to render debug information</div></div></center>
|
|
|
|
<p></p>
|
|
<a class="target" name="specularglossiness"> </a><a class="target" name="materialmodels/specularglossiness"> </a><a class="target" name="toc3.5"> </a><h2>Specular glossiness</h2>
|
|
<p>
|
|
|
|
|
|
This alternative lighting model exists to comply with legacy standards. Since it is not a
|
|
physically-based formulation, we do not recommend using it except when loading legacy assets.
|
|
|
|
</p><p>
|
|
|
|
This model encompasses the parameters previously defined for the standard lit mode except for
|
|
<em class="underscore">metallic</em>, <em class="underscore">reflectance</em>, and <em class="underscore">roughness</em>. It adds parameters for <em class="underscore">specularColor</em> and <em class="underscore">glossiness</em>.
|
|
</p><div class="table">
|
|
<table class="table"><tbody><tr><th style="text-align:right"> Parameter </th><th style="text-align:left"> Definition </th></tr>
|
|
<tr><td style="text-align:right"> <strong class="asterisk">baseColor</strong> </td><td style="text-align:left"> Surface diffuse color </td></tr>
|
|
<tr><td style="text-align:right"> <strong class="asterisk">specularColor</strong> </td><td style="text-align:left"> Specular tint (defaults to black) </td></tr>
|
|
<tr><td style="text-align:right"> <strong class="asterisk">glossiness</strong> </td><td style="text-align:left"> Glossiness (defaults to 0.0) </td></tr>
|
|
</tbody></table><div class="tablecaption"><a class="target" name="table_glossinessproperties"> </a><b style="font-style:normal;">Table 11:</b> Properties of the specular-glossiness shading model</div></div>
|
|
|
|
<p></p><p>
|
|
|
|
The type and range of each property is described in <a href="#table_glossinesspropertiestypes">table 12</a>.
|
|
</p><div class="table">
|
|
<table class="table"><tbody><tr><th style="text-align:right"> Property </th><th style="text-align:center"> Type </th><th style="text-align:center"> Range </th><th style="text-align:left"> Note </th></tr>
|
|
<tr><td style="text-align:right"> <strong class="asterisk">baseColor</strong> </td><td style="text-align:center"> float4 </td><td style="text-align:center"> [0..1] </td><td style="text-align:left"> Pre-multiplied linear RGB </td></tr>
|
|
<tr><td style="text-align:right"> <strong class="asterisk">specularColor</strong> </td><td style="text-align:center"> float3 </td><td style="text-align:center"> [0..1] </td><td style="text-align:left"> Linear RGB </td></tr>
|
|
<tr><td style="text-align:right"> <strong class="asterisk">glossiness</strong> </td><td style="text-align:center"> float </td><td style="text-align:center"> [0..1] </td><td style="text-align:left"> Inverse of roughness </td></tr>
|
|
</tbody></table><div class="tablecaption"><a class="target" name="table_glossinesspropertiestypes"> </a><b style="font-style:normal;">Table 12:</b> Range and type of the specular-glossiness model's properties</div></div>
|
|
|
|
<p></p>
|
|
<a class="target" name="materialdefinitions"> </a><a class="target" name="materialdefinitions"> </a><a class="target" name="toc4"> </a><h1>Material definitions</h1>
|
|
<p>
|
|
|
|
|
|
A material definition is a text file that describes all the information required by a material:
|
|
|
|
</p><p>
|
|
|
|
</p><ul>
|
|
<li class="minus">Name
|
|
</li>
|
|
<li class="minus">User parameters
|
|
</li>
|
|
<li class="minus">Material model
|
|
</li>
|
|
<li class="minus">Required attributes
|
|
</li>
|
|
<li class="minus">Interpolants (called <em class="underscore">variables</em>)
|
|
</li>
|
|
<li class="minus">Raster state (blending mode, etc.)
|
|
</li>
|
|
<li class="minus">Shader code (fragment shader, optionally vertex shader)</li></ul>
|
|
|
|
<p></p>
|
|
<a class="target" name="format"> </a><a class="target" name="materialdefinitions/format"> </a><a class="target" name="toc4.1"> </a><h2>Format</h2>
|
|
<p>
|
|
|
|
|
|
The material definition format is a format loosely based on <a href="https://www.json.org/">JSON</a> that we
|
|
call <em class="underscore">JSONish</em>. At the top level a material definition is composed of 3 different blocks that use
|
|
the JSON object notation:
|
|
|
|
</p><pre class="listing tilde"><code><span class="line">material {</span>
|
|
<span class="line"> // material properties</span>
|
|
<span class="line">}</span>
|
|
<span class="line"></span>
|
|
<span class="line">vertex {</span>
|
|
<span class="line"> // vertex shader, optional</span>
|
|
<span class="line">}</span>
|
|
<span class="line"></span>
|
|
<span class="line">fragment {</span>
|
|
<span class="line"> // fragment shader</span>
|
|
<span class="line">}</span></code></pre><p>
|
|
|
|
A minimum viable material definition must contain a <code>material</code> section and a <code>fragment</code> block. The
|
|
<code>vertex</code> block is optional.
|
|
|
|
</p>
|
|
<a class="target" name="differenceswithjson"> </a><a class="target" name="materialdefinitions/format/differenceswithjson"> </a><a class="target" name="toc4.1.1"> </a><h3>Differences with JSON</h3>
|
|
<p>
|
|
|
|
|
|
In JSON, an object is made of key/value <em class="underscore">pairs</em>. A JSON pair has the following syntax:
|
|
|
|
</p><pre class="listing tilde"><code><span class="line">"key" : value</span></code></pre><p>
|
|
|
|
Where value can be a string, number, object, array or a literal (<code>true</code>, <code>false</code> or <code>null</code>). While
|
|
this syntax is perfectly valid in a material definition, a variant without quotes around strings is
|
|
also accepted in JSONish:
|
|
|
|
</p><pre class="listing tilde"><code><span class="line">key : value</span></code></pre><p>
|
|
|
|
Quotes remain mandatory when the string contains spaces.
|
|
|
|
</p><p>
|
|
|
|
The <code>vertex</code> and <code>fragment</code> blocks contain unescaped, unquoted GLSL code, which is not valid in JSON.
|
|
|
|
</p><p>
|
|
|
|
Single-line C++-style comments are allowed.
|
|
|
|
</p><p>
|
|
|
|
The key of a pair is case-sensitive.
|
|
|
|
</p><p>
|
|
|
|
The value of a pair is not case-sensitive.
|
|
|
|
</p>
|
|
<a class="target" name="example"> </a><a class="target" name="materialdefinitions/format/example"> </a><a class="target" name="toc4.1.2"> </a><h3>Example</h3>
|
|
<p>
|
|
|
|
|
|
The following code listing shows an example of a valid material definition. This definition uses
|
|
the <em class="underscore">lit</em> material model (see <a href="#litmodel">Lit model</a> section), uses the default opaque blending mode, requires
|
|
that a set of UV coordinates be presented in the rendered mesh and defines 3 user parameters. The
|
|
following sections of this document describe the <code>material</code> and <code>fragment</code> blocks in detail.
|
|
|
|
</p><pre class="listing tilde"><code><span class="line">material {</span>
|
|
<span class="line"> name : "Textured material",</span>
|
|
<span class="line"> parameters : [</span>
|
|
<span class="line"> {</span>
|
|
<span class="line"> type : sampler2d,</span>
|
|
<span class="line"> name : texture</span>
|
|
<span class="line"> },</span>
|
|
<span class="line"> {</span>
|
|
<span class="line"> type : float,</span>
|
|
<span class="line"> name : metallic</span>
|
|
<span class="line"> },</span>
|
|
<span class="line"> {</span>
|
|
<span class="line"> type : float,</span>
|
|
<span class="line"> name : roughness</span>
|
|
<span class="line"> }</span>
|
|
<span class="line"> ],</span>
|
|
<span class="line"> requires : [</span>
|
|
<span class="line"> uv0</span>
|
|
<span class="line"> ],</span>
|
|
<span class="line"> shadingModel : lit,</span>
|
|
<span class="line"> blending : opaque</span>
|
|
<span class="line">}</span>
|
|
<span class="line"></span>
|
|
<span class="line">fragment {</span>
|
|
<span class="line"> void material(inout MaterialInputs material) {</span>
|
|
<span class="line"> prepareMaterial(material);</span>
|
|
<span class="line"> material.baseColor = texture(materialParams_texture, getUV0());</span>
|
|
<span class="line"> material.metallic = materialParams.metallic;</span>
|
|
<span class="line"> material.roughness = materialParams.roughness;</span>
|
|
<span class="line"> }</span>
|
|
<span class="line">}</span></code></pre>
|
|
<a class="target" name="materialblock"> </a><a class="target" name="materialdefinitions/materialblock"> </a><a class="target" name="toc4.2"> </a><h2>Material block</h2>
|
|
<p>
|
|
|
|
|
|
The material block is mandatory block that contains a list of property pairs to describe all
|
|
non-shader data.
|
|
|
|
</p>
|
|
<a class="target" name="general:name"> </a><a class="target" name="materialdefinitions/materialblock/general:name"> </a><a class="target" name="toc4.2.1"> </a><h3>General: name</h3>
|
|
<p>
|
|
|
|
|
|
</p><dl><table><tbody><tr valign="top"><td><dt>Type</dt></td><td><dd><p> <code>string</code>
|
|
|
|
</p></dd></td></tr><tr valign="top"><td><dt>Value</dt></td><td><dd><p> Any string. Double quotes are required if the name contains spaces.
|
|
|
|
</p></dd></td></tr><tr valign="top"><td><dt>Description</dt></td><td><dd><p> Sets the name of the material. The name is retained at runtime for debugging purpose.
|
|
|
|
</p></dd></td></tr></tbody></table></dl><p></p><pre class="listing tilde"><code><span class="line">material {</span>
|
|
<span class="line"> name : stone</span>
|
|
<span class="line">}</span>
|
|
<span class="line"></span>
|
|
<span class="line">material {</span>
|
|
<span class="line"> name : "Wet pavement"</span>
|
|
<span class="line">}</span></code></pre>
|
|
<a class="target" name="general:shadingmodel"> </a><a class="target" name="materialdefinitions/materialblock/general:shadingmodel"> </a><a class="target" name="toc4.2.2"> </a><h3>General: shadingModel</h3>
|
|
<p>
|
|
|
|
|
|
</p><dl><table><tbody><tr valign="top"><td><dt>Type</dt></td><td><dd><p> <code>string</code>
|
|
|
|
</p></dd></td></tr><tr valign="top"><td><dt>Value</dt></td><td><dd><p> Any of <code>lit</code>, <code>subsurface</code>, <code>cloth</code>, <code>unlit</code>, <code>specularGlossiness</code>. Defaults to <code>lit</code>.
|
|
|
|
</p></dd></td></tr><tr valign="top"><td><dt>Description</dt></td><td><dd><p> Selects the material model as described in the <a href="#materialmodels">Material models</a> section.
|
|
|
|
</p></dd></td></tr></tbody></table></dl><p></p><pre class="listing tilde"><code><span class="line">material {</span>
|
|
<span class="line"> shadingModel : unlit</span>
|
|
<span class="line">}</span>
|
|
<span class="line"></span>
|
|
<span class="line">material {</span>
|
|
<span class="line"> shadingModel : "subsurface"</span>
|
|
<span class="line">}</span></code></pre>
|
|
<a class="target" name="general:parameters"> </a><a class="target" name="materialdefinitions/materialblock/general:parameters"> </a><a class="target" name="toc4.2.3"> </a><h3>General: parameters</h3>
|
|
<p>
|
|
|
|
|
|
</p><dl><dt>Type</dt><dd><p> array of parameter objects
|
|
|
|
</p></dd><dt>Value</dt><dd><p> Each entry is an object with the properties <code>name</code> and <code>type</code>, both of <code>string</code> type. The
|
|
name must be a valid GLSL identifier. The type must be one of the types described in
|
|
<a href="#table_materialparamstypes">table 13</a>.
|
|
|
|
</p></dd></dl><div class="table">
|
|
<table class="table"><tbody><tr><th style="text-align:left"> Type </th><th style="text-align:left"> Description </th></tr>
|
|
<tr><td style="text-align:left"> bool </td><td style="text-align:left"> Single boolean </td></tr>
|
|
<tr><td style="text-align:left"> bool2 </td><td style="text-align:left"> Vector of 2 booleans </td></tr>
|
|
<tr><td style="text-align:left"> bool3 </td><td style="text-align:left"> Vector of 3 booleans </td></tr>
|
|
<tr><td style="text-align:left"> bool4 </td><td style="text-align:left"> Vector of 4 booleans </td></tr>
|
|
<tr><td style="text-align:left"> float </td><td style="text-align:left"> Single float </td></tr>
|
|
<tr><td style="text-align:left"> float2 </td><td style="text-align:left"> Vector of 2 floats </td></tr>
|
|
<tr><td style="text-align:left"> float3 </td><td style="text-align:left"> Vector of 3 floats </td></tr>
|
|
<tr><td style="text-align:left"> float4 </td><td style="text-align:left"> Vector of 4 floats </td></tr>
|
|
<tr><td style="text-align:left"> int </td><td style="text-align:left"> Single integer </td></tr>
|
|
<tr><td style="text-align:left"> int2 </td><td style="text-align:left"> Vector of 2 integers </td></tr>
|
|
<tr><td style="text-align:left"> int3 </td><td style="text-align:left"> Vector of 3 integers </td></tr>
|
|
<tr><td style="text-align:left"> int4 </td><td style="text-align:left"> Vector of 4 integers </td></tr>
|
|
<tr><td style="text-align:left"> uint </td><td style="text-align:left"> Single unsigned integer </td></tr>
|
|
<tr><td style="text-align:left"> uint2 </td><td style="text-align:left"> Vector of 2 unsigned integers </td></tr>
|
|
<tr><td style="text-align:left"> uint3 </td><td style="text-align:left"> Vector of 3 unsigned integers </td></tr>
|
|
<tr><td style="text-align:left"> uint4 </td><td style="text-align:left"> Vector of 4 unsigned integers </td></tr>
|
|
<tr><td style="text-align:left"> float3×3 </td><td style="text-align:left"> Matrix of 3×3 floats </td></tr>
|
|
<tr><td style="text-align:left"> float4×4 </td><td style="text-align:left"> Matrix of 4×4 floats </td></tr>
|
|
<tr><td style="text-align:left"> sampler2d </td><td style="text-align:left"> 2D texture </td></tr>
|
|
<tr><td style="text-align:left"> samplerExternal </td><td style="text-align:left"> External texture (platform-specific) </td></tr>
|
|
<tr><td style="text-align:left"> samplerCubemap </td><td style="text-align:left"> Cubemap texture </td></tr>
|
|
</tbody></table><div class="tablecaption"><a class="target" name="table_materialparamstypes"> </a><b style="font-style:normal;">Table 13:</b> Material parameter types</div></div>
|
|
|
|
<p></p><p>
|
|
|
|
</p><dl><dt>Samplers</dt><dd><p> Sampler types can also specify a <code>format</code> (defaults to <code>float</code>) and a <code>precision</code> (defaults
|
|
to <code>default</code>). The format can be one of <code>int</code>, <code>float</code>. The precision can be one of <code>default</code>
|
|
(best precision for the platform, typically <code>high</code> on desktop, <code>medium</code> on mobile),
|
|
<code>low</code>, <code>medium</code>, <code>high</code>.
|
|
|
|
</p></dd><dt>Arrays</dt><dd><p> A parameter can define an array of values by appending <code>[size]</code> after the type name, where
|
|
<code>size</code> is a positive integer. For instance: <code>float[9]</code> declares an array of nine <code>float</code>
|
|
values. Arrays of samplers are <em class="underscore">not</em> supported at the moment.
|
|
|
|
</p></dd><dt>Description</dt><dd><p> Lists the parameters required by your material. These parameters can be set at runtime using
|
|
Filament's material API. Accessing parameters from the shaders varies depending on the type of
|
|
parameter:
|
|
|
|
</p><p>
|
|
|
|
</p><ul>
|
|
<li class="minus"><strong class="asterisk">Samplers types</strong>: use the parameter name prefixed with <code>materialParams_</code>. For instance,
|
|
<code>materialParams_myTexture</code>.
|
|
</li>
|
|
<li class="minus"><strong class="asterisk">Other types</strong>: use the parameter name as the field of a structure called <code>materialParams</code>.
|
|
For instance, <code>materialParams.myColor</code>.</li></ul>
|
|
|
|
<p></p></dd></dl><p></p><pre class="listing tilde"><code><span class="line">material {</span>
|
|
<span class="line"> parameters : [</span>
|
|
<span class="line"> {</span>
|
|
<span class="line"> type : float4,</span>
|
|
<span class="line"> name : albedo</span>
|
|
<span class="line"> },</span>
|
|
<span class="line"> {</span>
|
|
<span class="line"> type : sampler2d,</span>
|
|
<span class="line"> format : float,</span>
|
|
<span class="line"> precision : high,</span>
|
|
<span class="line"> name : roughness</span>
|
|
<span class="line"> },</span>
|
|
<span class="line"> {</span>
|
|
<span class="line"> type : float2,</span>
|
|
<span class="line"> name : metallicReflectance</span>
|
|
<span class="line"> }</span>
|
|
<span class="line"> ],</span>
|
|
<span class="line"> requires : [</span>
|
|
<span class="line"> uv0</span>
|
|
<span class="line"> ],</span>
|
|
<span class="line"> shadingModel : lit,</span>
|
|
<span class="line">}</span>
|
|
<span class="line"></span>
|
|
<span class="line">fragment {</span>
|
|
<span class="line"> void material(inout MaterialInputs material) {</span>
|
|
<span class="line"> prepareMaterial(material);</span>
|
|
<span class="line"> material.baseColor = materialParams.albedo;</span>
|
|
<span class="line"> material.roughness = texture(materialParams_roughness, getUV0());</span>
|
|
<span class="line"> material.metallic = materialParams.metallicReflectance.x;</span>
|
|
<span class="line"> material.reflectance = materialParams.metallicReflectance.y;</span>
|
|
<span class="line"> }</span>
|
|
<span class="line">}</span></code></pre>
|
|
<a class="target" name="general:variantfilter"> </a><a class="target" name="materialdefinitions/materialblock/general:variantfilter"> </a><a class="target" name="toc4.2.4"> </a><h3>General: variantFilter</h3>
|
|
<p>
|
|
|
|
|
|
</p><dl><dt>Type</dt><dd><p> array of <code>string</code>
|
|
|
|
</p></dd><dt>Value</dt><dd><p> Each entry must be any of <code>dynamicLighting</code>, <code>directionalLighting</code>, <code>shadowReceiver</code> or <code>skinning</code>.
|
|
|
|
</p></dd><dt>Description</dt><dd><p> Used to specify a list of shader variants that the application guarantees will never be
|
|
needed. These shader variants are skipped during the code generation phase, thus reducing
|
|
the overall size of the material.
|
|
Note that some variants may automatically be filtered out. For instance, all lighting related
|
|
variants (<code>directionalLighting</code>, etc.) are filtered out when compiling an <code>unlit</code> material.
|
|
Use the variant filter with caution, filtering out a variant required at runtime may lead
|
|
to crashes.
|
|
|
|
</p></dd></dl>Description of the variants:
|
|
|
|
<p></p><p>
|
|
|
|
</p><ul>
|
|
<li class="minus"><code>directionalLighting</code>, used when a directional light is present in the scene
|
|
</li>
|
|
<li class="minus"><code>dynamicLighting</code>, used when a non-directional light (point, spot, etc.) is present in the scene
|
|
</li>
|
|
<li class="minus"><code>shadowReceiver</code>, used when an object can receive shadows
|
|
</li>
|
|
<li class="minus"><code>skinning</code>, used when an object is animated using GPU skinning</li></ul>
|
|
|
|
<p></p><pre class="listing tilde"><code><span class="line">material {</span>
|
|
<span class="line"> name : "Invisible shadow plane",</span>
|
|
<span class="line"> shadingModel : unlit,</span>
|
|
<span class="line"> shadowMultiplier : true,</span>
|
|
<span class="line"> blending : transparent,</span>
|
|
<span class="line"> variantFilter : [ skinning ]</span>
|
|
<span class="line">}</span></code></pre>
|
|
<a class="target" name="general:flipuv"> </a><a class="target" name="materialdefinitions/materialblock/general:flipuv"> </a><a class="target" name="toc4.2.5"> </a><h3>General: flipUV</h3>
|
|
<p>
|
|
|
|
|
|
</p><dl><dt>Type</dt><dd><p> <code>boolean</code>
|
|
|
|
</p></dd><dt>Value</dt><dd><p> <code>true</code> or <code>false</code>. Defaults to <code>true</code>.
|
|
|
|
</p></dd><dt>Description</dt><dd><p> When set to <code>true</code> (default value), the Y coordinate of UV attributes will be flipped when
|
|
read by this material's vertex shader. Flipping is equivalent to <code>y = 1.0 - y</code>. When set
|
|
to <code>false</code>, flipping is disabled and the UV attributes are read as is.
|
|
|
|
</p></dd></dl><p></p><pre class="listing tilde"><code><span class="line">material {</span>
|
|
<span class="line"> flipUV : false</span>
|
|
<span class="line">}</span></code></pre>
|
|
<a class="target" name="vertexandattributes:requires"> </a><a class="target" name="materialdefinitions/materialblock/vertexandattributes:requires"> </a><a class="target" name="toc4.2.6"> </a><h3>Vertex and attributes: requires</h3>
|
|
<p>
|
|
|
|
|
|
</p><dl><dt>Type</dt><dd><p> array of <code>string</code>
|
|
|
|
</p></dd><dt>Value</dt><dd><p> Each entry must be any of <code>uv0</code>, <code>uv1</code>, <code>color</code>, <code>position</code>, <code>tangents</code>.
|
|
|
|
</p></dd><dt>Description</dt><dd><p> Lists the vertex attributes required by the material. The <code>position</code> attribute is always
|
|
required and does not need to be specified. The <code>tangents</code> attribute is automatically required
|
|
when selecting any shading model that is not <code>unlit</code>. See the shader sections of this document
|
|
for more information on how to access these attributes from the shaders.
|
|
|
|
</p></dd></dl><p></p><pre class="listing tilde"><code><span class="line">material {</span>
|
|
<span class="line"> parameters : [</span>
|
|
<span class="line"> {</span>
|
|
<span class="line"> type : sampler2d,</span>
|
|
<span class="line"> name : texture</span>
|
|
<span class="line"> },</span>
|
|
<span class="line"> ],</span>
|
|
<span class="line"> requires : [</span>
|
|
<span class="line"> uv0</span>
|
|
<span class="line"> ],</span>
|
|
<span class="line"> shadingModel : lit,</span>
|
|
<span class="line">}</span>
|
|
<span class="line"></span>
|
|
<span class="line">fragment {</span>
|
|
<span class="line"> void material(inout MaterialInputs material) {</span>
|
|
<span class="line"> prepareMaterial(material);</span>
|
|
<span class="line"> material.baseColor = texture(materialParams_texture, getUV0());</span>
|
|
<span class="line"> }</span>
|
|
<span class="line">}</span></code></pre>
|
|
<a class="target" name="vertexandattributes:variables"> </a><a class="target" name="materialdefinitions/materialblock/vertexandattributes:variables"> </a><a class="target" name="toc4.2.7"> </a><h3>Vertex and attributes: variables</h3>
|
|
<p>
|
|
|
|
|
|
</p><dl><dt>Type</dt><dd><p> array of <code>string</code>
|
|
|
|
</p></dd><dt>Value</dt><dd><p> Up to 4 strings, each must be a valid GLSL identifier.
|
|
|
|
</p></dd><dt>Description</dt><dd><p> Defines custom interpolants (or variables) that are output by the material's vertex shader.
|
|
Each entry of the array defines the name of an interpolant. The full name in the fragment
|
|
shader is the name of the interpolant with the <code>variable_</code> prefix. For instance, if you
|
|
declare a variable called <code>eyeDirection</code> you can access it in the fragment shader using
|
|
<code>variable_eyeDirection</code>. In the vertex shader, the interpolant name is simply a member of
|
|
the <code>MaterialVertexInputs</code> structure (<code>material.eyeDirection</code> in your example). Each
|
|
interpolant is of type <code>float4</code> (<code>vec4</code>) in the shaders.
|
|
|
|
</p></dd></dl><p></p><pre class="listing tilde"><code><span class="line">material {</span>
|
|
<span class="line"> name : Skybox,</span>
|
|
<span class="line"> parameters : [</span>
|
|
<span class="line"> {</span>
|
|
<span class="line"> type : samplerCubemap,</span>
|
|
<span class="line"> name : skybox</span>
|
|
<span class="line"> }</span>
|
|
<span class="line"> ],</span>
|
|
<span class="line"> variables : [</span>
|
|
<span class="line"> eyeDirection</span>
|
|
<span class="line"> ],</span>
|
|
<span class="line"> vertexDomain : device,</span>
|
|
<span class="line"> depthWrite : false,</span>
|
|
<span class="line"> shadingModel : unlit</span>
|
|
<span class="line">}</span>
|
|
<span class="line"></span>
|
|
<span class="line">fragment {</span>
|
|
<span class="line"> void material(inout MaterialInputs material) {</span>
|
|
<span class="line"> prepareMaterial(material);</span>
|
|
<span class="line"> float3 sky = texture(materialParams_skybox, variable_eyeDirection.xyz).rgb;</span>
|
|
<span class="line"> material.baseColor = vec4(sky, 1.0);</span>
|
|
<span class="line"> }</span>
|
|
<span class="line">}</span>
|
|
<span class="line"></span>
|
|
<span class="line">vertex {</span>
|
|
<span class="line"> void materialVertex(inout MaterialVertexInputs material) {</span>
|
|
<span class="line"> float3 p = getPosition().xyz;</span>
|
|
<span class="line"> float3 u = mulMat4x4Float3(getViewFromClipMatrix(), p).xyz;</span>
|
|
<span class="line"> material.eyeDirection.xyz = mulMat3x3Float3(getWorldFromViewMatrix(), u);</span>
|
|
<span class="line"> }</span>
|
|
<span class="line">}</span></code></pre>
|
|
<a class="target" name="vertexandattributes:vertexdomain"> </a><a class="target" name="materialdefinitions/materialblock/vertexandattributes:vertexdomain"> </a><a class="target" name="toc4.2.8"> </a><h3>Vertex and attributes: vertexDomain</h3>
|
|
<p>
|
|
|
|
|
|
</p><dl><dt>Type</dt><dd><p> <code>string</code>
|
|
|
|
</p></dd><dt>Value</dt><dd><p> Any of <code>object</code>, <code>world</code>, <code>view</code>, <code>device</code>. Defaults to <code>object</code>.
|
|
|
|
</p></dd><dt>Description</dt><dd><p> Defines the domain (or coordinate space) of the rendered mesh. The domain influences how the
|
|
vertices are transformed in the vertex shader. The possible domains are:
|
|
|
|
</p><p>
|
|
|
|
</p><ul>
|
|
<li class="minus"><strong class="asterisk">Object</strong>: the vertices are defined in the object (or model) coordinate space. The
|
|
vertices are transformed using the rendered object's transform matrix
|
|
</li>
|
|
<li class="minus"><strong class="asterisk">World</strong>: the vertices are defined in world coordinate space. The vertices are not
|
|
transformed using the rendered object's transform.
|
|
</li>
|
|
<li class="minus"><strong class="asterisk">View</strong>: the vertices are defined in view (or eye or camera) coordinate space. The
|
|
vertices are not transformed using the rendered object's transform.
|
|
</li>
|
|
<li class="minus"><strong class="asterisk">Device</strong>: the vertices are defined in normalized device (or clip) coordinate space.
|
|
The vertices are not transformed using the rendered object's transform.</li></ul>
|
|
|
|
<p></p></dd></dl><p></p><pre class="listing tilde"><code><span class="line">material {</span>
|
|
<span class="line"> vertexDomain : device</span>
|
|
<span class="line">}</span></code></pre>
|
|
<a class="target" name="vertexandattributes:interpolation"> </a><a class="target" name="materialdefinitions/materialblock/vertexandattributes:interpolation"> </a><a class="target" name="toc4.2.9"> </a><h3>Vertex and attributes: interpolation</h3>
|
|
<p>
|
|
|
|
|
|
</p><dl><dt>Type</dt><dd><p> <code>string</code>
|
|
|
|
</p></dd><dt>Value</dt><dd><p> Any of <code>smooth</code>, <code>flat</code>. Defaults to <code>smooth</code>.
|
|
|
|
</p></dd><dt>Description</dt><dd><p> Defines how interpolants (or variables) are interpolated between vertices. When this property
|
|
is set to <code>smooth</code>, a perspective correct interpolation is performed on each interpolant.
|
|
When set to <code>flat</code>, no interpolation is performed and all the fragments within a given
|
|
triangle will be shaded the same.
|
|
|
|
</p></dd></dl><p></p><pre class="listing tilde"><code><span class="line">material {</span>
|
|
<span class="line"> interpolation : flat</span>
|
|
<span class="line">}</span></code></pre>
|
|
<a class="target" name="blendingandtransparency:blending"> </a><a class="target" name="materialdefinitions/materialblock/blendingandtransparency:blending"> </a><a class="target" name="toc4.2.10"> </a><h3>Blending and transparency: blending</h3>
|
|
<p>
|
|
|
|
|
|
</p><dl><dt>Type</dt><dd><p> <code>string</code>
|
|
|
|
</p></dd><dt>Value</dt><dd><p> Any of <code>opaque</code>, <code>transparent</code>, <code>fade</code>, <code>add</code>, <code>masked</code>, <code>multiply</code>, <code>screen</code>. Defaults to <code>opaque</code>.
|
|
|
|
</p></dd><dt>Description</dt><dd><p> Defines how/if the rendered object is blended with the content of the render target.
|
|
The possible blending modes are:
|
|
|
|
</p><p>
|
|
|
|
</p><ul>
|
|
<li class="minus"><strong class="asterisk">Opaque</strong>: blending is disabled, the alpha channel of the material's output is ignored.
|
|
</li>
|
|
<li class="minus"><strong class="asterisk">Transparent</strong>: blending is enabled. The material's output is alpha composited with the
|
|
render target, using Porter-Duff's <code>source over</code> rule. This blending mode assumes
|
|
pre-multiplied alpha.
|
|
</li>
|
|
<li class="minus"><strong class="asterisk">Fade</strong>: acts as <code>transparent</code> but transparency is also applied to specular lighting. In
|
|
<code>transparent</code> mode, the material's alpha values only applies to diffuse lighting. This
|
|
blending mode is useful to fade lit objects in and out.
|
|
</li>
|
|
<li class="minus"><strong class="asterisk">Add</strong>: blending is enabled. The material's output is added to the content of the
|
|
render target.
|
|
</li>
|
|
<li class="minus"><strong class="asterisk">Multiply</strong>: blending is enabled. The material's output is multiplied with the content of the
|
|
render target, darkening the content.
|
|
</li>
|
|
<li class="minus"><strong class="asterisk">Screen</strong>: blending is enabled. Effectively the opposite of the <code>multiply</code>, the content of the
|
|
render target is brightened.
|
|
</li>
|
|
<li class="minus"><strong class="asterisk">Masked</strong>: blending is disabled. This blending mode enables alpha masking. The alpha channel
|
|
of the material's output defines whether a fragment is discarded or not. See the maskThreshold
|
|
section for more information.</li></ul>
|
|
|
|
<p></p></dd></dl><p></p><pre class="listing tilde"><code><span class="line">material {</span>
|
|
<span class="line"> blending : transparent</span>
|
|
<span class="line">}</span></code></pre>
|
|
<a class="target" name="blendingandtransparency:postlightingblending"> </a><a class="target" name="materialdefinitions/materialblock/blendingandtransparency:postlightingblending"> </a><a class="target" name="toc4.2.11"> </a><h3>Blending and transparency: postLightingBlending</h3>
|
|
<p>
|
|
|
|
|
|
</p><dl><dt>Type</dt><dd><p> <code>string</code>
|
|
|
|
</p></dd><dt>Value</dt><dd><p> Any of <code>opaque</code>, <code>transparent</code>, <code>add</code>. Defaults to <code>transparent</code>.
|
|
|
|
</p></dd><dt>Description</dt><dd><p> Defines how the <code>postLightingColor</code> material property is blended with the result of the
|
|
lighting computations. The possible blending modes are:
|
|
|
|
</p><p>
|
|
|
|
</p><ul>
|
|
<li class="minus"><strong class="asterisk">Opaque</strong>: blending is disabled, the material will output <code>postLightingColor</code> directly.
|
|
</li>
|
|
<li class="minus"><strong class="asterisk">Transparent</strong>: blending is enabled. The material's computed color is alpha composited with
|
|
the <code>postLightingColor</code>, using Porter-Duff's <code>source over</code> rule. This blending mode assumes
|
|
pre-multiplied alpha.
|
|
</li>
|
|
<li class="minus"><strong class="asterisk">Add</strong>: blending is enabled. The material's computed color is added to <code>postLightingColor</code>.
|
|
</li>
|
|
<li class="minus"><strong class="asterisk">Multiply</strong>: blending is enabled. The material's computed color is multiplied with <code>postLightingColor</code>.
|
|
</li>
|
|
<li class="minus"><strong class="asterisk">Screen</strong>: blending is enabled. The material's computed color is inverted and multiplied with <code>postLightingColor</code>,
|
|
and the result is added to the material's computed color.</li></ul>
|
|
|
|
<p></p></dd></dl><p></p><pre class="listing tilde"><code><span class="line">material {</span>
|
|
<span class="line"> postLightingBlending : add</span>
|
|
<span class="line">}</span></code></pre>
|
|
<a class="target" name="blendingandtransparency:transparency"> </a><a class="target" name="materialdefinitions/materialblock/blendingandtransparency:transparency"> </a><a class="target" name="toc4.2.12"> </a><h3>Blending and transparency: transparency</h3>
|
|
<p>
|
|
|
|
|
|
</p><dl><dt>Type</dt><dd><p> <code>string</code>
|
|
|
|
</p></dd><dt>Value</dt><dd><p> Any of <code>default</code>, <code>twoPassesOneSide</code> or <code>twoPassesTwoSides</code>. Defaults to <code>default</code>.
|
|
|
|
</p></dd><dt>Description</dt><dd><p> Controls how transparent objects are rendered. It is only valid when the <code>blending</code> mode is
|
|
not <code>opaque</code>. None of these methods can accurately render concave geometry, but in practice
|
|
they are often good enough.
|
|
|
|
</p></dd></dl>The three possible transparency modes are:
|
|
|
|
<p></p><p>
|
|
|
|
</p><ul>
|
|
<li class="minus"><code>default</code>: the transparent object is rendered normally (as seen in <a href="#figure_transparencydefault">figure 31</a>),
|
|
honoring the <code>culling</code> mode, etc.
|
|
</li>
|
|
<li class="minus"><code>twoPassesOneSide</code>: the transparent object is first rendered in the depth buffer, then again in
|
|
the color buffer, honoring the <code>culling</code> mode. This effectively renders only half of the
|
|
transparent object as shown in <a href="#figure_transparencytwopassesoneside">figure 32</a>.
|
|
</li>
|
|
<li class="minus"><code>twoPassesTwoSides</code>: the transparent object is rendered twice in the color buffer: first with its
|
|
back faces, then with its front faces. This mode lets you render both set of faces while reducing
|
|
or eliminating sorting issues, as shown in <a href="#figure_transparencytwopassestwosides">figure 33</a>.
|
|
<code>twoPassesTwoSides</code> can be combined with <code>doubleSided</code> for better effect.</li></ul>
|
|
|
|
<p></p><pre class="listing tilde"><code><span class="line">material {</span>
|
|
<span class="line"> transparency : twoPassesOneSide</span>
|
|
<span class="line">}</span></code></pre><p>
|
|
|
|
</p><center><div class="image" style><a href="images/screenshot_transparency_default.png" target="_blank"><img class="markdeep" src="images/screenshot_transparency_default.png"></a><div class="imagecaption"><a class="target" name="figure_transparencydefault"> </a><b style="font-style:normal;">Figure 31:</b> This double sided model shows the type of sorting issues transparent
|
|
objects can be subject to in <code>default</code> mode</div></div></center>
|
|
|
|
<p></p><p>
|
|
|
|
</p><center><div class="image" style><a href="images/screenshot_twopasses_oneside.png" target="_blank"><img class="markdeep" src="images/screenshot_twopasses_oneside.png"></a><div class="imagecaption"><a class="target" name="figure_transparencytwopassesoneside"> </a><b style="font-style:normal;">Figure 32:</b> In <code>twoPassesOneSide</code> mode, only one set of faces is visible
|
|
and correctly sorted</div></div></center>
|
|
|
|
<p></p><p>
|
|
|
|
</p><center><div class="image" style><a href="images/screenshot_twopasses_twosides.png" target="_blank"><img class="markdeep" src="images/screenshot_twopasses_twosides.png"></a><div class="imagecaption"><a class="target" name="figure_transparencytwopassestwosides"> </a><b style="font-style:normal;">Figure 33:</b> In <code>twoPassesTwoSides</code> mode, both set of faces are visible
|
|
and sorting issues are minimized or eliminated</div></div></center>
|
|
|
|
<p></p>
|
|
<a class="target" name="blendingandtransparency:maskthreshold"> </a><a class="target" name="materialdefinitions/materialblock/blendingandtransparency:maskthreshold"> </a><a class="target" name="toc4.2.13"> </a><h3>Blending and transparency: maskThreshold</h3>
|
|
<p>
|
|
|
|
|
|
</p><dl><dt>Type</dt><dd><p> <code>number</code>
|
|
|
|
</p></dd><dt>Value</dt><dd><p> A value between <code>0.0</code> and <code>1.0</code>. Defaults to <code>0.4</code>.
|
|
|
|
</p></dd><dt>Description</dt><dd><p> Sets the minimum alpha value a fragment must have to not be discarded when the <code>blending</code> mode
|
|
is set to <code>masked</code>. When the blending mode is not <code>masked</code>, this value is ignored. This value
|
|
can be used to controlled the appearance of alpha-masked objects.
|
|
|
|
</p></dd></dl><p></p><pre class="listing tilde"><code><span class="line">material {</span>
|
|
<span class="line"> blending : masked,</span>
|
|
<span class="line"> maskThreshold : 0.5</span>
|
|
<span class="line">}</span></code></pre>
|
|
<a class="target" name="blendingandtransparency:refractionmode"> </a><a class="target" name="materialdefinitions/materialblock/blendingandtransparency:refractionmode"> </a><a class="target" name="toc4.2.14"> </a><h3>Blending and transparency: refractionMode</h3>
|
|
<p>
|
|
|
|
|
|
</p><dl><dt>Type</dt><dd><p> <code>string</code>
|
|
|
|
</p></dd><dt>Value</dt><dd><p> Any of <code>none</code>, <code>cubemap</code>, <code>screenspace</code>. Defaults to <code>none</code>.
|
|
|
|
</p></dd><dt>Description</dt><dd><p> Activates refraction when set to anything but <code>none</code>. A value of <code>cubemap</code> will only use the
|
|
IBL cubemap as source of refraction, while this is significantly more efficient, no scene
|
|
objects will be refracted, only the distant environment encoded in the cubemap. This mode is
|
|
adequate for an object viewer for instance. A value of <code>screenspace</code> will employ the more
|
|
advanced screen-space refraction algorithm which allows opaque objects in the scene to be
|
|
refracted. In <code>cubemap</code> mode, refracted rays are assumed to emerge from the center of the
|
|
object and the <code>thickness</code> parameter is only used for computing the absorption, but has no
|
|
impact on the refraction itself. In <code>screenspace</code> mode, refracted rays are assumed to travel
|
|
parallel to the view direction when they exit the refractive medium.
|
|
|
|
</p></dd></dl><p></p><pre class="listing tilde"><code><span class="line">material {</span>
|
|
<span class="line"> refractionMode : cubemap,</span>
|
|
<span class="line">}</span></code></pre>
|
|
<a class="target" name="blendingandtransparency:refractiontype"> </a><a class="target" name="materialdefinitions/materialblock/blendingandtransparency:refractiontype"> </a><a class="target" name="toc4.2.15"> </a><h3>Blending and transparency: refractionType</h3>
|
|
<p>
|
|
|
|
|
|
</p><dl><dt>Type</dt><dd><p> <code>string</code>
|
|
|
|
</p></dd><dt>Value</dt><dd><p> Any of <code>solid</code>, <code>thin</code>. Defaults to <code>solid</code>.
|
|
|
|
</p></dd><dt>Description</dt><dd><p> This is only meaningful when <code>refractionMode</code> is set to anything but <code>none</code>. <code>refractionType</code>
|
|
defines the refraction model used. <code>solid</code> is used for thick objects such as a crystal ball,
|
|
an ice cube or as sculpture. <code>thin</code> is used for thin objects such as a window, an ornament
|
|
ball or a soap bubble. In <code>solid</code> mode all refracive objects are assumed to be a sphere
|
|
tangent to the entry point and of radius <code>thickness</code>. In <code>thin</code> mode, all refractive objects
|
|
are assumed to be flat and thin and of thickness <code>thickness</code>.
|
|
|
|
</p></dd></dl><p></p><pre class="listing tilde"><code><span class="line">material {</span>
|
|
<span class="line"> refractionMode : cubemap,</span>
|
|
<span class="line"> refractionType : thin,</span>
|
|
<span class="line">}</span></code></pre>
|
|
<a class="target" name="rasterization:culling"> </a><a class="target" name="materialdefinitions/materialblock/rasterization:culling"> </a><a class="target" name="toc4.2.16"> </a><h3>Rasterization: culling</h3>
|
|
<p>
|
|
|
|
|
|
</p><dl><table><tbody><tr valign="top"><td><dt>Type</dt></td><td><dd><p> <code>string</code>
|
|
|
|
</p></dd></td></tr><tr valign="top"><td><dt>Value</dt></td><td><dd><p> Any of <code>none</code>, <code>front</code>, <code>back</code>, <code>frontAndBack</code>. Defaults to <code>back</code>.
|
|
|
|
</p></dd></td></tr><tr valign="top"><td><dt>Description</dt></td><td><dd><p> Defines which triangles should be culled: none, front-facing triangles, back-facing
|
|
triangles or all.
|
|
|
|
</p></dd></td></tr></tbody></table></dl><p></p><pre class="listing tilde"><code><span class="line">material {</span>
|
|
<span class="line"> culling : none</span>
|
|
<span class="line">}</span></code></pre>
|
|
<a class="target" name="rasterization:colorwrite"> </a><a class="target" name="materialdefinitions/materialblock/rasterization:colorwrite"> </a><a class="target" name="toc4.2.17"> </a><h3>Rasterization: colorWrite</h3>
|
|
<p>
|
|
|
|
|
|
</p><dl><table><tbody><tr valign="top"><td><dt>Type</dt></td><td><dd><p> <code>boolean</code>
|
|
|
|
</p></dd></td></tr><tr valign="top"><td><dt>Value</dt></td><td><dd><p> <code>true</code> or <code>false</code>. Defaults to <code>true</code>.
|
|
|
|
</p></dd></td></tr><tr valign="top"><td><dt>Description</dt></td><td><dd><p> Enables or disables writes to the color buffer.
|
|
|
|
</p></dd></td></tr></tbody></table></dl><p></p><pre class="listing tilde"><code><span class="line">material {</span>
|
|
<span class="line"> colorWrite : false</span>
|
|
<span class="line">}</span></code></pre>
|
|
<a class="target" name="rasterization:depthwrite"> </a><a class="target" name="materialdefinitions/materialblock/rasterization:depthwrite"> </a><a class="target" name="toc4.2.18"> </a><h3>Rasterization: depthWrite</h3>
|
|
<p>
|
|
|
|
|
|
</p><dl><table><tbody><tr valign="top"><td><dt>Type</dt></td><td><dd><p> <code>boolean</code>
|
|
|
|
</p></dd></td></tr><tr valign="top"><td><dt>Value</dt></td><td><dd><p> <code>true</code> or <code>false</code>. Defaults to <code>true</code> for opaque materials, <code>false</code> for transparent materials.
|
|
|
|
</p></dd></td></tr><tr valign="top"><td><dt>Description</dt></td><td><dd><p> Enables or disables writes to the depth buffer.
|
|
|
|
</p></dd></td></tr></tbody></table></dl><p></p><pre class="listing tilde"><code><span class="line">material {</span>
|
|
<span class="line"> depthWrite : false</span>
|
|
<span class="line">}</span></code></pre>
|
|
<a class="target" name="rasterization:depthculling"> </a><a class="target" name="materialdefinitions/materialblock/rasterization:depthculling"> </a><a class="target" name="toc4.2.19"> </a><h3>Rasterization: depthCulling</h3>
|
|
<p>
|
|
|
|
|
|
</p><dl><dt>Type</dt><dd><p> <code>boolean</code>
|
|
|
|
</p></dd><dt>Value</dt><dd><p> <code>true</code> or <code>false</code>. Defaults to <code>true</code>.
|
|
|
|
</p></dd><dt>Description</dt><dd><p> Enables or disables depth testing. When depth testing is disabled, an object rendered with
|
|
this material will always appear on top of other opaque objects.
|
|
|
|
</p></dd></dl><p></p><pre class="listing tilde"><code><span class="line">material {</span>
|
|
<span class="line"> depthCulling : false</span>
|
|
<span class="line">}</span></code></pre>
|
|
<a class="target" name="rasterization:doublesided"> </a><a class="target" name="materialdefinitions/materialblock/rasterization:doublesided"> </a><a class="target" name="toc4.2.20"> </a><h3>Rasterization: doubleSided</h3>
|
|
<p>
|
|
|
|
|
|
</p><dl><dt>Type</dt><dd><p> <code>boolean</code>
|
|
|
|
</p></dd><dt>Value</dt><dd><p> <code>true</code> or <code>false</code>. Defaults to <code>false</code>.
|
|
|
|
</p></dd><dt>Description</dt><dd><p> Enables two-sided rendering and its capability to be toggled at run time. When set to <code>true</code>,
|
|
<code>culling</code> is automatically set to <code>none</code>; if the triangle is back-facing, the triangle's
|
|
normal is flipped to become front-facing. When explicitly set to <code>false</code>, this allows the
|
|
double-sidedness to be toggled at run time.
|
|
|
|
</p></dd></dl><p></p><pre class="listing tilde"><code><span class="line">material {</span>
|
|
<span class="line"> doubleSided : true</span>
|
|
<span class="line">}</span></code></pre>
|
|
<a class="target" name="lighting:shadowmultiplier"> </a><a class="target" name="materialdefinitions/materialblock/lighting:shadowmultiplier"> </a><a class="target" name="toc4.2.21"> </a><h3>Lighting: shadowMultiplier</h3>
|
|
<p>
|
|
|
|
|
|
</p><dl><dt>Type</dt><dd><p> <code>boolean</code>
|
|
|
|
</p></dd><dt>Value</dt><dd><p> <code>true</code> or <code>false</code>. Defaults to <code>false</code>.
|
|
|
|
</p></dd><dt>Description</dt><dd><p> Only available in the <code>unlit</code> shading model. If this property is enabled, the final color
|
|
computed by the material is multiplied by the shadowing factor (or visibility). This allows to
|
|
create transparent shadow-receiving objects (for instance an invisible ground plane in AR).
|
|
|
|
</p></dd></dl><p></p><pre class="listing tilde"><code><span class="line">material {</span>
|
|
<span class="line"> name : "Invisible shadow plane",</span>
|
|
<span class="line"> shadingModel : unlit,</span>
|
|
<span class="line"> shadowMultiplier : true,</span>
|
|
<span class="line"> blending : transparent</span>
|
|
<span class="line">}</span>
|
|
<span class="line"></span>
|
|
<span class="line">fragment {</span>
|
|
<span class="line"> void material(inout MaterialInputs material) {</span>
|
|
<span class="line"> prepareMaterial(material);</span>
|
|
<span class="line"> // baseColor defines the color and opacity of the final shadow</span>
|
|
<span class="line"> material.baseColor = vec4(0.0, 0.0, 0.0, 0.7);</span>
|
|
<span class="line"> }</span>
|
|
<span class="line">}</span></code></pre>
|
|
<a class="target" name="lighting:clearcoatiorchange"> </a><a class="target" name="materialdefinitions/materialblock/lighting:clearcoatiorchange"> </a><a class="target" name="toc4.2.22"> </a><h3>Lighting: clearCoatIorChange</h3>
|
|
<p>
|
|
|
|
|
|
</p><dl><dt>Type</dt><dd><p> <code>boolean</code>
|
|
|
|
</p></dd><dt>Value</dt><dd><p> <code>true</code> or <code>false</code>. Defaults to <code>true</code>.
|
|
|
|
</p></dd><dt>Description</dt><dd><p> When adding a clear coat layer, the change in index of refraction (IoR) is taken into account
|
|
to modify the specular color of the base layer. This appears to darken <code>baseColor</code>. When this
|
|
effect is disabled, <code>baseColor</code> is left unmodified. See <a href="#figure_clearcoatiorchange">figure 34</a> for an
|
|
example of how this property can affect a red metallic base layer.
|
|
|
|
</p></dd></dl><p></p><pre class="listing tilde"><code><span class="line">material {</span>
|
|
<span class="line"> clearCoatIorChange : false</span>
|
|
<span class="line">}</span></code></pre><p>
|
|
|
|
</p><center><div class="image" style><a href="images/screenshot_clear_coat_ior_change.jpg" target="_blank"><img class="markdeep" src="images/screenshot_clear_coat_ior_change.jpg"></a><div class="imagecaption"><a class="target" name="figure_clearcoatiorchange"> </a><b style="font-style:normal;">Figure 34:</b> The same rough metallic ball with a clear coat layer rendered
|
|
with <code>clearCoatIorChange</code> enabled (left) and disabled
|
|
(right).</div></div></center>
|
|
|
|
<p></p>
|
|
<a class="target" name="lighting:multibounceambientocclusion"> </a><a class="target" name="materialdefinitions/materialblock/lighting:multibounceambientocclusion"> </a><a class="target" name="toc4.2.23"> </a><h3>Lighting: multiBounceAmbientOcclusion</h3>
|
|
<p>
|
|
|
|
|
|
</p><dl><dt>Type</dt><dd><p> <code>boolean</code>
|
|
|
|
</p></dd><dt>Value</dt><dd><p> <code>true</code> or <code>false</code>. Defaults to <code>false</code> on mobile, <code>true</code> on desktop.
|
|
|
|
</p></dd><dt>Description</dt><dd><p> Multi-bounce ambient occlusion takes into account interreflections when applying ambient
|
|
occlusion to image-based lighting. Turning this feature on avoids over-darkening occluded
|
|
areas. It also takes the surface color into account to generate colored ambient occlusion.
|
|
<a href="#figure_multibounceao">Figure 35</a> compares the ambient occlusion term of a surface with and without
|
|
multi-bounce ambient occlusion. Notice how multi-bounce ambient occlusion introduces color
|
|
in the occluded areas. <a href="#figure_multibounceaoanimated">Figure 36</a> toggles between multi-bounce ambient
|
|
occlusion on and off on a lit brick material to highlight the effects of this property.
|
|
|
|
</p></dd></dl><p></p><pre class="listing tilde"><code><span class="line">material {</span>
|
|
<span class="line"> multiBounceAmbientOcclusion : true</span>
|
|
<span class="line">}</span></code></pre><p>
|
|
|
|
</p><center><div class="image" style><a href="images/screenshot_multi_bounce_ao.jpg" target="_blank"><img class="markdeep" src="images/screenshot_multi_bounce_ao.jpg"></a><div class="imagecaption"><a class="target" name="figure_multibounceao"> </a><b style="font-style:normal;">Figure 35:</b> Brick texture amient occlusion map rendered with multi-bounce ambient
|
|
occclusion enabled (left) and disabled (right).</div></div></center>
|
|
|
|
<p></p><p>
|
|
|
|
</p><center><div class="image" style><a href="images/screenshot_multi_bounce_ao.gif" target="_blank"><img class="markdeep" src="images/screenshot_multi_bounce_ao.gif"></a><div class="imagecaption"><a class="target" name="figure_multibounceaoanimated"> </a><b style="font-style:normal;">Figure 36:</b> Brick texture rendered with multi-bounce ambient
|
|
occclusion enabled and disabled.</div></div></center>
|
|
|
|
<p></p>
|
|
<a class="target" name="lighting:specularambientocclusion"> </a><a class="target" name="materialdefinitions/materialblock/lighting:specularambientocclusion"> </a><a class="target" name="toc4.2.24"> </a><h3>Lighting: specularAmbientOcclusion</h3>
|
|
<p>
|
|
|
|
|
|
</p><dl><dt>Type</dt><dd><p> <code>boolean</code>
|
|
|
|
</p></dd><dt>Value</dt><dd><p> <code>true</code> or <code>false</code>. Defaults to <code>false</code> on mobile, <code>true</code> on desktop.
|
|
|
|
</p></dd><dt>Description</dt><dd><p> Static ambient occlusion maps and dynamic ambient occlusion (SSAO, etc.) apply to diffuse
|
|
indirect lighting. When setting this property to true, a new ambient occlusion term is
|
|
derived from the surface roughness and applied to specular indirec lighting. This effect
|
|
helps remove unwanted specular reflections as shown in <a href="#figure_specularao">figure 37</a>.
|
|
|
|
</p></dd></dl><p></p><pre class="listing tilde"><code><span class="line">material {</span>
|
|
<span class="line"> specularAmbientOcclusion : true</span>
|
|
<span class="line">}</span></code></pre><p>
|
|
|
|
</p><center><div class="image" style><a href="images/screenshot_specular_ao.gif" target="_blank"><img class="markdeep" src="images/screenshot_specular_ao.gif"></a><div class="imagecaption"><a class="target" name="figure_specularao"> </a><b style="font-style:normal;">Figure 37:</b> Comparison of specular ambient occlusion on and off. The effect is
|
|
particularly visible under the hose.</div></div></center>
|
|
|
|
<p></p>
|
|
<a class="target" name="anti-aliasing:specularantialiasing"> </a><a class="target" name="materialdefinitions/materialblock/anti-aliasing:specularantialiasing"> </a><a class="target" name="toc4.2.25"> </a><h3>Anti-aliasing: specularAntiAliasing</h3>
|
|
<p>
|
|
|
|
|
|
</p><dl><dt>Type</dt><dd><p> <code>boolean</code>
|
|
|
|
</p></dd><dt>Value</dt><dd><p> <code>true</code> or <code>false</code>. Defaults to <code>false</code>.
|
|
|
|
</p></dd><dt>Description</dt><dd><p> Reduces specular aliasing and preserves the shape of specular highlights as an object moves
|
|
away from the camera. This anti-aliasing solution is particularly effective on glossy materials
|
|
(low roughness) but increases the cost of the material. The strengthf of the anti-aliasing
|
|
effect can be controlled using two other properties: <code>specularAntiAliasingVariance</code> and
|
|
<code>specularAntiAliasingThreshold</code>.
|
|
|
|
</p></dd></dl><p></p><pre class="listing tilde"><code><span class="line">material {</span>
|
|
<span class="line"> specularAntiAliasing : true</span>
|
|
<span class="line">}</span></code></pre>
|
|
<a class="target" name="anti-aliasing:specularantialiasingvariance"> </a><a class="target" name="materialdefinitions/materialblock/anti-aliasing:specularantialiasingvariance"> </a><a class="target" name="toc4.2.26"> </a><h3>Anti-aliasing: specularAntiAliasingVariance</h3>
|
|
<p>
|
|
|
|
|
|
</p><dl><dt>Type</dt><dd><p> <code>float</code>
|
|
|
|
</p></dd><dt>Value</dt><dd><p> A value between 0 and 1, set to 0.15 by default.
|
|
|
|
</p></dd><dt>Description</dt><dd><p> Sets the screen space variance of the filter kernel used when applying specular anti-aliasing.
|
|
Higher values will increase the effect of the filter but may increase roughness in unwanted
|
|
areas.
|
|
|
|
</p></dd></dl><p></p><pre class="listing tilde"><code><span class="line">material {</span>
|
|
<span class="line"> specularAntiAliasingVariance : 0.2</span>
|
|
<span class="line">}</span></code></pre>
|
|
<a class="target" name="anti-aliasing:specularantialiasingthreshold"> </a><a class="target" name="materialdefinitions/materialblock/anti-aliasing:specularantialiasingthreshold"> </a><a class="target" name="toc4.2.27"> </a><h3>Anti-aliasing: specularAntiAliasingThreshold</h3>
|
|
<p>
|
|
|
|
|
|
</p><dl><dt>Type</dt><dd><p> <code>float</code>
|
|
|
|
</p></dd><dt>Value</dt><dd><p> A value between 0 and 1, set to 0.2 by default.
|
|
|
|
</p></dd><dt>Description</dt><dd><p> Sets the clamping threshold used to suppress estimation errors when applying specular
|
|
anti-aliasing. When set to 0, specular anti-aliasing is disabled.
|
|
|
|
</p></dd></dl><p></p><pre class="listing tilde"><code><span class="line">material {</span>
|
|
<span class="line"> specularAntiAliasingThreshold : 0.1</span>
|
|
<span class="line">}</span></code></pre>
|
|
<a class="target" name="vertexblock"> </a><a class="target" name="materialdefinitions/vertexblock"> </a><a class="target" name="toc4.3"> </a><h2>Vertex block</h2>
|
|
<p>
|
|
|
|
|
|
The vertex block is optional and can be used to control the vertex shading stage of the material.
|
|
The vertex block must contain valid
|
|
<a href="https://www.khronos.org/registry/OpenGL/specs/es/3.0/GLSL_ES_Specification_3.00.pdf">ESSL 3.0</a> code
|
|
(the version of GLSL supported in OpenGL ES 3.0). You are free to create multiple functions inside
|
|
the vertex block but you <strong class="asterisk">must</strong> declare the <code>materialVertex</code> function:
|
|
|
|
</p><pre class="listing tilde"><code><span class="line">vertex {</span>
|
|
<span class="line"> <span class="hljs-type">void</span> materialVertex(<span class="hljs-keyword">inout</span> MaterialVertexInputs material) {</span>
|
|
<span class="line"> <span class="hljs-comment">// vertex shading code</span></span>
|
|
<span class="line"> }</span>
|
|
<span class="line">}</span></code></pre><p>
|
|
|
|
This function will be invoked automatically at runtime by the shading system and gives you the
|
|
ability to read and modify material properties using the <code>MaterialVertexInputs</code> structure. This full
|
|
definition of the structure can be found in the <a href="#materialvertexinputs">Material vertex inputs</a> section.
|
|
|
|
</p><p>
|
|
|
|
You can use this structure to compute your custom variables/interpolants or to modify the value of
|
|
the attributes. For instance, the following vertex blocks modifies both the color and the UV
|
|
coordinates of the vertex over time:
|
|
|
|
</p><pre class="listing tilde"><code><span class="line">material {</span>
|
|
<span class="line"> requires : [uv0, color]</span>
|
|
<span class="line">}</span>
|
|
<span class="line">vertex {</span>
|
|
<span class="line"> <span class="hljs-type">void</span> materialVertex(<span class="hljs-keyword">inout</span> MaterialVertexInputs material) {</span>
|
|
<span class="line"> material.color *= <span class="hljs-built_in">sin</span>(getTime());</span>
|
|
<span class="line"> material.uv0 *= <span class="hljs-built_in">sin</span>(getTime());</span>
|
|
<span class="line"> }</span>
|
|
<span class="line">}</span></code></pre><p>
|
|
|
|
In addition to the <code>MaterialVertexInputs</code> structure, your vertex shading code can use all the public
|
|
APIs listed in the <a href="#shaderpublicapis">Shader public APIs</a> section.
|
|
|
|
</p>
|
|
<a class="target" name="materialvertexinputs"> </a><a class="target" name="materialdefinitions/vertexblock/materialvertexinputs"> </a><a class="target" name="toc4.3.1"> </a><h3>Material vertex inputs</h3>
|
|
<pre class="listing tilde"><code><span class="line">struct MaterialVertexInputs {</span>
|
|
<span class="line"> float4 color; <span class="hljs-comment">// if the color attribute is required</span></span>
|
|
<span class="line"> float2 uv0; <span class="hljs-comment">// if the uv0 attribute is required</span></span>
|
|
<span class="line"> float2 uv1; <span class="hljs-comment">// if the uv1 attribute is required</span></span>
|
|
<span class="line"> float3 worldNormal; <span class="hljs-comment">// only if the shading model is not unlit</span></span>
|
|
<span class="line"> float4 worldPosition; <span class="hljs-comment">// always available (see note below about world-space)</span></span>
|
|
<span class="line"></span>
|
|
<span class="line"> <span class="hljs-type">mat4</span> clipSpaceTransform; <span class="hljs-comment">// default: identity, transforms the clip-space position</span></span>
|
|
<span class="line"></span>
|
|
<span class="line"> <span class="hljs-comment">// variable* names are replaced with actual names</span></span>
|
|
<span class="line"> float4 variable0; <span class="hljs-comment">// if 1 or more variables is defined</span></span>
|
|
<span class="line"> float4 variable1; <span class="hljs-comment">// if 2 or more variables is defined</span></span>
|
|
<span class="line"> float4 variable2; <span class="hljs-comment">// if 3 or more variables is defined</span></span>
|
|
<span class="line"> float4 variable3; <span class="hljs-comment">// if 4 or more variables is defined</span></span>
|
|
<span class="line">};</span></code></pre><p>
|
|
|
|
|
|
|
|
</p><div class="admonition tip"><div class="admonition-title"> worldPosition</div>
|
|
|
|
<p></p><p>
|
|
|
|
To achieve good precision, the <code>worldPosition</code> coordinate in the vertex shader is shifted by the
|
|
camera position. To get the true world-space position, users can add this to
|
|
<code>getWorldOffset()</code>.</p></div>
|
|
|
|
<p></p><p>
|
|
|
|
</p><div class="admonition tip"><div class="admonition-title"> UV attributes</div>
|
|
|
|
<p></p><p>
|
|
|
|
By default the vertex shader of a material will flip the Y coordinate of the UV attributes
|
|
of the current mesh: <code>material.uv0 = vec2(mesh_uv0.x, 1.0 - mesh_uv0.y)</code>. You can control
|
|
this behavior using the <code>flipUV</code> property and setting it to <code>false</code>.</p></div>
|
|
|
|
<p></p>
|
|
<a class="target" name="fragmentblock"> </a><a class="target" name="materialdefinitions/fragmentblock"> </a><a class="target" name="toc4.4"> </a><h2>Fragment block</h2>
|
|
<p>
|
|
|
|
|
|
The fragment block must be used to control the fragment shading stage of the material. The vertex
|
|
block must contain valid
|
|
<a href="https://www.khronos.org/registry/OpenGL/specs/es/3.0/GLSL_ES_Specification_3.00.pdf">ESSL 3.0</a>
|
|
code (the version of GLSL supported in OpenGL ES 3.0). You are free to create multiple functions
|
|
inside the vertex block but you <strong class="asterisk">must</strong> declare the <code>material</code> function:
|
|
|
|
</p><pre class="listing tilde"><code><span class="line">fragment {</span>
|
|
<span class="line"> <span class="hljs-type">void</span> material(<span class="hljs-keyword">inout</span> MaterialInputs material) {</span>
|
|
<span class="line"> prepareMaterial(material);</span>
|
|
<span class="line"> <span class="hljs-comment">// fragment shading code</span></span>
|
|
<span class="line"> }</span>
|
|
<span class="line">}</span></code></pre><p>
|
|
|
|
This function will be invoked automatically at runtime by the shading system and gives you the
|
|
ability to read and modify material properties using the <code>MaterialInputs</code> structure. This full
|
|
definition of the structure can be found in the <a href="#materialfragmentinputs">Material fragment inputs</a> section. The full
|
|
definition of the various members of the structure can be found in the <a href="#materialmodels">Material models</a> section
|
|
of this document.
|
|
|
|
</p><p>
|
|
|
|
The goal of the <code>material()</code> function is to compute the material properties specific to the selected
|
|
shading model. For instance, here is a fragment block that creates a glossy red metal using the
|
|
standard lit shading model:
|
|
|
|
</p><pre class="listing tilde"><code><span class="line">fragment {</span>
|
|
<span class="line"> <span class="hljs-type">void</span> material(<span class="hljs-keyword">inout</span> MaterialInputs material) {</span>
|
|
<span class="line"> prepareMaterial(material);</span>
|
|
<span class="line"> material.baseColor.rgb = <span class="hljs-type">vec3</span>(<span class="hljs-number">1.0</span>, <span class="hljs-number">0.0</span>, <span class="hljs-number">0.0</span>);</span>
|
|
<span class="line"> material.metallic = <span class="hljs-number">1.0</span>;</span>
|
|
<span class="line"> material.roughness = <span class="hljs-number">0.0</span>;</span>
|
|
<span class="line"> }</span>
|
|
<span class="line">}</span></code></pre>
|
|
<a class="target" name="preparematerialfunction"> </a><a class="target" name="materialdefinitions/fragmentblock/preparematerialfunction"> </a><a class="target" name="toc4.4.1"> </a><h3>prepareMaterial function</h3>
|
|
<p>
|
|
|
|
|
|
Note that you <strong class="asterisk">must</strong> call <code>prepareMaterial(material)</code> before exiting the <code>material()</code> function.
|
|
This <code>prepareMaterial</code> function sets up the internal state of the material mdoel. Some of the APIs
|
|
described in the Fragment APIs section - like <code>shading_normal</code> for instance - can only be accessed
|
|
<em class="underscore">after</em> invoking <code>prepareMaterial()</code>.
|
|
|
|
</p><p>
|
|
|
|
It is also important to remember that the <code>normal</code> property - as described in the Material fragment
|
|
inputs section - only has an effect when modified <em class="underscore">before</em> calling <code>prepareMaterial()</code>. Here is an
|
|
example of a fragment shader that properly modifies the <code>normal</code> property to implement a glossy red
|
|
plastic with bump mapping:
|
|
|
|
</p><pre class="listing tilde"><code><span class="line">fragment {</span>
|
|
<span class="line"> <span class="hljs-type">void</span> material(<span class="hljs-keyword">inout</span> MaterialInputs material) {</span>
|
|
<span class="line"> <span class="hljs-comment">// fetch the normal in tangent space</span></span>
|
|
<span class="line"> <span class="hljs-type">vec3</span> normal = <span class="hljs-built_in">texture</span>(materialParams_normalMap, getUV0()).xyz;</span>
|
|
<span class="line"> material.normal = normal * <span class="hljs-number">2.0</span> - <span class="hljs-number">1.0</span>;</span>
|
|
<span class="line"></span>
|
|
<span class="line"> <span class="hljs-comment">// prepare the material</span></span>
|
|
<span class="line"> prepareMaterial(material);</span>
|
|
<span class="line"></span>
|
|
<span class="line"> <span class="hljs-comment">// from now on, shading_normal, etc. can be accessed</span></span>
|
|
<span class="line"> material.baseColor.rgb = <span class="hljs-type">vec3</span>(<span class="hljs-number">1.0</span>, <span class="hljs-number">0.0</span>, <span class="hljs-number">0.0</span>);</span>
|
|
<span class="line"> material.metallic = <span class="hljs-number">0.0</span>;</span>
|
|
<span class="line"> material.roughness = <span class="hljs-number">1.0</span>;</span>
|
|
<span class="line"> }</span>
|
|
<span class="line">}</span></code></pre>
|
|
<a class="target" name="materialfragmentinputs"> </a><a class="target" name="materialdefinitions/fragmentblock/materialfragmentinputs"> </a><a class="target" name="toc4.4.2"> </a><h3>Material fragment inputs</h3>
|
|
<pre class="listing tilde"><code><span class="line">struct MaterialInputs {</span>
|
|
<span class="line"> float4 baseColor; <span class="hljs-comment">// default: float4(1.0)</span></span>
|
|
<span class="line"> float4 emissive; <span class="hljs-comment">// default: float4(0.0)</span></span>
|
|
<span class="line"> float4 postLightingColor; <span class="hljs-comment">// default: float4(0.0)</span></span>
|
|
<span class="line"></span>
|
|
<span class="line"> <span class="hljs-comment">// no other field is available with the unlit shading model</span></span>
|
|
<span class="line"> <span class="hljs-type">float</span> roughness; <span class="hljs-comment">// default: 1.0</span></span>
|
|
<span class="line"> <span class="hljs-type">float</span> metallic; <span class="hljs-comment">// default: 0.0, not available with cloth or specularGlossiness</span></span>
|
|
<span class="line"> <span class="hljs-type">float</span> reflectance; <span class="hljs-comment">// default: 0.5, not available with cloth or specularGlossiness</span></span>
|
|
<span class="line"> <span class="hljs-type">float</span> ambientOcclusion; <span class="hljs-comment">// default: 0.0</span></span>
|
|
<span class="line"></span>
|
|
<span class="line"> <span class="hljs-comment">// not available when the shading model is subsurface or cloth</span></span>
|
|
<span class="line"> <span class="hljs-type">float</span> clearCoat; <span class="hljs-comment">// default: 1.0</span></span>
|
|
<span class="line"> <span class="hljs-type">float</span> clearCoatRoughness; <span class="hljs-comment">// default: 0.0</span></span>
|
|
<span class="line"> float3 clearCoatNormal; <span class="hljs-comment">// default: float3(0.0, 0.0, 1.0)</span></span>
|
|
<span class="line"> <span class="hljs-type">float</span> anisotropy; <span class="hljs-comment">// default: 0.0</span></span>
|
|
<span class="line"> float3 anisotropyDirection; <span class="hljs-comment">// default: float3(1.0, 0.0, 0.0)</span></span>
|
|
<span class="line"></span>
|
|
<span class="line"> <span class="hljs-comment">// only available when the shading model is subsurface or refraction is enabled</span></span>
|
|
<span class="line"> <span class="hljs-type">float</span> thickness; <span class="hljs-comment">// default: 0.5</span></span>
|
|
<span class="line"></span>
|
|
<span class="line"> <span class="hljs-comment">// only available when the shading model is subsurface</span></span>
|
|
<span class="line"> <span class="hljs-type">float</span> subsurfacePower; <span class="hljs-comment">// default: 12.234</span></span>
|
|
<span class="line"> float3 subsurfaceColor; <span class="hljs-comment">// default: float3(1.0)</span></span>
|
|
<span class="line"></span>
|
|
<span class="line"> <span class="hljs-comment">// only available when the shading model is cloth</span></span>
|
|
<span class="line"> float3 sheenColor; <span class="hljs-comment">// default: sqrt(baseColor)</span></span>
|
|
<span class="line"> float3 subsurfaceColor; <span class="hljs-comment">// default: float3(0.0)</span></span>
|
|
<span class="line"></span>
|
|
<span class="line"> <span class="hljs-comment">// only available when the shading model is specularGlossiness</span></span>
|
|
<span class="line"> float3 specularColor; <span class="hljs-comment">// default: float3(0.0)</span></span>
|
|
<span class="line"> <span class="hljs-type">float</span> glossiness; <span class="hljs-comment">// default: 0.0</span></span>
|
|
<span class="line"></span>
|
|
<span class="line"> <span class="hljs-comment">// not available when the shading model is unlit</span></span>
|
|
<span class="line"> <span class="hljs-comment">// must be set before calling prepareMaterial()</span></span>
|
|
<span class="line"> float3 normal; <span class="hljs-comment">// default: float3(0.0, 0.0, 1.0)</span></span>
|
|
<span class="line"></span>
|
|
<span class="line"> <span class="hljs-comment">// only available when refraction is enabled</span></span>
|
|
<span class="line"> <span class="hljs-type">float</span> transmission; <span class="hljs-comment">// default: 1.0</span></span>
|
|
<span class="line"> float3 absorption; <span class="hljs-comment">// default float3(0.0, 0.0, 0.0)</span></span>
|
|
<span class="line"> <span class="hljs-type">float</span> ior; <span class="hljs-comment">// default: 1.5</span></span>
|
|
<span class="line"> <span class="hljs-type">float</span> microThickness; <span class="hljs-comment">// default: 0.0, not available with refractionType "solid"</span></span>
|
|
<span class="line">}</span></code></pre>
|
|
<a class="target" name="shaderpublicapis"> </a><a class="target" name="materialdefinitions/shaderpublicapis"> </a><a class="target" name="toc4.5"> </a><h2>Shader public APIs</h2>
|
|
|
|
<a class="target" name="types"> </a><a class="target" name="materialdefinitions/shaderpublicapis/types"> </a><a class="target" name="toc4.5.1"> </a><h3>Types</h3>
|
|
<p>
|
|
|
|
|
|
While GLSL types can be used directly (<code>vec4</code> or <code>mat4</code>) we recommend the use of the following
|
|
type aliases:
|
|
</p><div class="table"><table class="table"><tbody><tr><th style="text-align:left"> Name </th><th style="text-align:center"> GLSL type </th><th style="text-align:left"> Description </th></tr>
|
|
<tr><td style="text-align:left"> <strong class="asterisk">bool2</strong> </td><td style="text-align:center"> bvec2 </td><td style="text-align:left"> A vector of 2 booleans </td></tr>
|
|
<tr><td style="text-align:left"> <strong class="asterisk">bool3</strong> </td><td style="text-align:center"> bvec3 </td><td style="text-align:left"> A vector of 3 booleans </td></tr>
|
|
<tr><td style="text-align:left"> <strong class="asterisk">bool4</strong> </td><td style="text-align:center"> bvec4 </td><td style="text-align:left"> A vector of 4 booleans </td></tr>
|
|
<tr><td style="text-align:left"> <strong class="asterisk">int2</strong> </td><td style="text-align:center"> ivec2 </td><td style="text-align:left"> A vector of 2 integers </td></tr>
|
|
<tr><td style="text-align:left"> <strong class="asterisk">int3</strong> </td><td style="text-align:center"> ivec3 </td><td style="text-align:left"> A vector of 3 integers </td></tr>
|
|
<tr><td style="text-align:left"> <strong class="asterisk">int4</strong> </td><td style="text-align:center"> ivec4 </td><td style="text-align:left"> A vector of 4 integers </td></tr>
|
|
<tr><td style="text-align:left"> <strong class="asterisk">uint2</strong> </td><td style="text-align:center"> uvec2 </td><td style="text-align:left"> A vector of 2 unsigned integers </td></tr>
|
|
<tr><td style="text-align:left"> <strong class="asterisk">uint3</strong> </td><td style="text-align:center"> uvec3 </td><td style="text-align:left"> A vector of 3 unsigned integers </td></tr>
|
|
<tr><td style="text-align:left"> <strong class="asterisk">uint4</strong> </td><td style="text-align:center"> uvec4 </td><td style="text-align:left"> A vector of 4 unsigned integers </td></tr>
|
|
<tr><td style="text-align:left"> <strong class="asterisk">float2</strong> </td><td style="text-align:center"> float2 </td><td style="text-align:left"> A vector of 2 floats </td></tr>
|
|
<tr><td style="text-align:left"> <strong class="asterisk">float3</strong> </td><td style="text-align:center"> float3 </td><td style="text-align:left"> A vector of 3 floats </td></tr>
|
|
<tr><td style="text-align:left"> <strong class="asterisk">float4</strong> </td><td style="text-align:center"> float4 </td><td style="text-align:left"> A vector of 4 floats </td></tr>
|
|
<tr><td style="text-align:left"> <strong class="asterisk">float4×4</strong> </td><td style="text-align:center"> mat4 </td><td style="text-align:left"> A 4×4 float matrix </td></tr>
|
|
<tr><td style="text-align:left"> <strong class="asterisk">float3×3</strong> </td><td style="text-align:center"> mat3 </td><td style="text-align:left"> A 3×3 float matrix </td></tr>
|
|
</tbody></table></div>
|
|
|
|
<p></p>
|
|
<a class="target" name="math"> </a><a class="target" name="materialdefinitions/shaderpublicapis/math"> </a><a class="target" name="toc4.5.2"> </a><h3>Math</h3>
|
|
<p>
|
|
</p><div class="table"><table class="table"><tbody><tr><th style="text-align:left"> Name </th><th style="text-align:center"> Type </th><th style="text-align:left"> Description </th></tr>
|
|
<tr><td style="text-align:left"> <strong class="asterisk">PI</strong> </td><td style="text-align:center"> float </td><td style="text-align:left"> A constant that represent \(\pi\) </td></tr>
|
|
<tr><td style="text-align:left"> <strong class="asterisk">HALF_PI</strong> </td><td style="text-align:center"> float </td><td style="text-align:left"> A constant that represent \(\frac{\pi}{2}\) </td></tr>
|
|
<tr><td style="text-align:left"> <strong class="asterisk">saturate(float x)</strong> </td><td style="text-align:center"> float </td><td style="text-align:left"> Clamps the specified value between 0.0 and 1.0 </td></tr>
|
|
<tr><td style="text-align:left"> <strong class="asterisk">pow5(float x)</strong> </td><td style="text-align:center"> float </td><td style="text-align:left"> Computes \(x^5\) </td></tr>
|
|
<tr><td style="text-align:left"> <strong class="asterisk">sq(float x)</strong> </td><td style="text-align:center"> float </td><td style="text-align:left"> Computes \(x^2\) </td></tr>
|
|
<tr><td style="text-align:left"> <strong class="asterisk">max3(float3 v)</strong> </td><td style="text-align:center"> float </td><td style="text-align:left"> Returns the maximum value of the specified <code>float3</code> </td></tr>
|
|
<tr><td style="text-align:left"> <strong class="asterisk">mulMat4×4Float3(float4×4 m, float3 v)</strong> </td><td style="text-align:center"> float4 </td><td style="text-align:left"> Returns \(m * v\) </td></tr>
|
|
<tr><td style="text-align:left"> <strong class="asterisk">mulMat3×3Float3(float4×4 m, float3 v)</strong> </td><td style="text-align:center"> float4 </td><td style="text-align:left"> Returns \(m * v\) </td></tr>
|
|
</tbody></table></div>
|
|
|
|
<p></p>
|
|
<a class="target" name="matrices"> </a><a class="target" name="materialdefinitions/shaderpublicapis/matrices"> </a><a class="target" name="toc4.5.3"> </a><h3>Matrices</h3>
|
|
<p>
|
|
|
|
</p><div class="table"><table class="table"><tbody><tr><th style="text-align:left"> Name </th><th style="text-align:center"> Type </th><th style="text-align:left"> Description </th></tr>
|
|
<tr><td style="text-align:left"> <strong class="asterisk">getViewFromWorldMatrix()</strong> </td><td style="text-align:center"> float4×4 </td><td style="text-align:left"> Matrix that converts from world space to view/eye space </td></tr>
|
|
<tr><td style="text-align:left"> <strong class="asterisk">getWorldFromViewMatrix()</strong> </td><td style="text-align:center"> float4×4 </td><td style="text-align:left"> Matrix that converts from view/eye space to world space </td></tr>
|
|
<tr><td style="text-align:left"> <strong class="asterisk">getClipFromViewMatrix()</strong> </td><td style="text-align:center"> float4×4 </td><td style="text-align:left"> Matrix that converts from view/eye space to clip (NDC) space </td></tr>
|
|
<tr><td style="text-align:left"> <strong class="asterisk">getViewFromClipMatrix()</strong> </td><td style="text-align:center"> float4×4 </td><td style="text-align:left"> Matrix that converts from clip (NDC) space to view/eye space </td></tr>
|
|
<tr><td style="text-align:left"> <strong class="asterisk">getClipFromWorldMatrix()</strong> </td><td style="text-align:center"> float4×4 </td><td style="text-align:left"> Matrix that converts from world to clip (NDC) space </td></tr>
|
|
<tr><td style="text-align:left"> <strong class="asterisk">getWorldFromClipMatrix()</strong> </td><td style="text-align:center"> float4×4 </td><td style="text-align:left"> Matrix that converts from clip (NDC) space to world space </td></tr>
|
|
</tbody></table></div>
|
|
|
|
<p></p>
|
|
<a class="target" name="frameconstants"> </a><a class="target" name="materialdefinitions/shaderpublicapis/frameconstants"> </a><a class="target" name="toc4.5.4"> </a><h3>Frame constants</h3>
|
|
<p>
|
|
|
|
</p><div class="table"><table class="table"><tbody><tr><th style="text-align:left"> Name </th><th style="text-align:center"> Type </th><th style="text-align:left"> Description </th></tr>
|
|
<tr><td style="text-align:left"> <strong class="asterisk">getResolution()</strong> </td><td style="text-align:center"> float4 </td><td style="text-align:left"> Resolution of the view in pixels: <code>width</code>, <code>height</code>, <code>1 / width</code>, <code>1 / height</code> </td></tr>
|
|
<tr><td style="text-align:left"> <strong class="asterisk">getWorldCameraPosition()</strong> </td><td style="text-align:center"> float3 </td><td style="text-align:left"> Position of the camera/eye in world space </td></tr>
|
|
<tr><td style="text-align:left"> <strong class="asterisk">getWorldOffset()</strong> </td><td style="text-align:center"> float3 </td><td style="text-align:left"> The shift required to obtain API-level world space </td></tr>
|
|
<tr><td style="text-align:left"> <strong class="asterisk">getTime()</strong> </td><td style="text-align:center"> float </td><td style="text-align:left"> Current time in seconds, may be reset regularly to avoid precision loss </td></tr>
|
|
<tr><td style="text-align:left"> <strong class="asterisk">getUserTime()</strong> </td><td style="text-align:center"> float4 </td><td style="text-align:left"> Current time in seconds: <code>time</code>, <code>(double)time - time</code>, <code>0</code>, <code>0</code> </td></tr>
|
|
<tr><td style="text-align:left"> <strong class="asterisk">getUserTimeMode(float m)</strong> </td><td style="text-align:center"> float </td><td style="text-align:left"> Current time modulo m in seconds </td></tr>
|
|
<tr><td style="text-align:left"> <strong class="asterisk">getExposure()</strong> </td><td style="text-align:center"> float </td><td style="text-align:left"> Photometric exposure of the camera </td></tr>
|
|
<tr><td style="text-align:left"> <strong class="asterisk">getEV100()</strong> </td><td style="text-align:center"> float </td><td style="text-align:left"> <a href="https://en.wikipedia.org/wiki/Exposure_value">Exposure value at ISO 100</a> of the camera </td></tr>
|
|
</tbody></table></div>
|
|
|
|
<p></p><p>
|
|
|
|
</p><div class="admonition tip"><div class="admonition-title"> world space</div>
|
|
|
|
<p></p><p>
|
|
|
|
To achieve good precision, the “world space” in Filament's shading system does not necessarily
|
|
match the API-level world space. To obtain the position of the API-level camera, custom
|
|
materials can add <code>getWorldOffset()</code> to <code>getWorldCameraPosition()</code>.</p></div>
|
|
|
|
<p></p>
|
|
<a class="target" name="vertexonly"> </a><a class="target" name="materialdefinitions/shaderpublicapis/vertexonly"> </a><a class="target" name="toc4.5.5"> </a><h3>Vertex only</h3>
|
|
<p>
|
|
|
|
|
|
The following APIs are only available from the vertex block:
|
|
</p><div class="table"><table class="table"><tbody><tr><th style="text-align:left"> Name </th><th style="text-align:center"> Type </th><th style="text-align:left"> Description </th></tr>
|
|
<tr><td style="text-align:left"> <strong class="asterisk">getPosition()</strong> </td><td style="text-align:center"> float4 </td><td style="text-align:left"> Vertex position in the domain defined by the material (default: object/model space) </td></tr>
|
|
<tr><td style="text-align:left"> <strong class="asterisk">getCustom0()</strong> to <strong class="asterisk">getCustom7()</strong> </td><td style="text-align:center"> float4 </td><td style="text-align:left"> Custom vertex attribute </td></tr>
|
|
<tr><td style="text-align:left"> <strong class="asterisk">getWorldFromModelMatrix()</strong> </td><td style="text-align:center"> float4×4 </td><td style="text-align:left"> Matrix that converts from model (object) space to world space </td></tr>
|
|
<tr><td style="text-align:left"> <strong class="asterisk">getWorldFromModelNormalMatrix()</strong> </td><td style="text-align:center"> float3×3 </td><td style="text-align:left"> Matrix that converts normals from model (object) space to world space </td></tr>
|
|
</tbody></table></div>
|
|
|
|
<p></p>
|
|
<a class="target" name="fragmentonly"> </a><a class="target" name="materialdefinitions/shaderpublicapis/fragmentonly"> </a><a class="target" name="toc4.5.6"> </a><h3>Fragment only</h3>
|
|
<p>
|
|
|
|
|
|
The following APIs are only available from the fragment block:
|
|
</p><div class="table"><table class="table"><tbody><tr><th style="text-align:left"> Name </th><th style="text-align:center"> Type </th><th style="text-align:left"> Description </th></tr>
|
|
<tr><td style="text-align:left"> <strong class="asterisk">getWorldTangentFrame()</strong> </td><td style="text-align:center"> float3×3 </td><td style="text-align:left"> Matrix containing in each column the <code>tangent</code> (<code>frame[0]</code>), <code>bi-tangent</code> (<code>frame[1]</code>) and <code>normal</code> (<code>frame[2]</code>) of the vertex in world space. If the material does not compute a tangent space normal for bump mapping or if the shading is not anisotropic, only the <code>normal</code> is valid in this matrix. </td></tr>
|
|
<tr><td style="text-align:left"> <strong class="asterisk">getWorldPosition()</strong> </td><td style="text-align:center"> float3 </td><td style="text-align:left"> Position of the fragment in world space (see note below about world-space) </td></tr>
|
|
<tr><td style="text-align:left"> <strong class="asterisk">getWorldViewVector()</strong> </td><td style="text-align:center"> float3 </td><td style="text-align:left"> Normalized vector in world space from the fragment position to the eye </td></tr>
|
|
<tr><td style="text-align:left"> <strong class="asterisk">getWorldNormalVector()</strong> </td><td style="text-align:center"> float3 </td><td style="text-align:left"> Normalized normal in world space, after bump mapping (must be used after <code>prepareMaterial()</code>) </td></tr>
|
|
<tr><td style="text-align:left"> <strong class="asterisk">getWorldGeometricNormalVector()</strong> </td><td style="text-align:center"> float3 </td><td style="text-align:left"> Normalized normal in world space, before bump mapping (can be used before <code>prepareMaterial()</code>) </td></tr>
|
|
<tr><td style="text-align:left"> <strong class="asterisk">getWorldReflectedVector()</strong> </td><td style="text-align:center"> float3 </td><td style="text-align:left"> Reflection of the view vector about the normal (must be used after <code>prepareMaterial()</code>) </td></tr>
|
|
<tr><td style="text-align:left"> <strong class="asterisk">getNdotV()</strong> </td><td style="text-align:center"> float </td><td style="text-align:left"> The result of <code>dot(normal, view)</code>, always strictly greater than 0 (must be used after <code>prepareMaterial()</code>) </td></tr>
|
|
<tr><td style="text-align:left"> <strong class="asterisk">getColor()</strong> </td><td style="text-align:center"> float4 </td><td style="text-align:left"> Interpolated color of the fragment, if the color attribute is required </td></tr>
|
|
<tr><td style="text-align:left"> <strong class="asterisk">getUV0()</strong> </td><td style="text-align:center"> float2 </td><td style="text-align:left"> First interpolated set of UV coordinates, only available if the uv0 attribute is required </td></tr>
|
|
<tr><td style="text-align:left"> <strong class="asterisk">getUV1()</strong> </td><td style="text-align:center"> float2 </td><td style="text-align:left"> First interpolated set of UV coordinates, only available if the uv1 attribute is required </td></tr>
|
|
<tr><td style="text-align:left"> <strong class="asterisk">getMaskThreshold()</strong> </td><td style="text-align:center"> float </td><td style="text-align:left"> Returns the mask threshold, only available when <code>blending</code> is set to <code>masked</code> </td></tr>
|
|
<tr><td style="text-align:left"> <strong class="asterisk">inverseTonemap(float3)</strong> </td><td style="text-align:center"> float3 </td><td style="text-align:left"> Applies the inverse tone mapping operator to the specified linear sRGB color and returns a linear sRGB color. This operation may be an approximation </td></tr>
|
|
<tr><td style="text-align:left"> <strong class="asterisk">inverseTonemapSRGB(float3)</strong> </td><td style="text-align:center"> float3 </td><td style="text-align:left"> Applies the inverse tone mapping operator to the specified non-linear sRGB color and returns a linear sRGB color. This operation may be an approximation </td></tr>
|
|
<tr><td style="text-align:left"> <strong class="asterisk">luminance(float3)</strong> </td><td style="text-align:center"> float </td><td style="text-align:left"> Computes the luminance of the specified linear sRGB color </td></tr>
|
|
<tr><td style="text-align:left"> <strong class="asterisk">ycbcrToRgb(float, float2)</strong> </td><td style="text-align:center"> float3 </td><td style="text-align:left"> Converts a luminance and CbCr pair to a sRGB color </td></tr>
|
|
<tr><td style="text-align:left"> <strong class="asterisk">uvToRenderTargetUV(float2)</strong> </td><td style="text-align:center"> float2 </td><td style="text-align:left"> Transforms a UV coordinate to allow sampling from a <code>RenderTarget</code> attachment </td></tr>
|
|
</tbody></table></div>
|
|
|
|
<p></p><p>
|
|
|
|
</p><div class="admonition tip"><div class="admonition-title"> world space</div>
|
|
|
|
<p></p><p>
|
|
|
|
To obtain API-level world space coordinates, custom materials should add <code>getWorldOffset()</code> to
|
|
<code>getWorldPosition()</code> (et al).</p></div>
|
|
|
|
<p></p><p>
|
|
|
|
</p><div class="admonition tip"><div class="admonition-title"> sampling from render targets</div>
|
|
|
|
<p></p><p>
|
|
|
|
When sampling from a <code>filament::Texture</code> that is attached to a <code>filament::RenderTarget</code> for
|
|
materials in the surface domain, please use <code>uvToRenderTargetUV</code> to transform the texture
|
|
coordinate. This will flip the coordinate depending on which backend is being used.</p></div>
|
|
|
|
<p></p>
|
|
<a class="target" name="compilingmaterials"> </a><a class="target" name="compilingmaterials"> </a><a class="target" name="toc5"> </a><h1>Compiling materials</h1>
|
|
<p>
|
|
|
|
|
|
Material packages can be compiled from material definitions using the command line tool called
|
|
<code>matc</code>. The simplest way to use <code>matc</code> is to specify an input material definition (<code>car_paint.mat</code>
|
|
in the example below) and an output material package (<code>car_paint.filamat</code> in the example below):
|
|
|
|
</p><pre class="listing backtick"><code><span class="line">$ matc -o ./materials/bin/car_paint.filamat ./materials/src/car_paint.mat</span></code></pre>
|
|
<a class="target" name="shadervalidation"> </a><a class="target" name="compilingmaterials/shadervalidation"> </a><a class="target" name="toc5.1"> </a><h2>Shader validation</h2>
|
|
<p>
|
|
|
|
|
|
<code>matc</code> attempts to validate shaders when compiling a material package. The example below shows an
|
|
example of an error message generated when compiling a material definition containing a typo in the
|
|
fragment shader (<code>metalic</code> instead of <code>metallic</code>). The reported line numbers are line numbers in the
|
|
source material definition file.
|
|
|
|
</p><pre class="listing backtick"><code><span class="line">ERROR: 0:13: 'metalic' : no such field in structure</span>
|
|
<span class="line">ERROR: 0:13: '' : compilation terminated</span>
|
|
<span class="line">ERROR: 2 compilation errors. No code generated.</span>
|
|
<span class="line"></span>
|
|
<span class="line">Could not compile material metal.mat</span></code></pre>
|
|
<a class="target" name="flags"> </a><a class="target" name="compilingmaterials/flags"> </a><a class="target" name="toc5.2"> </a><h2>Flags</h2>
|
|
<p>
|
|
|
|
|
|
The command line flags relevant to application development are described in <a href="#table_matcflags">table 14</a>.
|
|
</p><div class="table">
|
|
<table class="table"><tbody><tr><th style="text-align:right"> Flag </th><th style="text-align:center"> Value </th><th style="text-align:left"> Usage </th></tr>
|
|
<tr><td style="text-align:right"> <strong class="asterisk">-o</strong>, <strong class="asterisk">—output</strong> </td><td style="text-align:center"> [path] </td><td style="text-align:left"> Specify the output file path </td></tr>
|
|
<tr><td style="text-align:right"> <strong class="asterisk">-p</strong>, <strong class="asterisk">—platform</strong> </td><td style="text-align:center"> desktop/mobile/all </td><td style="text-align:left"> Select the target platform(s) </td></tr>
|
|
<tr><td style="text-align:right"> <strong class="asterisk">-a</strong>, <strong class="asterisk">—api</strong> </td><td style="text-align:center"> opengl/vulkan/all </td><td style="text-align:left"> Specify the target graphics API </td></tr>
|
|
<tr><td style="text-align:right"> <strong class="asterisk">-S</strong>, <strong class="asterisk">—optimize-size</strong> </td><td style="text-align:center"> N/A </td><td style="text-align:left"> Optimize compiled material for size instead of just performance </td></tr>
|
|
<tr><td style="text-align:right"> <strong class="asterisk">-r</strong>, <strong class="asterisk">—reflect</strong> </td><td style="text-align:center"> parameters </td><td style="text-align:left"> Outputs the specified metadata as JSON </td></tr>
|
|
<tr><td style="text-align:right"> <strong class="asterisk">-v</strong>, <strong class="asterisk">—variant-filter</strong> </td><td style="text-align:center"> [variant] </td><td style="text-align:left"> Filters out the specified, comma-separated variants </td></tr>
|
|
</tbody></table><div class="tablecaption"><a class="target" name="table_matcflags"> </a><b style="font-style:normal;">Table 14:</b> List of <code>matc</code> flags</div></div>
|
|
|
|
<p></p><p>
|
|
|
|
<code>matc</code> offers a few other flags that are irrelevant to application developers and for internal
|
|
use only.
|
|
|
|
</p>
|
|
<a class="target" name="--platform"> </a><a class="target" name="compilingmaterials/flags/—platform"> </a><a class="target" name="toc5.2.1"> </a><h3>—platform</h3>
|
|
<p>
|
|
|
|
|
|
By default, <code>matc</code> generates material packages containing shaders for all supported platforms. If
|
|
you wish to reduce the size of your material packages, it is recommended to select only the
|
|
appropriate target platform. For instance, to compile a material package for Android only, run
|
|
the following command:
|
|
|
|
</p><pre class="listing backtick"><code><span class="line">$ matc -p mobile -o ./materials/bin/car_paint.filamat ./materials/src/car_paint.mat</span></code></pre>
|
|
<a class="target" name="--api"> </a><a class="target" name="compilingmaterials/flags/—api"> </a><a class="target" name="toc5.2.2"> </a><h3>—api</h3>
|
|
<p>
|
|
|
|
|
|
By default, <code>matc</code> generates material packages containing shaders for the OpenGL API. You can choose
|
|
to generate shaders for the Vulkan API in addition to the OpenGL shaders. If you intend on targeting
|
|
only Vulkan capable devices, you can reduce the size of the material packages by generating only
|
|
the set of Vulkan shaders:
|
|
|
|
</p><pre class="listing backtick"><code><span class="line">$ matc -a vulkan -o ./materials/bin/car_paint.filamat ./materials/src/car_paint.mat</span></code></pre>
|
|
<a class="target" name="--optimize-size"> </a><a class="target" name="compilingmaterials/flags/—optimize-size"> </a><a class="target" name="toc5.2.3"> </a><h3>—optimize-size</h3>
|
|
<p>
|
|
|
|
|
|
This flag applies fewer optimization techniques to try and keep the final material as small as
|
|
possible. If the compiled material is deemed too large by default, using this flag might be
|
|
a good compromise between runtime performance and size.
|
|
|
|
</p>
|
|
<a class="target" name="--reflect"> </a><a class="target" name="compilingmaterials/flags/—reflect"> </a><a class="target" name="toc5.2.4"> </a><h3>—reflect</h3>
|
|
<p>
|
|
|
|
|
|
This flag was designed to help build tools around <code>matc</code>. It allows you to print out specific
|
|
metadata in JSON format. The example below prints out the list of parameters defined in Filament's
|
|
standard skybox material. It produces a list of 2 parameters, named <code>showSun</code> and <code>skybox</code>,
|
|
respectively a boolean and a cubemap texture.
|
|
|
|
</p><pre class="listing backtick"><code><span class="line">$ matc --reflect parameters filament/src/materials/skybox.mat </span>
|
|
<span class="line">{</span>
|
|
<span class="line"> "parameters": [</span>
|
|
<span class="line"> {</span>
|
|
<span class="line"> "name": "showSun",</span>
|
|
<span class="line"> "type": "bool",</span>
|
|
<span class="line"> "size": "1"</span>
|
|
<span class="line"> },</span>
|
|
<span class="line"> {</span>
|
|
<span class="line"> "name": "skybox",</span>
|
|
<span class="line"> "type": "samplerCubemap",</span>
|
|
<span class="line"> "format": "float",</span>
|
|
<span class="line"> "precision": "default"</span>
|
|
<span class="line"> }</span>
|
|
<span class="line"> ]</span>
|
|
<span class="line">}</span></code></pre>
|
|
<a class="target" name="--variant-filter"> </a><a class="target" name="compilingmaterials/flags/—variant-filter"> </a><a class="target" name="toc5.2.5"> </a><h3>—variant-filter</h3>
|
|
<p>
|
|
|
|
|
|
This flag can be used to further reduce the size of a compiled material. It is used to specify a
|
|
list of shader variants that the application guarantees will never be needed. These shader variants
|
|
are skipped during the code generation phase of <code>matc</code>, thus reducing the overall size of the
|
|
material.
|
|
|
|
</p><p>
|
|
|
|
The variants must be specified as a comma-separated list, using one of the following available
|
|
variants:
|
|
|
|
</p><p>
|
|
|
|
</p><ul>
|
|
<li class="minus"><code>directionalLighting</code>, used when a directional light is present in the scene
|
|
</li>
|
|
<li class="minus"><code>dynamicLighting</code>, used when a non-directional light (point, spot, etc.) is present in the scene
|
|
</li>
|
|
<li class="minus"><code>shadowReceiver</code>, used when an object can receive shadows
|
|
</li>
|
|
<li class="minus"><code>skinning</code>, used when an object is animated using GPU skinning or vertex morphing</li></ul>
|
|
|
|
<p></p><p>
|
|
|
|
Example:
|
|
</p><pre class="listing backtick"><code><span class="line"><span class="hljs-comment">--variant-filter=skinning,shadowReceiver</span></span></code></pre><p>
|
|
|
|
Note that some variants may automatically be filtered out. For instance, all lighting related
|
|
variants (<code>directionalLighting</code>, etc.) are filtered out when compiling an <code>unlit</code> material.
|
|
|
|
</p><p>
|
|
|
|
When this flag is used, the specified variant filters are merged with the variant filters specified
|
|
in the material itself.
|
|
|
|
</p><p>
|
|
|
|
Use this flag with caution, filtering out a variant required at runtime may lead to crashes.
|
|
|
|
</p>
|
|
<a class="target" name="handlingcolors"> </a><a class="target" name="handlingcolors"> </a><a class="target" name="toc6"> </a><h1>Handling colors</h1>
|
|
|
|
<a class="target" name="linearcolors"> </a><a class="target" name="handlingcolors/linearcolors"> </a><a class="target" name="toc6.1"> </a><h2>Linear colors</h2>
|
|
<p>
|
|
|
|
|
|
If the color data comes from a texture, simply make sure you use an sRGB texture to benefit from
|
|
automatic hardware conversion from sRGB to linear. If the color data is passed as a parameter to
|
|
the material you can convert from sRGB to linear by running the following algorithm on each
|
|
color channel:
|
|
|
|
</p><pre class="listing tilde"><code><span class="line"><span class="hljs-type">float</span> sRGB_to_linear(<span class="hljs-type">float</span> color) {</span>
|
|
<span class="line"> <span class="hljs-keyword">return</span> color <= <span class="hljs-number">0.04045</span> ? color / <span class="hljs-number">12.92</span> : <span class="hljs-built_in">pow</span>((color + <span class="hljs-number">0.055</span>) / <span class="hljs-number">1.055</span>, <span class="hljs-number">2.4</span>);</span>
|
|
<span class="line">}</span></code></pre><p>
|
|
|
|
Alternatively you can use one of the two cheaper but less accurate versions shown below:
|
|
|
|
</p><pre class="listing tilde"><code><span class="line"><span class="hljs-comment">// Cheaper</span></span>
|
|
<span class="line">linearColor = <span class="hljs-built_in">pow</span>(color, <span class="hljs-number">2.2</span>);</span>
|
|
<span class="line"><span class="hljs-comment">// Cheapest</span></span>
|
|
<span class="line">linearColor = color * color;</span></code></pre>
|
|
<a class="target" name="pre-multipliedalpha"> </a><a class="target" name="handlingcolors/pre-multipliedalpha"> </a><a class="target" name="toc6.2"> </a><h2>Pre-multiplied alpha</h2>
|
|
<p>
|
|
|
|
|
|
A color uses pre-multiplied alpha if its RGB components are multiplied by the alpha channel:
|
|
|
|
</p><pre class="listing tilde"><code><span class="line"><span class="hljs-comment">// Compute pre-multiplied color</span></span>
|
|
<span class="line">color.rgb *= color.a;</span></code></pre><p>
|
|
|
|
If the color is sampled from a texture, you can simply ensure that the texture data is
|
|
pre-multiplied ahead of time. On Android, any texture uploaded from a
|
|
<a href="https://developer.android.com/reference/android/graphics/Bitmap.html">Bitmap</a> will be
|
|
pre-multiplied by default.
|
|
|
|
</p><p>
|
|
|
|
</p></span><div class="markdeepFooter"><i>formatted by <a href="http://casual-effects.com/markdeep" style="color:#999">Markdeep 1.03  </a></i><div style="display:inline-block;font-size:13px;font-family:'Times New Roman',serif;vertical-align:middle;transform:translate(-3px,-1px)rotate(135deg);">✒</div></div><script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script><script>window.alreadyProcessedMarkdeep||(document.body.style.visibility="visible")</script>
|
|
</body></html> |