2685 lines
309 KiB
HTML
2685 lines
309 KiB
HTML
<!DOCTYPE HTML>
|
||
<html lang="en" class="light sidebar-visible" dir="ltr">
|
||
<head>
|
||
<!-- Book generated using mdBook -->
|
||
<meta charset="UTF-8">
|
||
<title>Materials - Filament</title>
|
||
|
||
|
||
<!-- Custom HTML head -->
|
||
|
||
<meta name="description" content="">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||
<meta name="theme-color" content="#ffffff">
|
||
|
||
<link rel="shortcut icon" href="../favicon.png">
|
||
<link rel="stylesheet" href="../css/variables.css">
|
||
<link rel="stylesheet" href="../css/general.css">
|
||
<link rel="stylesheet" href="../css/chrome.css">
|
||
|
||
<!-- Fonts -->
|
||
<link rel="stylesheet" href="../FontAwesome/css/font-awesome.css">
|
||
<link rel="stylesheet" href="../fonts/fonts.css">
|
||
|
||
<!-- Highlight.js Stylesheets -->
|
||
<link rel="stylesheet" href="../highlight.css">
|
||
<link rel="stylesheet" href="../tomorrow-night.css">
|
||
<link rel="stylesheet" href="../ayu-highlight.css">
|
||
|
||
<!-- Custom theme stylesheets -->
|
||
|
||
<!-- MathJax -->
|
||
<script async src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
|
||
|
||
<!-- Provide site root to javascript -->
|
||
<script>
|
||
var path_to_root = "../";
|
||
var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "light" : "light";
|
||
</script>
|
||
<!-- Start loading toc.js asap -->
|
||
<script src="../toc.js"></script>
|
||
</head>
|
||
<body>
|
||
<div id="body-container">
|
||
<!-- Work around some values being stored in localStorage wrapped in quotes -->
|
||
<script>
|
||
try {
|
||
var theme = localStorage.getItem('mdbook-theme');
|
||
var sidebar = localStorage.getItem('mdbook-sidebar');
|
||
|
||
if (theme.startsWith('"') && theme.endsWith('"')) {
|
||
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
|
||
}
|
||
|
||
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
|
||
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
|
||
}
|
||
} catch (e) { }
|
||
</script>
|
||
|
||
<!-- Set the theme before any content is loaded, prevents flash -->
|
||
<script>
|
||
var theme;
|
||
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
|
||
if (theme === null || theme === undefined) { theme = default_theme; }
|
||
const html = document.documentElement;
|
||
html.classList.remove('light')
|
||
html.classList.add(theme);
|
||
html.classList.add("js");
|
||
</script>
|
||
|
||
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
|
||
|
||
<!-- Hide / unhide sidebar before it is displayed -->
|
||
<script>
|
||
var sidebar = null;
|
||
var sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
|
||
if (document.body.clientWidth >= 1080) {
|
||
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
|
||
sidebar = sidebar || 'visible';
|
||
} else {
|
||
sidebar = 'hidden';
|
||
}
|
||
sidebar_toggle.checked = sidebar === 'visible';
|
||
html.classList.remove('sidebar-visible');
|
||
html.classList.add("sidebar-" + sidebar);
|
||
</script>
|
||
|
||
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
|
||
<div style="display:flex;align-items:center;justify-content:center">
|
||
<img class="flogo" src="../images/filament_logo_small.png"></img>
|
||
</div>
|
||
<!-- populated by js -->
|
||
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
|
||
<noscript>
|
||
<iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
|
||
</noscript>
|
||
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
|
||
<div class="sidebar-resize-indicator"></div>
|
||
</div>
|
||
</nav>
|
||
|
||
<div id="page-wrapper" class="page-wrapper">
|
||
|
||
<div class="page">
|
||
<div id="menu-bar-hover-placeholder"></div>
|
||
<div id="menu-bar" class="menu-bar sticky">
|
||
<div class="left-buttons">
|
||
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
|
||
<i class="fa fa-bars"></i>
|
||
</label>
|
||
<!-- Filament: disable themes because the markdeep part does not look good for dark themes -->
|
||
<!--
|
||
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
|
||
<i class="fa fa-paint-brush"></i>
|
||
</button>
|
||
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
|
||
<li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
|
||
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
|
||
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
|
||
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
|
||
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
|
||
</ul>
|
||
-->
|
||
<button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
|
||
<i class="fa fa-search"></i>
|
||
</button>
|
||
</div>
|
||
|
||
<h1 class="menu-title">Filament</h1>
|
||
|
||
<div class="right-buttons">
|
||
<a href="https://github.com/google/filament" title="Git repository" aria-label="Git repository">
|
||
<i id="git-repository-button" class="fa fa-github"></i>
|
||
</a>
|
||
|
||
</div>
|
||
</div>
|
||
|
||
<div id="search-wrapper" class="hidden">
|
||
<form id="searchbar-outer" class="searchbar-outer">
|
||
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
|
||
</form>
|
||
<div id="searchresults-outer" class="searchresults-outer hidden">
|
||
<div id="searchresults-header" class="searchresults-header"></div>
|
||
<ul id="searchresults">
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
|
||
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
|
||
<script>
|
||
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
|
||
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
|
||
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
|
||
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
|
||
});
|
||
</script>
|
||
|
||
<div id="content" class="content">
|
||
<main>
|
||
<p><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{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,.md contents,.md .tocHeader,.md h1,.md h2,.md h3,.md h4,.md h5,.md h6,.md .shortTOC,.md .mediumTOC,.md .nonumberh1,.md .nonumberh2,.md .nonumberh3,.md .nonumberh4,.md .nonumberh5,.md .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.longtable th{top:0;position:sticky}.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 .img-attrib-container .img-attrib{font-size:50%;line-height:120%;writing-mode:vertical-rl;position:absolute;bottom:0;right:0;padding:8px 4px;color:#FFF;background-color:rgba(0,0,0,.3)}.md .img-attrib-container .img-attrib a{color:#FFF;text-decoration:none}.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"></p>
|
||
<style>img { max-width: 100%; }</style>
|
||
<p><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><div class="title"> Filament ⟨L:1⟩Materials Guide </div></p>
|
||
<div class="afterTitles"></div>
|
||
</p><p>
|
||
</p>
|
||
<div class="longTOC"><div class="tocHeader">Contents</div><p><a href="#" class="tocTop" target="_self">(Top)</a><br/>
|
||
<a href="#about" target="_self" class="level1"><span class="tocNumber">1 </span>⟨L:5⟩About</a><br/>
|
||
<a href="#about/authors" target="_self" class="level2"><span class="tocNumber">1.1 </span>⟨L:9⟩Authors</a><br/>
|
||
<a href="#overview" target="_self" class="level1"><span class="tocNumber">2 </span>⟨L:14⟩Overview</a><br/>
|
||
<a href="#overview/coreconcepts" target="_self" class="level2"><span class="tocNumber">2.1 </span>⟨L:20⟩Core concepts</a><br/>
|
||
<a href="#materialmodels" target="_self" class="level1"><span class="tocNumber">3 </span>⟨L:52⟩Material models</a><br/>
|
||
<a href="#materialmodels/litmodel" target="_self" class="level2"><span class="tocNumber">3.1 </span>⟨L:61⟩Lit model</a><br/>
|
||
<a href="#materialmodels/litmodel/basecolor" target="_self" class="level3"><span class="tocNumber">3.1.1 </span>⟨L:160⟩Base color</a><br/>
|
||
<a href="#materialmodels/litmodel/metallic" target="_self" class="level3"><span class="tocNumber">3.1.2 </span>⟨L:201⟩Metallic</a><br/>
|
||
<a href="#materialmodels/litmodel/roughness" target="_self" class="level3"><span class="tocNumber">3.1.3 </span>⟨L:219⟩Roughness</a><br/>
|
||
<a href="#materialmodels/litmodel/non-metals" target="_self" class="level3"><span class="tocNumber">3.1.4 </span>⟨L:226⟩Non-metals</a><br/>
|
||
<a href="#materialmodels/litmodel/metals" target="_self" class="level3"><span class="tocNumber">3.1.5 </span>⟨L:234⟩Metals</a><br/>
|
||
<a href="#materialmodels/litmodel/refraction" target="_self" class="level3"><span class="tocNumber">3.1.6 </span>⟨L:242⟩Refraction</a><br/>
|
||
<a href="#materialmodels/litmodel/reflectance" target="_self" class="level3"><span class="tocNumber">3.1.7 </span>⟨L:251⟩Reflectance</a><br/>
|
||
<a href="#materialmodels/litmodel/sheencolor" target="_self" class="level3"><span class="tocNumber">3.1.8 </span>⟨L:300⟩Sheen color</a><br/>
|
||
<a href="#materialmodels/litmodel/sheenroughness" target="_self" class="level3"><span class="tocNumber">3.1.9 </span>⟨L:319⟩Sheen roughness</a><br/>
|
||
<a href="#materialmodels/litmodel/clearcoat" target="_self" class="level3"><span class="tocNumber">3.1.10 </span>⟨L:331⟩Clear coat</a><br/>
|
||
<a href="#materialmodels/litmodel/clearcoatroughness" target="_self" class="level3"><span class="tocNumber">3.1.11 </span>⟨L:360⟩Clear coat roughness</a><br/>
|
||
<a href="#materialmodels/litmodel/anisotropy" target="_self" class="level3"><span class="tocNumber">3.1.12 </span>⟨L:371⟩Anisotropy</a><br/>
|
||
<a href="#materialmodels/litmodel/anisotropydirection" target="_self" class="level3"><span class="tocNumber">3.1.13 </span>⟨L:397⟩Anisotropy direction</a><br/>
|
||
<a href="#materialmodels/litmodel/ambientocclusion" target="_self" class="level3"><span class="tocNumber">3.1.14 </span>⟨L:415⟩Ambient occlusion</a><br/>
|
||
<a href="#materialmodels/litmodel/normal" target="_self" class="level3"><span class="tocNumber">3.1.15 </span>⟨L:425⟩Normal</a><br/>
|
||
<a href="#materialmodels/litmodel/bentnormal" target="_self" class="level3"><span class="tocNumber">3.1.16 </span>⟨L:444⟩Bent normal</a><br/>
|
||
<a href="#materialmodels/litmodel/clearcoatnormal" target="_self" class="level3"><span class="tocNumber">3.1.17 </span>⟨L:458⟩Clear coat normal</a><br/>
|
||
<a href="#materialmodels/litmodel/emissive" target="_self" class="level3"><span class="tocNumber">3.1.18 </span>⟨L:469⟩Emissive</a><br/>
|
||
<a href="#materialmodels/litmodel/post-lightingcolor" target="_self" class="level3"><span class="tocNumber">3.1.19 </span>⟨L:488⟩Post-lighting color</a><br/>
|
||
<a href="#materialmodels/litmodel/indexofrefraction" target="_self" class="level3"><span class="tocNumber">3.1.20 </span>⟨L:503⟩Index of refraction</a><br/>
|
||
<a href="#materialmodels/litmodel/transmission" target="_self" class="level3"><span class="tocNumber">3.1.21 </span>⟨L:559⟩Transmission</a><br/>
|
||
<a href="#materialmodels/litmodel/absorption" target="_self" class="level3"><span class="tocNumber">3.1.22 </span>⟨L:580⟩Absorption</a><br/>
|
||
<a href="#materialmodels/litmodel/micro-thicknessandthickness" target="_self" class="level3"><span class="tocNumber">3.1.23 </span>⟨L:617⟩Micro-thickness and thickness</a><br/>
|
||
<a href="#materialmodels/subsurfacemodel" target="_self" class="level2"><span class="tocNumber">3.2 </span>⟨L:650⟩Subsurface model</a><br/>
|
||
<a href="#materialmodels/subsurfacemodel/thickness" target="_self" class="level3"><span class="tocNumber">3.2.1 </span>⟨L:652⟩Thickness</a><br/>
|
||
<a href="#materialmodels/subsurfacemodel/subsurfacecolor" target="_self" class="level3"><span class="tocNumber">3.2.2 </span>⟨L:654⟩Subsurface color</a><br/>
|
||
<a href="#materialmodels/subsurfacemodel/subsurfacepower" target="_self" class="level3"><span class="tocNumber">3.2.3 </span>⟨L:656⟩Subsurface power</a><br/>
|
||
<a href="#materialmodels/clothmodel" target="_self" class="level2"><span class="tocNumber">3.3 </span>⟨L:658⟩Cloth model</a><br/>
|
||
<a href="#materialmodels/clothmodel/sheencolor" target="_self" class="level3"><span class="tocNumber">3.3.1 </span>⟨L:723⟩Sheen color</a><br/>
|
||
<a href="#materialmodels/clothmodel/subsurfacecolor" target="_self" class="level3"><span class="tocNumber">3.3.2 </span>⟨L:734⟩Subsurface color</a><br/>
|
||
<a href="#materialmodels/unlitmodel" target="_self" class="level2"><span class="tocNumber">3.4 </span>⟨L:749⟩Unlit model</a><br/>
|
||
<a href="#materialmodels/specularglossiness" target="_self" class="level2"><span class="tocNumber">3.5 </span>⟨L:780⟩Specular glossiness</a><br/>
|
||
<a href="#materialdefinitions" target="_self" class="level1"><span class="tocNumber">4 </span>⟨L:804⟩Material definitions</a><br/>
|
||
<a href="#materialdefinitions/format" target="_self" class="level2"><span class="tocNumber">4.1 </span>⟨L:816⟩Format</a><br/>
|
||
<a href="#materialdefinitions/format/differenceswithjson" target="_self" class="level3"><span class="tocNumber">4.1.1 </span>⟨L:839⟩Differences with JSON</a><br/>
|
||
<a href="#materialdefinitions/format/example" target="_self" class="level3"><span class="tocNumber">4.1.2 </span>⟨L:865⟩Example</a><br/>
|
||
<a href="#materialdefinitions/materialblock" target="_self" class="level2"><span class="tocNumber">4.2 </span>⟨L:906⟩Material block</a><br/>
|
||
<a href="#materialdefinitions/materialblock/general:name" target="_self" class="level3"><span class="tocNumber">4.2.1 </span>⟨L:911⟩General: name</a><br/>
|
||
<a href="#materialdefinitions/materialblock/general:featurelevel" target="_self" class="level3"><span class="tocNumber">4.2.2 </span>⟨L:932⟩General: featureLevel</a><br/>
|
||
<a href="#materialdefinitions/materialblock/general:shadingmodel" target="_self" class="level3"><span class="tocNumber">4.2.3 </span>⟨L:963⟩General: shadingModel</a><br/>
|
||
<a href="#materialdefinitions/materialblock/general:parameters" target="_self" class="level3"><span class="tocNumber">4.2.4 </span>⟨L:984⟩General: parameters</a><br/>
|
||
<a href="#materialdefinitions/materialblock/general:constants" target="_self" class="level3"><span class="tocNumber">4.2.5 </span>⟨L:1084⟩General: constants</a><br/>
|
||
<a href="#materialdefinitions/materialblock/general:variantfilter" target="_self" class="level3"><span class="tocNumber">4.2.6 </span>⟨L:1141⟩General: variantFilter</a><br/>
|
||
<a href="#materialdefinitions/materialblock/general:flipuv" target="_self" class="level3"><span class="tocNumber">4.2.7 </span>⟨L:1179⟩General: flipUV</a><br/>
|
||
<a href="#materialdefinitions/materialblock/general:linearfog" target="_self" class="level3"><span class="tocNumber">4.2.8 </span>⟨L:1198⟩General: linearFog</a><br/>
|
||
<a href="#materialdefinitions/materialblock/general:shadowfarattenuation" target="_self" class="level3"><span class="tocNumber">4.2.9 </span>⟨L:1216⟩General: shadowFarAttenuation</a><br/>
|
||
<a href="#materialdefinitions/materialblock/general:quality" target="_self" class="level3"><span class="tocNumber">4.2.10 </span>⟨L:1233⟩General: quality</a><br/>
|
||
<a href="#materialdefinitions/materialblock/general:instanced" target="_self" class="level3"><span class="tocNumber">4.2.11 </span>⟨L:1253⟩General: instanced</a><br/>
|
||
<a href="#materialdefinitions/materialblock/general:vertexdomaindevicejittered" target="_self" class="level3"><span class="tocNumber">4.2.12 </span>⟨L:1274⟩General: vertexDomainDeviceJittered</a><br/>
|
||
<a href="#materialdefinitions/materialblock/general:usedefaultdepthvariant" target="_self" class="level3"><span class="tocNumber">4.2.13 </span>⟨L:1297⟩General: useDefaultDepthVariant</a><br/>
|
||
<a href="#materialdefinitions/materialblock/vertexandattributes:requires" target="_self" class="level3"><span class="tocNumber">4.2.14 </span>⟨L:1336⟩Vertex and attributes: requires</a><br/>
|
||
<a href="#materialdefinitions/materialblock/vertexandattributes:variables" target="_self" class="level3"><span class="tocNumber">4.2.15 </span>⟨L:1378⟩Vertex and attributes: variables</a><br/>
|
||
<a href="#materialdefinitions/materialblock/vertexandattributes:vertexdomain" target="_self" class="level3"><span class="tocNumber">4.2.16 </span>⟨L:1442⟩Vertex and attributes: vertexDomain</a><br/>
|
||
<a href="#materialdefinitions/materialblock/vertexandattributes:interpolation" target="_self" class="level3"><span class="tocNumber">4.2.17 </span>⟨L:1469⟩Vertex and attributes: interpolation</a><br/>
|
||
<a href="#materialdefinitions/materialblock/blendingandtransparency:blending" target="_self" class="level3"><span class="tocNumber">4.2.18 </span>⟨L:1489⟩Blending and transparency: blending</a><br/>
|
||
<a href="#materialdefinitions/materialblock/blendingandtransparency:blendfunction" target="_self" class="level3"><span class="tocNumber">4.2.19 </span>⟨L:1531⟩Blending and transparency: blendFunction</a><br/>
|
||
<a href="#materialdefinitions/materialblock/blendingandtransparency:postlightingblending" target="_self" class="level3"><span class="tocNumber">4.2.20 </span>⟨L:1561⟩Blending and transparency: postLightingBlending</a><br/>
|
||
<a href="#materialdefinitions/materialblock/blendingandtransparency:transparency" target="_self" class="level3"><span class="tocNumber">4.2.21 </span>⟨L:1588⟩Blending and transparency: transparency</a><br/>
|
||
<a href="#materialdefinitions/materialblock/blendingandtransparency:maskthreshold" target="_self" class="level3"><span class="tocNumber">4.2.22 </span>⟨L:1627⟩Blending and transparency: maskThreshold</a><br/>
|
||
<a href="#materialdefinitions/materialblock/blendingandtransparency:refractionmode" target="_self" class="level3"><span class="tocNumber">4.2.23 </span>⟨L:1648⟩Blending and transparency: refractionMode</a><br/>
|
||
<a href="#materialdefinitions/materialblock/blendingandtransparency:refractiontype" target="_self" class="level3"><span class="tocNumber">4.2.24 </span>⟨L:1673⟩Blending and transparency: refractionType</a><br/>
|
||
<a href="#materialdefinitions/materialblock/rasterization:culling" target="_self" class="level3"><span class="tocNumber">4.2.25 </span>⟨L:1696⟩Rasterization: culling</a><br/>
|
||
<a href="#materialdefinitions/materialblock/rasterization:colorwrite" target="_self" class="level3"><span class="tocNumber">4.2.26 </span>⟨L:1714⟩Rasterization: colorWrite</a><br/>
|
||
<a href="#materialdefinitions/materialblock/rasterization:depthwrite" target="_self" class="level3"><span class="tocNumber">4.2.27 </span>⟨L:1731⟩Rasterization: depthWrite</a><br/>
|
||
<a href="#materialdefinitions/materialblock/rasterization:depthculling" target="_self" class="level3"><span class="tocNumber">4.2.28 </span>⟨L:1748⟩Rasterization: depthCulling</a><br/>
|
||
<a href="#materialdefinitions/materialblock/rasterization:doublesided" target="_self" class="level3"><span class="tocNumber">4.2.29 </span>⟨L:1766⟩Rasterization: doubleSided</a><br/>
|
||
<a href="#materialdefinitions/materialblock/rasterization:alphatocoverage" target="_self" class="level3"><span class="tocNumber">4.2.30 </span>⟨L:1795⟩Rasterization: alphaToCoverage</a><br/>
|
||
<a href="#materialdefinitions/materialblock/lighting:reflections" target="_self" class="level3"><span class="tocNumber">4.2.31 </span>⟨L:1826⟩Lighting: reflections</a><br/>
|
||
<a href="#materialdefinitions/materialblock/lighting:shadowmultiplier" target="_self" class="level3"><span class="tocNumber">4.2.32 </span>⟨L:1847⟩Lighting: shadowMultiplier</a><br/>
|
||
<a href="#materialdefinitions/materialblock/lighting:transparentshadow" target="_self" class="level3"><span class="tocNumber">4.2.33 </span>⟨L:1878⟩Lighting: transparentShadow</a><br/>
|
||
<a href="#materialdefinitions/materialblock/lighting:clearcoatiorchange" target="_self" class="level3"><span class="tocNumber">4.2.34 </span>⟨L:1914⟩Lighting: clearCoatIorChange</a><br/>
|
||
<a href="#materialdefinitions/materialblock/lighting:multibounceambientocclusion" target="_self" class="level3"><span class="tocNumber">4.2.35 </span>⟨L:1938⟩Lighting: multiBounceAmbientOcclusion</a><br/>
|
||
<a href="#materialdefinitions/materialblock/lighting:specularambientocclusion" target="_self" class="level3"><span class="tocNumber">4.2.36 </span>⟨L:1967⟩Lighting: specularAmbientOcclusion</a><br/>
|
||
<a href="#materialdefinitions/materialblock/anti-aliasing:specularantialiasing" target="_self" class="level3"><span class="tocNumber">4.2.37 </span>⟨L:1995⟩Anti-aliasing: specularAntiAliasing</a><br/>
|
||
<a href="#materialdefinitions/materialblock/anti-aliasing:specularantialiasingvariance" target="_self" class="level3"><span class="tocNumber">4.2.38 </span>⟨L:2016⟩Anti-aliasing: specularAntiAliasingVariance</a><br/>
|
||
<a href="#materialdefinitions/materialblock/anti-aliasing:specularantialiasingthreshold" target="_self" class="level3"><span class="tocNumber">4.2.39 </span>⟨L:2035⟩Anti-aliasing: specularAntiAliasingThreshold</a><br/>
|
||
<a href="#materialdefinitions/materialblock/shading:customsurfaceshading" target="_self" class="level3"><span class="tocNumber">4.2.40 </span>⟨L:2053⟩Shading: customSurfaceShading</a><br/>
|
||
<a href="#materialdefinitions/vertexblock" target="_self" class="level2"><span class="tocNumber">4.3 </span>⟨L:2073⟩Vertex block</a><br/>
|
||
<a href="#materialdefinitions/vertexblock/materialvertexinputs" target="_self" class="level3"><span class="tocNumber">4.3.1 </span>⟨L:2112⟩Material vertex inputs</a><br/>
|
||
<a href="#materialdefinitions/vertexblock/customvertexattributes" target="_self" class="level3"><span class="tocNumber">4.3.2 </span>⟨L:2143⟩Custom vertex attributes</a><br/>
|
||
<a href="#materialdefinitions/fragmentblock" target="_self" class="level2"><span class="tocNumber">4.4 </span>⟨L:2160⟩Fragment block</a><br/>
|
||
<a href="#materialdefinitions/fragmentblock/preparematerialfunction" target="_self" class="level3"><span class="tocNumber">4.4.1 </span>⟨L:2198⟩prepareMaterial function</a><br/>
|
||
<a href="#materialdefinitions/fragmentblock/materialfragmentinputs" target="_self" class="level3"><span class="tocNumber">4.4.2 </span>⟨L:2228⟩Material fragment inputs</a><br/>
|
||
<a href="#materialdefinitions/fragmentblock/customsurfaceshading" target="_self" class="level3"><span class="tocNumber">4.4.3 </span>⟨L:2278⟩Custom surface shading</a><br/>
|
||
<a href="#materialdefinitions/shaderpublicapis" target="_self" class="level2"><span class="tocNumber">4.5 </span>⟨L:2437⟩Shader public APIs</a><br/>
|
||
<a href="#materialdefinitions/shaderpublicapis/types" target="_self" class="level3"><span class="tocNumber">4.5.1 </span>⟨L:2439⟩Types</a><br/>
|
||
<a href="#materialdefinitions/shaderpublicapis/math" target="_self" class="level3"><span class="tocNumber">4.5.2 </span>⟨L:2461⟩Math</a><br/>
|
||
<a href="#materialdefinitions/shaderpublicapis/matrices" target="_self" class="level3"><span class="tocNumber">4.5.3 </span>⟨L:2473⟩Matrices</a><br/>
|
||
<a href="#materialdefinitions/shaderpublicapis/frameconstants" target="_self" class="level3"><span class="tocNumber">4.5.4 </span>⟨L:2487⟩Frame constants</a><br/>
|
||
<a href="#materialdefinitions/shaderpublicapis/materialglobals" target="_self" class="level3"><span class="tocNumber">4.5.5 </span>⟨L:2506⟩Material globals</a><br/>
|
||
<a href="#materialdefinitions/shaderpublicapis/vertexonly" target="_self" class="level3"><span class="tocNumber">4.5.6 </span>⟨L:2515⟩Vertex only</a><br/>
|
||
<a href="#materialdefinitions/shaderpublicapis/fragmentonly" target="_self" class="level3"><span class="tocNumber">4.5.7 </span>⟨L:2528⟩Fragment only</a><br/>
|
||
<a href="#compilingmaterials" target="_self" class="level1"><span class="tocNumber">5 </span>⟨L:2563⟩Compiling materials</a><br/>
|
||
<a href="#compilingmaterials/shadervalidation" target="_self" class="level2"><span class="tocNumber">5.1 </span>⟨L:2573⟩Shader validation</a><br/>
|
||
<a href="#compilingmaterials/flags" target="_self" class="level2"><span class="tocNumber">5.2 </span>⟨L:2588⟩Flags</a><br/>
|
||
<a href="#compilingmaterials/flags/—platform" target="_self" class="level3"><span class="tocNumber">5.2.1 </span>⟨L:2605⟩—platform</a><br/>
|
||
<a href="#compilingmaterials/flags/—api" target="_self" class="level3"><span class="tocNumber">5.2.2 </span>⟨L:2616⟩—api</a><br/>
|
||
<a href="#compilingmaterials/flags/—optimize-size" target="_self" class="level3"><span class="tocNumber">5.2.3 </span>⟨L:2627⟩—optimize-size</a><br/>
|
||
<a href="#compilingmaterials/flags/—reflect" target="_self" class="level3"><span class="tocNumber">5.2.4 </span>⟨L:2633⟩—reflect</a><br/>
|
||
<a href="#compilingmaterials/flags/—variant-filter" target="_self" class="level3"><span class="tocNumber">5.2.5 </span>⟨L:2659⟩—variant-filter</a><br/>
|
||
<a href="#handlingcolors" target="_self" class="level1"><span class="tocNumber">6 </span>⟨L:2690⟩Handling colors</a><br/>
|
||
<a href="#handlingcolors/linearcolors" target="_self" class="level2"><span class="tocNumber">6.1 </span>⟨L:2692⟩Linear colors</a><br/>
|
||
<a href="#handlingcolors/pre-multipliedalpha" target="_self" class="level2"><span class="tocNumber">6.2 </span>⟨L:2714⟩Pre-multiplied alpha</a><br/>
|
||
<a href="#samplerusageinmaterials" target="_self" class="level1"><span class="tocNumber">7 </span>⟨L:2728⟩Sampler usage in Materials</a><br/>
|
||
<a href="#samplerusageinmaterials/featurelevel1and2" target="_self" class="level2"><span class="tocNumber">7.1 </span>⟨L:2733⟩Feature level 1 and 2</a><br/>
|
||
<a href="#samplerusageinmaterials/featurelevel3" target="_self" class="level2"><span class="tocNumber">7.2 </span>⟨L:2743⟩Feature level 3</a><br/>
|
||
</p></div><section class="h1-section"><a class="target" name="about"> </a><a class="target" name="about"> </a><a class="target" name="toc1"> </a><h1 id="l5about"><a class="header" href="#l5about">⟨L:5⟩About</a></h1>
|
||
<p>
|
||
<p>This ⟨L:7⟩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>
|
||
</p>
|
||
<section class="h2-section"><a class="target" name="authors"> </a><a class="target" name="about/authors"> </a><a class="target" name="toc1.1"> </a><h2 id="l9authors"><a class="header" href="#l9authors">⟨L:9⟩Authors</a></h2>
|
||
<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://bsky.app/profile/pixelflinger.bsky.social">@pixelflinger</a></li></ul>
|
||
</p>
|
||
</section></section><section class="h1-section"><a class="target" name="overview"> </a><a class="target" name="overview"> </a><a class="target" name="toc2"> </a><h1 id="l14overview"><a class="header" href="#l14overview">⟨L:14⟩Overview</a></h1>
|
||
<p>
|
||
<p>Filament ⟨L:16⟩is a physically based rendering (PBR) engine for Android. Filament offers a customizable
|
||
material ⟨L:17⟩system that you can use to create both simple and complex materials. This document
|
||
describes ⟨L:18⟩all the features available to materials and how to create your own material.</p>
|
||
</p>
|
||
<section class="h2-section"><a class="target" name="coreconcepts"> </a><a class="target" name="overview/coreconcepts"> </a><a class="target" name="toc2.1"> </a><h2 id="l20core-concepts"><a class="header" href="#l20core-concepts">⟨L:20⟩Core concepts</a></h2>
|
||
<p>
|
||
<dl><dt><a class="target" name="overview/coreconcepts/def-material"> </a>Material⟨L:22⟩</dt><dd><p> ⟨L:23⟩A material defines the visual appearance of a surface. To completely describe and render a
|
||
surface, ⟨L:24⟩a material provides the following information:
|
||
</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></dd><dt><a class="target" name="overview/coreconcepts/def-materialmodel"> </a>Material ⟨L:31⟩model</dt><dd><p> ⟨L:32⟩Also called <em class="underscore">shading model</em> or <em class="underscore">lighting model</em>, the material model defines the intrinsic
|
||
properties ⟨L:33⟩of a surface. These properties have a direct influence on the way lighting is
|
||
computed ⟨L:34⟩and therefore on the appearance of a surface.
|
||
</p></dd><dt><a class="target" name="overview/coreconcepts/def-materialdefinition"> </a>Material ⟨L:36⟩definition</dt><dd><p> ⟨L:37⟩A text file that describes all the information required by a material. This is the file that you
|
||
will ⟨L:38⟩directly author to create new materials.
|
||
</p></dd><dt><a class="target" name="overview/coreconcepts/def-materialpackage"> </a>Material ⟨L:40⟩package</dt><dd><p> ⟨L:41⟩At runtime, materials are loaded from <em class="underscore">material packages</em> compiled from material definitions
|
||
using ⟨L:42⟩the <code>matc</code> tool. A material package contains all the information required to describe a
|
||
material, ⟨L:43⟩and shaders generated for the target runtime platforms. This is necessary because
|
||
different ⟨L:44⟩platforms (Android, macOS, Linux, etc.) use different graphics APIs or different
|
||
variants ⟨L:45⟩of similar graphics APIs (OpenGL vs OpenGL ES for instance).
|
||
</p></dd><dt><a class="target" name="overview/coreconcepts/def-materialinstance"> </a>Material ⟨L:47⟩instance</dt><dd><p> ⟨L:48⟩A material instance is a reference to a material and a set of values for the different values of
|
||
that ⟨L:49⟩material. Material instances are not covered in this document as they are created and
|
||
manipulated ⟨L:50⟩directly from code using Filament's APIs.
|
||
</p></dd></dl></p>
|
||
</section></section><section class="h1-section"><a class="target" name="materialmodels"> </a><a class="target" name="materialmodels"> </a><a class="target" name="toc3"> </a><h1 id="l52material-models"><a class="header" href="#l52material-models">⟨L:52⟩Material models</a></h1>
|
||
<p>
|
||
<p>Filament ⟨L:54⟩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>
|
||
<section class="h2-section"><a class="target" name="litmodel"> </a><a class="target" name="materialmodels/litmodel"> </a><a class="target" name="toc3.1"> </a><h2 id="l61lit-model"><a class="header" href="#l61lit-model">⟨L:61⟩Lit model</a></h2>
|
||
<p>
|
||
<p>The ⟨L:63⟩lit model is Filament's standard material model. This physically-based shading model was
|
||
designed ⟨L:64⟩after to offer good interoperability with other common tools and engines such as <em class="underscore">Unity 5</em>,
|
||
<em class="underscore">Unreal ⟨L:65⟩Engine 4</em>, <em class="underscore">Substance Designer</em> or <em class="underscore">Marmoset Toolbag</em>.</p>
|
||
</p><p>
|
||
This ⟨L:67⟩material model can be used to describe many non-metallic surfaces (<em class="underscore">dielectrics</em>)
|
||
or ⟨L:68⟩metallic surfaces (<em class="underscore">conductors</em>).
|
||
</p><p>
|
||
The ⟨L:70⟩appearance of a material using the standard model is controlled using the properties described
|
||
in ⟨L:71⟩<a href="#table_standardproperties" target="_self">table 1</a>.
|
||
</p><p>
|
||
<div class='table'>
|
||
<a class="target" name="table_standardproperties"> </a><table class="table longtable"><tr><th style="text-align:right"> Property ⟨L:74⟩ </th><th style="text-align:left"> Definition </th></tr>
|
||
<tr><td style="text-align:right"> <strong class="asterisk">baseColor</strong> ⟨L:76⟩ </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">roughness</strong> ⟨L:77⟩ </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">metallic</strong> ⟨L:78⟩ </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">reflectance</strong> ⟨L:79⟩ </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">ambientOcclusion</strong> ⟨L:80⟩ </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">clearCoat</strong> ⟨L:81⟩ </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> ⟨L:82⟩ </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">clearCoatNormal</strong> ⟨L:83⟩ </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">anisotropy</strong> ⟨L:84⟩ </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> ⟨L:85⟩ </td><td style="text-align:left"> Local surface direction in tangent space </td></tr>
|
||
<tr><td style="text-align:right"> <strong class="asterisk">thickness</strong> ⟨L:86⟩ </td><td style="text-align:left"> Thickness of the solid volume of refractive objects </td></tr>
|
||
<tr><td style="text-align:right"> <strong class="asterisk">sheenColor</strong> ⟨L:87⟩ </td><td style="text-align:left"> Strength of the sheen layer </td></tr>
|
||
<tr><td style="text-align:right"> <strong class="asterisk">sheenRoughness</strong> ⟨L:88⟩ </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">emissive</strong> ⟨L:89⟩ </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">normal</strong> ⟨L:90⟩ </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">postLightingColor</strong> ⟨L:91⟩ </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">absorption</strong> ⟨L:92⟩ </td><td style="text-align:left"> Absorption factor for refractive objects </td></tr>
|
||
<tr><td style="text-align:right"> <strong class="asterisk">transmission</strong> ⟨L:93⟩ </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">ior</strong> ⟨L:94⟩ </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">microThickness</strong> ⟨L:95⟩ </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">bentNormal</strong> ⟨L:96⟩ </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">shadowStrength</strong> ⟨L:97⟩ </td><td style="text-align:left"> Strength factor between 0 and 1 for all shadows received by this material </td></tr>
|
||
</table><center><div class="tablecaption"><b style="font-style:normal;">Table 1:</b> Properties of the standard model</div></center></div>
|
||
</p><p>
|
||
The ⟨L:100⟩type and range of each property is described in <a href="#table_standardpropertiestypes" target="_self">table 2</a>.
|
||
<div class='table'>
|
||
<a class="target" name="table_standardpropertiestypes"> </a><table class="table longtable"><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>
|
||
</table><center><div class="tablecaption"><b style="font-style:normal;">Table 2:</b> Range and type of the standard model's properties</div></center></div>
|
||
</p><p>
|
||
<div class="admonition ⟨L:128⟩note"><div class="admonition-title"> About linear RGB</div>
|
||
</p><p>
|
||
Several ⟨L:129⟩material model properties expect RGB colors. Filament materials use RGB colors in linear
|
||
space ⟨L:130⟩and you must take proper care of supplying colors in that space. See the Linear colors
|
||
section ⟨L:131⟩for more information.</div>
|
||
</p><p>
|
||
<div class="admonition ⟨L:133⟩note"><div class="admonition-title"> About pre-multiplied RGB</div>
|
||
</p><p>
|
||
Filament ⟨L:134⟩materials expect colors to use pre-multiplied alpha. See the Pre-multiplied alpha
|
||
section ⟨L:135⟩for more information.</div>
|
||
</p><p>
|
||
<div class="admonition ⟨L:137⟩note"><div class="admonition-title"> About <code>absorption</code></div>
|
||
</p><p>
|
||
The ⟨L:138⟩light attenuation through the material is defined as \(e^{-absorption \cdot distance}\),
|
||
and ⟨L:139⟩the distance depends on the <code>thickness</code> parameter. If <code>thickness</code> is not provided, then
|
||
the ⟨L:140⟩<code>absorption</code> parameter is used directly and the light attenuation through the material
|
||
becomes ⟨L:141⟩\(1 - absorption\). To obtain a certain color at a desired distance, the above
|
||
equation ⟨L:142⟩can be inverted such as \(absorption = -\frac{ln(color)}{distance}\).</div>
|
||
</p><p>
|
||
<div class="admonition ⟨L:144⟩note"><div class="admonition-title"> About <code>ior</code> and <code>reflectance</code></div>
|
||
</p><p>
|
||
The ⟨L:145⟩index of refraction (IOR) and the reflectance represent the same physical attribute,
|
||
therefore ⟨L:146⟩they don't need to be both specified. Typically, only the reflectance is specified,
|
||
and ⟨L:147⟩the IOR is deduced automatically. When only the IOR is specified, the reflectance is then
|
||
deduced ⟨L:148⟩automatically. It is possible to specify both, in which case their values are kept
|
||
as-is, ⟨L:149⟩which can lead to physically impossible materials, however, this might be desirable
|
||
for ⟨L:150⟩artistic reasons.</div>
|
||
</p><p>
|
||
<div class="admonition ⟨L:152⟩note"><div class="admonition-title"> About <code>thickness</code> and <code>microThickness</code> for refraction</div>
|
||
</p><p>
|
||
<code>thickness</code> ⟨L:153⟩represents the thickness of solid objects in the direction of the normal, for
|
||
satisfactory ⟨L:154⟩results, this should be provided per fragment (e.g.: as a texture) or at least per
|
||
vertex. ⟨L:155⟩<code>microThickness</code> represent the thickness of the thin layer of an object, and can
|
||
generally ⟨L:156⟩be provided as a constant value. For example, a 1mm thin hollow sphere of radius 1m,
|
||
would ⟨L:157⟩have a <code>thickness</code> of 1 and a <code>microThickness</code> of 0.001. Currently <code>thickness</code> is not
|
||
used ⟨L:158⟩when <code>refractionType</code> is set to <code>thin</code>.</div>
|
||
</p>
|
||
<section class="h3-section"><a class="target" name="basecolor"> </a><a class="target" name="materialmodels/litmodel/basecolor"> </a><a class="target" name="toc3.1.1"> </a><h3 id="l160base-color"><a class="header" href="#l160base-color">⟨L:160⟩Base color</a></h3>
|
||
<p>
|
||
<p>The ⟨L:162⟩<code>baseColor</code> property defines the perceived color of an object (sometimes called albedo). The
|
||
effect ⟨L:163⟩of <code>baseColor</code> depends on the nature of the surface, controlled by the <code>metallic</code> property
|
||
explained ⟨L:164⟩in the Metallic section.</p>
|
||
</p><p>
|
||
<dl><dt><a class="target" name="materialmodels/litmodel/basecolor/def-non-metals(dielectrics)"> </a>Non-metals ⟨L:166⟩(dielectrics)</dt><dd><p> ⟨L:167⟩Defines the diffuse color of the surface. Real-world values are typically found in the range
|
||
\([10..240]\) ⟨L:168⟩if the value is encoded between 0 and 255, or in the range \([0.04..0.94]\) between 0
|
||
and ⟨L:169⟩1. Several examples of base colors for non-metallic surfaces can be found in
|
||
table ⟨L:170⟩[baseColorsDielectrics].
|
||
</p></dd></dl><div class='table'>
|
||
<a class="target" name="table_basecolorsdielectrics"> </a><table class="table"><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>
|
||
</table><center><div class="tablecaption"><b style="font-style:normal;">Table 3:</b> <code>baseColor</code> for common non-metals</div></center></div>
|
||
</p><p>
|
||
<dl><dt><a class="target" name="materialmodels/litmodel/basecolor/def-metals(conductors)"> </a>Metals ⟨L:184⟩(conductors)</dt><dd><p> ⟨L:185⟩Defines the specular color of the surface. Real-world values are typically found in the range
|
||
\([170..255]\) ⟨L:186⟩if the value is encoded between 0 and 255, or in the range \([0.66..1.0]\) between 0 and
|
||
</p><p>
|
||
<ol start=1>
|
||
<li class="number">Several examples of base colors for metallic surfaces can be found in <a href="#table_basecolorsconductors" target="_self">table 4</a>.</li></ol>
|
||
</p></dd></dl><div class='table'>
|
||
<a class="target" name="table_basecolorsconductors"> </a><table class="table"><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>
|
||
</table><center><div class="tablecaption"><b style="font-style:normal;">Table 4:</b> <code>baseColor</code> for common metals</div></center></div>
|
||
</p>
|
||
</section><section class="h3-section"><a class="target" name="metallic"> </a><a class="target" name="materialmodels/litmodel/metallic"> </a><a class="target" name="toc3.1.2"> </a><h3 id="l201metallic"><a class="header" href="#l201metallic">⟨L:201⟩Metallic</a></h3>
|
||
<p>
|
||
<p>The ⟨L:203⟩<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>) ⟨L:204⟩surface. This property should be used as a binary value, set to either 0 or 1.
|
||
Intermediate ⟨L:205⟩values are only truly useful to create transitions between different types of surfaces
|
||
when ⟨L:206⟩using textures.</p>
|
||
</p><p>
|
||
This ⟨L:208⟩property can dramatically change the appearance of a surface. Non-metallic surfaces have
|
||
chromatic ⟨L:209⟩diffuse reflection and achromatic specular reflection (reflected light does not change
|
||
color). ⟨L:210⟩Metallic surfaces do not have any diffuse reflection and chromatic specular reflection
|
||
(reflected ⟨L:211⟩light takes on the color of the surfaced as defined by <code>baseColor</code>).
|
||
</p><p>
|
||
The ⟨L:213⟩effect of <code>metallic</code> is shown in figure ? (click on the image to see a
|
||
larger ⟨L:214⟩version).
|
||
</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">Figure ⟨L:216⟩[metallicProperty]: <code>metallic</code> varying from 0.0
|
||
(left) ⟨L:217⟩to 1.0 (right)</span></center></div></center>
|
||
</p>
|
||
</section><section class="h3-section"><a class="target" name="roughness"> </a><a class="target" name="materialmodels/litmodel/roughness"> </a><a class="target" name="toc3.1.3"> </a><h3 id="l219roughness"><a class="header" href="#l219roughness">⟨L:219⟩Roughness</a></h3>
|
||
<p>
|
||
<p>The ⟨L:221⟩<code>roughness</code> property controls the perceived smoothness of the surface. When <code>roughness</code> is set
|
||
to ⟨L:222⟩0, the surface is perfectly smooth and highly glossy. The rougher a surface is, the “blurrier”
|
||
the ⟨L:223⟩reflections are. This property is often called <em class="underscore">glossiness</em> in other engines and tools, and is
|
||
simply ⟨L:224⟩the opposite of the roughness (<code>roughness = 1 - glossiness</code>).</p>
|
||
</p>
|
||
</section><section class="h3-section"><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 id="l226non-metals"><a class="header" href="#l226non-metals">⟨L:226⟩Non-metals</a></h3>
|
||
<p>
|
||
<p>The ⟨L:228⟩effect of <code>roughness</code> on non-metallic surfaces is shown in figure ? (click
|
||
on ⟨L:229⟩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">Figure ⟨L:231⟩[roughnessProperty]: Dielectric <code>roughness</code> varying from 0.0
|
||
(left) ⟨L:232⟩to 1.0 (right)</span></center></div></center>
|
||
</p>
|
||
</section><section class="h3-section"><a class="target" name="metals"> </a><a class="target" name="materialmodels/litmodel/metals"> </a><a class="target" name="toc3.1.5"> </a><h3 id="l234metals"><a class="header" href="#l234metals">⟨L:234⟩Metals</a></h3>
|
||
<p>
|
||
<p>The ⟨L:236⟩effect of <code>roughness</code> on metallic surfaces is shown in figure ?
|
||
(click ⟨L:237⟩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">Figure ⟨L:239⟩[roughnessConductorProperty]: Conductor <code>roughness</code> varying from 0.0
|
||
(left) ⟨L:240⟩to 1.0 (right)</span></center></div></center>
|
||
</p>
|
||
</section><section class="h3-section"><a class="target" name="refraction"> </a><a class="target" name="materialmodels/litmodel/refraction"> </a><a class="target" name="toc3.1.6"> </a><h3 id="l242refraction"><a class="header" href="#l242refraction">⟨L:242⟩Refraction</a></h3>
|
||
<p>
|
||
<p>When ⟨L:244⟩refraction through an object is enabled (using a <code>refractonType</code> of <code>thin</code> or <code>solid</code>), the
|
||
<code>roughness</code> ⟨L:245⟩property will also affect the refractions, as shown in figure ? ⟨L:246⟩(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">Figure ⟨L:248⟩[roughnessRefractionProperty]: Refractive sphere with <code>roughness</code> varying from 0.0
|
||
(left) ⟨L:249⟩to 1.0 (right)</span></center></div></center>
|
||
</p>
|
||
</section><section class="h3-section"><a class="target" name="reflectance"> </a><a class="target" name="materialmodels/litmodel/reflectance"> </a><a class="target" name="toc3.1.7"> </a><h3 id="l251reflectance"><a class="header" href="#l251reflectance">⟨L:251⟩Reflectance</a></h3>
|
||
<p>
|
||
<p>The ⟨L:253⟩<code>reflectance</code> property only affects non-metallic surfaces. This property can be used to control
|
||
the ⟨L:254⟩specular intensity and index of refraction of materials. This value is defined
|
||
between ⟨L:255⟩0 and 1 and represents a remapping of a percentage of reflectance. For instance, the
|
||
default ⟨L:256⟩value of 0.5 corresponds to a reflectance of 4%. Values below 0.35 (2% reflectance) should
|
||
be ⟨L:257⟩avoided as no real-world materials have such low reflectance.</p>
|
||
</p><p>
|
||
The ⟨L:259⟩effect of <code>reflectance</code> on non-metallic surfaces is shown in figure ?
|
||
(click ⟨L:260⟩on the image to see a larger version).
|
||
</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">Figure ⟨L:262⟩[reflectanceProperty]: <code>reflectance</code> varying from 0.0 (left)
|
||
to ⟨L:263⟩1.0 (right)</span></center></div></center>
|
||
</p><p>
|
||
Figure ⟨L:265⟩[reflectance] shows common values and how they relate to the mapping function.
|
||
</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">Figure ⟨L:267⟩[reflectance]: Common reflectance values</span></center></div></center>
|
||
</p><p>
|
||
Table ⟨L:269⟩[commonMatReflectance] describes acceptable reflectance values for various types of materials
|
||
(no ⟨L:270⟩real world material has a value under 2%).
|
||
</p><p>
|
||
<div class='table'>
|
||
<a class="target" name="table_commonmatreflectance"> </a><table class="table"><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>
|
||
</table><center><div class="tablecaption"><b style="font-style:normal;">Table 5:</b> Reflectance of common materials</div></center></div>
|
||
</p><p>
|
||
Note ⟨L:288⟩that the <code>reflectance</code> property also defines the index of refraction of the surface.
|
||
When ⟨L:289⟩this property is defined it is not necessary to define the <code>ior</code> property. Setting
|
||
either ⟨L:290⟩of these properties will automatically compute the other property. It is possible
|
||
to ⟨L:291⟩specify both, in which case their values are kept as-is, which can lead to physically
|
||
impossible ⟨L:292⟩materials, however, this might be desirable for artistic reasons.
|
||
</p><p>
|
||
The ⟨L:294⟩<code>reflectance</code> property is designed as a normalized property in the range 0..1 which makes
|
||
it ⟨L:295⟩easy to define from a texture.
|
||
</p><p>
|
||
See ⟨L:297⟩section <a href="#toc3.1.20" target="_self">3.1.20</a> for more information about the <code>ior</code> property and refractive
|
||
indices.⟨L:298⟩
|
||
</p>
|
||
</section><section class="h3-section"><a class="target" name="sheencolor"> </a><a class="target" name="materialmodels/litmodel/sheencolor"> </a><a class="target" name="toc3.1.8"> </a><h3 id="l300sheen-color"><a class="header" href="#l300sheen-color">⟨L:300⟩Sheen color</a></h3>
|
||
<p>
|
||
<p>The ⟨L:302⟩sheen color controls the color appearance and strength of an optional sheen layer on top of the
|
||
base ⟨L:303⟩layer described by the properties above. The sheen layer always sits below the clear coat layer
|
||
if ⟨L:304⟩such a layer is present.</p>
|
||
</p><p>
|
||
The ⟨L:306⟩sheen layer can be used to represent cloth and fabric materials. Please refer to
|
||
section ⟨L:307⟩[Cloth model] for more information about cloth and fabric materials.
|
||
</p><p>
|
||
The ⟨L:309⟩effect of <code>sheenColor</code> is shown in figure ?
|
||
(click ⟨L:310⟩on the image to see a larger version).
|
||
</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">Figure ⟨L:312⟩[materialSheenColor]: Different sheen colors</span></center></div></center>
|
||
</p><p>
|
||
<div class="admonition ⟨L:314⟩note">If ⟨L:315⟩you do not need the other properties offered by the standard lit material model but want to
|
||
create ⟨L:316⟩a cloth-like or fabric-like appearance, it is more efficient to use the dedicated cloth
|
||
model ⟨L:317⟩described in section <a href="#toc3.3" target="_self">3.3</a>.</div>
|
||
</p>
|
||
</section><section class="h3-section"><a class="target" name="sheenroughness"> </a><a class="target" name="materialmodels/litmodel/sheenroughness"> </a><a class="target" name="toc3.1.9"> </a><h3 id="l319sheen-roughness"><a class="header" href="#l319sheen-roughness">⟨L:319⟩Sheen roughness</a></h3>
|
||
<p>
|
||
<p>The ⟨L:321⟩<code>sheenRoughness</code> property is similar to the <code>roughness</code> property but applies only to the
|
||
sheen ⟨L:322⟩layer.</p>
|
||
</p><p>
|
||
The ⟨L:324⟩effect of <code>sheenRoughness</code> on a rough metal is shown in figure ?
|
||
(click ⟨L:325⟩on the image to see a larger version). In this picture, the base layer is a dark blue, with
|
||
<code>metallic</code> ⟨L:326⟩set to <code>0.0</code> and <code>roughness</code> set to <code>1.0</code>.
|
||
</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">Figure ⟨L:328⟩[sheenRoughnessProperty]: <code>sheenRoughness</code> varying from 0.0
|
||
(left) ⟨L:329⟩to 1.0 (right)</span></center></div></center>
|
||
</p>
|
||
</section><section class="h3-section"><a class="target" name="clearcoat"> </a><a class="target" name="materialmodels/litmodel/clearcoat"> </a><a class="target" name="toc3.1.10"> </a><h3 id="l331clear-coat"><a class="header" href="#l331clear-coat">⟨L:331⟩Clear coat</a></h3>
|
||
<p>
|
||
<p>Multi-layer ⟨L:333⟩materials are fairly common, particularly materials with a thin translucent
|
||
layer ⟨L:334⟩over a base layer. Real world examples of such materials include car paints, soda cans,
|
||
lacquered ⟨L:335⟩wood and acrylic.</p>
|
||
</p><p>
|
||
The ⟨L:337⟩<code>clearCoat</code> property can be used to describe materials with two layers. The clear coat layer
|
||
will ⟨L:338⟩always be isotropic and dielectric.
|
||
</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">Figure ⟨L:340⟩[clearCoat]: Comparison of a carbon-fiber material under the standard material model
|
||
(left) ⟨L:341⟩and the clear coat model (right)</span></center></div></center>
|
||
</p><p>
|
||
The ⟨L:343⟩<code>clearCoat</code> property controls the strength of the clear coat layer. This should be treated as a
|
||
binary ⟨L:344⟩value, set to either 0 or 1. Intermediate values are useful to control transitions between
|
||
parts ⟨L:345⟩of the surface that have a clear coat layers and parts that don't.
|
||
</p><p>
|
||
The ⟨L:347⟩effect of <code>clearCoat</code> on a rough metal is shown in figure ?
|
||
(click ⟨L:348⟩on the image to see a larger version).
|
||
</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">Figure ⟨L:350⟩[clearCoatProperty]: <code>clearCoat</code> varying from 0.0
|
||
(left) ⟨L:351⟩to 1.0 (right)</span></center></div></center>
|
||
</p><p>
|
||
<div class="admonition ⟨L:353⟩warning">The ⟨L:354⟩clear coat layer effectively doubles the cost of specular computations. Do not assign a
|
||
value, ⟨L:355⟩even 0.0, to the clear coat property if you don't need this second layer.</div>
|
||
</p><p>
|
||
<div class="admonition ⟨L:357⟩note">The ⟨L:358⟩clear coat layer is added on top of the sheen layer if present.</div>
|
||
</p>
|
||
</section><section class="h3-section"><a class="target" name="clearcoatroughness"> </a><a class="target" name="materialmodels/litmodel/clearcoatroughness"> </a><a class="target" name="toc3.1.11"> </a><h3 id="l360clear-coat-roughness"><a class="header" href="#l360clear-coat-roughness">⟨L:360⟩Clear coat roughness</a></h3>
|
||
<p>
|
||
<p>The ⟨L:362⟩<code>clearCoatRoughness</code> property is similar to the <code>roughness</code> property but applies only to the
|
||
clear ⟨L:363⟩coat layer.</p>
|
||
</p><p>
|
||
The ⟨L:365⟩effect of <code>clearCoatRoughness</code> on a rough metal is shown in figure ?
|
||
(click ⟨L:366⟩on the image to see a larger version).
|
||
</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">Figure ⟨L:368⟩[clearCoatRoughnessProperty]: <code>clearCoatRoughness</code> varying from 0.0
|
||
(left) ⟨L:369⟩to 1.0 (right)</span></center></div></center>
|
||
</p>
|
||
</section><section class="h3-section"><a class="target" name="anisotropy"> </a><a class="target" name="materialmodels/litmodel/anisotropy"> </a><a class="target" name="toc3.1.12"> </a><h3 id="l371anisotropy"><a class="header" href="#l371anisotropy">⟨L:371⟩Anisotropy</a></h3>
|
||
<p>
|
||
<p>Many ⟨L:373⟩real-world materials, such as brushed metal, can only be replicated using an anisotropic
|
||
reflectance ⟨L:374⟩model. A material can be changed from the default isotropic model to an anisotropic
|
||
model ⟨L:375⟩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">Figure ⟨L:377⟩[anisotropic]: Comparison of isotropic material
|
||
(left) ⟨L:378⟩and anistropic material (right)</span></center></div></center>
|
||
</p><p>
|
||
The ⟨L:380⟩effect of <code>anisotropy</code> on a rough metal is shown in figure ?
|
||
(click ⟨L:381⟩on the image to see a larger version).
|
||
</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">Figure ⟨L:383⟩[anisotropyProperty]: <code>anisotropy</code> varying from 0.0
|
||
(left) ⟨L:384⟩to 1.0 (right)</span></center></div></center>
|
||
</p><p>
|
||
The ⟨L:386⟩figure ? below shows how the direction of the anisotropic highlights can be
|
||
controlled ⟨L:387⟩by using either positive or negative values: positive values define anisotropy in the
|
||
tangent ⟨L:388⟩direction and negative values in the bitangent direction.
|
||
</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">Figure ⟨L:390⟩[anisotropyDir]: Positive (left) vs negative
|
||
(right) ⟨L:391⟩<code>anisotropy</code> values</span></center></div></center>
|
||
</p><p>
|
||
<div class="admonition ⟨L:393⟩tip">The ⟨L:394⟩anisotropic material model is slightly more expensive than the standard material model. Do
|
||
not ⟨L:395⟩assign a value (even 0.0) to the <code>anisotropy</code> property if you don't need anisotropy.</div>
|
||
</p>
|
||
</section><section class="h3-section"><a class="target" name="anisotropydirection"> </a><a class="target" name="materialmodels/litmodel/anisotropydirection"> </a><a class="target" name="toc3.1.13"> </a><h3 id="l397anisotropy-direction"><a class="header" href="#l397anisotropy-direction">⟨L:397⟩Anisotropy direction</a></h3>
|
||
<p>
|
||
<p>The ⟨L:399⟩<code>anisotropyDirection</code> property defines the direction of the surface at a given point and thus
|
||
control ⟨L:400⟩the shape of the specular highlights. It is specified as vector of 3 values that usually
|
||
come ⟨L:401⟩from a texture, encoding the directions local to the surface in tangent space. Because the
|
||
direction ⟨L:402⟩is in tangent space, the Z component should be set to 0.</p>
|
||
</p><p>
|
||
The ⟨L:404⟩effect of <code>anisotropyDirection</code> on a metal is shown in figure ?
|
||
(click ⟨L:405⟩on the image to see a larger version).
|
||
</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">Figure ⟨L:407⟩[anisotropyDirectionProperty]: Anisotropic metal rendered
|
||
with ⟨L:408⟩a direction map</span></center></div></center>
|
||
</p><p>
|
||
The ⟨L:410⟩result shown in figure ? was obtained using the direction map shown
|
||
in ⟨L:411⟩figure ?.
|
||
</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">Figure ⟨L:413⟩[anisotropyDirectionProperty]: Example of Lighting: specularAmbientOcclusiona direction map</span></center></div></center>
|
||
</p>
|
||
</section><section class="h3-section"><a class="target" name="ambientocclusion"> </a><a class="target" name="materialmodels/litmodel/ambientocclusion"> </a><a class="target" name="toc3.1.14"> </a><h3 id="l415ambient-occlusion"><a class="header" href="#l415ambient-occlusion">⟨L:415⟩Ambient occlusion</a></h3>
|
||
<p>
|
||
<p>The ⟨L:417⟩<code>ambientOcclusion</code> property defines how much of the ambient light is accessible to a surface
|
||
point. ⟨L:418⟩It is a per-pixel shadowing factor between 0.0 (fully shadowed) and 1.0 (fully lit). This
|
||
property ⟨L:419⟩only affects diffuse indirect lighting (image-based lighting), not direct lights such as
|
||
directional, ⟨L:420⟩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">Figure ⟨L:422⟩[aoExample]: Comparison of materials without diffuse ambient occlusion
|
||
(left) ⟨L:423⟩and with (right)</span></center></div></center>
|
||
</p>
|
||
</section><section class="h3-section"><a class="target" name="normal"> </a><a class="target" name="materialmodels/litmodel/normal"> </a><a class="target" name="toc3.1.15"> </a><h3 id="l425normal"><a class="header" href="#l425normal">⟨L:425⟩Normal</a></h3>
|
||
<p>
|
||
<p>The ⟨L:427⟩<code>normal</code> property defines the normal of the surface at a given point. It usually comes from a
|
||
<em class="underscore">normal ⟨L:428⟩map</em> texture, which allows to vary the property per-pixel. The normal is supplied in tangent
|
||
space, ⟨L:429⟩which means that +Z points outside of the surface.</p>
|
||
</p><p>
|
||
For ⟨L:431⟩example, let's imagine that we want to render a piece of furniture covered in tufted leather.
|
||
Modeling ⟨L:432⟩the geometry to accurately represent the tufted pattern would require too many triangles
|
||
so ⟨L:433⟩we instead bake a high-poly mesh into a normal map. Once the base map is applied to a simplified
|
||
mesh, ⟨L:434⟩we get the result in figure ?.
|
||
</p><p>
|
||
Note ⟨L:436⟩that the <code>normal</code> property affects the <em class="underscore">base layer</em> and not the clear coat layer.
|
||
</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">Figure ⟨L:438⟩[normalMapped]: Low-poly mesh without normal mapping (left)
|
||
and ⟨L:439⟩with (right)</span></center></div></center>
|
||
</p><p>
|
||
<div class="admonition ⟨L:441⟩warning">Using ⟨L:442⟩a normal map increases the runtime cost of the material model.</div>
|
||
</p>
|
||
</section><section class="h3-section"><a class="target" name="bentnormal"> </a><a class="target" name="materialmodels/litmodel/bentnormal"> </a><a class="target" name="toc3.1.16"> </a><h3 id="l444bent-normal"><a class="header" href="#l444bent-normal">⟨L:444⟩Bent normal</a></h3>
|
||
<p>
|
||
<p>The ⟨L:446⟩<code>bentNormal</code> property defines the average unoccluded direction at a point on the surface. It is
|
||
used ⟨L:447⟩to improve the accuracy of indirect lighting. Bent normals can also improve the quality of
|
||
specular ⟨L:448⟩ambient occlusion (see section <a href="#toc4.2.36" target="_self">4.2.36</a> about
|
||
<code>specularAmbientOcclusion</code>).⟨L:449⟩</p>
|
||
</p><p>
|
||
Bent ⟨L:451⟩normals can greatly increase the visual fidelity of an asset with various cavities and concave
|
||
areas, ⟨L:452⟩as shown in figure ?. See the areas of the ears, nostrils and eyes for
|
||
instance.⟨L:453⟩
|
||
</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">Figure ⟨L:455⟩[bentNormalMapped]: Example of a model rendered with and without a bent normal map. Both
|
||
versions ⟨L:456⟩use the same ambient occlusion map.</span></center></div></center>
|
||
</p>
|
||
</section><section class="h3-section"><a class="target" name="clearcoatnormal"> </a><a class="target" name="materialmodels/litmodel/clearcoatnormal"> </a><a class="target" name="toc3.1.17"> </a><h3 id="l458clear-coat-normal"><a class="header" href="#l458clear-coat-normal">⟨L:458⟩Clear coat normal</a></h3>
|
||
<p>
|
||
<p>The ⟨L:460⟩<code>clearCoatNormal</code> property defines the normal of the clear coat layer at a given point. It
|
||
behaves ⟨L:461⟩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">Figure ⟨L:463⟩[clearCoatNormalMapped]: A material with a clear coat normal
|
||
map ⟨L:464⟩and a surface normal map</span></center></div></center>
|
||
</p><p>
|
||
<div class="admonition ⟨L:466⟩warning">Using ⟨L:467⟩a clear coat normal map increases the runtime cost of the material model.</div>
|
||
</p>
|
||
</section><section class="h3-section"><a class="target" name="emissive"> </a><a class="target" name="materialmodels/litmodel/emissive"> </a><a class="target" name="toc3.1.18"> </a><h3 id="l469emissive"><a class="header" href="#l469emissive">⟨L:469⟩Emissive</a></h3>
|
||
<p>
|
||
<p>The ⟨L:471⟩<code>emissive</code> property can be used to simulate additional light emitted by the surface. It is
|
||
defined ⟨L:472⟩as a <code>float4</code> value that contains an RGB intensity in nits as well as an exposure
|
||
weight ⟨L:473⟩(in the alpha channel).</p>
|
||
</p><p>
|
||
The ⟨L:475⟩intensity in nits allows an emissive surface to function as a light and can be used to recreate
|
||
real ⟨L:476⟩world surfaces. For instance a computer display has an intensity between 200 and 1,000 nits.
|
||
</p><p>
|
||
If ⟨L:478⟩you prefer to work in EV (or f-stops), you can simplify multiply your emissive color by the
|
||
output ⟨L:479⟩of the API <code>filament::Exposure::luminance(ev)</code>. This API returns the luminance in nits of
|
||
the ⟨L:480⟩specific EV. You can perform this conversion yourself using the following formula, where \(L\)
|
||
is ⟨L:481⟩the final intensity in nits: \( L = 2^{EV - 3} \).
|
||
</p><p>
|
||
The ⟨L:483⟩exposure weight carried in the alpha channel can be used to undo the camera exposure, and thus
|
||
force ⟨L:484⟩an emissive surface to bloom. When the exposure weight is set to 0, the emissive intensity is
|
||
not ⟨L:485⟩affected by the camera exposure. When the weight is set to 1, the intensity is multiplied by
|
||
the ⟨L:486⟩camera exposure like with any regular light.
|
||
</p>
|
||
</section><section class="h3-section"><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 id="l488post-lighting-color"><a class="header" href="#l488post-lighting-color">⟨L:488⟩Post-lighting color</a></h3>
|
||
<p>
|
||
<p>The ⟨L:490⟩<code>postLightingColor</code> can be used to modify the surface color after lighting computations. This
|
||
property ⟨L:491⟩has no physical meaning and only exists to implement specific effects or to help with
|
||
debugging. ⟨L:492⟩This property is defined as a <code>float4</code> value containing a pre-multiplied RGB color in
|
||
linear ⟨L:493⟩space.</p>
|
||
</p><p>
|
||
The ⟨L:495⟩post-lighting color is blended with the result of lighting according to the blending mode
|
||
specified ⟨L:496⟩by the <code>postLightingBlending</code> material option. Please refer to the documentation of
|
||
this ⟨L:497⟩option for more information.
|
||
</p><p>
|
||
<div class="admonition ⟨L:499⟩tip"><code>postLightingColor</code> ⟨L:500⟩can be used as a simpler <code>emissive</code> property by setting
|
||
<code>postLightingBlending</code> ⟨L:501⟩to <code>add</code> and by providing an RGB color with alpha set to <code>0.0</code>.</div>
|
||
</p>
|
||
</section><section class="h3-section"><a class="target" name="indexofrefraction"> </a><a class="target" name="materialmodels/litmodel/indexofrefraction"> </a><a class="target" name="toc3.1.20"> </a><h3 id="l503index-of-refraction"><a class="header" href="#l503index-of-refraction">⟨L:503⟩Index of refraction</a></h3>
|
||
<p>
|
||
<p>The ⟨L:505⟩<code>ior</code> property only affects non-metallic surfaces. This property can be used to control the
|
||
index ⟨L:506⟩of refraction and the specular intensity of materials. The <code>ior</code> property is intended to
|
||
be ⟨L:507⟩used with refractive (transmissive) materials, which are enabled when the <code>refractionMode</code> is
|
||
set ⟨L:508⟩to <code>cubemap</code> or <code>screenspace</code>. It can also be used on non-refractive objects as an alternative
|
||
to ⟨L:509⟩setting the reflectance.</p>
|
||
</p><p>
|
||
The ⟨L:511⟩index of refraction (or refractive index) of a material is a dimensionless number that describes
|
||
how ⟨L:512⟩fast light travels through that material. The higher the number, the slower light travels
|
||
through ⟨L:513⟩the medium. More importantly for rendering materials, the refractive index determines how
|
||
the ⟨L:514⟩path light travels is bent when entering the material. Higher indices of refraction will cause
|
||
light ⟨L:515⟩to bend further away from the initial path.
|
||
</p><p>
|
||
Table ⟨L:517⟩[commonMatIOR] describes acceptable refractive indices for various types of materials.
|
||
<div class='table'>
|
||
<a class="target" name="table_commonmatior"> </a><table class="table"><tr><th style="text-align:right"> Material ⟨L:519⟩ </th><th style="text-align:left"> IOR </th></tr>
|
||
<tr><td style="text-align:right"> Air ⟨L:521⟩ </td><td style="text-align:left"> 1.0 </td></tr>
|
||
<tr><td style="text-align:right"> Water ⟨L:522⟩ </td><td style="text-align:left"> 1.33 </td></tr>
|
||
<tr><td style="text-align:right"> Common ⟨L:523⟩liquids </td><td style="text-align:left"> 1.33 to 1.5 </td></tr>
|
||
<tr><td style="text-align:right"> Common ⟨L:524⟩gemstones </td><td style="text-align:left"> 1.58 to 2.33 </td></tr>
|
||
<tr><td style="text-align:right"> Plastics, ⟨L:525⟩glass </td><td style="text-align:left"> 1.5 to 1.58 </td></tr>
|
||
<tr><td style="text-align:right"> Other ⟨L:526⟩dielectric materials </td><td style="text-align:left"> 1.33 to 1.58 </td></tr>
|
||
</table><center><div class="tablecaption"><b style="font-style:normal;">Table 6:</b> Index of refraction of common materials</div></center></div>
|
||
</p><p>
|
||
The ⟨L:529⟩appearance of a refractive material will greatly depend on the <code>refractionType</code> and
|
||
<code>refractionMode</code> ⟨L:530⟩settings of the material. Refer to section ? and section <a href="#toc4.2.23" target="_self">4.2.23</a>
|
||
for ⟨L:532⟩more information.
|
||
</p><p>
|
||
The ⟨L:534⟩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 ⟨L:535⟩be seen in figure ? (click on the image to see a larger version).
|
||
</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">Figure ⟨L:537⟩[iorProperty2]: <code>transmission</code> varying from 1.0
|
||
(left) ⟨L:538⟩to 1.5 (right)</span></center></div></center>
|
||
</p><p>
|
||
Figure ⟨L:540⟩[iorProperty] shows the comparison of a sphere of <code>ior</code> 1.0 with a sphere of <code>ior</code> 1.33, with
|
||
the ⟨L:541⟩<code>refractionMode</code> set to <code>screenspace</code> and the <code>refractionType</code> set to <code>solid</code>
|
||
(click ⟨L:542⟩on the image to see a larger version).
|
||
</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">Figure ⟨L:544⟩[iorProperty]: <code>ior</code> of 1.0 (left) and 1.33 (right)</span></center></div></center>
|
||
</p><p>
|
||
Note ⟨L:546⟩that the <code>ior</code> property also defines the reflectance (or specular intensity) of the surface.
|
||
When ⟨L:547⟩this property is defined it is not necessary to define the <code>reflectance</code> property. Setting
|
||
either ⟨L:548⟩of these properties will automatically compute the other property. It is possible to specify
|
||
both, ⟨L:549⟩in which case their values are kept as-is, which can lead to physically impossible materials,
|
||
however, ⟨L:550⟩this might be desirable for artistic reasons.
|
||
</p><p>
|
||
See ⟨L:552⟩the Reflectance section for more information on the <code>reflectance</code> property.
|
||
</p><p>
|
||
<div class="admonition ⟨L:554⟩tip">Refractive ⟨L:555⟩materials are affected by the <code>roughness</code> property. Rough materials will scatter
|
||
light, ⟨L:556⟩creating a diffusion effect useful to recreate “blurry” appearances such as frosted
|
||
glass, ⟨L:557⟩certain plastics, etc.</div>
|
||
</p>
|
||
</section><section class="h3-section"><a class="target" name="transmission"> </a><a class="target" name="materialmodels/litmodel/transmission"> </a><a class="target" name="toc3.1.21"> </a><h3 id="l559transmission"><a class="header" href="#l559transmission">⟨L:559⟩Transmission</a></h3>
|
||
<p>
|
||
<p>The ⟨L:561⟩<code>transmission</code> property defines what ratio of diffuse light is transmitted through a refractive
|
||
material. ⟨L:562⟩This property only affects materials with a <code>refractionMode</code> set to <code>cubemap</code> or
|
||
<code>screenspace</code>.⟨L:563⟩</p>
|
||
</p><p>
|
||
When ⟨L:565⟩<code>transmission</code> is set to 0, no amount of light is transmitted and the diffuse component of
|
||
the ⟨L:566⟩surface is 100% visible. When <code>transmission</code> is set to 1, all the light is transmitted and the
|
||
diffuse ⟨L:567⟩component is not visible anymore, only the specular component is.
|
||
</p><p>
|
||
The ⟨L:569⟩effect of <code>transmission</code> on a glossy dielectric (<code>ior</code> of 1.5, <code>refractionMode</code> set to
|
||
<code>cubemap</code>, ⟨L:570⟩<code>refractionType</code> set to <code>solid</code>) is shown in figure ?
|
||
(click ⟨L:571⟩on the image to see a larger version).
|
||
</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">Figure ⟨L:573⟩[transmissionProperty]: <code>transmission</code> varying from 0.0
|
||
(left) ⟨L:574⟩to 1.0 (right)</span></center></div></center>
|
||
</p><p>
|
||
<div class="admonition ⟨L:576⟩tip">The ⟨L:577⟩<code>transmission</code> property is useful to create decals, paint, etc. at the surface of refractive
|
||
materials.⟨L:578⟩</div>
|
||
</p>
|
||
</section><section class="h3-section"><a class="target" name="absorption"> </a><a class="target" name="materialmodels/litmodel/absorption"> </a><a class="target" name="toc3.1.22"> </a><h3 id="l580absorption"><a class="header" href="#l580absorption">⟨L:580⟩Absorption</a></h3>
|
||
<p>
|
||
<p>The ⟨L:582⟩<code>absorption</code> property defines the absorption coefficients of light transmitted through the
|
||
material. ⟨L:583⟩Figure ? shows the effect of <code>absorption</code> on a refracting object with
|
||
an ⟨L:584⟩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">Figure ⟨L:586⟩[absorptionExample]: Refracting object without (left)
|
||
and ⟨L:587⟩with (right) absorption</span></center></div></center>
|
||
</p><p>
|
||
Transmittance ⟨L:589⟩through a volume is exponential with respect to the optical depth (defined either
|
||
with ⟨L:590⟩<code>microThickness</code> or <code>thickness</code>). The computed color follows the following formula:
|
||
</p><p>
|
||
$$color ⟨L:592⟩\cdot e^{-absorption \cdot distance}$$
|
||
</p><p>
|
||
Where ⟨L:594⟩<code>distance</code> is either <code>microThickness</code> or <code>thickness</code>, that is the distance light will travel
|
||
through ⟨L:595⟩the material at a given point. If no thickness/distance is specified, the computed color
|
||
follows ⟨L:596⟩this formula instead:
|
||
</p><p>
|
||
$$color ⟨L:598⟩\cdot (1 - absorption)$$
|
||
</p><p>
|
||
The ⟨L:600⟩effect of varying the <code>absorption</code> coefficients is shown in figure ?
|
||
(click ⟨L:601⟩on the image to see a larger version). In this picture, the object has a fixed <code>thickness</code>
|
||
of ⟨L:602⟩4.5 and an index of refraction set to 1.3.
|
||
</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">Figure ⟨L:604⟩[absorptionProperty]: <code>absorption</code> varying from (0.0, 0.02, 0.14)
|
||
(left) ⟨L:605⟩to (0.0, 0.36, 2.3) (right)</span></center></div></center>
|
||
</p><p>
|
||
Setting ⟨L:607⟩the absorption coefficients directly can be unintuitive which is why we recommend working
|
||
with ⟨L:608⟩a <em class="underscore">transmittance color</em> and a <em class="underscore">“at distance”</em> factor instead. These two parameters allow an
|
||
artist ⟨L:609⟩to specify the precise color the material should have at a specified distance through the
|
||
volume. ⟨L:610⟩The value to pass to <code>absorption</code> can be computed this way:
|
||
</p><p>
|
||
$$absorption ⟨L:612⟩= -\frac{ln(transmittanceColor)}{atDistance}$$
|
||
</p><p>
|
||
While ⟨L:614⟩this computation can be done in the material itself we recommend doing it offline whenever
|
||
possible. ⟨L:615⟩Filament provides an API for this purpose, <code>Color::absorptionAtDistance()</code>.
|
||
</p>
|
||
</section><section class="h3-section"><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 id="l617micro-thickness-and-thickness"><a class="header" href="#l617micro-thickness-and-thickness">⟨L:617⟩Micro-thickness and thickness</a></h3>
|
||
<p>
|
||
<p>The ⟨L:619⟩<code>microThickness</code> and <code>thickness</code> properties define the optical depth of the material of a
|
||
refracting ⟨L:620⟩object. <code>microThickness</code> is used when <code>refractionType</code> is set to <code>thin</code>, and <code>thickness</code>
|
||
is ⟨L:621⟩used when <code>refractionType</code> is set to <code>volume</code>.</p>
|
||
</p><p>
|
||
<code>thickness</code> ⟨L:623⟩represents the thickness of solid objects in the direction of the normal, for
|
||
satisfactory ⟨L:624⟩results, this should be provided per fragment (e.g.: as a texture) or at least per
|
||
vertex.⟨L:625⟩
|
||
</p><p>
|
||
<code>microThickness</code> ⟨L:627⟩represent the thickness of the thin layer (shell) of an object, and can generally
|
||
be ⟨L:628⟩provided as a constant value. For example, a 1mm thin hollow sphere of radius 1m, would have a
|
||
<code>thickness</code> ⟨L:629⟩of 1 and a <code>microThickness</code> of 0.001. Currently <code>thickness</code> is not used when
|
||
<code>refractionType</code> ⟨L:630⟩is set to <code>thin</code>. Both properties are made available for possible future use.
|
||
</p><p>
|
||
Both ⟨L:632⟩<code>thickness</code> and <code>microThickness</code> are used to compute the transmitted color of the material
|
||
when ⟨L:633⟩the <code>absorption</code> property is set. In solid volumes, <code>thickness</code> will also affect how light
|
||
rays ⟨L:634⟩are refracted.
|
||
</p><p>
|
||
The ⟨L:636⟩effect <code>thickness</code> in a solid volume with <code>refractionMode</code> set to <code>screenSpace</code> is shown in
|
||
figure ⟨L:637⟩[thicknessProperty] (click on the image to see a larger version). Note how the <code>thickness</code>
|
||
value ⟨L:638⟩not only changes the effect of <code>absorption</code> but also modifies the direction of the refracted
|
||
light.⟨L:639⟩
|
||
</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">Figure ⟨L:641⟩[thicknessProperty]: <code>thickness</code> varying from 0.0
|
||
(left) ⟨L:642⟩to 2.0 (right)</span></center></div></center>
|
||
</p><p>
|
||
Figure ⟨L:644⟩[varyingThickness] shows what a prism with spatially varying <code>thickness</code> looks like when
|
||
the ⟨L:645⟩<code>refractionType</code> is set to <code>solid</code> and <code>absorption</code> coefficients are set.
|
||
</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">Figure ⟨L:647⟩[varyingThickness]: <code>thickness</code> varying from 0.0 at the top of the prism to 3.0 at the
|
||
bottom ⟨L:648⟩of the prism</span></center></div></center>
|
||
</p>
|
||
</section></section><section class="h2-section"><a class="target" name="subsurfacemodel"> </a><a class="target" name="materialmodels/subsurfacemodel"> </a><a class="target" name="toc3.2"> </a><h2 id="l650subsurface-model"><a class="header" href="#l650subsurface-model">⟨L:650⟩Subsurface model</a></h2>
|
||
<section class="h3-section"><a class="target" name="thickness"> </a><a class="target" name="materialmodels/subsurfacemodel/thickness"> </a><a class="target" name="toc3.2.1"> </a><h3 id="l652thickness"><a class="header" href="#l652thickness">⟨L:652⟩Thickness</a></h3>
|
||
</section><section class="h3-section"><a class="target" name="subsurfacecolor"> </a><a class="target" name="materialmodels/subsurfacemodel/subsurfacecolor"> </a><a class="target" name="toc3.2.2"> </a><h3 id="l654subsurface-color"><a class="header" href="#l654subsurface-color">⟨L:654⟩Subsurface color</a></h3>
|
||
</section><section class="h3-section"><a class="target" name="subsurfacepower"> </a><a class="target" name="materialmodels/subsurfacemodel/subsurfacepower"> </a><a class="target" name="toc3.2.3"> </a><h3 id="l656subsurface-power"><a class="header" href="#l656subsurface-power">⟨L:656⟩Subsurface power</a></h3>
|
||
</section></section><section class="h2-section"><a class="target" name="clothmodel"> </a><a class="target" name="materialmodels/clothmodel"> </a><a class="target" name="toc3.3"> </a><h2 id="l658cloth-model"><a class="header" href="#l658cloth-model">⟨L:658⟩Cloth model</a></h2>
|
||
<p>
|
||
<p>All ⟨L:660⟩the material models described previously are designed to simulate dense surfaces, both at a
|
||
macro ⟨L:661⟩and at a micro level. Clothes and fabrics are however often made of loosely connected threads
|
||
that ⟨L:662⟩absorb and scatter incident light. When compared to hard surfaces, cloth is characterized by
|
||
a ⟨L:663⟩softer specular lob with a large falloff and the presence of fuzz lighting, caused by
|
||
forward/backward ⟨L:664⟩scattering. Some fabrics also exhibit two-tone specular colors
|
||
(velvets ⟨L:665⟩for instance).</p>
|
||
</p><p>
|
||
Figure ⟨L:667⟩[materialCloth] shows how the standard material model fails to capture the appearance of a
|
||
sample ⟨L:668⟩of denim fabric. The surface appears rigid (almost plastic-like), more similar to a tarp
|
||
than ⟨L:669⟩a piece of clothing. This figure also shows how important the softer specular lobe caused by
|
||
absorption ⟨L:670⟩and scattering is to the faithful recreation of the fabric.
|
||
</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">Figure ⟨L:672⟩[materialCloth]: Comparison of denim fabric rendered using the standard model
|
||
(left) ⟨L:673⟩and the cloth model (right)</span></center></div></center>
|
||
</p><p>
|
||
Velvet ⟨L:675⟩is an interesting use case for a cloth material model. As shown in figure ?
|
||
this ⟨L:676⟩type of fabric exhibits strong rim lighting due to forward and backward scattering. These
|
||
scattering ⟨L:677⟩events are caused by fibers standing straight at the surface of the fabric. When the
|
||
incident ⟨L:678⟩light comes from the direction opposite to the view direction, the fibers will forward
|
||
scatter ⟨L:679⟩the light. Similarly, when the incident light from the same direction as the view
|
||
direction, ⟨L:680⟩the fibers will scatter the light backward.
|
||
</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">Figure ⟨L:682⟩[materialVelvet]: Velvet fabric showcasing forward and
|
||
backward ⟨L:683⟩scattering</span></center></div></center>
|
||
</p><p>
|
||
It ⟨L:685⟩is important to note that there are types of fabrics that are still best modeled by hard surface
|
||
material ⟨L:686⟩models. For instance, leather, silk and satin can be recreated using the standard or
|
||
anisotropic ⟨L:687⟩material models.
|
||
</p><p>
|
||
The ⟨L:689⟩cloth material model encompasses all the parameters previously defined for the standard
|
||
material ⟨L:690⟩mode except for <em class="underscore">metallic</em> and <em class="underscore">reflectance</em>. Two extra parameters described in
|
||
table ⟨L:691⟩[clothProperties] are also available.
|
||
</p><p>
|
||
<div class='table'>
|
||
<a class="target" name="table_clothproperties"> </a><table class="table"><tr><th style="text-align:right"> Parameter ⟨L:694⟩ </th><th style="text-align:left"> Definition </th></tr>
|
||
<tr><td style="text-align:right"> <strong class="asterisk">sheenColor</strong> ⟨L:696⟩ </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> ⟨L:697⟩ </td><td style="text-align:left"> Tint for the diffuse color after scattering and absorption through the material </td></tr>
|
||
</table><center><div class="tablecaption"><b style="font-style:normal;">Table 7:</b> Cloth model parameters</div></center></div>
|
||
</p><p>
|
||
The ⟨L:700⟩type and range of each property is described in <a href="#table_clothpropertiestypes" target="_self">table 8</a>.
|
||
<div class='table'>
|
||
<a class="target" name="table_clothpropertiestypes"> </a><table class="table"><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>
|
||
</table><center><div class="tablecaption"><b style="font-style:normal;">Table 8:</b> Range and type of the cloth model's properties</div></center></div>
|
||
</p><p>
|
||
To ⟨L:708⟩create a velvet-like material, the base color can be set to black (or a dark color).
|
||
Chromaticity ⟨L:709⟩information should instead be set on the sheen color. To create more common fabrics
|
||
such ⟨L:710⟩as denim, cotton, etc. use the base color for chromaticity and use the default sheen color
|
||
or ⟨L:711⟩set the sheen color to the luminance of the base color.
|
||
</p><p>
|
||
<div class="admonition ⟨L:713⟩tip">To ⟨L:714⟩see the effect of the <code>roughness</code> parameter make sure the <code>sheenColor</code> is brighter than
|
||
<code>baseColor</code>. ⟨L:715⟩This can be used to create a fuzz effect. Taking the luminance of <code>baseColor</code>
|
||
as ⟨L:716⟩the <code>sheenColor</code> will produce a fairly natural effect that works for common cloth. A dark
|
||
<code>baseColor</code> ⟨L:717⟩combined with a bright/saturated <code>sheenColor</code> can be used to create velvet.</div>
|
||
</p><p>
|
||
<div class="admonition ⟨L:719⟩tip">The ⟨L:720⟩<code>subsurfaceColor</code> parameter should be used with care. High values can interfere with shadows
|
||
in ⟨L:721⟩some areas. It is best suited for subtle transmission effects through the material.</div>
|
||
</p>
|
||
<section class="h3-section"><a class="target" name="sheencolor"> </a><a class="target" name="materialmodels/clothmodel/sheencolor"> </a><a class="target" name="toc3.3.1"> </a><h3 id="l723sheen-color"><a class="header" href="#l723sheen-color">⟨L:723⟩Sheen color</a></h3>
|
||
<p>
|
||
<p>The ⟨L:725⟩<code>sheenColor</code> property can be used to directly modify the specular reflectance. It offers
|
||
better ⟨L:726⟩control over the appearance of cloth and gives give the ability to create
|
||
two-tone ⟨L:727⟩specular materials.</p>
|
||
</p><p>
|
||
The ⟨L:729⟩effect of <code>sheenColor</code> is shown in figure ?
|
||
(click ⟨L:730⟩on the image to see a larger version).
|
||
</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">Figure ⟨L:732⟩[materialClothSheen]: Blue fabric without (left) and with (right) sheen</span></center></div></center>
|
||
</p>
|
||
</section><section class="h3-section"><a class="target" name="subsurfacecolor"> </a><a class="target" name="materialmodels/clothmodel/subsurfacecolor"> </a><a class="target" name="toc3.3.2"> </a><h3 id="l734subsurface-color"><a class="header" href="#l734subsurface-color">⟨L:734⟩Subsurface color</a></h3>
|
||
<p>
|
||
<p>The ⟨L:736⟩<code>subsurfaceColor</code> property is not physically-based and can be used to simulate the scattering,
|
||
partial ⟨L:737⟩absorption and re-emission of light in certain types of fabrics. This is particularly
|
||
useful ⟨L:738⟩to create softer fabrics.</p>
|
||
</p><p>
|
||
<div class="admonition ⟨L:740⟩warning">The ⟨L:741⟩cloth material model is more expensive to compute when the <code>subsurfaceColor</code> property is used.</div>
|
||
</p><p>
|
||
The ⟨L:743⟩effect of <code>subsurfaceColor</code> is shown in figure ?
|
||
(click ⟨L:744⟩on the image to see a larger version).
|
||
</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">Figure ⟨L:746⟩[materialClothSubsurface]: White cloth (left column) vs white cloth with
|
||
brown ⟨L:747⟩subsurface scatting (right)</span></center></div></center>
|
||
</p>
|
||
</section></section><section class="h2-section"><a class="target" name="unlitmodel"> </a><a class="target" name="materialmodels/unlitmodel"> </a><a class="target" name="toc3.4"> </a><h2 id="l749unlit-model"><a class="header" href="#l749unlit-model">⟨L:749⟩Unlit model</a></h2>
|
||
<p>
|
||
<p>The ⟨L:751⟩unlit material model can be used to turn off all lighting computations. Its primary purpose is
|
||
to ⟨L:752⟩render pre-lit elements such as a cubemap, external content (such as a video or camera stream),
|
||
user ⟨L:753⟩interfaces, visualization/debugging etc. The unlit model exposes only two properties described
|
||
in ⟨L:754⟩<a href="#table_unlitproperties" target="_self">table 9</a>.</p>
|
||
<div class='table'>
|
||
<a class="target" name="table_unlitproperties"> </a><table class="table"><tr><th style="text-align:right"> Property ⟨L:756⟩ </th><th style="text-align:left"> Definition </th></tr>
|
||
<tr><td style="text-align:right"> <strong class="asterisk">baseColor</strong> ⟨L:758⟩ </td><td style="text-align:left"> Surface diffuse color </td></tr>
|
||
<tr><td style="text-align:right"> <strong class="asterisk">emissive</strong> ⟨L:759⟩ </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> ⟨L:760⟩ </td><td style="text-align:left"> Additional color to blend with base color and emissive </td></tr>
|
||
</table><center><div class="tablecaption"><b style="font-style:normal;">Table 9:</b> Properties of the standard model</div></center></div>
|
||
</p><p>
|
||
The ⟨L:763⟩type and range of each property is described in <a href="#table_unlitpropertiestypes" target="_self">table 10</a>.
|
||
<div class='table'>
|
||
<a class="target" name="table_unlitpropertiestypes"> </a><table class="table"><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>
|
||
</table><center><div class="tablecaption"><b style="font-style:normal;">Table 10:</b> Range and type of the unlit model's properties</div></center></div>
|
||
</p><p>
|
||
The ⟨L:772⟩value of <code>postLightingColor</code> is blended with the sum of <code>emissive</code> and <code>baseColor</code> according to
|
||
the ⟨L:773⟩blending mode specified by the <code>postLightingBlending</code> material option.
|
||
</p><p>
|
||
Figure ⟨L:775⟩[materialUnlit] shows an example of the unlit material model
|
||
(click ⟨L:776⟩on the image to see a larger version).
|
||
</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">Figure ⟨L:778⟩[materialUnlit]: The unlit model is used to render debug information</span></center></div></center>
|
||
</p>
|
||
</section><section class="h2-section"><a class="target" name="specularglossiness"> </a><a class="target" name="materialmodels/specularglossiness"> </a><a class="target" name="toc3.5"> </a><h2 id="l780specular-glossiness"><a class="header" href="#l780specular-glossiness">⟨L:780⟩Specular glossiness</a></h2>
|
||
<p>
|
||
<p>This ⟨L:782⟩alternative lighting model exists to comply with legacy standards. Since it is not a
|
||
physically-based ⟨L:783⟩formulation, we do not recommend using it except when loading legacy assets.</p>
|
||
</p><p>
|
||
This ⟨L:785⟩model encompasses the parameters previously defined for the standard lit mode except for
|
||
<em class="underscore">metallic</em>, ⟨L:786⟩<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>.
|
||
<div class='table'>
|
||
<a class="target" name="table_glossinessproperties"> </a><table class="table"><tr><th style="text-align:right"> Parameter ⟨L:788⟩ </th><th style="text-align:left"> Definition </th></tr>
|
||
<tr><td style="text-align:right"> <strong class="asterisk">baseColor</strong> ⟨L:790⟩ </td><td style="text-align:left"> Surface diffuse color </td></tr>
|
||
<tr><td style="text-align:right"> <strong class="asterisk">specularColor</strong> ⟨L:791⟩ </td><td style="text-align:left"> Specular tint (defaults to black) </td></tr>
|
||
<tr><td style="text-align:right"> <strong class="asterisk">glossiness</strong> ⟨L:792⟩ </td><td style="text-align:left"> Glossiness (defaults to 0.0) </td></tr>
|
||
</table><center><div class="tablecaption"><b style="font-style:normal;">Table 11:</b> Properties of the specular-glossiness shading model</div></center></div>
|
||
</p><p>
|
||
The ⟨L:795⟩type and range of each property is described in <a href="#table_glossinesspropertiestypes" target="_self">table 12</a>.
|
||
<div class='table'>
|
||
<a class="target" name="table_glossinesspropertiestypes"> </a><table class="table"><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>
|
||
</table><center><div class="tablecaption"><b style="font-style:normal;">Table 12:</b> Range and type of the specular-glossiness model's properties</div></center></div>
|
||
</p>
|
||
</section></section><section class="h1-section"><a class="target" name="materialdefinitions"> </a><a class="target" name="materialdefinitions"> </a><a class="target" name="toc4"> </a><h1 id="l804material-definitions"><a class="header" href="#l804material-definitions">⟨L:804⟩Material definitions</a></h1>
|
||
<p>
|
||
<p>A ⟨L:806⟩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>
|
||
<section class="h2-section"><a class="target" name="format"> </a><a class="target" name="materialdefinitions/format"> </a><a class="target" name="toc4.1"> </a><h2 id="l816format"><a class="header" href="#l816format">⟨L:816⟩Format</a></h2>
|
||
<p>
|
||
<p>The ⟨L:818⟩material definition format is a format loosely based on <a href="https://www.json.org/">JSON</a> that we
|
||
call ⟨L:819⟩<em class="underscore">JSONish</em>. At the top level a material definition is composed of 3 different blocks that use
|
||
the ⟨L:820⟩JSON object notation:</p>
|
||
</p><pre class="listing tilde"><code><span class="line"></span>material <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> <span class="hljs-comment">// material properties</span>
|
||
<span class="line"></span><span class="hljs-punctuation">}</span>
|
||
<span class="line"></span>
|
||
<span class="line"></span>vertex <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> <span class="hljs-comment">// vertex shader, optional</span>
|
||
<span class="line"></span><span class="hljs-punctuation">}</span>
|
||
<span class="line"></span>
|
||
<span class="line"></span>fragment <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> <span class="hljs-comment">// fragment shader</span>
|
||
<span class="line"></span><span class="hljs-punctuation">}</span></code></pre><p>
|
||
A ⟨L:836⟩minimum viable material definition must contain a <code>material</code> preamble and a <code>fragment</code> block. The
|
||
<code>vertex</code> ⟨L:837⟩block is optional.
|
||
</p>
|
||
<section class="h3-section"><a class="target" name="differenceswithjson"> </a><a class="target" name="materialdefinitions/format/differenceswithjson"> </a><a class="target" name="toc4.1.1"> </a><h3 id="l839differences-with-json"><a class="header" href="#l839differences-with-json">⟨L:839⟩Differences with JSON</a></h3>
|
||
<p>
|
||
<p>In ⟨L:841⟩JSON, an object is made of key/value <em class="underscore">pairs</em>. A JSON pair has the following syntax:</p>
|
||
</p><pre class="listing tilde"><code><span class="line"></span><span class="hljs-attr">"key"</span> <span class="hljs-punctuation">:</span> value</code></pre><p>
|
||
Where ⟨L:847⟩value can be a string, number, object, array or a literal (<code>true</code>, <code>false</code> or <code>null</code>). While
|
||
this ⟨L:848⟩syntax is perfectly valid in a material definition, a variant without quotes around strings is
|
||
also ⟨L:849⟩accepted in JSONish:
|
||
</p><pre class="listing tilde"><code><span class="line"></span>key <span class="hljs-punctuation">:</span> value</code></pre><p>
|
||
Quotes ⟨L:855⟩remain mandatory when the string contains spaces.
|
||
</p><p>
|
||
The ⟨L:857⟩<code>vertex</code> and <code>fragment</code> blocks contain unescaped, unquoted GLSL code, which is not valid in JSON.
|
||
</p><p>
|
||
Single-line ⟨L:859⟩C++-style comments are allowed.
|
||
</p><p>
|
||
The ⟨L:861⟩key of a pair is case-sensitive.
|
||
</p><p>
|
||
The ⟨L:863⟩value of a pair is not case-sensitive.
|
||
</p>
|
||
</section><section class="h3-section"><a class="target" name="example"> </a><a class="target" name="materialdefinitions/format/example"> </a><a class="target" name="toc4.1.2"> </a><h3 id="l865example"><a class="header" href="#l865example">⟨L:865⟩Example</a></h3>
|
||
<p>
|
||
<p>The ⟨L:867⟩following code listing shows an example of a valid material definition. This definition uses
|
||
the ⟨L:868⟩<em class="underscore">lit</em> material model (see Lit model section), uses the default opaque blending mode, requires
|
||
that ⟨L:869⟩a set of UV coordinates be presented in the rendered mesh and defines 3 user parameters. The
|
||
following ⟨L:870⟩sections of this document describe the <code>material</code> and <code>fragment</code> blocks in detail.</p>
|
||
</p><pre class="listing tilde"><code><span class="line"></span>material <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> name <span class="hljs-punctuation">:</span> <span class="hljs-string">"Textured material"</span><span class="hljs-punctuation">,</span>
|
||
<span class="line"></span> parameters <span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span>
|
||
<span class="line"></span> <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> type <span class="hljs-punctuation">:</span> sampler2d<span class="hljs-punctuation">,</span>
|
||
<span class="line"></span> name <span class="hljs-punctuation">:</span> texture
|
||
<span class="line"></span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
|
||
<span class="line"></span> <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> type <span class="hljs-punctuation">:</span> float<span class="hljs-punctuation">,</span>
|
||
<span class="line"></span> name <span class="hljs-punctuation">:</span> metallic
|
||
<span class="line"></span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
|
||
<span class="line"></span> <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> type <span class="hljs-punctuation">:</span> float<span class="hljs-punctuation">,</span>
|
||
<span class="line"></span> name <span class="hljs-punctuation">:</span> roughness
|
||
<span class="line"></span> <span class="hljs-punctuation">}</span>
|
||
<span class="line"></span> <span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span>
|
||
<span class="line"></span> requires <span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span>
|
||
<span class="line"></span> uv0
|
||
<span class="line"></span> <span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span>
|
||
<span class="line"></span> shadingModel <span class="hljs-punctuation">:</span> lit<span class="hljs-punctuation">,</span>
|
||
<span class="line"></span> blending <span class="hljs-punctuation">:</span> opaque
|
||
<span class="line"></span><span class="hljs-punctuation">}</span>
|
||
<span class="line"></span>
|
||
<span class="line"></span>fragment <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> void material(inout MaterialInputs material) <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> prepareMaterial(material);
|
||
<span class="line"></span> material.baseColor = texture(materialParams_texture<span class="hljs-punctuation">,</span> getUV0());
|
||
<span class="line"></span> material.metallic = materialParams.metallic;
|
||
<span class="line"></span> material.roughness = materialParams.roughness;
|
||
<span class="line"></span> <span class="hljs-punctuation">}</span>
|
||
<span class="line"></span><span class="hljs-punctuation">}</span></code></pre>
|
||
</section></section><section class="h2-section"><a class="target" name="materialblock"> </a><a class="target" name="materialdefinitions/materialblock"> </a><a class="target" name="toc4.2"> </a><h2 id="l906material-block"><a class="header" href="#l906material-block">⟨L:906⟩Material block</a></h2>
|
||
<p>
|
||
<p>The ⟨L:908⟩material block is mandatory block that contains a list of property pairs to describe all
|
||
non-shader ⟨L:909⟩data.</p>
|
||
</p>
|
||
<section class="h3-section"><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 id="l911general-name"><a class="header" href="#l911general-name">⟨L:911⟩General: name</a></h3>
|
||
<p>
|
||
<dl><table><tr valign=top><td><dt><a class="target" name="materialdefinitions/materialblock/general:name/def-type"> </a>Type⟨L:913⟩</dt></td><td><dd><p> ⟨L:914⟩<code>string</code>
|
||
</p></dd></td></tr><tr valign=top><td><dt><a class="target" name="materialdefinitions/materialblock/general:name/def-value"> </a>Value⟨L:916⟩</dt></td><td><dd><p> ⟨L:917⟩Any string. Double quotes are required if the name contains spaces.
|
||
</p></dd></td></tr><tr valign=top><td><dt><a class="target" name="materialdefinitions/materialblock/general:name/def-description"> </a>Description⟨L:919⟩</dt></td><td><dd><p> ⟨L:920⟩Sets the name of the material. The name is retained at runtime for debugging purpose.
|
||
</p></dd></td></tr></table></dl></p><pre class="listing tilde"><code><span class="line"></span>material <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> name <span class="hljs-punctuation">:</span> stone
|
||
<span class="line"></span><span class="hljs-punctuation">}</span>
|
||
<span class="line"></span>
|
||
<span class="line"></span>material <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> name <span class="hljs-punctuation">:</span> <span class="hljs-string">"Wet pavement"</span>
|
||
<span class="line"></span><span class="hljs-punctuation">}</span></code></pre>
|
||
</section><section class="h3-section"><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 id="l932general-featurelevel"><a class="header" href="#l932general-featurelevel">⟨L:932⟩General: featureLevel</a></h3>
|
||
<p>
|
||
<dl><table><tr valign=top><td><dt><a class="target" name="materialdefinitions/materialblock/general:featurelevel/def-type"> </a>Type⟨L:934⟩</dt></td><td><dd><p> ⟨L:935⟩<code>number</code>
|
||
</p></dd></td></tr><tr valign=top><td><dt><a class="target" name="materialdefinitions/materialblock/general:featurelevel/def-value"> </a>Value⟨L:937⟩</dt></td><td><dd><p> ⟨L:938⟩An integer value, either 1, 2 or 3. Defaults to 1.
|
||
</p></dd></td></tr></table></dl><div class='table'>
|
||
<a class="target" name="table_featurelevels"> </a><table class="table"><tr><th style="text-align:left"> Feature ⟨L:940⟩Level </th><th style="text-align:left"> Guaranteed features </th></tr>
|
||
<tr><td style="text-align:left"> 1 ⟨L:942⟩ </td><td style="text-align:left"> 9 textures per material </td></tr>
|
||
<tr><td style="text-align:left"> 2 ⟨L:943⟩ </td><td style="text-align:left"> 9 textures per material, cubemap arrays, ESSL 3.10 </td></tr>
|
||
<tr><td style="text-align:left"> 3 ⟨L:944⟩ </td><td style="text-align:left"> 12 textures per material, cubemap arrays, ESSL 3.10 </td></tr>
|
||
</table><center><div class="tablecaption"><b style="font-style:normal;">Table 13:</b> Feature levels</div></center></div>
|
||
</p><p>
|
||
<dl><dt><a class="target" name="materialdefinitions/materialblock/general:featurelevel/def-description"> </a>Description⟨L:947⟩</dt><dd><p> ⟨L:948⟩Sets the feature level of the material. Each feature level defines a set of features the
|
||
material ⟨L:949⟩can use. If the material uses a feature not supported by the selected level, <code>matc</code>
|
||
will ⟨L:950⟩generate an error during compilation. A given feature level is guaranteed to support
|
||
all ⟨L:951⟩features of lower feature levels.
|
||
</p></dd></dl></p><pre class="listing tilde"><code><span class="line"></span>material <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> featureLevel <span class="hljs-punctuation">:</span> <span class="hljs-number">2</span>
|
||
<span class="line"></span><span class="hljs-punctuation">}</span></code></pre><p>
|
||
<dl><table><tr valign=top><td><dt><a class="target" name="materialdefinitions/materialblock/general:featurelevel/def-bugs"> </a>Bugs⟨L:959⟩</dt></td><td><dd><p> ⟨L:960⟩<code>matc</code> doesn't verify that a material is not using features above its selected feature level.
|
||
</p></dd></td></tr></table></dl></p>
|
||
</section><section class="h3-section"><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 id="l963general-shadingmodel"><a class="header" href="#l963general-shadingmodel">⟨L:963⟩General: shadingModel</a></h3>
|
||
<p>
|
||
<dl><table><tr valign=top><td><dt><a class="target" name="materialdefinitions/materialblock/general:shadingmodel/def-type"> </a>Type⟨L:965⟩</dt></td><td><dd><p> ⟨L:966⟩<code>string</code>
|
||
</p></dd></td></tr><tr valign=top><td><dt><a class="target" name="materialdefinitions/materialblock/general:shadingmodel/def-value"> </a>Value⟨L:968⟩</dt></td><td><dd><p> ⟨L:969⟩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><a class="target" name="materialdefinitions/materialblock/general:shadingmodel/def-description"> </a>Description⟨L:971⟩</dt></td><td><dd><p> ⟨L:972⟩Selects the material model as described in the Material models section.
|
||
</p></dd></td></tr></table></dl></p><pre class="listing tilde"><code><span class="line"></span>material <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> shadingModel <span class="hljs-punctuation">:</span> unlit
|
||
<span class="line"></span><span class="hljs-punctuation">}</span>
|
||
<span class="line"></span>
|
||
<span class="line"></span>material <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> shadingModel <span class="hljs-punctuation">:</span> <span class="hljs-string">"subsurface"</span>
|
||
<span class="line"></span><span class="hljs-punctuation">}</span></code></pre>
|
||
</section><section class="h3-section"><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 id="l984general-parameters"><a class="header" href="#l984general-parameters">⟨L:984⟩General: parameters</a></h3>
|
||
<p>
|
||
<dl><dt><a class="target" name="materialdefinitions/materialblock/general:parameters/def-type"> </a>Type⟨L:986⟩</dt><dd><p> ⟨L:987⟩array of parameter objects
|
||
</p></dd><dt><a class="target" name="materialdefinitions/materialblock/general:parameters/def-value"> </a>Value⟨L:989⟩</dt><dd><p> ⟨L:990⟩Each entry is an object with the properties <code>name</code> and <code>type</code>, both of <code>string</code> type. The
|
||
name ⟨L:991⟩must be a valid GLSL identifier. Entries have an optional <code>precision</code>, which can be
|
||
one ⟨L:992⟩of <code>default</code> (best precision for the platform, typically <code>high</code> on desktop, <code>medium</code> on
|
||
mobile), ⟨L:993⟩<code>low</code>, <code>medium</code>, <code>high</code>. The type must be one of the types described in
|
||
table ⟨L:994⟩[materialParamsTypes]. For Android external textures, entries also have an optional
|
||
transformName ⟨L:995⟩parameter to specify the name of the material parameter that will be
|
||
used ⟨L:996⟩to expose the transform matrix associated with the external sampler. In iOS and Vulkan,
|
||
this ⟨L:997⟩will always be identity.
|
||
</p></dd></dl><div class='table'>
|
||
<a class="target" name="table_materialparamstypes"> </a><table class="table longtable"><tr><th style="text-align:left"> Type ⟨L:999⟩ </th><th style="text-align:left"> Description </th></tr>
|
||
<tr><td style="text-align:left"> bool ⟨L:1001⟩ </td><td style="text-align:left"> Single boolean </td></tr>
|
||
<tr><td style="text-align:left"> bool2 ⟨L:1002⟩ </td><td style="text-align:left"> Vector of 2 booleans </td></tr>
|
||
<tr><td style="text-align:left"> bool3 ⟨L:1003⟩ </td><td style="text-align:left"> Vector of 3 booleans </td></tr>
|
||
<tr><td style="text-align:left"> bool4 ⟨L:1004⟩ </td><td style="text-align:left"> Vector of 4 booleans </td></tr>
|
||
<tr><td style="text-align:left"> float ⟨L:1005⟩ </td><td style="text-align:left"> Single float </td></tr>
|
||
<tr><td style="text-align:left"> float2 ⟨L:1006⟩ </td><td style="text-align:left"> Vector of 2 floats </td></tr>
|
||
<tr><td style="text-align:left"> float3 ⟨L:1007⟩ </td><td style="text-align:left"> Vector of 3 floats </td></tr>
|
||
<tr><td style="text-align:left"> float4 ⟨L:1008⟩ </td><td style="text-align:left"> Vector of 4 floats </td></tr>
|
||
<tr><td style="text-align:left"> int ⟨L:1009⟩ </td><td style="text-align:left"> Single integer </td></tr>
|
||
<tr><td style="text-align:left"> int2 ⟨L:1010⟩ </td><td style="text-align:left"> Vector of 2 integers </td></tr>
|
||
<tr><td style="text-align:left"> int3 ⟨L:1011⟩ </td><td style="text-align:left"> Vector of 3 integers </td></tr>
|
||
<tr><td style="text-align:left"> int4 ⟨L:1012⟩ </td><td style="text-align:left"> Vector of 4 integers </td></tr>
|
||
<tr><td style="text-align:left"> uint ⟨L:1013⟩ </td><td style="text-align:left"> Single unsigned integer </td></tr>
|
||
<tr><td style="text-align:left"> uint2 ⟨L:1014⟩ </td><td style="text-align:left"> Vector of 2 unsigned integers </td></tr>
|
||
<tr><td style="text-align:left"> uint3 ⟨L:1015⟩ </td><td style="text-align:left"> Vector of 3 unsigned integers </td></tr>
|
||
<tr><td style="text-align:left"> uint4 ⟨L:1016⟩ </td><td style="text-align:left"> Vector of 4 unsigned integers </td></tr>
|
||
<tr><td style="text-align:left"> float3×3 ⟨L:1017⟩ </td><td style="text-align:left"> Matrix of 3×3 floats </td></tr>
|
||
<tr><td style="text-align:left"> float4×4 ⟨L:1018⟩ </td><td style="text-align:left"> Matrix of 4×4 floats </td></tr>
|
||
<tr><td style="text-align:left"> sampler2d ⟨L:1019⟩ </td><td style="text-align:left"> 2D texture </td></tr>
|
||
<tr><td style="text-align:left"> sampler2dArray ⟨L:1020⟩ </td><td style="text-align:left"> Array of 2D textures </td></tr>
|
||
<tr><td style="text-align:left"> samplerExternal ⟨L:1021⟩ </td><td style="text-align:left"> External texture (platform-specific) </td></tr>
|
||
<tr><td style="text-align:left"> samplerCubemap ⟨L:1022⟩ </td><td style="text-align:left"> Cubemap texture </td></tr>
|
||
</table><center><div class="tablecaption"><b style="font-style:normal;">Table 14:</b> Material parameter types</div></center></div>
|
||
</p><p>
|
||
<dl><dt><a class="target" name="materialdefinitions/materialblock/general:parameters/def-samplers"> </a>Samplers⟨L:1025⟩</dt><dd><p> ⟨L:1026⟩Sampler types can have the following fields:
|
||
</p><p>
|
||
<ul>
|
||
<li class="minus"><code>format</code> : which can be either <code>int</code> or <code>float</code> (defaults to <code>float</code>).
|
||
</li>
|
||
<li class="minus"><code>multisample</code> : a boolean to indicate whether the sampler is meant for multisampling (defaults to <code>false</code>)
|
||
</li>
|
||
<li class="minus"><code>filterable</code> : a boolean to indicate whether the sampling is filterable
|
||
<ul>
|
||
<li class="minus">When the <code>format</code> is <code>int</code>, <code>filterable</code> is assumed to be <code>false</code>, and setting this attribute is not allowed.
|
||
</li>
|
||
<li class="minus">When the <code>format</code> is <code>float</code>, the default of <code>filterable</code> is <code>true</code>. The client must explicitly
|
||
set ⟨L:1032⟩it to <code>false</code> if they wish for unfiltered sampling.</li></ul></li></ul>
|
||
</p></dd><dt><a class="target" name="materialdefinitions/materialblock/general:parameters/def-arrays"> </a>Arrays⟨L:1034⟩</dt><dd><p> ⟨L:1035⟩A parameter can define an array of values by appending <code>[size]</code> after the type name, where
|
||
<code>size</code> ⟨L:1036⟩is a positive integer. For instance: <code>float[9]</code> declares an array of nine <code>float</code>
|
||
values. ⟨L:1037⟩This syntax does not apply to samplers as arrays are treated as separate types.
|
||
</p></dd><dt><a class="target" name="materialdefinitions/materialblock/general:parameters/def-description"> </a>Description⟨L:1039⟩</dt><dd><p> ⟨L:1040⟩Lists the parameters required by your material. These parameters can be set at runtime using
|
||
Filament's ⟨L:1041⟩material API. Accessing parameters from the shaders varies depending on the type of
|
||
parameter:⟨L:1042⟩
|
||
</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>.⟨L:1045⟩
|
||
</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 ⟨L:1047⟩instance, <code>materialParams.myColor</code>.</li></ul>
|
||
</p></dd></dl></p><pre class="listing tilde"><code><span class="line"></span>material <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> parameters <span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span>
|
||
<span class="line"></span> <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> type <span class="hljs-punctuation">:</span> float4<span class="hljs-punctuation">,</span>
|
||
<span class="line"></span> name <span class="hljs-punctuation">:</span> albedo
|
||
<span class="line"></span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
|
||
<span class="line"></span> <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> type <span class="hljs-punctuation">:</span> sampler2d<span class="hljs-punctuation">,</span>
|
||
<span class="line"></span> format <span class="hljs-punctuation">:</span> float<span class="hljs-punctuation">,</span>
|
||
<span class="line"></span> precision <span class="hljs-punctuation">:</span> high<span class="hljs-punctuation">,</span>
|
||
<span class="line"></span> name <span class="hljs-punctuation">:</span> roughness
|
||
<span class="line"></span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
|
||
<span class="line"></span> <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> type <span class="hljs-punctuation">:</span> float2<span class="hljs-punctuation">,</span>
|
||
<span class="line"></span> name <span class="hljs-punctuation">:</span> metallicReflectance
|
||
<span class="line"></span> <span class="hljs-punctuation">}</span>
|
||
<span class="line"></span> <span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span>
|
||
<span class="line"></span> requires <span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span>
|
||
<span class="line"></span> uv0
|
||
<span class="line"></span> <span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span>
|
||
<span class="line"></span> shadingModel <span class="hljs-punctuation">:</span> lit<span class="hljs-punctuation">,</span>
|
||
<span class="line"></span><span class="hljs-punctuation">}</span>
|
||
<span class="line"></span>
|
||
<span class="line"></span>fragment <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> void material(inout MaterialInputs material) <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> prepareMaterial(material);
|
||
<span class="line"></span> material.baseColor = materialParams.albedo;
|
||
<span class="line"></span> material.roughness = texture(materialParams_roughness<span class="hljs-punctuation">,</span> getUV0());
|
||
<span class="line"></span> material.metallic = materialParams.metallicReflectance.x;
|
||
<span class="line"></span> material.reflectance = materialParams.metallicReflectance.y;
|
||
<span class="line"></span> <span class="hljs-punctuation">}</span>
|
||
<span class="line"></span><span class="hljs-punctuation">}</span></code></pre>
|
||
</section><section class="h3-section"><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 id="l1084general-constants"><a class="header" href="#l1084general-constants">⟨L:1084⟩General: constants</a></h3>
|
||
<p>
|
||
<dl><dt><a class="target" name="materialdefinitions/materialblock/general:constants/def-type"> </a>Type⟨L:1086⟩</dt><dd><p> ⟨L:1087⟩array of constant objects
|
||
</p></dd><dt><a class="target" name="materialdefinitions/materialblock/general:constants/def-value"> </a>Value⟨L:1089⟩</dt><dd><p> ⟨L:1090⟩Each entry is an object with the properties <code>name</code> and <code>type</code>, both of <code>string</code> type. The name
|
||
must ⟨L:1091⟩be a valid GLSL identifier. Entries also have an optional <code>default</code>, which can either be a
|
||
<code>bool</code> ⟨L:1092⟩or <code>number</code>, depending on the <code>type</code> of the constant. The type must be one of the types
|
||
described ⟨L:1093⟩in <a href="#table_materialconstantstypes" target="_self">table 15</a>.
|
||
</p></dd></dl><div class='table'>
|
||
<a class="target" name="table_materialconstantstypes"> </a><table class="table"><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>
|
||
</table><center><div class="tablecaption"><b style="font-style:normal;">Table 15:</b> Material constants types</div></center></div>
|
||
</p><p>
|
||
<dl><dt><a class="target" name="materialdefinitions/materialblock/general:constants/def-description"> </a>Description⟨L:1102⟩</dt><dd><p> ⟨L:1103⟩Lists the constant parameters accepted by your material. These constants can be set, or
|
||
“specialized”, ⟨L:1104⟩at runtime when loading a material package. Multiple materials can be loaded from
|
||
the ⟨L:1105⟩same material package with differing constant parameter specializations. Once a material is
|
||
loaded ⟨L:1106⟩from a material package, its constant parameters cannot be changed. Compared to regular
|
||
parameters, ⟨L:1107⟩constant parameters allow the compiler to generate more efficient code. Access
|
||
constant ⟨L:1108⟩parameters from the shader by prefixing the name with <code>materialConstant_</code>. For example,
|
||
a ⟨L:1109⟩constant parameter named <code>myConstant</code> is accessed in the shader as
|
||
<code>materialConstant_myConstant</code>. ⟨L:1110⟩If a constant parameter is not set at runtime, the default is
|
||
used.⟨L:1111⟩
|
||
</p></dd></dl></p><pre class="listing tilde"><code><span class="line"></span>material <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> constants <span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span>
|
||
<span class="line"></span> <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> name <span class="hljs-punctuation">:</span> overrideAlpha<span class="hljs-punctuation">,</span>
|
||
<span class="line"></span> type <span class="hljs-punctuation">:</span> bool
|
||
<span class="line"></span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
|
||
<span class="line"></span> <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> name <span class="hljs-punctuation">:</span> customAlpha<span class="hljs-punctuation">,</span>
|
||
<span class="line"></span> type <span class="hljs-punctuation">:</span> float<span class="hljs-punctuation">,</span>
|
||
<span class="line"></span> default <span class="hljs-punctuation">:</span> <span class="hljs-number">0.5</span>
|
||
<span class="line"></span> <span class="hljs-punctuation">}</span>
|
||
<span class="line"></span> <span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span>
|
||
<span class="line"></span> shadingModel <span class="hljs-punctuation">:</span> lit<span class="hljs-punctuation">,</span>
|
||
<span class="line"></span> blending <span class="hljs-punctuation">:</span> transparent<span class="hljs-punctuation">,</span>
|
||
<span class="line"></span><span class="hljs-punctuation">}</span>
|
||
<span class="line"></span>
|
||
<span class="line"></span>fragment <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> void material(inout MaterialInputs material) <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> prepareMaterial(material);
|
||
<span class="line"></span> if (materialConstants_overrideAlpha) <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> material.baseColor.a = materialConstants_customAlpha;
|
||
<span class="line"></span> material.baseColor.rgb *= material.baseColor.a;
|
||
<span class="line"></span> <span class="hljs-punctuation">}</span>
|
||
<span class="line"></span> <span class="hljs-punctuation">}</span>
|
||
<span class="line"></span><span class="hljs-punctuation">}</span></code></pre>
|
||
</section><section class="h3-section"><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 id="l1141general-variantfilter"><a class="header" href="#l1141general-variantfilter">⟨L:1141⟩General: variantFilter</a></h3>
|
||
<p>
|
||
<dl><dt><a class="target" name="materialdefinitions/materialblock/general:variantfilter/def-type"> </a>Type⟨L:1143⟩</dt><dd><p> ⟨L:1144⟩array of <code>string</code>
|
||
</p></dd><dt><a class="target" name="materialdefinitions/materialblock/general:variantfilter/def-value"> </a>Value⟨L:1146⟩</dt><dd><p> ⟨L:1147⟩Each entry must be any of <code>dynamicLighting</code>, <code>directionalLighting</code>, <code>shadowReceiver</code>,
|
||
<code>skinning</code>, ⟨L:1148⟩<code>ssr</code>, or <code>stereo</code>.
|
||
</p></dd><dt><a class="target" name="materialdefinitions/materialblock/general:variantfilter/def-description"> </a>Description⟨L:1150⟩</dt><dd><p> ⟨L:1151⟩Used to specify a list of shader variants that the application guarantees will never be
|
||
needed. ⟨L:1152⟩These shader variants are skipped during the code generation phase, thus reducing
|
||
the ⟨L:1153⟩overall size of the material.
|
||
Note ⟨L:1154⟩that some variants may automatically be filtered out. For instance, all lighting related
|
||
variants ⟨L:1155⟩(<code>directionalLighting</code>, etc.) are filtered out when compiling an <code>unlit</code> material.
|
||
Use ⟨L:1156⟩the variant filter with caution, filtering out a variant required at runtime may lead
|
||
to ⟨L:1157⟩crashes.
|
||
</p></dd></dl>Description ⟨L:1159⟩of the variants:
|
||
</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><pre class="listing tilde"><code><span class="line"></span>material <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> name <span class="hljs-punctuation">:</span> <span class="hljs-string">"Invisible shadow plane"</span><span class="hljs-punctuation">,</span>
|
||
<span class="line"></span> shadingModel <span class="hljs-punctuation">:</span> unlit<span class="hljs-punctuation">,</span>
|
||
<span class="line"></span> shadowMultiplier <span class="hljs-punctuation">:</span> <span class="hljs-literal"><span class="hljs-keyword">true</span></span><span class="hljs-punctuation">,</span>
|
||
<span class="line"></span> blending <span class="hljs-punctuation">:</span> transparent<span class="hljs-punctuation">,</span>
|
||
<span class="line"></span> variantFilter <span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span> skinning <span class="hljs-punctuation">]</span>
|
||
<span class="line"></span><span class="hljs-punctuation">}</span></code></pre>
|
||
</section><section class="h3-section"><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 id="l1179general-flipuv"><a class="header" href="#l1179general-flipuv">⟨L:1179⟩General: flipUV</a></h3>
|
||
<p>
|
||
<dl><dt><a class="target" name="materialdefinitions/materialblock/general:flipuv/def-type"> </a>Type⟨L:1181⟩</dt><dd><p> ⟨L:1182⟩<code>boolean</code>
|
||
</p></dd><dt><a class="target" name="materialdefinitions/materialblock/general:flipuv/def-value"> </a>Value⟨L:1184⟩</dt><dd><p> ⟨L:1185⟩<code>true</code> or <code>false</code>. Defaults to <code>true</code>.
|
||
</p></dd><dt><a class="target" name="materialdefinitions/materialblock/general:flipuv/def-description"> </a>Description⟨L:1187⟩</dt><dd><p> ⟨L:1188⟩When set to <code>true</code> (default value), the Y coordinate of UV attributes will be flipped when
|
||
read ⟨L:1189⟩by this material's vertex shader. Flipping is equivalent to <code>y = 1.0 - y</code>. When set
|
||
to ⟨L:1190⟩<code>false</code>, flipping is disabled and the UV attributes are read as is.
|
||
</p></dd></dl></p><pre class="listing tilde"><code><span class="line"></span>material <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> flipUV <span class="hljs-punctuation">:</span> <span class="hljs-literal"><span class="hljs-keyword">false</span></span>
|
||
<span class="line"></span><span class="hljs-punctuation">}</span></code></pre>
|
||
</section><section class="h3-section"><a class="target" name="general:linearfog"> </a><a class="target" name="materialdefinitions/materialblock/general:linearfog"> </a><a class="target" name="toc4.2.8"> </a><h3 id="l1198general-linearfog"><a class="header" href="#l1198general-linearfog">⟨L:1198⟩General: linearFog</a></h3>
|
||
<p>
|
||
<dl><dt><a class="target" name="materialdefinitions/materialblock/general:linearfog/def-type"> </a>Type⟨L:1200⟩</dt><dd><p> ⟨L:1201⟩<code>boolean</code>
|
||
</p></dd><dt><a class="target" name="materialdefinitions/materialblock/general:linearfog/def-value"> </a>Value⟨L:1203⟩</dt><dd><p> ⟨L:1204⟩<code>true</code> or <code>false</code>. Defaults to <code>false</code>.
|
||
</p></dd><dt><a class="target" name="materialdefinitions/materialblock/general:linearfog/def-description"> </a>Description⟨L:1206⟩</dt><dd><p> ⟨L:1207⟩When set to <code>true</code>, a simplified fog equation is used for large-scale fog calculations. In this mode,
|
||
in-scattering ⟨L:1208⟩is ignored as well as height falloff.
|
||
</p></dd></dl></p><pre class="listing tilde"><code><span class="line"></span>material <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> linearFog <span class="hljs-punctuation">:</span> <span class="hljs-literal"><span class="hljs-keyword">true</span></span>
|
||
<span class="line"></span><span class="hljs-punctuation">}</span></code></pre>
|
||
</section><section class="h3-section"><a class="target" name="general:shadowfarattenuation"> </a><a class="target" name="materialdefinitions/materialblock/general:shadowfarattenuation"> </a><a class="target" name="toc4.2.9"> </a><h3 id="l1216general-shadowfarattenuation"><a class="header" href="#l1216general-shadowfarattenuation">⟨L:1216⟩General: shadowFarAttenuation</a></h3>
|
||
<p>
|
||
<dl><table><tr valign=top><td><dt><a class="target" name="materialdefinitions/materialblock/general:shadowfarattenuation/def-type"> </a>Type⟨L:1218⟩</dt></td><td><dd><p> ⟨L:1219⟩<code>boolean</code>
|
||
</p></dd></td></tr><tr valign=top><td><dt><a class="target" name="materialdefinitions/materialblock/general:shadowfarattenuation/def-value"> </a>Value⟨L:1221⟩</dt></td><td><dd><p> ⟨L:1222⟩<code>true</code> or <code>false</code>. Defaults to <code>true</code>.
|
||
</p></dd></td></tr><tr valign=top><td><dt><a class="target" name="materialdefinitions/materialblock/general:shadowfarattenuation/def-description"> </a>Description⟨L:1224⟩</dt></td><td><dd><p> ⟨L:1225⟩When set to <code>false</code>, the directional light shadow is no longer attenuated at near the far plane.
|
||
</p></dd></td></tr></table></dl></p><pre class="listing tilde"><code><span class="line"></span>material <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> shadowFarAttenuation <span class="hljs-punctuation">:</span> <span class="hljs-literal"><span class="hljs-keyword">true</span></span>
|
||
<span class="line"></span><span class="hljs-punctuation">}</span></code></pre>
|
||
</section><section class="h3-section"><a class="target" name="general:quality"> </a><a class="target" name="materialdefinitions/materialblock/general:quality"> </a><a class="target" name="toc4.2.10"> </a><h3 id="l1233general-quality"><a class="header" href="#l1233general-quality">⟨L:1233⟩General: quality</a></h3>
|
||
<p>
|
||
<dl><dt><a class="target" name="materialdefinitions/materialblock/general:quality/def-type"> </a>Type⟨L:1235⟩</dt><dd><p> ⟨L:1236⟩<code>string</code>
|
||
</p></dd><dt><a class="target" name="materialdefinitions/materialblock/general:quality/def-value"> </a>Value⟨L:1238⟩</dt><dd><p> ⟨L:1239⟩Any of <code>low</code>, <code>normal</code>, <code>high</code>, <code>default</code>. Defaults to <code>default</code>.
|
||
</p></dd><dt><a class="target" name="materialdefinitions/materialblock/general:quality/def-description"> </a>Description⟨L:1241⟩</dt><dd><p> ⟨L:1242⟩Set some global quality parameters of the material. <code>low</code> enables optimizations that can
|
||
slightly ⟨L:1243⟩affect correctness and is the default on mobile platforms. <code>normal</code> does not affect
|
||
correctness ⟨L:1244⟩and is otherwise similar to <code>low</code>. <code>high</code> enables quality settings that can
|
||
adversely ⟨L:1245⟩affect performance and is the default on desktop platforms.
|
||
</p></dd></dl></p><pre class="listing tilde"><code><span class="line"></span>material <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> quality <span class="hljs-punctuation">:</span> default
|
||
<span class="line"></span><span class="hljs-punctuation">}</span></code></pre>
|
||
</section><section class="h3-section"><a class="target" name="general:instanced"> </a><a class="target" name="materialdefinitions/materialblock/general:instanced"> </a><a class="target" name="toc4.2.11"> </a><h3 id="l1253general-instanced"><a class="header" href="#l1253general-instanced">⟨L:1253⟩General: instanced</a></h3>
|
||
<p>
|
||
<dl><dt><a class="target" name="materialdefinitions/materialblock/general:instanced/def-type"> </a>Type⟨L:1255⟩</dt><dd><p> ⟨L:1256⟩<code>boolean</code>
|
||
</p></dd><dt><a class="target" name="materialdefinitions/materialblock/general:instanced/def-value"> </a>Value⟨L:1258⟩</dt><dd><p> ⟨L:1259⟩<code>true</code> or <code>false</code>. Defaults to <code>false</code>.
|
||
</p></dd><dt><a class="target" name="materialdefinitions/materialblock/general:instanced/def-description"> </a>Description⟨L:1261⟩</dt><dd><p> ⟨L:1262⟩Allows a material to access the instance index (i.e.: <strong class="asterisk"><code>gl_InstanceIndex</code></strong>) of instanced
|
||
primitives ⟨L:1263⟩using <code>getInstanceIndex()</code> in the material's shader code. Never use
|
||
<strong class="asterisk"><code>gl_InstanceIndex</code></strong> ⟨L:1264⟩directly. This is typically used with
|
||
<code>RenderableManager::Builder::instances()</code>. ⟨L:1265⟩<code>getInstanceIndex()</code> is available in both the
|
||
vertex ⟨L:1266⟩and fragment shader.
|
||
</p></dd></dl></p><pre class="listing tilde"><code><span class="line"></span>material <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> instanced <span class="hljs-punctuation">:</span> <span class="hljs-literal"><span class="hljs-keyword">true</span></span>
|
||
<span class="line"></span><span class="hljs-punctuation">}</span></code></pre>
|
||
</section><section class="h3-section"><a class="target" name="general:vertexdomaindevicejittered"> </a><a class="target" name="materialdefinitions/materialblock/general:vertexdomaindevicejittered"> </a><a class="target" name="toc4.2.12"> </a><h3 id="l1274general-vertexdomaindevicejittered"><a class="header" href="#l1274general-vertexdomaindevicejittered">⟨L:1274⟩General: vertexDomainDeviceJittered</a></h3>
|
||
<p>
|
||
<dl><dt><a class="target" name="materialdefinitions/materialblock/general:vertexdomaindevicejittered/def-type"> </a>Type⟨L:1276⟩</dt><dd><p> ⟨L:1277⟩<code>boolean</code>
|
||
</p></dd><dt><a class="target" name="materialdefinitions/materialblock/general:vertexdomaindevicejittered/def-value"> </a>Value⟨L:1279⟩</dt><dd><p> ⟨L:1280⟩<code>true</code> or <code>false</code>. Defaults to <code>false</code>.
|
||
</p></dd><dt><a class="target" name="materialdefinitions/materialblock/general:vertexdomaindevicejittered/def-description"> </a>Description⟨L:1282⟩</dt><dd><p> ⟨L:1283⟩Only meaningful for <code>vertexDomain:Device</code> materials, this parameter specifies whether the
|
||
filament ⟨L:1284⟩clip-space transforms need to be applied or not, which affects TAA and guard bands.
|
||
Generally ⟨L:1285⟩it needs to be applied because by definition <code>vertexDomain:Device</code> materials
|
||
vertices ⟨L:1286⟩are not transformed and used <em class="asterisk">as is</em>.
|
||
However, ⟨L:1287⟩if the vertex shader uses for instance <code>getViewFromClipMatrix()</code> (or other
|
||
matrices ⟨L:1288⟩based on the projection), the clip-space transform is already applied.
|
||
Setting ⟨L:1289⟩this parameter incorrectly can prevent TAA or the guard bands to work correctly.
|
||
</p></dd></dl></p><pre class="listing tilde"><code><span class="line"></span>material <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> vertexDomainDeviceJittered <span class="hljs-punctuation">:</span> <span class="hljs-literal"><span class="hljs-keyword">true</span></span>
|
||
<span class="line"></span><span class="hljs-punctuation">}</span></code></pre>
|
||
</section><section class="h3-section"><a class="target" name="general:usedefaultdepthvariant"> </a><a class="target" name="materialdefinitions/materialblock/general:usedefaultdepthvariant"> </a><a class="target" name="toc4.2.13"> </a><h3 id="l1297general-usedefaultdepthvariant"><a class="header" href="#l1297general-usedefaultdepthvariant">⟨L:1297⟩General: useDefaultDepthVariant</a></h3>
|
||
<p>
|
||
<dl><dt><a class="target" name="materialdefinitions/materialblock/general:usedefaultdepthvariant/def-type"> </a>Type⟨L:1299⟩</dt><dd><p> ⟨L:1300⟩<code>boolean</code>
|
||
</p></dd><dt><a class="target" name="materialdefinitions/materialblock/general:usedefaultdepthvariant/def-value"> </a>Value⟨L:1302⟩</dt><dd><p> ⟨L:1303⟩<code>true</code> or <code>false</code>. Defaults to <code>false</code>.
|
||
</p></dd><dt><a class="target" name="materialdefinitions/materialblock/general:usedefaultdepthvariant/def-description"> </a>Description⟨L:1305⟩</dt><dd><p> ⟨L:1306⟩This parameter forces Filament to use its default variant for depth passes, such as those used
|
||
in ⟨L:1307⟩shadow rendering. This provides an optimization for materials with expensive custom vertex
|
||
shaders. ⟨L:1308⟩For example, custom vertex shader computations intended to be consumed by the fragment
|
||
stage ⟨L:1309⟩can be skipped during the depth-only pass. This parameter is only meaningful if the
|
||
material ⟨L:1310⟩has a vertex block.
|
||
This ⟨L:1311⟩parameter should not be set to <code>true</code> for vertex blocks that modify geometry (i.e.,
|
||
modifying ⟨L:1312⟩<code>worldPosition</code>), otherwise shadows may render incorrectly.
|
||
</p></dd></dl></p><pre class="listing tilde"><code><span class="line"></span>material <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> variables <span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span>
|
||
<span class="line"></span> customColor
|
||
<span class="line"></span> <span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span>
|
||
<span class="line"></span> useDefaultDepthVariant <span class="hljs-punctuation">:</span> <span class="hljs-literal"><span class="hljs-keyword">true</span></span>
|
||
<span class="line"></span><span class="hljs-punctuation">}</span>
|
||
<span class="line"></span>
|
||
<span class="line"></span>vertex <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> void materialVertex(inout MaterialVertexInputs material) <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> material.customColor = <span class="hljs-comment">/* expensive computation that can be skipped for depth-only passes */</span>
|
||
<span class="line"></span> <span class="hljs-punctuation">}</span>
|
||
<span class="line"></span><span class="hljs-punctuation">}</span>
|
||
<span class="line"></span>
|
||
<span class="line"></span>fragment <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> void material(inout MaterialInputs material) <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> prepareMaterial(material);
|
||
<span class="line"></span> material.baseColor = variable_customColor;
|
||
<span class="line"></span> <span class="hljs-punctuation">}</span>
|
||
<span class="line"></span><span class="hljs-punctuation">}</span></code></pre>
|
||
</section><section class="h3-section"><a class="target" name="vertexandattributes:requires"> </a><a class="target" name="materialdefinitions/materialblock/vertexandattributes:requires"> </a><a class="target" name="toc4.2.14"> </a><h3 id="l1336vertex-and-attributes-requires"><a class="header" href="#l1336vertex-and-attributes-requires">⟨L:1336⟩Vertex and attributes: requires</a></h3>
|
||
<p>
|
||
<dl><dt><a class="target" name="materialdefinitions/materialblock/vertexandattributes:requires/def-type"> </a>Type⟨L:1338⟩</dt><dd><p> ⟨L:1339⟩array of <code>string</code>
|
||
</p></dd><dt><a class="target" name="materialdefinitions/materialblock/vertexandattributes:requires/def-value"> </a>Value⟨L:1341⟩</dt><dd><p> ⟨L:1342⟩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 ⟨L:1343⟩<code>custom7</code>.
|
||
</p></dd><dt><a class="target" name="materialdefinitions/materialblock/vertexandattributes:requires/def-description"> </a>Description⟨L:1345⟩</dt><dd><p> ⟨L:1346⟩Lists the vertex attributes required by the material. The <code>position</code> attribute is always
|
||
required ⟨L:1347⟩and does not need to be specified. The <code>tangents</code> attribute is automatically required
|
||
when ⟨L:1348⟩selecting any shading model that is not <code>unlit</code>. See the shader sections of this document
|
||
for ⟨L:1349⟩more information on how to access these attributes from the shaders.
|
||
</p></dd></dl><div class="admonition ⟨L:1351⟩note"><div class="admonition-title"> Interaction with custom variables</div>
|
||
</p><p>
|
||
When ⟨L:1352⟩the <code>color</code> attribute is specified, only four custom variables are available instead of five.</div>
|
||
</p><pre class="listing tilde"><code><span class="line"></span>material <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> parameters <span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span>
|
||
<span class="line"></span> <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> type <span class="hljs-punctuation">:</span> sampler2d<span class="hljs-punctuation">,</span>
|
||
<span class="line"></span> name <span class="hljs-punctuation">:</span> texture
|
||
<span class="line"></span> <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
|
||
<span class="line"></span> <span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span>
|
||
<span class="line"></span> requires <span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span>
|
||
<span class="line"></span> uv0<span class="hljs-punctuation">,</span>
|
||
<span class="line"></span> custom0
|
||
<span class="line"></span> <span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span>
|
||
<span class="line"></span> shadingModel <span class="hljs-punctuation">:</span> lit<span class="hljs-punctuation">,</span>
|
||
<span class="line"></span><span class="hljs-punctuation">}</span>
|
||
<span class="line"></span>
|
||
<span class="line"></span>fragment <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> void material(inout MaterialInputs material) <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> prepareMaterial(material);
|
||
<span class="line"></span> material.baseColor = texture(materialParams_texture<span class="hljs-punctuation">,</span> getUV0());
|
||
<span class="line"></span> material.baseColor.rgb *= getCustom0().rgb;
|
||
<span class="line"></span> <span class="hljs-punctuation">}</span>
|
||
<span class="line"></span><span class="hljs-punctuation">}</span></code></pre>
|
||
</section><section class="h3-section"><a class="target" name="vertexandattributes:variables"> </a><a class="target" name="materialdefinitions/materialblock/vertexandattributes:variables"> </a><a class="target" name="toc4.2.15"> </a><h3 id="l1378vertex-and-attributes-variables"><a class="header" href="#l1378vertex-and-attributes-variables">⟨L:1378⟩Vertex and attributes: variables</a></h3>
|
||
<p>
|
||
<dl><dt><a class="target" name="materialdefinitions/materialblock/vertexandattributes:variables/def-type"> </a>Type⟨L:1380⟩</dt><dd><p> ⟨L:1381⟩array of <code>string</code>
|
||
</p></dd><dt><a class="target" name="materialdefinitions/materialblock/vertexandattributes:variables/def-value"> </a>Value⟨L:1383⟩</dt><dd><p> ⟨L:1384⟩Up to 5 strings, each must be a valid GLSL identifier.
|
||
</p></dd><dt><a class="target" name="materialdefinitions/materialblock/vertexandattributes:variables/def-description"> </a>Description⟨L:1386⟩</dt><dd><p> ⟨L:1387⟩Defines custom interpolants (or variables) that are output by the material's vertex shader.
|
||
Each ⟨L:1388⟩entry of the array defines the name of an interpolant. The full name in the fragment
|
||
shader ⟨L:1389⟩is the name of the interpolant with the <code>variable_</code> prefix. For instance, if you
|
||
declare ⟨L:1390⟩a variable called <code>eyeDirection</code> you can access it in the fragment shader using
|
||
<code>variable_eyeDirection</code>. ⟨L:1391⟩In the vertex shader, the interpolant name is simply a member of
|
||
the ⟨L:1392⟩<code>MaterialVertexInputs</code> structure (<code>material.eyeDirection</code> in your example). Each
|
||
interpolant ⟨L:1393⟩is of type <code>float4</code> (<code>vec4</code>) in the shaders. By default the precision of the
|
||
interpolant ⟨L:1394⟩is <code>highp</code> in <em class="asterisk">both</em> the vertex and fragment shaders.
|
||
An ⟨L:1395⟩alternate syntax can be used to specify both the name and precision of the interpolant.
|
||
In ⟨L:1396⟩this case the specified precision is used as-is in both fragment and vertex stages, in
|
||
particular ⟨L:1397⟩if <code>default</code> is specified the default precision is used is the fragment shader
|
||
(<code>mediump</code>) ⟨L:1398⟩and in the vertex shader (<code>highp</code>).
|
||
</p></dd></dl><div class="admonition ⟨L:1400⟩warning"><div class="admonition-title"> Interaction with required attributes</div>
|
||
</p><p>
|
||
If ⟨L:1401⟩the <code>color</code> attribute is specified in the <code>required</code> list, then only four variables can be used
|
||
instead ⟨L:1402⟩of five.</div>
|
||
</p><pre class="listing tilde"><code><span class="line"></span>material <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> name <span class="hljs-punctuation">:</span> Skybox<span class="hljs-punctuation">,</span>
|
||
<span class="line"></span> parameters <span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span>
|
||
<span class="line"></span> <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> type <span class="hljs-punctuation">:</span> samplerCubemap<span class="hljs-punctuation">,</span>
|
||
<span class="line"></span> name <span class="hljs-punctuation">:</span> skybox
|
||
<span class="line"></span> <span class="hljs-punctuation">}</span>
|
||
<span class="line"></span> <span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span>
|
||
<span class="line"></span> variables <span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span>
|
||
<span class="line"></span> eyeDirection<span class="hljs-punctuation">,</span>
|
||
<span class="line"></span> <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> name <span class="hljs-punctuation">:</span> eyeColor<span class="hljs-punctuation">,</span>
|
||
<span class="line"></span> precision <span class="hljs-punctuation">:</span> medium
|
||
<span class="line"></span> <span class="hljs-punctuation">}</span>
|
||
<span class="line"></span> <span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span>
|
||
<span class="line"></span> vertexDomain <span class="hljs-punctuation">:</span> device<span class="hljs-punctuation">,</span>
|
||
<span class="line"></span> depthWrite <span class="hljs-punctuation">:</span> <span class="hljs-literal"><span class="hljs-keyword">false</span></span><span class="hljs-punctuation">,</span>
|
||
<span class="line"></span> shadingModel <span class="hljs-punctuation">:</span> unlit
|
||
<span class="line"></span><span class="hljs-punctuation">}</span>
|
||
<span class="line"></span>
|
||
<span class="line"></span>fragment <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> void material(inout MaterialInputs material) <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> prepareMaterial(material);
|
||
<span class="line"></span> float3 sky = texture(materialParams_skybox<span class="hljs-punctuation">,</span> variable_eyeDirection.xyz).rgb;
|
||
<span class="line"></span> material.baseColor = vec4(sky<span class="hljs-punctuation">,</span> <span class="hljs-number">1.0</span>);
|
||
<span class="line"></span> <span class="hljs-punctuation">}</span>
|
||
<span class="line"></span><span class="hljs-punctuation">}</span>
|
||
<span class="line"></span>
|
||
<span class="line"></span>vertex <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> void materialVertex(inout MaterialVertexInputs material) <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> float3 p = getPosition().xyz;
|
||
<span class="line"></span> float3 u = mulMat4x4Float3(getViewFromClipMatrix()<span class="hljs-punctuation">,</span> p).xyz;
|
||
<span class="line"></span> material.eyeDirection.xyz = mulMat3x3Float3(getWorldFromViewMatrix()<span class="hljs-punctuation">,</span> u);
|
||
<span class="line"></span> <span class="hljs-punctuation">}</span>
|
||
<span class="line"></span><span class="hljs-punctuation">}</span></code></pre>
|
||
</section><section class="h3-section"><a class="target" name="vertexandattributes:vertexdomain"> </a><a class="target" name="materialdefinitions/materialblock/vertexandattributes:vertexdomain"> </a><a class="target" name="toc4.2.16"> </a><h3 id="l1442vertex-and-attributes-vertexdomain"><a class="header" href="#l1442vertex-and-attributes-vertexdomain">⟨L:1442⟩Vertex and attributes: vertexDomain</a></h3>
|
||
<p>
|
||
<dl><dt><a class="target" name="materialdefinitions/materialblock/vertexandattributes:vertexdomain/def-type"> </a>Type⟨L:1444⟩</dt><dd><p> ⟨L:1445⟩<code>string</code>
|
||
</p></dd><dt><a class="target" name="materialdefinitions/materialblock/vertexandattributes:vertexdomain/def-value"> </a>Value⟨L:1447⟩</dt><dd><p> ⟨L:1448⟩Any of <code>object</code>, <code>world</code>, <code>view</code>, <code>device</code>. Defaults to <code>object</code>.
|
||
</p></dd><dt><a class="target" name="materialdefinitions/materialblock/vertexandattributes:vertexdomain/def-description"> </a>Description⟨L:1450⟩</dt><dd><p> ⟨L:1451⟩Defines the domain (or coordinate space) of the rendered mesh. The domain influences how the
|
||
vertices ⟨L:1452⟩are transformed in the vertex shader. The possible domains are:
|
||
</p><p>
|
||
<ul>
|
||
<li class="minus"><strong class="asterisk">Object</strong>: the vertices are defined in the object (or model) coordinate space. The
|
||
vertices ⟨L:1455⟩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 ⟨L:1457⟩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 ⟨L:1459⟩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 ⟨L:1461⟩vertices are not transformed using the rendered object's transform.</li></ul>
|
||
</p></dd></dl></p><pre class="listing tilde"><code><span class="line"></span>material <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> vertexDomain <span class="hljs-punctuation">:</span> device
|
||
<span class="line"></span><span class="hljs-punctuation">}</span></code></pre>
|
||
</section><section class="h3-section"><a class="target" name="vertexandattributes:interpolation"> </a><a class="target" name="materialdefinitions/materialblock/vertexandattributes:interpolation"> </a><a class="target" name="toc4.2.17"> </a><h3 id="l1469vertex-and-attributes-interpolation"><a class="header" href="#l1469vertex-and-attributes-interpolation">⟨L:1469⟩Vertex and attributes: interpolation</a></h3>
|
||
<p>
|
||
<dl><dt><a class="target" name="materialdefinitions/materialblock/vertexandattributes:interpolation/def-type"> </a>Type⟨L:1471⟩</dt><dd><p> ⟨L:1472⟩<code>string</code>
|
||
</p></dd><dt><a class="target" name="materialdefinitions/materialblock/vertexandattributes:interpolation/def-value"> </a>Value⟨L:1474⟩</dt><dd><p> ⟨L:1475⟩Any of <code>smooth</code>, <code>flat</code>. Defaults to <code>smooth</code>.
|
||
</p></dd><dt><a class="target" name="materialdefinitions/materialblock/vertexandattributes:interpolation/def-description"> </a>Description⟨L:1477⟩</dt><dd><p> ⟨L:1478⟩Defines how interpolants (or variables) are interpolated between vertices. When this property
|
||
is ⟨L:1479⟩set to <code>smooth</code>, a perspective correct interpolation is performed on each interpolant.
|
||
When ⟨L:1480⟩set to <code>flat</code>, no interpolation is performed and all the fragments within a given
|
||
triangle ⟨L:1481⟩will be shaded the same.
|
||
</p></dd></dl></p><pre class="listing tilde"><code><span class="line"></span>material <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> interpolation <span class="hljs-punctuation">:</span> flat
|
||
<span class="line"></span><span class="hljs-punctuation">}</span></code></pre>
|
||
</section><section class="h3-section"><a class="target" name="blendingandtransparency:blending"> </a><a class="target" name="materialdefinitions/materialblock/blendingandtransparency:blending"> </a><a class="target" name="toc4.2.18"> </a><h3 id="l1489blending-and-transparency-blending"><a class="header" href="#l1489blending-and-transparency-blending">⟨L:1489⟩Blending and transparency: blending</a></h3>
|
||
<p>
|
||
<dl><dt><a class="target" name="materialdefinitions/materialblock/blendingandtransparency:blending/def-type"> </a>Type⟨L:1491⟩</dt><dd><p> ⟨L:1492⟩<code>string</code>
|
||
</p></dd><dt><a class="target" name="materialdefinitions/materialblock/blendingandtransparency:blending/def-value"> </a>Value⟨L:1494⟩</dt><dd><p> ⟨L:1495⟩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><a class="target" name="materialdefinitions/materialblock/blendingandtransparency:blending/def-description"> </a>Description⟨L:1497⟩</dt><dd><p> ⟨L:1498⟩Defines how/if the rendered object is blended with the content of the render target.
|
||
The ⟨L:1499⟩possible blending modes are:
|
||
</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 ⟨L:1503⟩target, using Porter-Duff's <code>source over</code> rule. This blending mode assumes
|
||
pre-multiplied ⟨L:1504⟩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> ⟨L:1506⟩mode, the material's alpha values only applies to diffuse lighting. This
|
||
blending ⟨L:1507⟩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 ⟨L:1509⟩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 ⟨L:1511⟩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 ⟨L:1513⟩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 ⟨L:1515⟩the material's output defines whether a fragment is discarded or not. Additionally,
|
||
ALPHA_TO_COVERAGE ⟨L:1516⟩is enabled for non-translucent views. See the maskThreshold section for more
|
||
information.⟨L:1517⟩
|
||
</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></dd></dl><div class="admonition ⟨L:1520⟩note">When ⟨L:1521⟩<code>blending</code> is set to <code>masked</code>, alpha to coverage is automatically enabled for the material.
|
||
If ⟨L:1522⟩this behavior is undesirable, refer to the Rasterization: alphaToCoverage section to turn
|
||
alpha ⟨L:1523⟩to coverage off using the <code>alphaToCoverage</code> property.</div>
|
||
</p><pre class="listing tilde"><code><span class="line"></span>material <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> blending <span class="hljs-punctuation">:</span> transparent
|
||
<span class="line"></span><span class="hljs-punctuation">}</span></code></pre>
|
||
</section><section class="h3-section"><a class="target" name="blendingandtransparency:blendfunction"> </a><a class="target" name="materialdefinitions/materialblock/blendingandtransparency:blendfunction"> </a><a class="target" name="toc4.2.19"> </a><h3 id="l1531blending-and-transparency-blendfunction"><a class="header" href="#l1531blending-and-transparency-blendfunction">⟨L:1531⟩Blending and transparency: blendFunction</a></h3>
|
||
<p>
|
||
<dl><dt><a class="target" name="materialdefinitions/materialblock/blendingandtransparency:blendfunction/def-type"> </a>Type⟨L:1533⟩</dt><dd><p> ⟨L:1534⟩<code>object</code>
|
||
</p></dd><dt><a class="target" name="materialdefinitions/materialblock/blendingandtransparency:blendfunction/def-fields"> </a>Fields⟨L:1536⟩</dt><dd><p> ⟨L:1537⟩<code>srcRGB</code>, <code>srcA</code>, <code>dstRGB</code>, <code>dstA</code>
|
||
</p></dd><dt><a class="target" name="materialdefinitions/materialblock/blendingandtransparency:blendfunction/def-description"> </a>Description⟨L:1539⟩</dt><dd><p> ⟨L:1540⟩- <em class="asterisk">srcRGB</em>: source function applied to the RGB channels
|
||
</p><p>
|
||
<ul>
|
||
<li class="minus"><em class="asterisk">srcA</em>: source function applied to the alpha channel
|
||
</li>
|
||
<li class="minus"><em class="asterisk">srcRGB</em>: destination function applied to the RGB channels
|
||
</li>
|
||
<li class="minus"><em class="asterisk">srcRGB</em>: destination function applied to the alpha channel
|
||
</li></ul>
|
||
The ⟨L:1544⟩values possible for each functions are one of <code>zero</code>, <code>one</code>, <code>srcColor</code>, <code>oneMinusSrcColor</code>,
|
||
<code>dstColor</code>, ⟨L:1545⟩<code>oneMinusDstColor</code>, <code>srcAlpha</code>, <code>oneMinusSrcAlpha</code>, <code>dstAlpha</code>,
|
||
<code>oneMinusDstAlpha</code>, ⟨L:1546⟩<code>srcAlphaSaturate</code>
|
||
</p></dd></dl></p><pre class="listing tilde"><code><span class="line"></span>material <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> blending <span class="hljs-punctuation">:</span> custom<span class="hljs-punctuation">,</span>
|
||
<span class="line"></span> blendFunction <span class="hljs-punctuation">:</span>
|
||
<span class="line"></span> <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> srcRGB<span class="hljs-punctuation">:</span> one<span class="hljs-punctuation">,</span>
|
||
<span class="line"></span> srcA<span class="hljs-punctuation">:</span> one<span class="hljs-punctuation">,</span>
|
||
<span class="line"></span> dstRGB<span class="hljs-punctuation">:</span> oneMinusSrcColor<span class="hljs-punctuation">,</span>
|
||
<span class="line"></span> dstA<span class="hljs-punctuation">:</span> oneMinusSrcAlpha
|
||
<span class="line"></span> <span class="hljs-punctuation">}</span>
|
||
<span class="line"></span> <span class="hljs-punctuation">}</span></code></pre>
|
||
</section><section class="h3-section"><a class="target" name="blendingandtransparency:postlightingblending"> </a><a class="target" name="materialdefinitions/materialblock/blendingandtransparency:postlightingblending"> </a><a class="target" name="toc4.2.20"> </a><h3 id="l1561blending-and-transparency-postlightingblending"><a class="header" href="#l1561blending-and-transparency-postlightingblending">⟨L:1561⟩Blending and transparency: postLightingBlending</a></h3>
|
||
<p>
|
||
<dl><dt><a class="target" name="materialdefinitions/materialblock/blendingandtransparency:postlightingblending/def-type"> </a>Type⟨L:1563⟩</dt><dd><p> ⟨L:1564⟩<code>string</code>
|
||
</p></dd><dt><a class="target" name="materialdefinitions/materialblock/blendingandtransparency:postlightingblending/def-value"> </a>Value⟨L:1566⟩</dt><dd><p> ⟨L:1567⟩Any of <code>opaque</code>, <code>transparent</code>, <code>add</code>. Defaults to <code>transparent</code>.
|
||
</p></dd><dt><a class="target" name="materialdefinitions/materialblock/blendingandtransparency:postlightingblending/def-description"> </a>Description⟨L:1569⟩</dt><dd><p> ⟨L:1570⟩Defines how the <code>postLightingColor</code> material property is blended with the result of the
|
||
lighting ⟨L:1571⟩computations. The possible blending modes are:
|
||
</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 ⟨L:1575⟩<code>postLightingColor</code>, using Porter-Duff's <code>source over</code> rule. This blending mode assumes
|
||
pre-multiplied ⟨L:1576⟩alpha.</li></ul>
|
||
</p><p>
|
||
<ul>
|
||
<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 ⟨L:1580⟩the result is added to the material's computed color.</li></ul>
|
||
</p></dd></dl></p><pre class="listing tilde"><code><span class="line"></span>material <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> postLightingBlending <span class="hljs-punctuation">:</span> add
|
||
<span class="line"></span><span class="hljs-punctuation">}</span></code></pre>
|
||
</section><section class="h3-section"><a class="target" name="blendingandtransparency:transparency"> </a><a class="target" name="materialdefinitions/materialblock/blendingandtransparency:transparency"> </a><a class="target" name="toc4.2.21"> </a><h3 id="l1588blending-and-transparency-transparency"><a class="header" href="#l1588blending-and-transparency-transparency">⟨L:1588⟩Blending and transparency: transparency</a></h3>
|
||
<p>
|
||
<dl><dt><a class="target" name="materialdefinitions/materialblock/blendingandtransparency:transparency/def-type"> </a>Type⟨L:1590⟩</dt><dd><p> ⟨L:1591⟩<code>string</code>
|
||
</p></dd><dt><a class="target" name="materialdefinitions/materialblock/blendingandtransparency:transparency/def-value"> </a>Value⟨L:1593⟩</dt><dd><p> ⟨L:1594⟩Any of <code>default</code>, <code>twoPassesOneSide</code> or <code>twoPassesTwoSides</code>. Defaults to <code>default</code>.
|
||
</p></dd><dt><a class="target" name="materialdefinitions/materialblock/blendingandtransparency:transparency/def-description"> </a>Description⟨L:1596⟩</dt><dd><p> ⟨L:1597⟩Controls how transparent objects are rendered. It is only valid when the <code>blending</code> mode is
|
||
not ⟨L:1598⟩<code>opaque</code> and <code>refractionMode</code> is <code>none</code>. None of these methods can accurately render
|
||
concave ⟨L:1599⟩geometry, but in practice they are often good enough.
|
||
</p></dd></dl>The ⟨L:1601⟩three possible transparency modes are:
|
||
</p><p>
|
||
<ul>
|
||
<li class="minus"><code>default</code>: the transparent object is rendered normally (as seen in figure ?),
|
||
honoring ⟨L:1603⟩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 ⟨L:1605⟩color buffer, honoring the <code>culling</code> mode. This effectively renders only half of the
|
||
transparent ⟨L:1606⟩object as shown in figure ?.
|
||
</li>
|
||
<li class="minus"><code>twoPassesTwoSides</code>: the transparent object is rendered twice in the color buffer: first with its
|
||
back ⟨L:1608⟩faces, then with its front faces. This mode lets you render both set of faces while reducing
|
||
or ⟨L:1609⟩eliminating sorting issues, as shown in figure ?.
|
||
<code>twoPassesTwoSides</code> ⟨L:1610⟩can be combined with <code>doubleSided</code> for better effect.</li></ul>
|
||
</p><pre class="listing tilde"><code><span class="line"></span>material <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> transparency <span class="hljs-punctuation">:</span> twoPassesOneSide
|
||
<span class="line"></span><span class="hljs-punctuation">}</span></code></pre><p>
|
||
<table width="100%"><tr valign="top"><td>
|
||
</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">Figure ⟨L:1618⟩[transparencyDefault]: This double sided model shows the type of sorting issues transparent
|
||
objects ⟨L:1619⟩can be subject to in <code>default</code> mode</span></center></div></center>
|
||
</p><p>
|
||
</td></tr><tr valign="top"><td>
|
||
</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">Figure ⟨L:1621⟩[transparencyTwoPassesOneSide]: In <code>twoPassesOneSide</code> mode, only one set of faces is visible
|
||
and ⟨L:1622⟩correctly sorted</span></center></div></center>
|
||
</p><p>
|
||
</td></tr><tr valign="top"><td>
|
||
</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">Figure ⟨L:1624⟩[transparencyTwoPassesTwoSides]: In <code>twoPassesTwoSides</code> mode, both set of faces are visible
|
||
and ⟨L:1625⟩sorting issues are minimized or eliminated</span></center></div></center>
|
||
</p><p>
|
||
</td></tr></table>
|
||
</p>
|
||
</section><section class="h3-section"><a class="target" name="blendingandtransparency:maskthreshold"> </a><a class="target" name="materialdefinitions/materialblock/blendingandtransparency:maskthreshold"> </a><a class="target" name="toc4.2.22"> </a><h3 id="l1627blending-and-transparency-maskthreshold"><a class="header" href="#l1627blending-and-transparency-maskthreshold">⟨L:1627⟩Blending and transparency: maskThreshold</a></h3>
|
||
<p>
|
||
<dl><dt><a class="target" name="materialdefinitions/materialblock/blendingandtransparency:maskthreshold/def-type"> </a>Type⟨L:1629⟩</dt><dd><p> ⟨L:1630⟩<code>number</code>
|
||
</p></dd><dt><a class="target" name="materialdefinitions/materialblock/blendingandtransparency:maskthreshold/def-value"> </a>Value⟨L:1632⟩</dt><dd><p> ⟨L:1633⟩A value between <code>0.0</code> and <code>1.0</code>. Defaults to <code>0.4</code>.
|
||
</p></dd><dt><a class="target" name="materialdefinitions/materialblock/blendingandtransparency:maskthreshold/def-description"> </a>Description⟨L:1635⟩</dt><dd><p> ⟨L:1636⟩Sets the minimum alpha value a fragment must have to not be discarded when the <code>blending</code> mode
|
||
is ⟨L:1637⟩set to <code>masked</code>. If the fragment is not discarded, its source alpha is set to 1. When the
|
||
blending ⟨L:1638⟩mode is not <code>masked</code>, this value is ignored. This value can be used to controlled the
|
||
appearance ⟨L:1639⟩of alpha-masked objects.
|
||
</p></dd></dl></p><pre class="listing tilde"><code><span class="line"></span>material <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> blending <span class="hljs-punctuation">:</span> masked<span class="hljs-punctuation">,</span>
|
||
<span class="line"></span> maskThreshold <span class="hljs-punctuation">:</span> <span class="hljs-number">0.5</span>
|
||
<span class="line"></span><span class="hljs-punctuation">}</span></code></pre>
|
||
</section><section class="h3-section"><a class="target" name="blendingandtransparency:refractionmode"> </a><a class="target" name="materialdefinitions/materialblock/blendingandtransparency:refractionmode"> </a><a class="target" name="toc4.2.23"> </a><h3 id="l1648blending-and-transparency-refractionmode"><a class="header" href="#l1648blending-and-transparency-refractionmode">⟨L:1648⟩Blending and transparency: refractionMode</a></h3>
|
||
<p>
|
||
<dl><dt><a class="target" name="materialdefinitions/materialblock/blendingandtransparency:refractionmode/def-type"> </a>Type⟨L:1650⟩</dt><dd><p> ⟨L:1651⟩<code>string</code>
|
||
</p></dd><dt><a class="target" name="materialdefinitions/materialblock/blendingandtransparency:refractionmode/def-value"> </a>Value⟨L:1653⟩</dt><dd><p> ⟨L:1654⟩Any of <code>none</code>, <code>cubemap</code>, <code>screenspace</code>. Defaults to <code>none</code>.
|
||
</p></dd><dt><a class="target" name="materialdefinitions/materialblock/blendingandtransparency:refractionmode/def-description"> </a>Description⟨L:1656⟩</dt><dd><p> ⟨L:1657⟩Activates refraction when set to anything but <code>none</code>. A value of <code>cubemap</code> will only use the
|
||
IBL ⟨L:1658⟩cubemap as source of refraction, while this is significantly more efficient, no scene
|
||
objects ⟨L:1659⟩will be refracted, only the distant environment encoded in the cubemap. This mode is
|
||
adequate ⟨L:1660⟩for an object viewer for instance. A value of <code>screenspace</code> will employ the more
|
||
advanced ⟨L:1661⟩screen-space refraction algorithm which allows opaque objects in the scene to be
|
||
refracted. ⟨L:1662⟩In <code>cubemap</code> mode, refracted rays are assumed to emerge from the center of the
|
||
object ⟨L:1663⟩and the <code>thickness</code> parameter is only used for computing the absorption, but has no
|
||
impact ⟨L:1664⟩on the refraction itself. In <code>screenspace</code> mode, refracted rays are assumed to travel
|
||
parallel ⟨L:1665⟩to the view direction when they exit the refractive medium.
|
||
</p></dd></dl></p><pre class="listing tilde"><code><span class="line"></span>material <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> refractionMode <span class="hljs-punctuation">:</span> cubemap<span class="hljs-punctuation">,</span>
|
||
<span class="line"></span><span class="hljs-punctuation">}</span></code></pre>
|
||
</section><section class="h3-section"><a class="target" name="blendingandtransparency:refractiontype"> </a><a class="target" name="materialdefinitions/materialblock/blendingandtransparency:refractiontype"> </a><a class="target" name="toc4.2.24"> </a><h3 id="l1673blending-and-transparency-refractiontype"><a class="header" href="#l1673blending-and-transparency-refractiontype">⟨L:1673⟩Blending and transparency: refractionType</a></h3>
|
||
<p>
|
||
<dl><dt><a class="target" name="materialdefinitions/materialblock/blendingandtransparency:refractiontype/def-type"> </a>Type⟨L:1675⟩</dt><dd><p> ⟨L:1676⟩<code>string</code>
|
||
</p></dd><dt><a class="target" name="materialdefinitions/materialblock/blendingandtransparency:refractiontype/def-value"> </a>Value⟨L:1678⟩</dt><dd><p> ⟨L:1679⟩Any of <code>solid</code>, <code>thin</code>. Defaults to <code>solid</code>.
|
||
</p></dd><dt><a class="target" name="materialdefinitions/materialblock/blendingandtransparency:refractiontype/def-description"> </a>Description⟨L:1681⟩</dt><dd><p> ⟨L:1682⟩This is only meaningful when <code>refractionMode</code> is set to anything but <code>none</code>. <code>refractionType</code>
|
||
defines ⟨L:1683⟩the refraction model used. <code>solid</code> is used for thick objects such as a crystal ball,
|
||
an ⟨L:1684⟩ice cube or as sculpture. <code>thin</code> is used for thin objects such as a window, an ornament
|
||
ball ⟨L:1685⟩or a soap bubble. In <code>solid</code> mode all refracive objects are assumed to be a sphere
|
||
tangent ⟨L:1686⟩to the entry point and of radius <code>thickness</code>. In <code>thin</code> mode, all refractive objects
|
||
are ⟨L:1687⟩assumed to be flat and thin and of thickness <code>thickness</code>.
|
||
</p></dd></dl></p><pre class="listing tilde"><code><span class="line"></span>material <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> refractionMode <span class="hljs-punctuation">:</span> cubemap<span class="hljs-punctuation">,</span>
|
||
<span class="line"></span> refractionType <span class="hljs-punctuation">:</span> thin<span class="hljs-punctuation">,</span>
|
||
<span class="line"></span><span class="hljs-punctuation">}</span></code></pre>
|
||
</section><section class="h3-section"><a class="target" name="rasterization:culling"> </a><a class="target" name="materialdefinitions/materialblock/rasterization:culling"> </a><a class="target" name="toc4.2.25"> </a><h3 id="l1696rasterization-culling"><a class="header" href="#l1696rasterization-culling">⟨L:1696⟩Rasterization: culling</a></h3>
|
||
<p>
|
||
<dl><table><tr valign=top><td><dt><a class="target" name="materialdefinitions/materialblock/rasterization:culling/def-type"> </a>Type⟨L:1698⟩</dt></td><td><dd><p> ⟨L:1699⟩<code>string</code>
|
||
</p></dd></td></tr><tr valign=top><td><dt><a class="target" name="materialdefinitions/materialblock/rasterization:culling/def-value"> </a>Value⟨L:1701⟩</dt></td><td><dd><p> ⟨L:1702⟩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><a class="target" name="materialdefinitions/materialblock/rasterization:culling/def-description"> </a>Description⟨L:1704⟩</dt></td><td><dd><p> ⟨L:1705⟩Defines which triangles should be culled: none, front-facing triangles, back-facing
|
||
triangles ⟨L:1706⟩or all.
|
||
</p></dd></td></tr></table></dl></p><pre class="listing tilde"><code><span class="line"></span>material <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> culling <span class="hljs-punctuation">:</span> none
|
||
<span class="line"></span><span class="hljs-punctuation">}</span></code></pre>
|
||
</section><section class="h3-section"><a class="target" name="rasterization:colorwrite"> </a><a class="target" name="materialdefinitions/materialblock/rasterization:colorwrite"> </a><a class="target" name="toc4.2.26"> </a><h3 id="l1714rasterization-colorwrite"><a class="header" href="#l1714rasterization-colorwrite">⟨L:1714⟩Rasterization: colorWrite</a></h3>
|
||
<p>
|
||
<dl><table><tr valign=top><td><dt><a class="target" name="materialdefinitions/materialblock/rasterization:colorwrite/def-type"> </a>Type⟨L:1716⟩</dt></td><td><dd><p> ⟨L:1717⟩<code>boolean</code>
|
||
</p></dd></td></tr><tr valign=top><td><dt><a class="target" name="materialdefinitions/materialblock/rasterization:colorwrite/def-value"> </a>Value⟨L:1719⟩</dt></td><td><dd><p> ⟨L:1720⟩<code>true</code> or <code>false</code>. Defaults to <code>true</code>.
|
||
</p></dd></td></tr><tr valign=top><td><dt><a class="target" name="materialdefinitions/materialblock/rasterization:colorwrite/def-description"> </a>Description⟨L:1722⟩</dt></td><td><dd><p> ⟨L:1723⟩Enables or disables writes to the color buffer.
|
||
</p></dd></td></tr></table></dl></p><pre class="listing tilde"><code><span class="line"></span>material <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> colorWrite <span class="hljs-punctuation">:</span> <span class="hljs-literal"><span class="hljs-keyword">false</span></span>
|
||
<span class="line"></span><span class="hljs-punctuation">}</span></code></pre>
|
||
</section><section class="h3-section"><a class="target" name="rasterization:depthwrite"> </a><a class="target" name="materialdefinitions/materialblock/rasterization:depthwrite"> </a><a class="target" name="toc4.2.27"> </a><h3 id="l1731rasterization-depthwrite"><a class="header" href="#l1731rasterization-depthwrite">⟨L:1731⟩Rasterization: depthWrite</a></h3>
|
||
<p>
|
||
<dl><table><tr valign=top><td><dt><a class="target" name="materialdefinitions/materialblock/rasterization:depthwrite/def-type"> </a>Type⟨L:1733⟩</dt></td><td><dd><p> ⟨L:1734⟩<code>boolean</code>
|
||
</p></dd></td></tr><tr valign=top><td><dt><a class="target" name="materialdefinitions/materialblock/rasterization:depthwrite/def-value"> </a>Value⟨L:1736⟩</dt></td><td><dd><p> ⟨L:1737⟩<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><a class="target" name="materialdefinitions/materialblock/rasterization:depthwrite/def-description"> </a>Description⟨L:1739⟩</dt></td><td><dd><p> ⟨L:1740⟩Enables or disables writes to the depth buffer.
|
||
</p></dd></td></tr></table></dl></p><pre class="listing tilde"><code><span class="line"></span>material <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> depthWrite <span class="hljs-punctuation">:</span> <span class="hljs-literal"><span class="hljs-keyword">false</span></span>
|
||
<span class="line"></span><span class="hljs-punctuation">}</span></code></pre>
|
||
</section><section class="h3-section"><a class="target" name="rasterization:depthculling"> </a><a class="target" name="materialdefinitions/materialblock/rasterization:depthculling"> </a><a class="target" name="toc4.2.28"> </a><h3 id="l1748rasterization-depthculling"><a class="header" href="#l1748rasterization-depthculling">⟨L:1748⟩Rasterization: depthCulling</a></h3>
|
||
<p>
|
||
<dl><dt><a class="target" name="materialdefinitions/materialblock/rasterization:depthculling/def-type"> </a>Type⟨L:1750⟩</dt><dd><p> ⟨L:1751⟩<code>boolean</code>
|
||
</p></dd><dt><a class="target" name="materialdefinitions/materialblock/rasterization:depthculling/def-value"> </a>Value⟨L:1753⟩</dt><dd><p> ⟨L:1754⟩<code>true</code> or <code>false</code>. Defaults to <code>true</code>.
|
||
</p></dd><dt><a class="target" name="materialdefinitions/materialblock/rasterization:depthculling/def-description"> </a>Description⟨L:1756⟩</dt><dd><p> ⟨L:1757⟩Enables or disables depth testing. When depth testing is disabled, an object rendered with
|
||
this ⟨L:1758⟩material will always appear on top of other opaque objects.
|
||
</p></dd></dl></p><pre class="listing tilde"><code><span class="line"></span>material <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> depthCulling <span class="hljs-punctuation">:</span> <span class="hljs-literal"><span class="hljs-keyword">false</span></span>
|
||
<span class="line"></span><span class="hljs-punctuation">}</span></code></pre>
|
||
</section><section class="h3-section"><a class="target" name="rasterization:doublesided"> </a><a class="target" name="materialdefinitions/materialblock/rasterization:doublesided"> </a><a class="target" name="toc4.2.29"> </a><h3 id="l1766rasterization-doublesided"><a class="header" href="#l1766rasterization-doublesided">⟨L:1766⟩Rasterization: doubleSided</a></h3>
|
||
<p>
|
||
<dl><dt><a class="target" name="materialdefinitions/materialblock/rasterization:doublesided/def-type"> </a>Type⟨L:1768⟩</dt><dd><p> ⟨L:1769⟩<code>boolean</code>
|
||
</p></dd><dt><a class="target" name="materialdefinitions/materialblock/rasterization:doublesided/def-value"> </a>Value⟨L:1771⟩</dt><dd><p> ⟨L:1772⟩<code>true</code> or <code>false</code>. Defaults to <code>false</code>.
|
||
</p></dd><dt><a class="target" name="materialdefinitions/materialblock/rasterization:doublesided/def-description"> </a>Description⟨L:1774⟩</dt><dd><p> ⟨L:1775⟩Enables two-sided rendering and its capability to be toggled at run time. When set to <code>true</code>,
|
||
<code>culling</code> ⟨L:1776⟩is automatically set to <code>none</code>; if the triangle is back-facing, the triangle's
|
||
normal ⟨L:1777⟩is flipped to become front-facing. When explicitly set to <code>false</code>, this allows the
|
||
double-sidedness ⟨L:1778⟩to be toggled at run time.
|
||
</p></dd></dl></p><pre class="listing tilde"><code><span class="line"></span>material <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> name <span class="hljs-punctuation">:</span> <span class="hljs-string">"Double sided material"</span><span class="hljs-punctuation">,</span>
|
||
<span class="line"></span> shadingModel <span class="hljs-punctuation">:</span> lit<span class="hljs-punctuation">,</span>
|
||
<span class="line"></span> doubleSided <span class="hljs-punctuation">:</span> <span class="hljs-literal"><span class="hljs-keyword">true</span></span>
|
||
<span class="line"></span><span class="hljs-punctuation">}</span>
|
||
<span class="line"></span>
|
||
<span class="line"></span>fragment <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> void material(inout MaterialInputs material) <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> prepareMaterial(material);
|
||
<span class="line"></span> material.baseColor = materialParams.albedo;
|
||
<span class="line"></span> <span class="hljs-punctuation">}</span>
|
||
<span class="line"></span><span class="hljs-punctuation">}</span></code></pre>
|
||
</section><section class="h3-section"><a class="target" name="rasterization:alphatocoverage"> </a><a class="target" name="materialdefinitions/materialblock/rasterization:alphatocoverage"> </a><a class="target" name="toc4.2.30"> </a><h3 id="l1795rasterization-alphatocoverage"><a class="header" href="#l1795rasterization-alphatocoverage">⟨L:1795⟩Rasterization: alphaToCoverage</a></h3>
|
||
<p>
|
||
<dl><dt><a class="target" name="materialdefinitions/materialblock/rasterization:alphatocoverage/def-type"> </a>Type⟨L:1797⟩</dt><dd><p> ⟨L:1798⟩<code>boolean</code>
|
||
</p></dd><dt><a class="target" name="materialdefinitions/materialblock/rasterization:alphatocoverage/def-value"> </a>Value⟨L:1800⟩</dt><dd><p> ⟨L:1801⟩<code>true</code> or <code>false</code>. Defaults to <code>false</code>.
|
||
</p></dd><dt><a class="target" name="materialdefinitions/materialblock/rasterization:alphatocoverage/def-description"> </a>Description⟨L:1803⟩</dt><dd><p> ⟨L:1804⟩Enables or disables alpha to coverage. When alpha to coverage is enabled, the coverage of
|
||
fragment ⟨L:1805⟩is derived from its alpha. This property is only meaningful when MSAA is enabled.
|
||
Note: ⟨L:1806⟩setting <code>blending</code> to <code>masked</code> automatically enables alpha to coverage. If this is not
|
||
desired, ⟨L:1807⟩you can override this behavior by setting alpha to coverage to false as in the
|
||
example ⟨L:1808⟩below.
|
||
</p></dd></dl></p><pre class="listing tilde"><code><span class="line"></span>material <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> name <span class="hljs-punctuation">:</span> <span class="hljs-string">"Alpha to coverage"</span><span class="hljs-punctuation">,</span>
|
||
<span class="line"></span> shadingModel <span class="hljs-punctuation">:</span> lit<span class="hljs-punctuation">,</span>
|
||
<span class="line"></span> blending <span class="hljs-punctuation">:</span> masked<span class="hljs-punctuation">,</span>
|
||
<span class="line"></span> alphaToCoverage <span class="hljs-punctuation">:</span> <span class="hljs-literal"><span class="hljs-keyword">false</span></span>
|
||
<span class="line"></span><span class="hljs-punctuation">}</span>
|
||
<span class="line"></span>
|
||
<span class="line"></span>fragment <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> void material(inout MaterialInputs material) <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> prepareMaterial(material);
|
||
<span class="line"></span> material.baseColor = materialParams.albedo;
|
||
<span class="line"></span> <span class="hljs-punctuation">}</span>
|
||
<span class="line"></span><span class="hljs-punctuation">}</span></code></pre>
|
||
</section><section class="h3-section"><a class="target" name="lighting:reflections"> </a><a class="target" name="materialdefinitions/materialblock/lighting:reflections"> </a><a class="target" name="toc4.2.31"> </a><h3 id="l1826lighting-reflections"><a class="header" href="#l1826lighting-reflections">⟨L:1826⟩Lighting: reflections</a></h3>
|
||
<p>
|
||
<dl><dt><a class="target" name="materialdefinitions/materialblock/lighting:reflections/def-type"> </a>Type⟨L:1828⟩</dt><dd><p> ⟨L:1829⟩<code>string</code>
|
||
</p></dd><dt><a class="target" name="materialdefinitions/materialblock/lighting:reflections/def-value"> </a>Value⟨L:1831⟩</dt><dd><p> ⟨L:1832⟩<code>default</code> or <code>screenspace</code>. Defaults to <code>default</code>.
|
||
</p></dd><dt><a class="target" name="materialdefinitions/materialblock/lighting:reflections/def-description"> </a>Description⟨L:1834⟩</dt><dd><p> ⟨L:1835⟩Controls the source of specular reflections for this material. When this property is set to
|
||
<code>default</code>, ⟨L:1836⟩reflections only come image-based lights. When this property is set to
|
||
<code>screenspace</code>, ⟨L:1837⟩reflections come from the screen space's color buffer in addition to
|
||
image-based ⟨L:1838⟩lights.
|
||
</p></dd></dl></p><pre class="listing tilde"><code><span class="line"></span>material <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> name <span class="hljs-punctuation">:</span> <span class="hljs-string">"Glossy metal"</span><span class="hljs-punctuation">,</span>
|
||
<span class="line"></span> reflections <span class="hljs-punctuation">:</span> screenspace
|
||
<span class="line"></span><span class="hljs-punctuation">}</span></code></pre>
|
||
</section><section class="h3-section"><a class="target" name="lighting:shadowmultiplier"> </a><a class="target" name="materialdefinitions/materialblock/lighting:shadowmultiplier"> </a><a class="target" name="toc4.2.32"> </a><h3 id="l1847lighting-shadowmultiplier"><a class="header" href="#l1847lighting-shadowmultiplier">⟨L:1847⟩Lighting: shadowMultiplier</a></h3>
|
||
<p>
|
||
<dl><dt><a class="target" name="materialdefinitions/materialblock/lighting:shadowmultiplier/def-type"> </a>Type⟨L:1849⟩</dt><dd><p> ⟨L:1850⟩<code>boolean</code>
|
||
</p></dd><dt><a class="target" name="materialdefinitions/materialblock/lighting:shadowmultiplier/def-value"> </a>Value⟨L:1852⟩</dt><dd><p> ⟨L:1853⟩<code>true</code> or <code>false</code>. Defaults to <code>false</code>.
|
||
</p></dd><dt><a class="target" name="materialdefinitions/materialblock/lighting:shadowmultiplier/def-description"> </a>Description⟨L:1855⟩</dt><dd><p> ⟨L:1856⟩Only available in the <code>unlit</code> shading model. If this property is enabled, the final color
|
||
computed ⟨L:1857⟩by the material is multiplied by the shadowing factor (or visibility). This allows to
|
||
create ⟨L:1858⟩transparent shadow-receiving objects (for instance an invisible ground plane in AR).
|
||
This ⟨L:1859⟩is only supported with shadows from directional lights.
|
||
</p></dd></dl></p><pre class="listing tilde"><code><span class="line"></span>material <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> name <span class="hljs-punctuation">:</span> <span class="hljs-string">"Invisible shadow plane"</span><span class="hljs-punctuation">,</span>
|
||
<span class="line"></span> shadingModel <span class="hljs-punctuation">:</span> unlit<span class="hljs-punctuation">,</span>
|
||
<span class="line"></span> shadowMultiplier <span class="hljs-punctuation">:</span> <span class="hljs-literal"><span class="hljs-keyword">true</span></span><span class="hljs-punctuation">,</span>
|
||
<span class="line"></span> blending <span class="hljs-punctuation">:</span> transparent
|
||
<span class="line"></span><span class="hljs-punctuation">}</span>
|
||
<span class="line"></span>
|
||
<span class="line"></span>fragment <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> void material(inout MaterialInputs material) <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> prepareMaterial(material);
|
||
<span class="line"></span> <span class="hljs-comment">// baseColor defines the color and opacity of the final shadow</span>
|
||
<span class="line"></span> material.baseColor = vec4(<span class="hljs-number">0.0</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0.0</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0.0</span><span class="hljs-punctuation">,</span> <span class="hljs-number">0.7</span>);
|
||
<span class="line"></span> <span class="hljs-punctuation">}</span>
|
||
<span class="line"></span><span class="hljs-punctuation">}</span></code></pre>
|
||
</section><section class="h3-section"><a class="target" name="lighting:transparentshadow"> </a><a class="target" name="materialdefinitions/materialblock/lighting:transparentshadow"> </a><a class="target" name="toc4.2.33"> </a><h3 id="l1878lighting-transparentshadow"><a class="header" href="#l1878lighting-transparentshadow">⟨L:1878⟩Lighting: transparentShadow</a></h3>
|
||
<p>
|
||
<dl><dt><a class="target" name="materialdefinitions/materialblock/lighting:transparentshadow/def-type"> </a>Type⟨L:1880⟩</dt><dd><p> ⟨L:1881⟩<code>boolean</code>
|
||
</p></dd><dt><a class="target" name="materialdefinitions/materialblock/lighting:transparentshadow/def-value"> </a>Value⟨L:1883⟩</dt><dd><p> ⟨L:1884⟩<code>true</code> or <code>false</code>. Defaults to <code>false</code>.
|
||
</p></dd><dt><a class="target" name="materialdefinitions/materialblock/lighting:transparentshadow/def-description"> </a>Description⟨L:1886⟩</dt><dd><p> ⟨L:1887⟩Enables transparent shadows on this material. When this feature is enabled, Filament emulates
|
||
transparent ⟨L:1888⟩shadows using a dithering pattern: they work best with variance shadow maps (VSM)
|
||
and ⟨L:1889⟩blurring enabled. The opacity of the shadow derives directly from the alpha channel of
|
||
the ⟨L:1890⟩material's <code>baseColor</code> property. Transparent shadows can be enabled on opaque objects,
|
||
making ⟨L:1891⟩them compatible with refractive/transmissive objects that are otherwise considered
|
||
opaque.⟨L:1892⟩
|
||
</p></dd></dl></p><pre class="listing tilde"><code><span class="line"></span>material <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> name <span class="hljs-punctuation">:</span> <span class="hljs-string">"Clear plastic with stickers"</span><span class="hljs-punctuation">,</span>
|
||
<span class="line"></span> transparentShadow <span class="hljs-punctuation">:</span> <span class="hljs-literal"><span class="hljs-keyword">true</span></span><span class="hljs-punctuation">,</span>
|
||
<span class="line"></span> blending <span class="hljs-punctuation">:</span> transparent<span class="hljs-punctuation">,</span>
|
||
<span class="line"></span> <span class="hljs-comment">// ...</span>
|
||
<span class="line"></span><span class="hljs-punctuation">}</span>
|
||
<span class="line"></span>
|
||
<span class="line"></span>fragment <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> void material(inout MaterialInputs material) <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> prepareMaterial(material);
|
||
<span class="line"></span> material.baseColor = texture(materialParams_baseColor<span class="hljs-punctuation">,</span> getUV0());
|
||
<span class="line"></span> <span class="hljs-punctuation">}</span>
|
||
<span class="line"></span><span class="hljs-punctuation">}</span></code></pre><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">Figure ⟨L:1910⟩[transparentShadow]: Objects rendered with transparent shadows and blurry VSM with a
|
||
radius ⟨L:1911⟩of 4. Model <a href="https://sketchfab.com/3d-models/bottle-of-water-48fd4f6e90d84d89b5740ee78587d0ff">Bottle of Water</a>
|
||
by ⟨L:1912⟩<a href="https://sketchfab.com/person-x">T-Art</a>.</span></center></div></center>
|
||
</p>
|
||
</section><section class="h3-section"><a class="target" name="lighting:clearcoatiorchange"> </a><a class="target" name="materialdefinitions/materialblock/lighting:clearcoatiorchange"> </a><a class="target" name="toc4.2.34"> </a><h3 id="l1914lighting-clearcoatiorchange"><a class="header" href="#l1914lighting-clearcoatiorchange">⟨L:1914⟩Lighting: clearCoatIorChange</a></h3>
|
||
<p>
|
||
<dl><dt><a class="target" name="materialdefinitions/materialblock/lighting:clearcoatiorchange/def-type"> </a>Type⟨L:1916⟩</dt><dd><p> ⟨L:1917⟩<code>boolean</code>
|
||
</p></dd><dt><a class="target" name="materialdefinitions/materialblock/lighting:clearcoatiorchange/def-value"> </a>Value⟨L:1919⟩</dt><dd><p> ⟨L:1920⟩<code>true</code> or <code>false</code>. Defaults to <code>true</code>.
|
||
</p></dd><dt><a class="target" name="materialdefinitions/materialblock/lighting:clearcoatiorchange/def-description"> </a>Description⟨L:1922⟩</dt><dd><p> ⟨L:1923⟩When adding a clear coat layer, the change in index of refraction (IoR) is taken into account
|
||
to ⟨L:1924⟩modify the specular color of the base layer. This appears to darken <code>baseColor</code>. When this
|
||
effect ⟨L:1925⟩is disabled, <code>baseColor</code> is left unmodified. See figure ? for an
|
||
example ⟨L:1926⟩of how this property can affect a red metallic base layer.
|
||
</p></dd></dl></p><pre class="listing tilde"><code><span class="line"></span>material <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> clearCoatIorChange <span class="hljs-punctuation">:</span> <span class="hljs-literal"><span class="hljs-keyword">false</span></span>
|
||
<span class="line"></span><span class="hljs-punctuation">}</span></code></pre><p>
|
||
<div class="image" style="float:right;margin:4px 0px 0px 25px;"><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">Figure ⟨L:1934⟩[clearCoatIorChange]: The same rough metallic ball with a clear coat layer rendered
|
||
with ⟨L:1935⟩<code>clearCoatIorChange</code> enabled (left) and disabled
|
||
(right).</span></center></div>⟨L:1936⟩
|
||
</p>
|
||
</section><section class="h3-section"><a class="target" name="lighting:multibounceambientocclusion"> </a><a class="target" name="materialdefinitions/materialblock/lighting:multibounceambientocclusion"> </a><a class="target" name="toc4.2.35"> </a><h3 id="l1938lighting-multibounceambientocclusion"><a class="header" href="#l1938lighting-multibounceambientocclusion">⟨L:1938⟩Lighting: multiBounceAmbientOcclusion</a></h3>
|
||
<p>
|
||
<dl><dt><a class="target" name="materialdefinitions/materialblock/lighting:multibounceambientocclusion/def-type"> </a>Type⟨L:1940⟩</dt><dd><p> ⟨L:1941⟩<code>boolean</code>
|
||
</p></dd><dt><a class="target" name="materialdefinitions/materialblock/lighting:multibounceambientocclusion/def-value"> </a>Value⟨L:1943⟩</dt><dd><p> ⟨L:1944⟩<code>true</code> or <code>false</code>. Defaults to <code>false</code> on mobile, <code>true</code> on desktop.
|
||
</p></dd><dt><a class="target" name="materialdefinitions/materialblock/lighting:multibounceambientocclusion/def-description"> </a>Description⟨L:1946⟩</dt><dd><p> ⟨L:1947⟩Multi-bounce ambient occlusion takes into account interreflections when applying ambient
|
||
occlusion ⟨L:1948⟩to image-based lighting. Turning this feature on avoids over-darkening occluded
|
||
areas. ⟨L:1949⟩It also takes the surface color into account to generate colored ambient occlusion.
|
||
Figure ⟨L:1950⟩[multiBounceAO] compares the ambient occlusion term of a surface with and without
|
||
multi-bounce ⟨L:1951⟩ambient occlusion. Notice how multi-bounce ambient occlusion introduces color
|
||
in ⟨L:1952⟩the occluded areas. Figure ? toggles between multi-bounce ambient
|
||
occlusion ⟨L:1953⟩on and off on a lit brick material to highlight the effects of this property.
|
||
</p></dd></dl></p><pre class="listing tilde"><code><span class="line"></span>material <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> multiBounceAmbientOcclusion <span class="hljs-punctuation">:</span> <span class="hljs-literal"><span class="hljs-keyword">true</span></span>
|
||
<span class="line"></span><span class="hljs-punctuation">}</span></code></pre><p>
|
||
<table width="100%"><tr valign="top"><td>
|
||
</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">Figure ⟨L:1961⟩[multiBounceAO]: Brick texture amient occlusion map rendered with multi-bounce ambient
|
||
occclusion ⟨L:1962⟩enabled (left) and disabled (right).</span></center></div></center>
|
||
</p><p>
|
||
</td></tr><tr valign="top"><td>
|
||
</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">Figure ⟨L:1964⟩[multiBounceAOAnimated]: Brick texture rendered with multi-bounce ambient
|
||
occclusion ⟨L:1965⟩enabled and disabled.</span></center></div></center>
|
||
</p><p>
|
||
</td></tr></table>
|
||
</p>
|
||
</section><section class="h3-section"><a class="target" name="lighting:specularambientocclusion"> </a><a class="target" name="materialdefinitions/materialblock/lighting:specularambientocclusion"> </a><a class="target" name="toc4.2.36"> </a><h3 id="l1967lighting-specularambientocclusion"><a class="header" href="#l1967lighting-specularambientocclusion">⟨L:1967⟩Lighting: specularAmbientOcclusion</a></h3>
|
||
<p>
|
||
<dl><dt><a class="target" name="materialdefinitions/materialblock/lighting:specularambientocclusion/def-type"> </a>Type⟨L:1969⟩</dt><dd><p> ⟨L:1970⟩<code>string</code>
|
||
</p></dd><dt><a class="target" name="materialdefinitions/materialblock/lighting:specularambientocclusion/def-value"> </a>Value⟨L:1972⟩</dt><dd><p> ⟨L:1973⟩<code>none</code>, <code>simple</code> or <code>bentNormals</code>. Defaults to <code>none</code> on mobile, <code>simple</code> on desktop. For
|
||
compatibility ⟨L:1974⟩reasons, <code>true</code> and <code>false</code> are also accepted and map respectively to <code>simple</code>
|
||
and ⟨L:1975⟩<code>none</code>.
|
||
</p></dd><dt><a class="target" name="materialdefinitions/materialblock/lighting:specularambientocclusion/def-description"> </a>Description⟨L:1977⟩</dt><dd><p> ⟨L:1978⟩Static ambient occlusion maps and dynamic ambient occlusion (SSAO, etc.) apply to diffuse
|
||
indirect ⟨L:1979⟩lighting. When setting this property to other than <code>none</code>, a new ambient occlusion
|
||
term ⟨L:1980⟩is derived from the surface roughness and applied to specular indirect lighting.
|
||
This ⟨L:1981⟩effect helps remove unwanted specular reflections as shown in figure ?.
|
||
When ⟨L:1982⟩this value is set to <code>simple</code>, Filament uses a cheap but approximate method of computing
|
||
the ⟨L:1983⟩specular ambient occlusion term. If this value is set to <code>bentNormals</code>, Filament will use
|
||
a ⟨L:1984⟩much more accurate but much more expensive method.
|
||
</p></dd></dl></p><pre class="listing tilde"><code><span class="line"></span>material <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> specularAmbientOcclusion <span class="hljs-punctuation">:</span> simple
|
||
<span class="line"></span><span class="hljs-punctuation">}</span></code></pre><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">Figure ⟨L:1992⟩[specularAO]: Comparison of specular ambient occlusion on and off. The effect is
|
||
particularly ⟨L:1993⟩visible under the hose.</span></center></div></center>
|
||
</p>
|
||
</section><section class="h3-section"><a class="target" name="anti-aliasing:specularantialiasing"> </a><a class="target" name="materialdefinitions/materialblock/anti-aliasing:specularantialiasing"> </a><a class="target" name="toc4.2.37"> </a><h3 id="l1995anti-aliasing-specularantialiasing"><a class="header" href="#l1995anti-aliasing-specularantialiasing">⟨L:1995⟩Anti-aliasing: specularAntiAliasing</a></h3>
|
||
<p>
|
||
<dl><dt><a class="target" name="materialdefinitions/materialblock/anti-aliasing:specularantialiasing/def-type"> </a>Type⟨L:1997⟩</dt><dd><p> ⟨L:1998⟩<code>boolean</code>
|
||
</p></dd><dt><a class="target" name="materialdefinitions/materialblock/anti-aliasing:specularantialiasing/def-value"> </a>Value⟨L:2000⟩</dt><dd><p> ⟨L:2001⟩<code>true</code> or <code>false</code>. Defaults to <code>false</code>.
|
||
</p></dd><dt><a class="target" name="materialdefinitions/materialblock/anti-aliasing:specularantialiasing/def-description"> </a>Description⟨L:2003⟩</dt><dd><p> ⟨L:2004⟩Reduces specular aliasing and preserves the shape of specular highlights as an object moves
|
||
away ⟨L:2005⟩from the camera. This anti-aliasing solution is particularly effective on glossy materials
|
||
(low ⟨L:2006⟩roughness) but increases the cost of the material. The strength of the anti-aliasing
|
||
effect ⟨L:2007⟩can be controlled using two other properties: <code>specularAntiAliasingVariance</code> and
|
||
<code>specularAntiAliasingThreshold</code>.⟨L:2008⟩
|
||
</p></dd></dl></p><pre class="listing tilde"><code><span class="line"></span>material <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> specularAntiAliasing <span class="hljs-punctuation">:</span> <span class="hljs-literal"><span class="hljs-keyword">true</span></span>
|
||
<span class="line"></span><span class="hljs-punctuation">}</span></code></pre>
|
||
</section><section class="h3-section"><a class="target" name="anti-aliasing:specularantialiasingvariance"> </a><a class="target" name="materialdefinitions/materialblock/anti-aliasing:specularantialiasingvariance"> </a><a class="target" name="toc4.2.38"> </a><h3 id="l2016anti-aliasing-specularantialiasingvariance"><a class="header" href="#l2016anti-aliasing-specularantialiasingvariance">⟨L:2016⟩Anti-aliasing: specularAntiAliasingVariance</a></h3>
|
||
<p>
|
||
<dl><dt><a class="target" name="materialdefinitions/materialblock/anti-aliasing:specularantialiasingvariance/def-type"> </a>Type⟨L:2018⟩</dt><dd><p> ⟨L:2019⟩<code>float</code>
|
||
</p></dd><dt><a class="target" name="materialdefinitions/materialblock/anti-aliasing:specularantialiasingvariance/def-value"> </a>Value⟨L:2021⟩</dt><dd><p> ⟨L:2022⟩A value between 0 and 1, set to 0.15 by default.
|
||
</p></dd><dt><a class="target" name="materialdefinitions/materialblock/anti-aliasing:specularantialiasingvariance/def-description"> </a>Description⟨L:2024⟩</dt><dd><p> ⟨L:2025⟩Sets the screen space variance of the filter kernel used when applying specular anti-aliasing.
|
||
Higher ⟨L:2026⟩values will increase the effect of the filter but may increase roughness in unwanted
|
||
areas.⟨L:2027⟩
|
||
</p></dd></dl></p><pre class="listing tilde"><code><span class="line"></span>material <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> specularAntiAliasingVariance <span class="hljs-punctuation">:</span> <span class="hljs-number">0.2</span>
|
||
<span class="line"></span><span class="hljs-punctuation">}</span></code></pre>
|
||
</section><section class="h3-section"><a class="target" name="anti-aliasing:specularantialiasingthreshold"> </a><a class="target" name="materialdefinitions/materialblock/anti-aliasing:specularantialiasingthreshold"> </a><a class="target" name="toc4.2.39"> </a><h3 id="l2035anti-aliasing-specularantialiasingthreshold"><a class="header" href="#l2035anti-aliasing-specularantialiasingthreshold">⟨L:2035⟩Anti-aliasing: specularAntiAliasingThreshold</a></h3>
|
||
<p>
|
||
<dl><dt><a class="target" name="materialdefinitions/materialblock/anti-aliasing:specularantialiasingthreshold/def-type"> </a>Type⟨L:2037⟩</dt><dd><p> ⟨L:2038⟩<code>float</code>
|
||
</p></dd><dt><a class="target" name="materialdefinitions/materialblock/anti-aliasing:specularantialiasingthreshold/def-value"> </a>Value⟨L:2040⟩</dt><dd><p> ⟨L:2041⟩A value between 0 and 1, set to 0.2 by default.
|
||
</p></dd><dt><a class="target" name="materialdefinitions/materialblock/anti-aliasing:specularantialiasingthreshold/def-description"> </a>Description⟨L:2043⟩</dt><dd><p> ⟨L:2044⟩Sets the clamping threshold used to suppress estimation errors when applying specular
|
||
anti-aliasing. ⟨L:2045⟩When set to 0, specular anti-aliasing is disabled.
|
||
</p></dd></dl></p><pre class="listing tilde"><code><span class="line"></span>material <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> specularAntiAliasingThreshold <span class="hljs-punctuation">:</span> <span class="hljs-number">0.1</span>
|
||
<span class="line"></span><span class="hljs-punctuation">}</span></code></pre>
|
||
</section><section class="h3-section"><a class="target" name="shading:customsurfaceshading"> </a><a class="target" name="materialdefinitions/materialblock/shading:customsurfaceshading"> </a><a class="target" name="toc4.2.40"> </a><h3 id="l2053shading-customsurfaceshading"><a class="header" href="#l2053shading-customsurfaceshading">⟨L:2053⟩Shading: customSurfaceShading</a></h3>
|
||
<p>
|
||
<dl><dt><a class="target" name="materialdefinitions/materialblock/shading:customsurfaceshading/def-type"> </a>Type⟨L:2055⟩</dt><dd><p> ⟨L:2056⟩<code>bool</code>
|
||
</p></dd><dt><a class="target" name="materialdefinitions/materialblock/shading:customsurfaceshading/def-value"> </a>Value⟨L:2058⟩</dt><dd><p> ⟨L:2059⟩<code>true</code> or <code>false</code>. Defaults to <code>false</code>.
|
||
</p></dd><dt><a class="target" name="materialdefinitions/materialblock/shading:customsurfaceshading/def-description"> </a>Description⟨L:2061⟩</dt><dd><p> ⟨L:2062⟩Enables custom surface shading when set to true. When surface shading is enabled, the fragment
|
||
shader ⟨L:2063⟩must provide an extra function that will be invoked for every light in the scene that
|
||
may ⟨L:2064⟩influence the current fragment. Please refer to the Custom surface shading section below
|
||
for ⟨L:2065⟩more information.
|
||
</p></dd></dl></p><pre class="listing tilde"><code><span class="line"></span>material <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> customSurfaceShading <span class="hljs-punctuation">:</span> <span class="hljs-literal"><span class="hljs-keyword">true</span></span>
|
||
<span class="line"></span><span class="hljs-punctuation">}</span></code></pre>
|
||
</section></section><section class="h2-section"><a class="target" name="vertexblock"> </a><a class="target" name="materialdefinitions/vertexblock"> </a><a class="target" name="toc4.3"> </a><h2 id="l2073vertex-block"><a class="header" href="#l2073vertex-block">⟨L:2073⟩Vertex block</a></h2>
|
||
<p>
|
||
<p>The ⟨L:2075⟩vertex block is optional and can be used to control the vertex shading stage of the material.
|
||
The ⟨L:2076⟩vertex block must contain valid
|
||
<a href="https://www.khronos.org/registry/OpenGL/specs/es/3.0/GLSL_ES_Specification_3.00.pdf">ESSL ⟨L:2077⟩3.0</a> code
|
||
(the ⟨L:2078⟩version of GLSL supported in OpenGL ES 3.0). You are free to create multiple functions inside
|
||
the ⟨L:2079⟩vertex block but you <strong class="asterisk">must</strong> declare the <code>materialVertex</code> function:</p>
|
||
</p><pre class="listing tilde"><code><span class="line"></span>vertex {
|
||
<span class="line"></span> <span class="hljs-type">void</span> materialVertex(<span class="hljs-keyword">inout</span> MaterialVertexInputs material) {
|
||
<span class="line"></span> <span class="hljs-comment">// vertex shading code</span>
|
||
<span class="line"></span> }
|
||
<span class="line"></span>}</code></pre><p>
|
||
This ⟨L:2089⟩function will be invoked automatically at runtime by the shading system and gives you the
|
||
ability ⟨L:2090⟩to read and modify material properties using the <code>MaterialVertexInputs</code> structure. This full
|
||
definition ⟨L:2091⟩of the structure can be found in the Material vertex inputs section.
|
||
</p><p>
|
||
You ⟨L:2093⟩can use this structure to compute your custom variables/interpolants or to modify the value of
|
||
the ⟨L:2094⟩attributes. For instance, the following vertex blocks modifies both the color and the UV
|
||
coordinates ⟨L:2095⟩of the vertex over time:
|
||
</p><pre class="listing tilde"><code><span class="line"></span>material {
|
||
<span class="line"></span> requires : [uv0, color]
|
||
<span class="line"></span>}
|
||
<span class="line"></span>vertex {
|
||
<span class="line"></span> <span class="hljs-type">void</span> materialVertex(<span class="hljs-keyword">inout</span> MaterialVertexInputs material) {
|
||
<span class="line"></span> material.color *= <span class="hljs-built_in">sin</span>(getUserTime().x);
|
||
<span class="line"></span> material.uv0 *= <span class="hljs-built_in">sin</span>(getUserTime().x);
|
||
<span class="line"></span> }
|
||
<span class="line"></span>}</code></pre><p>
|
||
In ⟨L:2109⟩addition to the <code>MaterialVertexInputs</code> structure, your vertex shading code can use all the public
|
||
APIs ⟨L:2110⟩listed in the Shader public APIs section.
|
||
</p>
|
||
<section class="h3-section"><a class="target" name="materialvertexinputs"> </a><a class="target" name="materialdefinitions/vertexblock/materialvertexinputs"> </a><a class="target" name="toc4.3.1"> </a><h3 id="l2112material-vertex-inputs"><a class="header" href="#l2112material-vertex-inputs">⟨L:2112⟩Material vertex inputs</a></h3>
|
||
<pre class="listing tilde"><code><span class="line"></span>struct MaterialVertexInputs {
|
||
<span class="line"></span> float4 color; <span class="hljs-comment">// if the color attribute is required</span>
|
||
<span class="line"></span> float2 uv0; <span class="hljs-comment">// if the uv0 attribute is required</span>
|
||
<span class="line"></span> float2 uv1; <span class="hljs-comment">// if the uv1 attribute is required</span>
|
||
<span class="line"></span> float3 worldNormal; <span class="hljs-comment">// only if the shading model is not unlit</span>
|
||
<span class="line"></span> float4 worldPosition; <span class="hljs-comment">// always available (see note below about world-space)</span>
|
||
<span class="line"></span>
|
||
<span class="line"></span> <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 class="line"></span>
|
||
<span class="line"></span> <span class="hljs-comment">// variable* names are replaced with actual names</span>
|
||
<span class="line"></span> float4 variable0; <span class="hljs-comment">// if 1 or more variables is defined</span>
|
||
<span class="line"></span> float4 variable1; <span class="hljs-comment">// if 2 or more variables is defined</span>
|
||
<span class="line"></span> float4 variable2; <span class="hljs-comment">// if 3 or more variables is defined</span>
|
||
<span class="line"></span> float4 variable3; <span class="hljs-comment">// if 4 or more variables is defined</span>
|
||
<span class="line"></span>};</code></pre><p>
|
||
<div class="admonition ⟨L:2132⟩tip"><div class="admonition-title"> worldPosition</div>
|
||
</p><p>
|
||
To ⟨L:2133⟩achieve good precision, the <code>worldPosition</code> coordinate in the vertex shader is shifted by the
|
||
camera ⟨L:2134⟩position. To get the true world-space position, users can use
|
||
<code>getUserWorldPosition()</code>, ⟨L:2135⟩however be aware that the true world-position might not
|
||
be ⟨L:2136⟩able to fit in a <code>float</code> or might be represented with severely reduced precision.</div>
|
||
</p><p>
|
||
<div class="admonition ⟨L:2138⟩tip"><div class="admonition-title"> UV attributes</div>
|
||
</p><p>
|
||
By ⟨L:2139⟩default the vertex shader of a material will flip the Y coordinate of the UV attributes
|
||
of ⟨L:2140⟩the current mesh: <code>material.uv0 = vec2(mesh_uv0.x, 1.0 - mesh_uv0.y)</code>. You can control
|
||
this ⟨L:2141⟩behavior using the <code>flipUV</code> property and setting it to <code>false</code>.</div>
|
||
</p>
|
||
</section><section class="h3-section"><a class="target" name="customvertexattributes"> </a><a class="target" name="materialdefinitions/vertexblock/customvertexattributes"> </a><a class="target" name="toc4.3.2"> </a><h3 id="l2143custom-vertex-attributes"><a class="header" href="#l2143custom-vertex-attributes">⟨L:2143⟩Custom vertex attributes</a></h3>
|
||
<p>
|
||
<p>You ⟨L:2145⟩can use up to 8 custom vertex attributes, all of type <code>float4</code>. These attributes can be accessed
|
||
using ⟨L:2146⟩the vertex block shader functions <code>getCustom0()</code> to <code>getCustom7()</code>. However, before using
|
||
custom ⟨L:2147⟩attributes, you <em class="asterisk">must</em> declare those attributes as required in the <code>requires</code> property of
|
||
the ⟨L:2148⟩material:</p>
|
||
</p><pre class="listing tilde"><code><span class="line"></span>material <span class="hljs-punctuation">{</span>
|
||
<span class="line"></span> requires <span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span>
|
||
<span class="line"></span> custom0<span class="hljs-punctuation">,</span>
|
||
<span class="line"></span> custom1<span class="hljs-punctuation">,</span>
|
||
<span class="line"></span> custom2
|
||
<span class="line"></span> <span class="hljs-punctuation">]</span>
|
||
<span class="line"></span><span class="hljs-punctuation">}</span></code></pre>
|
||
</section></section><section class="h2-section"><a class="target" name="fragmentblock"> </a><a class="target" name="materialdefinitions/fragmentblock"> </a><a class="target" name="toc4.4"> </a><h2 id="l2160fragment-block"><a class="header" href="#l2160fragment-block">⟨L:2160⟩Fragment block</a></h2>
|
||
<p>
|
||
<p>The ⟨L:2162⟩fragment block must be used to control the fragment shading stage of the material. The fragment
|
||
block ⟨L:2163⟩must contain valid
|
||
<a href="https://www.khronos.org/registry/OpenGL/specs/es/3.0/GLSL_ES_Specification_3.00.pdf">ESSL ⟨L:2164⟩3.0</a>
|
||
code ⟨L:2165⟩(the version of GLSL supported in OpenGL ES 3.0). You are free to create multiple functions
|
||
inside ⟨L:2166⟩the fragment block but you <strong class="asterisk">must</strong> declare the <code>material</code> function:</p>
|
||
</p><pre class="listing tilde"><code><span class="line"></span>fragment {
|
||
<span class="line"></span> <span class="hljs-type">void</span> material(<span class="hljs-keyword">inout</span> MaterialInputs material) {
|
||
<span class="line"></span> prepareMaterial(material);
|
||
<span class="line"></span> <span class="hljs-comment">// fragment shading code</span>
|
||
<span class="line"></span> }
|
||
<span class="line"></span>}</code></pre><p>
|
||
This ⟨L:2177⟩function will be invoked automatically at runtime by the shading system and gives you the
|
||
ability ⟨L:2178⟩to read and modify material properties using the <code>MaterialInputs</code> structure. This full
|
||
definition ⟨L:2179⟩of the structure can be found in the Material fragment inputs section. The full
|
||
definition ⟨L:2180⟩of the various members of the structure can be found in the Material models section
|
||
of ⟨L:2181⟩this document.
|
||
</p><p>
|
||
The ⟨L:2183⟩goal of the <code>material()</code> function is to compute the material properties specific to the selected
|
||
shading ⟨L:2184⟩model. For instance, here is a fragment block that creates a glossy red metal using the
|
||
standard ⟨L:2185⟩lit shading model:
|
||
</p><pre class="listing tilde"><code><span class="line"></span>fragment {
|
||
<span class="line"></span> <span class="hljs-type">void</span> material(<span class="hljs-keyword">inout</span> MaterialInputs material) {
|
||
<span class="line"></span> prepareMaterial(material);
|
||
<span class="line"></span> 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 class="line"></span> material.metallic = <span class="hljs-number">1.0</span>;
|
||
<span class="line"></span> material.roughness = <span class="hljs-number">0.0</span>;
|
||
<span class="line"></span> }
|
||
<span class="line"></span>}</code></pre>
|
||
<section class="h3-section"><a class="target" name="preparematerialfunction"> </a><a class="target" name="materialdefinitions/fragmentblock/preparematerialfunction"> </a><a class="target" name="toc4.4.1"> </a><h3 id="l2198preparematerial-function"><a class="header" href="#l2198preparematerial-function">⟨L:2198⟩prepareMaterial function</a></h3>
|
||
<p>
|
||
<p>Note ⟨L:2200⟩that you <strong class="asterisk">must</strong> call <code>prepareMaterial(material)</code> before exiting the <code>material()</code> function.
|
||
This ⟨L:2201⟩<code>prepareMaterial</code> function sets up the internal state of the material model. Some of the APIs
|
||
described ⟨L:2202⟩in the Fragment APIs section - like <code>shading_normal</code> for instance - can only be accessed
|
||
<em class="underscore">after</em> ⟨L:2203⟩invoking <code>prepareMaterial()</code>.</p>
|
||
</p><p>
|
||
It ⟨L:2205⟩is also important to remember that the <code>normal</code> property - as described in the Material fragment
|
||
inputs ⟨L:2206⟩section - only has an effect when modified <em class="underscore">before</em> calling <code>prepareMaterial()</code>. Here is an
|
||
example ⟨L:2207⟩of a fragment shader that properly modifies the <code>normal</code> property to implement a glossy red
|
||
plastic ⟨L:2208⟩with bump mapping:
|
||
</p><pre class="listing tilde"><code><span class="line"></span>fragment {
|
||
<span class="line"></span> <span class="hljs-type">void</span> material(<span class="hljs-keyword">inout</span> MaterialInputs material) {
|
||
<span class="line"></span> <span class="hljs-comment">// fetch the normal in tangent space</span>
|
||
<span class="line"></span> <span class="hljs-type">vec3</span> normal = <span class="hljs-built_in">texture</span>(materialParams_normalMap, getUV0()).xyz;
|
||
<span class="line"></span> material.normal = normal * <span class="hljs-number">2.0</span> - <span class="hljs-number">1.0</span>;
|
||
<span class="line"></span>
|
||
<span class="line"></span> <span class="hljs-comment">// prepare the material</span>
|
||
<span class="line"></span> prepareMaterial(material);
|
||
<span class="line"></span>
|
||
<span class="line"></span> <span class="hljs-comment">// from now on, shading_normal, etc. can be accessed</span>
|
||
<span class="line"></span> 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 class="line"></span> material.metallic = <span class="hljs-number">0.0</span>;
|
||
<span class="line"></span> material.roughness = <span class="hljs-number">1.0</span>;
|
||
<span class="line"></span> }
|
||
<span class="line"></span>}</code></pre>
|
||
</section><section class="h3-section"><a class="target" name="materialfragmentinputs"> </a><a class="target" name="materialdefinitions/fragmentblock/materialfragmentinputs"> </a><a class="target" name="toc4.4.2"> </a><h3 id="l2228material-fragment-inputs"><a class="header" href="#l2228material-fragment-inputs">⟨L:2228⟩Material fragment inputs</a></h3>
|
||
<pre class="listing tilde"><code><span class="line"></span>struct MaterialInputs {
|
||
<span class="line"></span> float4 baseColor; <span class="hljs-comment">// default: float4(1.0)</span>
|
||
<span class="line"></span> float4 emissive; <span class="hljs-comment">// default: float4(0.0, 0.0, 0.0, 1.0)</span>
|
||
<span class="line"></span> float4 postLightingColor; <span class="hljs-comment">// default: float4(0.0)</span>
|
||
<span class="line"></span>
|
||
<span class="line"></span> <span class="hljs-comment">// no other field is available with the unlit shading model</span>
|
||
<span class="line"></span> <span class="hljs-type">float</span> roughness; <span class="hljs-comment">// default: 1.0</span>
|
||
<span class="line"></span> <span class="hljs-type">float</span> metallic; <span class="hljs-comment">// default: 0.0, not available with cloth or specularGlossiness</span>
|
||
<span class="line"></span> <span class="hljs-type">float</span> reflectance; <span class="hljs-comment">// default: 0.5, not available with cloth or specularGlossiness</span>
|
||
<span class="line"></span> <span class="hljs-type">float</span> ambientOcclusion; <span class="hljs-comment">// default: 0.0</span>
|
||
<span class="line"></span>
|
||
<span class="line"></span> <span class="hljs-comment">// not available when the shading model is subsurface or cloth</span>
|
||
<span class="line"></span> float3 sheenColor; <span class="hljs-comment">// default: float3(0.0)</span>
|
||
<span class="line"></span> <span class="hljs-type">float</span> sheenRoughness; <span class="hljs-comment">// default: 0.0</span>
|
||
<span class="line"></span> <span class="hljs-type">float</span> clearCoat; <span class="hljs-comment">// default: 1.0</span>
|
||
<span class="line"></span> <span class="hljs-type">float</span> clearCoatRoughness; <span class="hljs-comment">// default: 0.0</span>
|
||
<span class="line"></span> float3 clearCoatNormal; <span class="hljs-comment">// default: float3(0.0, 0.0, 1.0)</span>
|
||
<span class="line"></span> <span class="hljs-type">float</span> anisotropy; <span class="hljs-comment">// default: 0.0</span>
|
||
<span class="line"></span> float3 anisotropyDirection; <span class="hljs-comment">// default: float3(1.0, 0.0, 0.0)</span>
|
||
<span class="line"></span>
|
||
<span class="line"></span> <span class="hljs-comment">// only available when the shading model is subsurface or refraction is enabled</span>
|
||
<span class="line"></span> <span class="hljs-type">float</span> thickness; <span class="hljs-comment">// default: 0.5</span>
|
||
<span class="line"></span>
|
||
<span class="line"></span> <span class="hljs-comment">// only available when the shading model is subsurface</span>
|
||
<span class="line"></span> <span class="hljs-type">float</span> subsurfacePower; <span class="hljs-comment">// default: 12.234</span>
|
||
<span class="line"></span> float3 subsurfaceColor; <span class="hljs-comment">// default: float3(1.0)</span>
|
||
<span class="line"></span>
|
||
<span class="line"></span> <span class="hljs-comment">// only available when the shading model is cloth</span>
|
||
<span class="line"></span> float3 sheenColor; <span class="hljs-comment">// default: sqrt(baseColor)</span>
|
||
<span class="line"></span> float3 subsurfaceColor; <span class="hljs-comment">// default: float3(0.0)</span>
|
||
<span class="line"></span>
|
||
<span class="line"></span> <span class="hljs-comment">// only available when the shading model is specularGlossiness</span>
|
||
<span class="line"></span> float3 specularColor; <span class="hljs-comment">// default: float3(0.0)</span>
|
||
<span class="line"></span> <span class="hljs-type">float</span> glossiness; <span class="hljs-comment">// default: 0.0</span>
|
||
<span class="line"></span>
|
||
<span class="line"></span> <span class="hljs-comment">// not available when the shading model is unlit</span>
|
||
<span class="line"></span> <span class="hljs-comment">// must be set before calling prepareMaterial()</span>
|
||
<span class="line"></span> float3 normal; <span class="hljs-comment">// default: float3(0.0, 0.0, 1.0)</span>
|
||
<span class="line"></span>
|
||
<span class="line"></span> <span class="hljs-comment">// only available when refraction is enabled</span>
|
||
<span class="line"></span> <span class="hljs-type">float</span> transmission; <span class="hljs-comment">// default: 1.0</span>
|
||
<span class="line"></span> float3 absorption; <span class="hljs-comment">// default float3(0.0, 0.0, 0.0)</span>
|
||
<span class="line"></span> <span class="hljs-type">float</span> ior; <span class="hljs-comment">// default: 1.5</span>
|
||
<span class="line"></span> <span class="hljs-type">float</span> microThickness; <span class="hljs-comment">// default: 0.0, not available with refractionType "solid"</span>
|
||
<span class="line"></span>}</code></pre>
|
||
</section><section class="h3-section"><a class="target" name="customsurfaceshading"> </a><a class="target" name="materialdefinitions/fragmentblock/customsurfaceshading"> </a><a class="target" name="toc4.4.3"> </a><h3 id="l2278custom-surface-shading"><a class="header" href="#l2278custom-surface-shading">⟨L:2278⟩Custom surface shading</a></h3>
|
||
<p>
|
||
<p>When ⟨L:2280⟩<code>customSurfaceShading</code> is set to <code>true</code> in the material block, the fragment block <strong class="asterisk">must</strong>
|
||
declare ⟨L:2281⟩and implement the <code>surfaceShading</code> function:</p>
|
||
</p><pre class="listing tilde"><code><span class="line"></span>fragment {
|
||
<span class="line"></span> <span class="hljs-type">void</span> material(<span class="hljs-keyword">inout</span> MaterialInputs material) {
|
||
<span class="line"></span> prepareMaterial(material);
|
||
<span class="line"></span> <span class="hljs-comment">// prepare material inputs</span>
|
||
<span class="line"></span> }
|
||
<span class="line"></span>
|
||
<span class="line"></span> <span class="hljs-type">vec3</span> surfaceShading(
|
||
<span class="line"></span> <span class="hljs-keyword">const</span> MaterialInputs materialInputs,
|
||
<span class="line"></span> <span class="hljs-keyword">const</span> ShadingData shadingData,
|
||
<span class="line"></span> <span class="hljs-keyword">const</span> LightData lightData
|
||
<span class="line"></span> ) {
|
||
<span class="line"></span> <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 class="line"></span> }
|
||
<span class="line"></span>}</code></pre><p>
|
||
This ⟨L:2300⟩function will be invoked for every light (directional, spot or point) in the scene that may
|
||
influence ⟨L:2301⟩the current fragment. The <code>surfaceShading</code> is invoked with 3 sets of data:
|
||
</p><p>
|
||
<ul>
|
||
<li class="minus"><code>MaterialInputs</code>, as described in the Material fragment inputs section and prepared in the
|
||
<code>material</code> ⟨L:2304⟩function explained above</li></ul>
|
||
</p><p>
|
||
<ul>
|
||
<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 ⟨L:2307⟩(see below)</li></ul>
|
||
</p><p>
|
||
The ⟨L:2309⟩<code>surfaceShading</code> function must return an RGB color in linear sRGB. Alpha blending and alpha
|
||
masking ⟨L:2310⟩are handled outside of this function and must therefore be ignored.
|
||
</p><p>
|
||
<div class="admonition ⟨L:2312⟩note"><div class="admonition-title"> About shadowed fragments</div>
|
||
</p><p>
|
||
The ⟨L:2313⟩<code>surfaceShading</code> function is invoked even when a fragment is known to be fully in the shadow
|
||
of ⟨L:2314⟩the current light (<code>lightData.NdotL <= 0.0</code> or <code>lightData.visibility <= 0.0</code>). This gives
|
||
more ⟨L:2315⟩flexibility to the <code>surfaceShading</code> function as it provides a simple way to handle constant
|
||
ambient ⟨L:2316⟩lighting for instance.</div>
|
||
</p><p>
|
||
<div class="admonition ⟨L:2318⟩warning"><div class="admonition-title"> Shading models</div>
|
||
</p><p>
|
||
Custom ⟨L:2319⟩surface shading only works with the <code>lit</code> shading model. Attempting to use any other
|
||
model ⟨L:2320⟩will result in an error.</div>
|
||
</p>
|
||
<section class="h4-section"><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 id="l2322shading-data-structure"><a class="header" href="#l2322shading-data-structure">⟨L:2322⟩Shading data structure</a></h4>
|
||
<pre class="listing tilde"><code><span class="line"></span>struct ShadingData {
|
||
<span class="line"></span> <span class="hljs-comment">// The material's diffuse color, as derived from baseColor and metallic.</span>
|
||
<span class="line"></span> <span class="hljs-comment">// This color is pre-multiplied by alpha and in the linear sRGB color space.</span>
|
||
<span class="line"></span> <span class="hljs-type">vec3</span> diffuseColor;
|
||
<span class="line"></span>
|
||
<span class="line"></span> <span class="hljs-comment">// The material's specular color, as derived from baseColor and metallic.</span>
|
||
<span class="line"></span> <span class="hljs-comment">// This color is pre-multiplied by alpha and in the linear sRGB color space.</span>
|
||
<span class="line"></span> <span class="hljs-type">vec3</span> f0;
|
||
<span class="line"></span>
|
||
<span class="line"></span> <span class="hljs-comment">// The perceptual roughness is the roughness value set in MaterialInputs,</span>
|
||
<span class="line"></span> <span class="hljs-comment">// with extra processing:</span>
|
||
<span class="line"></span> <span class="hljs-comment">// - Clamped to safe values</span>
|
||
<span class="line"></span> <span class="hljs-comment">// - Filtered if specularAntiAliasing is enabled</span>
|
||
<span class="line"></span> <span class="hljs-comment">// This value is between 0.0 and 1.0.</span>
|
||
<span class="line"></span> <span class="hljs-type">float</span> perceptualRoughness;
|
||
<span class="line"></span>
|
||
<span class="line"></span> <span class="hljs-comment">// The roughness value expected by BRDFs. This value is the square of</span>
|
||
<span class="line"></span> <span class="hljs-comment">// perceptualRoughness. This value is between 0.0 and 1.0.</span>
|
||
<span class="line"></span> <span class="hljs-type">float</span> roughness;
|
||
<span class="line"></span>};</code></pre>
|
||
</section><section class="h4-section"><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 id="l2347light-data-structure"><a class="header" href="#l2347light-data-structure">⟨L:2347⟩Light data structure</a></h4>
|
||
<pre class="listing tilde"><code><span class="line"></span>struct LightData {
|
||
<span class="line"></span> <span class="hljs-comment">// The color (.rgb) and pre-exposed intensity (.w) of the light.</span>
|
||
<span class="line"></span> <span class="hljs-comment">// The color is an RGB value in the linear sRGB color space.</span>
|
||
<span class="line"></span> <span class="hljs-comment">// The pre-exposed intensity is the intensity of the light multiplied by</span>
|
||
<span class="line"></span> <span class="hljs-comment">// the camera's exposure value.</span>
|
||
<span class="line"></span> <span class="hljs-type">vec4</span> colorIntensity;
|
||
<span class="line"></span>
|
||
<span class="line"></span> <span class="hljs-comment">// The normalized light vector, in world space (direction from the</span>
|
||
<span class="line"></span> <span class="hljs-comment">// current fragment's position to the light).</span>
|
||
<span class="line"></span> <span class="hljs-type">vec3</span> l;
|
||
<span class="line"></span>
|
||
<span class="line"></span> <span class="hljs-comment">// The dot product of the shading normal (with normal mapping applied)</span>
|
||
<span class="line"></span> <span class="hljs-comment">// and the light vector. This value is equal to the result of</span>
|
||
<span class="line"></span> <span class="hljs-comment">// saturate(dot(getWorldSpaceNormal(), lightData.l)).</span>
|
||
<span class="line"></span> <span class="hljs-comment">// This value is always between 0.0 and 1.0. When the value is <= 0.0,</span>
|
||
<span class="line"></span> <span class="hljs-comment">// the current fragment is not visible from the light and lighting</span>
|
||
<span class="line"></span> <span class="hljs-comment">// computations can be skipped.</span>
|
||
<span class="line"></span> <span class="hljs-type">float</span> NdotL;
|
||
<span class="line"></span>
|
||
<span class="line"></span> <span class="hljs-comment">// The position of the light in world space.</span>
|
||
<span class="line"></span> <span class="hljs-type">vec3</span> worldPosition;
|
||
<span class="line"></span>
|
||
<span class="line"></span> <span class="hljs-comment">// Attenuation of the light based on the distance from the current</span>
|
||
<span class="line"></span> <span class="hljs-comment">// fragment to the light in world space. This value between 0.0 and 1.0</span>
|
||
<span class="line"></span> <span class="hljs-comment">// is computed differently for each type of light (it's always 1.0 for</span>
|
||
<span class="line"></span> <span class="hljs-comment">// directional lights).</span>
|
||
<span class="line"></span> <span class="hljs-type">float</span> attenuation;
|
||
<span class="line"></span>
|
||
<span class="line"></span> <span class="hljs-comment">// Visibility factor computed from shadow maps or other occlusion data</span>
|
||
<span class="line"></span> <span class="hljs-comment">// specific to the light being evaluated. This value is between 0.0 and</span>
|
||
<span class="line"></span> <span class="hljs-comment">// 1.0.</span>
|
||
<span class="line"></span> <span class="hljs-type">float</span> visibility;
|
||
<span class="line"></span>};</code></pre>
|
||
</section><section class="h4-section"><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 id="l2385example"><a class="header" href="#l2385example">⟨L:2385⟩Example</a></h4>
|
||
<p>
|
||
<p>The ⟨L:2387⟩material below shows how to use custom surface shading to implement a simplified toon shader:</p>
|
||
</p><pre class="listing tilde"><code><span class="line"></span>material {
|
||
<span class="line"></span> name : Toon,
|
||
<span class="line"></span> shadingModel : lit,
|
||
<span class="line"></span> parameters : [
|
||
<span class="line"></span> {
|
||
<span class="line"></span> type : float3,
|
||
<span class="line"></span> name : baseColor
|
||
<span class="line"></span> }
|
||
<span class="line"></span> ],
|
||
<span class="line"></span> customSurfaceShading : <span class="hljs-literal">true</span>
|
||
<span class="line"></span>}
|
||
<span class="line"></span>
|
||
<span class="line"></span>fragment {
|
||
<span class="line"></span> <span class="hljs-type">void</span> material(<span class="hljs-keyword">inout</span> MaterialInputs material) {
|
||
<span class="line"></span> prepareMaterial(material);
|
||
<span class="line"></span> material.baseColor.rgb = materialParams.baseColor;
|
||
<span class="line"></span> }
|
||
<span class="line"></span>
|
||
<span class="line"></span> <span class="hljs-type">vec3</span> surfaceShading(
|
||
<span class="line"></span> <span class="hljs-keyword">const</span> MaterialInputs materialInputs,
|
||
<span class="line"></span> <span class="hljs-keyword">const</span> ShadingData shadingData,
|
||
<span class="line"></span> <span class="hljs-keyword">const</span> LightData lightData
|
||
<span class="line"></span> ) {
|
||
<span class="line"></span> <span class="hljs-comment">// Number of visible shade transitions</span>
|
||
<span class="line"></span> <span class="hljs-keyword">const</span> <span class="hljs-type">float</span> shades = <span class="hljs-number">5.0</span>;
|
||
<span class="line"></span> <span class="hljs-comment">// Ambient intensity</span>
|
||
<span class="line"></span> <span class="hljs-keyword">const</span> <span class="hljs-type">float</span> ambient = <span class="hljs-number">0.1</span>;
|
||
<span class="line"></span>
|
||
<span class="line"></span> <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 class="line"></span>
|
||
<span class="line"></span> <span class="hljs-comment">// Shadowing and attenuation</span>
|
||
<span class="line"></span> toon *= lightData.visibility * lightData.attenuation;
|
||
<span class="line"></span>
|
||
<span class="line"></span> <span class="hljs-comment">// Color and intensity</span>
|
||
<span class="line"></span> <span class="hljs-type">vec3</span> light = lightData.colorIntensity.rgb * lightData.colorIntensity.w;
|
||
<span class="line"></span>
|
||
<span class="line"></span> <span class="hljs-keyword">return</span> shadingData.diffuseColor * light * toon;
|
||
<span class="line"></span> }
|
||
<span class="line"></span>}</code></pre><p>
|
||
The ⟨L:2431⟩result can be seen in figure ?.
|
||
</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">Figure ⟨L:2433⟩[toonShading]: simple toon shading implemented with custom
|
||
surface ⟨L:2434⟩shading</span></center></div></center>
|
||
</p>
|
||
</section></section></section><section class="h2-section"><a class="target" name="shaderpublicapis"> </a><a class="target" name="materialdefinitions/shaderpublicapis"> </a><a class="target" name="toc4.5"> </a><h2 id="l2437shader-public-apis"><a class="header" href="#l2437shader-public-apis">⟨L:2437⟩Shader public APIs</a></h2>
|
||
<section class="h3-section"><a class="target" name="types"> </a><a class="target" name="materialdefinitions/shaderpublicapis/types"> </a><a class="target" name="toc4.5.1"> </a><h3 id="l2439types"><a class="header" href="#l2439types">⟨L:2439⟩Types</a></h3>
|
||
<p>
|
||
<p>While ⟨L:2441⟩GLSL types can be used directly (<code>vec4</code> or <code>mat4</code>) we recommend the use of the following
|
||
type ⟨L:2442⟩aliases:</p>
|
||
<div class='table'><table class="table longtable"><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>
|
||
</table></div>
|
||
</p>
|
||
</section><section class="h3-section"><a class="target" name="math"> </a><a class="target" name="materialdefinitions/shaderpublicapis/math"> </a><a class="target" name="toc4.5.2"> </a><h3 id="l2461math"><a class="header" href="#l2461math">⟨L:2461⟩Math</a></h3>
|
||
<p>
|
||
<div class='table'><table class="table"><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>
|
||
</table></div>
|
||
</p>
|
||
</section><section class="h3-section"><a class="target" name="matrices"> </a><a class="target" name="materialdefinitions/shaderpublicapis/matrices"> </a><a class="target" name="toc4.5.3"> </a><h3 id="l2473matrices"><a class="header" href="#l2473matrices">⟨L:2473⟩Matrices</a></h3>
|
||
<p>
|
||
<div class='table'><table class="table"><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">getEyeFromViewMatrix()</strong> </td><td style="text-align:center"> float4×4 </td><td style="text-align:left"> Matrix that converts from view space to eye space </td></tr>
|
||
<tr><td style="text-align:left"> <strong class="asterisk">getEyeFromViewMatrix(int eyeIndex)</strong> </td><td style="text-align:center"> float4×4 </td><td style="text-align:left"> Matrix that converts from view space to eye space for the eye referred to by eyeIndex </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">getClipFromWorldMatrix(int eyeIndex)</strong> </td><td style="text-align:center"> float4×4 </td><td style="text-align:left"> Matrix that converts from world to clip (NDC) space for the eye referred to by eyeIndex </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>
|
||
</table></div>
|
||
</p>
|
||
</section><section class="h3-section"><a class="target" name="frameconstants"> </a><a class="target" name="materialdefinitions/shaderpublicapis/frameconstants"> </a><a class="target" name="toc4.5.4"> </a><h3 id="l2487frame-constants"><a class="header" href="#l2487frame-constants">⟨L:2487⟩Frame constants</a></h3>
|
||
<p>
|
||
<div class='table'><table class="table"><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>
|
||
</table></div>
|
||
</p><p>
|
||
<div class="admonition ⟨L:2501⟩tip"><div class="admonition-title"> world space</div>
|
||
</p><p>
|
||
To ⟨L:2502⟩achieve good precision, the “world space” in Filament's shading system does not necessarily
|
||
match ⟨L:2503⟩the API-level world space. To obtain the position of the API-level camera, custom
|
||
materials ⟨L:2504⟩can use <code>getUserWorldFromWorldMatrix()</code> to transform <code>getWorldCameraPosition()</code>.</div>
|
||
</p>
|
||
</section><section class="h3-section"><a class="target" name="materialglobals"> </a><a class="target" name="materialdefinitions/shaderpublicapis/materialglobals"> </a><a class="target" name="toc4.5.5"> </a><h3 id="l2506material-globals"><a class="header" href="#l2506material-globals">⟨L:2506⟩Material globals</a></h3>
|
||
<p>
|
||
<div class='table'><table class="table"><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>
|
||
</table></div>
|
||
</p>
|
||
</section><section class="h3-section"><a class="target" name="vertexonly"> </a><a class="target" name="materialdefinitions/shaderpublicapis/vertexonly"> </a><a class="target" name="toc4.5.6"> </a><h3 id="l2515vertex-only"><a class="header" href="#l2515vertex-only">⟨L:2515⟩Vertex only</a></h3>
|
||
<p>
|
||
<p>The ⟨L:2517⟩following APIs are only available from the vertex block:</p>
|
||
<div class='table'><table class="table"><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>
|
||
</table></div>
|
||
</p>
|
||
</section><section class="h3-section"><a class="target" name="fragmentonly"> </a><a class="target" name="materialdefinitions/shaderpublicapis/fragmentonly"> </a><a class="target" name="toc4.5.7"> </a><h3 id="l2528fragment-only"><a class="header" href="#l2528fragment-only">⟨L:2528⟩Fragment only</a></h3>
|
||
<p>
|
||
<p>The ⟨L:2530⟩following APIs are only available from the fragment block:</p>
|
||
<div class='table'><table class="table longtable"><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>
|
||
</table></div>
|
||
</p><p>
|
||
<div class="admonition ⟨L:2553⟩tip"><div class="admonition-title"> world-space</div>
|
||
</p><p>
|
||
To ⟨L:2554⟩obtain API-level world-space coordinates, custom materials should use <code>getUserWorldPosition()</code>
|
||
or ⟨L:2555⟩use <code>getUserWorldFromWorldMatrix()</code>. Note that API-level world-space coordinates should
|
||
never ⟨L:2556⟩or rarely be used because they may not fit in a float3 or have severely reduced precision.</div>
|
||
</p><p>
|
||
<div class="admonition ⟨L:2558⟩tip"><div class="admonition-title"> sampling from render targets</div>
|
||
</p><p>
|
||
When ⟨L:2559⟩sampling from a <code>filament::Texture</code> that is attached to a <code>filament::RenderTarget</code> for
|
||
materials ⟨L:2560⟩in the surface domain, please use <code>uvToRenderTargetUV</code> to transform the texture
|
||
coordinate. ⟨L:2561⟩This will flip the coordinate depending on which backend is being used.</div>
|
||
</p>
|
||
</section></section></section><section class="h1-section"><a class="target" name="compilingmaterials"> </a><a class="target" name="compilingmaterials"> </a><a class="target" name="toc5"> </a><h1 id="l2563compiling-materials"><a class="header" href="#l2563compiling-materials">⟨L:2563⟩Compiling materials</a></h1>
|
||
<p>
|
||
<p>Material ⟨L:2565⟩packages can be compiled from material definitions using the command line tool called
|
||
<code>matc</code>. ⟨L:2566⟩The simplest way to use <code>matc</code> is to specify an input material definition (<code>car_paint.mat</code>
|
||
in ⟨L:2567⟩the example below) and an output material package (<code>car_paint.filamat</code> in the example below):</p>
|
||
</p><pre class="listing backtick"><code><span class="line"></span>$ matc -o ./materials/bin/car_paint.filamat ./materials/src/car_paint.mat</code></pre>
|
||
<section class="h2-section"><a class="target" name="shadervalidation"> </a><a class="target" name="compilingmaterials/shadervalidation"> </a><a class="target" name="toc5.1"> </a><h2 id="l2573shader-validation"><a class="header" href="#l2573shader-validation">⟨L:2573⟩Shader validation</a></h2>
|
||
<p>
|
||
<p><code>matc</code> ⟨L:2575⟩attempts to validate shaders when compiling a material package. The example below shows an
|
||
example ⟨L:2576⟩of an error message generated when compiling a material definition containing a typo in the
|
||
fragment ⟨L:2577⟩shader (<code>metalic</code> instead of <code>metallic</code>). The reported line numbers are line numbers in the
|
||
source ⟨L:2578⟩material definition file.</p>
|
||
</p><pre class="listing backtick"><code><span class="line"></span>ERROR: 0:13: 'metalic' : no such field in structure
|
||
<span class="line"></span>ERROR: 0:13: '' : compilation terminated
|
||
<span class="line"></span>ERROR: 2 compilation errors. No code generated.
|
||
<span class="line"></span>
|
||
<span class="line"></span>Could not compile material metal.mat</code></pre>
|
||
</section><section class="h2-section"><a class="target" name="flags"> </a><a class="target" name="compilingmaterials/flags"> </a><a class="target" name="toc5.2"> </a><h2 id="l2588flags"><a class="header" href="#l2588flags">⟨L:2588⟩Flags</a></h2>
|
||
<p>
|
||
<p>The ⟨L:2590⟩command line flags relevant to application development are described in <a href="#table_matcflags" target="_self">table 16</a>.</p>
|
||
<div class='table'>
|
||
<a class="target" name="table_matcflags"> </a><table class="table"><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>
|
||
</table><center><div class="tablecaption"><b style="font-style:normal;">Table 16:</b> List of <code>matc</code> flags</div></center></div>
|
||
</p><p>
|
||
<code>matc</code> ⟨L:2602⟩offers a few other flags that are irrelevant to application developers and for internal
|
||
use ⟨L:2603⟩only.
|
||
</p>
|
||
<section class="h3-section"><a class="target" name="--platform"> </a><a class="target" name="compilingmaterials/flags/—platform"> </a><a class="target" name="toc5.2.1"> </a><h3 id="l2605mdashplatform"><a class="header" href="#l2605mdashplatform">⟨L:2605⟩—platform</a></h3>
|
||
<p>
|
||
<p>By ⟨L:2607⟩default, <code>matc</code> generates material packages containing shaders for all supported platforms. If
|
||
you ⟨L:2608⟩wish to reduce the size of your material packages, it is recommended to select only the
|
||
appropriate ⟨L:2609⟩target platform. For instance, to compile a material package for Android only, run
|
||
the ⟨L:2610⟩following command:</p>
|
||
</p><pre class="listing backtick"><code><span class="line"></span>$ matc -p mobile -o ./materials/bin/car_paint.filamat ./materials/src/car_paint.mat</code></pre>
|
||
</section><section class="h3-section"><a class="target" name="--api"> </a><a class="target" name="compilingmaterials/flags/—api"> </a><a class="target" name="toc5.2.2"> </a><h3 id="l2616mdashapi"><a class="header" href="#l2616mdashapi">⟨L:2616⟩—api</a></h3>
|
||
<p>
|
||
<p>By ⟨L:2618⟩default, <code>matc</code> generates material packages containing shaders for the OpenGL API. You can choose
|
||
to ⟨L:2619⟩generate shaders for the Vulkan API in addition to the OpenGL shaders. If you intend on targeting
|
||
only ⟨L:2620⟩Vulkan capable devices, you can reduce the size of the material packages by generating only
|
||
the ⟨L:2621⟩set of Vulkan shaders:</p>
|
||
</p><pre class="listing backtick"><code><span class="line"></span>$ matc -a vulkan -o ./materials/bin/car_paint.filamat ./materials/src/car_paint.mat</code></pre>
|
||
</section><section class="h3-section"><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 id="l2627mdashoptimize-size"><a class="header" href="#l2627mdashoptimize-size">⟨L:2627⟩—optimize-size</a></h3>
|
||
<p>
|
||
<p>This ⟨L:2629⟩flag applies fewer optimization techniques to try and keep the final material as small as
|
||
possible. ⟨L:2630⟩If the compiled material is deemed too large by default, using this flag might be
|
||
a ⟨L:2631⟩good compromise between runtime performance and size.</p>
|
||
</p>
|
||
</section><section class="h3-section"><a class="target" name="--reflect"> </a><a class="target" name="compilingmaterials/flags/—reflect"> </a><a class="target" name="toc5.2.4"> </a><h3 id="l2633mdashreflect"><a class="header" href="#l2633mdashreflect">⟨L:2633⟩—reflect</a></h3>
|
||
<p>
|
||
<p>This ⟨L:2635⟩flag was designed to help build tools around <code>matc</code>. It allows you to print out specific
|
||
metadata ⟨L:2636⟩in JSON format. The example below prints out the list of parameters defined in Filament's
|
||
standard ⟨L:2637⟩skybox material. It produces a list of 2 parameters, named <code>showSun</code> and <code>skybox</code>,
|
||
respectively ⟨L:2638⟩a boolean and a cubemap texture.</p>
|
||
</p><pre class="listing backtick"><code><span class="line"></span>$ matc --reflect parameters filament/src/materials/skybox.mat
|
||
<span class="line"></span>{
|
||
<span class="line"></span> "parameters": [
|
||
<span class="line"></span> {
|
||
<span class="line"></span> "name": "showSun",
|
||
<span class="line"></span> "type": "bool",
|
||
<span class="line"></span> "size": "1"
|
||
<span class="line"></span> },
|
||
<span class="line"></span> {
|
||
<span class="line"></span> "name": "skybox",
|
||
<span class="line"></span> "type": "samplerCubemap",
|
||
<span class="line"></span> "format": "float",
|
||
<span class="line"></span> "precision": "default"
|
||
<span class="line"></span> }
|
||
<span class="line"></span> ]
|
||
<span class="line"></span>}</code></pre>
|
||
</section><section class="h3-section"><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 id="l2659mdashvariant-filter"><a class="header" href="#l2659mdashvariant-filter">⟨L:2659⟩—variant-filter</a></h3>
|
||
<p>
|
||
<p>This ⟨L:2661⟩flag can be used to further reduce the size of a compiled material. It is used to specify a
|
||
list ⟨L:2662⟩of shader variants that the application guarantees will never be needed. These shader variants
|
||
are ⟨L:2663⟩skipped during the code generation phase of <code>matc</code>, thus reducing the overall size of the
|
||
material.⟨L:2664⟩</p>
|
||
</p><p>
|
||
The ⟨L:2666⟩variants must be specified as a comma-separated list, using one of the following available
|
||
variants:⟨L:2667⟩
|
||
</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>
|
||
Example:⟨L:2677⟩
|
||
</p><pre class="listing backtick"><code><span class="line"></span>--variant-filter=skinning,shadowReceiver</code></pre><p>
|
||
Note ⟨L:2682⟩that some variants may automatically be filtered out. For instance, all lighting related
|
||
variants ⟨L:2683⟩(<code>directionalLighting</code>, etc.) are filtered out when compiling an <code>unlit</code> material.
|
||
</p><p>
|
||
When ⟨L:2685⟩this flag is used, the specified variant filters are merged with the variant filters specified
|
||
in ⟨L:2686⟩the material itself.
|
||
</p><p>
|
||
Use ⟨L:2688⟩this flag with caution, filtering out a variant required at runtime may lead to crashes.
|
||
</p>
|
||
</section></section></section><section class="h1-section"><a class="target" name="handlingcolors"> </a><a class="target" name="handlingcolors"> </a><a class="target" name="toc6"> </a><h1 id="l2690handling-colors"><a class="header" href="#l2690handling-colors">⟨L:2690⟩Handling colors</a></h1>
|
||
<section class="h2-section"><a class="target" name="linearcolors"> </a><a class="target" name="handlingcolors/linearcolors"> </a><a class="target" name="toc6.1"> </a><h2 id="l2692linear-colors"><a class="header" href="#l2692linear-colors">⟨L:2692⟩Linear colors</a></h2>
|
||
<p>
|
||
<p>If ⟨L:2694⟩the color data comes from a texture, simply make sure you use an sRGB texture to benefit from
|
||
automatic ⟨L:2695⟩hardware conversion from sRGB to linear. If the color data is passed as a parameter to
|
||
the ⟨L:2696⟩material you can convert from sRGB to linear by running the following algorithm on each
|
||
color ⟨L:2697⟩channel:</p>
|
||
</p><pre class="listing tilde"><code><span class="line"></span><span class="hljs-type">float</span> sRGB_to_linear(<span class="hljs-type">float</span> color) {
|
||
<span class="line"></span> <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 class="line"></span>}</code></pre><p>
|
||
Alternatively ⟨L:2705⟩you can use one of the two cheaper but less accurate versions shown below:
|
||
</p><pre class="listing tilde"><code><span class="line"></span><span class="hljs-comment">// Cheaper</span>
|
||
<span class="line"></span>linearColor = <span class="hljs-built_in">pow</span>(color, <span class="hljs-number">2.2</span>);
|
||
<span class="line"></span><span class="hljs-comment">// Cheapest</span>
|
||
<span class="line"></span>linearColor = color * color;</code></pre>
|
||
</section><section class="h2-section"><a class="target" name="pre-multipliedalpha"> </a><a class="target" name="handlingcolors/pre-multipliedalpha"> </a><a class="target" name="toc6.2"> </a><h2 id="l2714pre-multiplied-alpha"><a class="header" href="#l2714pre-multiplied-alpha">⟨L:2714⟩Pre-multiplied alpha</a></h2>
|
||
<p>
|
||
<p>A ⟨L:2716⟩color uses pre-multiplied alpha if its RGB components are multiplied by the alpha channel:</p>
|
||
</p><pre class="listing tilde"><code><span class="line"></span><span class="hljs-comment">// Compute pre-multiplied color</span>
|
||
<span class="line"></span>color.rgb *= color.a;</code></pre><p>
|
||
If ⟨L:2723⟩the color is sampled from a texture, you can simply ensure that the texture data is
|
||
pre-multiplied ⟨L:2724⟩ahead of time. On Android, any texture uploaded from a
|
||
<a href="https://developer.android.com/reference/android/graphics/Bitmap.html">Bitmap</a> ⟨L:2725⟩will be
|
||
pre-multiplied ⟨L:2726⟩by default.
|
||
</p>
|
||
</section></section><section class="h1-section"><a class="target" name="samplerusageinmaterials"> </a><a class="target" name="samplerusageinmaterials"> </a><a class="target" name="toc7"> </a><h1 id="l2728sampler-usage-in-materials"><a class="header" href="#l2728sampler-usage-in-materials">⟨L:2728⟩Sampler usage in Materials</a></h1>
|
||
<p>
|
||
<p>The ⟨L:2730⟩number of usable sampler parameters (e.g.: type is <code>sampler2d</code>) in materials is limited and
|
||
depends ⟨L:2731⟩on the material properties, shading model, feature level and variant filter.</p>
|
||
</p>
|
||
<section class="h2-section"><a class="target" name="featurelevel1and2"> </a><a class="target" name="samplerusageinmaterials/featurelevel1and2"> </a><a class="target" name="toc7.1"> </a><h2 id="l2733feature-level-1-and-2"><a class="header" href="#l2733feature-level-1-and-2">⟨L:2733⟩Feature level 1 and 2</a></h2>
|
||
<p>
|
||
<p><code>unlit</code> ⟨L:2735⟩materials can use up to 12 samplers by default.</p>
|
||
</p><p>
|
||
<code>lit</code> ⟨L:2737⟩materials can use up to 9 samplers by default, however if <code>refractionMode</code> or <code>reflectionMode</code>
|
||
is ⟨L:2738⟩set to <code>screenspace</code> that number is reduced to 8.
|
||
</p><p>
|
||
Finally ⟨L:2740⟩if <code>variantFilter</code> contains the <code>fog</code> filter, an extra sampler is made available, such that
|
||
<code>unlit</code> ⟨L:2741⟩materials can use up to 13 and <code>lit</code> materials up to 10 samplers by default.
|
||
</p>
|
||
</section><section class="h2-section"><a class="target" name="featurelevel3"> </a><a class="target" name="samplerusageinmaterials/featurelevel3"> </a><a class="target" name="toc7.2"> </a><h2 id="l2743feature-level-3"><a class="header" href="#l2743feature-level-3">⟨L:2743⟩Feature level 3</a></h2>
|
||
<p>
|
||
<p>16 ⟨L:2745⟩samplers are available.</p>
|
||
</p><p>
|
||
<div class="admonition ⟨L:2747⟩tip"><div class="admonition-title"> external samplers</div>
|
||
</p><p>
|
||
Be ⟨L:2748⟩aware that <code>external</code> samplers account for 2 regular samplers.</div>
|
||
</p><p>
|
||
⟨L:2750⟩</section></section></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.18 </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://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-chtml.js"></script>
|
||
</main>
|
||
|
||
<nav class="nav-wrapper" aria-label="Page navigation">
|
||
<!-- Mobile navigation buttons -->
|
||
<a rel="prev" href="../main/filament.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
|
||
<i class="fa fa-angle-left"></i>
|
||
</a>
|
||
|
||
<a rel="next prefetch" href="../samples/index.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
|
||
<i class="fa fa-angle-right"></i>
|
||
</a>
|
||
|
||
<div style="clear: both"></div>
|
||
</nav>
|
||
</div>
|
||
</div>
|
||
|
||
<nav class="nav-wide-wrapper" aria-label="Page navigation">
|
||
<a rel="prev" href="../main/filament.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
|
||
<i class="fa fa-angle-left"></i>
|
||
</a>
|
||
|
||
<a rel="next prefetch" href="../samples/index.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
|
||
<i class="fa fa-angle-right"></i>
|
||
</a>
|
||
</nav>
|
||
|
||
</div>
|
||
|
||
|
||
|
||
|
||
<script>
|
||
window.playground_copyable = true;
|
||
</script>
|
||
|
||
|
||
<script src="../elasticlunr.min.js"></script>
|
||
<script src="../mark.min.js"></script>
|
||
<script src="../searcher.js"></script>
|
||
|
||
<script src="../clipboard.min.js"></script>
|
||
<script src="../highlight.js"></script>
|
||
<script src="../book.js"></script>
|
||
|
||
<!-- Custom JS scripts -->
|
||
|
||
|
||
</div>
|
||
</body>
|
||
</html>
|