3164 lines
238 KiB
HTML
3164 lines
238 KiB
HTML
<html><head><meta charset="utf-8">
|
||
|
||
<style>img { max-width: 100%; }</style>
|
||
|
||
</head><body id="md" style="visibility: visible;"><meta charset="UTF-8"><meta http-equiv="content-type" content="text/html;charset=UTF-8"><meta name="viewport" content="width=600, initial-scale=1"><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>@media print{*{-webkit-print-color-adjust:exact;text-shadow:none !important}}body{counter-reset: h1 paragraph line item list-item}@page{margin:0;size:auto}#mdContextMenu{position:absolute;background:#383838;cursor:default;border:1px solid #999;color:#fff;padding:4px 0px;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Oxygen,Ubuntu,"Helvetica Neue",sans-serif;font-size:85%;font-weight:600;border-radius:4px;box-shadow:0px 3px 10px rgba(0,0,0,35%)}#mdContextMenu div{padding:0px 20px}#mdContextMenu div:hover{background:#1659d1}.md code,.md pre{font-family:Menlo,Consolas,monospace;font-size:85%;text-align:left;line-height:140%}.md .mediumToc code,.md longToc code,.md .shortToc code,.md h1 code,.md h2 code,.md h3 code,.md h4 code,.md h5 code,.md h6 code{font-size:unset}.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 iframe.textinsert, .md object.textinsert,.md iframe:not(.markdeep){display:block;margin-top:10px;margin-bottom:10px;width:100%;height:75vh;border:1px solid #000;border-radius:4px;background:#f5f5f4}.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 {width:100%;tab-size:4;-moz-tab-size:4;-o-tab-size:4;counter-reset:line;overflow-x:auto;resize:horizontal}.md pre.listing .linenumbers span.line:before{width:30px;margin-left:-28px;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 .imagecaption,.md .tablecaption,.md .listingcaption{display:inline-block;margin:7px 5px 12px;text-align:justify;font-style:italic}.md img.pixel{image-rendering:-moz-crisp-edges;image-rendering:pixelated}.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,.md h1,.md h2,.md h3,.md h4,.md h5,.md 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 .tocTop {display:none}.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:85%;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 .shadeddot{fill:#CCC}.md svg.diagram .dotteddot{stroke:#000;stroke-dasharray:4;fill:none}.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:Verdana,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:Verdana,Helvetica,Arial,sans-serif}.md table.calendar th{font-size:16px}.md .today{background:#ECF8FA}.md .calendar .parenthesized{color:#999;font-style:italic}.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{page-break-inside:avoid;} @media print{.md .listing code{white-space:pre-wrap}}.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="#" class="tocTop">(Top)</a><br>
|
||
<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/sheencolor" class="level3"><span class="tocNumber">3.1.8 </span>Sheen color</a><br>
|
||
<a href="#materialmodels/litmodel/sheenroughness" class="level3"><span class="tocNumber">3.1.9 </span>Sheen roughness</a><br>
|
||
<a href="#materialmodels/litmodel/clearcoat" class="level3"><span class="tocNumber">3.1.10 </span>Clear coat</a><br>
|
||
<a href="#materialmodels/litmodel/clearcoatroughness" class="level3"><span class="tocNumber">3.1.11 </span>Clear coat roughness</a><br>
|
||
<a href="#materialmodels/litmodel/anisotropy" class="level3"><span class="tocNumber">3.1.12 </span>Anisotropy</a><br>
|
||
<a href="#materialmodels/litmodel/anisotropydirection" class="level3"><span class="tocNumber">3.1.13 </span>Anisotropy direction</a><br>
|
||
<a href="#materialmodels/litmodel/ambientocclusion" class="level3"><span class="tocNumber">3.1.14 </span>Ambient occlusion</a><br>
|
||
<a href="#materialmodels/litmodel/normal" class="level3"><span class="tocNumber">3.1.15 </span>Normal</a><br>
|
||
<a href="#materialmodels/litmodel/bentnormal" class="level3"><span class="tocNumber">3.1.16 </span>Bent normal</a><br>
|
||
<a href="#materialmodels/litmodel/clearcoatnormal" class="level3"><span class="tocNumber">3.1.17 </span>Clear coat normal</a><br>
|
||
<a href="#materialmodels/litmodel/emissive" class="level3"><span class="tocNumber">3.1.18 </span>Emissive</a><br>
|
||
<a href="#materialmodels/litmodel/post-lightingcolor" class="level3"><span class="tocNumber">3.1.19 </span>Post-lighting color</a><br>
|
||
<a href="#materialmodels/litmodel/indexofrefraction" class="level3"><span class="tocNumber">3.1.20 </span>Index of refraction</a><br>
|
||
<a href="#materialmodels/litmodel/transmission" class="level3"><span class="tocNumber">3.1.21 </span>Transmission</a><br>
|
||
<a href="#materialmodels/litmodel/absorption" class="level3"><span class="tocNumber">3.1.22 </span>Absorption</a><br>
|
||
<a href="#materialmodels/litmodel/micro-thicknessandthickness" class="level3"><span class="tocNumber">3.1.23 </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:featurelevel" class="level3"><span class="tocNumber">4.2.2 </span>General: featureLevel</a><br>
|
||
<a href="#materialdefinitions/materialblock/general:shadingmodel" class="level3"><span class="tocNumber">4.2.3 </span>General: shadingModel</a><br>
|
||
<a href="#materialdefinitions/materialblock/general:parameters" class="level3"><span class="tocNumber">4.2.4 </span>General: parameters</a><br>
|
||
<a href="#materialdefinitions/materialblock/general:constants" class="level3"><span class="tocNumber">4.2.5 </span>General: constants</a><br>
|
||
<a href="#materialdefinitions/materialblock/general:variantfilter" class="level3"><span class="tocNumber">4.2.6 </span>General: variantFilter</a><br>
|
||
<a href="#materialdefinitions/materialblock/general:flipuv" class="level3"><span class="tocNumber">4.2.7 </span>General: flipUV</a><br>
|
||
<a href="#materialdefinitions/materialblock/general:quality" class="level3"><span class="tocNumber">4.2.8 </span>General: quality</a><br>
|
||
<a href="#materialdefinitions/materialblock/general:instanced" class="level3"><span class="tocNumber">4.2.9 </span>General: instanced</a><br>
|
||
<a href="#materialdefinitions/materialblock/general:vertexdomaindevicejittered" class="level3"><span class="tocNumber">4.2.10 </span>General: vertexDomainDeviceJittered</a><br>
|
||
<a href="#materialdefinitions/materialblock/vertexandattributes:requires" class="level3"><span class="tocNumber">4.2.11 </span>Vertex and attributes: requires</a><br>
|
||
<a href="#materialdefinitions/materialblock/vertexandattributes:variables" class="level3"><span class="tocNumber">4.2.12 </span>Vertex and attributes: variables</a><br>
|
||
<a href="#materialdefinitions/materialblock/vertexandattributes:vertexdomain" class="level3"><span class="tocNumber">4.2.13 </span>Vertex and attributes: vertexDomain</a><br>
|
||
<a href="#materialdefinitions/materialblock/vertexandattributes:interpolation" class="level3"><span class="tocNumber">4.2.14 </span>Vertex and attributes: interpolation</a><br>
|
||
<a href="#materialdefinitions/materialblock/blendingandtransparency:blending" class="level3"><span class="tocNumber">4.2.15 </span>Blending and transparency: blending</a><br>
|
||
<a href="#materialdefinitions/materialblock/blendingandtransparency:blendfunction" class="level3"><span class="tocNumber">4.2.16 </span>Blending and transparency: blendFunction</a><br>
|
||
<a href="#materialdefinitions/materialblock/blendingandtransparency:postlightingblending" class="level3"><span class="tocNumber">4.2.17 </span>Blending and transparency: postLightingBlending</a><br>
|
||
<a href="#materialdefinitions/materialblock/blendingandtransparency:transparency" class="level3"><span class="tocNumber">4.2.18 </span>Blending and transparency: transparency</a><br>
|
||
<a href="#materialdefinitions/materialblock/blendingandtransparency:maskthreshold" class="level3"><span class="tocNumber">4.2.19 </span>Blending and transparency: maskThreshold</a><br>
|
||
<a href="#materialdefinitions/materialblock/blendingandtransparency:refractionmode" class="level3"><span class="tocNumber">4.2.20 </span>Blending and transparency: refractionMode</a><br>
|
||
<a href="#materialdefinitions/materialblock/blendingandtransparency:refractiontype" class="level3"><span class="tocNumber">4.2.21 </span>Blending and transparency: refractionType</a><br>
|
||
<a href="#materialdefinitions/materialblock/rasterization:culling" class="level3"><span class="tocNumber">4.2.22 </span>Rasterization: culling</a><br>
|
||
<a href="#materialdefinitions/materialblock/rasterization:colorwrite" class="level3"><span class="tocNumber">4.2.23 </span>Rasterization: colorWrite</a><br>
|
||
<a href="#materialdefinitions/materialblock/rasterization:depthwrite" class="level3"><span class="tocNumber">4.2.24 </span>Rasterization: depthWrite</a><br>
|
||
<a href="#materialdefinitions/materialblock/rasterization:depthculling" class="level3"><span class="tocNumber">4.2.25 </span>Rasterization: depthCulling</a><br>
|
||
<a href="#materialdefinitions/materialblock/rasterization:doublesided" class="level3"><span class="tocNumber">4.2.26 </span>Rasterization: doubleSided</a><br>
|
||
<a href="#materialdefinitions/materialblock/rasterization:alphatocoverage" class="level3"><span class="tocNumber">4.2.27 </span>Rasterization: alphaToCoverage</a><br>
|
||
<a href="#materialdefinitions/materialblock/lighting:reflections" class="level3"><span class="tocNumber">4.2.28 </span>Lighting: reflections</a><br>
|
||
<a href="#materialdefinitions/materialblock/lighting:shadowmultiplier" class="level3"><span class="tocNumber">4.2.29 </span>Lighting: shadowMultiplier</a><br>
|
||
<a href="#materialdefinitions/materialblock/lighting:transparentshadow" class="level3"><span class="tocNumber">4.2.30 </span>Lighting: transparentShadow</a><br>
|
||
<a href="#materialdefinitions/materialblock/lighting:clearcoatiorchange" class="level3"><span class="tocNumber">4.2.31 </span>Lighting: clearCoatIorChange</a><br>
|
||
<a href="#materialdefinitions/materialblock/lighting:multibounceambientocclusion" class="level3"><span class="tocNumber">4.2.32 </span>Lighting: multiBounceAmbientOcclusion</a><br>
|
||
<a href="#materialdefinitions/materialblock/lighting:specularambientocclusion" class="level3"><span class="tocNumber">4.2.33 </span>Lighting: specularAmbientOcclusion</a><br>
|
||
<a href="#materialdefinitions/materialblock/anti-aliasing:specularantialiasing" class="level3"><span class="tocNumber">4.2.34 </span>Anti-aliasing: specularAntiAliasing</a><br>
|
||
<a href="#materialdefinitions/materialblock/anti-aliasing:specularantialiasingvariance" class="level3"><span class="tocNumber">4.2.35 </span>Anti-aliasing: specularAntiAliasingVariance</a><br>
|
||
<a href="#materialdefinitions/materialblock/anti-aliasing:specularantialiasingthreshold" class="level3"><span class="tocNumber">4.2.36 </span>Anti-aliasing: specularAntiAliasingThreshold</a><br>
|
||
<a href="#materialdefinitions/materialblock/shading:customsurfaceshading" class="level3"><span class="tocNumber">4.2.37 </span>Shading: customSurfaceShading</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/vertexblock/customvertexattributes" class="level3"><span class="tocNumber">4.3.2 </span>Custom vertex attributes</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/fragmentblock/customsurfaceshading" class="level3"><span class="tocNumber">4.4.3 </span>Custom surface shading</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/materialglobals" class="level3"><span class="tocNumber">4.5.5 </span>Material globals</a><br>
|
||
<a href="#materialdefinitions/shaderpublicapis/vertexonly" class="level3"><span class="tocNumber">4.5.6 </span>Vertex only</a><br>
|
||
<a href="#materialdefinitions/shaderpublicapis/fragmentonly" class="level3"><span class="tocNumber">4.5.7 </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>
|
||
<a href="#samplerusageinmaterials" class="level1"><span class="tocNumber">7 </span>Sampler usage in Materials</a><br>
|
||
<a href="#samplerusageinmaterials/featurelevel1and2" class="level2"><span class="tocNumber">7.1 </span>Feature level 1 and 2</a><br>
|
||
<a href="#samplerusageinmaterials/featurelevel3" class="level2"><span class="tocNumber">7.2 </span>Feature level 3</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">@darthmoosious</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 many 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">sheenColor</strong> </td><td style="text-align:left"> Strength of the sheen layer </td></tr>
|
||
<tr><td style="text-align:right"> <strong class="asterisk">sheenRoughness</strong> </td><td style="text-align:left"> Perceived smoothness or roughness of the sheen layer </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 in tangent space </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, either for refractive objects or as an alternative to reflectance </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><center><div class="tablecaption"><a class="target" name="table_standardproperties"> </a><b style="font-style:normal;">Table 1:</b> Properties of the standard model</div></center></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">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">sheenRoughness</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">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..n], a=[0..1] </td><td style="text-align:left"> Linear RGB intensity in nits, alpha encodes the exposure weight </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><center><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></center></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><center><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></center></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><center><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></center></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><center><span 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)</span></center></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><center><span 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)</span></center></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><center><span 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)</span></center></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><center><span 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)</span></center></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><center><span 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)</span></center></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><center><span class="imagecaption"><a class="target" name="figure_reflectance"> </a><b style="font-style:normal;">Figure 6:</b> Common reflectance values</span></center></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><center><div class="tablecaption"><a class="target" name="table_commonmatreflectance"> </a><b style="font-style:normal;">Table 5:</b> Reflectance of common materials</div></center></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 section <a href="#toc3.1.20">3.1.20</a> for more information about the <code>ior</code> property and refractive
|
||
indices.
|
||
|
||
</p>
|
||
<a class="target" name="sheencolor"> </a><a class="target" name="materialmodels/litmodel/sheencolor"> </a><a class="target" name="toc3.1.8"> </a><h3>Sheen color</h3>
|
||
<p>
|
||
|
||
|
||
The sheen color controls the color appearance and strength of an optional sheen layer on top of the
|
||
base layer described by the properties above. The sheen layer always sits below the clear coat layer
|
||
if such a layer is present.
|
||
|
||
</p><p>
|
||
|
||
The sheen layer can be used to represent cloth and fabric materials. Please refer to
|
||
section <a href="#toc3.3">3.3</a> for more information about cloth and fabric materials.
|
||
|
||
</p><p>
|
||
|
||
The effect of <code>sheenColor</code> is shown in <a href="#figure_materialsheencolor">figure 7</a>
|
||
(click on the image to see a larger version).
|
||
|
||
</p><p>
|
||
|
||
</p><center><div class="image" style=""><a href="images/screenshot_sheen_color.png" target="_blank"><img class="markdeep" src="images/screenshot_sheen_color.png"></a><center><span class="imagecaption"><a class="target" name="figure_materialsheencolor"> </a><b style="font-style:normal;">Figure 7:</b> Different sheen colors</span></center></div></center>
|
||
|
||
<p></p><p>
|
||
|
||
</p><div class="admonition note">If you do not need the other properties offered by the standard lit material model but want to
|
||
create a cloth-like or fabric-like appearance, it is more efficient to use the dedicated cloth
|
||
model described in section <a href="#toc3.3">3.3</a>.</div>
|
||
|
||
<p></p>
|
||
<a class="target" name="sheenroughness"> </a><a class="target" name="materialmodels/litmodel/sheenroughness"> </a><a class="target" name="toc3.1.9"> </a><h3>Sheen roughness</h3>
|
||
<p>
|
||
|
||
|
||
The <code>sheenRoughness</code> property is similar to the <code>roughness</code> property but applies only to the
|
||
sheen layer.
|
||
|
||
</p><p>
|
||
|
||
The effect of <code>sheenRoughness</code> on a rough metal is shown in <a href="#figure_sheenroughnessproperty">figure 8</a>
|
||
(click on the image to see a larger version). In this picture, the base layer is a dark blue, with
|
||
<code>metallic</code> set to <code>0.0</code> and <code>roughness</code> set to <code>1.0</code>.
|
||
|
||
</p><p>
|
||
|
||
</p><center><div class="image" style=""><a href="images/materials/sheen_roughness.png" target="_blank"><img class="markdeep" src="images/materials/sheen_roughness.png"></a><center><span class="imagecaption"><a class="target" name="figure_sheenroughnessproperty"> </a><b style="font-style:normal;">Figure 8:</b> <code>sheenRoughness</code> varying from 0.0
|
||
(left) to 1.0 (right)</span></center></div></center>
|
||
|
||
<p></p>
|
||
<a class="target" name="clearcoat"> </a><a class="target" name="materialmodels/litmodel/clearcoat"> </a><a class="target" name="toc3.1.10"> </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><center><span class="imagecaption"><a class="target" name="figure_clearcoat"> </a><b style="font-style:normal;">Figure 9:</b> Comparison of a carbon-fiber material under the standard material model
|
||
(left) and the clear coat model (right)</span></center></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 10</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><center><span class="imagecaption"><a class="target" name="figure_clearcoatproperty"> </a><b style="font-style:normal;">Figure 10:</b> <code>clearCoat</code> varying from 0.0
|
||
(left) to 1.0 (right)</span></center></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><p>
|
||
|
||
</p><div class="admonition note">The clear coat layer is added on top of the sheen layer if present.</div>
|
||
|
||
<p></p>
|
||
<a class="target" name="clearcoatroughness"> </a><a class="target" name="materialmodels/litmodel/clearcoatroughness"> </a><a class="target" name="toc3.1.11"> </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 11</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><center><span class="imagecaption"><a class="target" name="figure_clearcoatroughnessproperty"> </a><b style="font-style:normal;">Figure 11:</b> <code>clearCoatRoughness</code> varying from 0.0
|
||
(left) to 1.0 (right)</span></center></div></center>
|
||
|
||
<p></p>
|
||
<a class="target" name="anisotropy"> </a><a class="target" name="materialmodels/litmodel/anisotropy"> </a><a class="target" name="toc3.1.12"> </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><center><span class="imagecaption"><a class="target" name="figure_anisotropic"> </a><b style="font-style:normal;">Figure 12:</b> Comparison of isotropic material
|
||
(left) and anistropic material (right)</span></center></div></center>
|
||
|
||
<p></p><p>
|
||
|
||
The effect of <code>anisotropy</code> on a rough metal is shown in <a href="#figure_anisotropyproperty">figure 13</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><center><span class="imagecaption"><a class="target" name="figure_anisotropyproperty"> </a><b style="font-style:normal;">Figure 13:</b> <code>anisotropy</code> varying from 0.0
|
||
(left) to 1.0 (right)</span></center></div></center>
|
||
|
||
<p></p><p>
|
||
|
||
The <a href="#figure_anisotropydir">figure 14</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><center><span class="imagecaption"><a class="target" name="figure_anisotropydir"> </a><b style="font-style:normal;">Figure 14:</b> Positive (left) vs negative
|
||
(right) <code>anisotropy</code> values</span></center></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.13"> </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 in tangent space. Because the
|
||
direction is in tangent space, the Z component should be set to 0.
|
||
|
||
</p><p>
|
||
|
||
The effect of <code>anisotropyDirection</code> on a metal is shown in <a href="#figure_anisotropydirectionproperty">figure 16</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><center><span class="imagecaption"><a class="target" name="figure_anisotropydirectionproperty"> </a><b style="font-style:normal;">Figure 15:</b> Anisotropic metal rendered
|
||
with a direction map</span></center></div></center>
|
||
|
||
<p></p><p>
|
||
|
||
The result shown in <a href="#figure_anisotropydirectionproperty">figure 16</a> was obtained using the direction map shown
|
||
in <a href="#figure_anisotropydirectionproperty">figure 16</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><center><span class="imagecaption"><a class="target" name="figure_anisotropydirectionproperty"> </a><b style="font-style:normal;">Figure 16:</b> Example of Lighting: specularAmbientOcclusiona direction map</span></center></div></center>
|
||
|
||
<p></p>
|
||
<a class="target" name="ambientocclusion"> </a><a class="target" name="materialmodels/litmodel/ambientocclusion"> </a><a class="target" name="toc3.1.14"> </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><center><span class="imagecaption"><a class="target" name="figure_aoexample"> </a><b style="font-style:normal;">Figure 17:</b> Comparison of materials without diffuse ambient occlusion
|
||
(left) and with (right)</span></center></div></center>
|
||
|
||
<p></p>
|
||
<a class="target" name="normal"> </a><a class="target" name="materialmodels/litmodel/normal"> </a><a class="target" name="toc3.1.15"> </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 18</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><center><span class="imagecaption"><a class="target" name="figure_normalmapped"> </a><b style="font-style:normal;">Figure 18:</b> Low-poly mesh without normal mapping (left)
|
||
and with (right)</span></center></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.16"> </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 can also improve the quality of
|
||
specular ambient occlusion (see section <a href="#toc4.2.33">4.2.33</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 19</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><center><span class="imagecaption"><a class="target" name="figure_bentnormalmapped"> </a><b style="font-style:normal;">Figure 19:</b> Example of a model rendered with and without a bent normal map. Both
|
||
versions use the same ambient occlusion map.</span></center></div></center>
|
||
|
||
<p></p>
|
||
<a class="target" name="clearcoatnormal"> </a><a class="target" name="materialmodels/litmodel/clearcoatnormal"> </a><a class="target" name="toc3.1.17"> </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><center><span class="imagecaption"><a class="target" name="figure_clearcoatnormalmapped"> </a><b style="font-style:normal;">Figure 20:</b> A material with a clear coat normal
|
||
map and a surface normal map</span></center></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.18"> </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 intensity in nits as well as an exposure
|
||
weight (in the alpha channel).
|
||
|
||
</p><p>
|
||
|
||
The intensity in nits allows an emissive surface to function as a light and can be used to recreate
|
||
real world surfaces. For instance a computer display has an intensity between 200 and 1,000 nits.
|
||
|
||
</p><p>
|
||
|
||
If you prefer to work in EV (or f-stops), you can simplify multiply your emissive color by the
|
||
output of the API <code>filament::Exposure::luminance(ev)</code>. This API returns the luminance in nits of
|
||
the specific EV. You can perform this conversion yourself using the following formula, where \(L\)
|
||
is the final intensity in nits: \( L = 2^{EV - 3} \).
|
||
|
||
</p><p>
|
||
|
||
The exposure weight carried in the alpha channel can be used to undo the camera exposure, and thus
|
||
force an emissive surface to bloom. When the exposure weight is set to 0, the emissive intensity is
|
||
not affected by the camera exposure. When the weight is set to 1, the intensity is multiplied by
|
||
the camera exposure like with any regular light.
|
||
|
||
</p>
|
||
<a class="target" name="post-lightingcolor"> </a><a class="target" name="materialmodels/litmodel/post-lightingcolor"> </a><a class="target" name="toc3.1.19"> </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.20"> </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>. It can also be used on non-refractive objects as an alternative
|
||
to setting the reflectance.
|
||
|
||
</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><center><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></center></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 section <a href="#toc4.2.21">4.2.21</a> and section <a href="#toc4.2.20">4.2.20</a>
|
||
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 21</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><center><span class="imagecaption"><a class="target" name="figure_iorproperty2"> </a><b style="font-style:normal;">Figure 21:</b> <code>transmission</code> varying from 1.0
|
||
(left) to 1.5 (right)</span></center></div></center>
|
||
|
||
<p></p><p>
|
||
|
||
<a href="#figure_iorproperty">Figure 22</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><center><span class="imagecaption"><a class="target" name="figure_iorproperty"> </a><b style="font-style:normal;">Figure 22:</b> <code>ior</code> of 1.0 (left) and 1.33 (right)</span></center></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.21"> </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 23</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><center><span class="imagecaption"><a class="target" name="figure_transmissionproperty"> </a><b style="font-style:normal;">Figure 23:</b> <code>transmission</code> varying from 0.0
|
||
(left) to 1.0 (right)</span></center></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.22"> </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 24</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><center><span class="imagecaption"><a class="target" name="figure_absorptionexample"> </a><b style="font-style:normal;">Figure 24:</b> Refracting object without (left)
|
||
and with (right) absorption</span></center></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 25</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><center><span class="imagecaption"><a class="target" name="figure_absorptionproperty"> </a><b style="font-style:normal;">Figure 25:</b> <code>absorption</code> varying from (0.0, 0.02, 0.14)
|
||
(left) to (0.0, 0.36, 2.3) (right)</span></center></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.23"> </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 26</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><center><span class="imagecaption"><a class="target" name="figure_thicknessproperty"> </a><b style="font-style:normal;">Figure 26:</b> <code>thickness</code> varying from 0.0
|
||
(left) to 2.0 (right)</span></center></div></center>
|
||
|
||
<p></p><p>
|
||
|
||
<a href="#figure_varyingthickness">Figure 27</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><center><span class="imagecaption"><a class="target" name="figure_varyingthickness"> </a><b style="font-style:normal;">Figure 27:</b> <code>thickness</code> varying from 0.0 at the top of the prism to 3.0 at the
|
||
bottom of the prism</span></center></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 28</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><center><span class="imagecaption"><a class="target" name="figure_materialcloth"> </a><b style="font-style:normal;">Figure 28:</b> Comparison of denim fabric rendered using the standard model
|
||
(left) and the cloth model (right)</span></center></div></center>
|
||
|
||
<p></p><p>
|
||
|
||
Velvet is an interesting use case for a cloth material model. As shown in <a href="#figure_materialvelvet">figure 29</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><center><span class="imagecaption"><a class="target" name="figure_materialvelvet"> </a><b style="font-style:normal;">Figure 29:</b> Velvet fabric showcasing forward and
|
||
backward scattering</span></center></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><center><div class="tablecaption"><a class="target" name="table_clothproperties"> </a><b style="font-style:normal;">Table 7:</b> Cloth model parameters</div></center></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><center><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></center></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 30</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><center><span class="imagecaption"><a class="target" name="figure_materialclothsheen"> </a><b style="font-style:normal;">Figure 30:</b> Blue fabric without (left) and with (right) sheen</span></center></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 31</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><center><span class="imagecaption"><a class="target" name="figure_materialclothsubsurface"> </a><b style="font-style:normal;">Figure 31:</b> White cloth (left column) vs white cloth with
|
||
brown subsurface scatting (right)</span></center></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><center><div class="tablecaption"><a class="target" name="table_unlitproperties"> </a><b style="font-style:normal;">Table 9:</b> Properties of the standard model</div></center></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..n], a=[0..1] </td><td style="text-align:left"> Linear RGB intensity in nits, alpha encodes the exposure weight </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><center><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></center></div>
|
||
|
||
<p></p><p>
|
||
|
||
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 32</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><center><span class="imagecaption"><a class="target" name="figure_materialunlit"> </a><b style="font-style:normal;">Figure 32:</b> The unlit model is used to render debug information</span></center></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><center><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></center></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><center><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></center></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"> <span class="hljs-comment">// material properties</span></span>
|
||
<span class="line">}</span>
|
||
<span class="line"></span>
|
||
<span class="line">vertex {</span>
|
||
<span class="line"> <span class="hljs-comment">// vertex shader, optional</span></span>
|
||
<span class="line">}</span>
|
||
<span class="line"></span>
|
||
<span class="line">fragment {</span>
|
||
<span class="line"> <span class="hljs-comment">// fragment shader</span></span>
|
||
<span class="line">}</span></code></pre><p>
|
||
|
||
A minimum viable material definition must contain a <code>material</code> preamble 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"><span class="hljs-string">"key"</span> : 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 : <span class="hljs-string">"Textured material"</span>,</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 : <span class="hljs-string">"Wet pavement"</span></span>
|
||
<span class="line">}</span></code></pre>
|
||
<a class="target" name="general:featurelevel"> </a><a class="target" name="materialdefinitions/materialblock/general:featurelevel"> </a><a class="target" name="toc4.2.2"> </a><h3>General: featureLevel</h3>
|
||
<p>
|
||
|
||
|
||
</p><dl><table><tbody><tr valign="top"><td><dt>Type</dt></td><td><dd><p> <code>number</code>
|
||
|
||
</p></dd></td></tr><tr valign="top"><td><dt>Value</dt></td><td><dd><p> An integer value, either 1, 2 or 3. Defaults to 1.
|
||
|
||
</p></dd></td></tr></tbody></table></dl><div class="table">
|
||
<table class="table"><tbody><tr><th style="text-align:left"> Feature Level </th><th style="text-align:left"> Guaranteed features </th></tr>
|
||
<tr><td style="text-align:left"> 1 </td><td style="text-align:left"> 9 textures per material </td></tr>
|
||
<tr><td style="text-align:left"> 2 </td><td style="text-align:left"> 9 textures per material, cubemap arrays, ESSL 3.10 </td></tr>
|
||
<tr><td style="text-align:left"> 3 </td><td style="text-align:left"> 12 textures per material, cubemap arrays, ESSL 3.10 </td></tr>
|
||
</tbody></table><center><div class="tablecaption"><a class="target" name="table_featurelevels"> </a><b style="font-style:normal;">Table 13:</b> Feature levels</div></center></div>
|
||
|
||
<p></p><p>
|
||
|
||
</p><dl><dt>Description</dt><dd><p> Sets the feature level of the material. Each feature level defines a set of features the
|
||
material can use. If the material uses a feature not supported by the selected level, <code>matc</code>
|
||
will generate an error during compilation. A given feature level is guaranteed to support
|
||
all features of lower feature levels.
|
||
|
||
</p></dd></dl><p></p><pre class="listing tilde"><code><span class="line">material {</span>
|
||
<span class="line"> featureLevel : <span class="hljs-number">2</span></span>
|
||
<span class="line">}</span></code></pre><p>
|
||
|
||
</p><dl><table><tbody><tr valign="top"><td><dt>Bugs</dt></td><td><dd><p> <code>matc</code> doesn't verify that a material is not using features above its selected feature level.
|
||
|
||
</p></dd></td></tr></tbody></table></dl><p></p>
|
||
<a class="target" name="general:shadingmodel"> </a><a class="target" name="materialdefinitions/materialblock/general:shadingmodel"> </a><a class="target" name="toc4.2.3"> </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 : <span class="hljs-string">"subsurface"</span></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.4"> </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. Entries also have an optional <code>precision</code>, which 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>. The type must be one of the types described in
|
||
<a href="#table_materialparamstypes">table 14</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"> sampler2dArray </td><td style="text-align:left"> Array of 2D textures </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><center><div class="tablecaption"><a class="target" name="table_materialparamstypes"> </a><b style="font-style:normal;">Table 14:</b> Material parameter types</div></center></div>
|
||
|
||
<p></p><p>
|
||
|
||
</p><dl><dt>Samplers</dt><dd><p> Sampler types can also specify a <code>format</code> which can be either <code>int</code> or <code>float</code> (defaults to
|
||
<code>float</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. This syntax does not apply to samplers as arrays are treated as separate types.
|
||
|
||
</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:constants"> </a><a class="target" name="materialdefinitions/materialblock/general:constants"> </a><a class="target" name="toc4.2.5"> </a><h3>General: constants</h3>
|
||
<p>
|
||
|
||
|
||
</p><dl><dt>Type</dt><dd><p> array of constant 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. Entries also have an optional <code>default</code>, which can either be a
|
||
<code>bool</code> or <code>number</code>, depending on the <code>type</code> of the constant. The type must be one of the types
|
||
described in <a href="#table_materialconstantstypes">table 15</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><th style="text-align:left"> Default </th></tr>
|
||
<tr><td style="text-align:left"> int </td><td style="text-align:left"> A signed, 32 bit GLSL int </td><td style="text-align:left"> 0 </td></tr>
|
||
<tr><td style="text-align:left"> float </td><td style="text-align:left"> A single-precision GLSL float </td><td style="text-align:left"> 0.0 </td></tr>
|
||
<tr><td style="text-align:left"> bool </td><td style="text-align:left"> A GLSL bool </td><td style="text-align:left"> false </td></tr>
|
||
</tbody></table><center><div class="tablecaption"><a class="target" name="table_materialconstantstypes"> </a><b style="font-style:normal;">Table 15:</b> Material constants types</div></center></div>
|
||
|
||
<p></p><p>
|
||
|
||
</p><dl><dt>Description</dt><dd><p> Lists the constant parameters accepted by your material. These constants can be set, or
|
||
“specialized”, at runtime when loading a material package. Multiple materials can be loaded from
|
||
the same material package with differing constant parameter specializations. Once a material is
|
||
loaded from a material package, its constant parameters cannot be changed. Compared to regular
|
||
parameters, constant parameters allow the compiler to generate more efficient code. Access
|
||
constant parameters from the shader by prefixing the name with <code>materialConstant_</code>. For example,
|
||
a constant parameter named <code>myConstant</code> is accessed in the shader as
|
||
<code>materialConstant_myConstant</code>. If a constant parameter is not set at runtime, the default is
|
||
used.
|
||
|
||
</p></dd></dl><p></p><pre class="listing tilde"><code><span class="line">material {</span>
|
||
<span class="line"> constants : [</span>
|
||
<span class="line"> {</span>
|
||
<span class="line"> name : overrideAlpha,</span>
|
||
<span class="line"> type : bool</span>
|
||
<span class="line"> },</span>
|
||
<span class="line"> {</span>
|
||
<span class="line"> name : customAlpha,</span>
|
||
<span class="line"> type : float,</span>
|
||
<span class="line"> default : <span class="hljs-number">0.5</span></span>
|
||
<span class="line"> }</span>
|
||
<span class="line"> ],</span>
|
||
<span class="line"> shadingModel : lit,</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"> if (materialConstants_overrideAlpha) {</span>
|
||
<span class="line"> material.baseColor.a = materialConstants_customAlpha;</span>
|
||
<span class="line"> material.baseColor.rgb *= material.baseColor.a;</span>
|
||
<span class="line"> }</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.6"> </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>,
|
||
<code>skinning</code>, <code>ssr</code>, or <code>stereo</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>
|
||
<li class="minus"><code>fog</code>, used when global fog is applied to the scene
|
||
</li>
|
||
<li class="minus"><code>vsm</code>, used when VSM shadows are enabled and the object is a shadow receiver
|
||
</li>
|
||
<li class="minus"><code>ssr</code>, used when screen-space reflections are enabled in the View
|
||
</li>
|
||
<li class="minus"><code>stereo</code>, used when stereoscopic rendering is enabled in the View</li></ul>
|
||
|
||
<p></p><pre class="listing tilde"><code><span class="line">material {</span>
|
||
<span class="line"> name : <span class="hljs-string">"Invisible shadow plane"</span>,</span>
|
||
<span class="line"> shadingModel : unlit,</span>
|
||
<span class="line"> shadowMultiplier : <span class="hljs-literal">true</span>,</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.7"> </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 : <span class="hljs-literal">false</span></span>
|
||
<span class="line">}</span></code></pre>
|
||
<a class="target" name="general:quality"> </a><a class="target" name="materialdefinitions/materialblock/general:quality"> </a><a class="target" name="toc4.2.8"> </a><h3>General: quality</h3>
|
||
<p>
|
||
|
||
|
||
</p><dl><dt>Type</dt><dd><p> <code>string</code>
|
||
|
||
</p></dd><dt>Value</dt><dd><p> Any of <code>low</code>, <code>normal</code>, <code>high</code>, <code>default</code>. Defaults to <code>default</code>.
|
||
|
||
</p></dd><dt>Description</dt><dd><p> Set some global quality parameters of the material. <code>low</code> enables optimizations that can
|
||
slightly affect correctness and is the default on mobile platforms. <code>normal</code> does not affect
|
||
correctness and is otherwise similar to <code>low</code>. <code>high</code> enables quality settings that can
|
||
adversely affect performance and is the default on desktop platforms.
|
||
|
||
</p></dd></dl><p></p><pre class="listing tilde"><code><span class="line">material {</span>
|
||
<span class="line"> quality : default</span>
|
||
<span class="line">}</span></code></pre>
|
||
<a class="target" name="general:instanced"> </a><a class="target" name="materialdefinitions/materialblock/general:instanced"> </a><a class="target" name="toc4.2.9"> </a><h3>General: instanced</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> Allows a material to access the instance index (i.e.: <strong class="asterisk"><code>gl_InstanceIndex</code></strong>) of instanced
|
||
primitives using <code>getInstanceIndex()</code> in the material's shader code. Never use
|
||
<strong class="asterisk"><code>gl_InstanceIndex</code></strong> directly. This is typically used with
|
||
<code>RenderableManager::Builder::instances()</code>. <code>getInstanceIndex()</code> is available in both the
|
||
vertex and fragment shader.
|
||
|
||
</p></dd></dl><p></p><pre class="listing tilde"><code><span class="line">material {</span>
|
||
<span class="line"> instanced : <span class="hljs-literal">true</span></span>
|
||
<span class="line">}</span></code></pre>
|
||
<a class="target" name="general:vertexdomaindevicejittered"> </a><a class="target" name="materialdefinitions/materialblock/general:vertexdomaindevicejittered"> </a><a class="target" name="toc4.2.10"> </a><h3>General: vertexDomainDeviceJittered</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 meaningful for <code>vertexDomain:Device</code> materials, this parameter specifies whether the
|
||
filament clip-space transforms need to be applied or not, which affects TAA and guard bands.
|
||
Generally it needs to be applied because by definition <code>vertexDomain:Device</code> materials
|
||
vertices are not transformed and used <em class="asterisk">as is</em>.
|
||
However, if the vertex shader uses for instance <code>getViewFromClipMatrix()</code> (or other
|
||
matrices based on the projection), the clip-space transform is already applied.
|
||
Setting this parameter incorrectly can prevent TAA or the guard bands to work correctly.
|
||
|
||
</p></dd></dl><p></p><pre class="listing tilde"><code><span class="line">material {</span>
|
||
<span class="line"> vertexDomainDeviceJittered : <span class="hljs-literal">true</span></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.11"> </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>, <code>custom0</code>
|
||
through <code>custom7</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"> custom0</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"> material.baseColor.rgb *= getCustom0().rgb;</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.12"> </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. By default the precision of the
|
||
interpolant is <code>highp</code> in <em class="asterisk">both</em> the vertex and fragment shaders.
|
||
An alternate syntax can be used to specify both the name and precision of the interpolant.
|
||
In this case the specified precision is used as-is in both fragment and vertex stages, in
|
||
particular if <code>default</code> is specified the default precision is used is the fragment shader
|
||
(<code>mediump</code>) and in the vertex shader (<code>highp</code>).
|
||
|
||
</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"> name : eyeColor,</span>
|
||
<span class="line"> precision : medium</span>
|
||
<span class="line"> }</span>
|
||
<span class="line"> ],</span>
|
||
<span class="line"> vertexDomain : device,</span>
|
||
<span class="line"> depthWrite : <span class="hljs-literal">false</span>,</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.13"> </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.14"> </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.15"> </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>, <code>custom</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. Additionally,
|
||
ALPHA_TO_COVERAGE is enabled for non-translucent views. See the maskThreshold section for more
|
||
information.
|
||
</li>
|
||
<li class="minus"><strong class="asterisk">Custom</strong>: blending is enabled. But the blending function is user specified. See <code>blendFunction</code>.</li></ul>
|
||
|
||
<p></p></dd></dl><div class="admonition note">When <code>blending</code> is set to <code>masked</code>, alpha to coverage is automatically enabled for the material.
|
||
If this behavior is undesirable, refer to the <a href="#rasterization:alphatocoverage">Rasterization: alphaToCoverage</a> section to turn
|
||
alpha to coverage off using the <code>alphaToCoverage</code> property.</div>
|
||
|
||
<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:blendfunction"> </a><a class="target" name="materialdefinitions/materialblock/blendingandtransparency:blendfunction"> </a><a class="target" name="toc4.2.16"> </a><h3>Blending and transparency: blendFunction</h3>
|
||
<p>
|
||
|
||
|
||
</p><dl><dt>Type</dt><dd><p> <code>object</code>
|
||
|
||
</p></dd><dt>Fields</dt><dd><p> <code>srcRGB</code>, <code>srcA</code>, <code>dstRGB</code>, <code>dstA</code>
|
||
|
||
</p></dd><dt>Description</dt><dd><p> - <em class="asterisk">srcRGB</em>: source function applied to the RGB channels
|
||
- <em class="asterisk">srcA</em>: source function applied to the alpha channel
|
||
- <em class="asterisk">srcRGB</em>: destination function applied to the RGB channels
|
||
- <em class="asterisk">srcRGB</em>: destination function applied to the alpha channel
|
||
The values possible for each functions are one of <code>zero</code>, <code>one</code>, <code>srcColor</code>, <code>oneMinusSrcColor</code>,
|
||
<code>dstColor</code>, <code>oneMinusDstColor</code>, <code>srcAlpha</code>, <code>oneMinusSrcAlpha</code>, <code>dstAlpha</code>,
|
||
<code>oneMinusDstAlpha</code>, <code>srcAlphaSaturate</code>
|
||
|
||
</p></dd></dl><p></p><pre class="listing tilde"><code><span class="line">material {</span>
|
||
<span class="line"> blending : custom,</span>
|
||
<span class="line"> blendFunction :</span>
|
||
<span class="line"> {</span>
|
||
<span class="line"> srcRGB: one,</span>
|
||
<span class="line"> srcA: one,</span>
|
||
<span class="line"> dstRGB: oneMinusSrcColor,</span>
|
||
<span class="line"> dstA: oneMinusSrcAlpha</span>
|
||
<span class="line"> }</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.17"> </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.18"> </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> and <code>refractionMode</code> is <code>none</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 33</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 34</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 35</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><center><span class="imagecaption"><a class="target" name="figure_transparencydefault"> </a><b style="font-style:normal;">Figure 33:</b> This double sided model shows the type of sorting issues transparent
|
||
objects can be subject to in <code>default</code> mode</span></center></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><center><span class="imagecaption"><a class="target" name="figure_transparencytwopassesoneside"> </a><b style="font-style:normal;">Figure 34:</b> In <code>twoPassesOneSide</code> mode, only one set of faces is visible
|
||
and correctly sorted</span></center></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><center><span class="imagecaption"><a class="target" name="figure_transparencytwopassestwosides"> </a><b style="font-style:normal;">Figure 35:</b> In <code>twoPassesTwoSides</code> mode, both set of faces are visible
|
||
and sorting issues are minimized or eliminated</span></center></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.19"> </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>. If the fragment is not discarded, its source alpha is set to 1. 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 : <span class="hljs-number">0.5</span></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.20"> </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.21"> </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.22"> </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.23"> </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 : <span class="hljs-literal">false</span></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.24"> </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 : <span class="hljs-literal">false</span></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.25"> </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 : <span class="hljs-literal">false</span></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.26"> </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"> name : <span class="hljs-string">"Double sided material"</span>,</span>
|
||
<span class="line"> shadingModel : lit,</span>
|
||
<span class="line"> doubleSided : <span class="hljs-literal">true</span></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"> }</span>
|
||
<span class="line">}</span></code></pre>
|
||
<a class="target" name="rasterization:alphatocoverage"> </a><a class="target" name="materialdefinitions/materialblock/rasterization:alphatocoverage"> </a><a class="target" name="toc4.2.27"> </a><h3>Rasterization: alphaToCoverage</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 or disables alpha to coverage. When alpha to coverage is enabled, the coverage of
|
||
fragment is derived from its alpha. This property is only meaningful when MSAA is enabled.
|
||
Note: setting <code>blending</code> to <code>masked</code> automatically enables alpha to coverage. If this is not
|
||
desired, you can override this behavior by setting alpha to coverage to false as in the
|
||
example below.
|
||
|
||
</p></dd></dl><p></p><pre class="listing tilde"><code><span class="line">material {</span>
|
||
<span class="line"> name : <span class="hljs-string">"Alpha to coverage"</span>,</span>
|
||
<span class="line"> shadingModel : lit,</span>
|
||
<span class="line"> blending : masked,</span>
|
||
<span class="line"> alphaToCoverage : <span class="hljs-literal">false</span></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"> }</span>
|
||
<span class="line">}</span></code></pre>
|
||
<a class="target" name="lighting:reflections"> </a><a class="target" name="materialdefinitions/materialblock/lighting:reflections"> </a><a class="target" name="toc4.2.28"> </a><h3>Lighting: reflections</h3>
|
||
<p>
|
||
|
||
|
||
</p><dl><dt>Type</dt><dd><p> <code>string</code>
|
||
|
||
</p></dd><dt>Value</dt><dd><p> <code>default</code> or <code>screenspace</code>. Defaults to <code>default</code>.
|
||
|
||
</p></dd><dt>Description</dt><dd><p> Controls the source of specular reflections for this material. When this property is set to
|
||
<code>default</code>, reflections only come image-based lights. When this property is set to
|
||
<code>screenspace</code>, reflections come from the screen space's color buffer in addition to
|
||
image-based lights.
|
||
|
||
</p></dd></dl><p></p><pre class="listing tilde"><code><span class="line">material {</span>
|
||
<span class="line"> name : <span class="hljs-string">"Glossy metal"</span>,</span>
|
||
<span class="line"> reflections : screenspace</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.29"> </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).
|
||
This is only supported with shadows from directional lights.
|
||
|
||
</p></dd></dl><p></p><pre class="listing tilde"><code><span class="line">material {</span>
|
||
<span class="line"> name : <span class="hljs-string">"Invisible shadow plane"</span>,</span>
|
||
<span class="line"> shadingModel : unlit,</span>
|
||
<span class="line"> shadowMultiplier : <span class="hljs-literal">true</span>,</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"> <span class="hljs-comment">// baseColor defines the color and opacity of the final shadow</span></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:transparentshadow"> </a><a class="target" name="materialdefinitions/materialblock/lighting:transparentshadow"> </a><a class="target" name="toc4.2.30"> </a><h3>Lighting: transparentShadow</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 transparent shadows on this material. When this feature is enabled, Filament emulates
|
||
transparent shadows using a dithering pattern: they work best with variance shadow maps (VSM)
|
||
and blurring enabled. The opacity of the shadow derives directly from the alpha channel of
|
||
the material's <code>baseColor</code> property. Transparent shadows can be enabled on opaque objects,
|
||
making them compatible with refractive/transmissive objects that are otherwise considered
|
||
opaque.
|
||
|
||
</p></dd></dl><p></p><pre class="listing tilde"><code><span class="line">material {</span>
|
||
<span class="line"> name : <span class="hljs-string">"Clear plastic with stickers"</span>,</span>
|
||
<span class="line"> transparentShadow : <span class="hljs-literal">true</span>,</span>
|
||
<span class="line"> blending : transparent,</span>
|
||
<span class="line"> <span class="hljs-comment">// ...</span></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_baseColor, getUV0());</span>
|
||
<span class="line"> }</span>
|
||
<span class="line">}</span></code></pre><p>
|
||
|
||
</p><center><div class="image" style=""><a href="images/screenshot_transparent_shadows.jpg" target="_blank"><img class="markdeep" src="images/screenshot_transparent_shadows.jpg"></a><center><span class="imagecaption"><a class="target" name="figure_transparentshadow"> </a><b style="font-style:normal;">Figure 36:</b> Objects rendered with transparent shadows and blurry VSM with a
|
||
radius of 4. Model <a href="https://sketchfab.com/3d-models/bottle-of-water-48fd4f6e90d84d89b5740ee78587d0ff">Bottle of Water</a>
|
||
by <a href="https://sketchfab.com/person-x">T-Art</a>.</span></center></div></center>
|
||
|
||
<p></p>
|
||
<a class="target" name="lighting:clearcoatiorchange"> </a><a class="target" name="materialdefinitions/materialblock/lighting:clearcoatiorchange"> </a><a class="target" name="toc4.2.31"> </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 37</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 : <span class="hljs-literal">false</span></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><center><span class="imagecaption"><a class="target" name="figure_clearcoatiorchange"> </a><b style="font-style:normal;">Figure 37:</b> The same rough metallic ball with a clear coat layer rendered
|
||
with <code>clearCoatIorChange</code> enabled (left) and disabled
|
||
(right).</span></center></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.32"> </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 38</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 39</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 : <span class="hljs-literal">true</span></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><center><span class="imagecaption"><a class="target" name="figure_multibounceao"> </a><b style="font-style:normal;">Figure 38:</b> Brick texture amient occlusion map rendered with multi-bounce ambient
|
||
occclusion enabled (left) and disabled (right).</span></center></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><center><span class="imagecaption"><a class="target" name="figure_multibounceaoanimated"> </a><b style="font-style:normal;">Figure 39:</b> Brick texture rendered with multi-bounce ambient
|
||
occclusion enabled and disabled.</span></center></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.33"> </a><h3>Lighting: specularAmbientOcclusion</h3>
|
||
<p>
|
||
|
||
|
||
</p><dl><dt>Type</dt><dd><p> <code>string</code>
|
||
|
||
</p></dd><dt>Value</dt><dd><p> <code>none</code>, <code>simple</code> or <code>bentNormals</code>. Defaults to <code>none</code> on mobile, <code>simple</code> on desktop. For
|
||
compatibility reasons, <code>true</code> and <code>false</code> are also accepted and map respectively to <code>simple</code>
|
||
and <code>none</code>.
|
||
|
||
</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 other than <code>none</code>, a new ambient occlusion
|
||
term is derived from the surface roughness and applied to specular indirect lighting.
|
||
This effect helps remove unwanted specular reflections as shown in <a href="#figure_specularao">figure 40</a>.
|
||
When this value is set to <code>simple</code>, Filament uses a cheap but approximate method of computing
|
||
the specular ambient occlusion term. If this value is set to <code>bentNormals</code>, Filament will use
|
||
a much more accurate but much more expensive method.
|
||
|
||
</p></dd></dl><p></p><pre class="listing tilde"><code><span class="line">material {</span>
|
||
<span class="line"> specularAmbientOcclusion : simple</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><center><span class="imagecaption"><a class="target" name="figure_specularao"> </a><b style="font-style:normal;">Figure 40:</b> Comparison of specular ambient occlusion on and off. The effect is
|
||
particularly visible under the hose.</span></center></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.34"> </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 strength 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 : <span class="hljs-literal">true</span></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.35"> </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 : <span class="hljs-number">0.2</span></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.36"> </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 : <span class="hljs-number">0.1</span></span>
|
||
<span class="line">}</span></code></pre>
|
||
<a class="target" name="shading:customsurfaceshading"> </a><a class="target" name="materialdefinitions/materialblock/shading:customsurfaceshading"> </a><a class="target" name="toc4.2.37"> </a><h3>Shading: customSurfaceShading</h3>
|
||
<p>
|
||
|
||
|
||
</p><dl><dt>Type</dt><dd><p> <code>bool</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 custom surface shading when set to true. When surface shading is enabled, the fragment
|
||
shader must provide an extra function that will be invoked for every light in the scene that
|
||
may influence the current fragment. Please refer to the <a href="#customsurfaceshading">Custom surface shading</a> section below
|
||
for more information.
|
||
|
||
</p></dd></dl><p></p><pre class="listing tilde"><code><span class="line">material {</span>
|
||
<span class="line"> customSurfaceShading : <span class="hljs-literal">true</span></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>(getUserTime().x);</span>
|
||
<span class="line"> material.uv0 *= <span class="hljs-built_in">sin</span>(getUserTime().x);</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, only available for `vertexDomain:device`</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 use
|
||
<code>getUserWorldPosition()</code>, however be aware that the true world-position might not
|
||
be able to fit in a <code>float</code> or might be represented with severely reduced precision.</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="customvertexattributes"> </a><a class="target" name="materialdefinitions/vertexblock/customvertexattributes"> </a><a class="target" name="toc4.3.2"> </a><h3>Custom vertex attributes</h3>
|
||
<p>
|
||
|
||
|
||
You can use up to 8 custom vertex attributes, all of type <code>float4</code>. These attributes can be accessed
|
||
using the vertex block shader functions <code>getCustom0()</code> to <code>getCustom7()</code>. However, before using
|
||
custom attributes, you <em class="asterisk">must</em> declare those attributes as required in the <code>requires</code> property of
|
||
the material:
|
||
|
||
</p><pre class="listing tilde"><code><span class="line">material {</span>
|
||
<span class="line"> requires : [</span>
|
||
<span class="line"> custom0,</span>
|
||
<span class="line"> custom1,</span>
|
||
<span class="line"> custom2</span>
|
||
<span class="line"> ]</span>
|
||
<span class="line">}</span></code></pre>
|
||
<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 fragment
|
||
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 fragment 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 model. 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, 0.0, 0.0, 1.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"> float3 sheenColor; <span class="hljs-comment">// default: float3(0.0)</span></span>
|
||
<span class="line"> <span class="hljs-type">float</span> sheenRoughness; <span class="hljs-comment">// default: 0.0</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="customsurfaceshading"> </a><a class="target" name="materialdefinitions/fragmentblock/customsurfaceshading"> </a><a class="target" name="toc4.4.3"> </a><h3>Custom surface shading</h3>
|
||
<p>
|
||
|
||
|
||
When <code>customSurfaceShading</code> is set to <code>true</code> in the material block, the fragment block <strong class="asterisk">must</strong>
|
||
declare and implement the <code>surfaceShading</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">// prepare material inputs</span></span>
|
||
<span class="line"> }</span>
|
||
<span class="line"></span>
|
||
<span class="line"> <span class="hljs-type">vec3</span> surfaceShading(</span>
|
||
<span class="line"> <span class="hljs-keyword">const</span> MaterialInputs materialInputs,</span>
|
||
<span class="line"> <span class="hljs-keyword">const</span> ShadingData shadingData,</span>
|
||
<span class="line"> <span class="hljs-keyword">const</span> LightData lightData</span>
|
||
<span class="line"> ) {</span>
|
||
<span class="line"> <span class="hljs-keyword">return</span> <span class="hljs-type">vec3</span>(<span class="hljs-number">1.0</span>); <span class="hljs-comment">// output of custom lighting</span></span>
|
||
<span class="line"> }</span>
|
||
<span class="line">}</span></code></pre><p>
|
||
|
||
This function will be invoked for every light (directional, spot or point) in the scene that may
|
||
influence the current fragment. The <code>surfaceShading</code> is invoked with 3 sets of data:
|
||
|
||
</p><p>
|
||
|
||
</p><ul>
|
||
<li class="minus"><code>MaterialInputs</code>, as described in the <a href="#materialfragmentinputs">Material fragment inputs</a> section and prepared in the
|
||
<code>material</code> function explained above
|
||
</li>
|
||
<li class="minus"><code>ShadingData</code>, a structure containing values derived from <code>MaterialInputs</code> (see below)
|
||
</li>
|
||
<li class="minus"><code>LightData</code>, a structure containing values specific to the light being currently
|
||
evaluated (see below)</li></ul>
|
||
|
||
<p></p><p>
|
||
|
||
The <code>surfaceShading</code> function must return an RGB color in linear sRGB. Alpha blending and alpha
|
||
masking are handled outside of this function and must therefore be ignored.
|
||
|
||
</p><p>
|
||
|
||
</p><div class="admonition note"><div class="admonition-title"> About shadowed fragments</div>
|
||
|
||
<p></p><p>
|
||
|
||
The <code>surfaceShading</code> function is invoked even when a fragment is known to be fully in the shadow
|
||
of the current light (<code>lightData.NdotL <= 0.0</code> or <code>lightData.visibility <= 0.0</code>). This gives
|
||
more flexibility to the <code>surfaceShading</code> function as it provides a simple way to handle constant
|
||
ambient lighting for instance.</p></div>
|
||
|
||
<p></p><p>
|
||
|
||
</p><div class="admonition warning"><div class="admonition-title"> Shading models</div>
|
||
|
||
<p></p><p>
|
||
|
||
Custom surface shading only works with the <code>lit</code> shading model. Attempting to use any other
|
||
model will result in an error.</p></div>
|
||
|
||
<p></p>
|
||
<a class="target" name="shadingdatastructure"> </a><a class="target" name="materialdefinitions/fragmentblock/customsurfaceshading/shadingdatastructure"> </a><a class="target" name="toc4.4.3.1"> </a><h4>Shading data structure</h4>
|
||
<pre class="listing tilde"><code><span class="line">struct ShadingData {</span>
|
||
<span class="line"> <span class="hljs-comment">// The material's diffuse color, as derived from baseColor and metallic.</span></span>
|
||
<span class="line"> <span class="hljs-comment">// This color is pre-multiplied by alpha and in the linear sRGB color space.</span></span>
|
||
<span class="line"> <span class="hljs-type">vec3</span> diffuseColor;</span>
|
||
<span class="line"></span>
|
||
<span class="line"> <span class="hljs-comment">// The material's specular color, as derived from baseColor and metallic.</span></span>
|
||
<span class="line"> <span class="hljs-comment">// This color is pre-multiplied by alpha and in the linear sRGB color space.</span></span>
|
||
<span class="line"> <span class="hljs-type">vec3</span> f0;</span>
|
||
<span class="line"></span>
|
||
<span class="line"> <span class="hljs-comment">// The perceptual roughness is the roughness value set in MaterialInputs,</span></span>
|
||
<span class="line"> <span class="hljs-comment">// with extra processing:</span></span>
|
||
<span class="line"> <span class="hljs-comment">// - Clamped to safe values</span></span>
|
||
<span class="line"> <span class="hljs-comment">// - Filtered if specularAntiAliasing is enabled</span></span>
|
||
<span class="line"> <span class="hljs-comment">// This value is between 0.0 and 1.0.</span></span>
|
||
<span class="line"> <span class="hljs-type">float</span> perceptualRoughness;</span>
|
||
<span class="line"></span>
|
||
<span class="line"> <span class="hljs-comment">// The roughness value expected by BRDFs. This value is the square of</span></span>
|
||
<span class="line"> <span class="hljs-comment">// perceptualRoughness. This value is between 0.0 and 1.0.</span></span>
|
||
<span class="line"> <span class="hljs-type">float</span> roughness;</span>
|
||
<span class="line">};</span></code></pre>
|
||
<a class="target" name="lightdatastructure"> </a><a class="target" name="materialdefinitions/fragmentblock/customsurfaceshading/lightdatastructure"> </a><a class="target" name="toc4.4.3.2"> </a><h4>Light data structure</h4>
|
||
<pre class="listing tilde"><code><span class="line">struct LightData {</span>
|
||
<span class="line"> <span class="hljs-comment">// The color (.rgb) and pre-exposed intensity (.w) of the light.</span></span>
|
||
<span class="line"> <span class="hljs-comment">// The color is an RGB value in the linear sRGB color space.</span></span>
|
||
<span class="line"> <span class="hljs-comment">// The pre-exposed intensity is the intensity of the light multiplied by</span></span>
|
||
<span class="line"> <span class="hljs-comment">// the camera's exposure value.</span></span>
|
||
<span class="line"> <span class="hljs-type">vec4</span> colorIntensity;</span>
|
||
<span class="line"></span>
|
||
<span class="line"> <span class="hljs-comment">// The normalized light vector, in world space (direction from the</span></span>
|
||
<span class="line"> <span class="hljs-comment">// current fragment's position to the light).</span></span>
|
||
<span class="line"> <span class="hljs-type">vec3</span> l;</span>
|
||
<span class="line"></span>
|
||
<span class="line"> <span class="hljs-comment">// The dot product of the shading normal (with normal mapping applied)</span></span>
|
||
<span class="line"> <span class="hljs-comment">// and the light vector. This value is equal to the result of</span></span>
|
||
<span class="line"> <span class="hljs-comment">// saturate(dot(getWorldSpaceNormal(), lightData.l)).</span></span>
|
||
<span class="line"> <span class="hljs-comment">// This value is always between 0.0 and 1.0. When the value is <= 0.0,</span></span>
|
||
<span class="line"> <span class="hljs-comment">// the current fragment is not visible from the light and lighting</span></span>
|
||
<span class="line"> <span class="hljs-comment">// computations can be skipped.</span></span>
|
||
<span class="line"> <span class="hljs-type">float</span> NdotL;</span>
|
||
<span class="line"></span>
|
||
<span class="line"> <span class="hljs-comment">// The position of the light in world space.</span></span>
|
||
<span class="line"> <span class="hljs-type">vec3</span> worldPosition;</span>
|
||
<span class="line"></span>
|
||
<span class="line"> <span class="hljs-comment">// Attenuation of the light based on the distance from the current</span></span>
|
||
<span class="line"> <span class="hljs-comment">// fragment to the light in world space. This value between 0.0 and 1.0</span></span>
|
||
<span class="line"> <span class="hljs-comment">// is computed differently for each type of light (it's always 1.0 for</span></span>
|
||
<span class="line"> <span class="hljs-comment">// directional lights).</span></span>
|
||
<span class="line"> <span class="hljs-type">float</span> attenuation;</span>
|
||
<span class="line"></span>
|
||
<span class="line"> <span class="hljs-comment">// Visibility factor computed from shadow maps or other occlusion data</span></span>
|
||
<span class="line"> <span class="hljs-comment">// specific to the light being evaluated. This value is between 0.0 and</span></span>
|
||
<span class="line"> <span class="hljs-comment">// 1.0.</span></span>
|
||
<span class="line"> <span class="hljs-type">float</span> visibility;</span>
|
||
<span class="line">};</span></code></pre>
|
||
<a class="target" name="example"> </a><a class="target" name="materialdefinitions/fragmentblock/customsurfaceshading/example"> </a><a class="target" name="toc4.4.3.3"> </a><h4>Example</h4>
|
||
<p>
|
||
|
||
|
||
The material below shows how to use custom surface shading to implement a simplified toon shader:
|
||
|
||
</p><pre class="listing tilde"><code><span class="line">material {</span>
|
||
<span class="line"> name : Toon,</span>
|
||
<span class="line"> shadingModel : lit,</span>
|
||
<span class="line"> parameters : [</span>
|
||
<span class="line"> {</span>
|
||
<span class="line"> type : float3,</span>
|
||
<span class="line"> name : baseColor</span>
|
||
<span class="line"> }</span>
|
||
<span class="line"> ],</span>
|
||
<span class="line"> customSurfaceShading : <span class="hljs-literal">true</span></span>
|
||
<span class="line">}</span>
|
||
<span class="line"></span>
|
||
<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 = materialParams.baseColor;</span>
|
||
<span class="line"> }</span>
|
||
<span class="line"></span>
|
||
<span class="line"> <span class="hljs-type">vec3</span> surfaceShading(</span>
|
||
<span class="line"> <span class="hljs-keyword">const</span> MaterialInputs materialInputs,</span>
|
||
<span class="line"> <span class="hljs-keyword">const</span> ShadingData shadingData,</span>
|
||
<span class="line"> <span class="hljs-keyword">const</span> LightData lightData</span>
|
||
<span class="line"> ) {</span>
|
||
<span class="line"> <span class="hljs-comment">// Number of visible shade transitions</span></span>
|
||
<span class="line"> <span class="hljs-keyword">const</span> <span class="hljs-type">float</span> shades = <span class="hljs-number">5.0</span>;</span>
|
||
<span class="line"> <span class="hljs-comment">// Ambient intensity</span></span>
|
||
<span class="line"> <span class="hljs-keyword">const</span> <span class="hljs-type">float</span> ambient = <span class="hljs-number">0.1</span>;</span>
|
||
<span class="line"></span>
|
||
<span class="line"> <span class="hljs-type">float</span> toon = <span class="hljs-built_in">max</span>(<span class="hljs-built_in">ceil</span>(lightData.NdotL * shades) / shades, ambient);</span>
|
||
<span class="line"></span>
|
||
<span class="line"> <span class="hljs-comment">// Shadowing and attenuation</span></span>
|
||
<span class="line"> toon *= lightData.visibility * lightData.attenuation;</span>
|
||
<span class="line"></span>
|
||
<span class="line"> <span class="hljs-comment">// Color and intensity</span></span>
|
||
<span class="line"> <span class="hljs-type">vec3</span> light = lightData.colorIntensity.rgb * lightData.colorIntensity.w;</span>
|
||
<span class="line"></span>
|
||
<span class="line"> <span class="hljs-keyword">return</span> shadingData.diffuseColor * light * toon;</span>
|
||
<span class="line"> }</span>
|
||
<span class="line">}</span></code></pre><p>
|
||
|
||
The result can be seen in <a href="#figure_toonshading">figure 41</a>.
|
||
|
||
</p><p>
|
||
|
||
</p><center><div class="image" style=""><a href="images/screenshot_toon_shading.png" target="_blank"><img class="markdeep" src="images/screenshot_toon_shading.png"></a><center><span class="imagecaption"><a class="target" name="figure_toonshading"> </a><b style="font-style:normal;">Figure 41:</b> simple toon shading implemented with custom
|
||
surface shading</span></center></div></center>
|
||
|
||
<p></p>
|
||
<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"> Dimensions of the view's effective (physical) viewport in pixels: <code>width</code>, <code>height</code>, <code>1 / width</code>, <code>1 / height</code>. This might be different from <code>View::getViewport()</code> for instance because of added rendering guard-bands. </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 (see note below) </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"> [deprecated] The shift required to obtain API-level world space. Use getUserWorldPosition() instead </td></tr>
|
||
<tr><td style="text-align:left"> <strong class="asterisk">getUserWorldFromWorldMatrix()</strong> </td><td style="text-align:center"> float4×4 </td><td style="text-align:left"> Matrix that converts from world space to API-level (user) 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 as a remainder of 1 second. Yields a value between 0 and 1 </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">getUserTimeMod(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 use <code>getUserWorldFromWorldMatrix()</code> to transform <code>getWorldCameraPosition()</code>.</p></div>
|
||
|
||
<p></p>
|
||
<a class="target" name="materialglobals"> </a><a class="target" name="materialdefinitions/shaderpublicapis/materialglobals"> </a><a class="target" name="toc4.5.5"> </a><h3>Material globals</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">getMaterialGlobal0()</strong> </td><td style="text-align:center"> float4 </td><td style="text-align:left"> A vec4 visible by all materials, its value is set by <code>View::setMaterialGlobal(0, float4)</code>. Its default value is {0,0,0,1}. </td></tr>
|
||
<tr><td style="text-align:left"> <strong class="asterisk">getMaterialGlobal1()</strong> </td><td style="text-align:center"> float4 </td><td style="text-align:left"> A vec4 visible by all materials, its value is set by <code>View::setMaterialGlobal(1, float4)</code>. Its default value is {0,0,0,1}. </td></tr>
|
||
<tr><td style="text-align:left"> <strong class="asterisk">getMaterialGlobal2()</strong> </td><td style="text-align:center"> float4 </td><td style="text-align:left"> A vec4 visible by all materials, its value is set by <code>View::setMaterialGlobal(2, float4)</code>. Its default value is {0,0,0,1}. </td></tr>
|
||
<tr><td style="text-align:left"> <strong class="asterisk">getMaterialGlobal3()</strong> </td><td style="text-align:center"> float4 </td><td style="text-align:left"> A vec4 visible by all materials, its value is set by <code>View::setMaterialGlobal(3, float4)</code>. Its default value is {0,0,0,1}. </td></tr>
|
||
</tbody></table></div>
|
||
|
||
<p></p>
|
||
<a class="target" name="vertexonly"> </a><a class="target" name="materialdefinitions/shaderpublicapis/vertexonly"> </a><a class="target" name="toc4.5.6"> </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>
|
||
<tr><td style="text-align:left"> <strong class="asterisk">getVertexIndex()</strong> </td><td style="text-align:center"> int </td><td style="text-align:left"> Index of the current vertex </td></tr>
|
||
<tr><td style="text-align:left"> <strong class="asterisk">getEyeIndex()</strong> </td><td style="text-align:center"> int </td><td style="text-align:left"> Index of the eye being rendered, starting at 0 </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.7"> </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">getUserWorldPosition()</strong> </td><td style="text-align:center"> float3 </td><td style="text-align:left"> Position of the fragment in API-level (user) 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">getNormalizedViewportCoord()</strong> </td><td style="text-align:center"> float3 </td><td style="text-align:left"> Normalized user viewport position (i.e. NDC coordinates normalized to [0, 1] for the position, [1, 0] for the depth), can be used before <code>prepareMaterial()</code>). Because the user viewport is smaller than the actual physical viewport, these coordinates can be negative or superior to 1 in the non-visible area of the physical viewport. </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 and works best with the “Filmic” tone mapping operator </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 and works best with the “Filmic” tone mapping operator </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 use <code>getUserWorldPosition()</code>
|
||
or use <code>getUserWorldFromWorldMatrix()</code>. Note that API-level world-space coordinates should
|
||
never or rarely be used because they may not fit in a float3 or have severely reduced precision.</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 16</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><center><div class="tablecaption"><a class="target" name="table_matcflags"> </a><b style="font-style:normal;">Table 16:</b> List of <code>matc</code> flags</div></center></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>
|
||
<li class="minus"><code>fog</code>, used when global fog is applied to the scene
|
||
</li>
|
||
<li class="minus"><code>vsm</code>, used when VSM shadows are enabled and the object is a shadow receiver
|
||
</li>
|
||
<li class="minus"><code>ssr</code>, used when screen-space reflections are enabled in the View</li></ul>
|
||
|
||
<p></p><p>
|
||
|
||
Example:
|
||
</p><pre class="listing backtick"><code><span class="line">--variant-<span class="hljs-built_in">filter</span>=skinning,shadowReceiver</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>
|
||
<a class="target" name="samplerusageinmaterials"> </a><a class="target" name="samplerusageinmaterials"> </a><a class="target" name="toc7"> </a><h1>Sampler usage in Materials</h1>
|
||
<p>
|
||
|
||
|
||
The number of usable sampler parameters (e.g.: type is <code>sampler2d</code>) in materials is limited and
|
||
depends on the material properties, shading model, feature level and variant filter.
|
||
|
||
</p>
|
||
<a class="target" name="featurelevel1and2"> </a><a class="target" name="samplerusageinmaterials/featurelevel1and2"> </a><a class="target" name="toc7.1"> </a><h2>Feature level 1 and 2</h2>
|
||
<p>
|
||
|
||
|
||
<code>unlit</code> materials can use up to 12 samplers by default.
|
||
|
||
</p><p>
|
||
|
||
<code>lit</code> materials can use up to 9 samplers by default, however if <code>refractionMode</code> or <code>reflectionMode</code>
|
||
is set to <code>screenspace</code> that number is reduced to 8.
|
||
|
||
</p><p>
|
||
|
||
Finally if <code>variantFilter</code> contains the <code>fog</code> filter, an extra sampler is made available, such that
|
||
<code>unlit</code> materials can use up to 13 and <code>lit</code> materials up to 10 samplers by default.
|
||
|
||
</p>
|
||
<a class="target" name="featurelevel3"> </a><a class="target" name="samplerusageinmaterials/featurelevel3"> </a><a class="target" name="toc7.2"> </a><h2>Feature level 3</h2>
|
||
<p>
|
||
|
||
|
||
16 samplers are available.
|
||
|
||
</p><p>
|
||
|
||
</p><div class="admonition tip"><div class="admonition-title"> external samplers</div>
|
||
|
||
<p></p><p>
|
||
|
||
Be aware that <code>external</code> samplers account for 2 regular samplers.</p></div>
|
||
|
||
<p></p><p>
|
||
|
||
</p></span><div id="mdContextMenu" style="visibility:hidden"></div><div class="markdeepFooter"><i>formatted by <a href="https://casual-effects.com/markdeep" style="color:#999">Markdeep 1.13 </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.6/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script><script>window.alreadyProcessedMarkdeep||(document.body.style.visibility="visible")</script>
|
||
</body></html> |