diff --git a/docs_src/.gitignore b/docs_src/.gitignore
new file mode 100644
index 00000000000..9df0444c32f
--- /dev/null
+++ b/docs_src/.gitignore
@@ -0,0 +1,2 @@
+book
+src/dup/*.md
diff --git a/docs_src/README.md b/docs_src/README.md
new file mode 100644
index 00000000000..a827206f765
--- /dev/null
+++ b/docs_src/README.md
@@ -0,0 +1,89 @@
+# Documentation
+
+Filament's documentation (which you are reading) is a collection of pages created with [`mdBook`].
+
+## How the book is created and updated {#how-to-create}
+### Prerequisites
+ - Install [`mdBook`] for your platform
+ - `selenium` package for python
+   ```shell
+   python3 -m pip install selenium
+   ```
+
+### Generate  {#how-to-generate}
+We wrote a python script to gather and transform the different documents in the project tree into a
+single book. This script can be found in [`docs_src/build/run.py`]. In addition,
+[`docs_src/build/duplicates.json`] is used to describe the markdown files that are copied and
+transformed from the source tree. These copies are placed into `docs_src/src/dup`.
+
+To collect the pages and generate the book, run the following
+```shell
+cd docs_src
+python3 build/run.py
+```
+
+### Copy to `docs`
+`docs` is the github-specfic directory for producing a web frontend (i.e. documentation) for a
+project.
+
+(To be completed)
+
+## Document sources
+We list the different document sources and how they are copied and processed into the collection
+of markdown files that are then processed with `mdBook`.
+
+### Introductory docs {#introductory-doc}
+The [github landing page] for Filament displays an extensive introduction to Filament. It
+links to `BUILDING.md` and `CONTRIBUTING.md`, which are conventional pages for building or
+contributing to the project. We copy these pages from their respective locations in the project
+tree into `docs_src/src/dup`. Moreover, to restore valid linkage between the pages, we need
+to perform a number of URL replacements in addition to the copy. These replacements are
+described in [`docs_src/build/duplicates.json`].
+
+### Core concept docs
+The primary design of Filament as a phyiscally-based renderer and details of its materials
+system are described in `Filament.md.html` and `Materials.md.html`, respectively. These two
+documents are written in [`markdeep`]. To embed them into our book, we
+ 1. Convert the markdeep into html
+ 2. Embed the html output in a markdown file
+ 3. Place the markdown file in `docs_src/src/main`
+
+We describe step 1 in detail for the sake of record:
+ - Start a local-only server to serve the markdeep file (e.g. `Filament.md.html`)
+ - Start a `selenium` driver (essentially run chromium in headless mode)
+ - Visit the local page through the driver (i.e. open url `http://localhost:xx/Filament.md.html?export`)
+ - Parse out the exported output in the retrieved html (note that the output of the markdeep
+   export is an html with the output captured in a `<pre>` tag).
+ - Replace css styling in the exported output as needed (so they don't interfere with the book's css.
+ - Replace resource urls to refer to locations relative to the mdbook structure.
+
+### READMEs
+Filament depends on a number of libraries, which reside in the directory `libs`. These individual
+libaries often have README.md in their root to describe itself. We collect these descriptions into our
+book. In addition, client usage of Filament also requires using a set of binary tools, which are
+located in `tools`. Some of tools also have README.md as description. We also collect them into the book.
+
+The process for copying and processing these READMEs is outlined in [Introductory docs](#introductory-doc).
+
+### Other technical notes
+These are technical documents that do not fit into a library, tool, or directory of the
+Filament source tree. We collect them into the `docs_src/src/notes` directory. No additional
+processing are needed for these documents.
+
+## Adding more documents
+To add any documentation, first consider the type of the document you like to add. If it
+belongs to any of the above sources, then simply place the document in the appropriate place,
+add a link in `SUMMARY.md`, and perform the steps outlined in
+[how-to create section](#how-to-create).
+
+For example, if you are adding a general technical note, then you would
+ - Place the document (file with extension `.md`) in `docs_src/src/notes`
+ - Add a link in [`docs_src/src/SUMMARY.md`]
+ - Run the commands in the [Generate](#how-to-generate) section
+
+[github landing page]: https://google.github.io/filament
+[`mdBook`]: https://rust-lang.github.io/mdBook/
+[`markdeep`]: https://casual-effects.com/markdeep/
+[`docs_src/build/run.py`]: https://github.com/google/filament/blob/main/docs_src/build/run.py
+[`docs_src/build/duplicates.json`]: https://github.com/google/filament/blob/main/docs_src/build/duplicates.json
+[`docs_src/src/SUMMARY.md`]: https://github.com/google/filament/blob/main/docs_src/src/SUMMARY.md
diff --git a/docs_src/book.toml b/docs_src/book.toml
new file mode 100644
index 00000000000..1050eee0002
--- /dev/null
+++ b/docs_src/book.toml
@@ -0,0 +1,20 @@
+[book]
+authors = []
+language = "en"
+multilingual = false
+src = "src"
+title = "Filament"
+
+[build]
+create-missing = false
+
+[output.html]
+mathjax-support = true
+default-theme = "light"
+preferred-dark-theme = "light"
+
+[output.html.print]
+enable = false
+
+[output.html.fold]
+enable = false
diff --git a/docs_src/build/duplicates.json b/docs_src/build/duplicates.json
new file mode 100644
index 00000000000..d6713799125
--- /dev/null
+++ b/docs_src/build/duplicates.json
@@ -0,0 +1,74 @@
+{
+    "README.md": {
+        "dest": "dup/intro.md",
+        "link_transforms": {
+            "BUILDING.md": "building.md",
+            "/CONTRIBUTING.md": "contributing.md",
+            "/CODE_STYLE.md": "code_style.md",
+            "docs/images/samples": "../images/samples"
+        }
+    },
+    "BUILDING.md": {
+        "dest": "dup/building.md"
+    },
+    "CONTRIBUTING.md": {
+        "dest": "dup/contributing.md"
+    },
+    "CODE_STYLE.md": {
+        "dest": "dup/code_style.md"
+    },
+    "libs/uberz/README.md": {
+        "dest": "dup/uberz.md"
+    },
+    "libs/bluegl/README.md": {
+        "dest": "dup/bluegl.md"
+    },
+    "libs/bluevk/README.md": {
+        "dest": "dup/bluevk.md"
+    },
+    "libs/gltfio/README.md": {
+        "dest": "dup/gltfio.md"
+    },
+    "libs/filamat/README.md": {
+        "dest": "dup/filamat.md"
+    },
+    "libs/iblprefilter/README.md": {
+        "dest": "dup/iblprefilter.md"
+    },
+    "libs/matdbg/README.md": {
+        "dest": "dup/matdbg.md"
+    },
+    "tools/normal-blending/README.md": {
+        "dest": "dup/normal_blending.md"
+    },
+    "tools/filamesh/README.md": {
+        "dest": "dup/filamesh.md"
+    },
+    "tools/beamsplitter/README.md": {
+        "dest": "dup/beamsplitter.md"
+    },
+    "tools/cmgen/README.md": {
+        "dest": "dup/cmgen.md"
+    },
+    "tools/mipgen/README.md": {
+        "dest": "dup/mipgen.md"
+    },
+    "tools/matinfo/README.md": {
+        "dest": "dup/matinfo.md"
+    },
+    "tools/roughness-prefilter/README.md": {
+        "dest": "dup/roughness_prefilter.md"
+    },
+    "tools/zbloat/README.md": {
+        "dest": "dup/zbloat.md"
+    },
+    "tools/cso-lut/README.md": {
+        "dest": "dup/cso_lut.md"
+    },
+    "tools/specular-color/README.md": {
+        "dest": "dup/specular_color.md"
+    },
+    "docs_src/README.md": {
+        "dest": "dup/docs.md"
+    }
+}
diff --git a/docs_src/build/run.py b/docs_src/build/run.py
new file mode 100644
index 00000000000..42573e9f85c
--- /dev/null
+++ b/docs_src/build/run.py
@@ -0,0 +1,128 @@
+# Copyright (C) 2025 The Android Open Source Project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import json
+import os
+import re
+from utils import execute, ArgParseImpl
+
+CUR_DIR = os.path.dirname(os.path.abspath(__file__))
+DOCS_SRC_DIR = os.path.join(CUR_DIR, '../')
+ROOT_DIR = os.path.join(CUR_DIR, '../../')
+SRC_DIR = os.path.join(CUR_DIR, '../src')
+MARKDEEP_DIR = os.path.join(CUR_DIR, '../markdeep')
+DUP_DIR = os.path.join(SRC_DIR, 'dup')
+MAIN_DIR = os.path.join(SRC_DIR, 'main')
+
+def transform_dup_file_link(line, transforms):
+  URL_CONTENT = '[-a-zA-Z0-9()@:%_\+.~#?&//=]+'
+  res = re.findall(f'\[(.+)\]\(({URL_CONTENT})\)', line)
+  for text, url in  res:
+    word = f'[{text}]({url})'
+    for tkey in transforms.keys():
+      if url.startswith(tkey):
+        nurl = url.replace(tkey, transforms[tkey])
+        line = line.replace(word, f'[{text}]({nurl})')
+        break
+  return line
+
+def pull_duplicates():
+  if not os.path.exists(DUP_DIR):
+    os.mkdir(DUP_DIR)
+
+  config = {}
+  with open(f'{CUR_DIR}/duplicates.json') as config_txt:
+    config = json.loads(config_txt.read())
+
+  for fin in config.keys():
+    new_name = config[fin]['dest']
+    link_transforms = config[fin].get('link_transforms', {})
+    fpath = os.path.join(ROOT_DIR, fin)
+    new_fpath = os.path.join(SRC_DIR, new_name)
+
+    with open(fpath, 'r') as in_file:
+      with open(new_fpath, 'w') as out_file:
+        for line in in_file.readlines():
+          out_file.write(transform_dup_file_link(line, link_transforms))
+
+def pull_markdeep_docs():
+  import http.server
+  import socketserver
+  import threading
+  from selenium import webdriver
+  from selenium.webdriver.chrome.options import Options
+  from selenium.webdriver.common.by import By
+  import time
+
+  class Server(socketserver.ThreadingMixIn, http.server.HTTPServer):
+    """Handle requests in a separate thread."""
+
+  class Handler(http.server.SimpleHTTPRequestHandler):
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, directory=MARKDEEP_DIR, **kwargs)
+
+  def start_server(port):
+    """Starts the web server in a separate thread."""
+    httpd = Server(("", port), Handler)
+    server_thread = threading.Thread(target=httpd.serve_forever)
+    server_thread.daemon = True  # Allow main thread to exit
+    server_thread.start()
+    print(f"Server started on port {port}...")
+    return httpd
+
+  PORT = 12345
+  httpd = start_server(PORT)
+
+  # Set up Chrome options for headless mode
+  chrome_options = Options()
+  chrome_options.add_argument("--headless")
+
+  # This option is necessary for running on some VMs
+  chrome_options.add_argument("--no-sandbox")
+
+  # Create a new Chrome instance in headless mode
+  driver = webdriver.Chrome(options=chrome_options)
+
+  for doc in ['Filament', 'Materials']:
+    # Open the URL with ?export, which markdeep will export the resulting html.
+    driver.get(f"http://localhost:{PORT}/{doc}.md.html?export")
+
+    time.sleep(3)
+    # We extract the html from the resulting "page" (an html output itself).
+    text = driver.find_elements(By.TAG_NAME, "pre")[0].text
+
+    # 1. Remove the double empty lines.  These make the following text seem like markdown text as oppose to embedded html.
+    # 2. Remove the max-width styling from the body tag.
+    # 3. Remove the font-family styling from the body tag.
+    text = text.replace("\n\n","\n")\
+               .replace("max-width:680px;", "")\
+               .replace("font-family:Palatino", "--font-family:Palatino")\
+               .replace("\"./images", "\"../images")\
+               .replace("\"images/", "\"../images/")
+
+    # Save the page source as .md with embedded html
+    with open(f'{MAIN_DIR}/{doc.lower()}.md', "w", encoding="utf-8") as f:
+      f.write(text)
+
+  # Close the browser
+  driver.quit()
+  # Shutdown the server
+  httpd.shutdown()
+
+if __name__ == "__main__":
+  pull_duplicates()
+  pull_markdeep_docs()
+
+  res, err = execute('mdbook build', cwd=DOCS_SRC_DIR)
+  assert res == 0, f"failed to execute `mdbook`. return-code={res} err=\"{err}\""
diff --git a/docs_src/build/utils.py b/docs_src/build/utils.py
new file mode 100644
index 00000000000..80aa1453254
--- /dev/null
+++ b/docs_src/build/utils.py
@@ -0,0 +1,68 @@
+# Copyright (C) 2025 The Android Open Source Project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import subprocess
+import os
+import argparse
+import sys
+
+def execute(cmd,
+            cwd=None,
+            capture_output=True,
+            stdin=None,
+            env=None,
+            raise_errors=False):
+  in_env = os.environ
+  in_env.update(env if env else {})
+  home = os.environ['HOME']
+  if f'{home}/bin' not in in_env['PATH']:
+    in_env['PATH'] = in_env['PATH'] + f':{home}/bin'
+
+  stdout = subprocess.PIPE if capture_output else sys.stdout
+  stderr = subprocess.PIPE if capture_output else sys.stdout
+  output = ''
+  err_output = ''
+  return_code = -1
+  kwargs = {
+      'cwd': cwd,
+      'env': in_env,
+      'stdout': stdout,
+      'stderr': stderr,
+      'stdin': stdin,
+      'universal_newlines': True
+  }
+  if capture_output:
+    process = subprocess.Popen(cmd.split(' '), **kwargs)
+    output, err_output = process.communicate()
+    return_code = process.returncode
+  else:
+    return_code = subprocess.call(cmd.split(' '), **kwargs)
+
+  if return_code:
+    # Error
+    if raise_errors:
+      raise subprocess.CalledProcessError(return_code, cmd)
+  if output:
+    if type(output) != str:
+      try:
+        output = output.decode('utf-8').strip()
+      except UnicodeDecodeError as e:
+        print('cannot decode ', output, file=sys.stderr)
+  return return_code, (output if return_code == 0 else err_output)
+
+class ArgParseImpl(argparse.ArgumentParser):
+  def error(self, message):
+    sys.stderr.write('error: %s\n' % message)
+    self.print_help()
+    sys.exit(1)
diff --git a/docs_src/markdeep/Filament.md.html b/docs_src/markdeep/Filament.md.html
new file mode 100644
index 00000000000..167f967bd51
--- /dev/null
+++ b/docs_src/markdeep/Filament.md.html
@@ -0,0 +1,4315 @@
+               <meta charset="utf-8">
+
+<style>img { max-width: 100%; }</style>
+
+**Physically Based Rendering in Filament**
+
+![](images/filament_logo.png)
+
+# About
+
+This document is part of the [Filament project](https://github.com/google/filament). To report errors in this document please use the [project's issue tracker](https://github.com/google/filament/issues).
+
+## Authors
+
+- [Romain Guy](https://github.com/romainguy), [@romainguy](https://twitter.com/romainguy)
+- [Mathias Agopian](https://github.com/pixelflinger), [@darthmoosious](https://twitter.com/darthmoosious)
+
+# Overview
+
+Filament is a physically based rendering (PBR) engine for Android. The goal of Filament is to offer a set of tools and APIs for Android developers that will enable them to create high quality 2D and 3D rendering with ease.
+
+The goal of this document is to explain the equations and theory behind the material and lighting models used in Filament. This document is intended as a reference for contributors to Filament or developers interested in the inner workings of the engine. We will provide code snippets as needed to make the relationship between theory and practice as clear as possible.
+
+This document is not intended as a design document. It focuses solely on algorithms and its content could be used to implement PBR in any engine. However, this document explains why we chose specific algorithms/models over others.
+
+Unless noted otherwise, all the 3D renderings present in this document have been generated in-engine (prototype or production). Many of these 3D renderings were captured during the early stages of development of Filament and do not reflect the final quality.
+
+## Principles
+
+Real-time rendering is an active area of research and there is a large number of equations, algorithms and implementation to choose from for every single feature that needs to be implemented (the book *Rendering real-time shadows*, for instance, is a 400 pages summary of dozens of shadows rendering techniques). As such, we must first define our goals (or principles, to follow Brent Burley's seminal paper Physically-based shading at Disney [#Burley12]) before we can make informed decisions.
+
+Real-time mobile performance
+:   Our primary goal is to design and implement a rendering system able to perform efficiently on mobile platforms. The primary target will be OpenGL ES 3.x class GPUs.
+
+Quality
+:   Our rendering system will emphasize overall picture quality. We will however accept quality compromises to support low and medium performance GPUs.
+
+Ease of use
+:   Artists need to be able to iterate often and quickly on their assets and our rendering system must allow them to do so intuitively. We must therefore provide parameters that are easy to understand (for instance, no specular power).
+
+    We also understand that not all developers have the luxury to work with artists. The physically based approach of our system will allow developers to craft visually plausible materials without the need to understand the theory behind our implementation.
+
+    For both artists and developers, our system will rely on as few parameters as possible to reduce trial and error and allow users to quickly master the material model.
+
+    In addition, any combination of parameter values should lead to physically plausible results. Physically implausible materials must be hard to create.
+
+Familiarity
+:   Our system should use physical units everywhere possible: distances in meters or centimeters, color temperatures in Kelvin, light units in lumens or candelas, etc.
+
+Flexibility
+:   A physically based approach must not preclude non-realistic rendering. User interfaces for instance will need unlit materials.
+
+Deployment size
+:   While not directly related to the content of this document, it bears emphasizing our desire to keep the rendering library as small as possible so any application can bundle it without increasing the binary to undesirable sizes.
+
+## Physically based rendering
+
+We chose to adopt PBR for its benefits from an artistic and production efficient standpoints, and because it is compatible with our goals.
+
+Physically based rendering is a rendering method that provides a more accurate representation of materials and how they interact with light when compared to traditional real-time models. The separation of materials and lighting at the core of the PBR method makes it easier to create realistic assets that look accurate in all lighting conditions.
+
+# Notation
+
+$$
+\newcommand{NoL}{n \cdot l}
+\newcommand{NoV}{n \cdot v}
+\newcommand{NoH}{n \cdot h}
+\newcommand{VoH}{v \cdot h}
+\newcommand{LoH}{l \cdot h}
+\newcommand{fNormal}{f_{0}}
+\newcommand{fDiffuse}{f_d}
+\newcommand{fSpecular}{f_r}
+\newcommand{fX}{f_x}
+\newcommand{aa}{\alpha^2}
+\newcommand{fGrazing}{f_{90}}
+\newcommand{schlick}{F_{Schlick}}
+\newcommand{nior}{n_{ior}}
+\newcommand{Ed}{E_d}
+\newcommand{Lt}{L_{\bot}}
+\newcommand{Lout}{L_{out}}
+\newcommand{cosTheta}{\left< \cos \theta \right> }
+$$
+
+The equations found throughout this document use the symbols described in table [symbols].
+
+
+          Symbol             |           Definition
+:---------------------------:|:---------------------------|
+$v$                          | View unit vector
+$l$                          | Incident light unit vector
+$n$                          | Surface normal unit vector
+$h$                          | Half unit vector between $l$ and $v$
+$f$                          | BRDF
+$\fDiffuse$                  | Diffuse component of a BRDF
+$\fSpecular$                 | Specular component of a BRDF
+$\alpha$                     | Roughness, remapped from using input `perceptualRoughness`
+$\sigma$                     | Diffuse reflectance
+$\Omega$                     | Spherical domain
+$\fNormal$                   | Reflectance at normal incidence
+$\fGrazing$                  | Reflectance at grazing angle
+$\chi^+(a)$                  | Heaviside function (1 if $a > 0$ and 0 otherwise)
+$n_{ior}$                    | Index of refraction (IOR) of an interface
+$\left< \NoL \right>$        | Dot product clamped to [0..1]
+$\left< a \right>$           | Saturated value (clamped to [0..1])
+[Table [symbols]: Symbols definitions]
+
+# Material system
+
+The sections below describe multiple material models to simplify the description of various surface features such as anisotropy or the clear coat layer. In practice however some of these models are condensed into a single one. For instance, the standard model, the clear coat model and the anisotropic model can be combined to form a single, more flexible and powerful model. Please refer to the [Materials documentation](./Materials.md.html) to get a description of the material models as implemented in Filament.
+
+## Standard model
+
+The goal of our model is to represent standard material appearances. A material model is described mathematically by a BSDF (Bidirectional Scattering Distribution Function), which is itself composed of two other functions: the BRDF (Bidirectional Reflectance Distribution Function) and the BTDF (Bidirectional Transmittance Function).
+
+Since we aim to model commonly encountered surfaces, our standard material model will focus on the BRDF and ignore the BTDF, or approximate it greatly. Our standard model will therefore only be able to correctly mimic reflective, isotropic, dielectric or conductive surfaces with short mean free paths.
+
+The BRDF describes the surface response of a standard material as a function made of two terms:
+- A diffuse component, or $f_d$
+- A specular component, or $f_r$
+
+The relationship between a surface, the surface normal, incident light and these terms is shown in figure [frFd] (we ignore subsurface scattering for now):
+
+![Figure [frFd]: Interaction of the light with a surface using BRDF model with a diffuse term $ f_d $ and a specular term $ f_r $](images/diagram_fr_fd.png)
+
+The complete surface response can be expressed as such:
+
+$$\begin{equation}\label{brdf}
+f(v,l)=f_d(v,l)+f_r(v,l)
+\end{equation}$$
+
+This equation characterizes the surface response for incident light from a single direction. The full rendering equation would require to integrate $l$ over the entire hemisphere.
+
+Commonly encountered surfaces are usually not made of a flat interface so we need a model that can characterize the interaction of light with an irregular interface.
+
+A microfacet BRDF is a good physically plausible BRDF for that purpose. Such BRDF states that surfaces are not smooth at a micro level, but made of a large number of randomly aligned planar surface fragments, called microfacets. Figure [microfacetVsFlat] shows the difference between a flat interface and an irregular interface at a micro level:
+
+![Figure [microfacetVsFlat]: Irregular interface as modeled by a microfacet model (left) and flat interface (right)](images/diagram_microfacet.png)
+
+Only the microfacets whose normal is oriented halfway between the light direction and the view direction will reflect visible light, as shown in figure [microfacets].
+
+![Figure [microfacets]: Microfacets](images/diagram_macrosurface.png)
+
+However, not all microfacets with a properly oriented normal will contribute reflected light as the BRDF takes into account masking and shadowing. This is illustrated in figure [microfacetShadowing].
+
+![Figure [microfacetShadowing]: Masking and shadowing of microfacets](images/diagram_shadowing_masking.png)
+
+A microfacet BRDF is heavily influenced by a _roughness_ parameter which describes how smooth (low roughness) or how rough (high roughness) a surface is at a micro level. The smoother the surface, the more facets are aligned and the more pronounced the reflected light is. The rougher the surface, the fewer facets are oriented towards the camera and incoming light is scattered away from the camera after reflection, giving a blurry aspect to the specular highlights.
+
+Figure [roughness] shows surfaces of different roughness and how light interacts with them.
+
+![Figure [roughness]: Varying roughness (from left to right, rough to smooth) and the resulting BRDF specular component lobe](images/diagram_roughness.png)
+
+!!! Note: About roughness
+    The roughness parameter as set by the user is called `perceptualRoughness` in the shader snippets throughout this document. The variable called `roughness` is the `perceptualRoughness` with a remapping explained in section [Parameterization].
+
+A microfacet model is described by the following equation (where x stands for the specular or diffuse component):
+
+$$\begin{equation}
+\fX(v,l) = \frac{1}{| \NoV | | \NoL |}
+\int_\Omega D(m,\alpha) G(v,l,m) f_m(v,l,m) (v \cdot m) (l \cdot m) dm
+\end{equation}$$
+
+The term $D$ models the distribution of the microfacets (this term is also referred to as the NDF or Normal Distribution Function). This term plays a primordial role in the appearance of surfaces as shown in figure [roughness].
+
+The term $G$ models the visibility (or occlusion or shadow-masking) of the microfacets.
+
+Since this equation is valid for both the specular and diffuse components, the difference lies in the microfacet BRDF $f_m$.
+
+It is important to note that this equation is used to integrate over the hemisphere at a _micro level_:
+
+![Figure [microLevel]: Modeling the surface response at a single point requires an integration at the micro level](images/diagram_micro_vs_macro.png)
+
+The diagram above shows that at a macro level, the surfaces is considered flat. This helps simplify our equations by assuming that a shaded fragment lit from a single direction corresponds to a single point at the surface.
+
+At a micro level however, the surface is not flat and we cannot assume a single ray of light anymore (we can however assume that the incident rays are parallel). Since the micro facets will scatter the light in different directions given a bundle of parallel incident rays, we must integrate the surface response over a hemisphere, noted m in the above diagram.
+
+It is obviously not practical to compute the full integration over the microfacets hemisphere for each shaded fragment. We will therefore rely on approximations of the integration for both the specular and diffuse components.
+
+## Dielectrics and conductors
+
+To better understand some of the equations and behaviors shown below, we must first clearly understand the difference between metallic (conductor) and non-metallic (dielectric) surfaces.
+
+We saw earlier that when incident light hits a surface governed by a BRDF, the light is reflected as two separate components: the diffuse reflectance and the specular reflectance. The modelization of this behavior is straightforward as shown in figure [bsdfBrdf].
+
+![Figure [bsdfBrdf]: Modelization of the BRDF part of a BSDF](images/diagram_fr_fd.png)
+
+This modelization is a simplification of how the light actually interacts with the surface. In reality, part of the incident light will penetrate the surface, scatter inside, and exit the surface again as diffuse reflectance. This phenomenon is illustrated in figure [diffuseScattering].
+
+![Figure [diffuseScattering]: Scattering of diffuse light](images/diagram_scattering.png)
+
+Here lies the difference between conductors and dielectrics. There is no subsurface scattering occurring with purely metallic materials, which means there is no diffuse component (and we will see later that this has an influence on the perceived color of the specular component). Scattering happens in dielectrics, which means they have both specular and diffuse components.
+
+To properly modelize the BRDF we must therefore distinguish between dielectrics and conductors (scattering not shown for clarity), as shown in figure [dielectricConductor].
+
+![Figure [dielectricConductor]: BRDF modelization for dielectric and conductor surfaces](images/diagram_brdf_dielectric_conductor.png)
+
+## Energy conservation
+
+Energy conservation is one of the key components of a good BRDF for physically based rendering. An energy conservative BRDF states that the total amount of specular and diffuse reflectance energy is less than the total amount of incident energy. Without an energy conservative BRDF, artists must manually ensure that the light reflected off a surface is never more intense than the incident light.
+
+## Specular BRDF
+
+For the specular term, $f_r$ is a mirror BRDF that can be modeled with the Fresnel law, noted $F$ in the Cook-Torrance approximation of the microfacet model integration:
+
+$$\begin{equation}
+f_r(v,l) = \frac{D(h, \alpha) G(v, l, \alpha) F(v, h, f0)}{4(\NoV)(\NoL)}
+\end{equation}$$
+
+Given our real-time constraints, we must use an approximation for the three terms $D$, $G$ and $F$. [#Karis13a] has compiled a great list of formulations for these three terms that can be used with the Cook-Torrance specular BRDF. The sections that follow describe the equations we picked for these terms.
+
+### Normal distribution function (specular D)
+
+[#Burley12] observed that long-tailed normal distribution functions (NDF) are a good fit for real-world surfaces. The GGX distribution described in [#Walter07] is a distribution with long-tailed falloff and short peak in the highlights, with a simple formulation suitable for real-time implementations. It is also a popular model, equivalent to the Trowbridge-Reitz distribution, in modern physically based renderers.
+
+$$\begin{equation}
+D_{GGX}(h,\alpha) = \frac{\aa}{\pi ( (\NoH)^2 (\aa - 1) + 1)^2}
+\end{equation}$$
+
+The GLSL implementation of the NDF, shown in listing [specularD], is simple and efficient.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+float D_GGX(float NoH, float roughness) {
+    float a = NoH * roughness;
+    float k = roughness / (1.0 - NoH * NoH + a * a);
+    return k * k * (1.0 / PI);
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+[Listing [specularD]: Implementation of the specular D term in GLSL]
+
+We can improve this implementation by using half precision floats. This optimization requires changes to the original equation as there are two problems when computing $1 - (\NoH)^2$ in half-floats. First, this computation suffers from floating point cancellation when $(\NoH)^2$ is close to 1 (highlights). Secondly $\NoH$ does not have enough precision around 1.
+
+The solution involves Lagrange's identity:
+
+$$\begin{equation}
+| a \times b |^2 = |a|^2 |b|^2 - (a \cdot b)^2
+\end{equation}$$
+
+Since both $n$ and $h$ are unit vectors, $|n \times h|^2 = 1 - (\NoH)^2$. This allows us to compute $1 - (\NoH)^2$ directly with half precision floats by using a simple cross product. Listing [specularDfp16] shows the final optimized implementation.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#define MEDIUMP_FLT_MAX    65504.0
+#define saturateMediump(x) min(x, MEDIUMP_FLT_MAX)
+
+float D_GGX(float roughness, float NoH, const vec3 n, const vec3 h) {
+    vec3 NxH = cross(n, h);
+    float a = NoH * roughness;
+    float k = roughness / (dot(NxH, NxH) + a * a);
+    float d = k * k * (1.0 / PI);
+    return saturateMediump(d);
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+[Listing [specularDfp16]: Implementation of the specular D term in GLSL optimized for fp16]
+
+### Geometric shadowing (specular G)
+
+Eric Heitz showed in [#Heitz14] that the Smith geometric shadowing function is the correct and exact $G$ term to use. The Smith formulation is the following:
+
+$$\begin{equation}
+G(v,l,\alpha) = G_1(l,\alpha) G_1(v,\alpha)
+\end{equation}$$
+
+$G_1$ can in turn follow several models, and is commonly set to the GGX formulation:
+
+$$\begin{equation}
+G_1(v,\alpha) = G_{GGX}(v,\alpha) = \frac{2 (\NoV)}{\NoV + \sqrt{\aa + (1 - \aa) (\NoV)^2}}
+\end{equation}$$
+
+The full Smith-GGX formulation thus becomes:
+
+$$\begin{equation}
+G(v,l,\alpha) = \frac{2 (\NoL)}{\NoL + \sqrt{\aa + (1 - \aa) (\NoL)^2}} \frac{2 (\NoV)}{\NoV + \sqrt{\aa + (1 - \aa) (\NoV)^2}}
+\end{equation}$$
+
+We can observe that the dividends $2 (\NoL)$ and $2 (n \cdot v)$ allow us to simplify the original function $f_r$ by introducing a visibility function $V$:
+
+$$\begin{equation}
+f_r(v,l) = D(h, \alpha) V(v, l, \alpha) F(v, h, f_0)
+\end{equation}$$
+
+Where:
+
+$$\begin{equation}
+V(v,l,\alpha) = \frac{G(v, l, \alpha)}{4 (\NoV) (\NoL)} = V_1(l,\alpha) V_1(v,\alpha)
+\end{equation}$$
+
+And:
+
+$$\begin{equation}
+V_1(v,\alpha) = \frac{1}{\NoV + \sqrt{\aa + (1 - \aa) (\NoV)^2}}
+\end{equation}$$
+
+Heitz notes however that taking the height of the microfacets into account to correlate masking and shadowing leads to more accurate results. He defines the height-correlated Smith function thusly:
+
+$$\begin{equation}
+G(v,l,h,\alpha) = \frac{\chi^+(\VoH) \chi^+(\LoH)}{1 + \Lambda(v) + \Lambda(l)}
+\end{equation}$$
+
+$$\begin{equation}
+\Lambda(m) = \frac{-1 + \sqrt{1 + \aa tan^2(\theta_m)}}{2} = \frac{-1 + \sqrt{1 + \aa \frac{(1 - cos^2(\theta_m))}{cos^2(\theta_m)}}}{2}
+\end{equation}$$
+
+Replacing $cos(\theta_m)$ by $\NoV$, we obtain:
+
+$$\begin{equation}
+\Lambda(v) = \frac{1}{2} \left( \frac{\sqrt{\aa + (1 - \aa)(\NoV)^2}}{\NoV} - 1 \right)
+\end{equation}$$
+
+From which we can derive the visibility function:
+
+$$\begin{equation}
+V(v,l,\alpha) = \frac{0.5}{\NoL \sqrt{(\NoV)^2 (1 - \aa) + \aa} + \NoV \sqrt{(\NoL)^2 (1 - \aa) + \aa}}
+\end{equation}$$
+
+The GLSL implementation of the visibility term, shown in listing [specularV], is a bit more expensive than we would like since it requires two `sqrt` operations.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+float V_SmithGGXCorrelated(float NoV, float NoL, float roughness) {
+    float a2 = roughness * roughness;
+    float GGXV = NoL * sqrt(NoV * NoV * (1.0 - a2) + a2);
+    float GGXL = NoV * sqrt(NoL * NoL * (1.0 - a2) + a2);
+    return 0.5 / (GGXV + GGXL);
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+[Listing [specularV]: Implementation of the specular V term in GLSL]
+
+We can optimize this visibility function by using an approximation after noticing that all the terms under the square roots are squares and that all the terms are in the $[0..1]$ range:
+
+$$\begin{equation}
+V(v,l,\alpha) = \frac{0.5}{\NoL (\NoV (1 - \alpha) + \alpha) + \NoV (\NoL (1 - \alpha) + \alpha)}
+\end{equation}$$
+
+This approximation is mathematically wrong but saves two square root operations and is good enough for real-time mobile applications, as shown in listing [approximatedSpecularV].
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+float V_SmithGGXCorrelatedFast(float NoV, float NoL, float roughness) {
+    float a = roughness;
+    float GGXV = NoL * (NoV * (1.0 - a) + a);
+    float GGXL = NoV * (NoL * (1.0 - a) + a);
+    return 0.5 / (GGXV + GGXL);
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+[Listing [approximatedSpecularV]: Implementation of the approximated specular V term in GLSL]
+
+[#Hammon17] proposes the same approximation based on the same observation that the square root can be removed. It does so by rewriting the expressions as _lerps_:
+
+$$\begin{equation}
+V(v,l,\alpha) = \frac{0.5}{lerp(2 (\NoL) (\NoV), \NoL + \NoV, \alpha)}
+\end{equation}$$
+
+### Fresnel (specular F)
+
+The Fresnel effect plays an important role in the appearance of physically based materials. This effect models the fact that the amount of light the viewer sees reflected from a surface depends on the viewing angle. Large bodies of water are a perfect way to experience this phenomenon, as shown in figure [fresnelLake]. When looking at the water straight down (at normal incidence) you can see through the water. However, when looking further out in the distance (at grazing angle, where perceived light rays are getting parallel to the surface), you will see the specular reflections on the water become more intense.
+
+The amount of light reflected depends not only on the viewing angle, but also on the index of refraction (IOR) of the material. At normal incidence (perpendicular to the surface, or 0 degree angle), the amount of light reflected back is noted $\fNormal$ and can be derived from the IOR as we will see in section [Reflectance remapping]. The amount of light reflected back at grazing angle is noted $\fGrazing$ and approaches 100% for smooth materials.
+
+![Figure [fresnelLake]: The Fresnel effect is particularly evident on large bodies of water](images/photo_fresnel_lake.jpg)
+
+More formally, the Fresnel term defines how light reflects and refracts at the interface between two different media, or the ratio of reflected and transmitted energy. [#Schlick94] describes an inexpensive approximation of the Fresnel term for the Cook-Torrance specular BRDF:
+
+$$\begin{equation}
+F_{Schlick}(v,h,\fNormal,\fGrazing) = \fNormal + (\fGrazing - \fNormal)(1 - \VoH)^5
+\end{equation}$$
+
+The constant $\fNormal$ represents the specular reflectance at normal incidence and is achromatic for dielectrics, and chromatic for metals. The actual value depends on the index of refraction of the interface. The GLSL implementation of this term requires the use of a `pow`, as shown in listing [specularF], which can be replaced by a few multiplications.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+vec3 F_Schlick(float u, vec3 f0, float f90) {
+    return f0 + (vec3(f90) - f0) * pow(1.0 - u, 5.0);
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+[Listing [specularF]: Implementation of the specular F term in GLSL]
+
+This Fresnel function can be seen as interpolating between the incident specular reflectance and the reflectance at grazing angles, represented here by $\fGrazing$. Observation of real world materials show that both dielectrics and conductors exhibit achromatic specular reflectance at grazing angles and that the Fresnel reflectance is 1.0 at 90 degrees. A more correct $\fGrazing$ is discussed in section [Specular occlusion].
+
+Using $\fGrazing$ set to 1, the Schlick approximation for the Fresnel term can be optimized for scalar operations by refactoring the code slightly. The result is shown in listing [scalarSpecularF].
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+vec3 F_Schlick(float u, vec3 f0) {
+    float f = pow(1.0 - u, 5.0);
+    return f + f0 * (1.0 - f);
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+[Listing [scalarSpecularF]: Scalar optimization of the specular F term in GLSL]
+
+## Diffuse BRDF
+
+In the diffuse term, $f_m$ is a Lambertian function and the diffuse term of the BRDF becomes:
+
+$$\begin{equation}
+\fDiffuse(v,l) = \frac{\sigma}{\pi} \frac{1}{| \NoV | | \NoL |}
+\int_\Omega D(m,\alpha) G(v,l,m) (v \cdot m) (l \cdot m) dm
+\end{equation}$$
+
+Our implementation will instead use a simple Lambertian BRDF that assumes a uniform diffuse response over the microfacets hemisphere:
+
+$$\begin{equation}
+\fDiffuse(v,l) = \frac{\sigma}{\pi}
+\end{equation}$$
+
+In practice, the diffuse reflectance $\sigma$ is multiplied later, as shown in listing [diffuseBRDF].
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+float Fd_Lambert() {
+    return 1.0 / PI;
+}
+
+vec3 Fd = diffuseColor * Fd_Lambert();
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+[Listing [diffuseBRDF]: Implementation of the diffuse Lambertian BRDF in GLSL]
+
+The Lambertian BRDF is obviously extremely efficient and delivers results close enough to more complex models.
+
+However, the diffuse part would ideally be coherent with the specular term and take into account the surface roughness. Both the Disney diffuse BRDF [#Burley12] and Oren-Nayar model [#Oren94] take the roughness into account and create some retro-reflection at grazing angles. Given our constraints we decided that the extra runtime cost does not justify the slight increase in quality. This sophisticated diffuse model also renders image-based and spherical harmonics more difficult to express and implement.
+
+For completeness, the Disney diffuse BRDF expressed in [#Burley12] is the following:
+
+$$\begin{equation}
+\fDiffuse(v,l) = \frac{\sigma}{\pi} \schlick(n,l,1,\fGrazing) \schlick(n,v,1,\fGrazing)
+\end{equation}$$
+
+Where:
+
+$$\begin{equation}
+\fGrazing=0.5 + 2 \cdot \alpha cos^2(\theta_d)
+\end{equation}$$
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+float F_Schlick(float u, float f0, float f90) {
+    return f0 + (f90 - f0) * pow(1.0 - u, 5.0);
+}
+
+float Fd_Burley(float NoV, float NoL, float LoH, float roughness) {
+    float f90 = 0.5 + 2.0 * roughness * LoH * LoH;
+    float lightScatter = F_Schlick(NoL, 1.0, f90);
+    float viewScatter = F_Schlick(NoV, 1.0, f90);
+    return lightScatter * viewScatter * (1.0 / PI);
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+[Listing [diffuseBRDF]: Implementation of the diffuse Disney BRDF in GLSL]
+
+Figure [lambert_vs_disney] shows a comparison between a simple Lambertian diffuse BRDF and the higher quality Disney diffuse BRDF, using a fully rough dielectric material. For comparison purposes, the right sphere was mirrored. The surface response is very similar with both BRDFs but the Disney one exhibits some nice retro-reflections at grazing angles (look closely at the left edge of the spheres).
+
+![Figure [lambert_vs_disney]: Comparison between the Lambertian diffuse BRDF (left) and the Disney diffuse BRDF (right)](images/diagram_lambert_vs_disney.png)
+
+We could allow artists/developers to choose the Disney diffuse BRDF depending on the quality they desire and the performance of the target device. It is important to note however that the Disney diffuse BRDF is not energy conserving as expressed here.
+
+## Standard model summary
+
+**Specular term**: a Cook-Torrance specular microfacet model, with a GGX normal distribution function, a Smith-GGX height-correlated visibility function, and a Schlick Fresnel function.
+
+**Diffuse term**: a Lambertian diffuse model.
+
+The full GLSL implementation of the standard model is shown in listing [glslBRDF].
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+float D_GGX(float NoH, float a) {
+    float a2 = a * a;
+    float f = (NoH * a2 - NoH) * NoH + 1.0;
+    return a2 / (PI * f * f);
+}
+
+vec3 F_Schlick(float u, vec3 f0) {
+    return f0 + (vec3(1.0) - f0) * pow(1.0 - u, 5.0);
+}
+
+float V_SmithGGXCorrelated(float NoV, float NoL, float a) {
+    float a2 = a * a;
+    float GGXL = NoV * sqrt((-NoL * a2 + NoL) * NoL + a2);
+    float GGXV = NoL * sqrt((-NoV * a2 + NoV) * NoV + a2);
+    return 0.5 / (GGXV + GGXL);
+}
+
+float Fd_Lambert() {
+    return 1.0 / PI;
+}
+
+void BRDF(...) {
+    vec3 h = normalize(v + l);
+
+    float NoV = abs(dot(n, v)) + 1e-5;
+    float NoL = clamp(dot(n, l), 0.0, 1.0);
+    float NoH = clamp(dot(n, h), 0.0, 1.0);
+    float LoH = clamp(dot(l, h), 0.0, 1.0);
+
+    // perceptually linear roughness to roughness (see parameterization)
+    float roughness = perceptualRoughness * perceptualRoughness;
+
+    float D = D_GGX(NoH, roughness);
+    vec3  F = F_Schlick(LoH, f0);
+    float V = V_SmithGGXCorrelated(NoV, NoL, roughness);
+
+    // specular BRDF
+    vec3 Fr = (D * V) * F;
+
+    // diffuse BRDF
+    vec3 Fd = diffuseColor * Fd_Lambert();
+
+    // apply lighting...
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+[Listing [glslBRDF]: Evaluation of the BRDF in GLSL]
+
+## Improving the BRDFs
+
+We mentioned in section [Energy conservation] that energy conservation is one of the key components of a good BRDF. Unfortunately the BRDFs explored previously suffer from two problems that we will examine below.
+
+### Energy gain in diffuse reflectance
+
+The Lambert diffuse BRDF does not account for the light that reflects at the surface and that is therefore not able to participate in the diffuse scattering event.
+
+[TODO: talk about the issue with fr+fd]
+
+### Energy loss in specular reflectance
+
+The Cook-Torrance BRDF we presented earlier attempts to model several events at the microfacet level but does so by accounting for a single bounce of light. This approximation can cause a loss of energy at high roughness, the surface is not energy preserving. Figure [singleVsMultiBounce] shows why this loss of energy occurs. In the single bounce (or single scattering) model, a ray of light hitting the surface can be reflected back onto another microfacet and thus be discarded because of the masking and shadowing term. If we however account for multiple bounces (multiscattering), the same ray of light might escape the microfacet field and be reflected back towards the viewer.
+
+![Figure [singleVsMultiBounce]: Single scattering (left) vs multiscattering](images/diagram_single_vs_multi_scatter.png)
+
+Based on this simple explanation, we can intuitively deduce that the rougher a surface is, the higher the chances are that energy gets lost because of the failure to account for multiple scattering events. This loss of energy appears to darken rough materials. Metallic surfaces are particularly affected because all of their reflectance is specular. This darkening effect is illustrated in figure [metallicRoughEnergyLoss]. With multiscattering, energy preservation can be achieved, as shown in figure [metallicRoughEnergyPreservation].
+
+![Figure [metallicRoughEnergyLoss]: Darkening increases with roughness due to single scattering](images/material_metallic_energy_loss.png)
+
+![Figure [metallicRoughEnergyPreservation]: Energy preservation with multiscattering](images/material_metallic_energy_preservation.png)
+
+We can use a white furnace, a uniform lighting environment set to pure white, to validate the energy preservation property of a BRDF. When energy preservation is achieved, a purely reflective metallic surface ($\fNormal = 1$) should be indistinguishable from the background, no matter the roughness of said surface. Figure [whiteFurnaceLoss] shows what such a surface looks like with the specular BRDF presented in the previous sections. The loss of energy as the roughness increases is obvious. In contrast, figure [whiteFurnacePreservation] shows that accounting for multiscattering events addresses the energy loss.
+
+![Figure [whiteFurnaceLoss]: Darkening increases with roughness due to single scattering](images/material_furnace_energy_loss.png)
+
+![Figure [whiteFurnacePreservation]: Energy preservation with multiscattering](images/material_furnace_energy_preservation.png)
+
+Multiple-scattering microfacet BRDFs are discussed in depth in [#Heitz16]. Unfortunately this paper only presents a stochastic evaluation of the multiscattering BRDF. This solution is therefore not suitable for real-time rendering. Kulla and Conty present a different approach in [#Kulla17]. Their idea is to add an energy compensation term as an additional BRDF lobe shown in equation $\ref{energyCompensationLobe}$:
+
+$$\begin{equation}\label{energyCompensationLobe}
+f_{ms}(l,v) = \frac{(1 - E(l)) (1 - E(v)) F_{avg}^2 E_{avg}}{\pi (1 - E_{avg}) (1 - F_{avg}(1 - E_{avg}))}
+\end{equation}$$
+
+Where $E$ is the directional albedo of the specular BRDF $f_r$, with $\fNormal$ set to 1:
+
+$$\begin{equation}
+E(l) = \int_{\Omega} f(l,v) (\NoV) dv
+\end{equation}$$
+
+The term $E_{avg}$ is the cosine-weighted average of $E$:
+
+$$\begin{equation}
+E_{avg} = 2 \int_0^1 E(\mu) \mu d\mu
+\end{equation}$$
+
+Similarly, $F_{avg}$ is the cosine-weighted average of the Fresnel term:
+
+$$\begin{equation}
+F_{avg} = 2 \int_0^1 F(\mu) \mu d\mu
+\end{equation}$$
+
+Both terms $E$ and $E_{avg}$ can be precomputed and stored in lookup tables. while $F_{avg}$ can be greatly simplified when the Schlick approximation is used:
+
+$$\begin{equation}\label{averageFresnel}
+F_{avg} = \frac{1 + 20 \fNormal}{21}
+\end{equation}$$
+
+This new lobe is combined with the original single scattering lobe, previously noted $f_r$:
+
+$$\begin{equation}
+f_{r}(l,v) = f_{ss}(l,v) + f_{ms}(l,v)
+\end{equation}$$
+
+In [#Lagarde18], with credit to Emmanuel Turquin, Lagarde and Golubev make the observation that equation $\ref{averageFresnel}$ can be simplified to $\fNormal$. They also propose to apply energy compensation by adding a scaled GGX specular lobe:
+
+$$\begin{equation}\label{energyCompensation}
+f_{ms}(l,v) = \fNormal \frac{1 - E(l)}{E(l)} f_{ss}(l,v)
+\end{equation}$$
+
+The key insight is that $E(l)$ can not only be precomputed but also shared with image-based lighting pre-integration. The multiscattering energy compensation formula thus becomes:
+
+$$\begin{equation}\label{scaledEnergyCompensationLobe}
+f_r(l,v) = f_{ss}(l,v) + \fNormal \left( \frac{1}{r} - 1 \right) f_{ss}(l,v)
+\end{equation}$$
+
+Where $r$ is defined as:
+
+$$\begin{equation}
+r = \int_{\Omega} D(l,v) V(l,v) \left< \NoL \right> dl
+\end{equation}$$
+
+We can implement specular energy compensation at a negligible cost if we store $r$ in the DFG lookup table presented in section [Image based lights]. Listing [energyCompensationImpl] shows that the implementation is a direct conversion of equation $\ref{scaledEnergyCompensationLobe}$.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+vec3 energyCompensation = 1.0 + f0 * (1.0 / dfg.y - 1.0);
+// Scale the specular lobe to account for multiscattering
+Fr *= pixel.energyCompensation;
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+[Listing [energyCompensationImpl]: Implementation of the energy compensation specular lobe]
+
+Please refer to section [Image based lights] and section [Pre-integration for multiscattering] to learn how the DFG lookup table is derived and computed.
+
+## Parameterization
+
+Disney's material model described in [#Burley12] is a good starting point but its numerous parameters makes it impractical for real-time implementations. In addition, we would like our standard material model to be easy to understand and easy to use for both artists and developers.
+
+### Standard parameters
+
+Table [standardParameters] describes the list of parameters that satisfy our constraints.
+
+
+       Parameter      |      Definition
+---------------------:|:---------------------
+**BaseColor**         | Diffuse albedo for non-metallic surfaces, and specular color for metallic surfaces
+**Metallic**          | Whether a surface appears to be dielectric (0.0) or conductor (1.0). Often used as a binary value (0 or 1)
+**Roughness**         | Perceived smoothness (0.0) or roughness (1.0) of a surface. Smooth surfaces exhibit sharp reflections
+**Reflectance**       | Fresnel reflectance at normal incidence for dielectric surfaces. This replaces an explicit index of refraction
+**Emissive**          | Additional diffuse albedo to simulate emissive surfaces (such as neons, etc.) This parameter is mostly useful in an HDR pipeline with a bloom pass
+**Ambient occlusion** | 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. This parameter will be discussed in more details in the lighting section
+[Table [standardParameters]: Parameters of the standard model]
+
+Figure [material_parameters] shows how the metallic, roughness and reflectance parameters affect the appearance of a surface.
+
+![Figure [material_parameters]: From top to bottom: varying metallic, varying dielectric roughness, varying metallic roughness, varying reflectance](images/material_parameters.png)
+
+### Types and ranges
+
+It is important to understand the type and range of the different parameters of our material model, described in table [standardParametersTypes].
+
+
+       Parameter      |    Type and range
+---------------------:|:---------------------
+**BaseColor**         | Linear RGB [0..1]
+**Metallic**          | Scalar [0..1]
+**Roughness**         | Scalar [0..1]
+**Reflectance**       | Scalar [0..1]
+**Emissive**          | Linear RGB [0..1] + exposure compensation
+**Ambient occlusion** | Scalar [0..1]
+[Table [standardParametersTypes]: Range and type of the standard model's parameters]
+
+Note that the types and ranges described here are what the shader will expect. The API and/or tools UI could and should allow to specify the parameters using other types and ranges when they are more intuitive for artists.
+
+For instance, the base color could be expressed in sRGB space and converted to linear space before being sent off to the shader. It can also be useful for artists to express the metallic, roughness and reflectance parameters as gray values between 0 and 255 (black to white).
+
+Another example: the emissive parameter could be expressed as a color temperature and an intensity, to simulate the light emitted by a black body.
+
+### Remapping
+
+To make the standard material model easier and more intuitive to use for artists, we must remap the parameters _baseColor_, _roughness_ and _reflectance_.
+
+#### Base color remapping
+
+The base color of a material is affected by the "metallicness" of said material. Dielectrics have achromatic specular reflectance but retain their base color as the diffuse color. Conductors on the other hand use their base color as the specular color and do not have a diffuse component.
+
+The lighting equations must therefore use the diffuse color and $\fNormal$ instead of the base color. The diffuse color can easily be computed from the base color, as show in listing [baseColorToDiffuse].
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+vec3 diffuseColor = (1.0 - metallic) * baseColor.rgb;
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+[Listing [baseColorToDiffuse]: Conversion of base color to diffuse in GLSL]
+
+#### Reflectance remapping
+
+**Dielectrics**
+
+The Fresnel term relies on $\fNormal$, the specular reflectance at normal incidence angle, and is achromatic for dielectrics. We will use the remapping for dielectric surfaces described in [#Lagarde14] :
+
+$$\begin{equation}
+\fNormal = 0.16 \cdot reflectance^2
+\end{equation}$$
+
+The goal is to map $\fNormal$ onto a range that can represent the Fresnel values of both common dielectric surfaces (4% reflectance) and gemstones (8% to 16%). The mapping function is chosen to yield a 4% Fresnel reflectance value for an input reflectance of 0.5 (or 128 on a linear RGB gray scale). Figure [reflectance] show those common values and how they relate to the mapping function.
+
+![Figure [reflectance]: Common reflectance values](images/diagram_reflectance.png)
+
+If the index of refraction is known (for instance, an air-water interface has an IOR of 1.33), the Fresnel reflectance can be calculated as follows:
+
+$$\begin{equation}\label{fresnelEquation}
+\fNormal(n_{ior}) = \frac{(\nior - 1)^2}{(\nior + 1)^2}
+\end{equation}$$
+
+And if the reflectance value is known, we can compute the corresponding IOR:
+
+$$\begin{equation}
+n_{ior} = \frac{2}{1 - \sqrt{\fNormal}} - 1 
+\end{equation}$$
+
+Table [commonMatReflectance] describes acceptable Fresnel reflectance values for various types of materials (no real world material has a value under 2%).
+
+
+          Material         |    Reflectance   |        IOR       |   Linear value
+--------------------------:|:-----------------|:-----------------|:----------------
+Water                      | 2%               | 1.33             | 0.35
+Fabric                     | 4% to 5.6%       | 1.5 to 1.62      | 0.5 to 0.59
+Common liquids             | 2% to 4%         | 1.33 to 1.5      | 0.35 to 0.5
+Common gemstones           | 5% to 16%        | 1.58 to 2.33     | 0.56 to 1.0
+Plastics, glass            | 4% to 5%         | 1.5 to 1.58      | 0.5 to 0.56
+Other dielectric materials | 2% to 5%         | 1.33 to 1.58     | 0.35 to 0.56
+Eyes                       | 2.5%             | 1.38             | 0.39
+Skin                       | 2.8%             | 1.4              | 0.42
+Hair                       | 4.6%             | 1.55             | 0.54
+Teeth                      | 5.8%             | 1.63             | 0.6
+Default value              | 4%               | 1.5              | 0.5
+[Table [commonMatReflectance]: Reflectance of common materials (source: Real-Time Rendering 4th Edition)]
+
+Table [fNormalMetals] lists the $\fNormal$ values for a few metals. The values are given in sRGB and must be used as the base color in our material model. Please refer to the annex, section [Specular color], for an explanation of how these sRGB colors are computed from measured data.
+
+
+    Metal  | $\fNormal$ in sRGB  |  Hexadecimal |               Color
+----------:|:-------------------:|:------------:|-------------------------------------------------------
+Silver     | 0.97, 0.96, 0.91    | #f7f4e8     | <div style="background-color: #f7f4e8; width: 60px">&nbsp;</div>
+Aluminum   | 0.91, 0.92, 0.92    | #e8eaea     | <div style="background-color: #e8eaea; width: 60px">&nbsp;</div>
+Titanium   | 0.76, 0.73, 0.69    | #c1baaf     | <div style="background-color: #c1baaf; width: 60px">&nbsp;</div>
+Iron       | 0.77, 0.78, 0.78    | #c4c6c6     | <div style="background-color: #c4c6c6; width: 60px">&nbsp;</div>
+Platinum   | 0.83, 0.81, 0.78    | #d3cec6     | <div style="background-color: #d3cec6; width: 60px">&nbsp;</div>
+Gold       | 1.00, 0.85, 0.57    | #ffd891     | <div style="background-color: #ffd891; width: 60px">&nbsp;</div>
+Brass      | 0.98, 0.90, 0.59    | #f9e596     | <div style="background-color: #f9e596; width: 60px">&nbsp;</div>
+Copper     | 0.97, 0.74, 0.62    | #f7bc9e     | <div style="background-color: #f7bc9e; width: 60px">&nbsp;</div>
+[Table [fNormalMetals]: $\fNormal$ for common metals]
+
+All materials have a Fresnel reflectance of 100% at grazing angles so we will set $\fGrazing$ in the following way when evaluating the specular BRDF $\fSpecular$:
+
+$$\begin{equation}
+\fGrazing = 1.0
+\end{equation}$$
+
+Figure [grazing_reflectance] shows a red plastic ball. If you look closely at the edges of the sphere, you will be able to notice the achromatic specular reflectance at grazing angles.
+
+![Figure [grazing_reflectance]: The specular reflectance becomes achromatic at grazing angles](images/material_grazing_reflectance.png)
+
+**Conductors**
+
+The specular reflectance of metallic surfaces is chromatic:
+
+$$\begin{equation}
+\fNormal = baseColor \cdot metallic
+\end{equation}$$
+
+Listing [fNormal] shows how $\fNormal$ is computed for both dielectric and metallic materials. It shows that the color of the specular reflectance is derived from the base color in the metallic case.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+vec3 f0 = 0.16 * reflectance * reflectance * (1.0 - metallic) + baseColor * metallic;
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+[Listing [fNormal]: Computing $\fNormal$ for dielectric and metallic materials in GLSL]
+
+#### Roughness remapping and clamping
+
+The roughness set by the user, called `perceptualRoughness` here, is remapped to a perceptually linear range using the following formulation:
+
+$$\begin{equation}
+\alpha = perceptualRoughness^2
+\end{equation}$$
+
+Figure [roughness_remap] shows a silver metallic surface with increasing roughness (from 0.0 to 1.0), using the unmodified roughness value (bottom) and the remapped value (top).
+
+![Figure [roughness_remap]: Roughness remapping comparison: perceptually linear roughness (top) and roughness (bottom)](images/material_roughness_remap.png)
+
+Using this visual comparison, it is obvious that the remapped roughness is easier to understand by artists and developers. Without this remapping, shiny metallic surfaces would have to be confined to a very small range between 0.0 and 0.05.
+
+Brent Burley made similar observations in his presentation [#Burley12]. After experimenting with other remappings (cubic and quadratic mappings for instance), we have reached the conclusion that this simple square remapping delivers visually pleasing and intuitive results while being cheap for real-time applications.
+
+Last but not least, it is important to note that the roughness parameters is used in various computations at runtime where limited floating point precision can become an issue. For instance, _mediump_ precision floats are often implemented as half-floats (fp16) on mobile GPUs.
+
+This cause problems when computing small values like $\frac{1}{perceptualRoughness^4}$ in our lighting equations (roughness squared in the GGX computation). The smallest value that can be represented as a half-float is $2^{-14}$ or $6.1 \times 10^{-5}$. To avoid divisions by 0 on devices that do not support denormals, the result of $\frac{1}{roughness^4}$ must therefore not be lower than $6.1 \times 10^{-5}$. To do so, we must clamp the roughness to 0.089, which gives us $6.274 \times 10^{-5}$. 
+
+Denormals should also be avoided to prevent performance drops. The roughness can also not be set to 0 to avoid obvious divisions by 0.
+
+Since we also want specular highlights to have a minimum size (a roughness close to 0 creates almost invisible highlights), we should clamp the roughness to a safe range in the shader. This clamping has the added benefit of correcting specular aliasing[^frostbiteRoughnessClamp] that can appear for low roughness values.
+
+[^frostbiteRoughnessClamp]: The Frostbite engine clamps the roughness of analytical lights to 0.045 to reduce specular aliasing. This is possible when using single precision floats (fp32).
+
+### Blending and layering
+
+As noted in [#Burley12] and [#Neubelt13], this model allows for robust blending between different materials by simply interpolating the different parameters. In particular, this allows to layer different materials using simple masks.
+
+For instance, figure [materialBlending] shows how the studio Ready at Dawn used material blending and layering in _The Order: 1886_ to create complex appearances from a library of simple materials (gold, copper, wood, rust, etc.).
+
+![Figure [materialBlending]: Material blending and layering. Source: Ready at Dawn Studios](images/material_blending.png)
+
+The blending and layering of materials is effectively an interpolation of the various parameters of the material model. Figure [material_interpolation] show an interpolation between shiny metallic chrome and rough red plastic. While the intermediate blended materials make little physical sense, they look plausible.
+
+![Figure [material_interpolation]: Interpolation from shiny chrome (left) to rough red plastic (right)](images/material_interpolation.png)
+
+### Crafting physically based materials
+
+Designing physically based materials is fairly easy once you understand the nature of the four main parameters: base color, metallic, roughness and reflectance.
+
+We provide a [useful chart/reference guide](./Material%20Properties.pdf) to help artists and developers craft their own physically based materials.
+
+![Crafting physically based materials](images/material_chart.jpg)
+
+In addition, here is a quick summary of how to use our material model:
+
+All materials
+:   **Base color** should be devoid of lighting information, except for micro-occlusion.
+
+    **Metallic** is almost a binary value. Pure conductors have a metallic value of 1 and pure dielectrics have a metallic value of 0. You should try to use values close at or close to 0 and 1. Intermediate values are meant for transitions between surface types (metal to rust for instance).
+
+Non-metallic materials
+:   **Base color** represents the reflected color and should be an sRGB value in the range 50-240 (strict range) or 30-240 (tolerant range).
+
+    **Metallic** should be 0 or close to 0.
+
+    **Reflectance** should be set to 127 sRGB (0.5 linear, 4% reflectance) if you cannot find a proper value. Do not use values under 90 sRGB (0.35 linear, 2% reflectance).
+
+Metallic materials
+:   **Base color** represents both the specular color and reflectance. Use values with a luminosity of 67% to 100% (170-255 sRGB). Oxidized or dirty metals should use a lower luminosity than clean metals to take into account the non-metallic components.
+
+    **Metallic** should be 1 or close to 1.
+
+    **Reflectance** is ignored (calculated from the base color).
+
+## Clear coat model
+
+The standard material model described previously is a good fit for isotropic surfaces made of a single layer. Multi-layer materials are unfortunately fairly common, particularly materials with a thin translucent layer over a standard layer. Real world examples of such materials include car paints, soda cans, lacquered wood, acrylic, etc.
+
+![Figure [materialClearCoat]: Comparison of a blue metallic surface under the standard material model (left) and the clear coat model (right)](images/material_clear_coat.png)
+
+A clear coat layer can be simulated as an extension of the standard material model by adding a second specular lobe, which implies evaluating a second specular BRDF. To simplify the implementation and parameterization, the clear coat layer will always be isotropic and dielectric. The base layer can be anything allowed by the standard model (dielectric or conductor).
+
+Since incoming light will traverse the clear coat layer, we must also take the loss of energy into account as shown in figure [clearCoatModel]. Our model will however not simulate inter reflection and refraction behaviors.
+
+![Figure [clearCoatModel]: Clear coat surface model](images/diagram_clear_coat.png)
+
+### Clear coat specular BRDF
+
+The clear coat layer will be modeled using the same Cook-Torrance microfacet BRDF used in the standard model. Since the clear coat layer is always isotropic and dielectric, with low roughness values (see section [Clear coat parameterization]), we can choose cheaper DFG terms without notably sacrificing visual quality.
+
+A survey of the terms listed in [#Karis13a] and [#Burley12] shows that the Fresnel and NDF terms we already use in the standard model are not computationally more expensive than other terms. [#Kelemen01] describes a much simpler term that can replace our Smith-GGX visibility term:
+
+$$\begin{equation}
+V(l,h) = \frac{1}{4(\LoH)^2}
+\end{equation}$$
+
+This masking-shadowing function is not physically based, as shown in [#Heitz14], but its simplicity makes it desirable for real-time rendering.
+
+In summary, our clear coat BRDF is a Cook-Torrance specular microfacet model, with a GGX normal distribution function, a Kelemen visibility function, and a Schlick Fresnel function. Listing [kelemen] shows how trivial the GLSL implementation is.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+float V_Kelemen(float LoH) {
+    return 0.25 / (LoH * LoH);
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+[Listing [kelemen]: Implementation of the Kelemen visibility term in GLSL]
+
+**Note on the Fresnel term**
+
+The Fresnel term of the specular BRDF requires $\fNormal$, the specular reflectance at normal incidence angle. This parameter can be computed from an index of refraction of an interface. We will assume that our clear coat layer is made of polyurethane, a common compound [used in coatings and varnishes](https://en.wikipedia.org/wiki/List_of_polyurethane_applications#Varnish), or similar. An air-polyurethane interface [has an IOR of 1.5](http://www.clearpur.com/transparent-polyurethanes/), from which we can deduce $\fNormal$:
+
+$$\begin{equation}
+\fNormal(1.5) = \frac{(1.5 - 1)^2}{(1.5 + 1)^2} = 0.04
+\end{equation}$$
+
+This corresponds to a Fresnel reflectance of 4% that we know is associated with common dielectric materials.
+
+### Integration in the surface response
+
+Because we must take into account the loss of energy caused by the addition of the clear coat layer, we can reformulate the BRDF from equation $\ref{brdf}$ thusly:
+
+$$\begin{equation}
+f(v,l)=\fDiffuse(v,l) (1 - F_c) + \fSpecular(v,l) (1 - F_c) + f_c(v,l)
+\end{equation}$$
+
+Where $F_c$ is the Fresnel term of the clear coat BRDF and $f_c$ the clear coat BRDF 
+
+### Clear coat parameterization
+
+The clear coat material model encompasses all the parameters previously defined for the standard material mode, plus two parameters described in table [clearCoatParameters].
+
+
+        Parameter      |      Definition
+----------------------:|:---------------------
+**ClearCoat**          | Strength of the clear coat layer. Scalar between 0 and 1
+**ClearCoatRoughness** | Perceived smoothness or roughness of the clear coat layer. Scalar between 0 and 1
+[Table [clearCoatParameters]: Clear coat model parameters]
+
+The clear coat roughness parameter is remapped and clamped in a similar way to the roughness parameter of the standard material.
+
+Figure [clearCoat] and figure [clearCoatRoughness] show how the clear coat parameters affect the appearance of a surface.
+
+![Figure [clearCoat]: Clear coat varying from 0.0 (left) to 1.0 (right) with metallic set to 1.0 and roughness to 0.8](images/material_clear_coat1.png)
+
+![Figure [clearCoatRoughness]: Clear coat roughness varying from 0.0 (left) to 1.0 (right) with metallic set to 1.0, roughness to 0.8 and clear coat to 1.0](images/material_clear_coat2.png)
+
+Listing [clearCoatBRDF] shows the GLSL implementation of the clear coat material model after remapping, parameterization and integration in the standard surface response.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+void BRDF(...) {
+    // compute Fd and Fr from standard model
+
+    // remapping and linearization of clear coat roughness
+    clearCoatPerceptualRoughness = clamp(clearCoatPerceptualRoughness, 0.089, 1.0);
+    clearCoatRoughness = clearCoatPerceptualRoughness * clearCoatPerceptualRoughness;
+
+    // clear coat BRDF
+    float  Dc = D_GGX(clearCoatRoughness, NoH);
+    float  Vc = V_Kelemen(clearCoatRoughness, LoH);
+    float  Fc = F_Schlick(0.04, LoH) * clearCoat; // clear coat strength
+    float Frc = (Dc * Vc) * Fc;
+
+    // account for energy loss in the base layer
+    return color * ((Fd + Fr * (1.0 - Fc)) * (1.0 - Fc) + Frc);
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+[Listing [clearCoatBRDF]: Implementation of the clear coat BRDF in GLSL]
+
+### Base layer modification
+
+The presence of a clear coat layer means that we should recompute $\fNormal$, since it is normally based on an air-material interface. The base layer thus requires $\fNormal$ to be computed based on a clear coat-material interface instead.
+
+This can be achieved by computing the material's index of refraction (IOR) from $\fNormal$, then computing a new $\fNormal$ based on the newly computed IOR and the IOR of the clear coat layer (1.5).
+
+First, we compute the base layer's IOR:
+
+$$
+IOR_{base} = \frac{1 + \sqrt{\fNormal}}{1 - \sqrt{\fNormal}}
+$$
+
+Then we compute the new $\fNormal$ from this new index of refraction:
+
+$$
+f_{0_{base}} = \left( \frac{IOR_{base} - 1.5}{IOR_{base} + 1.5} \right) ^2
+$$
+
+Since the clear coat layer's IOR is fixed, we can combine both steps to simplify:
+
+$$
+f_{0_{base}} = \frac{\left( 1 - 5 \sqrt{\fNormal} \right) ^2}{\left( 5 - \sqrt{\fNormal} \right) ^2}
+$$
+
+We should also modify the base layer's apparent roughness based on the IOR of the clear coat layer but this is something we have opted to leave out for now.
+
+## Anisotropic model
+
+The standard material model described previously can only describe isotropic surfaces, that is, surfaces whose properties are identical in all directions. Many real-world materials, such as brushed metal, can, however, only be replicated using an anisotropic model.
+
+![Figure [anisotropic]: Comparison of isotropic material (left) and anisotropic material (right)](images/material_anisotropic.png)
+
+### Anisotropic specular BRDF
+
+The isotropic specular BRDF described previously can be modified to handle anisotropic materials. Burley achieves this by using an anisotropic GGX NDF:
+
+$$\begin{equation}
+D_{aniso}(h,\alpha) = \frac{1}{\pi \alpha_t \alpha_b} \frac{1}{((\frac{t \cdot h}{\alpha_t})^2 + (\frac{b \cdot h}{\alpha_b})^2 + (\NoH)^2)^2}
+\end{equation}$$
+
+This NDF unfortunately relies on two supplemental roughness terms noted $\alpha_b$, the roughness along the bitangent direction, and $\alpha_t$, the roughness along the tangent direction. Neubelt and Pettineo [#Neubelt13] propose a way to derive $\alpha_b$ from $\alpha_t$ by using an _anisotropy_ parameter that describes the relationship between the two roughness values for a material:
+
+$$
+\begin{align*}
+  \alpha_t &= \alpha \\
+  \alpha_b &= lerp(0, \alpha, 1 - anisotropy)
+\end{align*}
+$$
+
+The relationship defined in [#Burley12] is different, offers more pleasant and intuitive results, but is slightly more expensive:
+
+$$
+\begin{align*}
+  \alpha_t &= \frac{\alpha}{\sqrt{1 - 0.9 \times anisotropy}} \\
+  \alpha_b &= \alpha \sqrt{1 - 0.9 \times anisotropy}
+\end{align*}
+$$
+
+We instead opted to follow the relationship described in [#Kulla17] as it allows creation of sharp highlights:
+
+$$
+\begin{align*}
+  \alpha_t &= \alpha \times (1 + anisotropy) \\
+  \alpha_b &= \alpha \times (1 - anisotropy)
+\end{align*}
+$$
+
+Note that this NDF requires the tangent and bitangent directions in addition to the normal direction. Since these directions are already needed for normal mapping, providing them may not be an issue.
+
+The resulting implementation is described in listing [anisotropicBRDF].
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+float at = max(roughness * (1.0 + anisotropy), 0.001);
+float ab = max(roughness * (1.0 - anisotropy), 0.001);
+
+float D_GGX_Anisotropic(float NoH, const vec3 h,
+        const vec3 t, const vec3 b, float at, float ab) {
+    float ToH = dot(t, h);
+    float BoH = dot(b, h);
+    float a2 = at * ab;
+    highp vec3 v = vec3(ab * ToH, at * BoH, a2 * NoH);
+    highp float v2 = dot(v, v);
+    float w2 = a2 / v2;
+    return a2 * w2 * w2 * (1.0 / PI);
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+[Listing [anisotropicBRDF]: Implementation of Burley's anisotropic NDF in GLSL]
+
+In addition, [#Heitz14] presents an anisotropic masking-shadowing function to match the height-correlated GGX distribution. The masking-shadowing term can be greatly simplified by using the visibility function instead:
+
+$$\begin{equation}
+G(v,l,h,\alpha) = \frac{\chi^+(\VoH) \chi^+(\LoH)}{1 + \Lambda(v) + \Lambda(l)}
+\end{equation}$$
+
+$$\begin{equation}
+\Lambda(m) = \frac{-1 + \sqrt{1 + \alpha_0^2 tan^2(\theta_m)}}{2} = \frac{-1 + \sqrt{1 + \alpha_0^2 \frac{(1 - cos^2(\theta_m))}{cos^2(\theta_m)}}}{2}
+\end{equation}$$
+
+Where:
+
+$$\begin{equation}
+\alpha_0 = \sqrt{cos^2(\phi_0)\alpha_x^2 + sin^2(\phi_0)\alpha_y^2}
+\end{equation}$$
+
+After derivation we obtain:
+
+$$\begin{equation}
+V_{aniso}(\NoL,\NoV,\alpha) = \frac{1}{2((\NoL)\hat{\Lambda}_v+(\NoV)\hat{\Lambda}_l)} \\
+\hat{\Lambda}_v = \sqrt{\alpha^2_t(t \cdot v)^2+\alpha^2_b(b \cdot v)^2+(\NoV)^2} \\
+\hat{\Lambda}_l = \sqrt{\alpha^2_t(t \cdot l)^2+\alpha^2_b(b \cdot l)^2+(\NoL)^2}
+\end{equation}$$
+
+The term $ \hat{\Lambda}_v $ is the same for every light and can be computed only once if needed. The resulting implementation is described in listing [anisotropicV].
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+float at = max(roughness * (1.0 + anisotropy), 0.001);
+float ab = max(roughness * (1.0 - anisotropy), 0.001);
+
+float V_SmithGGXCorrelated_Anisotropic(float at, float ab, float ToV, float BoV,
+        float ToL, float BoL, float NoV, float NoL) {
+    float lambdaV = NoL * length(vec3(at * ToV, ab * BoV, NoV));
+    float lambdaL = NoV * length(vec3(at * ToL, ab * BoL, NoL));
+    float v = 0.5 / (lambdaV + lambdaL);
+    return saturateMediump(v);
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+[Listing [anisotropicV]: Implementation of the anisotropic visibility function in GLSL]
+
+### Anisotropic parameterization
+
+The anisotropic material model encompasses all the parameters previously defined for the standard material mode, plus an extra parameter described in table [anisotropicParameters].
+
+
+        Parameter      |      Definition
+----------------------:|:---------------------
+**Anisotropy**         | Amount of anisotropy. Scalar between -1 and 1
+[Table [anisotropicParameters]: Anisotropic model parameters]
+
+No further remapping is required. Note that negative values will align the anisotropy with the bitangent direction instead of the tangent direction. Figure [anisotropyParameter] shows how the anisotropy parameter affect the appearance of a rough metallic surface.
+
+![Figure [anisotropyParameter]: Anisotropy varying from 0.0 (left) to 1.0 (right)](images/materials/anisotropy.png)
+
+## Subsurface model
+
+[TODO]
+
+### Subsurface specular BRDF
+
+[TODO]
+
+### Subsurface parameterization
+
+[TODO]
+
+## Cloth model
+
+All the material models described previously are designed to simulate dense surfaces, both at a macro and at a micro level. Clothes and fabrics are however often made of loosely connected threads that absorb and scatter incident light. The microfacet BRDFs presented earlier do a poor job of recreating the nature of cloth due to their underlying assumption that a surface is made of random grooves that behave as perfect mirrors. When compared to hard surfaces, cloth is characterized by a softer specular lobe with a large falloff and the presence of fuzz lighting, caused by forward/backward scattering. Some fabrics also exhibit two-tone specular colors (velvets for instance).
+
+Figure [materialCloth] shows how a traditional microfacet BRDF fails to capture the appearance of a sample of denim fabric. The surface appears rigid (almost plastic-like), more similar to a tarp than a piece of clothing. This figure also shows how important the softer specular lobe caused by absorption and scattering is to the faithful recreation of the fabric.
+
+![Figure [materialCloth]: Comparison of denim fabric rendered using a traditional microfacet BRDF (left) and our cloth BRDF (right)](images/screenshot_cloth.png)
+
+Velvet is an interesting use case for a cloth material model. As shown in figure [materialVelvet] this type of fabric exhibits strong rim lighting due to forward and backward scattering. These scattering events are caused by fibers standing straight at the surface of the fabric. When the incident light comes from the direction opposite to the view direction, the fibers will forward-scatter the light. Similarly, when the incident light from the same direction as the view direction, the fibers will scatter the light backward.
+
+![Figure [materialVelvet]: Velvet fabric showcasing forward and backward scattering](images/screenshot_cloth_velvet.png)
+
+Since fibers are flexible, we should in theory model the ability to groom the surface. While our model does not replicate this characteristic, it does model a visible front facing specular contribution that can be attributed to the random variance in the direction of the fibers.
+
+It is important to note that there are types of fabrics that are still best modeled by hard surface material models. For instance, leather, silk and satin can be recreated using the standard or anisotropic material models.
+
+### Cloth specular BRDF
+
+The cloth specular BRDF we use is a modified microfacet BRDF as described by Ashikhmin and Premoze in [#Ashikhmin07]. In their work, Ashikhmin and Premoze note that the distribution term is what contributes most to a BRDF and that the shadowing/masking term is not necessary for their velvet distribution. The distribution term itself is an inverted Gaussian distribution. This helps achieve fuzz lighting (forward and backward scattering) while an offset is added to simulate the front facing specular contribution. The so-called velvet NDF is defined as follows:
+
+$$\begin{equation}
+D_{velvet}(v,h,\alpha) = c_{norm}(1 + 4 exp\left(\frac{-{cot}^2\theta_{h}}{\alpha^2}\right))
+\end{equation}$$
+
+This NDF is a variant of the NDF the same authors describe in [#Ashikhmin00], notably modified to include an offset (set to 1 here) and an amplitude (4). In [#Neubelt13], Neubelt and Pettineo propose a normalized version of this NDF:
+
+$$\begin{equation}
+D_{velvet}(v,h,\alpha) = \frac{1}{\pi(1 + 4\alpha^2)} (1 + 4 \frac{exp\left(\frac{-{cot}^2\theta_{h}}{\alpha^2}\right)}{{sin}^4\theta_{h}})
+\end{equation}$$
+
+For the full specular BRDF, we also follow [#Neubelt13] and replace the traditional denominator with a smoother variant:
+
+$$\begin{equation}\label{clothSpecularBRDF}
+f_{r}(v,h,\alpha) = \frac{D_{velvet}(v,h,\alpha)}{4(\NoL + \NoV - (\NoL)(\NoV))}
+\end{equation}$$
+
+The implementation of the velvet NDF is presented in listing [clothBRDF], optimized to properly fit in half float formats and to avoid computing a costly cotangent, relying instead on trigonometric identities. Note that we removed the Fresnel component from this BRDF.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+float D_Ashikhmin(float roughness, float NoH) {
+    // Ashikhmin 2007, "Distribution-based BRDFs"
+	float a2 = roughness * roughness;
+	float cos2h = NoH * NoH;
+	float sin2h = max(1.0 - cos2h, 0.0078125); // 2^(-14/2), so sin2h^2 > 0 in fp16
+	float sin4h = sin2h * sin2h;
+	float cot2 = -cos2h / (a2 * sin2h);
+	return 1.0 / (PI * (4.0 * a2 + 1.0) * sin4h) * (4.0 * exp(cot2) + sin4h);
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+[Listing [clothBRDF]: Implementation of Ashikhmin's velvet NDF in GLSL]
+
+In [#Estevez17] Estevez and Kulla propose a different NDF (called the "Charlie" sheen) that is based on an exponentiated sinusoidal instead of an inverted Gaussian. This NDF is appealing for several reasons: its parameterization feels more natural and intuitive, it provides a softer appearance and, as shown in equation $\ref{charlieNDF}$, its implementation is simpler:
+
+$$\begin{equation}\label{charlieNDF}
+D(m) = \frac{(2 + \frac{1}{\alpha}) sin(\theta)^{\frac{1}{\alpha}}}{2 \pi}
+\end{equation}$$
+
+[#Estevez17] also presents a new shadowing term that we omit here because of its cost. We instead rely on the visibility term from [#Neubelt13] (shown in equation $\ref{clothSpecularBRDF}$ above).
+The implementation of this NDF is presented in listing [clothCharlieBRDF], optimized to properly fit in half float formats.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+float D_Charlie(float roughness, float NoH) {
+    // Estevez and Kulla 2017, "Production Friendly Microfacet Sheen BRDF"
+    float invAlpha  = 1.0 / roughness;
+    float cos2h = NoH * NoH;
+    float sin2h = max(1.0 - cos2h, 0.0078125); // 2^(-14/2), so sin2h^2 > 0 in fp16
+    return (2.0 + invAlpha) * pow(sin2h, invAlpha * 0.5) / (2.0 * PI);
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+[Listing [clothCharlieBRDF]: Implementation of the "Charlie" NDF in GLSL]
+
+#### Sheen color
+
+To offer better control over the appearance of cloth and to give users the ability to recreate two-tone specular materials, we introduce the ability to directly modify the specular reflectance. Figure [materialClothSheen] shows an example of using the parameter we call "sheen color".
+
+![Figure [materialClothSheen]: Blue fabric without (left) and with (right) sheen](images/screenshot_cloth_sheen.png)
+
+### Cloth diffuse BRDF
+
+Our cloth material model still relies on a Lambertian diffuse BRDF. It is however slightly modified to be energy conservative (akin to the energy conservation of our clear coat material model) and offers an optional subsurface scattering term. This extra term is not physically based and can be used to simulate the scattering, partial absorption and re-emission of light in certain types of fabrics.
+
+First, here is the diffuse term without the optional subsurface scattering:
+
+$$\begin{equation}
+f_{d}(v,h) = \frac{c_{diff}}{\pi}(1 - F(v,h))
+\end{equation}$$
+
+Where $F(v,h)$ is the Fresnel term of the cloth specular BRDF in equation $\ref{clothSpecularBRDF}$. In practice we've opted to leave out the $1 - F(v, h)$ term in the diffuse component. The effect is a bit subtle and we deemed it wasn't worth the added cost.
+
+Subsurface scattering is implemented using the wrapped diffuse lighting technique, in its energy conservative form:
+
+$$\begin{equation}
+f_{d}(v,h) = \frac{c_{diff}}{\pi}(1 - F(v,h)) \left< \frac{\NoL + w}{(1 + w)^2} \right> \left< c_{subsurface} + \NoL \right>
+\end{equation}$$
+
+Where $w$ is a value between 0 and 1 defining by how much the diffuse light should wrap around the terminator. To avoid introducing another parameter, we fix $w = 0.5$. Note that with wrap diffuse lighting, the diffuse term must not be multiplied by $\NoL$. The effect of this cheap
+subsurface scattering approximation can be seen in figure [materialClothSubsurface].
+
+![Figure [materialClothSubsurface]: White cloth (left column) vs white cloth with brown subsurface scattering (right)](images/screenshot_cloth_subsurface.png)
+
+The complete implementation of our cloth BRDF, including sheen color and optional subsurface scattering, can be found in listing [clothFullBRDF].
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+// specular BRDF
+float D = distributionCloth(roughness, NoH);
+float V = visibilityCloth(NoV, NoL);
+vec3  F = sheenColor;
+vec3 Fr = (D * V) * F;
+
+// diffuse BRDF
+float diffuse = diffuse(roughness, NoV, NoL, LoH);
+#if defined(MATERIAL_HAS_SUBSURFACE_COLOR)
+// energy conservative wrap diffuse
+diffuse *= saturate((dot(n, light.l) + 0.5) / 2.25);
+#endif
+vec3 Fd = diffuse * pixel.diffuseColor;
+
+#if defined(MATERIAL_HAS_SUBSURFACE_COLOR)
+// cheap subsurface scatter
+Fd *= saturate(subsurfaceColor + NoL);
+vec3 color = Fd + Fr * NoL;
+color *= (lightIntensity * lightAttenuation) * lightColor;
+#else
+vec3 color = Fd + Fr;
+color *= (lightIntensity * lightAttenuation * NoL) * lightColor;
+#endif
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+[Listing [clothFullBRDF]: Implementation of our cloth BRDF in GLSL]
+
+### Cloth parameterization
+
+The cloth material model encompasses all the parameters previously defined for the standard material mode except for _metallic_ and _reflectance_. Two extra parameters described in table [clothParameters] are also available.
+
+
+       Parameter      |      Definition
+---------------------:|:---------------------
+**SheenColor**        | Specular tint to create two-tone specular fabrics (defaults to 0.04 to match the standard reflectance)
+**SubsurfaceColor**   | Tint for the diffuse color after scattering and absorption through the material
+[Table [clothParameters]: Cloth model parameters]
+
+
+To create a velvet-like material, the base color can be set to black (or a dark color). Chromaticity information should instead be set on the sheen color. To create more common fabrics such as denim, cotton, etc. use the base color for chromaticity and use the default sheen color or set the sheen color to the luminance of the base color.
+
+# Lighting
+
+The correctness and coherence of the lighting environment is paramount to achieving plausible visuals. After surveying existing rendering engines (such as Unity or Unreal Engine 4) as well as the traditional real-time rendering literature, it is obvious that coherency is rarely achieved.
+
+The Unreal Engine, for instance, lets artists specify the "brightness" of a point light in lumens, a unit of luminous power. The brightness of directional lights is however expressed using an arbitrary unnamed unit. To match the brightness of a point light with a luminous power of 5,000 lumens, the artist must use a directional light of brightness 10. This kind of mismatch makes it difficult for artists to maintain the visual integrity of a scene when adding, removing or modifying lights.
+Using solely arbitrary units is a coherent solution but it makes reusing lighting rigs a difficult task. For instance, an outdoor scene will use a directional light of brightness 10 as the sun and all other lights will be defined relative to that value. Moving these lights to an indoor environment would make them too bright.
+
+Our goal is therefore to make all lighting correct by default, while giving artists enough freedom to achieve the desired look. We will support a number of lights, split in two categories, direct and indirect lighting:
+
+**Direct lighting**: punctual lights, photometric lights, area lights.
+
+**Indirect lighting**: image based lights (IBLs), for both local[^localProbesMobile] and distant light probes.
+
+[^localProbesMobile]: Local light probes might be too expensive to support on mobile, we will first focus our efforts on distant light probes set at infinity
+
+## Units
+
+The following sections will discuss how to implement various types of lights and the proposed equations make use of different symbols and units summarized in table [lightUnits].
+
+
+    Photometric term    |      Notation      |        Unit
+-----------------------:|:------------------:|:-----------------
+Luminous power          | $\Phi$             | Lumen ($lm$)
+Luminous intensity      | $I$                | Candela ($cd$) or $\frac{lm}{sr}$
+Illuminance             | $E$                | Lux ($lx$) or $\frac{lm}{m^2}$
+Luminance               | $L$                | Nit ($nt$) or $\frac{cd}{m^2}$
+Radiant power           | $\Phi_e$           | Watt ($W$)
+Luminous efficacy       | $\eta$             | Lumens per watt ($\frac{lm}{W}$)
+Luminous efficiency     | $V$                | Percentage (%)
+[Table [lightUnits]: Photometric units]
+
+To get properly coherent lighting, we must use light units that respect the ratio between various light intensities found in real-world scenes. These intensities can vary greatly, from around 800 $lm$ for a household light bulb to 120,000 $lx$ for a daylight sky and sun illumination.
+
+The easiest way to achieve lighting coherency is to adopt physical light units. This will in turn enable full reusability of lighting rigs. Using physical light units also allows us to use a physically based camera.
+
+Table [lightTypesUnits] shows the light unit associated with each type of light we intend to support.
+
+
+        Light type       |        Unit
+------------------------:|:---------------------
+Directional light        | Illuminance ($lx$ or $\frac{lm}{m^2}$)
+Point light              | Luminous power ($lm$)
+Spot light               | Luminous power ($lm$)
+Photometric light        | Luminous intensity ($cd$)
+Masked photometric light | Luminous power ($lm$)
+Area light               | Luminous power ($lm$)
+Image based light        | Luminance ($\frac{cd}{m^2}$)
+[Table [lightTypesUnits]: Intensity unity for each light type]
+
+**Notes about the radiant power unit**
+
+Even though commercially available light bulbs often display their brightness in lumens on the packaging, it is common to refer to the brightness of a light bulb by using its required energy in watts. The number of watts only indicates how much energy a bulb uses, not how bright it is. It is even more important to understand this difference now that more energy efficient bulbs are readily available (halogens, LEDs, etc.).
+
+However, since artists might be accustomed to gauging a light's brightness by its power, we should allow users to use the power unit to define the brightness of a light. The conversion is presented in equation $\ref{radiantPowerToLuminousPower}$.
+
+$$\begin{equation}\label{radiantPowerToLuminousPower}
+\Phi = \Phi_e \eta
+\end{equation}$$
+
+In equation $\ref{radiantPowerToLuminousPower}$, $\eta$ is the luminous efficacy of the light, expressed in lumens per watt. Knowing that the [maximum possible luminous efficacy](http://en.wikipedia.org/wiki/Luminous_efficacy) is 683 $\frac{lm}{W}$ we can also use luminous efficiency $V$ (also called luminous coefficient), as shown in equation $\ref{radiantPowerLuminousEfficiency}$.
+
+$$\begin{equation}\label{radiantPowerLuminousEfficiency}
+\Phi = \Phi_e 683 \times V
+\end{equation}$$
+
+Table [lightTypesEfficacy] can be used as a reference to convert watts to lumens using either the luminous efficacy or the luminous efficiency of various types of lights. More specific values are available on Wikipedia's [luminous efficacy](http://en.wikipedia.org/wiki/Luminous_efficacy) page.
+
+
+       Light type       |  Efficacy $\eta$   |  Efficiency $V$
+-----------------------:|:------------------:|:-----------------
+Incandescent            | 14-35              | 2-5%
+LED                     | 28-100             | 4-15%
+Fluorescent             | 60-100             | 9-15%
+[Table [lightTypesEfficacy]: Efficacy and efficiency of various light types]
+
+### Light units validation
+
+One of the big advantages of using physical light units is the ability to physically validate our equations. We can use specialized devices to measure three light units.
+
+#### Illuminance
+
+The illuminance reaching a surface can be measured using an incident light meter. For our tests, we use a [Sekonic L-478D](http://www.sekonic.com/products/l-478d/overview.aspx), shown in figure [sekonic].
+
+The incident light meter uses a white diffuse dome to capture the illuminance reaching a surface. It is important to orient the dome properly depending on the desired measurement. For instance, orienting the dome perpendicular to the sun on a bright clear day will give very different results than orienting the dome horizontally.
+
+![Figure [sekonic]: Sekonic L-478D incident light meter](images/photo_light_meter.jpg)
+
+#### Luminance
+
+The luminance at a surface, or the product of the incident light and the surface, can be measured using a luminance meter, also often called a spot meter. While incident light meters use a diffuse hemisphere to capture light from all directions, a spot meter uses a shield to measure incident light from a single direction. For our tests, we use a [Sekonic 5 degree Viewfinder](http://www.sekonic.com/products/l-478dr/accessories/np-finder-5-degree-for-l-478.aspx) that can replace the diffuser on the L-478D to measure luminance in a 5 degree cone.
+
+![Sekonic L-478D working as a luminance meter using a special viewfinder](images/photo_incident_light_meter.jpg)
+
+#### Luminous intensity
+
+The luminous intensity of a light source cannot be measured directly but can be derived from the measured illuminance if we know the distance between the measuring device and the light source. Equation $\ref{derivedLuminousIntensity}$ is a simple application of the inverse square law discussed in section [Punctual lights].
+
+$$\begin{equation}\label{derivedLuminousIntensity}
+I = E \cdot d^2
+\end{equation}$$
+
+## Direct lighting
+
+We have defined the light units for all the light types supported by the renderer in the section above but we have not defined the light unit for the result of the lighting equations. Choosing physical light units means that we will compute luminance values in our shaders, and therefore that all our light evaluation functions will compute the luminance $L_{out}$ (or outgoing radiance) at any given point. The luminance depends on the illuminance $E$ and the BSDF $f(v,l)$ :
+
+$$\begin{equation}\label{luminanceEquation}
+L_{out} = f(v,l)E
+\end{equation}$$
+
+### Directional lights
+
+The main purpose of directional lights is to recreate important light sources for outdoor environment, i.e. the sun and/or the moon. While directional lights do not truly exist in the physical world, any light source sufficiently far from the light receptor can be assumed to be directional (i.e. all the incident light rays are parallel, as shown in  figure [directionalLight]).
+
+![Figure [directionalLight]: Interaction between a directional light and a surface. The light source is a virtual construct that can only be represented by a direction](images/diagram_directional_light.png)
+
+This approximation proves to work incredibly well for the diffuse response of a surface but the specular response is incorrect. The Frostbite engine solves this problem by treating the "sun" directional light as a disc area light. However, our tests have shown that the quality increase does not justify the added computational costs.
+
+We earlier stated that we chose an illuminance light unit ($lx$) for directional lights. This is in part due to the fact that we can easily find illuminance values for the sky and the sun (online or with a light meter) but also to simplify the luminance equation described in $\ref{luminanceEquation}$.
+
+$$\begin{equation}\label{directionalLuminanceEquation}
+L_{out} = f(v,l) E_{\bot} \left< \NoL \right>
+\end{equation}$$
+
+In the simplified luminance equation $\ref{directionalLuminanceEquation}$, $E_{\bot}$ is the illuminance of the light source for a surface perpendicular to said light source. If the directional light source simulates the sun, $E_{\bot}$ is the illuminance of the sun for a surface perpendicular to the sun direction.
+
+Table [sunSkyIlluminance] provides useful reference values for the sun and sky illumination, measured[^illuminanceMeasures] on a clear day in March, in California.
+
+
+          Light            |   10am   |   12pm   |  5:30pm  
+--------------------------:|---------:|---------:|---------:
+$Sky_{\bot} + Sun_{\bot}$  | 120,000  | 130,000  | 90,000  
+$Sky_{\bot}$               | 20,000   | 25,000   | 9,000   
+$Sun_{\bot}$               | 100,000  | 105,000  | 81,000  
+[Table [sunSkyIlluminance]: Illuminance values in $lx$ (a full moon has an illuminance of 1 $lx$)]
+
+Dynamic directional lights are particularly cheap to evaluate at runtime, as shown in listing [glslDirectionalLight].
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+vec3 l = normalize(-lightDirection);
+float NoL = clamp(dot(n, l), 0.0, 1.0);
+
+// lightIntensity is the illuminance
+// at perpendicular incidence in lux
+float illuminance = lightIntensity * NoL;
+vec3 luminance = BSDF(v, l) * illuminance;
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+[Listing [glslDirectionalLight]: Implementation of directional lights in GLSL]
+
+Figure [directionalLightTest] shows the effect of lighting a simple scene with a directional light setup to approximate a midday Sun (illuminance set to 110,000 $lx$). For illustration purposes, only direct lighting is shown.
+
+![Figure [directionalLightTest]: Series of dielectric materials of varying roughness under a directional light](images/screenshot_directional_light.png)
+
+[^illuminanceMeasures]: Measurements taken with an incident light meter (Sekonic L-478D)
+
+### Punctual lights
+
+Our engine will support two types of punctual lights, commonly found in most if not all rendering engines: point lights and spot lights. These types of lights are traditionally physically inaccurate for two reasons:
+
+1. They are truly punctual and infinitesimally small.
+2. They do not follow the [inverse square law](http://en.wikipedia.org/wiki/Inverse-square_law).
+
+The first issue can be addressed with area lights but, given the cheaper nature of punctual lights it is deemed practical to use infinitesimally small punctual lights whenever possible.
+
+The second issue is easy to fix. For a given punctual light, the perceived intensity decreases proportionally to the square of the distance from the viewer (more precisely, the light receptor).
+
+For punctual lights following the inverse square law, the term $E$ of equation $ \ref{luminanceEquation} $ is expressed in equation $\ref{punctualLightEquation}$, where $d$ is the distance from a point at the surface to the light.
+
+$$\begin{equation}\label{punctualLightEquation}
+E = L_{in} \left< \NoL \right> = \frac{I}{d^2} \left< \NoL \right>
+\end{equation}$$
+
+The difference between point and spot lights lies in how $E$ is computed, and in particular how the luminous intensity $I$ is computed from the luminous power $\Phi$.
+
+#### Point lights
+
+A point light is defined only by a position in space, as shown in figure [pointLight].
+
+![Figure [pointLight]: Interaction between a point light and a surface. The attenuation only depends on the distance to the light](images/diagram_point_light.png)
+
+The luminous power of a point light is calculated by integrating the luminous intensity over the light's solid angle, as show in equation $\ref{pointLightLuminousPower}$. The luminous intensity can then be easily derived from the luminous power.
+
+$$\begin{equation}\label{pointLightLuminousPower}
+\Phi = \int_{\Omega} I dl = \int_{0}^{2\pi} \int_{0}^{\pi} I d\theta d\phi = 4 \pi I \\
+I = \frac{\Phi}{4 \pi}
+\end{equation}$$
+
+By simple substitution of $I$ in $\ref{punctualLightEquation}$ and $E$ in $ \ref{luminanceEquation} $ we can formulate the luminance equation of a point light as a function of the luminous power (see $ \ref{pointLightLuminanceEquation} $).
+
+$$\begin{equation}\label{pointLightLuminanceEquation}
+L_{out} = f(v,l) \frac{\Phi}{4 \pi d^2} \left< \NoL \right>
+\end{equation}$$
+
+Figure [pointLightTest] shows the effect of lighting a simple scene with a point light subject to distance attenuation. Light falloff is exaggerated for illustration purposes.
+
+![Figure [pointLightTest]: Inverse square law applied to point lights evaluation](images/screenshot_point_light.png)
+
+#### Spot lights
+
+A spot light is defined by a position in space, a direction vector and two cone angles, $ \theta_{inner} $ and $ \theta_{outer} $ (see figure [spotLight]). These two angles are used to define the angular falloff attenuation of the spot light. The light evaluation function of a spot light must therefore take into account both the inverse square law and these two angles to properly evaluate the luminance attenuation.
+
+![Figure [spotLight]: Interaction between a spot light and a surface. The attenuation depends on the distance to the light and the angle between the surface the spot light's direction vector](images/diagram_spot_light.png)
+
+Equation $ \ref{spotLightLuminousPower} $ describes how the luminous power of a spot light can be calculated in a similar fashion to point lights, using $ \theta_{outer} $ the outer angle of the spot light's cone in the range [0..$\pi$].
+
+$$\begin{equation}\label{spotLightLuminousPower}
+\Phi = \int_{\Omega} I dl = \int_{0}^{2\pi} \int_{0}^{\theta_{outer}} I d\theta d\phi = 2 \pi (1 - cos\frac{\theta_{outer}}{2})I \\
+I = \frac{\Phi}{2 \pi (1 - cos\frac{\theta_{outer}}{2})}
+\end{equation}$$
+
+While this formulation is physically correct, it makes spot lights a little difficult to use: changing the outer angle of the cone changes the illumination levels. Figure [spotLightTestFocused] shows the same scene lit by a spot light, with an outer angle of 55 degrees and an outer angle of 15 degrees. Observes how the illumination level increases as the cone aperture decreases.
+
+![Figure [spotLightTestFocused]: Comparison of spot light outer angles, 55 degrees (left) and 15 degrees (right)](images/screenshot_spot_light_focused.png)
+
+The coupling of illumination and the outer cone means that an artist cannot tweak the influence cone of a spot light without also changing the perceived illumination. It therefore makes sense to provide artists with a parameter to disable this coupling. Equations $ \ref{spotLightLuminousPowerB} $ shows how to formulate the luminous power for that purpose.
+
+$$\begin{equation}\label{spotLightLuminousPowerB}
+\Phi = \pi I \\
+I = \frac{\Phi}{\pi} \\
+\end{equation}$$
+
+With this new formulation to compute the luminous intensity, the test scene in figure [spotLightTest] exhibits similar illumination levels with both cone apertures.
+
+![Figure [spotLightTest]: Comparison of spot light outer angles, 55 degrees (left) and 15 degrees (right)](images/screenshot_spot_light.png)
+
+This new formulation can also be considered physically based if the spot's reflector is replaced with a matte, diffuse mask that absorbs light perfectly.
+
+The spot light evaluation function can be expressed in two ways:
+
+- **With a light absorber**
+  $$\begin{equation}\label{spotAbsorber}
+  L_{out} = f(v,l) \frac{\Phi}{\pi d^2} \left< \NoL \right> \lambda(l)
+  \end{equation}$$
+- **With a light reflector**
+  $$\begin{equation}\label{spotReflector}
+  L_{out} = f(v,l) \frac{\Phi}{2 \pi (1 - cos\frac{\theta_{outer}}{2}) d^2} \left< \NoL \right> \lambda(l)
+  \end{equation}$$
+
+The term $ \lambda(l) $ in equations $ \ref{spotAbsorber} $ and $ \ref{spotReflector} $ is the spot's angle attenuation factor described in equation
+ $ \ref{spotAngleAtt} $ below.
+
+$$\begin{equation}\label{spotAngleAtt}
+\lambda(l) = \frac{l \cdot spotDirection - cos\theta_{outer}}{cos\theta_{inner} - cos\theta_{outer}}
+\end{equation}$$
+
+#### Attenuation function
+
+A proper evaluation of the inverse square law attenuation factor is mandatory for physically based punctual lights. The simple mathematical formulation is unfortunately impractical for implementation purposes:
+
+1. The division by the squared distance can lead to divides by 0 when objects intersect or "touch" light sources.
+
+2. The influence sphere of each light is infinite ($ \frac{I}{d^2} $ is asymptotic, it never reaches 0) which means that to correctly shade a pixel we need to evaluate every light in the world.
+
+
+The first issue can be solved easily by setting the assumption that punctual lights are not truly punctual but instead small area lights. To do this we can simply treat punctual lights as spheres of 1 cm radius, as show in equation $\ref{finitePunctualLight}$.
+
+$$\begin{equation}\label{finitePunctualLight}
+E = \frac{I}{max(d^2, {0.01}^2)}
+\end{equation}$$
+
+We can solve the second issue by introducing an influence radius for each light. There are several advantages to this solution. Tools can quickly show artists what parts of the world will be influenced by every light (the tool just needs to draw a sphere centered on each light). The rendering engine can cull lights more aggressively using this extra piece of information and artists/developers can assist the engine by manually tweaking the influence radius of a light.
+
+Mathematically, the illuminance of a light should smoothly reach zero at the limit defined by the influence radius. [#Karis13b] proposes to window the inverse square function in such a way that the majority of the light's influence remains unaffected. The proposed windowing is described in equation $\ref{attenuationWindowing}$, where $r$ is the light's radius of influence.
+
+$$\begin{equation}\label{attenuationWindowing}
+E = \frac{I}{max(d^2, {0.01}^2)} \left< 1 - \frac{d^4}{r^4} \right>^2
+\end{equation}$$
+
+Listing [glslPunctualLight] demonstrates how to implement physically based punctual lights in GLSL. Note that the light intensity used in this piece of code is the luminous intensity $I$ in $cd$, converted from the luminous power  CPU-side. This snippet is not optimized and some of the computations can be offloaded to the CPU (for instance the square of the light's inverse falloff radius, or the spot scale and angle).
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+float getSquareFalloffAttenuation(vec3 posToLight, float lightInvRadius) {
+    float distanceSquare = dot(posToLight, posToLight);
+    float factor = distanceSquare * lightInvRadius * lightInvRadius;
+    float smoothFactor = max(1.0 - factor * factor, 0.0);
+    return (smoothFactor * smoothFactor) / max(distanceSquare, 1e-4);
+}
+
+float getSpotAngleAttenuation(vec3 l, vec3 lightDir,
+        float innerAngle, float outerAngle) {
+    // the scale and offset computations can be done CPU-side
+    float cosOuter = cos(outerAngle);
+    float spotScale = 1.0 / max(cos(innerAngle) - cosOuter, 1e-4)
+    float spotOffset = -cosOuter * spotScale
+
+    float cd = dot(normalize(-lightDir), l);
+    float attenuation = clamp(cd * spotScale + spotOffset, 0.0, 1.0);
+    return attenuation * attenuation;
+}
+
+vec3 evaluatePunctualLight() {
+    vec3 l = normalize(posToLight);
+    float NoL = clamp(dot(n, l), 0.0, 1.0);
+    vec3 posToLight = lightPosition - worldPosition;
+
+    float attenuation;
+    attenuation  = getSquareFalloffAttenuation(posToLight, lightInvRadius);
+    attenuation *= getSpotAngleAttenuation(l, lightDir, innerAngle, outerAngle);
+
+    vec3 luminance = (BSDF(v, l) * lightIntensity * attenuation * NoL) * lightColor;
+    return luminance;
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+[Listing [glslPunctualLight]: Implementation of punctual lights in GLSL]
+
+### Photometric lights
+
+Punctual lights are an extremely practical and efficient way to light a scene but do not give artists enough control over the light distribution. The field of architectural lighting design concerns itself with designing lighting systems to serve humans needs by taking into account:
+
+- The amount of light provided
+- The color of the light
+- The distribution of light within the space
+
+The lighting system we have described so far can easily address the first two points but we need a way to define the distribution of light within the space. Light distribution is especially important for indoor scenes or for some types of outdoor scenes or even road lighting. Figure [lightDistributionTest] shows scenes where the light distribution is controlled by the artist. This type of distribution control is widely used when putting objects on display (museums, stores or galleries for instance).
+
+![Figure [lightDistributionTest]: Controlling the distribution of a point light](images/screenshot_photometric_lights.png)
+
+Photometric lights use a photometric profile to describe their intensity distribution. There are two commonly used formats, IES (Illuminating Engineering Society) and EULUMDAT (European Lumen Data format) but we will focus on the former. IES profiles are supported by many tools and engines, such as Unreal Engine 4, Frostbite, Renderman, Maya and Killzone. In addition, IES light profiles are commonly made available by bulbs and luminaires manufacturers (Philips offers [an extensive array of IES files](http://www.usa.lighting.philips.com/connect/tools_literature/photometric_data_1.wpd) for download for instance). Photometric profiles are particularly useful when they measure a luminaire or light fixture, in which the light source is partially covered. The luminaire will block the light emitted in certain directions, thus shaping the light distribution.
+
+![Example of a real world luminaires that can be described by photometric profiles](images/photo_photometric_lights.jpg)
+
+An IES profile stores luminous intensity for various angles on a sphere around the measured light source. This spherical coordinate system is usually referred to as the photometric web, which can be visualized using specialized tools such as [IESviewer](http://www.photometricviewer.com/). Figure [xarrow] below shows the photometric web of the XArrow IES profile [provided by Pixar](http://renderman.pixar.com/view/DP25764) for use with Renderman. This picture also shows a rendering in 3D space of the XArrow IES profile by our tool `lightgen`.
+
+![Figure [xarrow]: The XArrow IES profile rendered as a photometric web and as a point light in 3D space](images/screenshot_xarrow.png)
+
+The IES format is poorly documented and it is not uncommon to find syntax variations between files found on the Internet. The best resource to understand IES profile is Ian Ashdown's "Parsing the IESNA LM-63 photometric data file" document [#Ashdown98]. Succinctly, an IES profiles stores luminous intensities in candela at various angles around the light source. For each measured horizontal angle, a series of luminous intensities at different vertical angles is provided. It is however fairly common for measured light sources to be horizontally symmetrical. The XArrow profile shown above is a good example: intensities vary with vertical angles (vertical axis) but are symmetrical on the horizontal axis. The range of vertical angles in an IES profile is 0 to 180 degrees and the range of horizontal angles is 0 to 360 degrees.
+
+Figure [lightenSamples] shows the series of IES profiles provided by Pixar for Renderman, rendered using our `lightgen` tool.
+
+![Figure [lightenSamples]: Series of IES light profiles rendered with lightgen](images/screenshot_lightgen_samples.png)
+
+IES profiles can be applied directly to any punctual light, point or spot. To do so, we must first process the IES profile and generate a photometric profile as a texture. For performance considerations, the photometric profile we generate is a 1D texture that represents the average luminous intensity for all horizontal angles at a specific vertical angle (i.e., each pixel represents a vertical angle). To truly represent a photometric light, we should use a 2D texture but since most lights are fully, or mostly, symmetrical on the horizontal plane, we can accept this approximation. The values stored in the texture are normalized by the inverse maximum intensity defined in the IES profile. This allows us to easily store the texture in any float format or, at the cost of a bit of precision, in a luminance 8-bit texture (grayscale PNG for instance). Storing normalized values also allows us to treat photometric profiles as a mask:
+
+Photometric profile as a mask
+:   The luminous intensity is defined by the artist by setting the luminous power of the light, as with any other punctual light. The artist defined intensity is divided by the intensity of the light computed from the IES profile. IES profiles contain a luminous intensity but it is only valid for a bare light bulb whereas the measured intensity values take into account the light fixture. To measure the intensity of the luminaire, instead of the bulb, we perform a Monte-Carlo integration of the unit sphere using the intensities from the profile[^xarrowIntensity].
+
+Photometric profile
+:   The luminous intensity comes from the profile itself. All the values sampled from the 1D texture are simply multiplied by the maximum intensity. We also provide a multiplier for convenience.
+
+The photometric profile can be applied at rendering time as a simple attenuation. The luminance equation $ \ref{photometricLightEvaluation} $ describes the photometric point light evaluation function.
+
+$$\begin{equation}\label{photometricLightEvaluation}
+L_{out} = f(v,l) \frac{I}{d^2} \left< \NoL \right> \Psi(l)
+\end{equation}$$
+
+The term $ \Psi(l) $ is the photometric attenuation function. It depends on the light vector, but also on the direction of the light. Spot lights already possess a direction vector but we need to introduce one for photometric point lights as well.
+
+The photometric attenuation function can be easily implemented in GLSL by adding a new attenuation factor to the implementation of punctual lights (listing [glslPunctualLight]). The modified implementation is show in listing [glslPhotometricPunctualLight].
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+float getPhotometricAttenuation(vec3 posToLight, vec3 lightDir) {
+    float cosTheta = dot(-posToLight, lightDir);
+    float angle = acos(cosTheta) * (1.0 / PI);
+    return texture2DLodEXT(lightProfileMap, vec2(angle, 0.0), 0.0).r;
+}
+
+vec3 evaluatePunctualLight() {
+    vec3 l = normalize(posToLight);
+    float NoL = clamp(dot(n, l), 0.0, 1.0);
+    vec3 posToLight = lightPosition - worldPosition;
+
+    float attenuation;
+    attenuation  = getSquareFalloffAttenuation(posToLight, lightInvRadius);
+    attenuation *= getSpotAngleAttenuation(l, lightDirection, innerAngle, outerAngle);
+    attenuation *= getPhotometricAttenuation(l, lightDirection);
+
+    float luminance = (BSDF(v, l) * lightIntensity * attenuation * NoL) * lightColor;
+    return luminance;
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+[Listing [glslPhotometricPunctualLight]: Implementation of attenuation from photometric profiles in GLSL]
+
+The light intensity is computed CPU-side (listing [photometricLightIntensity]) and depends on whether the photometric profile is used as a mask.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+float multiplier;
+// Photometric profile used as a mask
+if (photometricLight.isMasked()) {
+    // The desired intensity is set by the artist
+    // The integrated intensity comes from a Monte-Carlo
+    // integration over the unit sphere around the luminaire
+    multiplier = photometricLight.getDesiredIntensity() /
+            photometricLight.getIntegratedIntensity();
+} else {
+    // Multiplier provided for convenience, set to 1.0 by default
+    multiplier = photometricLight.getMultiplier();
+}
+
+// The max intensity in cd comes from the IES profile
+float lightIntensity = photometricLight.getMaxIntensity() * multiplier;
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+[Listing [photometricLightIntensity]: Computing the intensity of a photometric light on the CPU]
+
+[^xarrowIntensity]: The XArrow profile declares a luminous intensity of 1,750 lm but a Monte-Carlo integration shows an intensity of only 350 lm.
+
+### Area lights
+
+[TODO]
+
+### Lights parameterization
+
+Similarly to the parameterization of the standard material model, our goal is to make lights parameterization intuitive and easy to use for artists and developers alike. In that spirit, we decided to separate the light color (or hue) from the light intensity. A light color will therefore be defined as a linear RGB color (or sRGB in the tools UI for convenience).
+
+The full list of light parameters is presented in table [lightParameters].
+
+
+          Parameter        |      Definition
+--------------------------:|:---------------------
+**Type**                   | Directional, point, spot or area
+**Direction**              | Used for directional lights, spot lights, photometric point lights, and linear and tubular area lights (orientation)
+**Color**                  | The color of emitted light, as a linear RGB color. Can be specified as an sRGB color or a color temperature in the tools
+**Intensity**              | The light's brightness. The unit depends on the type of light
+**Falloff radius**         | Maximum distance of influence
+**Inner angle**            | Angle of the inner cone for spot lights, in degrees
+**Outer angle**            | Angle of the outer cone for spot lights, in degrees
+**Length**                 | Length of the area light, used to create linear or tubular lights
+**Radius**                 | Radius of the area light, used to create spherical or tubular lights
+**Photometric profile**    | Texture representing a photometric light profile, works only for punctual lights
+**Masked profile**         | Boolean indicating whether the IES profile is used as a mask or not. When used as a mask, the light's brightness will be multiplied by the ratio between the user specified intensity and the integrated IES profile intensity. When not used as a mask, the user specified intensity is ignored but the IES multiplier is used instead
+**Photometric multiplier** | Brightness multiplier for photometric lights (if IES as mask is turned off)
+[Table [lightParameters]: Light types parameters]
+
+**Note**: to simplify the implementation, all luminous powers will converted to luminous intensities ($cd$) before being sent to the shader. The conversion is light dependent and is explained in the previous sections.
+
+**Note**: the light type can be inferred from other parameters (e.g. a point light has a length, radius, inner angle and outer angle of 0).
+
+#### Color temperature
+
+However, real-world artificial lights are often defined by their color temperature, measured in Kelvin (K). The color temperature of a light source is the temperature of an ideal black-body radiator that radiates light of comparable hue to that of the light source. For convenience, the tools should allow the artist to specify the hue of a light source as a color temperature (a meaningful range is 1,000 K to 12,500 K).
+
+To compute RGB values from a temperature, we can use the Planckian locus, shown in figure [planckianLocus]. This locus is the path that the color of an incandescent black body takes in a chromaticity space as the body's temperature changes.
+
+![Figure [planckianLocus]: The Planckian locus visualized on a CIE 1931 chromaticity diagram (source: Wikipedia)](images/diagram_planckian_locus.png)
+
+The easiest way to compute RGB values from this locus is to use the formula described in [#Krystek85]. Krystek's algorithm (equation $\ref{krystek}$) works in the CIE 1960 (UCS) space, using the following formula where $T$ is the desired temperature, and $u$ and $v$ the coordinates in UCS.
+
+$$\begin{equation}\label{krystek}
+u(T) = \frac{0.860117757 + 1.54118254 \times 10^{-4}T + 1.28641212 \times 10^{-7}T^2}{1 + 8.42420235 \times 10^{-4}T + 7.08145163 \times 10^{-7}T^2} \\
+v(T) = \frac{0.317398726 + 4.22806245
+ \times 10^{-5}T + 4.20481691 \times 10^{-8}T^2}{1 - 2.89741816
+ \times 10^{-5}T + 1.61456053 \times 10^{-7}T^2}
+\end{equation}$$
+
+This approximation is accurate to roughly $ 9 \times 10^{-5} $ in the range 1,000K to 15,000K. From the CIE 1960 space we can compute the coordinates in xyY space (CIES 1931), using the formula from equation $\ref{cieToxyY}$.
+
+$$\begin{equation}\label{cieToxyY}
+x = \frac{3u}{2u - 8v + 4} \\
+y = \frac{2v}{2u - 8v + 4}
+\end{equation}$$
+
+The formulas above are valid for black body color temperatures, and therefore correlated color temperatures of standard illuminants. If we wish to compute the precise chromaticity coordinates of standard CIE illuminants in the D series we can use equation $\ref{seriesDtoxyY}$.
+
+$$\begin{equation}\label{seriesDtoxyY}
+x = \begin{cases} 0.244063 + 0.09911 \frac{10^3}{T} + 2.9678 \frac{10^6}{T^2} - 4.6070 \frac{10^9}{T^3} & 4,000K \le T \le 7,000K \\
+0.237040 + 0.24748 \frac{10^3}{T} + 1.9018 \frac{10^6}{T^2} - 2.0064 \frac{10^9}{T^3} & 7,000K \le T \le 25,000K \end{cases} \\
+y = -3x^2 + 2.87 x - 0.275
+\end{equation}$$
+
+From the xyY space, we can then convert to the CIE XYZ space (equation $\ref{xyYtoXYZ}$).
+
+$$\begin{equation}\label{xyYtoXYZ}
+X = \frac{xY}{y} \\
+Z = \frac{(1 - x - y)Y}{y}
+\end{equation}$$
+
+For our needs, we will fix $Y = 1$. This allows us to convert from the XYZ space to linear RGB with a simple 3x3 matrix, as shown in equation $\ref{XYZtoRGB}$.
+
+$$\begin{equation}\label{XYZtoRGB}
+\left[ \begin{matrix} R \\ G \\ B \end{matrix} \right] = M^{-1} \left[ \begin{matrix} X \\ Y \\ Z \end{matrix} \right]
+\end{equation}$$
+
+The transformation matrix M is calculated from the target RGB color space primaries. Equation $ \ref{XYZtoRGBValues} $ shows the conversion using the inverse matrix for the sRGB color space.
+
+$$\begin{equation}\label{XYZtoRGBValues}
+\left[ \begin{matrix} R \\ G \\ B \end{matrix} \right] = \left[ \begin{matrix} 3.2404542 & -1.5371385 & -0.4985314 \\ -0.9692660 & 1.8760108 & 0.0415560 \\ 0.0556434 & -0.2040259 & 1.0572252 \end{matrix} \right] \left[ \begin{matrix} X \\ Y \\ Z \end{matrix} \right]
+\end{equation}$$
+
+The result of these operations is a linear RGB triplet in the sRGB color space. Since we care about the chromaticity of the results, we must apply a normalization step to avoid clamping values greater than 1.0 and distort resulting colors:
+
+$$\begin{equation}\label{normalizedRGB}
+\hat{C}_{linear} = \frac{C_{linear}}{max(C_{linear})}
+\end{equation}$$
+
+We must finally apply the sRGB opto-electronic conversion function (OECF, shown in equation $ \ref{OECFsRGB} $) to obtain a displayable value (the value should remain linear if passed to the renderer for shading).
+
+$$\begin{equation}\label{OECFsRGB}
+C_{sRGB} = \begin{cases} 12.92 \times \hat{C}_{linear} & \hat{C}_{linear} \le 0.0031308 \\
+1.055 \times \hat{C}_{linear}^{\frac{1}{2.4}} - 0.055 & \hat{C}_{linear} \gt 0.0031308 \end{cases}
+\end{equation}$$
+
+For convenience, figure [colorTemperatureScaleCCT] shows the range of correlated color temperatures from 1,000K to 12,500K. All the colors used below assume CIE $ D_{65} $ as the white point (as is the case in the sRGB color space).
+
+![Figure [colorTemperatureScaleCCT]: Scale of correlated color temperatures](images/diagram_color_temperature_cct.png)
+
+Similarly, figure [colorTemperatureScaleCIE] shows the range of CIE standard illuminants series D from 1,000K to 12,500K.
+
+![Figure [colorTemperatureScaleCIE]: Scale of CIE standard illuminants series D](images/diagram_color_temperature_cie.png)
+
+For reference, figure [colorTemperatureScaleCCTClamped] shows the range of correlated color temperatures without the normalization step presented in equation $\ref{normalizedRGB}$.
+
+![Figure [colorTemperatureScaleCCTClamped]: Unnormalized scale of correlated color temperatures](images/diagram_color_temperature_cct_clamped.png)
+
+Table [colorTemperatureSamples] presents the correlated color temperature of various common light sources as sRGB color swatches. These colors are relative to the $ D_{65} $ white point, so their perceived hue might vary based on your display's white point. See [What colour is the Sun?](http://jila.colorado.edu/~ajsh/colour/Tspectrum.html) for more information.
+
+
+    Temperature (K)  |          Light source        |                 Color
+--------------------:|:-----------------------------|-------------------------------------------------------
+1,700-1,800          | Match flame                  | <div style="background-color: #ff7d00; width: 60px">&nbsp;</div>
+1,850-1,930          | Candle flame                 | <div style="background-color: #ff8701; width: 60px">&nbsp;</div>
+2,000-3,000          | Sun at sunrise/sunset        | <div style="background-color: #ffa64c; width: 60px">&nbsp;</div>
+2,500-2,900          | Household tungsten lightbulb | <div style="background-color: #ffb05e; width: 60px">&nbsp;</div>
+3,000                | Tungsten lamp 1K             | <div style="background-color: #ffb86f; width: 60px">&nbsp;</div>
+3,200-3,500          | Quartz lights                | <div style="background-color: #ffbf7b; width: 60px">&nbsp;</div>
+3,200-3,700          | Fluorescent lights           | <div style="background-color: #ffbf7b; width: 60px">&nbsp;</div>
+3,275                | Tungsten lamp 2K             | <div style="background-color: #ffc180; width: 60px">&nbsp;</div>
+3,380                | Tungsten lamp 5K, 10K        | <div style="background-color: #ffc486; width: 60px">&nbsp;</div>
+5,000-5,400          | Sun at noon                  | <div style="background-color: #ffe9d7; width: 60px">&nbsp;</div>
+5,500-6,500          | Daylight (sun + sky)         | <div style="background-color: #fff3f1; width: 60px">&nbsp;</div>
+5,500-6,500          | Sun through clouds/haze      | <div style="background-color: #fff3f1; width: 60px">&nbsp;</div>
+6,000-7,500          | Overcast sky                 | <div style="background-color: #faf6ff; width: 60px">&nbsp;</div>
+6,500                | RGB monitor white point      | <div style="background-color: #fff8fe; width: 60px">&nbsp;</div>
+7,000-8,000          | Shaded areas outdoors        | <div style="background-color: #ebecff; width: 60px">&nbsp;</div>
+8,000-10,000         | Partly cloudy sky            | <div style="background-color: #d6e0ff; width: 60px">&nbsp;</div>
+[Table [colorTemperatureSamples]: Normalized correlated color temperatures for common light sources]
+
+### Pre-exposed lights
+
+Physically based rendering and physical light units pose an interesting challenge: how to store and handle the large range of values produced by the lighting code? Assuming computations performed at full precision in the shaders, we still want to be able to store the linear output of the lighting pass in a reasonably sized buffer (`RGB16F` or equivalent). The most obvious and easiest way to achieve this is to simply apply the camera exposure (see the Physically based camera section for more information) before writing out the result of the lighting pass. This simple step is shown in listing [preexposedLighting]:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+fragColor = luminance * camera.exposure;
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+[Listing [preexposedLighting]: The output of the lighting pass is pre-exposed to fit in half-float buffers]
+
+This solution solves the storage problem but requires intermediate computations to be performed with single precision floats. We would instead prefer to perform all (or at least most) of the lighting work using half precision floats instead. Doing so can greatly improve performance and power usage, particularly on mobile devices. Half precision floats are however ill-suited for this kind of work as common illuminance and luminance values (for the sun for instance) can exceed their range. The solution is to simply pre-expose the lights themselves instead of the result of the lighting pass. This can be done efficiently on the CPU if updating a light's constant buffer is cheap. This can also be done on the GPU, as shown in listing [preexposedLights].
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+// The inputs must be highp/single precision,
+// both for range (intensity) and precision (exposure)
+// The output is mediump/half precision
+float computePreExposedIntensity(highp float intensity, highp float exposure) {
+    return intensity * exposure;
+}
+
+Light getPointLight(uint index) {
+    Light light;
+    uint lightIndex = // fetch light index;
+
+    // the intensity must be highp/single precision
+    highp vec4 colorIntensity  = lightsUniforms.lights[lightIndex][1];
+
+    // pre-expose the light
+    light.colorIntensity.w = computePreExposedIntensity(
+            colorIntensity.w, frameUniforms.exposure);
+
+    return light;
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+[Listing [preexposedLights]: Pre-exposing lights allows the entire shading pipeline to use half precision floats]
+
+In practice we pre-expose the following lights:
+- Punctual lights (point and spot): on the GPU
+- Directional light: on the CPU
+- IBLs: on the CPU
+- Material emissive: on the GPU
+
+## Image based lights
+
+In real life, light comes from every direction either directly from light sources or indirectly after bouncing off objects in the environment, being partially absorbed in the process. In a way the whole environment around an object can be seen as a light source. Images, in particular cubemaps, are a great way to encode such an “environment light”. This is called Image Based Lighting (IBL) or sometimes Indirect Lighting.
+
+![Figure [iblBall]: The object shown here is lit only by image-encoded environment lights. Notice the subtle lighting effects that can be applied using this technique.](images/screenshot_ball_ibl.png)
+
+There are limitations with image-based lighting. Obviously the environment image must be acquired somehow and as we'll see below it needs to be pre-processed before it can be used for lighting. Typically, the environment image is acquired offline in the real world, or generated by the engine either offline or at run time; either way, local or distant probes are used.
+
+These probes can be used to acquire the distant or local environment. In this document, we're focusing on distant environment probes, where the light is assumed to come from infinitely far away (which means every point on the object's surface uses the same environment map).
+
+The whole environment contributes light to a given point on the object's surface; this is called _irradiance_ ($E$). The resulting light bouncing off of the object is called radiance ($L_{out}$). Incident lighting must be applied consistently to the diffuse and specular parts of the BRDF.
+
+The radiance $L_{out}$ resulting from the interaction between an image based light's (IBL) irradiance and a material model (BRDF) $f(\Theta)$[^ibl1] is computed as follows:
+
+$$\begin{equation}
+L_{out}(n, v, \Theta) = \int_\Omega  f(l, v, \Theta) L_{\bot}(l) \left< \NoL \right> dl 
+\end{equation}$$ 
+
+Note that here we're looking at the behavior of the surface at **macro** level (not to be confused with the micro level equation), which is why it only depends on $\vec n$ and $\vec v$. Essentially, we're applying the BRDF to “point-lights” coming from all directions and encoded in the IBL.
+
+### IBL Types ###
+
+There are four common types of IBLs used in modern rendering engines:
+
+- **Distant light probes**, used to capture lighting information at "infinity", where parallax can be ignored. Distant probes typically contain the sky, distant landscape features or buildings, etc. They are either captured by the engine or acquired from a camera as high dynamic range images (HDRI).
+
+- **Local light probes**, used to capture a certain area of the world from a specific point of view. The capture is projected on a cube or sphere depending on the surrounding geometry. Local probes are more accurate than distance probes and are particularly useful to add local reflections to materials.
+
+- **Planar reflections**, used to capture reflections by rendering the scene mirrored by a plane. This technique works only for flat surfaces such as building floors, roads and water.
+
+- **Screen space reflection**, used to capture reflections based on the rendered scene (using the previous frame for instance) by ray-marching in the depth buffer. SSR gives great result but can be very expensive.
+
+In addition we must distinguish between static and dynamic IBLs. Implementing a fully dynamic day/night cycle requires for instance to recompute the distant light probes dynamically[^iblTypes1]. Both planar and screen space reflections are inherently dynamic.
+
+### IBL Unit ###
+
+As discussed previously in the direct lighting section, all our lights must use physical units. As such our IBLs will use the luminance unit $\frac{cd}{m^2}$, which is also the output unit of all our direct lighting equations. Using the luminance unit is straightforward for light probes captures by the engine (dynamically or statically offline).
+
+High dynamic range images are a bit more delicate to handle however. Cameras do not record measured luminance but a device-dependent value that is only _related_ to the original scene luminance. As such, we must provide artists with a multiplier that allows them to recover, or at the very least closely approximate, the original absolute luminance.
+
+To properly reconstruct the luminance of an HDRI for IBL, artists must do more than simply take photos of the environment and record extra information:
+
+- **Color calibration**: using a gray card or a [MacBeth ColorChecker](http://en.wikipedia.org/wiki/ColorChecker)
+
+- **Camera settings**: aperture, shutter and ISO
+
+- **Luminance samples**: using a spot/luminance meter
+
+[TODO] Measure and list common luminance values (clear sky, interior, etc.)
+
+### Processing light probes ###
+
+We saw previously that the radiance of an IBL is computed by integrating over the surface's hemisphere. Since this would obviously be too expensive to do in real-time, we must first pre-process our light probes to convert them into a format better suited for real-time interactions.
+
+The sections below will discuss the techniques used to accelerate the evaluation of light probes:
+
+- **Specular reflectance**: pre-filtered importance sampling and split-sum approximation
+
+- **Diffuse reflectance**: irradiance map and spherical harmonics
+
+### Distant light probes ###
+
+#### Diffuse BRDF integration ####
+
+Using the Lambertian BRDF[^iblDiffuse1], we get the radiance:
+
+$$
+\begin{align*}
+   f_d(\sigma) &= \frac{\sigma}{\pi} \\
+L_d(n, \sigma) &= \int_{\Omega} f_d(\sigma) L_{\bot}(l) \left< \NoL \right> dl \\
+               &= \frac{\sigma}{\pi} \int_{\Omega} L_{\bot}(l) \left< \NoL \right> dl \\
+               &= \frac{\sigma}{\pi} E_d(n) \quad \text{with the irradiance} \; 
+        E_d(n) = \int_{\Omega} L_{\bot}(l) \left< \NoL \right> dl
+\end{align*}
+$$
+
+Or in the discrete domain:
+
+$$ E_d(n) \equiv \sum_{\forall \, i \in image} L_{\bot}(s_i) \left< n \cdot s_i \right> \Omega_s $$
+
+$\Omega_s$ is the solid-angle[^iblDiffuse2] associated to sample $i$.
+
+The irradiance integral $\Ed$ can be trivially, albeit slowly[^iblDiffuse3], precomputed and stored into a cubemap for efficient access at runtime. Typically, _image_ is a cubemap or an equirectangular image. The term $ \frac{\sigma}{\pi} $ is independent of the IBL and is added at runtime to obtain the _radiance_.
+
+![Figure [iblOriginal]: Image-based environment](images/ibl/ibl_river_roughness_m0.png style="max-width:100%;")
+
+![Figure [iblIrradiance]: Image-based irradiance map using the Lambertian BRDF](images/ibl/ibl_irradiance.png style="max-width:100%;")
+
+
+[^ibl1]: $\Theta$ represents the parameters of the material model $f$, i.e.: _roughness_, albedo and so on...
+
+[^iblTypes1]: This can be done through blending of static probes or by spreading the workload over time
+
+[^iblDiffuse1]: The Lambertian BRDF doesn't depend on $\vec l$, $\vec v$ or $\theta$, so $L_d(n,v,\theta) \equiv L_d(n,\sigma)$
+
+[^iblDiffuse2]: $\Omega_s$ can be approximated by $\frac{2\pi}{6 \cdot width \cdot height}$ for a cubemap
+
+[^iblDiffuse3]: $O(12\,n^2\,m^2)$, with $n$ and $m$ respectively the dimensions of the environment and the precomputed cubemap
+
+
+However, the irradiance can also be approximated very closely by a decomposition into Spherical Harmonics (SH, described in more details in the Spherical Harmonics section) and calculated at runtime cheaply. It is usually best to avoid texture fetches on mobile and free-up a texture unit. Even if it is stored into a cubemap, it is orders of magnitude faster to pre-compute the integral using SH decomposition followed by a rendering.
+
+SH decomposition is similar in concept to a Fourier transform, it expresses the signal over an orthonormal base in the frequency domain. The properties that interests us most are:
+
+- Very few coefficients are needed to encode $\cosTheta$
+
+- Convolutions by a kernel that _has a circular symmetry_ are very inexpensive and become products in SH space
+
+In practice only 4 or 9 coefficients (i.e.: 2 or 3 bands) are enough for $\cosTheta$ meaning we don't need more either for $\Lt$.
+
+![Figure [iblSH3]: 3 bands (9 coefficients)](images/ibl/ibl_irradiance_sh3.png style="max-width:100%;")
+
+![Figure [iblSH2]: 2 bands (4 coefficients)](images/ibl/ibl_irradiance_sh2.png style="max-width:100%;")
+
+
+In practice we pre-convolve $\Lt$ with $\cosTheta$ and pre-scale these coefficients by the basis scaling factors $K_l^m$ so that the reconstruction code is as simple as possible in the shader:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+vec3 irradianceSH(vec3 n) {
+    // uniform vec3 sphericalHarmonics[9]
+    // We can use only the first 2 bands for better performance
+    return
+          sphericalHarmonics[0]
+        + sphericalHarmonics[1] * (n.y)
+        + sphericalHarmonics[2] * (n.z)
+        + sphericalHarmonics[3] * (n.x)
+        + sphericalHarmonics[4] * (n.y * n.x)
+        + sphericalHarmonics[5] * (n.y * n.z)
+        + sphericalHarmonics[6] * (3.0 * n.z * n.z - 1.0)
+        + sphericalHarmonics[7] * (n.z * n.x)
+        + sphericalHarmonics[8] * (n.x * n.x - n.y * n.y);
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+[Listing [irradianceSH]: GLSL code to reconstruct the irradiance from the pre-scaled SH]
+
+Note that with 2 bands, the computation above becomes a single $4 \times 4$ matrix-by-vector multiply.
+
+Additionally, because of the pre-scaling by $K_l^m$, the SH coefficients can be thought of as colors, in particular `sphericalHarmonics[0]` is directly the average irradiance.
+
+
+#### Specular BRDF integration ####
+
+As we've seen above, the radiance $\Lout$ resulting from the interaction between an IBL's irradiance and a BRDF is:
+
+$$\begin{equation}\label{specularBRDFIntegration}
+\Lout(n, v, \Theta) = \int_\Omega f(l, v, \Theta) \Lt(l) \left< \NoL \right> \partial l 
+\end{equation}$$ 
+
+We recognize the convolution of $\Lt$ by $f(l, v, \Theta) \left< \NoL \right>$, 
+i.e.: the environment is *filtered* using the BRDF as a kernel. Indeed at higher roughness, 
+specular reflections look more *blurry*.
+ 
+Plugging the expression of $f$ in equation $\ref{specularBRDFIntegration}$, we obtain:
+
+$$\begin{equation}
+\Lout(n,v,\Theta) = \int_\Omega D(l, v, \alpha) F(l, v, f_0, f_{90}) V(l, v, \alpha) \left< \NoL \right> \Lt(l) \partial l
+\end{equation}$$ 
+
+This expression depends on $v$, $\alpha$, $f_0$ and $f_{90}$ inside the integral, 
+which makes its evaluation extremely costly and unsuitable for real-time on mobile 
+(even using pre-filtered importance sampling). 
+
+##### Simplifying the BRDF integration #####
+
+Since there is no closed-form solution or an easy way to compute the $\Lout$ integral, we use a simplified
+equation instead: $\hat{I}$, whereby we assume that $v = n$, that is the view direction $v$ is always
+equal to the surface normal $n$. Clearly, this assumption will break all view-dependant effects of 
+the convolution, such as the increased blur in reflections closer to the viewer 
+(a.k.a. stretchy reflections). 
+
+Such a simplification would also have a severe impact on constant environments, such as the white 
+furnace, because it would affect the magnitude of the constant (i.e. DC) term of the result. We
+can at least correct for that by using a scale factor, $K$, in our simplified integral, which
+will make sure the average irradiance stay correct when chosen properly.
+
+    - $I$ is our original integral, i.e.: $I(g) = \int_\Omega g(l) \left< \NoL \right> \partial l$
+    - $\hat{I}$ is the simplified integral where $v = n$
+    - $K$ is a scale factor that ensures the average irradiance is unchanged by $\hat{I}$
+    - $\tilde{I}$ is our final approximation of $I$, $\tilde{I} = \hat{I} \times K$ 
+
+
+Because $I$ is an integral multiplications can be distributed over it. i.e.: $I(g()f()) = I(g())I(f())$.
+
+Armed with that,
+
+$$\begin{equation}
+I( f(\Theta) \Lt ) \approx \tilde{I}( f(\Theta) \Lt )                       \\
+\tilde{I}( f(\Theta) \Lt ) = K \times \hat{I}( f(\Theta) \Lt )              \\
+K = \frac{I(f(\Theta))}{\hat{I}(f(\Theta))}
+\end{equation}$$ 
+
+
+From the equation above we can see that $\tilde{I}$ is equivalent to $I$  when $\Lt$ is a constant,
+and yields the correct result:
+
+$$\begin{align*}
+\tilde{I}(f(\Theta)\Lt^{constant}) &= \Lt^{constant} \hat{I}(f(\Theta)) \frac{I(f(\Theta))}{\hat{I}(f(\Theta))} \\
+                                   &= \Lt^{constant} I(f(\Theta))                                               \\
+                                   &= I(f(\Theta)\Lt^{constant})
+\end{align*}$$
+
+
+Similarly, we can also demonstrate that the result is correct when $v = n$, since in that case $I = \hat{I}$:
+
+$$\begin{align*}
+\tilde{I}(f(\Theta)\Lt) &= I(f(\Theta)\Lt) \frac{I(f(\Theta))}{I(f(\Theta))}    \\
+                        &= I(f(\Theta)\Lt)
+\end{align*}$$
+
+Finally, we can show that the scale factor $K$ satisfies our average irradiance ($\bar{\Lt}$)
+requirement by plugging $\Lt = \bar{\Lt} + (\Lt - \bar{\Lt}) = \bar{\Lt} + \Delta\Lt$ into $\tilde{I}$:
+
+$$\begin{align*}
+\tilde{I}(f(\Theta)\Lt) &= \tilde{I}\left[f\left(\Theta\right) \left(\bar{\Lt} + \Delta\Lt\right)\right] \\
+                        &= K \times \hat{I}\left[f\left(\Theta\right) \left(\bar{\Lt} + \Delta\Lt\right)\right] \\
+                        &= K \times \left[\hat{I}\left(f\left(\Theta\right)\bar{\Lt}\right) + \hat{I}\left(f\left(\Theta\right)\Delta\Lt\right)\right] \\ 
+                        &= K \times \hat{I}\left(f\left(\Theta\right)\bar{\Lt}\right) + K \times \hat{I}\left(f\left(\Theta\right) \Delta\Lt\right) \\
+                        &= \tilde{I}\left(f\left(\Theta\right)\bar{\Lt}\right) + \tilde{I}\left(f\left(\Theta\right) \Delta\Lt\right) \\
+                        &= I\left(f\left(\Theta\right)\bar{\Lt}\right) + \tilde{I}\left(f\left(\Theta\right) \Delta\Lt\right)
+\end{align*}$$
+
+The above result shows that the average irradiance is computed correctly, i.e.: $I(f(\Theta)\bar{\Lt})$.
+
+A way to think about this approximation is that it splits the radiance $\Lt$ in two parts, 
+the average $\bar{\Lt}$ and the delta from the average $\Delta\Lt$ and computes the correct
+integration of the average part then adds the simplified integration of the delta part:
+
+$$\begin{equation}
+approximation(\Lt) = correct(\bar{\Lt}) + simplified(\Lt - \bar{\Lt})
+\end{equation}$$ 
+
+
+
+Now, let's look at each term:
+
+$$\begin{equation}\label{iblPartialEquations}
+\hat{I}(f(n, \alpha) \Lt) = \int_\Omega f(l, n, \alpha) \Lt(l) \left< \NoL \right> \partial l   \\
+\hat{I}(f(n, \alpha))     = \int_\Omega f(l, n, \alpha)        \left< \NoL \right> \partial l   \\
+I(f(n, v, \alpha))        = \int_\Omega f(l, n, v, \alpha)     \left< \NoL \right> \partial l
+\end{equation}$$
+
+
+All three of these equations can be easily pre-calculated and stored in look-up tables, as explained 
+below.
+ 
+
+##### Discrete Domain #####
+
+In the discrete domain the equations in \ref{iblPartialEquations} become:
+
+$$\begin{equation}
+\hat{I}(f(n, \alpha) \Lt) \equiv \frac{1}{N}\sum_{\forall \, i \in image} f(l_i, n, \alpha) \Lt(l_i) \left<\NoL\right>  \\
+\hat{I}(f(n, \alpha))     \equiv \frac{1}{N}\sum_{\forall \, i \in image} f(l_i, n, \alpha)          \left<\NoL\right>  \\
+I(f(n, v, \alpha))        \equiv \frac{1}{N}\sum_{\forall \, i \in image} f(l_i, n, v, \alpha)       \left<\NoL\right>
+\end{equation}$$
+
+However, in practice we're using _importance sampling_ which needs to take the $pdf$ of the distribution
+into account and adds a term $\frac{4\left<\VoH\right>}{D(h_i, \alpha)\left<\NoH\right>}$.
+See Importance Sampling For The IBL section:
+
+$$\begin{equation}\label{iblImportanceSampling}
+\hat{I}(f(n, \alpha) \Lt) \equiv \frac{4}{N}\sum_i^N f(l_i, n, \alpha)    \frac{\left<\VoH\right>}{D(h_i, \alpha)\left<\NoH\right>} \Lt(l_i) \left<\NoL\right>  \\
+\hat{I}(f(n, \alpha))     \equiv \frac{4}{N}\sum_i^N f(l_i, n, \alpha)    \frac{\left<\VoH\right>}{D(h_i, \alpha)\left<\NoH\right>}          \left<\NoL\right>  \\
+I(f(n, v, \alpha))        \equiv \frac{4}{N}\sum_i^N f(l_i, n, v, \alpha) \frac{\left<\VoH\right>}{D(h_i, \alpha)\left<\NoH\right>}          \left<\NoL\right>
+\end{equation}$$
+
+
+Recalling that for $\hat{I}$, we assume that $v = n$, equations \ref{iblImportanceSampling},
+simplifies to:
+
+$$\begin{equation}
+\hat{I}(f(n, \alpha) \Lt) \equiv \frac{4}{N}\sum_i^N \frac{f(l_i, n,    \alpha)}{D(h_i, \alpha)} \Lt(l_i) \left<\NoL\right>  \\
+\hat{I}(f(n, \alpha))     \equiv \frac{4}{N}\sum_i^N \frac{f(l_i, n,    \alpha)}{D(h_i, \alpha)}          \left<\NoL\right>  \\
+I(f(n, v, \alpha))        \equiv \frac{4}{N}\sum_i^N \frac{f(l_i, n, v, \alpha)}{D(h_i, \alpha)} \frac{\left<\VoH\right>}{\left<\NoH\right>} \left<\NoL\right>
+\end{equation}$$
+
+Then, the first two equations can be merged together such that $LD(n, \alpha) = \frac{\hat{I}(f(n, \alpha) \Lt)}{\hat{I}(f(n, \alpha))}$
+
+$$\begin{equation}\label{iblLD}
+LD(n, \alpha)       \equiv \frac{\sum_i^N \frac{f(l_i, n, \alpha)}{D(h_i, \alpha)} \Lt(l_i) \left<\NoL\right>}{\sum_i^N \frac{f(l_i, n, \alpha)}{D(h_i, \alpha)}\left<\NoL\right>}
+\end{equation}$$
+$$\begin{equation}\label{iblDFV}
+I(f(n, v, \alpha))  \equiv \frac{4}{N}\sum_i^N \frac{f(l_i, n, v, \alpha)}{D(h_i, \alpha)} \frac{\left<\VoH\right>}{\left<\NoH\right>} \left<\NoL\right>
+\end{equation}$$
+
+Note that at this point, we could almost compute both remaining equations off-line. The only difficulty
+is that we don't know $f_0$ nor $f_{90}$ when we precompute those integrals. We will see below that
+we can incorporate these terms at runtime for equation \ref{iblDFV}, alas, this is not possible for
+equation \ref{iblLD} and we have to assume $f_0 = f_{90} = 1$ (i.e.: the fresnel term always evaluates to 1).
+
+We also have to deal with the visibility term of the brdf, in practice keeping it yields to slightly
+worst results compared to the ground truth, so we also set $V = 1$.
+
+Let's substitute $f$ in equations \ref{iblLD} and \ref{iblDFV}:
+
+$$\begin{equation}
+f(l_i, n, \alpha) = D(h_i, \alpha)F(f_0, f_{90}, \left<\VoH\right>)V(l_i, v, \alpha)
+\end{equation}$$
+
+The first simplification is that the term $D(h_i, \alpha)$ in the brdf cancels out with the
+denominator (which came from the $pdf$ due to importance sampling) and F and V disappear since we
+assume their value is 1. 
+
+$$\begin{equation}
+LD(n, \alpha)       \equiv \frac{\sum_i^N V(l_i, v, \alpha)\left<\NoL\right>\Lt(l_i) }{\sum_i^N \left<\NoL\right>}
+\end{equation}$$
+$$\begin{equation}\label{iblFV}
+I(f(n, v, \alpha))  \equiv \frac{4}{N}\sum_i^N \color{green}{F(f_0, f_{90}, \left<\VoH\right>)} V(l_i, v, \alpha)\frac{\left<\VoH\right>}{\left<\NoH\right>} \left<\NoL\right>
+\end{equation}$$
+
+Now, let's substitute the fresnel term into equation \ref{iblFV}:
+
+$$\begin{equation}
+F(f_0, f_{90}, \left<\VoH\right>) = f_0 (1 - F_c(\left<\VoH\right>)) + f_{90} F_c(\left<\VoH\right>) \\
+F_c(\left<\VoH\right>) = (1 - \left<\VoH\right>)^5
+\end{equation}$$
+
+
+$$\begin{equation}
+I(f(n, v, \alpha))  \equiv \frac{4}{N}\sum_i^N \left[\color{green}{f_0 (1 - F_c(\left<\VoH\right>)) + f_{90} F_c(\left<\VoH\right>)}\right] V(l_i, v, \alpha)\frac{\left<\VoH\right>}{\left<\NoH\right>} \left<\NoL\right> \\
+\end{equation}$$
+
+$$
+\begin{align*}
+I(f(n, v, \alpha))  \equiv & \color{green}{f_0   } \frac{4}{N}\sum_i^N  \color{green}{(1 - F_c(\left<\VoH\right>))} V(l_i, v, \alpha)\frac{\left<\VoH\right>}{\left<\NoH\right>} \left<\NoL\right> \\
+                    +      & \color{green}{f_{90}} \frac{4}{N}\sum_i^N  \color{green}{     F_c(\left<\VoH\right>) } V(l_i, v, \alpha)\frac{\left<\VoH\right>}{\left<\NoH\right>} \left<\NoL\right>
+\end{align*}
+$$
+
+
+And finally, we extract the equations that can be calculated off-line (i.e.: the part that doesn't 
+depend on the runtime parameters $f_0$ and $f_{90}$):
+
+$$\begin{equation}\label{iblAllEquations}
+DFG_1(\alpha, \left<\NoV\right>) = \frac{4}{N}\sum_i^N  \color{green}{(1 - F_c(\left<\VoH\right>))} V(l_i, v, \alpha)\frac{\left<\VoH\right>}{\left<\NoH\right>} \left<\NoL\right> \\
+DFG_2(\alpha, \left<\NoV\right>) = \frac{4}{N}\sum_i^N  \color{green}{     F_c(\left<\VoH\right>) } V(l_i, v, \alpha)\frac{\left<\VoH\right>}{\left<\NoH\right>} \left<\NoL\right> \\
+I(f(n, v, \alpha))  \equiv   \color{green}{f_0} \color{red}{DFG_1(\alpha, \left<\NoV\right>)} + \color{green}{f_{90}} \color{red}{DFG_2(\alpha, \left<\NoV\right>)}
+\end{equation}$$
+
+
+Notice that $DFG_1$ and $DFG_2$ only depend on $\NoV$, that is the angle between the normal $n$ and
+the view direction $v$. This is true because the integral is symmetrical with respect to $n$. 
+When integrating, we can choose any $v$ we please as long as it satisfies $\NoV$ 
+(e.g.: when calculating $\VoH$).
+
+
+Putting everything back together:
+
+$$
+\begin{align*}
+\Lout(n,v,\alpha,f_0,f_{90})     &\simeq \big[ f_0 \color{red}{DFG_1(\NoV, \alpha)} + f_{90} \color{red}{DFG_2(\NoV, \alpha)} \big] \times LD(n, \alpha) \\
+DFG_1(\alpha, \left<\NoV\right>) &=      \frac{4}{N}\sum_i^N  \color{green}{(1 - F_c(\left<\VoH\right>))} V(l_i, v, \alpha)\frac{\left<\VoH\right>}{\left<\NoH\right>} \left<\NoL\right> \\
+DFG_2(\alpha, \left<\NoV\right>) &=      \frac{4}{N}\sum_i^N  \color{green}{     F_c(\left<\VoH\right>) } V(l_i, v, \alpha)\frac{\left<\VoH\right>}{\left<\NoH\right>} \left<\NoL\right> \\
+LD(n, \alpha)                    &=      \frac{\sum_i^N V(l_i, n, \alpha)\left<\NoL\right>\Lt(l_i) }{\sum_i^N \left<\NoL\right>}
+\end{align*}     
+$$
+
+#### The $DFG_1$ and $DFG_2$ term visualized ####
+
+Both $DFG_1$ and $DFG_2$ can either be pre-calculated in a regular 2D texture indexed by $(\NoV, \alpha)$ 
+and sampled bilinearly, or computed at runtime using an analytic approximation of the surfaces. 
+See sample code in the annex. 
+The pre-calculated textures are shown in table [textureDFG]. 
+A C++ implementation of the pre-computation can be found in section [Precomputing L for image-based lighting].
+
+
+$DFG_1$                  | $DFG_2$                  | ${ DFG_1, DFG_2, 0 }$
+-------------------------|--------------------------|----------------------
+![](images/ibl/dfg1.png) | ![](images/ibl/dfg2.png) | ![](images/ibl/dfg.png)
+[Table [textureDFG]: Y axis: $\alpha$. X axis: $cos \theta$]
+
+
+$DFG_1$ and $DFG_2$  are conveniently within the $[0, 1]$ range, however 8-bits textures don't have
+enough precision and will cause problems. 
+Unfortunately, on mobile, 16-bits or float textures are not ubiquitous and there are a limited 
+number of samplers. 
+Despite the attractive simplicity of the shader code using a texture, it might be better to use an 
+analytic approximation. Note however that since we only need to store two terms, 
+OpenGL ES 3.0's RG16F texture format is a good candidate.
+
+Such analytic approximation is described in [#Karis14], itself based on [#Lazarov13]. 
+[#Narkowicz14] is another interesting approximation. Note that these two approximations are not
+compatible with the energy compensation term presented in section [Pre-integration for multiscattering].
+Table [textureApproxDFG] presents a visual representation of these approximations.
+
+$DFG_1$                         | $DFG_2$                         | ${ DFG_1, DFG_2, 0 }$
+--------------------------------|---------------------------------|----------------------
+![](images/ibl/dfg1_approx.png) | ![](images/ibl/dfg2_approx.png) | ![](images/ibl/dfg_approx.png)
+[Table [textureApproxDFG]: Y axis: $\alpha$. X axis: $cos \theta$]
+
+
+#### The $LD$ term visualized ####
+
+$LD$ is the convolution of the environment by a function that only depends on the $\alpha$ parameter
+(itself related to the roughness, see section [Roughness remapping and clamping]).
+$LD$ can conveniently be stored in a mip-mapped cubemap where increasing LODs receive the environment
+pre-filtered with increasing roughness. This works well because this convolution is a
+powerful low-pass filter. To make good use of each mipmap level, it is necessary to remap
+$\alpha$; we find that using a power remapping with $\gamma = 2$ works well and is convenient.
+
+$$
+\begin{align*}
+    \alpha       &= perceptualRoughness^2                        \\
+    lod_{\alpha} &= \alpha^{\frac{1}{2}} = perceptualRoughness   \\
+\end{align*}
+$$
+
+See an example below:
+
+
+![$\alpha=0.0$](images/ibl/ibl_river_roughness_m0.png style="max-width:100%;")
+![$\alpha=0.2$](images/ibl/ibl_river_roughness_m1.png style="max-width:100%;")
+![$\alpha=0.4$](images/ibl/ibl_river_roughness_m2.png style="max-width:100%;")
+![$0.6$](images/ibl/ibl_river_roughness_m3.png style="max-width:100%;")
+![$0.8$](images/ibl/ibl_river_roughness_m4.png style="max-width:100%;")
+
+#### Indirect specular and indirect diffuse components visualized ####
+
+Figure [iblVisualized] shows how indirect lighting interacts with dielectrics and conductors. Direct lighting was removed for illustration purposes.
+
+![Figure [iblVisualized]: Indirect diffuse and specular decomposition](images/ibl/ibl_visualization.jpg)
+
+#### IBL evaluation implementation ####
+
+Listing [iblEvaluation] presents a GLSL implementation to evaluate the IBL, using the various textures described in the previous sections. 
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+vec3 ibl(vec3 n, vec3 v, vec3 diffuseColor, vec3 f0, vec3 f90,
+        float perceptualRoughness) {
+    vec3 r = reflect(n);
+    vec3 Ld = textureCube(irradianceEnvMap, r) * diffuseColor;
+    float lod = computeLODFromRoughness(perceptualRoughness);
+    vec3 Lld = textureCube(prefilteredEnvMap, r, lod);
+    vec2 Ldfg = textureLod(dfgLut, vec2(dot(n, v), perceptualRoughness), 0.0).xy;
+    vec3 Lr =  (f0 * Ldfg.x + f90 * Ldfg.y) * Lld;
+    return Ld + Lr;
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+[Listing [iblEvaluation]: GLSL implementation of image based lighting evaluation]
+
+We can however save a couple of texture lookups by using Spherical Harmonics instead of an 
+irradiance cubemap and the analytical approximation of the $DFG$ LUT, as shown in listing [optimizedIblEvaluation].
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+vec3 irradianceSH(vec3 n) {
+    // uniform vec3 sphericalHarmonics[9]
+    // We can use only the first 2 bands for better performance
+    return
+          sphericalHarmonics[0]
+        + sphericalHarmonics[1] * (n.y)
+        + sphericalHarmonics[2] * (n.z)
+        + sphericalHarmonics[3] * (n.x)
+        + sphericalHarmonics[4] * (n.y * n.x)
+        + sphericalHarmonics[5] * (n.y * n.z)
+        + sphericalHarmonics[6] * (3.0 * n.z * n.z - 1.0)
+        + sphericalHarmonics[7] * (n.z * n.x)
+        + sphericalHarmonics[8] * (n.x * n.x - n.y * n.y);
+}
+
+// NOTE: this is the DFG LUT implementation of the function above
+vec2 prefilteredDFG_LUT(float coord, float NoV) {
+    // coord = sqrt(roughness), which is the mapping used by the
+    // IBL prefiltering code when computing the mipmaps
+    return textureLod(dfgLut, vec2(NoV, coord), 0.0).rg;
+}
+
+vec3 evaluateSpecularIBL(vec3 r, float perceptualRoughness) {
+    // This assumes a 256x256 cubemap, with 9 mip levels
+    float lod = 8.0 * perceptualRoughness;
+    // decodeEnvironmentMap() either decodes RGBM or is a no-op if the
+    // cubemap is stored in a float texture
+    return decodeEnvironmentMap(textureCubeLodEXT(environmentMap, r, lod));
+}
+
+vec3 evaluateIBL(vec3 n, vec3 v, vec3 diffuseColor, vec3 f0, vec3 f90, float perceptualRoughness) {
+    float NoV = max(dot(n, v), 0.0);
+    vec3 r = reflect(-v, n);
+
+    // Specular indirect
+    vec3 indirectSpecular = evaluateSpecularIBL(r, perceptualRoughness);
+    vec2 env = prefilteredDFG_LUT(perceptualRoughness, NoV);
+    vec3 specularColor = f0 * env.x + f90 * env.y;
+
+    // Diffuse indirect
+    // We multiply by the Lambertian BRDF to compute radiance from irradiance
+    // With the Disney BRDF we would have to remove the Fresnel term that
+    // depends on NoL (it would be rolled into the SH). The Lambertian BRDF
+    // can be baked directly in the SH to save a multiplication here
+    vec3 indirectDiffuse = max(irradianceSH(n), 0.0) * Fd_Lambert();
+
+    // Indirect contribution
+    return diffuseColor * indirectDiffuse + indirectSpecular * specularColor;
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+[Listing [optimizedIblEvaluation]: GLSL implementation of image based lighting evaluation]
+
+
+#### Pre-integration for multiscattering ####
+
+In section [Energy loss in specular reflectance] we discussed how to use a second scaled specular lobe 
+to compensate for the energy loss due to only accounting for a single scattering event in our BRDF.
+This energy compensation lobe is scaled by a term that depends on $r$ defined in the following way:
+
+$$\begin{equation}
+r = \int_{\Omega} D(l,v) V(l,v) \left< \NoL \right> \partial l
+\end{equation}$$
+
+Or, evaluated with importance sampling (See Importance Sampling For The IBL section):
+
+$$\begin{equation}
+r \equiv  \frac{4}{N}\sum_i^N  V(l_i, v, \alpha)\frac{\left<\VoH\right>}{\left<\NoH\right>} \left<\NoL\right>
+\end{equation}$$
+
+This equality is very similar to the terms $DFG_1$ and $DFG_2$ seen in equation $\ref{iblAllEquations}$.
+In fact, it's the same, except without the Fresnel term.
+
+By making the further assumption that $f_{90} = 1$, we can rewrite $DFG_1$ and $DFG_2$ and the
+$\Lout$ reconstruction:
+
+$$
+\begin{align*}
+\Lout(n,v,\alpha,f_0)                           &\simeq \big[ (1 - f_0) \color{red}{DFG_1^{multiscatter}(\NoV, \alpha)} + f_0 \color{red}{DFG_2^{multiscatter}(\NoV, \alpha)} \big] \times LD(n, \alpha) \\
+DFG_1^{multiscatter}(\alpha, \left<\NoV\right>) &=      \frac{4}{N}\sum_i^N  \color{green}{F_c(\left<\VoH\right>)} V(l_i, v, \alpha)\frac{\left<\VoH\right>}{\left<\NoH\right>} \left<\NoL\right> \\
+DFG_2^{multiscatter}(\alpha, \left<\NoV\right>) &=      \frac{4}{N}\sum_i^N                                        V(l_i, v, \alpha)\frac{\left<\VoH\right>}{\left<\NoH\right>} \left<\NoL\right> \\
+LD(n, \alpha)                                   &=      \frac{\sum_i^N V(l_i, n, \alpha)\left<\NoL\right>\Lt(l_i) }{\sum_i^N V(l_i, n, \alpha)\left<\NoL\right>}
+\end{align*}     
+$$
+
+These two new $DFG$ terms simply need to replace the ones used in the implementation shown in section [Precomputing L for image-based lighting]:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+float Fc = pow(1 - VoH, 5.0f);
+r.x += Gv * Fc;
+r.y += Gv;
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+[Listing [multiscatterIBLPreintegration]: C++ implementation of the $L_{DFG}$ term for multiscattering]
+
+To perform the reconstruction we need to slightly modify listing [multiscatterIBLEvaluation]:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+vec2 dfg = textureLod(dfgLut, vec2(dot(n, v), perceptualRoughness), 0.0).xy;
+// (1 - f0) * dfg.x + f0 * dfg.y
+vec3 specularColor = mix(dfg.xxx, dfg.yyy, f0);
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+[Listing [multiscatterIBLEvaluation]: GLSL implementation of image based lighting evaluation, with multiscattering LUT]
+
+
+#### Summary ####
+
+In order to calculate the specular contribution of distant image-based lights, we had to make a few
+approximations and compromises:
+
+    - $v = n$, by far the assumption contributing to the largest error when integrating the
+      non-constant part of the IBL. This results in the complete loss of roughness anisotropy
+      with respect to the view point.
+
+    - Roughness contribution for the non-constant part of the IBL is quantized and trilinear filtering
+      is used to interpolate between these levels. This is most visible at low roughnes (e.g.: around 0.0625
+      for a 9 LODs cubemap).
+
+    - Because mipmap levels are used to store the pre-integrated environment, they can't be used for
+      texture minification, as they ought to. This can causes aliasing or moiré artifacts in high frequency 
+      regions or the environment at low roughness and/or distant or small objects. 
+      This can also impact performance due to the resulting poor cache access pattern. 
+
+    - No Fresnel for the non-constant part of the IBL.
+
+    - Visibility = 1 for the non-constant part of the IBL.
+
+    - Schlick's Fresnel
+
+    - $f_{90} = 1$ in the multiscattering case.
+
+
+![Figure [iblPrefilterVsImportanceSampling]:
+Comparison between importance-sampled reference (top) and prefiltered IBL (middle).](images/ibl/ibl_prefilter_vs_reference.png)
+
+![Figure [iblStretchyReflectionLoss]:
+Error in reflections due to assuming $v = n$ (bottom) -- loss of "stretchy reflections".](images/ibl/ibl_stretchy_reflections_error.png)
+
+![Figure [iblRoughnessInLods0]:
+Error due to storing the roughness in cubemaps LODs at roughness = 0.0625 (i.e.: sampling exactly between levels).
+Notice how instead of bluring we see a "cross-fade" between two blurs.](images/ibl/ibl_trilinear_0.png)
+
+![Figure [iblRoughnessInLods1]:
+Error due to storing the roughness in cubemaps LODs at roughness = 0.125 (i.e.: sampling exactly level 1).
+When the roughness closely matches a LOD, the error due to trilinear filtering in the cubemap is
+reduced. Notice the errors due to $v = n$ at grazing angles.](images/ibl/ibl_trilinear_1.png)
+
+![Figure [iblMoirePattern]:
+Moiré pattern due to texture minification on a metallic sphere at $\alpha = 0$
+using an environment made of colored vertical stripes (skybox hidden).](images/ibl/ibl_no_mipmaping.png)
+
+
+### Clear coat ###
+
+When sampling the IBL, the clear coat layer is calculated as a second specular lobe. This specular lobe is oriented along the view direction since we cannot reasonably integrate over the hemisphere. Listing [clearCoatIBL] demonstrates this approximation in practice. It also shows the energy conservation step. It is important to note that this second specular lobe is computed exactly the same way as the main specular lobe, using the same DFG approximation.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+// clearCoat_NoV == shading_NoV if the clear coat layer doesn't have its own normal map
+float Fc = F_Schlick(0.04, 1.0, clearCoat_NoV) * clearCoat;
+// base layer attenuation for energy compensation
+iblDiffuse  *= 1.0 - Fc;
+iblSpecular *= sq(1.0 - Fc);
+iblSpecular += specularIBL(r, clearCoatPerceptualRoughness) * Fc;
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+[Listing [clearCoatIBL]: GLSL implementation of the clear coat specular lobe for image-based lighting]
+
+### Anisotropy ###
+
+[#McAuley15] describes a technique called “bent reflection vector”, based [#Revie12]. The bent reflection vector is a rough approximation of anisotropic lighting but the alternative is to use importance sampling. This approximation is sufficiently cheap to compute and provides good results, as shown in figure [anisotropicIBL1] and figure [anisotropicIBL2].
+
+![Figure [anisotropicIBL1]: Anisotropic indirect specular reflections using bent normals (left: roughness 0.3, right: roughness: 0.0; both: anisotropy 1.0)](images/screenshot_anisotropic_ibl1.jpg)
+
+![Figure [anisotropicIBL2]: Anisotropic reflections with varying roughness, metallicness, etc.](images/screenshot_anisotropic_ibl2.jpg)
+
+The implementation of this technique is straightforward, as demonstrated in listing [bentReflectionVector].
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+vec3 anisotropicTangent = cross(bitangent, v);
+vec3 anisotropicNormal = cross(anisotropicTangent, bitangent);
+vec3 bentNormal = normalize(mix(n, anisotropicNormal, anisotropy));
+vec3 r = reflect(-v, bentNormal);
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+[Listing [bentReflectionVector]: GLSL implementation of the bent reflection vector]
+
+This technique can be made more useful by accepting negative `anisotropy` values, as shown in listing [bentReflectionVectorDirection]. When the anisotropy is negative, the highlights are not in the direction of the tangent, but in the direction of the bitangent instead.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+vec3 anisotropicDirection = anisotropy >= 0.0 ? bitangent : tangent;
+vec3 anisotropicTangent = cross(anisotropicDirection, v);
+vec3 anisotropicNormal = cross(anisotropicTangent, anisotropicDirection);
+vec3 bentNormal = normalize(mix(n, anisotropicNormal, anisotropy));
+vec3 r = reflect(-v, bentNormal);
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+[Listing [bentReflectionVectorDirection]: GLSL implementation of the bent reflection vector]
+
+Figure [anisotropicDirection] demonstrates this modified implementation in practice.
+
+![Figure [anisotropicDirection]: Control of the anisotropy direction using positive (left) and negative (right) values](images/screenshot_anisotropy_direction.png)
+
+### Subsurface ###
+
+[TODO] Explain subsurface and IBL
+
+### Cloth ###
+
+The IBL implementation for the cloth material model is more complicated than for the other material models. The main difference stems from the use of a different NDF ("Charlie" vs height-correlated Smith GGX). As described in this section, we use the split-sum approximation to compute the DFG term of the BRDF when computing an IBL. This DFG term is designed for a different BRDF and cannot be used for the cloth BRDF. Since we designed our  cloth BRDF to not need a Fresnel term, we can generate a single DG term in the 3rd channel of the DFG LUT. The result is shown in figure [dfgClothLUT].
+
+The DG term is generated using uniform sampling as recommended in [#Estevez17]. With uniform sampling the $pdf$ is simply $\frac{1}{2\pi}$ and we must still use the Jacobian $\frac{1}{4\left< \VoH \right>}$.
+
+![Figure [dfgClothLUT]: DFG LUT with a 3rd channel encoding the DG term of the cloth BRDF](images/ibl/dfg_cloth.png)
+
+The remainder of the image-based lighting implementation follows the same steps as the implementation of regular lights, including the optional subsurface scattering term and its wrap diffuse component. Just as with the clear coat IBL implementation, we cannot integrate over the hemisphere and use the view direction as the dominant light direction to compute the wrap diffuse component.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+float diffuse = Fd_Lambert() * ambientOcclusion;
+#if defined(SHADING_MODEL_CLOTH)
+#if defined(MATERIAL_HAS_SUBSURFACE_COLOR)
+diffuse *= saturate((NoV + 0.5) / 2.25);
+#endif
+#endif
+
+vec3 indirectDiffuse = irradianceIBL(n) * diffuse;
+#if defined(SHADING_MODEL_CLOTH) && defined(MATERIAL_HAS_SUBSURFACE_COLOR)
+indirectDiffuse *= saturate(subsurfaceColor + NoV);
+#endif
+
+vec3 ibl = diffuseColor * indirectDiffuse + indirectSpecular * specularColor;
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+[Listing [clothApprox]: GLSL implementation of the DFG approximation for the cloth NDF]
+
+It is important to note that this only addresses part of the IBL problem. The pre-filtered specular environment maps described earlier are convolved with the standard shading model's BRDF, which differs from the cloth BRDF. To get accurate result we should in theory provide one set of IBLs per BRDF used in the engine. Providing a second set of IBLs is however not practical for our use case so we decided to rely on the existing IBLs instead.
+
+## Static lighting
+
+[TODO] Spherical-harmonics or spherical-gaussian lightmaps, irradiance volumes, PRT?…
+
+## Transparency and translucency lighting
+
+Transparent and translucent materials are important to add realism and correctness to scenes. Filament must therefore provide lighting models for both types of materials to allow artists to properly recreate realistic scenes. Translucency can also be used effectively in a number of non-realistic settings.
+
+### Transparency
+
+To properly light a transparent surface, we must first understand how the material's opacity is applied. Observe a window and you will see that the diffuse reflectance is transparent. On the other hand, the brighter the specular reflectance, the less opaque the window appears. This effect can be seen in figure [cameraTransparency]: the scene is properly reflected onto the glass surfaces but the specular highlight of the sun is bright enough to appear opaque.
+
+![Figure [cameraTransparency]: Example of a complex object where lit surface transparency plays an important role](images/screenshot_camera_transparency.jpg)
+
+![Figure [litCar]: Example of a complex object where lit surface transparency plays an important role](images/screenshot_car.jpg)
+
+To properly implement opacity, we will use the premultiplied alpha format. Given a desired opacity noted $ \alpha_{opacity} $ and a diffuse color $ \sigma $ (linear, unpremultiplied), we can compute the effective opacity of a fragment.
+
+$$\begin{align*}
+color &= \sigma * \alpha_{opacity} \\
+opacity &= \alpha_{opacity}
+\end{align*}$$
+
+The physical interpretation is that the RGB components of the source color define how much light is emitted by the pixel, whereas the alpha component defines how much of the light behind the pixel is blocked by said pixel. We must therefore use the following blending functions:
+
+$$\begin{align*}
+Blend_{src} &= 1 \\
+Blend_{dst} &= 1 - src_{\alpha}
+\end{align*}$$
+
+The GLSL implementation of these equations is presented in listing [surfaceTransparency].
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+// baseColor has already been premultiplied
+vec4 shadeSurface(vec4 baseColor) {
+    float alpha = baseColor.a;
+
+    vec3 diffuseColor = evaluateDiffuseLighting();
+    vec3 specularColor = evaluateSpecularLighting();    
+
+    return vec4(diffuseColor + specularColor, alpha);
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+[Listing [surfaceTransparency]: Implementation of lit surface transparency in GLSL]
+
+### Translucency
+
+Translucent materials can be divided into two categories:
+- Surface translucency
+-  Volume translucency
+
+Volume translucency is useful to light particle systems, for instance clouds or smoke. Surface translucency can be used to imitate materials with transmitted scattering such as wax, marble, skin, etc.
+
+[TODO] Surface translucency (BRDF+BTDF, BSSRDF)
+
+![Figure [translucency]: Front-lit translucent object (left) and back-lit translucent object (right), using approximated BTDF and BSSRDF. Model: Lucy from the Stanford University Computer Graphics Laboratory](images/screenshot_translucency.png)
+
+## Occlusion
+
+Occlusion is an important darkening factor used to recreate shadowing at various scales:
+
+Small&nbsp;scale
+:   Micro-occlusion used to handle creases, cracks and cavities.
+
+Medium&nbsp;scale
+:   Macro-occlusion used to handle occlusion by an object's own geometry or by geometry baked in normal maps (bricks, etc.).
+
+Large&nbsp;scale
+:   Occlusion coming from contact between objects, or from an object's own geometry.
+
+We currently ignore micro-occlusion, which is often exposed in tools and engines under the form of a "cavity map". Sébastien Lagarde offers an interesting discussion in [#Lagarde14] on how micro-occlusion is handled in Frostbite: diffuse micro-occlusion is pre-baked in diffuse maps and specular micro-occlusion is pre-baked in reflectance textures.
+In our system, micro-occlusion can simply be baked in the base color map. This must be done knowing that the specular light will not be affected by micro-occlusion.
+
+Medium scale ambient occlusion is pre-baked in ambient occlusion maps, exposed as a material parameter, as seen in the material parameterization section earlier.
+
+Large scale ambient occlusion is often computed using screen-space techniques such as *SSAO* (screen-space ambient occlusion), *HBAO* (horizon based ambient occlusion), etc. Note that these techniques can also contribute to medium scale ambient occlusion when the camera is close enough to surfaces.
+
+**Note**: to prevent over darkening when using both medium and large scale occlusion, Lagarde recommends to use $min({AO}_{medium}, {AO}_{large})$.
+
+### Diffuse occlusion
+
+Morgan McGuire formalizes ambient occlusion in the context of physically based rendering in [#McGuire10]. In his formulation, McGuire defines an ambient illumination function $ L_a $, which in our case is encoded with spherical harmonics. He also defines a visibility function $V$, with $V(l)=1$ if there is an unoccluded line of sight from the surface in direction $l$, and 0 otherwise.
+
+With these two functions, the ambient term of the rendering equation can be expressed as shown in equation $\ref{diffuseAO}$.
+
+$$\begin{equation}\label{diffuseAO}
+L(l,v) = \int_{\Omega} f(l,v) L_a(l) V(l) \left< \NoL \right> dl
+\end{equation}$$
+
+This expression can be approximated by separating the visibility term from the illumination function, as shown in equation $\ref{diffuseAOApprox}$.
+
+$$\begin{equation}\label{diffuseAOApprox}
+L(l,v) \approx \left( \pi \int_{\Omega} f(l,v) L_a(l) dl \right) \left( \frac{1}{\pi} \int_{\Omega} V(l) \left< \NoL \right> dl \right)
+\end{equation}$$
+
+This approximation is only exact when the distant light $ L_a $ is constant and $f$ is a Lambertian term. McGuire states however that this approximation is reasonable if both functions are relatively smooth over most of the sphere. This happens to be the case with a distant light probe (IBL).
+
+The left term of this approximation is the pre-computed diffuse component of our IBL. The right term is a scalar factor between 0 and 1 that indicates the fractional accessibility of a point. Its opposite is the diffuse ambient occlusion term, show in equation $\ref{diffuseAOTerm}$.
+
+$$\begin{equation}\label{diffuseAOTerm}
+{AO} = 1 - \frac{1}{\pi} \int_{\Omega} V(l) \left< \NoL \right> dl
+\end{equation}$$
+
+Since we use a pre-computed diffuse term, we cannot compute the exact accessibility of shaded points at runtime. To compensate for this lack of information in our precomputed term, we partially reconstruct incident lighting by applying an ambient occlusion factor specific to the surface's material at the shaded point.
+
+In practice, baked ambient occlusion is stored as a grayscale texture which can often be lower resolution than other textures (base color or normals for instance). It is important to note that the ambient occlusion property of our material model intends to recreate macro-level diffuse ambient occlusion. While this approximation is not physically correct, it constitutes an acceptable tradeoff of quality vs performance.
+
+Figure [aoComparison] shows two different materials without and with diffuse ambient occlusion. Notice how the material ambient occlusion is used to recreate the natural shadowing that occurs between the different tiles. Without ambient occlusion, both materials appear too flat.
+
+![Figure [aoComparison]: Comparison of materials without diffuse ambient occlusion (left) and with (right)](images/screenshot_ao.jpg)
+
+Applying baked diffuse ambient occlusion in a GLSL shader is straightforward, as shown in listing [bakedDiffuseAO].
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+// diffuse indirect
+vec3 indirectDiffuse = max(irradianceSH(n), 0.0) * Fd_Lambert();
+// ambient occlusion
+indirectDiffuse *= texture2D(aoMap, outUV).r;
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+[Listing [bakedDiffuseAO]: Implementation of baked diffuse ambient occlusion in GLSL]
+
+Note how the ambient occlusion term is only applied to indirect lighting.
+
+### Specular occlusion
+
+Specular micro-occlusion can be derived from $\fNormal$, itself derived from the diffuse color. The derivation is based on the knowledge that no real-world material has a reflectance lower than 2%. Values in the 0-2% range can therefore be treated as pre-baked specular occlusion used to smoothly extinguish the Fresnel term.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+float f90 = clamp(dot(f0, 50.0 * 0.33), 0.0, 1.0);
+// cheap luminance approximation
+float f90 = clamp(50.0 * f0.g, 0.0, 1.0);
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+[Listing [specularMicroOcclusion]: Pre-baked specular occlusion in GLSL]
+
+The derivations mentioned earlier for ambient occlusion assume Lambertian surfaces and are only valid for indirect diffuse lighting. The lack of information about surface accessibility is particularly harmful to the reconstruction of indirect specular lighting. It usually manifests itself as light leaks.
+
+Sébastien Lagarde proposes an empirical approach to derive the specular occlusion term from the diffuse occlusion term in [#Lagarde14]. The result does not have any physical basis but produces visually pleasant results. The goal of his formulation is return the diffuse occlusion term unmodified for rough surfaces. For smooth surfaces, the formulation, implemented in listing [specularOcclusion], reduces the influence of occlusion at normal incidence and increases it at grazing angles.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+float computeSpecularAO(float NoV, float ao, float roughness) {
+    return clamp(pow(NoV + ao, exp2(-16.0 * roughness - 1.0)) - 1.0 + ao, 0.0, 1.0);
+}
+
+// specular indirect
+vec3 indirectSpecular = evaluateSpecularIBL(r, perceptualRoughness);
+// ambient occlusion
+float ao = texture2D(aoMap, outUV).r;
+indirectSpecular *= computeSpecularAO(NoV, ao, roughness);
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+[Listing [specularOcclusion]: Implementation of Lagarde's specular occlusion factor in GLSL]
+
+Note how the specular occlusion factor is only applied to indirect lighting.
+
+#### Horizon specular occlusion
+
+When computing the specular IBL contribution for a surface that uses a normal map, it is possible to end up with a reflection vector pointing towards the surface. If this reflection vector is used for shading directly, the surface will be lit in places where it should not be lit (assuming opaque surfaces). This is another occurrence of light leaking that can easily be minimized using a simple technique described by Jeff Russell [#Russell15].
+
+The key idea is to occlude light coming from behind the surface. This can easily be achieved since a negative dot product between the reflected vector and the surface's normal indicates a reflection vector pointing towards the surface. Our implementation shown in listing [horizonOcclusion] is similar to Russell's, albeit without the artist controlled horizon fading factor.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+// specular indirect
+vec3 indirectSpecular = evaluateSpecularIBL(r, perceptualRoughness);
+
+// horizon occlusion with falloff, should be computed for direct specular too
+float horizon = min(1.0 + dot(r, n), 1.0);
+indirectSpecular *= horizon * horizon;
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+[Listing [horizonOcclusion]: Implementation of horizon specular occlusion in GLSL]
+
+Horizon specular occlusion fading is cheap but can easily be omitted to improve performance as needed.
+
+## Normal mapping
+
+There are two common use cases of normal maps: replacing high-poly meshes with low-poly meshes (using a base map) and adding surface details (using a detail map).
+
+Let's imagine that we want to render a piece of furniture covered in tufted leather. Modeling the geometry to accurately represent the tufted pattern would require too many triangles so we instead bake a high-poly mesh into a normal map. Once the base map is applied to a simplified mesh (in this case, a quad), we get the result in figure [normalMapped]. The base map used to create this effect is shown in figure [baseNormalMap].
+
+![Figure [normalMapped]: Low-poly mesh without normal mapping (left) and with (right)](images/screenshot_normal_mapping.jpg)
+
+![Figure [baseNormalMap]: Normal map used as a base map](images/screenshot_normal_map.jpg)
+
+A simple problem arises if we now want to combine this base map with a second normal map. For instance, let's use the detail map shown in figure [detailNormalMap] to add cracks in the leather.
+
+![Figure [detailNormalMap]: Normal map used as a detail map](images/screenshot_normal_map_detail.jpg)
+
+Given the nature of normal maps (XYZ components stored in tangent space), it is fairly obvious that naive approaches such as linear or overlay blending cannot work. We will use two more advanced techniques: a mathematically correct one and an approximation suitable for real-time shading.
+
+### Reoriented normal mapping
+
+Colin Barré-Brisebois and Stephen Hill propose in [#Hill12] a mathematically sound solution called *Reoriented Normal Mapping*, which consists in rotating the basis of the detail map onto the normal from the base map. This technique relies on the shortest arc quaternion to apply the rotation, which greatly simplifies thanks to the properties of the tangent space.
+
+Following the simplifications described in [#Hill12], we can produce the GLSL implementation shown in listing [reorientedNormalMapping].
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+vec3 t = texture(baseMap,   uv).xyz * vec3( 2.0,  2.0, 2.0) + vec3(-1.0, -1.0,  0.0);
+vec3 u = texture(detailMap, uv).xyz * vec3(-2.0, -2.0, 2.0) + vec3( 1.0,  1.0, -1.0);
+vec3 r = normalize(t * dot(t, u) - u * t.z);
+return r;
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+[Listing [reorientedNormalMapping]: Implementation of reoriented normal mapping in GLSL]
+
+Note that this implementation assumes that the normals are stored uncompressed and in the [0..1] range in the source textures.
+
+The normalization step is not strictly necessary and can be skipped if the technique is used at runtime. If so, the computation of `r` becomes `t * dot(t, u) / t.z - u`.
+
+Since this technique is slightly more expensive than the one described below, we will mostly use it offline. We therefore provide a simple offline tool to combine two normal maps. Figure [blendedNormalMaps] presents the output of the tool with the base map and the detail map shown previously.
+
+![Figure [blendedNormalMaps]: Blended normal and detail map (left) and resulting render when combined with a diffuse map (right)](images/screenshot_normal_map_blended.jpg)
+
+### UDN blending
+
+The technique called UDN blending, described in [#Hill12], is a variant of the partial derivative blending technique. Its main advantage is the low number of shader instructions it requires (see listing [udnBlending]). While it leads to a reduction in details over flat areas, UDN blending is interesting if blending must be performed at runtime.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+vec3 t = texture(baseMap,   uv).xyz * 2.0 - 1.0;
+vec3 u = texture(detailMap, uv).xyz * 2.0 - 1.0;
+vec3 r = normalize(t.xy + u.xy, t.z);
+return r;
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+[Listing [udnBlending]: Implementation of UDN blending in GLSL]
+
+The results are visually close to Reoriented Normal Mapping but a careful comparison of the data shows that UDN is indeed less correct. Figure [blendedNormalMapsUDN] presents the result of the UDN blending approach using the same source data as in the previous examples.
+
+![Figure [blendedNormalMapsUDN]: Blended normal and detail map using the UDN blending technique](images/screenshot_normal_map_blended_udn.jpg)
+
+# Volumetric effects
+
+## Exponential height fog
+
+![Figure [exponentialHeightFog1]: Example of directional in-scattering with exponential height fog](images/screenshot_fog1.jpg)
+
+![Figure [exponentialHeightFog2]: Example of directional in-scattering with exponential height fog](images/screenshot_fog2.jpg)
+
+# Anti-aliasing
+
+[TODO] MSAA, geometric AA (normals and roughness), shader anti-aliasing (object-space shading?)
+
+# Imaging pipeline
+
+The lighting section of this document describes how light interacts with surfaces in the scene in a physically based manner. To achieve plausible results, we must go a step further and consider the transformations necessary to convert the scene luminance, as computed by our lighting equations, into displayable pixel values.
+
+The series of transformations we are going to use form the following imaging pipeline:
+
+*************************************************************************************
+* .-------------.      .--------------.      .---------------.                      *
+* |    Scene    |      |  Normalized  |      |               |                      *
+* |  luminance  +----->|  luminance   +----->| White balance |                      *
+* |             |      |    (HDR)     |      |               |                      *
+* '-------------'      '--------------'      '-------+-------'                      *
+*                                                    |                              *
+*                                                    v                              *
+*                                            .---------------.                      *
+*                                            |               |                      *
+*                                            | Color grading |                      *
+*                                            |               |                      *
+*                                            '-------+-------'                      *
+*                                                    |                              *
+*                                                    v                              *
+*                                            .---------------.                      *
+*                                            |               |                      *
+*                                            | Tone mapping  |                      *
+*                                            |               |                      *
+*                                            '-------+-------'                      *
+*                                                    |                              *
+*                                                    v                              *
+*                                            .---------------.      .-------------. *
+*                                            |               |      |    Pixel    | *
+*                                            |     OETF      +----->|    value    | *
+*                                            |               |      |    (LDR)    | *
+*                                            '---------------'      '-------------' *
+*************************************************************************************
+
+**Note**: the *OETF* step is the application of the opto-electronic transfer function of the target color space. For clarity this diagram does not include post-processing steps such as vignette, bloom, etc. These effects will be discussed separately.
+
+[TODO] Color spaces (ACES, sRGB, Rec. 709, Rec. 2020, etc.), gamma/linear, etc.
+
+## Physically based camera
+
+The first step in the image transformation process is to use a physically based camera to properly expose the scene's outgoing luminance.
+
+### Exposure settings
+
+Because we use photometric units throughout the lighting pipeline, the light reaching the camera is an energy expressed in luminance $L$, in $cd.m^{-2}$. Light incident to the camera sensor can cover a large range of values, from $10^{-5}cd.m^{-2}$ for starlight to $10^{9}cd.m^{-2}$ for the sun. Since we obviously cannot manipulate and even less record such a large range of values, we need to remap them.
+
+This range remapping is done in a camera by exposing the sensor for a certain time. To maximize the use of the limited range of the sensor, the scene's light range is centered around the "middle gray", a value halfway between black and white. The exposition is therefore achieved by manipulating, either manually or automatically, 3 settings:
+
+- Aperture
+- Shutter speed
+- Sensitivity (also called gain)
+
+Aperture
+:   Noted $N$ and expressed in f-stops ƒ, this setting controls how open or closed the camera system's aperture is. Since an f-stop indicate the ratio of the lens' focal length to the diameter of the entrance pupil, high-values (ƒ/16) indicate a small aperture and small values (ƒ/1.4) indicate a wide aperture. In addition to the exposition, the aperture setting controls the depth of field.
+
+Shutter speed
+:   Noted $t$ and expressed in seconds $s$, this setting controls how long the aperture remains opened (it also controls the timing of the sensor shutter(s), whether electronic or mechanical). In addition to the exposition, the shutter speed controls motion blur.
+
+Sensitivity
+:   Noted $S$ and expressed in ISO, this setting controls how the light reaching the sensor is quantized. Because of its unit, this setting is often referred to as simply the "ISO" or "ISO setting". In addition to the exposition, the sensitivity setting controls the amount of noise.
+
+### Exposure value
+
+Since referring to these 3 settings in our equations would be unwieldy, we instead summarize the “exposure triangle” by an exposure value, noted EV[^reciprocity].
+
+The EV is expressed in a base-2 logarithmic scale, with a difference of 1 EV called a stop. One positive stop (+1 EV) corresponds to a factor of two in luminance and one negative stop (-1 EV) corresponds to a factor of half in luminance.
+
+Equation $ \ref{ev} $ shows the [formal definition of EV](https://en.wikipedia.org/wiki/Exposure_value).
+
+$$\begin{equation}\label{ev}
+EV = log_2(\frac{N^2}{t})
+\end{equation}$$
+
+Note that this definition is only function of the aperture and shutter speed, but not the sensitivity. An exposure value is by convention defined for ISO 100, or $ EV_{100} $, and because we wish to work with this convention, we need to be able to express $ EV_{100} $ as a function of the sensitivity.
+
+Since we know that EV is a base-2 logarithmic scale in which each stop increases or decreases the brightness by a factor of 2, we can formally define $ EV_{S} $, the exposure value at given sensitivity (equation $\ref{evS}$).
+
+$$\begin{equation}\label{evS}
+{EV}_S = EV_{100} + log_2(\frac{S}{100})
+\end{equation}$$
+
+Calculating the $ EV_{100} $ as a function of the 3 camera settings is trivial, as shown in $\ref{ev100}$.
+
+$$\begin{equation}\label{ev100}
+{EV}_{100} = EV_{S} - log_2(\frac{S}{100}) = log_2(\frac{N^2}{t}) - log_2(\frac{S}{100})
+\end{equation}$$
+
+Note that the operator (photographer, etc.) can achieve the same exposure (and therefore EV) with several combinations of aperture, shutter speed and sensitivity. This allows some artistic control in the process (depth of field vs motion blur vs grain).
+
+[^reciprocity]: We assume a digital sensor, which means we don't need to take reciprocity failure into account
+
+#### Exposure value and luminance
+
+A camera, similar to a spot meter, is able to measure the average luminance of a scene and convert it into EV to achieve automatic exposure, or at the very least offer the user exposure guidance.
+
+It is possible to define EV as a function of the scene luminance $L$, given a per-device calibration constant $K$ (equation $ \ref{evK} $).
+
+$$\begin{equation}\label{evK}
+EV = log_2(\frac{L \times S}{K})
+\end{equation}$$
+
+That constant $K$ is the reflected-light meter constant, which varies between manufacturers. We could find two common values for this constant: 12.5, used by Canon, Nikon and Sekonic, and 14, used by Pentax and Minolta. Given the wide availability of Canon and Nikon cameras, as well as our own usage of Sekonic light meters, we will choose to use $ K = 12.5 $.
+
+Since we want to work with $ EV_{100} $, we can substitute $K$ and $S$ in equation $ \ref{evK} $ to obtain equation $ \ref{ev100L} $.
+
+$$\begin{equation}\label{ev100L}
+EV = log_2(L \frac{100}{12.5})
+\end{equation}$$
+
+Given this relationship, it would be possible to implement automatic exposure in our engine by first measuring the average luminance of a frame. An easy way to achieve this is to simply downsample a luminance buffer down to 1 pixel and read the remaining value. This technique is unfortunately rarely stable and can easily be affected by extreme values. Many games use a different approach which consists in using a luminance histogram to remove extreme values.
+
+For validation and testing purposes, the luminance can be computed from a given EV:
+
+$$\begin{equation}
+L = 2^{EV_{100}} \times \frac{12.5}{100} = 2^{EV_{100} - 3}
+\end{equation}$$
+
+#### Exposure value and illuminance
+
+It is possible to define EV as a function of the illuminance $E$, given a per-device calibration constant $C$:
+
+$$\begin{equation}\label{evC}
+EV = log_2(\frac{E \times S}{C})
+\end{equation}$$
+
+The constant $C$ is the incident-light meter constant, which varies between manufacturers and/or types of sensors. There are two common types of sensors: flat and hemispherical. For flat sensors, a common value is 250. With hemispherical sensors, we could find two common values: 320, used by Minolta, and 340, used by Sekonic.
+
+Since we want to work with $ EV_{100} $, we can substitute $S$ $ \ref{evC} $ to obtain equation $ \ref{ev100C} $.
+
+$$\begin{equation}\label{ev100C}
+EV = log_2(E \frac{100}{C})
+\end{equation}$$
+
+The illuminance can then be computed from a given EV. For a flat sensor with $ C = 250 $ we obtain equation $ \ref{eFlatSensor} $.
+
+$$\begin{equation}\label{eFlatSensor}
+E = 2^{EV_{100}} \times 2.5
+\end{equation}$$
+
+For a hemispherical sensor with $ C = 340 $ we obtain equation $ \ref{eHemisphereSensor} $
+
+$$\begin{equation}\label{eHemisphereSensor}
+E = 2^{EV_{100}} \times 3.4
+\end{equation}$$
+
+#### Exposure compensation
+
+Even though an exposure value actually indicates combinations of camera settings, it is often used by photographers to describe light intensity. This is why cameras let photographers apply an exposure compensation to over or under-expose an image. This setting can be used for artistic control but also to achieve proper exposure (snow for instance will be exposed for as 18% middle-gray).
+
+Applying an exposure compensation $EC$ is a simple as adding an offset to the exposure value, as shown in equation $ \ref{ec} $.
+
+$$\begin{equation}\label{ec}
+EV_{100}' = EV_{100} - EC
+\end{equation}$$
+
+This equation uses a negative sign because we are using $EC$ in f-stops to adjust the final exposure. Increasing the EV is akin to closing down the aperture of the lens (or reducing shutter speed or reducing sensitivity). A higher EV will produce darker images.
+
+### Exposure
+
+To convert the scene luminance into normalized luminance, we must use the [photometric exposure](https://en.wikipedia.org/wiki/Exposure_value#Camera_settings_vs._photometric_exposure) (or luminous exposure), or amount of scene luminance that reaches the camera sensor. The photometric exposure, expressed in lux seconds and noted $H$, is given by equation $ \ref{photometricExposure} $.
+
+$$\begin{equation}\label{photometricExposure}
+H = \frac{q \cdot t}{N^2} L
+\end{equation}$$
+
+Where $L$ is the luminance of the scene, $t$ the shutter speed, $N$ the aperture and $q$ the lens and vignetting attenuation (typically $ q = 0.65 $[^lensAttenuation]). This definition does not take the sensor sensitivity into account. To do so, we must use one of the three ways to relate photometric exposure and sensitivity: saturation-based speed, noise-based speed and standard output sensitivity.
+
+We choose the saturation-based speed relation, which gives us $ H_{sat} $, the maximum possible exposure that does not lead to clipped or bloomed camera output (equation $ \ref{hSat} $).
+
+$$\begin{equation}\label{hSat}
+H_{sat} = \frac{78}{S_{sat}}
+\end{equation}$$
+
+We combine equations $ \ref{hSat} $ and $ \ref{photometricExposure} $ in equation $ \ref{lmax} $ to compute the maximum luminance $ L_{max} $ that will saturate the sensor given exposure settings $S$, $N$ and $t$.
+
+$$\begin{equation}\label{lmax}
+L_{max} = \frac{N^2}{q \cdot t} \frac{78}{S}
+\end{equation}$$
+
+This maximum luminance can then be used to normalize incident luminance $L$ as shown in equation $ \ref{normalizedLuminance} $.
+
+$$\begin{equation}\label{normalizedLuminance}
+L' = L \frac{1}{L_{max}}
+\end{equation}$$
+
+$ L_{max} $ can be simplified using equation $ \ref{ev} $, $ S = 100 $ and $ q = 0.65 $:
+
+$$\begin{align*}
+L_{max} &= \frac{N^2}{t} \frac{78}{q \cdot S} \\
+L_{max} &= 2^{EV_{100}} \frac{78}{q \cdot S} \\
+L_{max} &= 2^{EV_{100}} \times 1.2
+\end{align*}$$
+
+Listing [fragmentExposure] shows how the exposure term can be applied directly to the pixel color computed in a fragment shader.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+// Computes the camera's EV100 from exposure settings
+// aperture in f-stops
+// shutterSpeed in seconds
+// sensitivity in ISO
+float exposureSettings(float aperture, float shutterSpeed, float sensitivity) {
+    return log2((aperture * aperture) / shutterSpeed * 100.0 / sensitivity);
+}
+
+// Computes the exposure normalization factor from
+// the camera's EV100
+float exposure(float ev100) {
+    return 1.0 / (pow(2.0, ev100) * 1.2);
+}
+
+float ev100 = exposureSettings(aperture, shutterSpeed, sensitivity);
+float exposure = exposure(ev100);
+
+vec4 color = evaluateLighting();
+color.rgb *= exposure;
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+[Listing [fragmentExposure]: Implementation of exposure in GLSL]
+
+In practice the exposure factor can be pre-computed on the CPU to save shader instructions.
+
+[^lensAttenuation]: See *Film Speed, Measurements and calculations* on Wikipedia (https://en.wikipedia.org/wiki/Film_speed)
+
+### Automatic exposure
+
+The process described above relies on artists setting the camera exposure settings manually. This can prove cumbersome in practice since camera movements and/or dynamic effects can greatly affect the scene's luminance. Since we know how to compute the exposure value from a given luminance (see section [Exposure value and luminance]), we can transform our camera into a spot meter. To do so, we need to measure the scene's luminance.
+
+There are two common techniques used to measure the scene's luminance:
+
+- **Luminance downsampling**, by downsampling the previous frame successively until obtaining a 1x1 log luminance buffer that can be read on the CPU (this could also be achieved using a compute shader). The result is the average log luminance of the scene. The first downsampling must extract the luminance of each pixel first. This technique can be unstable and its output should be smoothed over time.
+- **Using a luminance histogram**, to find the average log luminance. This technique has an advantage over the previous one as it allows to ignore extreme values and offers more stable results.
+
+Note that both methods will find the average luminance after multiplication by the albedo. This is not entirely correct but the alternative is to keep a luminance buffer that contains the luminance of each pixel before multiplication by the surface albedo. This is expensive both computationally and memory-wise.
+
+These two techniques also limit the metering system to average metering, where each pixel has the same influence (or weight) over the final exposure. Cameras typically offer 3 modes of metering:
+
+Spot metering
+:   In which only a small circle in the center of the image contributes to the final exposure. That circle is usually 1 to 5% of the total image size.
+
+Center-weighted metering
+:   Gives more influence to scene luminance values located in the center of the screen.
+
+Multi-zone or matrix metering
+:   A metering mode that differs for each manufacturer. The goal of this mode is to prioritize exposure for the most important parts of the scene. This is often achieved by splitting the image into a grid and by classifying each cell (using focus information, min/max luminance, etc.). Advanced implementations attempt to compare the scene to a known dataset to achieve proper exposure (backlit sunset, overcast snowy day, etc.).
+
+#### Spot metering
+
+The weight $w$ of each luminance value to use when computing the scene luminance is given by equation $ \ref{spotMetering} $.
+
+$$\begin{equation}\label{spotMetering}
+w(x,y) = \begin{cases} 1 & \left| p_{x,y} - s_{x,y} \right| \le s_r \\ 0 & \left| p_{x,y} - s_{x,y} \right| \gt s_r \end{cases}
+\end{equation}$$
+
+Where $p$ is the position of the pixel, $s$ the center of the spot and $ s_r $ the radius of the spot.
+
+#### Center-weighted metering
+
+$$\begin{equation}\label{centerMetering}
+w(x,y) = smooth(\left| p_{x,y} - c \right| \times \frac{2}{width} )
+\end{equation}$$
+
+Where $c$ is the center of the time and $ smooth() $ a smoothing function such as GLSL's `smoothstep()`.
+
+#### Adaptation
+
+To smooth the result of the metering, we can use equation $ \ref{adaptation} $, an exponential feedback loop as described by Pattanaik et al. in [Pattanaik00].
+
+$$\begin{equation}\label{adaptation}
+L_{avg} = L_{avg} + (L - L_{avg}) \times (1 - e^{-\Delta t \cdot \tau})
+\end{equation}$$
+
+Where $ \Delta t $ is the delta time from the previous frame and $\tau$ a constant that controls the adaptation rate.
+
+### Bloom
+
+Because the EV scale is almost perceptually linear, the exposure value is also often used as a light unit. This means we could let artists specify the intensity of lights or emissive surfaces using exposure compensation as a unit. The intensity of emitted light would therefore be relative to the exposure settings. Using exposure compensation as a light unit should be avoided whenever possible but can be useful to force (or cancel) a bloom effect around emissive surfaces independently of the camera settings (for instance, a lightsaber in a game should always bloom).
+
+![Figure [bloom]: Saturated photosites on a sensor create a blooming effect in the bright parts of the scene](images/screenshot_bloom.jpg)
+
+With $c$ the bloom color and $ EV_{100} $ the current exposure value, we can easily compute the luminance of the bloom value as show in equation $ \ref{bloomEV} $.
+
+$$\begin{equation}\label{bloomEV}
+EV_{bloom} = EV_{100} + EC \\
+L_{bloom} = c \times 2^{EV_{bloom} - 3}
+\end{equation}$$
+
+Equation $ \ref{bloomEV} $ can be used in a fragment shader to implement emissive blooms, as shown in listing [fragmentEmissive].
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+vec4 surfaceShading() {
+    vec4 color = evaluateLights();
+    // rgb = color, w = exposure compensation
+    vec4 emissive = getEmissive();
+    color.rgb += emissive.rgb * pow(2.0, ev100 + emissive.w - 3.0);
+    color.rgb *= exposure;
+    return color;
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+[Listing [fragmentEmissive]: Implementation of emissive bloom in GLSL]
+
+## Optics post-processing
+
+### Color fringing
+
+[TODO]
+
+![Figure [fringing]: Example of color fringing: look at the ear on the left or the chin at the bottom.](images/screenshot_fringing.jpg)
+
+### Lens flares
+
+[TODO] Notes: there is a physically based approach to generating lens flares, by tracing rays through the optical assembly of the lens, but we are going to use an image-based approach. This approach is cheaper and has a few welcome benefits such as free emitters occlusion and unlimited light sources support.
+
+## Filmic post-processing
+
+[TODO] Perform post-processing on the scene referred data (linear space, before tone-mapping) as much as possible
+
+It is important to provide color correction tools to give artists greater artistic control over the final image. These tools are found in every photo or video processing application, such as Adobe Photoshop or Adobe After Effects.
+
+### Contrast
+
+### Curves
+
+### Levels
+
+### Color grading
+
+## Light path
+
+The light path, or rendering method, used by the engine can have serious performance implications and may impose strong limitations on how many lights can be used in a scene. There are traditionally two different rendering methods used by 3D engines forward and deferred rendering.
+
+Our goal is to use a rendering method that obeys the following constraints:
+
+- Low bandwidth requirements
+- Multiple dynamic lights per pixel
+
+Additionally, we would like to easily support:
+
+- MSAA
+- Transparency
+- Multiple material models
+
+Deferred rendering is used by many modern 3D rendering engines to easily support dozens, hundreds or even thousands of light source (amongst other benefits). This method is unfortunately very expensive in terms of bandwidth. With our default PBR material model, our G-buffer would use between 160 and 192 bits per pixel, which would translate directly to rather high bandwidth requirements.
+
+Forward rendering methods on the other hand have historically been bad at handling multiple lights. A common implementation is to render the scene multiple times, once per visible light, and to blend (add) the results. Another technique consists in assigning a fixed maximum of lights to each object in the scene. This is however impractical when objects occupy a vast amount of space in the world (building, road, etc.).
+
+Tiled shading can be applied to both forward and deferred rendering methods. The idea is to split the screen in a grid of tiles and for each tile, find the list of lights that affect the pixels within that tile. This has the advantage of reducing overdraw (in deferred rendering) and shading computations of large objects (in forward rendering). This technique suffers however from depth discontinuities issues that can lead to large amounts of extraneous work.
+
+The scene displayed in figure [sponza] was rendered using clustered forward rendering.
+
+![Figure [sponza]: Clustered forward rendering with dozens of dynamic lights and MSAA](images/screenshot_sponza.jpg)
+
+Figure [sponzaTiles] shows the same scene split in tiles (in this case, a 1280x720 render target with 80x80px tiles).
+
+![Figure [sponzaTiles]: Tiled shading (16x9 tiles)](images/screenshot_sponza_tiles.jpg)
+
+### Clustered Forward Rendering
+
+We decided to explore another method called Clustered Shading, in its forward variant. Clustered shading expands on the idea of tiled rendering but adds a segmentation on the 3rd axis. The “clustering” is done in view space, by splitting the frustum into a 3D grid.
+
+The frustum is first sliced on the depth axis as show in figure [sponzaSlices].
+
+![Figure [sponzaSlices]: Depth slicing (16 slices)](images/screenshot_sponza_slices.jpg)
+
+And the depth slices are then combined with the screen tiles to "voxelize" the frustum. We call each cluster a froxel as it makes it clear what they represent (a voxel in frustum space). The result of the "froxelization" pass is shown in figure [froxel1] and figure [froxel2].
+
+![Figure [froxel1]: Frustum voxelization (5x3 tiles, 8 depth slices)](images/screenshot_sponza_froxels1.jpg)
+
+![Figure [froxel2]: Frustum voxelization (5x3 tiles, 8 depth slices)](images/screenshot_sponza_froxels2.jpg)
+
+Before rendering a frame, each light in the scene is assigned to any froxel it intersects with. The result of the lights assignment pass is a list of lights for each froxel. During the rendering pass, we can compute the ID of the froxel a fragment belongs to and therefore the list of lights that can affect that fragment.
+
+The depth slicing is not linear, but exponential. In a typical scene, there will be more pixels close to the near plane than to the far plane. An exponential grid of froxels will therefore improve the assignment of lights where it matters the most.
+
+Figure [froxelDistribution] shows how much world space unit each depth slice uses with exponential slicing.
+
+![Figure [froxelDistribution]: Near: 0.1m, Far: 100m, 16 slices](images/diagram_froxels1.png)
+
+A simple exponential voxelization is unfortunately not enough. The graphic above clearly illustrates how world space is distributed across slices but it fails to show what happens close to the near plane. If we examine the same distribution in a smaller range (0.1m to 7m) we can see an interesting problem appear as shown in figure [froxelDistributionClose].
+
+![Figure [froxelDistributionClose]: Depth distribution in the 0.1-7m range](images/diagram_froxels2.png)
+
+This graphic shows that a simple exponential distribution uses up half of the slices very close to the camera. In this particular case, we use 8 slices out of 16in the first 5 meters. Since dynamic world lights are either point lights (spheres) or spot lights (cones), such a fine resolution is completely unnecessary so close to the near plane.
+
+Our solution is to manually tweak the size of the first froxel depending on the scene and the near and far planes. By doing so, we can better distribute the remaining froxels across the frustum. Figure [froxelDistributionExp] shows for instance what happens when we use a special froxel between 0.1m and 5m.
+
+![Figure [froxelDistributionExp]: Near: 0.1, Far: 100m, 16 slices, Special froxel: 0.1-5m](images/diagram_froxels3.png)
+
+This new distribution is much more efficient and allows a better assignment of the lights throughout the entire frustum.
+
+### Implementation notes
+
+Lights assignment can be done in two different ways, on the GPU or on the CPU.
+
+#### GPU lights assignment
+
+This implementation requires OpenGL ES 3.1 and support for compute shaders. The lights are stored in Shader Storage Buffer Objects (SSBO) and passed to a compute shader that assigns each light to the corresponding froxels.
+
+The frustum voxelization can be executed only once by a first compute shader (as long as the projection matrix does not change), and the lights assignment can be performed each frame by another compute shader.
+
+The threading model of compute shaders is particularly well suited for this task. We simply invoke as many workgroups as we have froxels (we can directly map the X, Y and Z workgroup counts to our froxel grid resolution). Each workground will in turn be threaded and traverse all the lights to assign.
+
+Intersection tests imply simple sphere/frustum or cone/frustum tests.
+
+See the annex for the source code of a GPU implementation (point lights only).
+
+#### CPU lights assignment
+
+On non-OpenGL ES 3.1 devices, lights assignment can be performed efficiently on the CPU. The algorithm is different from the GPU implementation. Instead of iterating over every light for each froxel, the engine will “rasterize” each light as froxels. For instance, given a point light’s center and radius, it is trivial to compute the list of froxels it intersects with.
+
+This technique has the added benefit of providing tighter culling than in the GPU variant. The CPU implementation can also more easily generate a packed list of lights.
+
+#### Shading
+
+The list of lights per froxel can be passed to the fragment shader either as an SSBO (OpenGL ES 3.1) or a texture.
+
+#### From depth to froxel
+
+Given a near plane $n$, a far plane $f$, a maximum number of depth slices $m$ and a linear depth value $z$ in the range [0..1], equation $\ref{zToCluster}$ can be used to compute the index of the cluster for a given position.
+
+$$\begin{equation}\label{zToCluster}
+zToCluster(z,n,f,m)=floor \left( max \left( log2(z) \frac{m}{-log2(\frac{n}{f})} + m, 0 \right) \right)
+\end{equation}$$
+
+This formula suffers however from the resolution issue mentioned previously. We can fix it by introducing $sn$, a special near value that defines the extent of the first froxel (the first froxel occupies the range [n..sn], the remaining froxels [sn..f]).
+
+$$\begin{equation}\label{zToClusterFix}
+zToCluster(z,n,sn,f,m)=floor \left( max \left( log2(z) \frac{m-1}{-log2(\frac{sn}{f})} + m, 0 \right) \right)
+\end{equation}$$
+
+Equation $\ref{linearZ}$ can be used to compute a linear depth value from `gl_FragCoord.z` (assuming a standard OpenGL projection matrix).
+
+$$\begin{equation}\label{linearZ}
+linearZ(z)=\frac{n}{f+z(n-f)}
+\end{equation}$$
+
+This equation can be simplified by pre-computing two terms $c0$ and $c1$, as shown in equation $\ref{linearZFix}$.
+
+$$\begin{equation}\label{linearZFix}
+c1 = \frac{f}{n} \\
+c0 = 1 - c1 \\
+linearZ(z)=\frac{1}{z \cdot c0 + c1}
+\end{equation}$$
+
+This simplification is important because we pass the linear z value to a `log2` in $\ref{zToClusterFix}$. Since the division becomes a negation under a logarithmic, we can avoid a division by using $-log2(z \cdot c0 + c1)$ instead.
+
+All put together, computing the froxel index of a given fragment can be implemented fairly easily as shown in listing [fragCoordToFroxel].
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#define MAX_LIGHT_COUNT 16 // max number of lights per froxel
+
+uniform uvec4 froxels; // res x, res y, count y, count y
+uniform vec4 zParams;  // c0, c1, index scale, index bias
+
+uint getDepthSlice() {
+    return uint(max(0.0, log2(zParams.x * gl_FragCoord.z + zParams.y) *
+            zParams.z + zParams.w));
+}
+
+uint getFroxelOffset(uint depthSlice) {
+    uvec2 froxelCoord = uvec2(gl_FragCoord.xy) / froxels.xy;
+    froxelCoord.y = (froxels.w - 1u) - froxelCoord.y;
+
+    uint index = froxelCoord.x + froxelCoord.y * froxels.z +
+            depthSlice * froxels.z * froxels.w;
+    return index * MAX_FROXEL_LIGHT_COUNT;
+}
+
+uint slice = getDepthSlice();
+uint offset = getFroxelOffset(slice);
+
+// Compute lighting...
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+[Listing [fragCoordToFroxel]: GLSL implementation to compute a froxel index from a fragment's screen coordinates]
+
+Several uniforms must be pre-computed for perform the index evaluation efficiently. The code used to pre-compute these uniforms can be found in listing [froxelIndexPrecomputation].
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+froxels[0] = TILE_RESOLUTION_IN_PX;
+froxels[1] = TILE_RESOLUTION_IN_PX;
+froxels[2] = numberOfTilesInX;
+froxels[3] = numberOfTilesInY;
+
+zParams[0] = 1.0f - Z_FAR / Z_NEAR;
+zParams[1] = Z_FAR / Z_NEAR;
+zParams[2] = (MAX_DEPTH_SLICES - 1) / log2(Z_SPECIAL_NEAR / Z_FAR);
+zParams[3] = MAX_DEPTH_SLICES;
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+[Listing [froxelIndexPrecomputation]]
+
+#### From froxel to depth
+
+Given a froxel index $i$, a special near plane $sn$, a far plane $f$ and a maximum number of depth slices $m$, equation $\ref{clusterToZ}$ computes the minimum depth of a given froxel.
+
+$$\begin{equation}\label{clusterToZ}
+clusterToZ(i \ge 1,sn,f,m)=2^{(i-m) \frac{-log2(\frac{sn}{f})}{m-1}}
+\end{equation}$$
+
+For $i=0$, the z value is 0. The result of this equation is in the [0..1] range and should be multiplied by $f$ to get a distance in world units.
+
+The compute shader implementation should use `exp2` instead of a `pow`. The division can be precomputed and passed as a uniform.
+
+## Validation
+
+Given the complexity of our lighting system, it is important to validate our implementation. We will do so in several ways: using reference renderings, light measurements and data visualization.
+
+[TODO] Explain light measurement validation (reading EV from the render target and comparing against values measure with light meters/cameras, etc.)
+
+### Scene referred visualization
+
+A quick and easy way to validate a scene's lighting is to modify the shader to output colors that provide an intuitive mapping to relevant data. This can easily be done by using a custom debug tone-mapping operator that outputs fake colors.
+
+#### Luminance stops
+
+With emissive materials and IBLs, it is fairly easy to obtain a scene in which specular highlights are brighter than their apparent caster. This type of issue can be difficult to observe after tone-mapping and quantization but is fairly obvious in the scene-referred space. Figure [luminanceViz] shows how the custom operator described in listing [tonemapLuminanceViz] is used to show the exposed luminance of a scene.
+
+![Figure [luminanceViz]: Visualizing luminance by color coding the stops: cyan is middle gray, blue is 1 stop darker, green 1 stop brighter, etc.](images/screenshot_luminance_debug.png)
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+vec3 Tonemap_DisplayRange(const vec3 x) {
+    // The 5th color in the array (cyan) represents middle gray (18%)
+    // Every stop above or below middle gray causes a color shift
+    float v = log2(luminance(x) / 0.18);
+    v = clamp(v + 5.0, 0.0, 15.0);
+    int index = int(floor(v));
+    return mix(debugColors[index], debugColors[min(15, index + 1)], fract(v));
+}
+
+const vec3 debugColors[16] = vec3[](
+     vec3(0.0, 0.0, 0.0),         // black
+     vec3(0.0, 0.0, 0.1647),      // darkest blue
+     vec3(0.0, 0.0, 0.3647),      // darker blue
+     vec3(0.0, 0.0, 0.6647),      // dark blue
+     vec3(0.0, 0.0, 0.9647),      // blue
+     vec3(0.0, 0.9255, 0.9255),   // cyan
+     vec3(0.0, 0.5647, 0.0),      // dark green
+     vec3(0.0, 0.7843, 0.0),      // green
+     vec3(1.0, 1.0, 0.0),         // yellow
+     vec3(0.90588, 0.75294, 0.0), // yellow-orange
+     vec3(1.0, 0.5647, 0.0),      // orange
+     vec3(1.0, 0.0, 0.0),         // bright red
+     vec3(0.8392, 0.0, 0.0),      // red
+     vec3(1.0, 0.0, 1.0),         // magenta
+     vec3(0.6, 0.3333, 0.7882),   // purple
+     vec3(1.0, 1.0, 1.0)          // white
+);
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+[Listing [tonemapLuminanceViz]: GLSL implementation of a custom debug tone-mapping operator for luminance visualization]
+
+### Reference renderings
+
+To validate our implementation against reference renderings, we will use a commercial-grade Open Source physically based offline path tracer called Mitsuba. Mitsuba offers many different integrators, samplers and material models, which should allow us to provide fair comparisons with our real-time renderer. This path tracer also relies on a simple XML scene description format that should be easy to automatically generate from our own scene descriptions.
+
+Figure [mitsubaReference] and figure [filamentReference] show a simple scene, a perfectly smooth dielectric sphere, rendered respectively with Mitsuba and Filament.
+
+![Figure [mitsubaReference]: Rendered in 2048x1440 in 1 minute and 42 seconds on a 12 core 2013 MacPro](images/screenshot_ref_mitsuba.jpg)
+
+![Figure [filamentReference]: Rendered in 2048x1440 with MSAA 4x at 60 fps on a Nexus 9 device (Tegra K1 GPU)](images/screenshot_ref_filament.jpg)
+
+The parameters used to render both scenes are the following:
+
+**Filament**
+
+- Material
+  - Base color: sRGB 0.81, 0, 0
+  - Metallic: 0
+  - Roughness: 0
+  - Reflectance: 0.5
+- Indirect light: IBL
+  - 256x256 cubemap generated by cmgen from office.exr
+  - Multiplier: 35,000
+- Direct light: directional light
+  - Linear color: 1.0, 0.96, 0.95
+  - Intensity: 120,000 lux
+- Exposure
+  - Aperture: f/16
+  - Shutter speed: 1/125s
+  - ISO: 100
+
+**Mitsuba**
+
+- BSDF: roughplastic
+  - Distribution: GGX
+  - Alpha: 0
+  - Diffuse reflectance: sRGB 0.81, 0, 0
+- Emitter: environment map
+  - Source: office.exr
+  - Scale: 35,000
+- Emitter: directional
+  - Irradiance: linear RGB 120,000 115,200 114,000
+- Film: LDR
+  - Exposure: -15.23, computed from log2(filamentExposure)
+- Integrator: path
+- Sampler: ldsampler
+  - Sample count: 256
+
+The full Mitsuba scene can be found as an annex. Both scenes were rendered at the same resolution (2048x1440).
+
+#### Comparison
+
+The slight differences between the two renderings come from the various approximations used by Filament: RGBM 256x256 reflection probe, RGBM 1024x1024 background map, Lambert diffuse, split-sum approximation, analytical approximation of the DFG term, etc.
+
+Figure [referenceComparison] shows the luminance gradient of the images produced by both engines. The comparison was performed on LDR images.
+
+![Figure [referenceComparison]: Luminance gradients from Mitsuba (left) and Filament (right)](images/screenshot_ref_comparison.png)
+
+The biggest difference is visible at grazing angles, which is most likely explained by Filament's use of a Lambertian diffuse term. The Disney diffuse term and its grazing retro-reflections would move Filament closer to Mitsuba.
+
+## Coordinates systems
+
+### World coordinates system
+
+Filament uses a Y-up, right-handed coordinate system.
+
+![Figure [coordinates]: Red +X, green +Y, blue +Z (rendered in Marmoset Toolbag).](images/screenshot_coordinates.jpg)
+
+
+### Camera coordinates system
+
+Filament's Camera looks towards its local -Z axis. That is, when placing a camera in the world
+without any transform applied to it, the camera looks down the world's -Z axis.
+
+
+### Cubemaps coordinates system
+
+All cubemaps used in Filament follow the OpenGL convention for face
+alignment shown in figure [cubemapCoordinates].
+
+![Figure [cubemapCoordinates]: Horizontal cross representation of a cubemap following the OpenGL faces alignment convention.](images/screenshot_cubemap_coordinates.png)
+
+Note that environment background and reflection probes are mirrored (see section [Mirroring]).
+
+
+#### Mirroring
+
+To simplify the rendering of reflections, IBL cubemaps are stored mirrored on the X axis. This is
+the default behaviour of the `cmgen` tool. This means that an IBL cubemap used as environment 
+background needs to be mirrored again at runtime. 
+An easy way to achieve this for skyboxes is to use textured back faces. Filament does
+this by default.
+
+
+#### Equirectangular environment maps
+
+To convert equirectangular environment maps to horizontal/vertical cross cubemaps we position the
++Z face in the center of the source rectilinear environment map.
+
+
+#### World space orientation of environment maps and Skyboxes
+
+When specifying a skybox or an IBL in Filament, the specified cubemap is oriented such that its 
+-Z face points towards the +Z axis of the world (this is because filament assumes mirrored cubemaps, 
+see section [Mirroring]). However, because environments and skyboxes are expected to be pre-mirrored, 
+their -Z (back) face points towards the world's -Z axis as expected (and the camera looks toward that 
+direction by default, see section [Camera coordinates system]).
+
+
+# Annex
+
+## Specular color
+
+The specular color of a metallic surface, or $\fNormal$, can be computed directly from measured spectral data. Online databases such as [Refractive Index](https://refractiveindex.info/?shelf=3d&book=metals&page=brass) provide tables of complex IOR measured at different wavelengths for various materials.
+
+Earlier in this document, we presented equation $\ref{fresnelEquation}$ to compute the Fresnel reflectance at normal incidence for a dielectric surface given its IOR. The same equation can be rewritten for conductors by using complex numbers to represent the surface's IOR:
+
+$$\begin{equation}
+c_{ior} = n_{ior} + ik
+\end{equation}$$
+
+Equation $\ref{fresnelComplexIOR}$ presents the resulting Fresnel formula, where $c^*$ is the conjugate of the complex number $c$:
+
+$$\begin{equation}\label{fresnelComplexIOR}
+\fNormal(c_{ior}) = \frac{(c_{ior} - 1)(c_{ior}^* - 1)}{(c_{ior} + 1)(c_{ior}^* + 1)}
+\end{equation}$$
+
+To compute the specular color of a material we need to evaluate the complex Fresnel equation at each spectral sample of complex IOR over the visible spectrum. For each spectral sample, we obtain a spectral reflectance sample. To find the RGB color at normal incidence, we must multiply each sample by the CIE XYZ CMFs (color matching functions) and the spectral power distribution of the desired illuminant. We choose the standard illuminant D65 because we want to compute a color in the sRGB color space.
+
+We then sum (integrate) and normalize all the samples to obtain $\fNormal$ in the XYZ color space. From there, a simple color space conversion yields a linear sRGB color or a non-linear sRGB color after applying the opto-electronic transfer function (OETF, commonly known as "gamma" curve). Note that for some materials such as gold the final sRGB color might fall out of gamut. We use a simple normalization step as a cheap form of gamut remapping but it would be interesting to consider computing values in a color space with a wider gamut (for instance BT.2020).
+
+To achieve the desired result we used the ICE 1931 2 degrees CMFs, from 360nm to 830nm at 1nm intervals ([source](http://cvrl.ioo.ucl.ac.uk/cmfs.htm)), and the CIE Standard Illuminant D65 relative spectral power distribution, from 300nm to 830nm, at 5nm intervals ([source](http://files.cie.co.at/204.xls)).
+
+Our implementation is presented in listing [specularColorImpl], with the actual data omitted for brevity.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+// CIE 1931 2-deg color matching functions (CMFs), from 360nm to 830nm,
+// at 1nm intervals
+//
+// Data source:
+//     http://cvrl.ioo.ucl.ac.uk/cmfs.htm
+//     http://cvrl.ioo.ucl.ac.uk/database/text/cmfs/ciexyz31.htm
+const size_t CIE_XYZ_START = 360;
+const size_t CIE_XYZ_COUNT = 471;
+const float3 CIE_XYZ[CIE_XYZ_COUNT] = { ... };
+
+// CIE Standard Illuminant D65 relative spectral power distribution,
+// from 300nm to 830, at 5nm intervals
+//
+// Data source:
+//     https://en.wikipedia.org/wiki/Illuminant_D65
+//     https://cielab.xyz/pdf/CIE_sel_colorimetric_tables.xls
+const size_t CIE_D65_INTERVAL = 5;
+const size_t CIE_D65_START = 300;
+const size_t CIE_D65_END = 830;
+const size_t CIE_D65_COUNT = 107;
+const float CIE_D65[CIE_D65_COUNT] = { ... };
+
+struct Sample {
+    float w = 0.0f; // wavelength
+    std::complex<float> ior; // complex IOR, n + ik
+};
+
+static float illuminantD65(float w) {
+    auto i0 = size_t((w - CIE_D65_START) / CIE_D65_INTERVAL);
+    uint2 indexBounds{i0, std::min(i0 + 1, CIE_D65_END)};
+
+    float2 wavelengthBounds = CIE_D65_START + float2{indexBounds} * CIE_D65_INTERVAL;
+    float t = (w - wavelengthBounds.x) / (wavelengthBounds.y - wavelengthBounds.x);
+    return lerp(CIE_D65[indexBounds.x], CIE_D65[indexBounds.y], t);
+}
+
+// For std::lower_bound
+bool operator<(const Sample& lhs, const Sample& rhs) {
+    return lhs.w < rhs.w;
+}
+
+// The wavelength w must be between 360nm and 830nm
+static std::complex<float> findSample(const std::vector<Sample>& samples, float w) {
+    auto i1 = std::lower_bound(
+	        samples.begin(), samples.end(), Sample{w, 0.0f + 0.0if});
+    auto i0 = i1 - 1;
+
+    // Interpolate the complex IORs
+    float t = (w - i0->w) / (i1->w - i0->w);
+    float n = lerp(i0->ior.real(), i1->ior.real(), t);
+    float k = lerp(i0->ior.imag(), i1->ior.imag(), t);
+    return { n, k };
+}
+
+static float fresnel(const std::complex<float>& sample) {
+    return (((sample - (1.0f + 0if)) * (std::conj(sample) - (1.0f + 0if))) /
+            ((sample + (1.0f + 0if)) * (std::conj(sample) + (1.0f + 0if)))).real();
+}
+
+static float3 XYZ_to_sRGB(const float3& v) {
+    const mat3f XYZ_sRGB{
+             3.2404542f, -0.9692660f,  0.0556434f,
+            -1.5371385f,  1.8760108f, -0.2040259f,
+            -0.4985314f,  0.0415560f,  1.0572252f
+    };
+    return XYZ_sRGB * v;
+}
+
+// Outputs a linear sRGB color
+static float3 computeColor(const std::vector<Sample>& samples) {
+    float3 xyz{0.0f};
+    float y = 0.0f;
+
+    for (size_t i = 0; i < CIE_XYZ_COUNT; i++) {
+        // Current wavelength
+        float w = CIE_XYZ_START + i;
+
+        // Find most appropriate CIE XYZ sample for the wavelength
+        auto sample = findSample(samples, w);
+        // Compute Fresnel reflectance at normal incidence
+        float f0 = fresnel(sample);
+
+        // We need to multiply by the spectral power distribution of the illuminant
+        float d65 = illuminantD65(w);
+
+        xyz += f0 * CIE_XYZ[i] * d65;
+        y += CIE_XYZ[i].y * d65;
+    }
+
+    // Normalize so that 100% reflectance at every wavelength yields Y=1
+    xyz /= y;
+
+    float3 linear = XYZ_to_sRGB(xyz);
+
+    // Normalize out-of-gamut values
+    if (any(greaterThan(linear, float3{1.0f}))) linear *= 1.0f / max(linear);
+
+    return linear;
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+[Listing [specularColorImpl]: C++ implementation to compute the base color of a metallic surface from spectral data]
+
+Special thanks to Naty Hoffman for his valuable help on this topic.
+
+## Importance sampling for the IBL
+
+In the discrete domain, the integral can be approximated with sampling as defined in equation $\ref{iblSampling}$.
+
+$$\begin{equation}\label{iblSampling}
+\Lout(n,v,\Theta) \equiv \frac{1}{N} \sum_{i}^{N} f(l_{i}^{uniform},v,\Theta) L_{\perp}(l_i) \left< n \cdot l_i^{uniform} \right>
+\end{equation}$$
+
+Unfortunately, we would need too many samples to evaluate this integral. A technique commonly used
+is to choose samples that are more "important" more often, this is called _importance sampling_.
+In our case we'll use the distribution of micro-facets normals, $D_{ggx}$, as the distribution of
+important samples.
+
+The evaluation of $ \Lout(n,v,\Theta) $ with importance sampling is presented in equation $\ref{annexIblImportanceSampling}$.
+
+$$\begin{equation}\label{annexIblImportanceSampling}
+\Lout(n,v,\Theta) \equiv \frac{1}{N} \sum_{i}^{N} \frac{f(l_{i},v,\Theta)}{p(l_i,v,\Theta)} L_{\perp}(l_i) \left< n \cdot l_i \right>
+\end{equation}$$
+
+In equation $\ref{annexIblImportanceSampling}$, $p$ is the probability density function (PDF) of the
+distribution of _important direction samples_ $l_i$. These samples depend on $h_i$, $v$ and $\alpha$.
+The definition of the PDF is shown in equation $\ref{iblPDF}$.
+
+$h_i$ is given by the distribution we chose, see section [Choosing important directions] for more details.
+
+The _important direction samples_ $l_i$ are calculated as the reflection of $v$ around $h_i$, and therefore
+**do not** have the same PDF as $h_i$. The PDF of a transformed distribution is given by:
+
+$$\begin{equation}
+p(T_r(x)) = p(x) |J(T_r)|^{-1}
+\end{equation}$$
+
+Where $|J(T_r)|$ is the determinant of the Jacobian of the transform. In our case we're considering
+the transform from $h_i$ to $l_i$ and the determinant of its Jacobian is given in \ref{iblPDF}.
+
+$$\begin{equation}\label{iblPDF}
+p(l,v,\Theta) = D(h,\alpha) \left< \NoH \right> |J_{h \rightarrow l}|^{-1} \\
+|J_{h \rightarrow l}| = 4 \left< \VoH \right>
+\end{equation}$$
+
+### Choosing important directions
+
+Refer to section [Choosing important directions for sampling the BRDF] for more details. Given a uniform distribution $(\zeta_{\phi},\zeta_{\theta})$ the important direction $l$ is defined by equation $\ref{importantDirection}$.
+
+$$\begin{equation}\label{importantDirection}
+\phi = 2 \pi \zeta_{\phi} \\
+\theta = cos^{-1} \sqrt{\frac{1 - \zeta_{\theta}}{(\alpha^2 - 1)\zeta_{\theta}+1}} \\
+l = \{ cos \phi sin \theta, sin \phi sin \theta, cos \theta \}
+\end{equation}$$
+
+Typically, $ (\zeta_{\phi},\zeta_{\theta}) $ are chosen using the Hammersley uniform distribution algorithm described in section [Hammersley sequence].
+
+### Pre-filtered importance sampling
+
+Importance sampling considers only the PDF to generate important directions; in particular, it is oblivious to the actual content of the IBL. If the latter contains high frequencies in areas without a lot of samples, the integration won’t be accurate. This can be somewhat mitigated by using a technique called _pre-filtered importance sampling_, in addition this allows the integral to converge with many fewer samples.
+
+Pre-filtered importance sampling uses several images of the environment increasingly low-pass filtered. This is typically implemented very efficiently with mipmaps and a box filter. The LOD is selected based on the sample importance, that is, low probability samples use a higher LOD index (more filtered).
+
+This technique is described in details in [#Krivanek08].
+
+The cubemap LOD is determined in the following way:
+
+$$\begin{align*}
+lod &= log_4 \left( K\frac{\Omega_s}{\Omega_p} \right) \\
+K &= 4.0 \\
+\Omega_s &= \frac{1}{N \cdot p(l_i)} \\
+\Omega_p &\approx \frac{4\pi}{6 \cdot width \cdot height}
+\end{align*}$$
+
+Where $K$ is a constant determined empirically, $p$ the PDF of the BRDF, $ \Omega_{s} $ the solid angle associated to the sample and $\Omega_p$ the solid angle associated with the texel in the cubemap.
+
+Cubemap sampling is done using seamless trilinear filtering. It is extremely important to sample the cubemap correctly across faces using OpenGL's seamless sampling feature or any other technique that avoids/reduces seams.
+
+Table [importanceSamplingViz] shows a comparison between importance sampling and pre-filtered importance sampling when applied to figure [importanceSamplingRef].
+
+![Figure [importanceSamplingRef]: Importance sampling image reference](images/image_is_original.png)
+
+
+ Samples |      Importance sampling      |    Pre-filtered importance sampling
+---------|-------------------------------|---------------------------------------
+  4096   | ![](images/image_is_4096.png) | &nbsp;
+  1024   | ![](images/image_is_1024.png) | ![](images/image_fis_1024.png)
+  32     | ![](images/image_is_32.png)   | ![](images/image_fis_32.png)
+[Table [importanceSamplingViz]: Importance sampling vs pre-filtered importance sampling with $\alpha = 0.4$]
+
+The reference renderer used in the comparison below performs no approximation. In particular, it does not assume $v = n$ and does not perform the split sum approximation.  The pre-filtered renderer uses all the techniques discussed in this section: pre-filtered cubemaps, the analytic formulation of the DFG term, and of course the split sum approximation.
+
+Left: reference renderer, right: pre-filtered importance sampling.
+
+![](images/image_is_ref_1.png) ![](images/image_filtered_1.png)
+![](images/image_is_ref_2.png) ![](images/image_filtered_2.png)
+![](images/image_is_ref_3.png) ![](images/image_filtered_3.png)
+![](images/image_is_ref_4.png) ![](images/image_filtered_4.png)
+
+## Choosing important directions for sampling the BRDF
+
+For simplicity we use the $ D $ term of the BRDF as the PDF, however the PDF must be normalized such that the integral over the hemisphere is 1:
+
+$$\begin{equation}
+\int_{\Omega}p(m)dm = 1 \\
+\int_{\Omega}D(m)(n \cdot m)dm = 1 \\
+\int_{\phi=0}^{2\pi}\int_{\theta=0}^{\frac{\pi}{2}}D(\theta,\phi) cos \theta sin \theta d\theta d\phi = 1 \\
+\end{equation}$$
+
+The PDF of the BRDF can therefore be expressed as in equation $\ref{importantPDF}$:
+
+$$\begin{equation}\label{importantPDF}
+p(\theta,\phi) = \frac{\alpha^2}{\pi(cos^2\theta (\alpha^2-1) + 1)^2} cos\theta sin\theta
+\end{equation}$$
+
+The term $sin\theta$ comes from the differential solid angle $sin\theta d\phi d\theta$ since we integrate over a sphere. We sample $\theta$ and $\phi$ independently:
+
+$$\begin{align*}
+p(\theta) &= \int_0^{2\pi} p(\theta,\phi) d\phi = \frac{2\alpha^2}{(cos^2\theta (\alpha^2-1) + 1)^2} cos\theta sin\theta \\
+p(\phi) &= \frac{p(\theta,\phi)}{p(\phi)} = \frac{1}{2\pi}
+\end{align*}$$
+
+The expression of $ p(\phi) $ is true for an isotropic distribution of normals.
+
+We then calculate the cumulative distribution function (CDF) for each variable:
+
+$$\begin{align*}
+P(s_{\phi}) &= \int_{0}^{s_{\phi}} p(\phi) d\phi = \frac{s_{\phi}}{2\pi} \\
+P(s_{\theta}) &= \int_{0}^{s_{\theta}} p(\theta) d\theta = 2 \alpha^2 \left( \frac{1}{(2\alpha^4-4\alpha^2+2) cos(s_{\theta})^2 + 2\alpha^2 - 2} - \frac{1}{2\alpha^4-2\alpha^2} \right)
+\end{align*}$$
+
+We set $ P(s_{\phi}) $ and $ P(s_{\theta}) $ to random variables $ \zeta_{\phi} $ and $ \zeta_{\theta} $ and solve for $ s_{\phi} $ and $ s_{\theta} $ respectively:
+
+$$\begin{align*}
+P(s_{\phi}) &= \zeta_{\phi} \rightarrow s_{\phi} = 2\pi\zeta_{\phi} \\
+P(s_{\theta}) &= \zeta_{\theta} \rightarrow s_{\theta} = cos^{-1} \sqrt{\frac{1-\zeta_{\theta}}{(\alpha^2-1)\zeta_{\theta}+1}}
+\end{align*}$$
+
+So given a uniform distribution $ (\zeta_{\phi},\zeta_{\theta}) $, our important direction $l$ is defined as:
+
+$$\begin{align*}
+\phi &= 2\pi\zeta_{\phi} \\
+\theta &= cos^{-1} \sqrt{\frac{1-\zeta_{\theta}}{(\alpha^2-1)\zeta_{\theta}+1}} \\
+l &= \{ cos\phi sin\theta,sin\phi sin\theta,cos\theta \}
+\end{align*}$$
+
+## Hammersley sequence
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+vec2f hammersley(uint i, float numSamples) {
+    uint bits = i;
+    bits = (bits << 16) | (bits >> 16);
+    bits = ((bits & 0x55555555) << 1) | ((bits & 0xAAAAAAAA) >> 1);
+    bits = ((bits & 0x33333333) << 2) | ((bits & 0xCCCCCCCC) >> 2);
+    bits = ((bits & 0x0F0F0F0F) << 4) | ((bits & 0xF0F0F0F0) >> 4);
+    bits = ((bits & 0x00FF00FF) << 8) | ((bits & 0xFF00FF00) >> 8);
+    return vec2f(i / numSamples, bits / exp2(32));
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+[C++ implementation of a Hammersley sequence generator]
+
+## Precomputing L for image-based lighting
+
+The term $ L_{DFG} $ is only dependent on $ \NoV $. Below, the normal is arbitrarily set to $ n=\left[0, 0, 1\right] $ and $v$ is chosen to satisfy $ \NoV $. The vector $ h_i $ is the $ D_{GGX}(\alpha) $ important direction sample $i$.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+float GDFG(float NoV, float NoL, float a) {
+    float a2 = a * a;
+    float GGXL = NoV * sqrt((-NoL * a2 + NoL) * NoL + a2);
+    float GGXV = NoL * sqrt((-NoV * a2 + NoV) * NoV + a2);
+    return (2 * NoL) / (GGXV + GGXL);
+}
+
+float2 DFG(float NoV, float a) {
+    float3 V;
+    V.x = sqrt(1.0f - NoV*NoV);
+    V.y = 0.0f;
+    V.z = NoV;
+
+    float2 r = 0.0f;
+    for (uint i = 0; i < sampleCount; i++) {
+        float2 Xi = hammersley(i, sampleCount);
+        float3 H = importanceSampleGGX(Xi, a, N);
+        float3 L = 2.0f * dot(V, H) * H - V;
+
+        float VoH = saturate(dot(V, H));
+        float NoL = saturate(L.z);
+        float NoH = saturate(H.z);
+
+        if (NoL > 0.0f) {
+            float G = GDFG(NoV, NoL, a);
+            float Gv = G * VoH / NoH;
+            float Fc = pow(1 - VoH, 5.0f);
+            r.x += Gv * (1 - Fc);
+            r.y += Gv * Fc;
+        }
+    }
+    return r * (1.0f / sampleCount);
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+[C++ implementation of the $ L_{DFG} $ term]
+
+## Spherical Harmonics
+
+          Symbol             |           Definition
+:---------------------------:|:---------------------------|
+$K^m_l$                      | Normalization factors
+$P^m_l(x)$                   | Associated Legendre polynomials
+$y^m_l$                      | Spherical harmonics bases, or SH bases
+$L^m_l$                      | SH coefficients of the $L(s)$ function defined on the unit sphere
+[Table [shSymbols]: Spherical harmonics symbols definitions]
+
+### Basis functions
+
+Spherical parameterization of points on the surface of the unit sphere:
+
+$$\begin{equation}
+\{ x, y, z \} = \{ cos \phi sin \theta, sin \phi sin \theta, cos \theta \}
+\end{equation}$$
+
+The complex spherical harmonics bases are given by:
+
+$$\begin{equation}
+Y^m_l(\theta, \phi) = K^m_l e^{im\theta} P^{|m|}_l(cos \theta), l \in N, -l <= m <= l
+\end{equation}$$
+
+However we only need the real bases:
+
+$$\begin{align*}
+y^{m > 0}_l &= \sqrt{2} K^m_l cos(m \phi) P^m_l(cos \theta) \\
+y^{m < 0}_l &= \sqrt{2} K^m_l sin(|m| \phi) P^{|m|}_l(cos \theta) \\
+y^0_l &= K^0_l P^0_l(cos \theta)
+\end{align*}$$
+
+The normalization factors are given by:
+
+$$\begin{equation}
+K^m_l = \sqrt{\frac{(2l + 1)(l - |m|)!}{4 \pi (l + |m|)!}}
+\end{equation}$$
+
+The associated Legendre polynomials $P^{|m|}_l$ can be calculated from the following recursions:
+
+$$\begin{equation}\label{shRecursions}
+P^0_0(x) = 1 \\
+P^0_1(x) = x \\
+P^l_l(x) = (-1)^l (2l - 1)!! (1 - x^2)^{\frac{l}{2}} \\
+P^m_l(x) = \frac{((2l - 1) x P^m_{l - 1} - (l + m - 1) P^m_{l - 2})}{l - m} \\
+\end{equation}$$
+
+Computing $y^{|m|}_l$ requires to compute $P^{|m|}_l(z)$ first.
+This can be accomplished fairly easily using the recursions in equation $\ref{shRecursions}$.
+The third recursion can be used to "move diagonally" in table [basisFunctions], i.e. calculating $y^0_0$, $y^1_1$, $y^2_2$ etc.
+Then, the fourth recursion can be used to move vertically.
+
+  Band index |  Basis functions $-l <= m <= l$
+:-----------:|:---------------------------------:|
+$l = 0$      | $y^0_0$
+$l = 1$      | $y^{-1}_1$ $y^0_1$ $y^1_1$
+$l = 2$      | $y^{-2}_2$ $y^{-1}_2$ $y^0_2$ $y^1_2$ $y^2_2$
+[Table [basisFunctions]: Basis functions per band]
+
+It’s also fairly easy to compute the trigonometric terms recursively:
+
+$$\begin{align*}
+C_m &\equiv cos(m \phi)sin(\theta)^m \\
+S_m &\equiv sin(m \phi)sin(\theta)^m \\
+\{ x, y, z \} &= \{ cos \phi sin \theta, sin \phi sin \theta, cos \theta \}
+\end{align*}$$
+
+Using the angle sum trigonometric identities:
+
+$$\begin{align*}
+cos(m \phi + \phi) &= cos(m \phi) cos(\phi) - sin(m \phi) sin(\phi) \Leftrightarrow C_{m + 1} = x C_m - y S_m \\
+sin(m \phi + \phi) &= sin(m \phi) cos(\phi) + cos(m \phi) sin(\phi) \Leftrightarrow S_{m + 1} = x S_m - y C_m
+\end{align*}$$
+
+
+Listing [nonNormalizedSHBasis] shows the C++ code to compute the non-normalized SH basis $\frac{y^m_l(s)}{\sqrt{2} K^m_l}$:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+static inline size_t SHindex(ssize_t m, size_t l) {
+    return l * (l + 1) + m;
+}
+
+void computeShBasis(
+        double* const SHb,
+        size_t numBands,
+        const vec3& s)
+{
+    // handle m=0 separately, since it produces only one coefficient
+    double Pml_2 = 0;
+    double Pml_1 = 1;
+    SHb[0] =  Pml_1;
+    for (ssize_t l = 1; l < numBands; l++) {
+        double Pml = ((2 * l - 1) * Pml_1 * s.z - (l - 1) * Pml_2) / l;
+        Pml_2 = Pml_1;
+        Pml_1 = Pml;
+        SHb[SHindex(0, l)] = Pml;
+    }
+    double Pmm = 1;
+    for (ssize_t m = 1; m < numBands ; m++) {
+        Pmm = (1 - 2 * m) * Pmm;
+        double Pml_2 = Pmm;
+        double Pml_1 = (2 * m + 1)*Pmm*s.z;
+        // l == m
+        SHb[SHindex(-m, m)] = Pml_2;
+        SHb[SHindex( m, m)] = Pml_2;
+        if (m + 1 < numBands) {
+            // l == m+1
+            SHb[SHindex(-m, m + 1)] = Pml_1;
+            SHb[SHindex( m, m + 1)] = Pml_1;
+            for (ssize_t l = m + 2; l < numBands; l++) {
+                double Pml = ((2 * l - 1) * Pml_1 * s.z - (l + m - 1) * Pml_2)
+                        / (l - m);
+                Pml_2 = Pml_1;
+                Pml_1 = Pml;
+                SHb[SHindex(-m, l)] = Pml;
+                SHb[SHindex( m, l)] = Pml;
+            }
+        }
+    }
+    double Cm = s.x;
+    double Sm = s.y;
+    for (ssize_t m = 1; m <= numBands ; m++) {
+        for (ssize_t l = m; l < numBands ; l++) {
+            SHb[SHindex(-m, l)] *= Sm;
+            SHb[SHindex( m, l)] *= Cm;
+        }
+        double Cm1 = Cm * s.x - Sm * s.y;
+        double Sm1 = Sm * s.x + Cm * s.y;
+        Cm = Cm1;
+        Sm = Sm1;
+    }
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+[Listing [nonNormalizedSHBasis]: C++ implementation to compute a non-normalized SH basis]
+
+Normalized SH basis functions $y^m_l(s)$ for the first 3 bands:
+
+   Band  |               $m = -2$               |                $m = -1$               |                      $m = 0$                        |                $m = 1$                |                    $m = 2$                    |
+:-------:|:------------------------------------:|:-------------------------------------:|:---------------------------------------------------:|:-------------------------------------:|:---------------------------------------------:|
+$l = 0$  |                                      |                                       | $\frac{1}{2}\sqrt{\frac{1}{\pi}}$                   |                                       |                                               |
+$l = 1$  |                                      | $-\frac{1}{2}\sqrt{\frac{3}{\pi}}y$   | $\frac{1}{2}\sqrt{\frac{3}{\pi}}z$                  | $-\frac{1}{2}\sqrt{\frac{3}{\pi}}x$   |                                               |
+$l = 2$  | $\frac{1}{2}\sqrt{\frac{15}{\pi}}xy$ | $-\frac{1}{2}\sqrt{\frac{15}{\pi}}yz$ | $\frac{1}{4}\sqrt{\frac{5}{\pi}}(2z^2 - x^2 - y^2)$ | $-\frac{1}{2}\sqrt{\frac{15}{\pi}}xz$ | $\frac{1}{4}\sqrt{\frac{15}{\pi}}(x^2 - y^2)$ |
+[Table [basisFunctions]: Normalized basis functions per band]
+
+### Decomposition and reconstruction
+
+A function $L(s)$ defined on a sphere is projected to the SH basis as follows:
+
+$$\begin{equation}
+L^m_l = \int_\Omega L(s) y^m_l(s) ds \\
+L^m_l = \int_{\theta = 0}^{\pi} \int_{\phi = 0}^{2\pi} L(\theta, \phi) y^m_l(\theta, \phi) sin \theta d\theta d\phi
+\end{equation}$$
+
+Note that each $L^m_l$ is a vector of 3 values, one for each RGB color channel.
+
+The inverse transformation, or reconstruction, or rendering, from the SH coefficients is given by:
+
+$$\begin{equation}
+\hat{L}(s) = \sum_l \sum_{m = -l}^l L^m_l y^m_l(s)
+\end{equation}$$
+
+### Decomposition of $\left< cos \theta \right>$
+
+Since $\left< cos \theta \right>$ does not depend on $\phi$ (azimuthal independence), the integral simplifies to:
+
+$$\begin{align*}
+C^0_l &= 2\pi \int_0^{\pi} \left< cos \theta \right> y^0_l(\theta) sin \theta d\theta \\
+C^0_l &= 2\pi K^m_l \int_0^{\frac{\pi}{2}} P^0_l(cos \theta) cos \theta sin \theta d\theta \\
+C^m_l &= 0, m != 0
+\end{align*}$$
+
+In [#Ramamoorthi01] an analytical solution to the integral is described:
+
+$$\begin{align*}
+C_1 &= \sqrt{\frac{\pi}{3}} \\
+C_{odd} &= 0 \\
+C_{l, even} &= 2\pi \sqrt{\frac{2l + 1}{4\pi}} \frac{(-1)^{\frac{l}{2} - 1}}{(l + 2)(l - 1)} \frac{l!}{2^l (\frac{l!}{2})^2}
+\end{align*}$$
+
+The first few coefficients are:
+
+$$\begin{align*}
+C_0 &= +0.88623 \\
+C_1 &= +1.02333 \\
+C_2 &= +0.49542 \\
+C_3 &= +0.00000 \\
+C_4 &= -0.11078
+\end{align*}$$
+
+Very few coefficients are needed to reasonably approximate $\left< cos \theta \right>$, as shown in figure [shCosThetaApprox].
+
+![Figure [shCosThetaApprox]: Approximation of $cos \theta$ with SH coefficients](images/chart_sh_cos_thera_approx.png)
+
+### Convolution
+
+Convolutions by a kernel $h$ that has a circular symmetry can be applied directly and easily in SH space:
+
+$$\begin{equation}
+(h * f)^m_l = \sqrt{\frac{4\pi}{2l + 1}} h^0_l(s) f^m_l(s)
+\end{equation}$$
+
+Conveniently, $\sqrt{\frac{4\pi}{2l + 1}} = \frac{1}{K^0_l}$, so in practice we pre-multiply $C_l$ by $\frac{1}{K^0_l}$ and we get a simpler expression:
+
+$$\begin{equation}
+\hat{C}_{l, even} = 2\pi \frac{(-1)^{\frac{l}{2} - 1}}{(l + 2)(l - 1)} \frac{l!}{2^l (\frac{l!}{2})^2} \\
+\hat{C}_1 = \frac{2\pi}{3}
+\end{equation}$$
+
+Here is the C++ code to compute $\hat{C}_l$:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+static double factorial(size_t n, size_t d = 1);
+
+// < cos(theta) > SH coefficients pre-multiplied by 1 / K(0,l)
+double computeTruncatedCosSh(size_t l) {
+    if (l == 0) {
+        return M_PI;
+    } else if (l == 1) {
+        return 2 * M_PI / 3;
+    } else if (l & 1) {
+        return 0;
+    }
+    const size_t l_2 = l / 2;
+    double A0 = ((l_2 & 1) ? 1.0 : -1.0) / ((l + 2) * (l - 1));
+    double A1 = factorial(l, l_2) / (factorial(l_2) * (1 << l));
+    return 2 * M_PI * A0 * A1;
+}
+
+// returns n! / d!
+double factorial(size_t n, size_t d ) {
+   d = std::max(size_t(1), d);
+   n = std::max(size_t(1), n);
+   double r = 1.0;
+   if (n == d) {
+       // intentionally left blank
+   } else if (n > d) {
+       for ( ; n>d ; n--) {
+           r *= n;
+       }
+   } else {
+       for ( ; d>n ; d--) {
+           r *= d;
+       }
+       r = 1.0 / r;
+   }
+   return r;
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+## Sample validation scene for Mitsuba
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+&lt;scene version="0.5.0"&gt;
+    &lt;integrator type="path"/&gt;
+
+    &lt;shape type="serialized" id="sphere_mesh"&gt;
+        &lt;string name="filename" value="plastic_sphere.serialized"/&gt;
+        &lt;integer name="shapeIndex" value="0"/&gt;
+
+        &lt;bsdf type="roughplastic"&gt;
+            &lt;string name="distribution" value="ggx"/&gt;
+            &lt;float name="alpha" value="0.0"/&gt;
+            &lt;srgb name="diffuseReflectance" value="0.81, 0.0, 0.0"/&gt;
+        &lt;/bsdf&gt;
+    &lt;/shape&gt;
+
+    &lt;emitter type="envmap"&gt;
+        &lt;string name="filename" value="../../environments/office/office.exr"/&gt;
+        &lt;float name="scale" value="35000.0" /&gt;
+        &lt;boolean name="cache" value="false" /&gt;
+    &lt;/emitter&gt;
+
+    &lt;emitter type="directional"&gt;
+        &lt;vector name="direction" x="-1" y="-1" z="1" /&gt;
+        &lt;rgb name="irradiance" value="120000.0, 115200.0, 114000.0" /&gt;
+    &lt;/emitter&gt;
+
+    &lt;sensor type="perspective"&gt;
+        &lt;float name="farClip" value="12.0"/&gt;
+        &lt;float name="focusDistance" value="4.1"/&gt;
+        &lt;float name="fov" value="45"/&gt;
+        &lt;string name="fovAxis" value="y"/&gt;
+        &lt;float name="nearClip" value="0.01"/&gt;
+        &lt;transform name="toWorld"&gt;
+
+            &lt;lookat target="0, 0, 0" origin="0, 0, -3.1" up="0, 1, 0"/&gt;
+        &lt;/transform&gt;
+
+        &lt;sampler type="ldsampler"&gt;
+            &lt;integer name="sampleCount" value="256"/&gt;
+        &lt;/sampler&gt;
+
+        &lt;film type="ldrfilm"&gt;
+            &lt;integer name="height" value="1440"/&gt;
+            &lt;integer name="width" value="2048"/&gt;
+            &lt;float name="exposure" value="-15.23" /&gt;
+            &lt;rfilter type="gaussian"/&gt;
+        &lt;/film&gt;
+    &lt;/sensor&gt;
+&lt;/scene&gt;
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+## Light assignment with froxels
+
+Assigning lights to froxels can be implemented on the GPU using two compute shaders. The first one, shown in listing [froxelGeneration], creates the froxels data (4 planes + a min Z and max Z per froxel) in an SSBO and needs to be run only once. The shader requires the following uniforms:
+
+Projection&nbsp;matrix
+:   The projection matrix used to render the scene (view space to clip space transformation).
+
+Inverse&nbsp;projection&nbsp;matrix
+:   The inverse of the projection matrix used to render the scene (clip space to view space transformation).
+
+Depth&nbsp;parameters
+:   $-log2(\frac{z_{lighnear}}{z_{far}}) \frac{1}{maxSlices-1}$, maximum number of depth slices, Z near and Z far.
+
+Clip&nbsp;space&nbsp;size
+:   $\frac{F_x \times F_r}{w} \times 2$, with $F_x$ the number of tiles on the X axis, $F_r$ the resolution in pixels of a tile and w the width in pixels of the render target.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#version 310 es
+
+precision highp float;
+precision highp int;
+
+
+#define FROXEL_RESOLUTION 80u
+
+layout(local_size_x = 1, local_size_y = 1, local_size_z = 1) in;
+
+layout(location = 0) uniform mat4 projectionMatrix;
+layout(location = 1) uniform mat4 projectionInverseMatrix;
+layout(location = 2) uniform vec4 depthParams; // index scale, index bias, near, far
+layout(location = 3) uniform float clipSpaceSize;
+
+struct Froxel {
+    // NOTE: the planes should be stored in vec4[4] but the
+    // Adreno shader compiler has a bug that causes the data
+    // to not be read properly inside the loop
+    vec4 plane0;
+    vec4 plane1;
+    vec4 plane2;
+    vec4 plane3;
+    vec2 minMaxZ;
+};
+
+layout(binding = 0, std140) writeonly restrict buffer FroxelBuffer {
+    Froxel data[];
+} froxels;
+
+shared vec4 corners[4];
+shared vec2 minMaxZ;
+
+vec4 projectionToView(vec4 p) {
+    p = projectionInverseMatrix * p;
+    return p / p.w;
+}
+
+vec4 createPlane(vec4 b, vec4 c) {
+    // standard plane equation, with a at (0, 0, 0)
+    return vec4(normalize(cross(c.xyz, b.xyz)), 1.0);
+}
+
+void main() {
+    uint index = gl_WorkGroupID.x + gl_WorkGroupID.y * gl_NumWorkGroups.x +
+            gl_WorkGroupID.z * gl_NumWorkGroups.x * gl_NumWorkGroups.y;
+
+    if (gl_LocalInvocationIndex == 0u) {
+        // first tile the screen and build the frustum for the current tile
+        vec2 renderTargetSize = vec2(FROXEL_RESOLUTION * gl_NumWorkGroups.xy);
+        vec2 frustumMin = vec2(FROXEL_RESOLUTION * gl_WorkGroupID.xy);
+        vec2 frustumMax = vec2(FROXEL_RESOLUTION * (gl_WorkGroupID.xy + 1u));
+
+        corners[0] = vec4(
+            frustumMin.x / renderTargetSize.x * clipSpaceSize - 1.0,
+            (renderTargetSize.y - frustumMin.y) / renderTargetSize.y
+			    * clipSpaceSize - 1.0,
+            1.0,
+            1.0
+        );
+        corners[1] = vec4(
+            frustumMax.x / renderTargetSize.x * clipSpaceSize - 1.0,
+            (renderTargetSize.y - frustumMin.y) / renderTargetSize.y
+			    * clipSpaceSize - 1.0,
+            1.0,
+            1.0
+        );
+        corners[2] = vec4(
+            frustumMax.x / renderTargetSize.x * clipSpaceSize - 1.0,
+            (renderTargetSize.y - frustumMax.y) / renderTargetSize.y
+			    * clipSpaceSize - 1.0,
+            1.0,
+            1.0
+        );
+        corners[3] = vec4(
+            frustumMin.x / renderTargetSize.x * clipSpaceSize - 1.0,
+            (renderTargetSize.y - frustumMax.y) / renderTargetSize.y
+			    * clipSpaceSize - 1.0,
+            1.0,
+            1.0
+        );
+
+        uint froxelSlice = gl_WorkGroupID.z;
+        minMaxZ = vec2(0.0, 0.0);
+        if (froxelSlice > 0u) {
+            minMaxZ.x = exp2((float(froxelSlice) - depthParams.y) * depthParams.x)
+                    * depthParams.w;
+        }
+        minMaxZ.y = exp2((float(froxelSlice + 1u) - depthParams.y) * depthParams.x)
+                * depthParams.w;
+    }
+
+    if (gl_LocalInvocationIndex == 0u) {
+        vec4 frustum[4];
+        frustum[0] = projectionToView(corners[0]);
+        frustum[1] = projectionToView(corners[1]);
+        frustum[2] = projectionToView(corners[2]);
+        frustum[3] = projectionToView(corners[3]);
+
+        froxels.data[index].plane0 = createPlane(frustum[0], frustum[1]);
+        froxels.data[index].plane1 = createPlane(frustum[1], frustum[2]);
+        froxels.data[index].plane2 = createPlane(frustum[2], frustum[3]);
+        froxels.data[index].plane3 = createPlane(frustum[3], frustum[0]);
+        froxels.data[index].minMaxZ = minMaxZ;
+    }
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+[Listing [froxelGeneration]: GLSL implementation of froxels data generation (compute shader)]
+
+The second compute shader, shown in listing [froxelEvaluation], runs every frame (if the camera and/or lights have changed) and assigns all the lights to their respective froxels. This shader relies only on a couple of uniforms (the number of point/spot lights and the view matrix) and four SSBOs:
+
+Light index buffer
+:   For each froxel, the index of each light that affects said froxel. The indices for point lights are written first and if there is enough space left, the indices for spot lights are written as well. A sentinel of value 0x7fffffffu separates point and spot lights and/or marks the end of the froxel's list of lights. Each froxel has a maximum number of lights (point + spot).
+
+Point lights buffer
+:   Array of structures describing the scene's point lights.
+
+Spot lights buffer
+:   Array of structures describing the scene's spot lights.
+
+Froxels buffer
+:   The list of froxels represented by planes, created by the previous compute shader.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#version 310 es
+precision highp float;
+precision highp int;
+
+#define LIGHT_BUFFER_SENTINEL 0x7fffffffu
+#define MAX_FROXEL_LIGHT_COUNT 32u
+
+#define THREADS_PER_FROXEL_X 8u
+#define THREADS_PER_FROXEL_Y 8u
+#define THREADS_PER_FROXEL_Z 1u
+#define THREADS_PER_FROXEL (THREADS_PER_FROXEL_X * \
+        THREADS_PER_FROXEL_Y * THREADS_PER_FROXEL_Z)
+
+layout(local_size_x = THREADS_PER_FROXEL_X,
+       local_size_y = THREADS_PER_FROXEL_Y,
+       local_size_z = THREADS_PER_FROXEL_Z) in;
+
+// x = point lights, y = spot lights
+layout(location = 0) uniform uvec2 totalLightCount;
+layout(location = 1) uniform mat4 viewMatrix;
+
+layout(binding = 0, packed) writeonly restrict buffer LightIndexBuffer {
+    uint index[];
+} lightIndexBuffer;
+
+struct PointLight {
+    vec4 positionFalloff; // x, y, z, falloff
+    vec4 colorIntensity;  // r, g, b, intensity
+    vec4 directionIES;    // dir x, dir y, dir z, IES profile index
+};
+
+layout(binding = 1, std140) readonly restrict buffer PointLightBuffer {
+    PointLight lights[];
+} pointLights;
+
+struct SpotLight {
+    vec4 positionFalloff; // x, y, z, falloff
+    vec4 colorIntensity;  // r, g, b, intensity
+    vec4 directionIES;    // dir x, dir y, dir z, IES profile index
+    vec4 angle;           // angle scale, angle offset, unused, unused
+};
+
+layout(binding = 2, std140) readonly restrict buffer SpotLightBuffer {
+    SpotLight lights[];
+} spotLights;
+
+struct Froxel {
+    // NOTE: the planes should be stored in vec4[4] but the
+    // Adreno shader compiler has a bug that causes the data
+    // to not be read properly inside the loop
+    vec4 plane0;
+    vec4 plane1;
+    vec4 plane2;
+    vec4 plane3;
+    vec2 minMaxZ;
+};
+
+layout(binding = 3, std140) readonly restrict buffer FroxelBuffer {
+    Froxel data[];
+} froxels;
+
+shared uint groupLightCounter;
+shared uint groupLightIndexBuffer[MAX_FROXEL_LIGHT_COUNT];
+
+float signedDistanceFromPlane(vec4 p, vec4 plane) {
+    // plane.w == 0.0, simplify computation
+    return dot(plane.xyz, p.xyz);
+}
+
+void synchronize() {
+    memoryBarrierShared();
+    barrier();
+}
+
+void main() {
+    if (gl_LocalInvocationIndex == 0u) {
+        groupLightCounter = 0u;
+    }
+    memoryBarrierShared();
+
+    uint froxelIndex = gl_WorkGroupID.x + gl_WorkGroupID.y * gl_NumWorkGroups.x +
+            gl_WorkGroupID.z * gl_NumWorkGroups.x * gl_NumWorkGroups.y;
+    Froxel current = froxels.data[froxelIndex];
+
+    uint offset = gl_LocalInvocationID.x +
+	        gl_LocalInvocationID.y * THREADS_PER_FROXEL_X;
+    for (uint i = 0u; i < totalLightCount.x &&
+		    groupLightCounter < MAX_FROXEL_LIGHT_COUNT &&
+            offset + i < totalLightCount.x; i += THREADS_PER_FROXEL) {
+
+        uint currentLight = offset + i;
+
+        vec4 center = pointLights.lights[currentLight].positionFalloff;
+        center.xyz = (viewMatrix * vec4(center.xyz, 1.0)).xyz;
+        float r = inversesqrt(center.w);
+
+        if (-center.z + r > current.minMaxZ.x &&
+                -center.z - r <= current.minMaxZ.y) {
+            if (signedDistanceFromPlane(center, current.plane0) < r &&
+                signedDistanceFromPlane(center, current.plane1) < r &&
+                signedDistanceFromPlane(center, current.plane2) < r &&
+                signedDistanceFromPlane(center, current.plane3) < r) {
+
+                uint index = atomicAdd(groupLightCounter, 1u);
+                groupLightIndexBuffer[index] = currentLight;
+            }
+        }
+    }
+
+    synchronize();
+
+    uint pointLightCount = groupLightCounter;
+    offset = froxelIndex * MAX_FROXEL_LIGHT_COUNT;
+
+    for (uint i = gl_LocalInvocationIndex; i < pointLightCount;
+            i += THREADS_PER_FROXEL) {
+        lightIndexBuffer.index[offset + i] = groupLightIndexBuffer[i];
+    }
+
+    if (gl_LocalInvocationIndex == 0u) {
+        if (pointLightCount < MAX_FROXEL_LIGHT_COUNT) {
+            lightIndexBuffer.index[offset + pointLightCount] = LIGHT_BUFFER_SENTINEL;
+        }
+    }
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+[Listing [froxelEvaluation]: GLSL implementation of assigning lights to froxels (compute shader)]
+
+# Revisions
+
+February 20, 2019: Cloth shading
+ - Removed Fresnel term from the cloth BRDF
+ - Removed cloth DFG approximations, replaced with a new channel in the DFG LUT
+
+August 21, 2018: Multiscattering
+ - Added section [Energy loss in specular reflectance] on how to compensate for energy loss in single scattering BRDFs
+
+August 17, 2018: Specular color
+ - Added section [Specular color] to explain how the base color of various metals is computed
+
+August 15, 2018: Fresnel
+ - Added a description of the Fresnel effect in section [Fresnel (specular F)]
+
+August 9, 2018: Lighting
+ - Added explanation about pre-exposed lights
+
+August 7, 2018: Cloth model
+ - Added description of the "Charlie" NDF
+
+August 3, 2018: First public version
+
+# Bibliography
+
+[#Ashdown98]: Ian Ashdown. 1998. Parsing the IESNA LM-63 photometric data file. http://lumen.iee.put.poznan.pl/kw/iesna.txt
+
+[#Ashikhmin00]: Michael Ashikhmin, Simon Premoze and Peter Shirley. A Microfacet-based BRDF Generator. *SIGGRAPH '00 Proceedings*, 65-74.
+
+[#Ashikhmin07]: Michael Ashikhmin and Simon Premoze. 2007. Distribution-based BRDFs.
+
+[#Burley12]: Brent Burley. 2012. Physically Based Shading at Disney. *Physically Based Shading in Film and Game Production, ACM SIGGRAPH 2012 Courses*.
+
+[#Estevez17]: Alejandro Conty Estevez and Christopher Kulla. 2017. Production Friendly Microfacet Sheen BRDF. *ACM SIGGRAPH 2017*.
+
+[#Hammon17]: Earl Hammon. 217. PBR Diffuse Lighting for GGX+Smith Microsurfaces. *GDC 2017*.
+
+[#Heitz14]: Eric Heitz. 2014. Understanding the Masking-Shadowing Function
+in Microfacet-Based BRDFs. *Journal of Computer Graphics Techniques*, 3 (2).
+
+[#Heitz16]: Eric Heitz et al. 2016. Multiple-Scattering Microfacet BSDFs with the Smith Model. *ACM SIGGRAPH 2016*.
+
+[#Hill12]: Colin Barré-Brisebois and Stephen Hill. 2012. Blending in Detail. http://blog.selfshadow.com/publications/blending-in-detail/
+
+[#Karis13a]: Brian Karis. 2013. Specular BRDF Reference. http://graphicrants.blogspot.com/2013/08/specular-brdf-reference.html
+
+[#Karis13b]: Brian Karis, 2013. Real Shading in Unreal Engine 4. https://blog.selfshadow.com/publications/s2013-shading-course/karis/s2013_pbs_epic_notes_v2.pdf
+
+[#Karis14]: Brian Karis. 2014. Physically Based Shading on Mobile. https://www.unrealengine.com/blog/physically-based-shading-on-mobile
+
+[#Kelemen01]: Csaba Kelemen et al. 2001. A Microfacet Based Coupled Specular-Matte BRDF Model with Importance Sampling. *Eurographics Short Presentations*.
+
+[#Krystek85]: M. Krystek. 1985. An algorithm to calculate correlated color temperature. *Color Research & Application*, 10 (1), 38–40.
+
+[#Krivanek08]: Jaroslave Krivànek and Mark Colbert. 2008. Real-time Shading with Filtered Importance Sampling. *Eurographics Symposium on Rendering 2008*, Volume 27, Number 4.
+
+[#Kulla17]: Christopher Kulla and Alejandro Conty. 2017. Revisiting Physically Based Shading at Imageworks. *ACM SIGGRAPH 2017*
+
+[#Lagarde14]: Sébastien Lagarde and Charles de Rousiers. 2014. Moving Frostbite to PBR. *Physically Based Shading in Theory and Practice, ACM SIGGRAPH 2014 Courses*.
+
+[#Lagarde18]: Sébastien Lagarde and Evgenii Golubev. 2018. The road toward unified rendering with Unity’s high definition rendering pipeline. *Advances in Real-Time Rendering in Games, ACM SIGGRAPH 2018 Courses*.
+
+[#Lazarov13]: Dimitar Lazarov. 2013. Physically-Based Shading in Call of Duty: Black Ops. *Physically Based Shading in Theory and Practice, ACM SIGGRAPH 2013 Courses*.
+
+[#McAuley15]: Stephen McAuley. 2015. Rendering the World of Far Cry 4. *GDC 2015*.
+
+[#McGuire10]: Morgan McGuire. 2010. Ambient Occlusion Volumes. *High Performance Graphics*.
+
+[#Narkowicz14]: Krzysztof Narkowicz. 2014. Analytical DFG Term for IBL. https://knarkowicz.wordpress.com/2014/12/27/analytical-dfg-term-for-ibl
+
+[#Neubelt13]: David Neubelt and Matt Pettineo. 2013. Crafting a Next-Gen Material Pipeline for The Order: 1886. *Physically Based Shading in Theory and Practice, ACM SIGGRAPH 2013 Courses*.
+
+[#Oren94]: Michael Oren and Shree K. Nayar. 1994. Generalization of lambert's reflectance model. *SIGGRAPH*, 239–246. ACM.
+
+[#Pattanaik00]: Sumanta Pattanaik00 et al. 2000. Time-Dependent Visual Adaptation
+For Fast Realistic Image Display. *SIGGRAPH '00 Proceedings of the 27th annual conference on Computer graphics and interactive techniques*, 47-54.
+
+[#Ramamoorthi01]: Ravi Ramamoorthi and Pat Hanrahan. 2001. On the relationship between radiance and irradiance: determining the illumination from images of a convex Lambertian object. *Journal of the Optical Society of America*, Volume 18, Number 10, October 2001.
+
+[#Revie12]: Donald Revie. 2012.  Implementing Fur in Deferred Shading. *GPU Pro 2*, Chapter 2.
+
+[#Russell15]: Jeff Russell. 2015. Horizon Occlusion for Normal Mapped Reflections. http://marmosetco.tumblr.com/post/81245981087
+
+[#Schlick94]: Christophe Schlick. 1994. An Inexpensive BRDF Model for Physically-Based Rendering. *Computer Graphics Forum*, 13 (3), 233–246.
+
+[#Walter07]: Bruce Walter et al. 2007. Microfacet Models for Refraction through Rough Surfaces. *Proceedings of the Eurographics Symposium on Rendering*.
+
+<!-- Markdeep: --><style class="fallback">body{visibility:hidden;white-space:pre;font-family:monospace}</style><script src="../third_party/markdeep/markdeep.min.js"></script><script src="https://casual-effects.com/markdeep/latest/markdeep.min.js"></script><script>window.alreadyProcessedMarkdeep||(document.body.style.visibility="visible")</script>
diff --git a/docs_src/markdeep/Materials.md.html b/docs_src/markdeep/Materials.md.html
new file mode 100644
index 00000000000..753e3a6b2f5
--- /dev/null
+++ b/docs_src/markdeep/Materials.md.html
@@ -0,0 +1,2661 @@
+               <meta charset="utf-8">
+
+<style>img { max-width: 100%; }</style>
+
+**Filament Materials Guide**
+
+![](images/filament_logo.png)
+
+# About
+
+This document is part of the [Filament project](https://github.com/google/filament). To report errors in this document please use the [project's issue tracker](https://github.com/google/filament/issues).
+
+## Authors
+
+- [Romain Guy](https://github.com/romainguy), [@romainguy](https://twitter.com/romainguy)
+- [Mathias Agopian](https://github.com/pixelflinger), [@darthmoosious](https://twitter.com/darthmoosious)
+
+# Overview
+
+Filament is a physically based rendering (PBR) engine for Android. Filament offers a customizable
+material system that you can use to create both simple and complex materials. This document
+describes all the features available to materials and how to create your own material.
+
+## Core concepts
+
+Material
+:   A material defines the visual appearance of a surface. To completely describe and render a
+    surface, a material provides the following information:
+    - Material model
+    - Set of use-controllable named parameters
+    - Raster state (blending mode, backface culling, etc.)
+    - Vertex shader code
+    - Fragment shader code
+
+Material model
+:   Also called _shading model_ or _lighting model_, the material model defines the intrinsic
+    properties of a surface. These properties have a direct influence on the way lighting is
+    computed and therefore on the appearance of a surface.
+
+Material definition
+:   A text file that describes all the information required by a material. This is the file that you
+    will directly author to create new materials.
+
+Material package
+:   At runtime, materials are loaded from _material packages_ compiled from material definitions
+    using the `matc` tool. A material package contains all the information required to describe a
+    material, and shaders generated for the target runtime platforms. This is necessary because
+    different platforms (Android, macOS, Linux, etc.) use different graphics APIs or different
+    variants of similar graphics APIs (OpenGL vs OpenGL ES for instance).
+
+Material instance
+:   A material instance is a reference to a material and a set of values for the different values of
+    that material. Material instances are not covered in this document as they are created and
+    manipulated directly from code using Filament's APIs.
+
+# Material models
+
+Filament materials can use one of the following material models:
+- Lit (or standard)
+- Subsurface
+- Cloth
+- Unlit
+- Specular glossiness (legacy)
+
+## Lit model
+
+The lit model is Filament's standard material model. This physically-based shading model was
+designed after to offer good interoperability with other common tools and engines such as _Unity 5_,
+_Unreal Engine 4_, _Substance Designer_ or _Marmoset Toolbag_.
+
+This material model can be used to describe many non-metallic surfaces (_dielectrics_)
+or metallic surfaces (_conductors_).
+
+The appearance of a material using the standard model is controlled using the properties described
+in table [standardProperties].
+
+
+        Property        |      Definition
+-----------------------:|:---------------------
+**baseColor**           | Diffuse albedo for non-metallic surfaces, and specular color for metallic surfaces
+**metallic**            | Whether a surface appears to be dielectric (0.0) or conductor (1.0). Often used as a binary value (0 or 1)
+**roughness**           | Perceived smoothness (1.0) or roughness (0.0) of a surface. Smooth surfaces exhibit sharp reflections
+**reflectance**         | Fresnel reflectance at normal incidence for dielectric surfaces. This directly controls the strength of the reflections
+**sheenColor**          | Strength of the sheen layer
+**sheenRoughness**      | Perceived smoothness or roughness of the sheen layer
+**clearCoat**           | Strength of the clear coat layer
+**clearCoatRoughness**  | Perceived smoothness or roughness of the clear coat layer
+**anisotropy**          | Amount of anisotropy in either the tangent or bitangent direction
+**anisotropyDirection** | Local surface direction in tangent space
+**ambientOcclusion**    | 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
+**normal**              | A detail normal used to perturb the surface using _bump mapping_ (_normal mapping_)
+**bentNormal**          | A normal pointing in the average unoccluded direction. Can be used to improve indirect lighting quality
+**clearCoatNormal**     | A detail normal used to perturb the clear coat layer using _bump mapping_ (_normal mapping_)
+**emissive**            | Additional diffuse albedo to simulate emissive surfaces (such as neons, etc.) This property is mostly useful in an HDR pipeline with a bloom pass
+**postLightingColor**   | Additional color that can be blended with the result of the lighting computations. See `postLightingBlending`
+**ior**                 | Index of refraction, either for refractive objects or as an alternative to reflectance
+**transmission**        | 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
+**absorption**          | Absorption factor for refractive objects
+**microThickness**      | Thickness of the thin layer of refractive objects
+**thickness**           | Thickness of the solid volume of refractive objects
+[Table [standardProperties]: Properties of the standard model]
+
+The type and range of each property is described in table [standardPropertiesTypes].
+
+        Property        |   Type   |            Range         |           Note
+-----------------------:|:--------:|:------------------------:|:-------------------------
+**baseColor**           | float4   |  [0..1]                  | Pre-multiplied linear RGB
+**metallic**            | float    |  [0..1]                  | Should be 0 or 1
+**roughness**           | float    |  [0..1]                  |
+**reflectance**         | float    |  [0..1]                  | Prefer values > 0.35
+**sheenColor**          | float3   |  [0..1]                  | Linear RGB
+**sheenRoughness**      | float    |  [0..1]                  |
+**clearCoat**           | float    |  [0..1]                  | Should be 0 or 1
+**clearCoatRoughness**  | float    |  [0..1]                  |
+**anisotropy**          | float    |  [-1..1]                 | Anisotropy is in the tangent direction when this value is positive
+**anisotropyDirection** | float3   |  [0..1]                  | Linear RGB, encodes a direction vector in tangent space
+**ambientOcclusion**    | float    |  [0..1]                  |
+**normal**              | float3   |  [0..1]                  | Linear RGB, encodes a direction vector in tangent space
+**bentNormal**          | float3   |  [0..1]                  | Linear RGB, encodes a direction vector in tangent space
+**clearCoatNormal**     | float3   |  [0..1]                  | Linear RGB, encodes a direction vector in tangent space
+**emissive**            | float4   |  rgb=[0..n], a=[0..1]    | Linear RGB intensity in nits, alpha encodes the exposure weight
+**postLightingColor**   | float4   |  [0..1]                  | Pre-multiplied linear RGB
+**ior**                 | float    |  [1..n]                  | Optional, usually deduced from the reflectance
+**transmission**        | float    |  [0..1]                  |
+**absorption**          | float3   |  [0..n]                  |
+**microThickness**      | float    |  [0..n]                  |
+**thickness**           | float    |  [0..n]                  |
+[Table [standardPropertiesTypes]: Range and type of the standard model's properties]
+
+
+!!! Note: About linear RGB
+    Several material model properties expect RGB colors. Filament materials use RGB colors in linear
+    space and you must take proper care of supplying colors in that space. See the Linear colors
+    section for more information.
+
+!!! Note: About pre-multiplied RGB
+    Filament materials expect colors to use pre-multiplied alpha. See the Pre-multiplied alpha
+    section for more information.
+
+!!! Note: About `absorption`
+    The light attenuation through the material is defined as $e^{-absorption \cdot distance}$,
+    and the distance depends on the `thickness` parameter. If `thickness` is not provided, then
+    the `absorption` parameter is used directly and the light attenuation through the material
+    becomes $1 - absorption$. To obtain a certain color at a desired distance, the above
+    equation can be inverted such as $absorption = -\frac{ln(color)}{distance}$.
+
+!!! Note: About `ior` and `reflectance`
+    The index of refraction (IOR) and the reflectance represent the same physical attribute,
+    therefore they don't need to be both specified. Typically, only the reflectance is specified,
+    and the IOR is deduced automatically. When only the IOR is specified, the reflectance is then
+    deduced automatically. It is possible to specify both, in which case their values are kept
+    as-is, which can lead to physically impossible materials, however, this might be desirable
+    for artistic reasons.
+
+!!! Note: About `thickness` and `microThickness` for refraction
+    `thickness` represents the thickness of solid objects in the direction of the normal, for
+    satisfactory results, this should be provided per fragment (e.g.: as a texture) or at least per
+    vertex. `microThickness` represent the thickness of the thin layer of an object, and can
+    generally be provided as a constant value. For example, a 1mm thin hollow sphere of radius 1m,
+    would have a `thickness` of 1 and a `microThickness` of 0.001. Currently `thickness` is not
+    used when `refractionType` is set to `thin`.
+
+### Base color
+
+The `baseColor` property defines the perceived color of an object (sometimes called albedo). The
+effect of `baseColor` depends on the nature of the surface, controlled by the `metallic` property
+explained in the Metallic section.
+
+Non-metals (dielectrics)
+: Defines the diffuse color of the surface. Real-world values are typically found in the range
+  $[10..240]$ if the value is encoded between 0 and 255, or in the range $[0.04..0.94]$ between 0
+  and 1. Several examples of base colors for non-metallic surfaces can be found in
+  table [baseColorsDielectrics].
+
+    Metal  |        sRGB         |  Hexadecimal |               Color
+----------:|:-------------------:|:------------:|-------------------------------------------------------
+Coal       | 0.19, 0.19, 0.19    | #323232      | <div style="background-color: #323232; width: 60px">&nbsp;</div>
+Rubber     | 0.21, 0.21, 0.21    | #353535      | <div style="background-color: #353535; width: 60px">&nbsp;</div>
+Mud        | 0.33, 0.24, 0.19    | #553d31      | <div style="background-color: #875c3c; width: 60px">&nbsp;</div>
+Wood       | 0.53, 0.36, 0.24    | #875c3c      | <div style="background-color: #c4c6c6; width: 60px">&nbsp;</div>
+Vegetation | 0.48, 0.51, 0.31    | #7b824e      | <div style="background-color: #7b824e; width: 60px">&nbsp;</div>
+Brick      | 0.58, 0.49, 0.46    | #947d75      | <div style="background-color: #947d75; width: 60px">&nbsp;</div>
+Sand       | 0.69, 0.66, 0.52    | #b1a884      | <div style="background-color: #b1a884; width: 60px">&nbsp;</div>
+Concrete   | 0.75, 0.75, 0.73    | #c0bfbb      | <div style="background-color: #c0bfbb; width: 60px">&nbsp;</div>
+[Table [baseColorsDielectrics]: `baseColor` for common non-metals]
+
+Metals (conductors)
+: Defines the specular color of the surface. Real-world values are typically found in the range
+  $[170..255]$ if the value is encoded between 0 and 255, or in the range $[0.66..1.0]$ between 0 and
+  1. Several examples of base colors for metallic surfaces can be found in table [baseColorsConductors].
+
+    Metal  |        sRGB         |  Hexadecimal |               Color
+----------:|:-------------------:|:------------:|-------------------------------------------------------
+Silver     | 0.97, 0.96, 0.91    | #f7f4e8     | <div style="background-color: #faf9f5; width: 60px">&nbsp;</div>
+Aluminum   | 0.91, 0.92, 0.92    | #e8eaea     | <div style="background-color: #f4f5f5; width: 60px">&nbsp;</div>
+Titanium   | 0.76, 0.73, 0.69    | #c1baaf     | <div style="background-color: #cec8c2; width: 60px">&nbsp;</div>
+Iron       | 0.77, 0.78, 0.78    | #c4c6c6     | <div style="background-color: #c0bdba; width: 60px">&nbsp;</div>
+Platinum   | 0.83, 0.81, 0.78    | #d3cec6     | <div style="background-color: #d6d1c8; width: 60px">&nbsp;</div>
+Gold       | 1.00, 0.85, 0.57    | #ffd891     | <div style="background-color: #fedc9d; width: 60px">&nbsp;</div>
+Brass      | 0.98, 0.90, 0.59    | #f9e596     | <div style="background-color: #f4e4ad; width: 60px">&nbsp;</div>
+Copper     | 0.97, 0.74, 0.62    | #f7bc9e     | <div style="background-color: #fbd8b8; width: 60px">&nbsp;</div>
+[Table [baseColorsConductors]: `baseColor` for common metals]
+
+### Metallic
+
+The `metallic` property defines whether the surface is a metallic (_conductor_) or a non-metallic
+(_dielectric_) surface. This property should be used as a binary value, set to either 0 or 1.
+Intermediate values are only truly useful to create transitions between different types of surfaces
+when using textures.
+
+This property can dramatically change the appearance of a surface. Non-metallic surfaces have
+chromatic diffuse reflection and achromatic specular reflection (reflected light does not change
+color). Metallic surfaces do not have any diffuse reflection and chromatic specular reflection
+(reflected light takes on the color of the surfaced as defined by `baseColor`). 
+
+The effect of `metallic` is shown in figure [metallicProperty] (click on the image to see a
+larger version).
+
+![Figure [metallicProperty]: `metallic` varying from 0.0
+(left) to 1.0 (right)](images/materials/metallic.png)
+
+### Roughness
+
+The `roughness` property controls the perceived smoothness of the surface. When `roughness` is set
+to 0, the surface is perfectly smooth and highly glossy. The rougher a surface is, the "blurrier"
+the reflections are. This property is often called _glossiness_ in other engines and tools, and is
+simply the opposite of the roughness (`roughness = 1 - glossiness`).
+
+### Non-metals
+
+The effect of `roughness` on non-metallic surfaces is shown in figure [roughnessProperty] (click
+on the image to see a larger version).
+
+![Figure [roughnessProperty]: Dielectric `roughness` varying from 0.0
+(left) to 1.0 (right)](images/materials/dielectric_roughness.png)
+
+### Metals
+
+The effect of `roughness` on metallic surfaces is shown in figure [roughnessConductorProperty]
+(click on the image to see a larger version).
+
+![Figure [roughnessConductorProperty]: Conductor `roughness` varying from 0.0
+(left) to 1.0 (right)](images/materials/conductor_roughness.png)
+
+### Refraction
+
+When refraction through an object is enabled (using a `refractonType` of `thin` or `solid`), the
+`roughness` property will also affect the refractions, as shown in figure
+[roughnessRefractionProperty] (click on the image to see a larger version).
+                             
+![Figure [roughnessRefractionProperty]: Refractive sphere with `roughness` varying from 0.0
+ (left) to 1.0 (right)](images/materials/refraction_roughness.png)
+
+### Reflectance
+
+The `reflectance` property only affects non-metallic surfaces. This property can be used to control
+the specular intensity and index of refraction of materials. This value is defined
+between 0 and 1 and represents a remapping of a  percentage of reflectance. For instance, the
+default value of 0.5 corresponds to a reflectance of 4%. Values below 0.35 (2% reflectance) should
+be avoided as no real-world materials have such low reflectance.
+
+The effect of `reflectance` on non-metallic surfaces is shown in figure [reflectanceProperty]
+(click on the image to see a larger version).
+
+![Figure [reflectanceProperty]: `reflectance` varying from 0.0 (left)
+to 1.0 (right)](images/materials/reflectance.png)
+
+Figure [reflectance] shows common values and how they relate to the mapping function.
+
+![Figure [reflectance]: Common reflectance values](images/diagram_reflectance.png)
+
+Table [commonMatReflectance] describes acceptable reflectance values for various types of materials
+(no real world material has a value under 2%).
+
+
+Material                   |    Reflectance   |        IOR       |   Linear value
+--------------------------:|:-----------------|:-----------------|:----------------
+Water                      | 2%               | 1.33             | 0.35
+Fabric                     | 4% to 5.6%       | 1.5 to 1.62      | 0.5 to 0.59
+Common liquids             | 2% to 4%         | 1.33 to 1.5      | 0.35 to 0.5
+Common gemstones           | 5% to 16%        | 1.58 to 2.33     | 0.56 to 1.0
+Plastics, glass            | 4% to 5%         | 1.5 to 1.58      | 0.5 to 0.56
+Other dielectric materials | 2% to 5%         | 1.33 to 1.58     | 0.35 to 0.56
+Eyes                       | 2.5%             | 1.38             | 0.39
+Skin                       | 2.8%             | 1.4              | 0.42
+Hair                       | 4.6%             | 1.55             | 0.54
+Teeth                      | 5.8%             | 1.63             | 0.6
+Default value              | 4%               | 1.5              | 0.5
+[Table [commonMatReflectance]: Reflectance of common materials]
+
+Note that the `reflectance` property also defines the index of refraction of the surface.
+When this property is defined it is not necessary to define the `ior` property. Setting
+either of these properties will automatically compute the other property. It is possible
+to specify both, in which case their values are kept as-is, which can lead to physically
+impossible materials, however, this might be desirable for artistic reasons.
+
+The `reflectance` property is designed as a normalized property in the range 0..1 which makes
+it easy to define from a texture.
+
+See section [Index of refraction] for more information about the `ior` property and refractive
+indices.
+
+### Sheen color
+
+The sheen color controls the color appearance and strength of an optional sheen layer on top of the
+base layer described by the properties above. The sheen layer always sits below the clear coat layer
+if such a layer is present.
+
+The sheen layer can be used to represent cloth and fabric materials. Please refer to 
+section [Cloth model] for more information about cloth and fabric materials.
+
+The effect of `sheenColor` is shown in figure [materialSheenColor]
+(click on the image to see a larger version).
+
+![Figure [materialSheenColor]: Different sheen colors](images/screenshot_sheen_color.png)
+
+!!! Note
+    If you do not need the other properties offered by the standard lit material model but want to
+    create a cloth-like or fabric-like appearance, it is more efficient to use the dedicated cloth
+    model described in section [Cloth model].
+
+### Sheen roughness
+
+The `sheenRoughness` property is similar to the `roughness` property but applies only to the
+sheen layer.
+
+The effect of `sheenRoughness` on a rough metal is shown in figure [sheenRoughnessProperty]
+(click on the image to see a larger version). In this picture, the base layer is a dark blue, with
+`metallic` set to `0.0` and `roughness` set to `1.0`.
+
+![Figure [sheenRoughnessProperty]: `sheenRoughness` varying from 0.0
+(left) to 1.0 (right)](images/materials/sheen_roughness.png)
+
+### Clear coat
+
+Multi-layer materials are fairly common, particularly materials with a thin translucent
+layer over a base layer. Real world examples of such materials include car paints, soda cans,
+lacquered wood and acrylic.
+
+The `clearCoat` property can be used to describe materials with two layers. The clear coat layer
+will always be isotropic and dielectric.
+
+![Figure [clearCoat]: Comparison of a carbon-fiber material under the standard material model
+(left) and the clear coat model (right)](images/material_carbon_fiber.png)
+
+The `clearCoat` property controls the strength of the clear coat layer. This should be treated as a
+binary value, set to either 0 or 1. Intermediate values are useful to control transitions between
+parts of the surface that have a clear coat layers and parts that don't.
+
+The effect of `clearCoat` on a rough metal is shown in figure [clearCoatProperty]
+(click on the image to see a larger version).
+
+![Figure [clearCoatProperty]: `clearCoat` varying from 0.0
+(left) to 1.0 (right)](images/materials/clear_coat.png)
+
+!!! Warning
+    The clear coat layer effectively doubles the cost of specular computations. Do not assign a
+    value, even 0.0, to the clear coat property if you don't need this second layer.
+
+!!! Note
+    The clear coat layer is added on top of the sheen layer if present.
+
+### Clear coat roughness
+
+The `clearCoatRoughness` property is similar to the `roughness` property but applies only to the
+clear coat layer.
+
+The effect of `clearCoatRoughness` on a rough metal is shown in figure [clearCoatRoughnessProperty]
+(click on the image to see a larger version).
+
+![Figure [clearCoatRoughnessProperty]: `clearCoatRoughness` varying from 0.0
+(left) to 1.0 (right)](images/materials/clear_coat_roughness.png)
+
+### Anisotropy
+
+Many real-world materials, such as brushed metal, can only be replicated using an anisotropic
+reflectance model. A material can be changed from the default isotropic model to an anisotropic
+model by using the `anisotropy` property.
+
+![Figure [anisotropic]: Comparison of isotropic material
+(left) and anistropic material (right)](images/material_anisotropic.png)
+
+The effect of `anisotropy` on a rough metal is shown in figure [anisotropyProperty]
+(click on the image to see a larger version).
+
+![Figure [anisotropyProperty]: `anisotropy` varying from 0.0
+(left) to 1.0 (right)](images/materials/anisotropy.png)
+
+The figure [anisotropyDir] below shows how the direction of the anisotropic highlights can be
+controlled by using either positive or negative values: positive values define anisotropy in the
+tangent direction and negative values in the bitangent direction.
+
+![Figure [anisotropyDir]: Positive (left) vs negative
+(right) `anisotropy` values](images/screenshot_anisotropy_direction.png)
+
+!!! Tip
+    The anisotropic material model is slightly more expensive than the standard material model. Do
+    not assign a value (even 0.0) to the `anisotropy` property if you don't need anisotropy.
+
+### Anisotropy direction
+
+The `anisotropyDirection` property defines the direction of the surface at a given point and thus
+control the shape of the specular highlights. It is specified as vector of 3 values that usually
+come from a texture, encoding the directions local to the surface in tangent space. Because the
+direction is in tangent space, the Z component should be set to 0.
+
+The effect of `anisotropyDirection` on a metal is shown in figure [anisotropyDirectionProperty]
+(click on the image to see a larger version).
+
+![Figure [anisotropyDirectionProperty]: Anisotropic metal rendered
+with a direction map](images/screenshot_anisotropy.png)
+
+The result shown in figure [anisotropyDirectionProperty] was obtained using the direction map shown
+in figure [anisotropyDirectionProperty].
+
+![Figure [anisotropyDirectionProperty]: Example of Lighting: specularAmbientOcclusiona direction map](images/screenshot_anisotropy_map.jpg)
+
+### Ambient occlusion
+
+The `ambientOcclusion` property defines how much of the ambient light is accessible to a surface
+point. It is a per-pixel shadowing factor between 0.0 (fully shadowed) and 1.0 (fully lit). This
+property only affects diffuse indirect lighting (image-based lighting), not direct lights such as
+directional, point and spot lights, nor specular lighting.
+
+![Figure [aoExample]: Comparison of materials without diffuse ambient occlusion
+(left) and with (right)](images/screenshot_ao.jpg)
+
+### Normal
+
+The `normal` property defines the normal of the surface at a given point. It usually comes from a
+_normal map_ texture, which allows to vary the property per-pixel. The normal is supplied in tangent
+space, which means that +Z points outside of the surface.
+
+For example, let's imagine that we want to render a piece of furniture covered in tufted leather.
+Modeling the geometry to accurately represent the tufted pattern would require too many triangles
+so we instead bake a high-poly mesh into a normal map. Once the base map is applied to a simplified
+mesh, we get the result in figure [normalMapped].
+
+Note that the `normal` property affects the _base layer_ and not the clear coat layer.
+
+![Figure [normalMapped]: Low-poly mesh without normal mapping (left)
+and with (right)](images/screenshot_normal_mapping.jpg)
+
+!!! Warning
+    Using a normal map increases the runtime cost of the material model.
+
+### Bent normal
+
+The `bentNormal` property defines the average unoccluded direction at a point on the surface. It is
+used to improve the accuracy of indirect lighting. Bent normals can also improve the quality of
+specular ambient occlusion (see section [Lighting: specularAmbientOcclusion] about
+`specularAmbientOcclusion`).
+
+Bent normals can greatly increase the visual fidelity of an asset with various cavities and concave
+areas, as shown in figure [bentNormalMapped]. See the areas of the ears, nostrils and eyes for
+instance.
+
+![Figure [bentNormalMapped]: Example of a model rendered with and without a bent normal map. Both
+versions use the same ambient occlusion map.](images/material_bent_normal.gif)
+
+### Clear coat normal
+
+The `clearCoatNormal` property defines the normal of the clear coat layer at a given point. It
+behaves otherwise like the `normal` property.
+
+![Figure [clearCoatNormalMapped]: A material with a clear coat normal
+map and a surface normal map](images/screenshot_clear_coat_normal.jpg)
+
+!!! Warning
+    Using a clear coat normal map increases the runtime cost of the material model.
+
+### Emissive
+
+The `emissive` property can be used to simulate additional light emitted by the surface. It is
+defined as a `float4` value that contains an RGB intensity in nits as well as an exposure
+weight (in the alpha channel).
+
+The intensity in nits allows an emissive surface to function as a light and can be used to recreate
+real world surfaces. For instance a computer display has an intensity between 200 and 1,000 nits.
+
+If you prefer to work in EV (or f-stops), you can simplify multiply your emissive color by the
+output of the API `filament::Exposure::luminance(ev)`. This API returns the luminance in nits of
+the specific EV. You can perform this conversion yourself using the following formula, where $L$
+is the final intensity in nits: $ L = 2^{EV - 3} $.
+
+The exposure weight carried in the alpha channel can be used to undo the camera exposure, and thus
+force an emissive surface to bloom. When the exposure weight is set to 0, the emissive intensity is
+not affected by the camera exposure. When the weight is set to 1, the intensity is multiplied by
+the camera exposure like with any regular light.
+
+### Post-lighting color
+
+The `postLightingColor` can be used to modify the surface color after lighting computations. This
+property has no physical meaning and only exists to implement specific effects or to help with
+debugging. This property is defined as a `float4` value containing a pre-multiplied RGB color in
+linear space.
+
+The post-lighting color is blended with the result of lighting according to the blending mode
+specified by the `postLightingBlending` material option. Please refer to the documentation of
+this option for more information.
+
+!!! Tip
+    `postLightingColor` can be used as a simpler `emissive` property by setting
+    `postLightingBlending` to `add` and by providing an RGB color with alpha set to `0.0`.
+
+### Index of refraction
+
+The `ior` property only affects non-metallic surfaces. This property can be used to control the
+index of refraction and the specular intensity of materials. The `ior` property is intended to
+be used with refractive (transmissive) materials, which are enabled when the `refractionMode` is
+set to `cubemap` or `screenspace`. It can also be used on non-refractive objects as an alternative
+to setting the reflectance.
+
+The index of refraction (or refractive index) of a material is a dimensionless number that describes
+how fast light travels through that material. The higher the number, the slower light travels
+through the medium. More importantly for rendering materials, the refractive index determines how
+the path light travels is bent when entering the material. Higher indices of refraction will cause
+light to bend further away from the initial path.
+
+Table [commonMatIOR] describes acceptable refractive indices for various types of materials.
+
+Material                   |        IOR       
+--------------------------:|:-----------------
+Air                        | 1.0
+Water                      | 1.33             
+Common liquids             | 1.33 to 1.5      
+Common gemstones           | 1.58 to 2.33     
+Plastics, glass            | 1.5 to 1.58      
+Other dielectric materials | 1.33 to 1.58     
+[Table [commonMatIOR]: Index of refraction of common materials]
+
+The appearance of a refractive material will greatly depend on the `refractionType` and
+`refractionMode` settings of the material. Refer to section
+[Blending and transparency: refractionType] and section [Blending and transparency: refractionMode]
+for more information.
+
+The effect of `ior` when `refractionMode` is set to `cubemap` and `refractionType` is set to `solid`
+can be seen in figure [iorProperty2] (click on the image to see a larger version).
+
+![Figure [iorProperty2]: `transmission` varying from 1.0
+(left) to 1.5 (right)](images/materials/ior.png)
+
+Figure [iorProperty] shows the comparison of a sphere of `ior` 1.0 with a sphere of `ior` 1.33, with
+the `refractionMode` set to `screenspace` and the `refractionType` set to `solid`
+(click on the image to see a larger version).
+
+![Figure [iorProperty]: `ior` of 1.0 (left) and 1.33 (right)](images/material_ior.png)
+
+Note that the `ior` property also defines the reflectance (or specular intensity) of the surface.
+When this property is defined it is not necessary to define the `reflectance` property. Setting
+either of these properties will automatically compute the other property. It is possible to specify
+both, in which case their values are kept as-is, which can lead to physically impossible materials,
+however, this might be desirable for artistic reasons.
+
+See the Reflectance section for more information on the `reflectance` property.
+
+!!! Tip
+    Refractive materials are affected by the `roughness` property. Rough materials will scatter
+    light, creating a diffusion effect useful to recreate "blurry" appearances such as frosted
+    glass, certain plastics, etc.
+
+### Transmission
+
+The `transmission` property defines what ratio of diffuse light is transmitted through a refractive
+material. This property only affects materials with a `refractionMode` set to `cubemap` or
+`screenspace`.
+
+When `transmission` is set to 0, no amount of light is transmitted and the diffuse component of
+the surface is 100% visible. When `transmission` is set to 1, all the light is transmitted and the
+diffuse component is not visible anymore, only the specular component is.
+
+The effect of `transmission` on a glossy dielectric (`ior` of 1.5, `refractionMode` set to
+`cubemap`, `refractionType` set to `solid`) is shown in figure [transmissionProperty]
+(click on the image to see a larger version).
+
+![Figure [transmissionProperty]: `transmission` varying from 0.0
+(left) to 1.0 (right)](images/materials/transmission.png)
+
+!!! Tip
+    The `transmission` property is useful to create decals, paint, etc. at the surface of refractive
+    materials.
+
+### Absorption
+
+The `absorption` property defines the absorption coefficients of light transmitted through the
+material. Figure [absorptionExample] shows the effect of `absorption` on a refracting object with
+an index of refraction of 1.5 and a base color set to white.
+
+![Figure [absorptionExample]: Refracting object without (left)
+and with (right) absorption](images/material_absorption.png)
+
+Transmittance through a volume is exponential with respect to the optical depth (defined either
+with `microThickness` or `thickness`). The computed color follows the following formula:
+
+$$color \cdot e^{-absorption \cdot distance}$$
+
+Where `distance` is either `microThickness` or `thickness`, that is the distance light will travel
+through the material at a given point. If no thickness/distance is specified, the computed color
+follows this formula instead:
+
+$$color \cdot (1 - absorption)$$
+
+The effect of varying the `absorption` coefficients is shown in figure [absorptionProperty]
+(click on the image to see a larger version). In this picture, the object has a fixed `thickness`
+of 4.5 and an index of refraction set to 1.3.
+
+![Figure [absorptionProperty]: `absorption` varying from (0.0, 0.02, 0.14)
+(left) to (0.0, 0.36, 2.3) (right)](images/materials/absorption.png)
+
+Setting the absorption coefficients directly can be unintuitive which is why we recommend working
+with a _transmittance color_ and a _"at distance"_ factor instead. These two parameters allow an
+artist to specify the precise color the material should have at a specified distance through the
+volume. The value to pass to `absorption` can be computed this way:
+
+$$absorption = -\frac{ln(transmittanceColor)}{atDistance}$$
+
+While this computation can be done in the material itself we recommend doing it offline whenever
+possible. Filament provides an API for this purpose, `Color::absorptionAtDistance()`.
+
+### Micro-thickness and thickness
+
+The `microThickness` and `thickness` properties define the optical depth of the material of a
+refracting object. `microThickness` is used when `refractionType` is set to `thin`, and `thickness`
+is used when `refractionType` is set to `volume`.
+
+`thickness` represents the thickness of solid objects in the direction of the normal, for
+satisfactory results, this should be provided per fragment (e.g.: as a texture) or at least per
+vertex.
+
+`microThickness` represent the thickness of the thin layer (shell) of an object, and can generally
+be provided as a constant value. For example, a 1mm thin hollow sphere of radius 1m, would have a
+`thickness` of 1 and a `microThickness` of 0.001. Currently `thickness` is not used when
+`refractionType` is set to `thin`. Both properties are made available for possible future use.
+
+Both `thickness` and `microThickness` are used to compute the transmitted color of the material
+when the `absorption` property is set. In solid volumes, `thickness` will also affect how light
+rays are refracted.
+
+The effect `thickness` in a solid volume with `refractionMode` set to `screenSpace` is shown in
+figure [thicknessProperty] (click on the image to see a larger version). Note how the `thickness`
+value not only changes the effect of `absorption` but also modifies the direction of the refracted
+light.
+
+![Figure [thicknessProperty]: `thickness` varying from 0.0
+(left) to 2.0 (right)](images/materials/thickness.png)
+
+Figure [varyingThickness] shows what a prism with spatially varying `thickness` looks like when
+the `refractionType` is set to `solid` and `absorption` coefficients are set.
+
+![Figure [varyingThickness]: `thickness` varying from 0.0 at the top of the prism to 3.0 at the
+bottom of the prism](images/material_thickness.png)
+
+## Subsurface model
+
+### Thickness
+
+### Subsurface color
+
+### Subsurface power
+
+## Cloth model
+
+All the material models described previously are designed to simulate dense surfaces, both at a
+macro and at a micro level. Clothes and fabrics are however often made of loosely connected threads
+that absorb and scatter incident light. When compared to hard surfaces, cloth is characterized by
+a softer specular lob with a large falloff and the presence of fuzz lighting, caused by
+forward/backward scattering. Some fabrics also exhibit two-tone specular colors
+(velvets for instance).
+
+Figure [materialCloth] shows how the standard material model fails to capture the appearance of a
+sample of denim fabric. The surface appears rigid (almost plastic-like), more similar to a tarp
+than a piece of clothing. This figure also shows how important the softer specular lobe caused by
+absorption and scattering is to the faithful recreation of the fabric.
+
+![Figure [materialCloth]: Comparison of denim fabric rendered using the standard model
+(left) and the cloth model (right)](images/screenshot_cloth.png)
+
+Velvet is an interesting use case for a cloth material model. As shown in figure [materialVelvet]
+this type of fabric exhibits strong rim lighting due to forward and backward scattering. These
+scattering events are caused by fibers standing straight at the surface of the fabric. When the
+incident light comes from the direction opposite to the view direction, the fibers will forward
+scatter the light. Similarly, when the incident light from the same direction as the view
+direction, the fibers will scatter the light backward.
+
+![Figure [materialVelvet]: Velvet fabric showcasing forward and
+backward scattering](images/screenshot_cloth_velvet.png)
+
+It is important to note that there are types of fabrics that are still best modeled by hard surface
+material models. For instance, leather, silk and satin can be recreated using the standard or
+anisotropic material models.
+
+The cloth material model encompasses all the parameters previously defined for the standard
+material mode except for _metallic_ and _reflectance_. Two extra parameters described in
+table [clothProperties] are also available.
+
+
+       Parameter      |      Definition
+---------------------:|:---------------------
+**sheenColor**        | Specular tint to create two-tone specular fabrics (defaults to $\sqrt{baseColor}$)
+**subsurfaceColor**   | Tint for the diffuse color after scattering and absorption through the material
+[Table [clothProperties]: Cloth model parameters]
+
+The type and range of each property is described in table [clothPropertiesTypes].
+
+       Property       |   Type   |            Range         |           Note
+---------------------:|:--------:|:------------------------:|:-------------------------
+**sheenColor**        | float3   |  [0..1]                  | Linear RGB
+**subsurfaceColor**   | float3   |  [0..1]                  | Linear RGB
+[Table [clothPropertiesTypes]: Range and type of the cloth model's properties]
+
+To create a velvet-like material, the base color can be set to black (or a dark color).
+Chromaticity information should instead be set on the sheen color. To create more common fabrics
+such as denim, cotton, etc. use the base color for chromaticity and use the default sheen color
+or set the sheen color to the luminance of the base color.
+
+!!! Tip
+    To see the effect of the `roughness` parameter make sure the `sheenColor` is brighter than
+    `baseColor`. This can be used to create a fuzz effect. Taking the luminance of `baseColor`
+    as the `sheenColor` will produce a fairly natural effect that works for common cloth. A dark
+    `baseColor` combined with a bright/saturated `sheenColor` can be used to create velvet.
+
+!!! Tip
+    The `subsurfaceColor` parameter should be used with care. High values can interfere with shadows
+    in some areas. It is best suited for subtle transmission effects through the material.
+
+### Sheen color
+
+The `sheenColor` property can be used to directly modify the specular reflectance. It offers
+better control over the appearance of cloth and gives give the ability to create
+two-tone specular materials.
+
+The effect of `sheenColor` is shown in figure [materialClothSheen]
+(click on the image to see a larger version).
+
+![Figure [materialClothSheen]: Blue fabric without (left) and with (right) sheen](images/screenshot_cloth_sheen.png)
+
+### Subsurface color
+
+The `subsurfaceColor` property is not physically-based and can be used to simulate the scattering,
+partial absorption and re-emission of light in certain types of fabrics. This is particularly
+useful to create softer fabrics.
+
+!!! Warning
+    The cloth material model is more expensive to compute when the `subsurfaceColor` property is used.
+
+The effect of `subsurfaceColor` is shown in figure [materialClothSubsurface]
+(click on the image to see a larger version).
+
+![Figure [materialClothSubsurface]: White cloth (left column) vs white cloth with
+brown subsurface scatting (right)](images/screenshot_cloth_subsurface.png)
+
+## Unlit model
+
+The unlit material model can be used to turn off all lighting computations. Its primary purpose is
+to render pre-lit elements such as a cubemap, external content (such as a video or camera stream),
+user interfaces, visualization/debugging etc. The unlit model exposes only two properties described
+in table [unlitProperties].
+
+       Property       |      Definition
+---------------------:|:---------------------
+**baseColor**         | Surface diffuse color
+**emissive**          | Additional diffuse color to simulate emissive surfaces. This property is mostly useful in an HDR pipeline with a bloom pass
+**postLightingColor** | Additional color to blend with base color and emissive
+[Table [unlitProperties]: Properties of the standard model]
+
+The type and range of each property is described in table [unlitPropertiesTypes].
+
+       Property       |   Type   |            Range         |           Note
+---------------------:|:--------:|:------------------------:|:-------------------------
+**baseColor**         | float4   |  [0..1]                  | Pre-multiplied linear RGB
+**emissive**          | float4   |  rgb=[0..n], a=[0..1]    | Linear RGB intensity in nits, alpha encodes the exposure weight
+**postLightingColor** | float4   |  [0..1]                  | Pre-multiplied linear RGB
+[Table [unlitPropertiesTypes]: Range and type of the unlit model's properties]
+
+The value of `postLightingColor` is blended with the sum of `emissive` and `baseColor` according to
+the blending mode specified by the `postLightingBlending` material option.
+
+Figure [materialUnlit] shows an example of the unlit material model
+(click on the image to see a larger version).
+
+![Figure [materialUnlit]: The unlit model is used to render debug information](images/screenshot_unlit.jpg)
+
+## Specular glossiness
+
+This alternative lighting model exists to comply with legacy standards. Since it is not a
+physically-based formulation, we do not recommend using it except when loading legacy assets.
+
+This model encompasses the parameters previously defined for the standard lit mode except for
+_metallic_, _reflectance_, and _roughness_. It adds parameters for _specularColor_ and _glossiness_.
+
+Parameter             |      Definition
+---------------------:|:---------------------
+**baseColor**         | Surface diffuse color
+**specularColor**     | Specular tint (defaults to black)
+**glossiness**        | Glossiness (defaults to 0.0)
+[Table [glossinessProperties]: Properties of the specular-glossiness shading model]
+
+The type and range of each property is described in table [glossinessPropertiesTypes].
+
+       Property       |   Type   |            Range         |           Note
+---------------------:|:--------:|:------------------------:|:-------------------------
+**baseColor**         | float4   |  [0..1]                  | Pre-multiplied linear RGB
+**specularColor**     | float3   |  [0..1]                  | Linear RGB
+**glossiness**        | float    |  [0..1]                  | Inverse of roughness
+[Table [glossinessPropertiesTypes]: Range and type of the specular-glossiness model's properties]
+
+# Material definitions
+
+A material definition is a text file that describes all the information required by a material:
+
+- Name
+- User parameters
+- Material model
+- Required attributes
+- Interpolants (called _variables_)
+- Raster state (blending mode, etc.)
+- Shader code (fragment shader, optionally vertex shader)
+
+## Format
+
+The material definition format is a format loosely based on [JSON](https://www.json.org/) that we
+call _JSONish_. At the top level a material definition is composed of 3 different blocks that use
+the JSON object notation:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ JSON
+material {
+    // material properties
+}
+
+vertex {
+    // vertex shader, optional
+}
+
+fragment {
+    // fragment shader
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A minimum viable material definition must contain a `material` preamble and a `fragment` block. The
+`vertex` block is optional.
+
+### Differences with JSON
+
+In JSON, an object is made of key/value _pairs_. A JSON pair has the following syntax:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ JSON
+"key" : value
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Where value can be a string, number, object, array or a literal (`true`, `false` or `null`). While
+this syntax is perfectly valid in a material definition, a variant without quotes around strings is
+also accepted in JSONish:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ JSON
+key : value
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Quotes remain mandatory when the string contains spaces.
+
+The `vertex` and `fragment` blocks contain unescaped, unquoted GLSL code, which is not valid in JSON.
+
+Single-line C++-style comments are allowed.
+
+The key of a pair is case-sensitive.
+
+The value of a pair is not case-sensitive.
+
+### Example
+
+The following code listing shows an example of a valid material definition. This definition uses
+the _lit_ material model (see Lit model section), uses the default opaque blending mode, requires
+that a set of UV coordinates be presented in the rendered mesh and defines 3 user parameters. The
+following sections of this document describe the `material` and `fragment` blocks in detail.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ JSON
+material {
+    name : "Textured material",
+    parameters : [
+        {
+           type : sampler2d,
+           name : texture
+        },
+        {
+           type : float,
+           name : metallic
+        },
+        {
+            type : float,
+            name : roughness
+        }
+    ],
+    requires : [
+        uv0
+    ],
+    shadingModel : lit,
+    blending : opaque
+}
+
+fragment {
+    void material(inout MaterialInputs material) {
+        prepareMaterial(material);
+        material.baseColor = texture(materialParams_texture, getUV0());
+        material.metallic = materialParams.metallic;
+        material.roughness = materialParams.roughness;
+    }
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+## Material block
+
+The material block is mandatory block that contains a list of property pairs to describe all
+non-shader data.
+
+### General: name
+
+Type
+:    `string`
+
+Value
+:     Any string. Double quotes are required if the name contains spaces.
+
+Description
+:     Sets the name of the material. The name is retained at runtime for debugging purpose.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ JSON
+material {
+    name : stone
+}
+
+material {
+    name : "Wet pavement"
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+### General: featureLevel
+
+Type
+:    `number`
+
+Value
+:     An integer value, either 1, 2 or 3. Defaults to 1.
+
+      Feature Level    |        Guaranteed features
+:----------------------|:---------------------------------
+1                      | 9 textures per material
+2                      | 9 textures per material, cubemap arrays, ESSL 3.10
+3                      | 12 textures per material, cubemap arrays, ESSL 3.10
+[Table [featureLevels]: Feature levels]
+
+Description
+:     Sets the feature level of the material. Each feature level defines a set of features the
+      material can use. If the material uses a feature not supported by the selected level, `matc`
+      will generate an error during compilation. A given feature level is guaranteed to support
+      all features of lower feature levels.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ JSON
+material {
+    featureLevel : 2
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Bugs
+:     `matc` doesn't verify that a material is not using features above its selected feature level.
+
+
+### General: shadingModel
+
+Type
+:    `string`
+
+Value
+:     Any of `lit`, `subsurface`, `cloth`, `unlit`, `specularGlossiness`. Defaults to `lit`.
+
+Description
+:     Selects the material model as described in the Material models section.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ JSON
+material {
+    shadingModel : unlit
+}
+
+material {
+    shadingModel : "subsurface"
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+### General: parameters
+
+Type
+:    array of parameter objects
+
+Value
+:     Each entry is an object with the properties `name` and `type`, both of `string` type. The
+      name must be a valid GLSL identifier. Entries also have an optional `precision`, which can be
+      one of `default` (best precision for the platform, typically `high` on desktop, `medium` on
+      mobile), `low`, `medium`, `high`. The type must be one of the types described in
+      table [materialParamsTypes].
+
+         Type          |            Description
+:----------------------|:---------------------------------
+bool                   | Single boolean
+bool2                  | Vector of 2 booleans
+bool3                  | Vector of 3 booleans
+bool4                  | Vector of 4 booleans
+float                  | Single float
+float2                 | Vector of 2 floats
+float3                 | Vector of 3 floats
+float4                 | Vector of 4 floats
+int                    | Single integer
+int2                   | Vector of 2 integers
+int3                   | Vector of 3 integers
+int4                   | Vector of 4 integers
+uint                   | Single unsigned integer
+uint2                  | Vector of 2 unsigned integers
+uint3                  | Vector of 3 unsigned integers
+uint4                  | Vector of 4 unsigned integers
+float3x3               | Matrix of 3x3 floats
+float4x4               | Matrix of 4x4 floats
+sampler2d              | 2D texture
+sampler2dArray         | Array of 2D textures
+samplerExternal        | External texture (platform-specific)
+samplerCubemap         | Cubemap texture
+[Table [materialParamsTypes]: Material parameter types]
+
+Samplers
+:     Sampler types can also specify a `format` which can be either `int` or `float` (defaults to
+      `float`).
+
+Arrays
+:     A parameter can define an array of values by appending `[size]` after the type name, where
+      `size` is a positive integer. For instance: `float[9]` declares an array of nine `float`
+      values. This syntax does not apply to samplers as arrays are treated as separate types.
+
+Description
+:     Lists the parameters required by your material. These parameters can be set at runtime using
+      Filament's material API. Accessing parameters from the shaders varies depending on the type of
+      parameter:
+
+    - **Samplers types**: use the parameter name prefixed with `materialParams_`. For instance,
+      `materialParams_myTexture`.
+    - **Other types**: use the parameter name as the field of a structure called `materialParams`.
+      For instance, `materialParams.myColor`.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ JSON
+material {
+    parameters : [
+        {
+           type : float4,
+           name : albedo
+        },
+        {
+           type      : sampler2d,
+           format    : float,
+           precision : high,
+           name      : roughness
+        },
+        {
+            type : float2,
+            name : metallicReflectance
+        }
+    ],
+    requires : [
+        uv0
+    ],
+    shadingModel : lit,
+}
+
+fragment {
+    void material(inout MaterialInputs material) {
+        prepareMaterial(material);
+        material.baseColor = materialParams.albedo;
+        material.roughness = texture(materialParams_roughness, getUV0());
+        material.metallic = materialParams.metallicReflectance.x;
+        material.reflectance = materialParams.metallicReflectance.y;
+    }
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+### General: constants
+
+Type
+:   array of constant objects
+
+Value
+:   Each entry is an object with the properties `name` and `type`, both of `string` type. The name
+    must be a valid GLSL identifier. Entries also have an optional `default`, which can either be a
+    `bool` or `number`, depending on the `type` of the constant. The type must be one of the types
+    described in table [materialConstantsTypes].
+
+         Type          |            Description                   |      Default
+:----------------------|:-----------------------------------------|:------------------
+int                    | A signed, 32 bit GLSL int                |         0
+float                  | A single-precision GLSL float            |         0.0
+bool                   | A GLSL bool                              |         false
+[Table [materialConstantsTypes]: Material constants types]
+
+Description
+:   Lists the constant parameters accepted by your material. These constants can be set, or
+    "specialized", at runtime when loading a material package. Multiple materials can be loaded from
+    the same material package with differing constant parameter specializations. Once a material is
+    loaded from a material package, its constant parameters cannot be changed. Compared to regular
+    parameters, constant parameters allow the compiler to generate more efficient code. Access
+    constant parameters from the shader by prefixing the name with `materialConstant_`. For example,
+    a constant parameter named `myConstant` is accessed in the shader as
+    `materialConstant_myConstant`. If a constant parameter is not set at runtime, the default is
+    used.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ JSON
+material {
+    constants : [
+        {
+           name : overrideAlpha,
+           type : bool
+        },
+        {
+           name : customAlpha,
+           type : float,
+           default : 0.5
+        }
+    ],
+    shadingModel : lit,
+    blending : transparent,
+}
+
+fragment {
+    void material(inout MaterialInputs material) {
+        prepareMaterial(material);
+        if (materialConstants_overrideAlpha) {
+            material.baseColor.a = materialConstants_customAlpha;
+            material.baseColor.rgb *= material.baseColor.a;
+        }
+    }
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+### General: variantFilter
+
+Type
+:    array of `string`
+
+Value
+:     Each entry must be any of `dynamicLighting`, `directionalLighting`, `shadowReceiver`,
+      `skinning`, `ssr`, or `stereo`.
+
+Description
+:     Used to specify a list of shader variants that the application guarantees will never be
+      needed. These shader variants are skipped during the code generation phase, thus reducing
+      the overall size of the material.
+      Note that some variants may automatically be filtered out. For instance, all lighting related
+      variants (`directionalLighting`, etc.) are filtered out when compiling an `unlit` material.
+      Use the variant filter with caution, filtering out a variant required at runtime may lead
+      to crashes.
+
+Description of the variants:
+- `directionalLighting`, used when a directional light is present in the scene
+- `dynamicLighting`, used when a non-directional light (point, spot, etc.) is present in the scene
+- `shadowReceiver`, used when an object can receive shadows
+- `skinning`, used when an object is animated using GPU skinning
+- `fog`, used when global fog is applied to the scene
+- `vsm`, used when VSM shadows are enabled and the object is a shadow receiver
+- `ssr`, used when screen-space reflections are enabled in the View
+- `stereo`, used when stereoscopic rendering is enabled in the View
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ JSON
+material {
+    name : "Invisible shadow plane",
+    shadingModel : unlit,
+    shadowMultiplier : true,
+    blending : transparent,
+    variantFilter : [ skinning ]
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+### General: flipUV
+
+Type
+:    `boolean`
+
+Value
+:     `true` or `false`. Defaults to `true`.
+
+Description
+:    When set to `true` (default value), the Y coordinate of UV attributes will be flipped when
+     read by this material's vertex shader. Flipping is equivalent to `y = 1.0 - y`. When set
+     to `false`, flipping is disabled and the UV attributes are read as is.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ JSON
+material {
+    flipUV : false
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+### General: quality
+
+Type
+:    `string`
+
+Value
+:     Any of `low`, `normal`, `high`, `default`. Defaults to `default`.
+
+Description
+:    Set some global quality parameters of the material. `low` enables optimizations that can
+     slightly affect correctness and is the default on mobile platforms. `normal` does not affect
+     correctness and is otherwise similar to `low`. `high` enables quality settings that can
+     adversely affect performance and is the default on desktop platforms.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ JSON
+material {
+    quality : default
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+### General: instanced
+
+Type
+:    `boolean`
+
+Value
+:     `true` or `false`. Defaults to `false`.
+
+Description
+:    Allows a material to access the instance index (i.e.: **`gl_InstanceIndex`**) of instanced
+     primitives using `getInstanceIndex()` in the material's shader code. Never use
+     **`gl_InstanceIndex`** directly. This is typically used with
+     `RenderableManager::Builder::instances()`. `getInstanceIndex()` is available in both the
+     vertex and fragment shader.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ JSON
+material {
+    instanced : true
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+### General: vertexDomainDeviceJittered
+
+Type
+:    `boolean`
+
+Value
+:     `true` or `false`. Defaults to `false`.
+
+Description
+:    Only meaningful for `vertexDomain:Device` materials, this parameter specifies whether the
+     filament clip-space transforms need to be applied or not, which affects TAA and guard bands.
+     Generally it needs to be applied because by definition `vertexDomain:Device` materials
+     vertices are not transformed and used *as is*.
+     However, if the vertex shader uses for instance `getViewFromClipMatrix()` (or other
+     matrices based on the projection), the clip-space transform is already applied.
+     Setting this parameter incorrectly can prevent TAA or the guard bands to work correctly.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ JSON
+material {
+    vertexDomainDeviceJittered : true
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+### Vertex and attributes: requires
+
+Type
+:    array of `string`
+
+Value
+:     Each entry must be any of `uv0`, `uv1`, `color`, `position`, `tangents`, `custom0`
+      through `custom7`.
+
+Description
+:     Lists the vertex attributes required by the material. The `position` attribute is always
+      required and does not need to be specified. The `tangents` attribute is automatically required
+      when selecting any shading model that is not `unlit`. See the shader sections of this document
+      for more information on how to access these attributes from the shaders.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ JSON
+material {
+    parameters : [
+        {
+           type : sampler2d,
+           name : texture
+        },
+    ],
+    requires : [
+        uv0,
+        custom0
+    ],
+    shadingModel : lit,
+}
+
+fragment {
+    void material(inout MaterialInputs material) {
+        prepareMaterial(material);
+        material.baseColor = texture(materialParams_texture, getUV0());
+        material.baseColor.rgb *= getCustom0().rgb;
+    }
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+### Vertex and attributes: variables
+
+Type
+:    array of `string`
+
+Value
+:     Up to 4 strings, each must be a valid GLSL identifier.
+
+Description
+:     Defines custom interpolants (or variables) that are output by the material's vertex shader.
+      Each entry of the array defines the name of an  interpolant. The full name in the fragment
+      shader is the name of the interpolant with the `variable_` prefix. For instance, if you
+      declare a variable called `eyeDirection` you can access it in the fragment shader using
+      `variable_eyeDirection`. In the vertex shader, the interpolant name is simply a member of
+      the `MaterialVertexInputs` structure (`material.eyeDirection` in your example). Each
+      interpolant is of type `float4` (`vec4`) in the shaders. By default the precision of the
+      interpolant is `highp` in *both* the vertex and fragment shaders.
+      An alternate syntax can be used to specify both the name and precision of the interpolant.
+      In this case the specified precision is used as-is in both fragment and vertex stages, in
+      particular if `default` is specified the default precision is used is the fragment shader
+      (`mediump`) and in the vertex shader (`highp`).
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ JSON
+material {
+    name : Skybox,
+    parameters : [
+        {
+           type : samplerCubemap,
+           name : skybox
+        }
+    ],
+    variables : [
+         eyeDirection,
+         {
+            name : eyeColor,
+            precision : medium
+         }
+    ],
+    vertexDomain : device,
+    depthWrite : false,
+    shadingModel : unlit
+}
+
+fragment {
+    void material(inout MaterialInputs material) {
+        prepareMaterial(material);
+        float3 sky = texture(materialParams_skybox, variable_eyeDirection.xyz).rgb;
+        material.baseColor = vec4(sky, 1.0);
+    }
+}
+
+vertex {
+    void materialVertex(inout MaterialVertexInputs material) {
+        float3 p = getPosition().xyz;
+        float3 u = mulMat4x4Float3(getViewFromClipMatrix(), p).xyz;
+        material.eyeDirection.xyz = mulMat3x3Float3(getWorldFromViewMatrix(), u);
+    }
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+### Vertex and attributes: vertexDomain
+
+Type
+:    `string`
+
+Value
+:     Any of `object`, `world`, `view`, `device`. Defaults to `object`.
+
+Description
+:     Defines the domain (or coordinate space) of the rendered mesh. The domain influences how the
+      vertices are transformed in the vertex shader. The possible domains are:
+
+     - **Object**: the vertices are defined in the object (or model) coordinate space. The
+       vertices are transformed using the rendered object's transform matrix
+     - **World**: the vertices are defined in world coordinate space. The vertices are not
+       transformed using the rendered object's transform.
+     - **View**: the vertices are defined in view (or eye or camera) coordinate space. The
+       vertices are not transformed using the rendered object's transform.
+     - **Device**:  the vertices are defined in normalized device (or clip) coordinate space.
+       The vertices are not transformed using the rendered object's transform.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ JSON
+material {
+    vertexDomain : device
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+### Vertex and attributes: interpolation
+
+Type
+:    `string`
+
+Value
+:     Any of `smooth`, `flat`. Defaults to `smooth`.
+
+Description
+:     Defines how interpolants (or variables) are interpolated between vertices. When this property
+      is set to `smooth`, a perspective correct interpolation is performed on each interpolant.
+      When set to `flat`, no interpolation is performed and all the fragments within a given
+      triangle will be shaded the same.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ JSON
+material {
+    interpolation : flat
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+### Blending and transparency: blending
+
+Type
+:    `string`
+
+Value
+:     Any of `opaque`, `transparent`, `fade`, `add`, `masked`, `multiply`, `screen`, `custom`. Defaults to `opaque`.
+
+Description
+:     Defines how/if the rendered object is blended with the content of the render target.
+      The possible blending modes are:
+
+    - **Opaque**: blending is disabled, the alpha channel of the material's output is ignored.
+    - **Transparent**: blending is enabled. The material's output is alpha composited with the
+      render target, using Porter-Duff's `source over` rule. This blending mode assumes
+      pre-multiplied alpha.
+    - **Fade**: acts as `transparent` but transparency is also applied to specular lighting. In
+      `transparent` mode, the material's alpha values only applies to diffuse lighting. This
+      blending mode is useful to fade lit objects in and out.
+    - **Add**: blending is enabled. The material's output is added to the content of the
+      render target.
+    - **Multiply**: blending is enabled. The material's output is multiplied with the content of the
+      render target, darkening the content.
+    - **Screen**: blending is enabled. Effectively the opposite of the `multiply`, the content of the
+      render target is brightened.
+    - **Masked**: blending is disabled. This blending mode enables alpha masking. The alpha channel
+      of the material's output defines whether a fragment is discarded or not. Additionally,
+      ALPHA_TO_COVERAGE is enabled for non-translucent views. See the maskThreshold section for more
+      information.
+    - **Custom**: blending is enabled. But the blending function is user specified. See `blendFunction`.
+
+!!! Note
+    When `blending` is set to `masked`, alpha to coverage is automatically enabled for the material.
+    If this behavior is undesirable, refer to the Rasterization: alphaToCoverage section to turn
+    alpha to coverage off using the `alphaToCoverage` property.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ JSON
+material {
+    blending : transparent
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+### Blending and transparency: blendFunction
+
+Type
+:    `object`
+
+Fields
+:     `srcRGB`, `srcA`, `dstRGB`, `dstA`
+
+Description
+:       - *srcRGB*: source function applied to the RGB channels
+        - *srcA*: source function applied to the alpha channel
+        - *srcRGB*: destination function applied to the RGB channels
+        - *srcRGB*: destination function applied to the alpha channel
+        The values possible for each functions are one of `zero`, `one`, `srcColor`, `oneMinusSrcColor`,
+               `dstColor`, `oneMinusDstColor`, `srcAlpha`, `oneMinusSrcAlpha`, `dstAlpha`,
+               `oneMinusDstAlpha`, `srcAlphaSaturate`
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ JSON
+material {
+    blending : custom,
+    blendFunction :
+    {
+        srcRGB: one,
+        srcA: one,
+        dstRGB: oneMinusSrcColor,
+        dstA: oneMinusSrcAlpha
+    }
+ }
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+### Blending and transparency: postLightingBlending
+
+Type
+:    `string`
+
+Value
+:     Any of `opaque`, `transparent`, `add`. Defaults to `transparent`.
+
+Description
+:     Defines how the `postLightingColor` material property is blended with the result of the
+      lighting computations. The possible blending modes are:
+
+    - **Opaque**: blending is disabled, the material will output `postLightingColor` directly.
+    - **Transparent**: blending is enabled. The material's computed color is alpha composited with
+      the `postLightingColor`, using Porter-Duff's `source over` rule. This blending mode assumes
+      pre-multiplied alpha.
+    - **Add**: blending is enabled. The material's computed color is added to `postLightingColor`.
+    - **Multiply**: blending is enabled. The material's computed color is multiplied with `postLightingColor`.
+    - **Screen**: blending is enabled. The material's computed color is inverted and multiplied with `postLightingColor`,
+      and the result is added to the material's computed color.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ JSON
+material {
+    postLightingBlending : add
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+### Blending and transparency: transparency
+
+Type
+:    `string`
+
+Value
+:     Any of `default`, `twoPassesOneSide` or `twoPassesTwoSides`. Defaults to `default`.
+
+Description
+:     Controls how transparent objects are rendered. It is only valid when the `blending` mode is
+      not `opaque` and `refractionMode` is `none`. None of these methods can accurately render
+      concave geometry, but in practice they are often good enough.
+
+The three possible transparency modes are:
+- `default`: the transparent object is rendered normally (as seen in figure [transparencyDefault]),
+   honoring the `culling` mode, etc.
+- `twoPassesOneSide`: the transparent object is first rendered in the depth buffer, then again in
+  the color buffer, honoring the `culling` mode. This effectively renders only half of the
+  transparent object as shown in figure [transparencyTwoPassesOneSide].
+- `twoPassesTwoSides`: the transparent object is rendered twice in the color buffer: first with its
+  back faces, then with its front faces. This mode lets you render both set of faces while reducing
+  or eliminating sorting issues, as shown in figure [transparencyTwoPassesTwoSides].
+  `twoPassesTwoSides` can be combined with `doubleSided` for better effect.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ JSON
+material {
+    transparency : twoPassesOneSide
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+![Figure [transparencyDefault]: This double sided model shows the type of sorting issues transparent
+objects can be subject to in `default` mode](images/screenshot_transparency_default.png)
+
+![Figure [transparencyTwoPassesOneSide]: In `twoPassesOneSide` mode, only one set of faces is visible
+and correctly sorted](images/screenshot_twopasses_oneside.png)
+
+![Figure [transparencyTwoPassesTwoSides]: In `twoPassesTwoSides` mode, both set of faces are visible
+and sorting issues are minimized or eliminated](images/screenshot_twopasses_twosides.png)
+
+### Blending and transparency: maskThreshold
+
+Type
+:    `number`
+
+Value
+:     A value between `0.0` and `1.0`. Defaults to `0.4`.
+
+Description
+:     Sets the minimum alpha value a fragment must have to not be discarded when the `blending` mode
+      is set to `masked`. If the fragment is not discarded, its source alpha is set to 1. When the
+      blending mode is not `masked`, this value is ignored. This value can be used to controlled the
+      appearance of alpha-masked objects.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ JSON
+material {
+    blending : masked,
+    maskThreshold : 0.5
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+### Blending and transparency: refractionMode
+
+Type
+:    `string`
+
+Value
+:     Any of `none`, `cubemap`, `screenspace`. Defaults to `none`.
+
+Description
+:     Activates refraction when set to anything but `none`. A value of `cubemap` will only use the
+      IBL cubemap as source of refraction, while this is significantly more efficient, no scene
+      objects will be refracted, only the distant environment encoded in the cubemap. This mode is
+      adequate for an object viewer for instance. A value of `screenspace` will employ the more
+      advanced screen-space refraction algorithm which allows opaque objects in the scene to be
+      refracted. In `cubemap` mode, refracted rays are assumed to emerge from the center of the
+      object and the `thickness` parameter is only used for computing the absorption, but has no
+      impact on the refraction itself. In `screenspace` mode, refracted rays are assumed to travel
+      parallel to the view direction when they exit the refractive medium.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ JSON
+material {
+    refractionMode : cubemap,
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+### Blending and transparency: refractionType
+
+Type
+:    `string`
+
+Value
+:     Any of `solid`, `thin`. Defaults to `solid`.
+
+Description
+:     This is only meaningful when `refractionMode` is set to anything but `none`. `refractionType`
+      defines the refraction model used. `solid` is used for thick objects such as a crystal ball,
+      an ice cube or as sculpture. `thin` is used for thin objects such as a window, an ornament
+      ball or a soap bubble. In `solid` mode all refracive objects are assumed to be a sphere
+      tangent to the entry point and of radius `thickness`. In `thin` mode, all refractive objects
+      are assumed to be flat and thin and of thickness `thickness`.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ JSON
+material {
+    refractionMode : cubemap,
+    refractionType : thin,
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+### Rasterization: culling
+
+Type
+:    `string`
+
+Value
+:     Any of `none`, `front`, `back`, `frontAndBack`. Defaults to `back`.
+
+Description
+:     Defines which triangles should be culled: none, front-facing triangles, back-facing
+      triangles or all.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ JSON
+material {
+    culling : none
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+### Rasterization: colorWrite
+
+Type
+:    `boolean`
+
+Value
+:     `true` or `false`. Defaults to `true`.
+
+Description
+:     Enables or disables writes to the color buffer.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ JSON
+material {
+    colorWrite : false
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+### Rasterization: depthWrite
+
+Type
+:    `boolean`
+
+Value
+:     `true` or `false`. Defaults to `true` for opaque materials, `false` for transparent materials.
+
+Description
+:     Enables or disables writes to the depth buffer.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ JSON
+material {
+    depthWrite : false
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+### Rasterization: depthCulling
+
+Type
+:    `boolean`
+
+Value
+:     `true` or `false`. Defaults to `true`.
+
+Description
+:     Enables or disables depth testing. When depth testing is disabled, an object rendered with
+      this material will always appear on top of other opaque objects.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ JSON
+material {
+    depthCulling : false
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+### Rasterization: doubleSided
+
+Type
+:    `boolean`
+
+Value
+:     `true` or `false`. Defaults to `false`.
+
+Description
+:     Enables two-sided rendering and its capability to be toggled at run time. When set to `true`,
+      `culling` is automatically set to `none`; if the triangle is back-facing, the triangle's
+      normal is flipped to become front-facing. When explicitly set to `false`, this allows the
+      double-sidedness to be toggled at run time.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ JSON
+material {
+    name : "Double sided material",
+    shadingModel : lit,
+    doubleSided : true
+}
+
+fragment {
+    void material(inout MaterialInputs material) {
+        prepareMaterial(material);
+        material.baseColor = materialParams.albedo;
+    }
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+### Rasterization: alphaToCoverage
+
+Type
+:    `boolean`
+
+Value
+:     `true` or `false`. Defaults to `false`.
+
+Description
+:     Enables or disables alpha to coverage. When alpha to coverage is enabled, the coverage of
+      fragment is derived from its alpha. This property is only meaningful when MSAA is enabled.
+      Note: setting `blending` to `masked` automatically enables alpha to coverage. If this is not
+      desired, you can override this behavior by setting alpha to coverage to false as in the
+      example below.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ JSON
+material {
+    name : "Alpha to coverage",
+    shadingModel : lit,
+    blending : masked,
+    alphaToCoverage : false
+}
+
+fragment {
+    void material(inout MaterialInputs material) {
+        prepareMaterial(material);
+        material.baseColor = materialParams.albedo;
+    }
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+### Lighting: reflections
+
+Type
+:    `string`
+
+Value
+:     `default` or `screenspace`. Defaults to `default`.
+
+Description
+:     Controls the source of specular reflections for this material. When this property is set to
+      `default`, reflections only come image-based lights. When this property is set to
+      `screenspace`, reflections come from the screen space's color buffer in addition to
+      image-based lights.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ JSON
+material {
+    name : "Glossy metal",
+    reflections : screenspace
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+### Lighting: shadowMultiplier
+
+Type
+:    `boolean`
+
+Value
+:     `true` or `false`. Defaults to `false`.
+
+Description
+:     Only available in the `unlit` shading model. If this property is enabled, the final color
+      computed by the material is multiplied by the shadowing factor (or visibility). This allows to
+      create transparent shadow-receiving objects (for instance an invisible ground plane in AR).
+      This is only supported with shadows from directional lights.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ JSON
+material {
+    name : "Invisible shadow plane",
+    shadingModel : unlit,
+    shadowMultiplier : true,
+    blending : transparent
+}
+
+fragment {
+    void material(inout MaterialInputs material) {
+        prepareMaterial(material);
+        // baseColor defines the color and opacity of the final shadow
+        material.baseColor = vec4(0.0, 0.0, 0.0, 0.7);
+    }
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+### Lighting: transparentShadow
+
+Type
+:    `boolean`
+
+Value
+:     `true` or `false`. Defaults to `false`.
+
+Description
+:     Enables transparent shadows on this material. When this feature is enabled, Filament emulates
+      transparent shadows using a dithering pattern: they work best with variance shadow maps (VSM)
+      and blurring enabled. The opacity of the shadow derives directly from the alpha channel of
+      the material's `baseColor` property. Transparent shadows can be enabled on opaque objects,
+      making them compatible with refractive/transmissive objects that are otherwise considered
+      opaque.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ JSON
+material {
+    name : "Clear plastic with stickers",
+    transparentShadow : true,
+    blending : transparent,
+    // ...
+}
+
+fragment {
+    void material(inout MaterialInputs material) {
+        prepareMaterial(material);
+        material.baseColor = texture(materialParams_baseColor, getUV0());
+    }
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+![Figure [transparentShadow]: Objects rendered with transparent shadows and blurry VSM with a
+radius of 4. Model [Bottle of Water](https://sketchfab.com/3d-models/bottle-of-water-48fd4f6e90d84d89b5740ee78587d0ff)
+by [T-Art](https://sketchfab.com/person-x).](images/screenshot_transparent_shadows.jpg)
+
+### Lighting: clearCoatIorChange
+
+Type
+:    `boolean`
+
+Value
+:     `true` or `false`. Defaults to `true`.
+
+Description
+:    When adding a clear coat layer, the change in index of refraction (IoR) is taken into account
+     to modify the specular color of the base layer. This appears to darken `baseColor`. When this
+     effect is disabled, `baseColor` is left unmodified. See figure [clearCoatIorChange] for an
+     example of how this property can affect a red metallic base layer.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ JSON
+material {
+    clearCoatIorChange : false
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+![Figure [clearCoatIorChange]: The same rough metallic ball with a clear coat layer rendered
+with `clearCoatIorChange` enabled (left) and disabled
+(right).](images/screenshot_clear_coat_ior_change.jpg)
+
+### Lighting: multiBounceAmbientOcclusion
+
+Type
+:    `boolean`
+
+Value
+:     `true` or `false`. Defaults to `false` on mobile, `true` on desktop.
+
+Description
+:    Multi-bounce ambient occlusion takes into account interreflections when applying ambient
+     occlusion to image-based lighting. Turning this feature on avoids over-darkening occluded
+     areas. It also takes the surface color into account to generate colored ambient occlusion.
+     Figure [multiBounceAO] compares the ambient occlusion term of a surface with and without
+     multi-bounce ambient occlusion. Notice how multi-bounce ambient occlusion introduces color
+     in the occluded areas. Figure [multiBounceAOAnimated] toggles between multi-bounce ambient
+     occlusion on and off on a lit brick material to highlight the effects of this property.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ JSON
+material {
+    multiBounceAmbientOcclusion : true
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+![Figure [multiBounceAO]: Brick texture amient occlusion map rendered with multi-bounce ambient
+occclusion enabled (left) and disabled (right).](images/screenshot_multi_bounce_ao.jpg)
+
+![Figure [multiBounceAOAnimated]: Brick texture rendered with multi-bounce ambient
+occclusion enabled and disabled.](images/screenshot_multi_bounce_ao.gif)
+
+### Lighting: specularAmbientOcclusion
+
+Type
+:    `string`
+
+Value
+:     `none`, `simple` or `bentNormals`. Defaults to `none` on mobile, `simple` on desktop. For
+      compatibility reasons, `true` and `false` are also accepted and map respectively to `simple`
+      and `none`.
+
+Description
+:    Static ambient occlusion maps and dynamic ambient occlusion (SSAO, etc.) apply to diffuse
+     indirect lighting. When setting this property to other than `none`, a new ambient occlusion
+     term is derived from the surface roughness and applied to specular indirect lighting.
+     This effect helps remove unwanted specular reflections as shown in figure [specularAO].
+     When this value is set to `simple`, Filament uses a cheap but approximate method of computing
+     the specular ambient occlusion term. If this value is set to `bentNormals`, Filament will use
+     a much more accurate but much more expensive method.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ JSON
+material {
+    specularAmbientOcclusion : simple
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+![Figure [specularAO]: Comparison of specular ambient occlusion on and off. The effect is
+particularly visible under the hose.](images/screenshot_specular_ao.gif)
+
+### Anti-aliasing: specularAntiAliasing
+
+Type
+:    `boolean`
+
+Value
+:     `true` or `false`. Defaults to `false`.
+
+Description
+:    Reduces specular aliasing and preserves the shape of specular highlights as an object moves
+     away from the camera. This anti-aliasing solution is particularly effective on glossy materials
+     (low roughness) but increases the cost of the material. The strength of the anti-aliasing
+     effect can be controlled using two other properties: `specularAntiAliasingVariance` and
+     `specularAntiAliasingThreshold`.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ JSON
+material {
+    specularAntiAliasing : true
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+### Anti-aliasing: specularAntiAliasingVariance
+
+Type
+:    `float`
+
+Value
+:     A value between 0 and 1, set to 0.15 by default.
+
+Description
+:    Sets the screen space variance of the filter kernel used when applying specular anti-aliasing.
+     Higher values will increase the effect of the filter but may increase roughness in unwanted
+     areas.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ JSON
+material {
+    specularAntiAliasingVariance : 0.2
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+### Anti-aliasing: specularAntiAliasingThreshold
+
+Type
+:    `float`
+
+Value
+:     A value between 0 and 1, set to 0.2 by default.
+
+Description
+:    Sets the clamping threshold used to suppress estimation errors when applying specular
+     anti-aliasing. When set to 0, specular anti-aliasing is disabled.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ JSON
+material {
+    specularAntiAliasingThreshold : 0.1
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+### Shading: customSurfaceShading
+
+Type
+:    `bool`
+
+Value
+:     `true` or `false`. Defaults to `false`.
+
+Description
+:    Enables custom surface shading when set to true. When surface shading is enabled, the fragment
+     shader must provide an extra function that will be invoked for every light in the scene that
+     may influence the current fragment. Please refer to the Custom surface shading section below
+     for more information.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ JSON
+material {
+    customSurfaceShading : true
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+## Vertex block
+
+The vertex block is optional and can be used to control the vertex shading stage of the material.
+The vertex block must contain valid
+[ESSL 3.0](https://www.khronos.org/registry/OpenGL/specs/es/3.0/GLSL_ES_Specification_3.00.pdf) code
+(the version of GLSL supported in OpenGL ES 3.0). You are free to create multiple functions inside
+the vertex block but you **must** declare the `materialVertex` function:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ GLSL
+vertex {
+    void materialVertex(inout MaterialVertexInputs material) {
+        // vertex shading code
+    }
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This function will be invoked automatically at runtime by the shading system and gives you the
+ability to read and modify material properties using the `MaterialVertexInputs` structure. This full
+definition of the structure can be found in the Material vertex inputs section.
+
+You can use this structure to compute your custom variables/interpolants or to modify the value of
+the attributes. For instance, the following vertex blocks modifies both the color and the UV
+coordinates of the vertex over time:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ GLSL
+material {
+    requires : [uv0, color]
+}
+vertex {
+    void materialVertex(inout MaterialVertexInputs material) {
+        material.color *= sin(getUserTime().x);
+        material.uv0 *= sin(getUserTime().x);
+    }
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In addition to the `MaterialVertexInputs` structure, your vertex shading code can use all the public
+APIs listed in the Shader public APIs section.
+
+### Material vertex inputs
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ GLSL
+struct MaterialVertexInputs {
+    float4 color;              // if the color attribute is required
+    float2 uv0;                // if the uv0 attribute is required
+    float2 uv1;                // if the uv1 attribute is required
+    float3 worldNormal;        // only if the shading model is not unlit
+    float4 worldPosition;      // always available (see note below about world-space)
+
+    mat4   clipSpaceTransform; // default: identity, transforms the clip-space position, only available for `vertexDomain:device`
+
+    // variable* names are replaced with actual names
+    float4 variable0;          // if 1 or more variables is defined
+    float4 variable1;          // if 2 or more variables is defined
+    float4 variable2;          // if 3 or more variables is defined
+    float4 variable3;          // if 4 or more variables is defined
+};
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+!!! TIP: worldPosition
+    To achieve good precision, the `worldPosition` coordinate in the vertex shader is shifted by the
+    camera position. To get the true world-space position, users can use
+    `getUserWorldPosition()`, however be aware that the true world-position might not
+    be able to fit in a `float` or might be represented with severely reduced precision.
+
+!!! TIP: UV attributes
+    By default the vertex shader of a material will flip the Y coordinate of the UV attributes
+    of the current mesh: `material.uv0 = vec2(mesh_uv0.x, 1.0 - mesh_uv0.y)`. You can control
+    this behavior using the `flipUV` property and setting it to `false`.
+
+### Custom vertex attributes
+
+You can use up to 8 custom vertex attributes, all of type `float4`. These attributes can be accessed
+using the vertex block shader functions `getCustom0()` to `getCustom7()`. However, before using
+custom attributes, you *must* declare those attributes as required in the `requires` property of
+the material:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ JSON
+material {
+    requires : [
+        custom0,
+        custom1,
+        custom2
+    ]
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+## Fragment block
+
+The fragment block must be used to control the fragment shading stage of the material. The fragment
+block must contain valid
+[ESSL 3.0](https://www.khronos.org/registry/OpenGL/specs/es/3.0/GLSL_ES_Specification_3.00.pdf)
+code (the version of GLSL supported in OpenGL ES 3.0). You are free to create multiple functions
+inside the fragment block but you **must** declare the `material` function:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ GLSL
+fragment {
+    void material(inout MaterialInputs material) {
+        prepareMaterial(material);
+        // fragment shading code
+    }
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This function will be invoked automatically at runtime by the shading system and gives you the
+ability to read and modify material properties using the `MaterialInputs` structure. This full
+definition of the structure can be found in the Material fragment inputs section. The full
+definition of the various members of the structure can be found in the Material models section
+of this document.
+
+The goal of the `material()` function is to compute the material properties specific to the selected
+shading model. For instance, here is a fragment block that creates a glossy red metal using the
+standard lit shading model:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ GLSL
+fragment {
+    void material(inout MaterialInputs material) {
+        prepareMaterial(material);
+        material.baseColor.rgb = vec3(1.0, 0.0, 0.0);
+        material.metallic = 1.0;
+        material.roughness = 0.0;
+    }
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+### prepareMaterial function
+
+Note that you **must** call `prepareMaterial(material)` before exiting the  `material()` function.
+This `prepareMaterial` function sets up the internal state of the material model. Some of the APIs
+described in the Fragment APIs section - like `shading_normal` for instance - can only be accessed
+_after_ invoking `prepareMaterial()`.
+
+It is also important to remember that the `normal` property - as described in the Material fragment
+inputs section - only has an effect when modified _before_ calling `prepareMaterial()`. Here is an
+example of a fragment shader that properly modifies the `normal` property to implement a glossy red
+plastic with bump mapping:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ GLSL
+fragment {
+    void material(inout MaterialInputs material) {
+        // fetch the normal in tangent space
+        vec3 normal = texture(materialParams_normalMap, getUV0()).xyz;
+        material.normal = normal * 2.0 - 1.0;
+
+        // prepare the material
+        prepareMaterial(material);
+
+        // from now on, shading_normal, etc. can be accessed
+        material.baseColor.rgb = vec3(1.0, 0.0, 0.0);
+        material.metallic = 0.0;
+        material.roughness = 1.0;
+    }
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+### Material fragment inputs
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ GLSL
+struct MaterialInputs {
+    float4 baseColor;           // default: float4(1.0)
+    float4 emissive;            // default: float4(0.0, 0.0, 0.0, 1.0)
+    float4 postLightingColor;   // default: float4(0.0)
+
+    // no other field is available with the unlit shading model
+    float  roughness;           // default: 1.0
+    float  metallic;            // default: 0.0, not available with cloth or specularGlossiness
+    float  reflectance;         // default: 0.5, not available with cloth or specularGlossiness
+    float  ambientOcclusion;    // default: 0.0
+
+    // not available when the shading model is subsurface or cloth
+    float3 sheenColor;          // default: float3(0.0)
+    float  sheenRoughness;      // default: 0.0
+    float  clearCoat;           // default: 1.0
+    float  clearCoatRoughness;  // default: 0.0
+    float3 clearCoatNormal;     // default: float3(0.0, 0.0, 1.0)
+    float  anisotropy;          // default: 0.0
+    float3 anisotropyDirection; // default: float3(1.0, 0.0, 0.0)
+
+    // only available when the shading model is subsurface or refraction is enabled
+    float  thickness;           // default: 0.5
+
+    // only available when the shading model is subsurface
+    float  subsurfacePower;     // default: 12.234
+    float3 subsurfaceColor;     // default: float3(1.0)
+
+    // only available when the shading model is cloth
+    float3 sheenColor;          // default: sqrt(baseColor)
+    float3 subsurfaceColor;     // default: float3(0.0)
+
+    // only available when the shading model is specularGlossiness
+    float3 specularColor;       // default: float3(0.0)
+    float  glossiness;          // default: 0.0
+
+    // not available when the shading model is unlit
+    // must be set before calling prepareMaterial()
+    float3 normal;              // default: float3(0.0, 0.0, 1.0)
+
+    // only available when refraction is enabled
+    float transmission;         // default: 1.0
+    float3 absorption;          // default float3(0.0, 0.0, 0.0)
+    float ior;                  // default: 1.5
+    float microThickness;       // default: 0.0, not available with refractionType "solid"
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+### Custom surface shading
+
+When `customSurfaceShading` is set to `true` in the material block, the fragment block **must**
+declare and implement the `surfaceShading` function:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ GLSL
+fragment {
+    void material(inout MaterialInputs material) {
+        prepareMaterial(material);
+        // prepare material inputs
+    }
+
+    vec3 surfaceShading(
+        const MaterialInputs materialInputs,
+        const ShadingData shadingData,
+        const LightData lightData
+    ) {
+        return vec3(1.0); // output of custom lighting
+    }
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This function will be invoked for every light (directional, spot or point) in the scene that may
+influence the current fragment. The `surfaceShading` is invoked with 3 sets of data:
+
+- `MaterialInputs`, as described in the Material fragment inputs section and prepared in the
+  `material` function explained above
+- `ShadingData`, a structure containing values derived from `MaterialInputs` (see below)
+- `LightData`, a structure containing values specific to the light being currently
+   evaluated (see below)
+
+The `surfaceShading` function must return an RGB color in linear sRGB. Alpha blending and alpha
+masking are handled outside of this function and must therefore be ignored.
+
+!!! Note: About shadowed fragments
+    The `surfaceShading` function is invoked even when a fragment is known to be fully in the shadow
+    of the current light (`lightData.NdotL <= 0.0` or `lightData.visibility <= 0.0`). This gives
+    more flexibility to the `surfaceShading` function as it provides a simple way to handle constant
+    ambient lighting for instance.
+
+!!! Warning: Shading models
+    Custom surface shading only works with the `lit` shading model. Attempting to use any other
+    model will result in an error.
+
+#### Shading data structure
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ GLSL
+struct ShadingData {
+    // The material's diffuse color, as derived from baseColor and metallic.
+    // This color is pre-multiplied by alpha and in the linear sRGB color space.
+    vec3  diffuseColor;
+
+    // The material's specular color, as derived from baseColor and metallic.
+    // This color is pre-multiplied by alpha and in the linear sRGB color space.
+    vec3  f0;
+
+    // The perceptual roughness is the roughness value set in MaterialInputs,
+    // with extra processing:
+    // - Clamped to safe values
+    // - Filtered if specularAntiAliasing is enabled
+    // This value is between 0.0 and 1.0.
+    float perceptualRoughness;
+
+    // The roughness value expected by BRDFs. This value is the square of
+    // perceptualRoughness. This value is between 0.0 and 1.0.
+    float roughness;
+};
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+#### Light data structure
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ GLSL
+struct LightData {
+    // The color (.rgb) and pre-exposed intensity (.w) of the light.
+    // The color is an RGB value in the linear sRGB color space.
+    // The pre-exposed intensity is the intensity of the light multiplied by
+    // the camera's exposure value.
+    vec4  colorIntensity;
+
+    // The normalized light vector, in world space (direction from the
+    // current fragment's position to the light).
+    vec3  l;
+
+    // The dot product of the shading normal (with normal mapping applied)
+    // and the light vector. This value is equal to the result of
+    // saturate(dot(getWorldSpaceNormal(), lightData.l)).
+    // This value is always between 0.0 and 1.0. When the value is <= 0.0,
+    // the current fragment is not visible from the light and lighting
+    // computations can be skipped.
+    float NdotL;
+
+    // The position of the light in world space.
+    vec3  worldPosition;
+
+    // Attenuation of the light based on the distance from the current
+    // fragment to the light in world space. This value between 0.0 and 1.0
+    // is computed differently for each type of light (it's always 1.0 for
+    // directional lights).
+    float attenuation;
+
+    // Visibility factor computed from shadow maps or other occlusion data
+    // specific to the light being evaluated. This value is between 0.0 and
+    // 1.0.
+    float visibility;
+};
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+#### Example
+
+The material below shows how to use custom surface shading to implement a simplified toon shader:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+material {
+    name : Toon,
+    shadingModel : lit,
+    parameters : [
+        {
+            type : float3,
+            name : baseColor
+        }
+    ],
+    customSurfaceShading : true
+}
+
+fragment {
+    void material(inout MaterialInputs material) {
+        prepareMaterial(material);
+        material.baseColor.rgb = materialParams.baseColor;
+    }
+
+    vec3 surfaceShading(
+            const MaterialInputs materialInputs,
+            const ShadingData shadingData,
+            const LightData lightData
+    ) {
+        // Number of visible shade transitions
+        const float shades = 5.0;
+        // Ambient intensity
+        const float ambient = 0.1;
+
+        float toon = max(ceil(lightData.NdotL * shades) / shades, ambient);
+
+        // Shadowing and attenuation
+        toon *= lightData.visibility * lightData.attenuation;
+
+        // Color and intensity
+        vec3 light = lightData.colorIntensity.rgb * lightData.colorIntensity.w;
+
+        return shadingData.diffuseColor * light * toon;
+    }
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The result can be seen in figure [toonShading].
+
+![Figure [toonShading]: simple toon shading implemented with custom
+surface shading](images/screenshot_toon_shading.png)
+
+
+## Shader public APIs
+
+### Types
+
+While GLSL types can be used directly (`vec4` or `mat4`) we recommend the use of the following
+type aliases:
+
+               Name              |   GLSL type  |            Description
+:--------------------------------|:------------:|:------------------------------------
+**bool2**                        | bvec2        |  A vector of 2 booleans
+**bool3**                        | bvec3        |  A vector of 3 booleans
+**bool4**                        | bvec4        |  A vector of 4 booleans
+**int2**                         | ivec2        |  A vector of 2 integers
+**int3**                         | ivec3        |  A vector of 3 integers
+**int4**                         | ivec4        |  A vector of 4 integers
+**uint2**                        | uvec2        |  A vector of 2 unsigned integers
+**uint3**                        | uvec3        |  A vector of 3 unsigned integers
+**uint4**                        | uvec4        |  A vector of 4 unsigned integers
+**float2**                       | float2       |  A vector of 2 floats
+**float3**                       | float3       |  A vector of 3 floats
+**float4**                       | float4       |  A vector of 4 floats
+**float4x4**                     | mat4         |  A 4x4 float matrix
+**float3x3**                     | mat3         |  A 3x3 float matrix
+
+### Math
+                   Name                   |   Type   |            Description
+:-----------------------------------------|:--------:|:------------------------------------
+**PI**                                    | float    |  A constant that represent $\pi$
+**HALF_PI**                               | float    |  A constant that represent $\frac{\pi}{2}$
+**saturate(float x)**                     | float    |  Clamps the specified value between 0.0 and 1.0
+**pow5(float x)**                         | float    |  Computes $x^5$
+**sq(float x)**                           | float    |  Computes $x^2$
+**max3(float3 v)**                        | float    |  Returns the maximum value of the specified `float3`
+**mulMat4x4Float3(float4x4 m, float3 v)** | float4   |  Returns $m * v$
+**mulMat3x3Float3(float4x4 m, float3 v)** | float4   |  Returns $m * v$
+
+### Matrices
+
+                 Name               |   Type   |            Description
+:-----------------------------------|:--------:|:------------------------------------
+**getViewFromWorldMatrix()**        | float4x4 |  Matrix that converts from world space to view/eye space
+**getWorldFromViewMatrix()**        | float4x4 |  Matrix that converts from view/eye space to world space
+**getClipFromViewMatrix()**         | float4x4 |  Matrix that converts from view/eye space to clip (NDC) space
+**getViewFromClipMatrix()**         | float4x4 |  Matrix that converts from clip (NDC) space to view/eye space
+**getClipFromWorldMatrix()**        | float4x4 |  Matrix that converts from world to clip (NDC) space
+**getWorldFromClipMatrix()**        | float4x4 |  Matrix that converts from clip (NDC) space to world space
+
+### Frame constants
+
+                 Name               |   Type   |            Description
+:-----------------------------------|:--------:|:------------------------------------
+**getResolution()**                 | float4   |  Dimensions of the view's effective (physical) viewport in pixels: `width`, `height`, `1 / width`, `1 / height`. This might be different from `View::getViewport()` for instance because of added rendering guard-bands.
+**getWorldCameraPosition()**        | float3   |  Position of the camera/eye in world space (see note below)
+**getWorldOffset()**                | float3   |  [deprecated] The shift required to obtain API-level world space. Use getUserWorldPosition() instead
+**getUserWorldFromWorldMatrix()**   | float4x4 |  Matrix that converts from world space to API-level (user) world space.
+**getTime()**                       | float    |  Current time as a remainder of 1 second. Yields a value between 0 and 1
+**getUserTime()**                   | float4   |  Current time in seconds: `time`, `(double)time - time`, `0`, `0`
+**getUserTimeMod(float m)**         | float    |  Current time modulo m in seconds
+**getExposure()**                   | float    |  Photometric exposure of the camera
+**getEV100()**                      | float    |  [Exposure value at ISO 100](https://en.wikipedia.org/wiki/Exposure_value) of the camera
+
+!!! TIP: world space
+    To achieve good precision, the "world space" in Filament's shading system does not necessarily
+    match the API-level world space. To obtain the position of the API-level camera, custom
+    materials can use `getUserWorldFromWorldMatrix()` to transform `getWorldCameraPosition()`.
+
+### Material globals
+
+                 Name               |   Type   |            Description
+:-----------------------------------|:--------:|:------------------------------------
+**getMaterialGlobal0()**            | float4   | A vec4 visible by all materials, its value is set by `View::setMaterialGlobal(0, float4)`. Its default value is {0,0,0,1}.
+**getMaterialGlobal1()**            | float4   | A vec4 visible by all materials, its value is set by `View::setMaterialGlobal(1, float4)`. Its default value is {0,0,0,1}.
+**getMaterialGlobal2()**            | float4   | A vec4 visible by all materials, its value is set by `View::setMaterialGlobal(2, float4)`. Its default value is {0,0,0,1}.
+**getMaterialGlobal3()**            | float4   | A vec4 visible by all materials, its value is set by `View::setMaterialGlobal(3, float4)`. Its default value is {0,0,0,1}.
+
+### Vertex only
+
+The following APIs are only available from the vertex block:
+
+                 Name                |   Type   |            Description
+:------------------------------------|:--------:|:------------------------------------
+**getPosition()**                    | float4   |  Vertex position in the domain defined by the material (default: object/model space)
+**getCustom0()** to **getCustom7()** | float4   |  Custom vertex attribute
+**getWorldFromModelMatrix()**        | float4x4 |  Matrix that converts from model (object) space to world space
+**getWorldFromModelNormalMatrix()**  | float3x3 |  Matrix that converts normals from model (object) space to world space
+**getVertexIndex()**                 | int      |  Index of the current vertex
+**getEyeIndex()**                    | int      |  Index of the eye being rendered, starting at 0
+
+### Fragment only
+
+The following APIs are only available from the fragment block:
+
+                 Name                   |   Type   |            Description
+:---------------------------------------|:--------:|:------------------------------------
+**getWorldTangentFrame()**              | float3x3 |  Matrix containing in each column the `tangent` (`frame[0]`), `bi-tangent` (`frame[1]`) and `normal` (`frame[2]`) 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 `normal` is valid in this matrix.
+**getWorldPosition()**                  | float3   |  Position of the fragment in world space (see note below about world-space)
+**getUserWorldPosition()**              | float3   |  Position of the fragment in API-level (user) world-space (see note below about world-space)
+**getWorldViewVector()**                | float3   |  Normalized vector in world space from the fragment position to the eye
+**getWorldNormalVector()**              | float3   |  Normalized normal in world space, after bump mapping (must be used after `prepareMaterial()`)
+**getWorldGeometricNormalVector()**     | float3   |  Normalized normal in world space, before bump mapping (can be used before `prepareMaterial()`)
+**getWorldReflectedVector()**           | float3   |  Reflection of the view vector about the normal (must be used after `prepareMaterial()`)
+**getNormalizedViewportCoord()**        | float3   |  Normalized user viewport position (i.e. NDC coordinates normalized to [0, 1] for the position, [1, 0] for the depth), can be used before `prepareMaterial()`). 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.
+**getNdotV()**                          | float    |  The result of `dot(normal, view)`, always strictly greater than 0 (must be used after `prepareMaterial()`)
+**getColor()**                          | float4   |  Interpolated color of the fragment, if the color attribute is required
+**getUV0()**                            | float2   |  First interpolated set of UV coordinates, only available if the uv0 attribute is required
+**getUV1()**                            | float2   |  First interpolated set of UV coordinates, only available if the uv1 attribute is required
+**getMaskThreshold()**                  | float    |  Returns the mask threshold, only available when `blending` is set to `masked`
+**inverseTonemap(float3)**              | float3   |  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
+**inverseTonemapSRGB(float3)**          | float3   |  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
+**luminance(float3)**                   | float    |  Computes the luminance of the specified linear sRGB color
+**ycbcrToRgb(float, float2)**           | float3   |  Converts a luminance and CbCr pair to a sRGB color
+**uvToRenderTargetUV(float2)**          | float2   |  Transforms a UV coordinate to allow sampling from a `RenderTarget` attachment
+
+!!! TIP: world-space
+    To obtain API-level world-space coordinates, custom materials should use `getUserWorldPosition()`
+    or use `getUserWorldFromWorldMatrix()`. Note that API-level world-space coordinates should
+    never or rarely be used because they may not fit in a float3 or have severely reduced precision.
+
+!!! TIP: sampling from render targets
+    When sampling from a `filament::Texture` that is attached to a `filament::RenderTarget` for
+    materials in the surface domain, please use `uvToRenderTargetUV` to transform the texture
+    coordinate. This will flip the coordinate depending on which backend is being used.
+
+# Compiling materials
+
+Material packages can be compiled from material definitions using the command line tool called
+`matc`. The simplest way to use `matc` is to specify an input material definition (`car_paint.mat`
+in the example below) and an output material package (`car_paint.filamat` in the example below):
+
+```text
+$ matc -o ./materials/bin/car_paint.filamat ./materials/src/car_paint.mat
+```
+
+## Shader validation
+
+`matc` attempts to validate shaders when compiling a material package. The example below shows an
+example of an error message generated when compiling a material definition containing a typo in the
+fragment shader (`metalic` instead of `metallic`). The reported line numbers are line numbers in the
+source material definition file.
+
+```text
+ERROR: 0:13: 'metalic' : no such field in structure
+ERROR: 0:13: '' : compilation terminated
+ERROR: 2 compilation errors.  No code generated.
+
+Could not compile material metal.mat
+```
+
+## Flags
+
+The command line flags relevant to application development are described in table [matcFlags].
+
+              Flag              |        Value       |        Usage
+-------------------------------:|:------------------:|:---------------------
+**-o**, **--output**            | [path]             | Specify the output file path
+**-p**, **--platform**          | desktop/mobile/all | Select the target platform(s)
+**-a**, **--api**               | opengl/vulkan/all  | Specify the target graphics API
+**-S**, **--optimize-size**     | N/A                | Optimize compiled material for size instead of just performance
+**-r**, **--reflect**           | parameters         | Outputs the specified metadata as JSON
+**-v**, **--variant-filter**    | [variant]          | Filters out the specified, comma-separated variants
+[Table [matcFlags]: List of `matc` flags]
+
+`matc` offers a few other flags that are irrelevant to application developers and for internal
+use only.
+
+### --platform
+
+By default, `matc` generates material packages containing shaders for all supported platforms. If
+you wish to reduce the size of your material packages, it is recommended to select only the
+appropriate target platform. For instance, to compile a material package for Android only, run
+the following command:
+
+```text
+$ matc -p mobile -o ./materials/bin/car_paint.filamat ./materials/src/car_paint.mat
+```
+
+### --api
+
+By default, `matc` generates material packages containing shaders for the OpenGL API. You can choose
+to generate shaders for the Vulkan API in addition to the OpenGL shaders. If you intend on targeting
+only Vulkan capable devices, you can reduce the size of the material packages by generating only
+the set of Vulkan shaders:
+
+```text
+$ matc -a vulkan -o ./materials/bin/car_paint.filamat ./materials/src/car_paint.mat
+```
+
+### --optimize-size
+
+This flag applies fewer optimization techniques to try and keep the final material as small as
+possible. If the compiled material is deemed too large by default, using this flag might be
+a good compromise between runtime performance and size.
+
+### --reflect
+
+This flag was designed to help build tools around `matc`. It allows you to print out specific
+metadata in JSON format. The example below prints out the list of parameters defined in Filament's
+standard skybox material. It produces a list of 2 parameters, named `showSun` and `skybox`,
+respectively a boolean and a cubemap texture.
+
+```text
+$ matc --reflect parameters filament/src/materials/skybox.mat 
+{
+  "parameters": [
+    {
+      "name": "showSun",
+      "type": "bool",
+      "size": "1"
+    },
+    {
+      "name": "skybox",
+      "type": "samplerCubemap",
+      "format": "float",
+      "precision": "default"
+    }
+  ]
+}
+``` 
+
+### --variant-filter
+
+This flag can be used to further reduce the size of a compiled material. It is used to specify a
+list of shader variants that the application guarantees will never be needed. These shader variants
+are skipped during the code generation phase of `matc`, thus reducing the overall size of the
+material.
+
+The variants must be specified as a comma-separated list, using one of the following available
+variants:
+
+- `directionalLighting`, used when a directional light is present in the scene
+- `dynamicLighting`, used when a non-directional light (point, spot, etc.) is present in the scene
+- `shadowReceiver`, used when an object can receive shadows
+- `skinning`, used when an object is animated using GPU skinning or vertex morphing
+- `fog`, used when global fog is applied to the scene
+- `vsm`, used when VSM shadows are enabled and the object is a shadow receiver
+- `ssr`, used when screen-space reflections are enabled in the View
+
+Example:
+```
+--variant-filter=skinning,shadowReceiver
+```
+
+Note that some variants may automatically be filtered out. For instance, all lighting related
+variants (`directionalLighting`, etc.) are filtered out when compiling an `unlit` material.
+
+When this flag is used, the specified variant filters are merged with the variant filters specified
+in the material itself.
+
+Use this flag with caution, filtering out a variant required at runtime may lead to crashes.
+
+# Handling colors
+
+## Linear colors
+
+If the color data comes from a texture, simply make sure you use an sRGB texture to benefit from
+automatic hardware conversion from sRGB to linear. If the color data is passed as a parameter to
+the material you can convert from sRGB to linear by running the following algorithm on each
+color channel:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ GLSL
+float sRGB_to_linear(float color) {
+	return color <= 0.04045 ? color / 12.92 : pow((color + 0.055) / 1.055, 2.4);
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Alternatively you can use one of the two cheaper but less accurate versions shown below:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ GLSL
+// Cheaper
+linearColor = pow(color, 2.2);
+// Cheapest
+linearColor = color * color;
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+## Pre-multiplied alpha
+
+A color uses pre-multiplied alpha if its RGB components are multiplied by the alpha channel:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ GLSL
+// Compute pre-multiplied color
+color.rgb *= color.a;
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If the color is sampled from a texture, you can simply ensure that the texture data is
+pre-multiplied ahead of time. On Android, any texture uploaded from a
+[Bitmap](https://developer.android.com/reference/android/graphics/Bitmap.html) will be
+pre-multiplied by default.
+
+# Sampler usage in Materials
+
+The number of usable sampler parameters (e.g.: type is `sampler2d`) in materials is limited and
+depends on the material properties, shading model, feature level and variant filter.
+
+## Feature level 1 and 2
+
+`unlit` materials can use up to 12 samplers by default.
+
+`lit` materials can use up to 9 samplers by default, however if `refractionMode` or `reflectionMode`
+is set to `screenspace` that number is reduced to 8.
+
+Finally if `variantFilter` contains the `fog` filter, an extra sampler is made available, such that
+`unlit` materials can use up to 13 and `lit` materials up to 10 samplers by default.
+
+## Feature level 3
+
+16 samplers are available.
+
+!!! TIP: external samplers
+               Be aware that `external` samplers account for 2 regular samplers.
+
+<!-- Markdeep: --><style class="fallback">body{visibility:hidden;white-space:pre;font-family:monospace}</style><script src="../third_party/markdeep/markdeep.min.js"></script><script src="https://casual-effects.com/markdeep/latest/markdeep.min.js"></script><script>window.alreadyProcessedMarkdeep||(document.body.style.visibility="visible")</script>
diff --git a/docs_src/markdeep/README.md b/docs_src/markdeep/README.md
new file mode 100644
index 00000000000..35c30efa842
--- /dev/null
+++ b/docs_src/markdeep/README.md
@@ -0,0 +1,10 @@
+# Markdeep documents
+
+Markdeep documents require special processing before they can be compiled into the group.
+The "original" are stored in this folder. The processing part takes place in
+`docs_src/build/run.py`.
+
+## Editing
+While editing the file, you might consider doing the following
+ - `python3 -m http.server 8001`
+ - visit `http://localhost:8001/Filament.md.html` in the browser to view the result
\ No newline at end of file
diff --git a/docs_src/src/SUMMARY.md b/docs_src/src/SUMMARY.md
new file mode 100644
index 00000000000..7b756517f41
--- /dev/null
+++ b/docs_src/src/SUMMARY.md
@@ -0,0 +1,39 @@
+# Summary
+
+- [Introduction](./dup/intro.md)
+  - [Build](./dup/building.md)
+    - [Build for Android on Windows](./build/windows_android.md)
+  - [Contribute](./dup/contributing.md)
+  - [Coding Style](./dup/code_style.md)
+- [Core Concepts](./main/README.md)
+  - [Filament](./main/filament.md)
+  - [Materials](./main/materials.md)
+- [Tutorials and Samples](./samples/README.md)
+  - [iOS Tutorial](./samples/ios.md)
+  - [Web Tutorial](./samples/web.md)
+- [Technical Notes](./notes/README.md)
+  - [Versioning](./notes/versioning.md)
+  - [Documentation](./dup/docs.md)
+  - [Debugging](./notes/debugging.md)
+    - [Metal](./notes/metal_debugging.md)
+    - [Vulkan](./notes/vulkan_debugging.md)
+    - [SPIR-V](./notes/spirv_debugging.md)
+  - [Libraries](./notes/libs.md)
+    - [bluegl](./dup/bluegl.md)
+    - [bluevk](./dup/bluevk.md)
+    - [filamat](./dup/filamat.md)
+    - [gltfio](./dup/gltfio.md)
+    - [iblprefilter](./dup/iblprefilter.md)
+    - [matdbg](./dup/matdbg.md)
+    - [uberz](./dup/uberz.md)
+  - [Tools](./notes/tools.md)
+    - [beamsplitter](./dup/beamsplitter.md)
+    - [cmgen](./dup/cmgen.md)
+    - [cso-lut](./dup/cso_lut.md)
+    - [filamesh](./dup/filamesh.md)
+    - [normal-blending](./dup/normal_blending.md)
+    - [mipgen](./dup/mipgen.md)
+    - [matinfo](./dup/matinfo.md)
+    - [roughness-prefilter](./dup/roughness_prefilter.md)
+    - [specular-color](./dup/specular_color.md)
+    - [zbloat](./dup/zbloat.md)
diff --git a/android/Windows.md b/docs_src/src/build/windows_android.md
similarity index 100%
rename from android/Windows.md
rename to docs_src/src/build/windows_android.md
diff --git a/docs_src/src/dup/README.txt b/docs_src/src/dup/README.txt
new file mode 100644
index 00000000000..554222e3098
--- /dev/null
+++ b/docs_src/src/dup/README.txt
@@ -0,0 +1,2 @@
+Do not manually edit any file in this folder. They have been autogenerated
+by a script.
diff --git a/docs_src/src/images/chart_sh_cos_thera_approx.png b/docs_src/src/images/chart_sh_cos_thera_approx.png
new file mode 100644
index 00000000000..c3bb69c0158
Binary files /dev/null and b/docs_src/src/images/chart_sh_cos_thera_approx.png differ
diff --git a/docs_src/src/images/diagram_brdf_dielectric_conductor.png b/docs_src/src/images/diagram_brdf_dielectric_conductor.png
new file mode 100644
index 00000000000..ec45e9ca996
Binary files /dev/null and b/docs_src/src/images/diagram_brdf_dielectric_conductor.png differ
diff --git a/docs_src/src/images/diagram_clear_coat.png b/docs_src/src/images/diagram_clear_coat.png
new file mode 100644
index 00000000000..fc1c1505a66
Binary files /dev/null and b/docs_src/src/images/diagram_clear_coat.png differ
diff --git a/docs_src/src/images/diagram_color_temperature_cct.png b/docs_src/src/images/diagram_color_temperature_cct.png
new file mode 100644
index 00000000000..e8f936bdef7
Binary files /dev/null and b/docs_src/src/images/diagram_color_temperature_cct.png differ
diff --git a/docs_src/src/images/diagram_color_temperature_cct_clamped.png b/docs_src/src/images/diagram_color_temperature_cct_clamped.png
new file mode 100644
index 00000000000..a2a1ec7b9ed
Binary files /dev/null and b/docs_src/src/images/diagram_color_temperature_cct_clamped.png differ
diff --git a/docs_src/src/images/diagram_color_temperature_cie.png b/docs_src/src/images/diagram_color_temperature_cie.png
new file mode 100644
index 00000000000..d661f7b38ef
Binary files /dev/null and b/docs_src/src/images/diagram_color_temperature_cie.png differ
diff --git a/docs_src/src/images/diagram_directional_light.png b/docs_src/src/images/diagram_directional_light.png
new file mode 100644
index 00000000000..175772c2830
Binary files /dev/null and b/docs_src/src/images/diagram_directional_light.png differ
diff --git a/docs_src/src/images/diagram_fr_fd.png b/docs_src/src/images/diagram_fr_fd.png
new file mode 100644
index 00000000000..5794760e5ba
Binary files /dev/null and b/docs_src/src/images/diagram_fr_fd.png differ
diff --git a/docs_src/src/images/diagram_froxels1.png b/docs_src/src/images/diagram_froxels1.png
new file mode 100644
index 00000000000..33486477bb2
Binary files /dev/null and b/docs_src/src/images/diagram_froxels1.png differ
diff --git a/docs_src/src/images/diagram_froxels2.png b/docs_src/src/images/diagram_froxels2.png
new file mode 100644
index 00000000000..7f7bccf5d7f
Binary files /dev/null and b/docs_src/src/images/diagram_froxels2.png differ
diff --git a/docs_src/src/images/diagram_froxels3.png b/docs_src/src/images/diagram_froxels3.png
new file mode 100644
index 00000000000..695a89a3b2c
Binary files /dev/null and b/docs_src/src/images/diagram_froxels3.png differ
diff --git a/docs_src/src/images/diagram_lambert_vs_disney.png b/docs_src/src/images/diagram_lambert_vs_disney.png
new file mode 100644
index 00000000000..2cef9ab17dc
Binary files /dev/null and b/docs_src/src/images/diagram_lambert_vs_disney.png differ
diff --git a/docs_src/src/images/diagram_macrosurface.png b/docs_src/src/images/diagram_macrosurface.png
new file mode 100644
index 00000000000..1d39160c46a
Binary files /dev/null and b/docs_src/src/images/diagram_macrosurface.png differ
diff --git a/docs_src/src/images/diagram_micro_vs_macro.png b/docs_src/src/images/diagram_micro_vs_macro.png
new file mode 100644
index 00000000000..13a96296841
Binary files /dev/null and b/docs_src/src/images/diagram_micro_vs_macro.png differ
diff --git a/docs_src/src/images/diagram_microfacet.png b/docs_src/src/images/diagram_microfacet.png
new file mode 100644
index 00000000000..2311e42981e
Binary files /dev/null and b/docs_src/src/images/diagram_microfacet.png differ
diff --git a/docs_src/src/images/diagram_planckian_locus.png b/docs_src/src/images/diagram_planckian_locus.png
new file mode 100644
index 00000000000..bea8ae6c226
Binary files /dev/null and b/docs_src/src/images/diagram_planckian_locus.png differ
diff --git a/docs_src/src/images/diagram_point_light.png b/docs_src/src/images/diagram_point_light.png
new file mode 100644
index 00000000000..44ca40189ff
Binary files /dev/null and b/docs_src/src/images/diagram_point_light.png differ
diff --git a/docs_src/src/images/diagram_reflectance.png b/docs_src/src/images/diagram_reflectance.png
new file mode 100644
index 00000000000..ca4cf781ba9
Binary files /dev/null and b/docs_src/src/images/diagram_reflectance.png differ
diff --git a/docs_src/src/images/diagram_roughness.png b/docs_src/src/images/diagram_roughness.png
new file mode 100644
index 00000000000..a428bff9175
Binary files /dev/null and b/docs_src/src/images/diagram_roughness.png differ
diff --git a/docs_src/src/images/diagram_scattering.png b/docs_src/src/images/diagram_scattering.png
new file mode 100644
index 00000000000..d8dbd0c966c
Binary files /dev/null and b/docs_src/src/images/diagram_scattering.png differ
diff --git a/docs_src/src/images/diagram_shadowing_masking.png b/docs_src/src/images/diagram_shadowing_masking.png
new file mode 100644
index 00000000000..78b37d71187
Binary files /dev/null and b/docs_src/src/images/diagram_shadowing_masking.png differ
diff --git a/docs_src/src/images/diagram_single_vs_multi_scatter.png b/docs_src/src/images/diagram_single_vs_multi_scatter.png
new file mode 100644
index 00000000000..81bfeb5c938
Binary files /dev/null and b/docs_src/src/images/diagram_single_vs_multi_scatter.png differ
diff --git a/docs_src/src/images/diagram_spot_light.png b/docs_src/src/images/diagram_spot_light.png
new file mode 100644
index 00000000000..7aa74421d61
Binary files /dev/null and b/docs_src/src/images/diagram_spot_light.png differ
diff --git a/docs_src/src/images/filament_logo.png b/docs_src/src/images/filament_logo.png
new file mode 100644
index 00000000000..58aacf78ad3
Binary files /dev/null and b/docs_src/src/images/filament_logo.png differ
diff --git a/docs_src/src/images/filament_logo_small.png b/docs_src/src/images/filament_logo_small.png
new file mode 100644
index 00000000000..710976c5160
Binary files /dev/null and b/docs_src/src/images/filament_logo_small.png differ
diff --git a/docs_src/src/images/ibl/dfg.png b/docs_src/src/images/ibl/dfg.png
new file mode 100644
index 00000000000..7d1f48aa214
Binary files /dev/null and b/docs_src/src/images/ibl/dfg.png differ
diff --git a/docs_src/src/images/ibl/dfg1.png b/docs_src/src/images/ibl/dfg1.png
new file mode 100644
index 00000000000..599b0ced0b9
Binary files /dev/null and b/docs_src/src/images/ibl/dfg1.png differ
diff --git a/docs_src/src/images/ibl/dfg1_approx.png b/docs_src/src/images/ibl/dfg1_approx.png
new file mode 100644
index 00000000000..59855e199e8
Binary files /dev/null and b/docs_src/src/images/ibl/dfg1_approx.png differ
diff --git a/docs_src/src/images/ibl/dfg2.png b/docs_src/src/images/ibl/dfg2.png
new file mode 100644
index 00000000000..2702a94233a
Binary files /dev/null and b/docs_src/src/images/ibl/dfg2.png differ
diff --git a/docs_src/src/images/ibl/dfg2_approx.png b/docs_src/src/images/ibl/dfg2_approx.png
new file mode 100644
index 00000000000..64848da0c1c
Binary files /dev/null and b/docs_src/src/images/ibl/dfg2_approx.png differ
diff --git a/docs_src/src/images/ibl/dfg_approx.png b/docs_src/src/images/ibl/dfg_approx.png
new file mode 100644
index 00000000000..d3f17555c97
Binary files /dev/null and b/docs_src/src/images/ibl/dfg_approx.png differ
diff --git a/docs_src/src/images/ibl/dfg_cloth.png b/docs_src/src/images/ibl/dfg_cloth.png
new file mode 100644
index 00000000000..1a05807775f
Binary files /dev/null and b/docs_src/src/images/ibl/dfg_cloth.png differ
diff --git a/docs_src/src/images/ibl/ibl_irradiance.png b/docs_src/src/images/ibl/ibl_irradiance.png
new file mode 100644
index 00000000000..3718d42077c
Binary files /dev/null and b/docs_src/src/images/ibl/ibl_irradiance.png differ
diff --git a/docs_src/src/images/ibl/ibl_irradiance_sh2.png b/docs_src/src/images/ibl/ibl_irradiance_sh2.png
new file mode 100644
index 00000000000..8ec7bc15e22
Binary files /dev/null and b/docs_src/src/images/ibl/ibl_irradiance_sh2.png differ
diff --git a/docs_src/src/images/ibl/ibl_irradiance_sh3.png b/docs_src/src/images/ibl/ibl_irradiance_sh3.png
new file mode 100644
index 00000000000..703a60aaddb
Binary files /dev/null and b/docs_src/src/images/ibl/ibl_irradiance_sh3.png differ
diff --git a/docs_src/src/images/ibl/ibl_no_mipmaping.png b/docs_src/src/images/ibl/ibl_no_mipmaping.png
new file mode 100644
index 00000000000..e9f43777a2a
Binary files /dev/null and b/docs_src/src/images/ibl/ibl_no_mipmaping.png differ
diff --git a/docs_src/src/images/ibl/ibl_prefilter_vs_reference.png b/docs_src/src/images/ibl/ibl_prefilter_vs_reference.png
new file mode 100644
index 00000000000..87d7e03d7ba
Binary files /dev/null and b/docs_src/src/images/ibl/ibl_prefilter_vs_reference.png differ
diff --git a/docs_src/src/images/ibl/ibl_river_roughness_m0.png b/docs_src/src/images/ibl/ibl_river_roughness_m0.png
new file mode 100644
index 00000000000..f029919a458
Binary files /dev/null and b/docs_src/src/images/ibl/ibl_river_roughness_m0.png differ
diff --git a/docs_src/src/images/ibl/ibl_river_roughness_m1.png b/docs_src/src/images/ibl/ibl_river_roughness_m1.png
new file mode 100644
index 00000000000..c0156e8a880
Binary files /dev/null and b/docs_src/src/images/ibl/ibl_river_roughness_m1.png differ
diff --git a/docs_src/src/images/ibl/ibl_river_roughness_m2.png b/docs_src/src/images/ibl/ibl_river_roughness_m2.png
new file mode 100644
index 00000000000..0efd9f579f7
Binary files /dev/null and b/docs_src/src/images/ibl/ibl_river_roughness_m2.png differ
diff --git a/docs_src/src/images/ibl/ibl_river_roughness_m3.png b/docs_src/src/images/ibl/ibl_river_roughness_m3.png
new file mode 100644
index 00000000000..f1b42a63cde
Binary files /dev/null and b/docs_src/src/images/ibl/ibl_river_roughness_m3.png differ
diff --git a/docs_src/src/images/ibl/ibl_river_roughness_m4.png b/docs_src/src/images/ibl/ibl_river_roughness_m4.png
new file mode 100644
index 00000000000..04129140137
Binary files /dev/null and b/docs_src/src/images/ibl/ibl_river_roughness_m4.png differ
diff --git a/docs_src/src/images/ibl/ibl_river_roughness_m5.png b/docs_src/src/images/ibl/ibl_river_roughness_m5.png
new file mode 100644
index 00000000000..57c75c8b088
Binary files /dev/null and b/docs_src/src/images/ibl/ibl_river_roughness_m5.png differ
diff --git a/docs_src/src/images/ibl/ibl_river_roughness_m6.png b/docs_src/src/images/ibl/ibl_river_roughness_m6.png
new file mode 100644
index 00000000000..0a4d29f5976
Binary files /dev/null and b/docs_src/src/images/ibl/ibl_river_roughness_m6.png differ
diff --git a/docs_src/src/images/ibl/ibl_river_roughness_m7.png b/docs_src/src/images/ibl/ibl_river_roughness_m7.png
new file mode 100644
index 00000000000..d3b71237120
Binary files /dev/null and b/docs_src/src/images/ibl/ibl_river_roughness_m7.png differ
diff --git a/docs_src/src/images/ibl/ibl_stretchy_reflections_error.png b/docs_src/src/images/ibl/ibl_stretchy_reflections_error.png
new file mode 100644
index 00000000000..c8e2bb39489
Binary files /dev/null and b/docs_src/src/images/ibl/ibl_stretchy_reflections_error.png differ
diff --git a/docs_src/src/images/ibl/ibl_trilinear_0.png b/docs_src/src/images/ibl/ibl_trilinear_0.png
new file mode 100644
index 00000000000..39ca22e840e
Binary files /dev/null and b/docs_src/src/images/ibl/ibl_trilinear_0.png differ
diff --git a/docs_src/src/images/ibl/ibl_trilinear_1.png b/docs_src/src/images/ibl/ibl_trilinear_1.png
new file mode 100644
index 00000000000..5ce39b0c310
Binary files /dev/null and b/docs_src/src/images/ibl/ibl_trilinear_1.png differ
diff --git a/docs_src/src/images/ibl/ibl_visualization.jpg b/docs_src/src/images/ibl/ibl_visualization.jpg
new file mode 100644
index 00000000000..7fe141a3cd0
Binary files /dev/null and b/docs_src/src/images/ibl/ibl_visualization.jpg differ
diff --git a/docs_src/src/images/image_filtered_1.png b/docs_src/src/images/image_filtered_1.png
new file mode 100644
index 00000000000..f9f1fd82f1e
Binary files /dev/null and b/docs_src/src/images/image_filtered_1.png differ
diff --git a/docs_src/src/images/image_filtered_2.png b/docs_src/src/images/image_filtered_2.png
new file mode 100644
index 00000000000..0e42263432b
Binary files /dev/null and b/docs_src/src/images/image_filtered_2.png differ
diff --git a/docs_src/src/images/image_filtered_3.png b/docs_src/src/images/image_filtered_3.png
new file mode 100644
index 00000000000..d19e3257e73
Binary files /dev/null and b/docs_src/src/images/image_filtered_3.png differ
diff --git a/docs_src/src/images/image_filtered_4.png b/docs_src/src/images/image_filtered_4.png
new file mode 100644
index 00000000000..1054dfcbef6
Binary files /dev/null and b/docs_src/src/images/image_filtered_4.png differ
diff --git a/docs_src/src/images/image_fis_1024.png b/docs_src/src/images/image_fis_1024.png
new file mode 100644
index 00000000000..25bb4436019
Binary files /dev/null and b/docs_src/src/images/image_fis_1024.png differ
diff --git a/docs_src/src/images/image_fis_32.png b/docs_src/src/images/image_fis_32.png
new file mode 100644
index 00000000000..4a73da0465a
Binary files /dev/null and b/docs_src/src/images/image_fis_32.png differ
diff --git a/docs_src/src/images/image_is_1024.png b/docs_src/src/images/image_is_1024.png
new file mode 100644
index 00000000000..b2ba367cb86
Binary files /dev/null and b/docs_src/src/images/image_is_1024.png differ
diff --git a/docs_src/src/images/image_is_32.png b/docs_src/src/images/image_is_32.png
new file mode 100644
index 00000000000..d4f1b96d19e
Binary files /dev/null and b/docs_src/src/images/image_is_32.png differ
diff --git a/docs_src/src/images/image_is_4096.png b/docs_src/src/images/image_is_4096.png
new file mode 100644
index 00000000000..70fcaf74d56
Binary files /dev/null and b/docs_src/src/images/image_is_4096.png differ
diff --git a/docs_src/src/images/image_is_original.png b/docs_src/src/images/image_is_original.png
new file mode 100644
index 00000000000..425268719da
Binary files /dev/null and b/docs_src/src/images/image_is_original.png differ
diff --git a/docs_src/src/images/image_is_ref_1.png b/docs_src/src/images/image_is_ref_1.png
new file mode 100644
index 00000000000..fe29a4b2939
Binary files /dev/null and b/docs_src/src/images/image_is_ref_1.png differ
diff --git a/docs_src/src/images/image_is_ref_2.png b/docs_src/src/images/image_is_ref_2.png
new file mode 100644
index 00000000000..61c2d38680c
Binary files /dev/null and b/docs_src/src/images/image_is_ref_2.png differ
diff --git a/docs_src/src/images/image_is_ref_3.png b/docs_src/src/images/image_is_ref_3.png
new file mode 100644
index 00000000000..f11d7400dca
Binary files /dev/null and b/docs_src/src/images/image_is_ref_3.png differ
diff --git a/docs_src/src/images/image_is_ref_4.png b/docs_src/src/images/image_is_ref_4.png
new file mode 100644
index 00000000000..ddc18dbe796
Binary files /dev/null and b/docs_src/src/images/image_is_ref_4.png differ
diff --git a/site/content/posts/cocoapods/blue-screen.png b/docs_src/src/images/ios_sample/blue-screen.png
similarity index 100%
rename from site/content/posts/cocoapods/blue-screen.png
rename to docs_src/src/images/ios_sample/blue-screen.png
diff --git a/site/content/posts/cocoapods/colored-triangle.png b/docs_src/src/images/ios_sample/colored-triangle.png
similarity index 100%
rename from site/content/posts/cocoapods/colored-triangle.png
rename to docs_src/src/images/ios_sample/colored-triangle.png
diff --git a/site/content/posts/cocoapods/default-options.png b/docs_src/src/images/ios_sample/default-options.png
similarity index 100%
rename from site/content/posts/cocoapods/default-options.png
rename to docs_src/src/images/ios_sample/default-options.png
diff --git a/site/content/posts/cocoapods/mtkview.gif b/docs_src/src/images/ios_sample/mtkview.gif
similarity index 100%
rename from site/content/posts/cocoapods/mtkview.gif
rename to docs_src/src/images/ios_sample/mtkview.gif
diff --git a/site/content/posts/cocoapods/obj-cpp.png b/docs_src/src/images/ios_sample/obj-cpp.png
similarity index 100%
rename from site/content/posts/cocoapods/obj-cpp.png
rename to docs_src/src/images/ios_sample/obj-cpp.png
diff --git a/site/content/posts/cocoapods/rotating-triangle.gif b/docs_src/src/images/ios_sample/rotating-triangle.gif
similarity index 100%
rename from site/content/posts/cocoapods/rotating-triangle.gif
rename to docs_src/src/images/ios_sample/rotating-triangle.gif
diff --git a/site/content/posts/cocoapods/single-view-app.png b/docs_src/src/images/ios_sample/single-view-app.png
similarity index 100%
rename from site/content/posts/cocoapods/single-view-app.png
rename to docs_src/src/images/ios_sample/single-view-app.png
diff --git a/site/content/posts/cocoapods/view.png b/docs_src/src/images/ios_sample/view.png
similarity index 100%
rename from site/content/posts/cocoapods/view.png
rename to docs_src/src/images/ios_sample/view.png
diff --git a/site/content/posts/cocoapods/white-triangle.png b/docs_src/src/images/ios_sample/white-triangle.png
similarity index 100%
rename from site/content/posts/cocoapods/white-triangle.png
rename to docs_src/src/images/ios_sample/white-triangle.png
diff --git a/docs_src/src/images/material_absorption.png b/docs_src/src/images/material_absorption.png
new file mode 100644
index 00000000000..ffbca78b10e
Binary files /dev/null and b/docs_src/src/images/material_absorption.png differ
diff --git a/docs_src/src/images/material_anisotropic.png b/docs_src/src/images/material_anisotropic.png
new file mode 100644
index 00000000000..68b812d6dc7
Binary files /dev/null and b/docs_src/src/images/material_anisotropic.png differ
diff --git a/docs_src/src/images/material_bent_normal.gif b/docs_src/src/images/material_bent_normal.gif
new file mode 100644
index 00000000000..9cc3ee234ba
Binary files /dev/null and b/docs_src/src/images/material_bent_normal.gif differ
diff --git a/docs_src/src/images/material_blending.png b/docs_src/src/images/material_blending.png
new file mode 100644
index 00000000000..f810e9beb1d
Binary files /dev/null and b/docs_src/src/images/material_blending.png differ
diff --git a/docs_src/src/images/material_carbon_fiber.png b/docs_src/src/images/material_carbon_fiber.png
new file mode 100644
index 00000000000..4b5851a9edc
Binary files /dev/null and b/docs_src/src/images/material_carbon_fiber.png differ
diff --git a/docs_src/src/images/material_chart.jpg b/docs_src/src/images/material_chart.jpg
new file mode 100644
index 00000000000..856ebcd8f82
Binary files /dev/null and b/docs_src/src/images/material_chart.jpg differ
diff --git a/docs_src/src/images/material_clear_coat.png b/docs_src/src/images/material_clear_coat.png
new file mode 100644
index 00000000000..bbf3b2954d1
Binary files /dev/null and b/docs_src/src/images/material_clear_coat.png differ
diff --git a/docs_src/src/images/material_clear_coat1.png b/docs_src/src/images/material_clear_coat1.png
new file mode 100644
index 00000000000..65bf963106f
Binary files /dev/null and b/docs_src/src/images/material_clear_coat1.png differ
diff --git a/docs_src/src/images/material_clear_coat2.png b/docs_src/src/images/material_clear_coat2.png
new file mode 100644
index 00000000000..1e50aa5f3e2
Binary files /dev/null and b/docs_src/src/images/material_clear_coat2.png differ
diff --git a/docs_src/src/images/material_furnace_energy_loss.png b/docs_src/src/images/material_furnace_energy_loss.png
new file mode 100644
index 00000000000..b025d26bfbb
Binary files /dev/null and b/docs_src/src/images/material_furnace_energy_loss.png differ
diff --git a/docs_src/src/images/material_furnace_energy_preservation.png b/docs_src/src/images/material_furnace_energy_preservation.png
new file mode 100644
index 00000000000..e116ce2593f
Binary files /dev/null and b/docs_src/src/images/material_furnace_energy_preservation.png differ
diff --git a/docs_src/src/images/material_grazing_reflectance.png b/docs_src/src/images/material_grazing_reflectance.png
new file mode 100644
index 00000000000..92da8ce4931
Binary files /dev/null and b/docs_src/src/images/material_grazing_reflectance.png differ
diff --git a/docs_src/src/images/material_interpolation.png b/docs_src/src/images/material_interpolation.png
new file mode 100644
index 00000000000..88bbf3d2417
Binary files /dev/null and b/docs_src/src/images/material_interpolation.png differ
diff --git a/docs_src/src/images/material_ior.png b/docs_src/src/images/material_ior.png
new file mode 100644
index 00000000000..99752738218
Binary files /dev/null and b/docs_src/src/images/material_ior.png differ
diff --git a/docs_src/src/images/material_metallic_energy_loss.png b/docs_src/src/images/material_metallic_energy_loss.png
new file mode 100644
index 00000000000..a4120d18acd
Binary files /dev/null and b/docs_src/src/images/material_metallic_energy_loss.png differ
diff --git a/docs_src/src/images/material_metallic_energy_preservation.png b/docs_src/src/images/material_metallic_energy_preservation.png
new file mode 100644
index 00000000000..ca95e1197be
Binary files /dev/null and b/docs_src/src/images/material_metallic_energy_preservation.png differ
diff --git a/docs_src/src/images/material_parameters.png b/docs_src/src/images/material_parameters.png
new file mode 100644
index 00000000000..4116632c7fc
Binary files /dev/null and b/docs_src/src/images/material_parameters.png differ
diff --git a/docs_src/src/images/material_roughness_remap.png b/docs_src/src/images/material_roughness_remap.png
new file mode 100644
index 00000000000..c98dfaaf830
Binary files /dev/null and b/docs_src/src/images/material_roughness_remap.png differ
diff --git a/docs_src/src/images/material_thickness.png b/docs_src/src/images/material_thickness.png
new file mode 100644
index 00000000000..bada6592913
Binary files /dev/null and b/docs_src/src/images/material_thickness.png differ
diff --git a/docs_src/src/images/materials/absorption.png b/docs_src/src/images/materials/absorption.png
new file mode 100644
index 00000000000..6c1ebf8652c
Binary files /dev/null and b/docs_src/src/images/materials/absorption.png differ
diff --git a/docs_src/src/images/materials/anisotropy.png b/docs_src/src/images/materials/anisotropy.png
new file mode 100644
index 00000000000..c568d486529
Binary files /dev/null and b/docs_src/src/images/materials/anisotropy.png differ
diff --git a/docs_src/src/images/materials/clear_coat.png b/docs_src/src/images/materials/clear_coat.png
new file mode 100644
index 00000000000..d3d41bc5bd1
Binary files /dev/null and b/docs_src/src/images/materials/clear_coat.png differ
diff --git a/docs_src/src/images/materials/clear_coat_roughness.png b/docs_src/src/images/materials/clear_coat_roughness.png
new file mode 100644
index 00000000000..03f169c85b6
Binary files /dev/null and b/docs_src/src/images/materials/clear_coat_roughness.png differ
diff --git a/docs_src/src/images/materials/conductor_roughness.png b/docs_src/src/images/materials/conductor_roughness.png
new file mode 100644
index 00000000000..1fe537984f1
Binary files /dev/null and b/docs_src/src/images/materials/conductor_roughness.png differ
diff --git a/docs_src/src/images/materials/dielectric_roughness.png b/docs_src/src/images/materials/dielectric_roughness.png
new file mode 100644
index 00000000000..0fe95758408
Binary files /dev/null and b/docs_src/src/images/materials/dielectric_roughness.png differ
diff --git a/docs_src/src/images/materials/ior.png b/docs_src/src/images/materials/ior.png
new file mode 100644
index 00000000000..e1b8ced8d90
Binary files /dev/null and b/docs_src/src/images/materials/ior.png differ
diff --git a/docs_src/src/images/materials/metallic.png b/docs_src/src/images/materials/metallic.png
new file mode 100644
index 00000000000..34dbbd83f9e
Binary files /dev/null and b/docs_src/src/images/materials/metallic.png differ
diff --git a/docs_src/src/images/materials/reflectance.png b/docs_src/src/images/materials/reflectance.png
new file mode 100644
index 00000000000..5a1a510d8f5
Binary files /dev/null and b/docs_src/src/images/materials/reflectance.png differ
diff --git a/docs_src/src/images/materials/refraction_roughness.png b/docs_src/src/images/materials/refraction_roughness.png
new file mode 100644
index 00000000000..64cf1a4f123
Binary files /dev/null and b/docs_src/src/images/materials/refraction_roughness.png differ
diff --git a/docs_src/src/images/materials/sheen_roughness.png b/docs_src/src/images/materials/sheen_roughness.png
new file mode 100644
index 00000000000..c1247f46e44
Binary files /dev/null and b/docs_src/src/images/materials/sheen_roughness.png differ
diff --git a/docs_src/src/images/materials/thickness.png b/docs_src/src/images/materials/thickness.png
new file mode 100644
index 00000000000..d64320f0aed
Binary files /dev/null and b/docs_src/src/images/materials/thickness.png differ
diff --git a/docs_src/src/images/materials/transmission.png b/docs_src/src/images/materials/transmission.png
new file mode 100644
index 00000000000..88d9a036f7d
Binary files /dev/null and b/docs_src/src/images/materials/transmission.png differ
diff --git a/docs_src/src/images/photo_fresnel_lake.jpg b/docs_src/src/images/photo_fresnel_lake.jpg
new file mode 100644
index 00000000000..0e34475a848
Binary files /dev/null and b/docs_src/src/images/photo_fresnel_lake.jpg differ
diff --git a/docs_src/src/images/photo_incident_light_meter.jpg b/docs_src/src/images/photo_incident_light_meter.jpg
new file mode 100644
index 00000000000..f7017ad930f
Binary files /dev/null and b/docs_src/src/images/photo_incident_light_meter.jpg differ
diff --git a/docs_src/src/images/photo_light_meter.jpg b/docs_src/src/images/photo_light_meter.jpg
new file mode 100644
index 00000000000..2ca1f94b5fb
Binary files /dev/null and b/docs_src/src/images/photo_light_meter.jpg differ
diff --git a/docs_src/src/images/photo_photometric_lights.jpg b/docs_src/src/images/photo_photometric_lights.jpg
new file mode 100644
index 00000000000..f1af42c0fec
Binary files /dev/null and b/docs_src/src/images/photo_photometric_lights.jpg differ
diff --git a/docs_src/src/images/samples/app_gmm_ar_nav.jpg b/docs_src/src/images/samples/app_gmm_ar_nav.jpg
new file mode 100644
index 00000000000..093400ebcbc
Binary files /dev/null and b/docs_src/src/images/samples/app_gmm_ar_nav.jpg differ
diff --git a/docs_src/src/images/samples/app_google_3d_viewer.jpg b/docs_src/src/images/samples/app_google_3d_viewer.jpg
new file mode 100644
index 00000000000..446370ef908
Binary files /dev/null and b/docs_src/src/images/samples/app_google_3d_viewer.jpg differ
diff --git a/docs_src/src/images/samples/example_bistro1.jpg b/docs_src/src/images/samples/example_bistro1.jpg
new file mode 100644
index 00000000000..29d7befdcde
Binary files /dev/null and b/docs_src/src/images/samples/example_bistro1.jpg differ
diff --git a/docs_src/src/images/samples/example_bistro2.jpg b/docs_src/src/images/samples/example_bistro2.jpg
new file mode 100644
index 00000000000..ecd092cd92b
Binary files /dev/null and b/docs_src/src/images/samples/example_bistro2.jpg differ
diff --git a/docs_src/src/images/samples/example_helmet.jpg b/docs_src/src/images/samples/example_helmet.jpg
new file mode 100644
index 00000000000..8f495435032
Binary files /dev/null and b/docs_src/src/images/samples/example_helmet.jpg differ
diff --git a/docs_src/src/images/samples/example_live_wallpaper.jpg b/docs_src/src/images/samples/example_live_wallpaper.jpg
new file mode 100644
index 00000000000..74ad33f1aeb
Binary files /dev/null and b/docs_src/src/images/samples/example_live_wallpaper.jpg differ
diff --git a/docs_src/src/images/samples/example_materials1.jpg b/docs_src/src/images/samples/example_materials1.jpg
new file mode 100644
index 00000000000..54266b97cf6
Binary files /dev/null and b/docs_src/src/images/samples/example_materials1.jpg differ
diff --git a/docs_src/src/images/samples/example_materials2.jpg b/docs_src/src/images/samples/example_materials2.jpg
new file mode 100644
index 00000000000..c5745515e96
Binary files /dev/null and b/docs_src/src/images/samples/example_materials2.jpg differ
diff --git a/docs_src/src/images/samples/example_ssr.jpg b/docs_src/src/images/samples/example_ssr.jpg
new file mode 100644
index 00000000000..46018afffbe
Binary files /dev/null and b/docs_src/src/images/samples/example_ssr.jpg differ
diff --git a/docs_src/src/images/samples/sample_gltf_viewer.jpg b/docs_src/src/images/samples/sample_gltf_viewer.jpg
new file mode 100644
index 00000000000..1ecbd3b38f2
Binary files /dev/null and b/docs_src/src/images/samples/sample_gltf_viewer.jpg differ
diff --git a/docs_src/src/images/samples/sample_hello_camera.jpg b/docs_src/src/images/samples/sample_hello_camera.jpg
new file mode 100644
index 00000000000..e945e8db06b
Binary files /dev/null and b/docs_src/src/images/samples/sample_hello_camera.jpg differ
diff --git a/docs_src/src/images/samples/sample_hello_triangle.jpg b/docs_src/src/images/samples/sample_hello_triangle.jpg
new file mode 100644
index 00000000000..224ee043665
Binary files /dev/null and b/docs_src/src/images/samples/sample_hello_triangle.jpg differ
diff --git a/docs_src/src/images/samples/sample_image_based_lighting.jpg b/docs_src/src/images/samples/sample_image_based_lighting.jpg
new file mode 100644
index 00000000000..334e2a2067a
Binary files /dev/null and b/docs_src/src/images/samples/sample_image_based_lighting.jpg differ
diff --git a/docs_src/src/images/samples/sample_lit_cube.jpg b/docs_src/src/images/samples/sample_lit_cube.jpg
new file mode 100644
index 00000000000..b5ef384e087
Binary files /dev/null and b/docs_src/src/images/samples/sample_lit_cube.jpg differ
diff --git a/docs_src/src/images/samples/sample_page_curl.jpg b/docs_src/src/images/samples/sample_page_curl.jpg
new file mode 100644
index 00000000000..6ea94d1ca42
Binary files /dev/null and b/docs_src/src/images/samples/sample_page_curl.jpg differ
diff --git a/docs_src/src/images/samples/sample_stream_test.jpg b/docs_src/src/images/samples/sample_stream_test.jpg
new file mode 100644
index 00000000000..d4429264774
Binary files /dev/null and b/docs_src/src/images/samples/sample_stream_test.jpg differ
diff --git a/docs_src/src/images/samples/sample_texture_view.jpg b/docs_src/src/images/samples/sample_texture_view.jpg
new file mode 100644
index 00000000000..76eb15cd7ec
Binary files /dev/null and b/docs_src/src/images/samples/sample_texture_view.jpg differ
diff --git a/docs_src/src/images/samples/sample_textured_object.jpg b/docs_src/src/images/samples/sample_textured_object.jpg
new file mode 100644
index 00000000000..2f04e30a601
Binary files /dev/null and b/docs_src/src/images/samples/sample_textured_object.jpg differ
diff --git a/docs_src/src/images/samples/sample_transparent_rendering.jpg b/docs_src/src/images/samples/sample_transparent_rendering.jpg
new file mode 100644
index 00000000000..8a5d0c0e1e3
Binary files /dev/null and b/docs_src/src/images/samples/sample_transparent_rendering.jpg differ
diff --git a/docs_src/src/images/screenshot_anisotropic_ibl1.jpg b/docs_src/src/images/screenshot_anisotropic_ibl1.jpg
new file mode 100644
index 00000000000..0462fdd5632
Binary files /dev/null and b/docs_src/src/images/screenshot_anisotropic_ibl1.jpg differ
diff --git a/docs_src/src/images/screenshot_anisotropic_ibl2.jpg b/docs_src/src/images/screenshot_anisotropic_ibl2.jpg
new file mode 100644
index 00000000000..b7aca5984ff
Binary files /dev/null and b/docs_src/src/images/screenshot_anisotropic_ibl2.jpg differ
diff --git a/docs_src/src/images/screenshot_anisotropy.png b/docs_src/src/images/screenshot_anisotropy.png
new file mode 100644
index 00000000000..9eda502fd9f
Binary files /dev/null and b/docs_src/src/images/screenshot_anisotropy.png differ
diff --git a/docs_src/src/images/screenshot_anisotropy_direction.png b/docs_src/src/images/screenshot_anisotropy_direction.png
new file mode 100644
index 00000000000..a0825b36e68
Binary files /dev/null and b/docs_src/src/images/screenshot_anisotropy_direction.png differ
diff --git a/docs_src/src/images/screenshot_anisotropy_map.jpg b/docs_src/src/images/screenshot_anisotropy_map.jpg
new file mode 100644
index 00000000000..8e5bde1c53e
Binary files /dev/null and b/docs_src/src/images/screenshot_anisotropy_map.jpg differ
diff --git a/docs_src/src/images/screenshot_ao.jpg b/docs_src/src/images/screenshot_ao.jpg
new file mode 100644
index 00000000000..8ed57a6e389
Binary files /dev/null and b/docs_src/src/images/screenshot_ao.jpg differ
diff --git a/docs_src/src/images/screenshot_ball_ibl.png b/docs_src/src/images/screenshot_ball_ibl.png
new file mode 100644
index 00000000000..a4533160931
Binary files /dev/null and b/docs_src/src/images/screenshot_ball_ibl.png differ
diff --git a/docs_src/src/images/screenshot_bloom.jpg b/docs_src/src/images/screenshot_bloom.jpg
new file mode 100644
index 00000000000..c7f62f54d4a
Binary files /dev/null and b/docs_src/src/images/screenshot_bloom.jpg differ
diff --git a/docs_src/src/images/screenshot_camera_transparency.jpg b/docs_src/src/images/screenshot_camera_transparency.jpg
new file mode 100644
index 00000000000..32336edcd40
Binary files /dev/null and b/docs_src/src/images/screenshot_camera_transparency.jpg differ
diff --git a/docs_src/src/images/screenshot_car.jpg b/docs_src/src/images/screenshot_car.jpg
new file mode 100644
index 00000000000..3c0970e42e5
Binary files /dev/null and b/docs_src/src/images/screenshot_car.jpg differ
diff --git a/docs_src/src/images/screenshot_clear_coat_ior_change.jpg b/docs_src/src/images/screenshot_clear_coat_ior_change.jpg
new file mode 100644
index 00000000000..49d74fd0ca7
Binary files /dev/null and b/docs_src/src/images/screenshot_clear_coat_ior_change.jpg differ
diff --git a/docs_src/src/images/screenshot_clear_coat_normal.jpg b/docs_src/src/images/screenshot_clear_coat_normal.jpg
new file mode 100644
index 00000000000..4debc92d317
Binary files /dev/null and b/docs_src/src/images/screenshot_clear_coat_normal.jpg differ
diff --git a/docs_src/src/images/screenshot_cloth.png b/docs_src/src/images/screenshot_cloth.png
new file mode 100644
index 00000000000..666034c628f
Binary files /dev/null and b/docs_src/src/images/screenshot_cloth.png differ
diff --git a/docs_src/src/images/screenshot_cloth_sheen.png b/docs_src/src/images/screenshot_cloth_sheen.png
new file mode 100644
index 00000000000..9be7ded2cb6
Binary files /dev/null and b/docs_src/src/images/screenshot_cloth_sheen.png differ
diff --git a/docs_src/src/images/screenshot_cloth_subsurface.png b/docs_src/src/images/screenshot_cloth_subsurface.png
new file mode 100644
index 00000000000..e78e80f22df
Binary files /dev/null and b/docs_src/src/images/screenshot_cloth_subsurface.png differ
diff --git a/docs_src/src/images/screenshot_cloth_velvet.png b/docs_src/src/images/screenshot_cloth_velvet.png
new file mode 100644
index 00000000000..9d6b04928f5
Binary files /dev/null and b/docs_src/src/images/screenshot_cloth_velvet.png differ
diff --git a/docs_src/src/images/screenshot_coordinates.jpg b/docs_src/src/images/screenshot_coordinates.jpg
new file mode 100644
index 00000000000..998b55e1c67
Binary files /dev/null and b/docs_src/src/images/screenshot_coordinates.jpg differ
diff --git a/docs_src/src/images/screenshot_cubemap_coordinates.png b/docs_src/src/images/screenshot_cubemap_coordinates.png
new file mode 100644
index 00000000000..5a8c58c7717
Binary files /dev/null and b/docs_src/src/images/screenshot_cubemap_coordinates.png differ
diff --git a/docs_src/src/images/screenshot_directional_light.png b/docs_src/src/images/screenshot_directional_light.png
new file mode 100644
index 00000000000..16f32ad924f
Binary files /dev/null and b/docs_src/src/images/screenshot_directional_light.png differ
diff --git a/docs_src/src/images/screenshot_fog1.jpg b/docs_src/src/images/screenshot_fog1.jpg
new file mode 100644
index 00000000000..bf60c6e5a5f
Binary files /dev/null and b/docs_src/src/images/screenshot_fog1.jpg differ
diff --git a/docs_src/src/images/screenshot_fog2.jpg b/docs_src/src/images/screenshot_fog2.jpg
new file mode 100644
index 00000000000..5ddf155fcfe
Binary files /dev/null and b/docs_src/src/images/screenshot_fog2.jpg differ
diff --git a/docs_src/src/images/screenshot_fringing.jpg b/docs_src/src/images/screenshot_fringing.jpg
new file mode 100644
index 00000000000..a9b5c22c9e9
Binary files /dev/null and b/docs_src/src/images/screenshot_fringing.jpg differ
diff --git a/docs_src/src/images/screenshot_lightgen_samples.png b/docs_src/src/images/screenshot_lightgen_samples.png
new file mode 100644
index 00000000000..80b292806c4
Binary files /dev/null and b/docs_src/src/images/screenshot_lightgen_samples.png differ
diff --git a/docs_src/src/images/screenshot_luminance_debug.png b/docs_src/src/images/screenshot_luminance_debug.png
new file mode 100644
index 00000000000..431ebed660c
Binary files /dev/null and b/docs_src/src/images/screenshot_luminance_debug.png differ
diff --git a/docs_src/src/images/screenshot_multi_bounce_ao.gif b/docs_src/src/images/screenshot_multi_bounce_ao.gif
new file mode 100644
index 00000000000..4208dc99050
Binary files /dev/null and b/docs_src/src/images/screenshot_multi_bounce_ao.gif differ
diff --git a/docs_src/src/images/screenshot_multi_bounce_ao.jpg b/docs_src/src/images/screenshot_multi_bounce_ao.jpg
new file mode 100644
index 00000000000..2f629906d21
Binary files /dev/null and b/docs_src/src/images/screenshot_multi_bounce_ao.jpg differ
diff --git a/docs_src/src/images/screenshot_normal_map.jpg b/docs_src/src/images/screenshot_normal_map.jpg
new file mode 100644
index 00000000000..dd186561e48
Binary files /dev/null and b/docs_src/src/images/screenshot_normal_map.jpg differ
diff --git a/docs_src/src/images/screenshot_normal_map_blended.jpg b/docs_src/src/images/screenshot_normal_map_blended.jpg
new file mode 100644
index 00000000000..af8fd0da76f
Binary files /dev/null and b/docs_src/src/images/screenshot_normal_map_blended.jpg differ
diff --git a/docs_src/src/images/screenshot_normal_map_blended_udn.jpg b/docs_src/src/images/screenshot_normal_map_blended_udn.jpg
new file mode 100644
index 00000000000..0453bf0e3bb
Binary files /dev/null and b/docs_src/src/images/screenshot_normal_map_blended_udn.jpg differ
diff --git a/docs_src/src/images/screenshot_normal_map_detail.jpg b/docs_src/src/images/screenshot_normal_map_detail.jpg
new file mode 100644
index 00000000000..7372941cf61
Binary files /dev/null and b/docs_src/src/images/screenshot_normal_map_detail.jpg differ
diff --git a/docs_src/src/images/screenshot_normal_mapping.jpg b/docs_src/src/images/screenshot_normal_mapping.jpg
new file mode 100644
index 00000000000..4c3ff5f5668
Binary files /dev/null and b/docs_src/src/images/screenshot_normal_mapping.jpg differ
diff --git a/docs_src/src/images/screenshot_photometric_lights.png b/docs_src/src/images/screenshot_photometric_lights.png
new file mode 100644
index 00000000000..6a2fe85b973
Binary files /dev/null and b/docs_src/src/images/screenshot_photometric_lights.png differ
diff --git a/docs_src/src/images/screenshot_point_light.png b/docs_src/src/images/screenshot_point_light.png
new file mode 100644
index 00000000000..bca0cc9457b
Binary files /dev/null and b/docs_src/src/images/screenshot_point_light.png differ
diff --git a/docs_src/src/images/screenshot_ref_comparison.png b/docs_src/src/images/screenshot_ref_comparison.png
new file mode 100644
index 00000000000..b050291896a
Binary files /dev/null and b/docs_src/src/images/screenshot_ref_comparison.png differ
diff --git a/docs_src/src/images/screenshot_ref_filament.jpg b/docs_src/src/images/screenshot_ref_filament.jpg
new file mode 100644
index 00000000000..43a749ef935
Binary files /dev/null and b/docs_src/src/images/screenshot_ref_filament.jpg differ
diff --git a/docs_src/src/images/screenshot_ref_mitsuba.jpg b/docs_src/src/images/screenshot_ref_mitsuba.jpg
new file mode 100644
index 00000000000..d3c2cccf6d1
Binary files /dev/null and b/docs_src/src/images/screenshot_ref_mitsuba.jpg differ
diff --git a/docs_src/src/images/screenshot_sheen_color.png b/docs_src/src/images/screenshot_sheen_color.png
new file mode 100644
index 00000000000..02f27ab820f
Binary files /dev/null and b/docs_src/src/images/screenshot_sheen_color.png differ
diff --git a/docs_src/src/images/screenshot_specular_ao.gif b/docs_src/src/images/screenshot_specular_ao.gif
new file mode 100644
index 00000000000..9d81e7dc4cb
Binary files /dev/null and b/docs_src/src/images/screenshot_specular_ao.gif differ
diff --git a/docs_src/src/images/screenshot_sponza.jpg b/docs_src/src/images/screenshot_sponza.jpg
new file mode 100644
index 00000000000..cf8934a3c5f
Binary files /dev/null and b/docs_src/src/images/screenshot_sponza.jpg differ
diff --git a/docs_src/src/images/screenshot_sponza_froxels1.jpg b/docs_src/src/images/screenshot_sponza_froxels1.jpg
new file mode 100644
index 00000000000..1d8702b14f8
Binary files /dev/null and b/docs_src/src/images/screenshot_sponza_froxels1.jpg differ
diff --git a/docs_src/src/images/screenshot_sponza_froxels2.jpg b/docs_src/src/images/screenshot_sponza_froxels2.jpg
new file mode 100644
index 00000000000..c297e312d2f
Binary files /dev/null and b/docs_src/src/images/screenshot_sponza_froxels2.jpg differ
diff --git a/docs_src/src/images/screenshot_sponza_slices.jpg b/docs_src/src/images/screenshot_sponza_slices.jpg
new file mode 100644
index 00000000000..7cb48b2771c
Binary files /dev/null and b/docs_src/src/images/screenshot_sponza_slices.jpg differ
diff --git a/docs_src/src/images/screenshot_sponza_tiles.jpg b/docs_src/src/images/screenshot_sponza_tiles.jpg
new file mode 100644
index 00000000000..c3e2aa86afa
Binary files /dev/null and b/docs_src/src/images/screenshot_sponza_tiles.jpg differ
diff --git a/docs_src/src/images/screenshot_spot_light.png b/docs_src/src/images/screenshot_spot_light.png
new file mode 100644
index 00000000000..8d0939ba181
Binary files /dev/null and b/docs_src/src/images/screenshot_spot_light.png differ
diff --git a/docs_src/src/images/screenshot_spot_light_focused.png b/docs_src/src/images/screenshot_spot_light_focused.png
new file mode 100644
index 00000000000..96c4d91f858
Binary files /dev/null and b/docs_src/src/images/screenshot_spot_light_focused.png differ
diff --git a/docs_src/src/images/screenshot_toon_shading.png b/docs_src/src/images/screenshot_toon_shading.png
new file mode 100644
index 00000000000..059cc5bca92
Binary files /dev/null and b/docs_src/src/images/screenshot_toon_shading.png differ
diff --git a/docs_src/src/images/screenshot_translucency.png b/docs_src/src/images/screenshot_translucency.png
new file mode 100644
index 00000000000..b27980f91c0
Binary files /dev/null and b/docs_src/src/images/screenshot_translucency.png differ
diff --git a/docs_src/src/images/screenshot_transparency_default.png b/docs_src/src/images/screenshot_transparency_default.png
new file mode 100644
index 00000000000..e9174998e97
Binary files /dev/null and b/docs_src/src/images/screenshot_transparency_default.png differ
diff --git a/docs_src/src/images/screenshot_transparent_shadows.jpg b/docs_src/src/images/screenshot_transparent_shadows.jpg
new file mode 100644
index 00000000000..819cf63d93f
Binary files /dev/null and b/docs_src/src/images/screenshot_transparent_shadows.jpg differ
diff --git a/docs_src/src/images/screenshot_twopasses_oneside.png b/docs_src/src/images/screenshot_twopasses_oneside.png
new file mode 100644
index 00000000000..8c2c366b0c0
Binary files /dev/null and b/docs_src/src/images/screenshot_twopasses_oneside.png differ
diff --git a/docs_src/src/images/screenshot_twopasses_twosides.png b/docs_src/src/images/screenshot_twopasses_twosides.png
new file mode 100644
index 00000000000..bb877fdc09b
Binary files /dev/null and b/docs_src/src/images/screenshot_twopasses_twosides.png differ
diff --git a/docs_src/src/images/screenshot_unlit.jpg b/docs_src/src/images/screenshot_unlit.jpg
new file mode 100644
index 00000000000..e03fb31612b
Binary files /dev/null and b/docs_src/src/images/screenshot_unlit.jpg differ
diff --git a/docs_src/src/images/screenshot_xarrow.png b/docs_src/src/images/screenshot_xarrow.png
new file mode 100644
index 00000000000..bdf91d44e55
Binary files /dev/null and b/docs_src/src/images/screenshot_xarrow.png differ
diff --git a/docs_src/src/main/README.md b/docs_src/src/main/README.md
new file mode 100644
index 00000000000..c0d25f7e5ee
--- /dev/null
+++ b/docs_src/src/main/README.md
@@ -0,0 +1,5 @@
+# Core Concepts
+
+
+- [Filament](main/filament.md) - High-level designs; Filament's PBR/math assumptions; implementation details.
+- [Materials](main/materials.md) - A guide to Filament's material definition.
diff --git a/docs_src/src/main/filament.md b/docs_src/src/main/filament.md
new file mode 100644
index 00000000000..7a15685b6ee
--- /dev/null
+++ b/docs_src/src/main/filament.md
@@ -0,0 +1,4410 @@
+<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">
+<style>img { max-width: 100%; }</style>
+<script type="text/x-mathjax-config">MathJax.Hub.Config({ TeX: { equationNumbers: {autoNumber: "AMS"} } });</script><span style="display:none">$$\newcommand{\n}{\hat{n}}\newcommand{\thetai}{\theta_\mathrm{i}}\newcommand{\thetao}{\theta_\mathrm{o}}\newcommand{\d}[1]{\mathrm{d}#1}\newcommand{\w}{\hat{\omega}}\newcommand{\wi}{\w_\mathrm{i}}\newcommand{\wo}{\w_\mathrm{o}}\newcommand{\wh}{\w_\mathrm{h}}\newcommand{\Li}{L_\mathrm{i}}\newcommand{\Lo}{L_\mathrm{o}}\newcommand{\Le}{L_\mathrm{e}}\newcommand{\Lr}{L_\mathrm{r}}\newcommand{\Lt}{L_\mathrm{t}}\newcommand{\O}{\mathrm{O}}\newcommand{\degrees}{{^{\large\circ}}}\newcommand{\T}{\mathsf{T}}\newcommand{\mathset}[1]{\mathbb{#1}}\newcommand{\Real}{\mathset{R}}\newcommand{\Integer}{\mathset{Z}}\newcommand{\Boolean}{\mathset{B}}\newcommand{\Complex}{\mathset{C}}\newcommand{\un}[1]{\,\mathrm{#1}}$$
+</span>
+<span class="md"><p><title>Physically Based Rendering in Filament</title><div class="title"> Physically Based Rendering in Filament </div>
+<div class="afterTitles"></div>
+</p><p>
+<center><a href="../images/filament_logo.png" target="_blank"><img class="markdeep" src="../images/filament_logo.png" /></a></center>
+</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&nbsp; </span>About</a><br/>
+&nbsp;&nbsp;<a href="#about/authors"  target="_self" class="level2"><span class="tocNumber">1.1&nbsp; </span>Authors</a><br/>
+<a href="#overview"  target="_self" class="level1"><span class="tocNumber">2&nbsp; </span>Overview</a><br/>
+&nbsp;&nbsp;<a href="#overview/principles"  target="_self" class="level2"><span class="tocNumber">2.1&nbsp; </span>Principles</a><br/>
+&nbsp;&nbsp;<a href="#overview/physicallybasedrendering"  target="_self" class="level2"><span class="tocNumber">2.2&nbsp; </span>Physically based rendering</a><br/>
+<a href="#notation"  target="_self" class="level1"><span class="tocNumber">3&nbsp; </span>Notation</a><br/>
+<a href="#materialsystem"  target="_self" class="level1"><span class="tocNumber">4&nbsp; </span>Material system</a><br/>
+&nbsp;&nbsp;<a href="#materialsystem/standardmodel"  target="_self" class="level2"><span class="tocNumber">4.1&nbsp; </span>Standard model</a><br/>
+&nbsp;&nbsp;<a href="#materialsystem/dielectricsandconductors"  target="_self" class="level2"><span class="tocNumber">4.2&nbsp; </span>Dielectrics and conductors</a><br/>
+&nbsp;&nbsp;<a href="#materialsystem/energyconservation"  target="_self" class="level2"><span class="tocNumber">4.3&nbsp; </span>Energy conservation</a><br/>
+&nbsp;&nbsp;<a href="#materialsystem/specularbrdf"  target="_self" class="level2"><span class="tocNumber">4.4&nbsp; </span>Specular BRDF</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialsystem/specularbrdf/normaldistributionfunction(speculard)"  target="_self" class="level3"><span class="tocNumber">4.4.1&nbsp; </span>Normal distribution function (specular D)</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialsystem/specularbrdf/geometricshadowing(specularg)"  target="_self" class="level3"><span class="tocNumber">4.4.2&nbsp; </span>Geometric shadowing (specular G)</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialsystem/specularbrdf/fresnel(specularf)"  target="_self" class="level3"><span class="tocNumber">4.4.3&nbsp; </span>Fresnel (specular F)</a><br/>
+&nbsp;&nbsp;<a href="#materialsystem/diffusebrdf"  target="_self" class="level2"><span class="tocNumber">4.5&nbsp; </span>Diffuse BRDF</a><br/>
+&nbsp;&nbsp;<a href="#materialsystem/standardmodelsummary"  target="_self" class="level2"><span class="tocNumber">4.6&nbsp; </span>Standard model summary</a><br/>
+&nbsp;&nbsp;<a href="#materialsystem/improvingthebrdfs"  target="_self" class="level2"><span class="tocNumber">4.7&nbsp; </span>Improving the BRDFs</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialsystem/improvingthebrdfs/energygainindiffusereflectance"  target="_self" class="level3"><span class="tocNumber">4.7.1&nbsp; </span>Energy gain in diffuse reflectance</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialsystem/improvingthebrdfs/energylossinspecularreflectance"  target="_self" class="level3"><span class="tocNumber">4.7.2&nbsp; </span>Energy loss in specular reflectance</a><br/>
+&nbsp;&nbsp;<a href="#materialsystem/parameterization"  target="_self" class="level2"><span class="tocNumber">4.8&nbsp; </span>Parameterization</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialsystem/parameterization/standardparameters"  target="_self" class="level3"><span class="tocNumber">4.8.1&nbsp; </span>Standard parameters</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialsystem/parameterization/typesandranges"  target="_self" class="level3"><span class="tocNumber">4.8.2&nbsp; </span>Types and ranges</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialsystem/parameterization/remapping"  target="_self" class="level3"><span class="tocNumber">4.8.3&nbsp; </span>Remapping</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialsystem/parameterization/blendingandlayering"  target="_self" class="level3"><span class="tocNumber">4.8.4&nbsp; </span>Blending and layering</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialsystem/parameterization/craftingphysicallybasedmaterials"  target="_self" class="level3"><span class="tocNumber">4.8.5&nbsp; </span>Crafting physically based materials</a><br/>
+&nbsp;&nbsp;<a href="#materialsystem/clearcoatmodel"  target="_self" class="level2"><span class="tocNumber">4.9&nbsp; </span>Clear coat model</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialsystem/clearcoatmodel/clearcoatspecularbrdf"  target="_self" class="level3"><span class="tocNumber">4.9.1&nbsp; </span>Clear coat specular BRDF</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialsystem/clearcoatmodel/integrationinthesurfaceresponse"  target="_self" class="level3"><span class="tocNumber">4.9.2&nbsp; </span>Integration in the surface response</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialsystem/clearcoatmodel/clearcoatparameterization"  target="_self" class="level3"><span class="tocNumber">4.9.3&nbsp; </span>Clear coat parameterization</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialsystem/clearcoatmodel/baselayermodification"  target="_self" class="level3"><span class="tocNumber">4.9.4&nbsp; </span>Base layer modification</a><br/>
+&nbsp;&nbsp;<a href="#materialsystem/anisotropicmodel"  target="_self" class="level2"><span class="tocNumber">4.10&nbsp; </span>Anisotropic model</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialsystem/anisotropicmodel/anisotropicspecularbrdf"  target="_self" class="level3"><span class="tocNumber">4.10.1&nbsp; </span>Anisotropic specular BRDF</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialsystem/anisotropicmodel/anisotropicparameterization"  target="_self" class="level3"><span class="tocNumber">4.10.2&nbsp; </span>Anisotropic parameterization</a><br/>
+&nbsp;&nbsp;<a href="#materialsystem/subsurfacemodel"  target="_self" class="level2"><span class="tocNumber">4.11&nbsp; </span>Subsurface model</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialsystem/subsurfacemodel/subsurfacespecularbrdf"  target="_self" class="level3"><span class="tocNumber">4.11.1&nbsp; </span>Subsurface specular BRDF</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialsystem/subsurfacemodel/subsurfaceparameterization"  target="_self" class="level3"><span class="tocNumber">4.11.2&nbsp; </span>Subsurface parameterization</a><br/>
+&nbsp;&nbsp;<a href="#materialsystem/clothmodel"  target="_self" class="level2"><span class="tocNumber">4.12&nbsp; </span>Cloth model</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialsystem/clothmodel/clothspecularbrdf"  target="_self" class="level3"><span class="tocNumber">4.12.1&nbsp; </span>Cloth specular BRDF</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialsystem/clothmodel/clothdiffusebrdf"  target="_self" class="level3"><span class="tocNumber">4.12.2&nbsp; </span>Cloth diffuse BRDF</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialsystem/clothmodel/clothparameterization"  target="_self" class="level3"><span class="tocNumber">4.12.3&nbsp; </span>Cloth parameterization</a><br/>
+<a href="#lighting"  target="_self" class="level1"><span class="tocNumber">5&nbsp; </span>Lighting</a><br/>
+&nbsp;&nbsp;<a href="#lighting/units"  target="_self" class="level2"><span class="tocNumber">5.1&nbsp; </span>Units</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#lighting/units/lightunitsvalidation"  target="_self" class="level3"><span class="tocNumber">5.1.1&nbsp; </span>Light units validation</a><br/>
+&nbsp;&nbsp;<a href="#lighting/directlighting"  target="_self" class="level2"><span class="tocNumber">5.2&nbsp; </span>Direct lighting</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#lighting/directlighting/directionallights"  target="_self" class="level3"><span class="tocNumber">5.2.1&nbsp; </span>Directional lights</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#lighting/directlighting/punctuallights"  target="_self" class="level3"><span class="tocNumber">5.2.2&nbsp; </span>Punctual lights</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#lighting/directlighting/photometriclights"  target="_self" class="level3"><span class="tocNumber">5.2.3&nbsp; </span>Photometric lights</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#lighting/directlighting/arealights"  target="_self" class="level3"><span class="tocNumber">5.2.4&nbsp; </span>Area lights</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#lighting/directlighting/lightsparameterization"  target="_self" class="level3"><span class="tocNumber">5.2.5&nbsp; </span>Lights parameterization</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#lighting/directlighting/pre-exposedlights"  target="_self" class="level3"><span class="tocNumber">5.2.6&nbsp; </span>Pre-exposed lights</a><br/>
+&nbsp;&nbsp;<a href="#lighting/imagebasedlights"  target="_self" class="level2"><span class="tocNumber">5.3&nbsp; </span>Image based lights</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#lighting/imagebasedlights/ibltypes"  target="_self" class="level3"><span class="tocNumber">5.3.1&nbsp; </span>IBL Types</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#lighting/imagebasedlights/iblunit"  target="_self" class="level3"><span class="tocNumber">5.3.2&nbsp; </span>IBL Unit</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#lighting/imagebasedlights/processinglightprobes"  target="_self" class="level3"><span class="tocNumber">5.3.3&nbsp; </span>Processing light probes</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#lighting/imagebasedlights/distantlightprobes"  target="_self" class="level3"><span class="tocNumber">5.3.4&nbsp; </span>Distant light probes</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#lighting/imagebasedlights/clearcoat"  target="_self" class="level3"><span class="tocNumber">5.3.5&nbsp; </span>Clear coat</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#lighting/imagebasedlights/anisotropy"  target="_self" class="level3"><span class="tocNumber">5.3.6&nbsp; </span>Anisotropy</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#lighting/imagebasedlights/subsurface"  target="_self" class="level3"><span class="tocNumber">5.3.7&nbsp; </span>Subsurface</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#lighting/imagebasedlights/cloth"  target="_self" class="level3"><span class="tocNumber">5.3.8&nbsp; </span>Cloth</a><br/>
+&nbsp;&nbsp;<a href="#lighting/staticlighting"  target="_self" class="level2"><span class="tocNumber">5.4&nbsp; </span>Static lighting</a><br/>
+&nbsp;&nbsp;<a href="#lighting/transparencyandtranslucencylighting"  target="_self" class="level2"><span class="tocNumber">5.5&nbsp; </span>Transparency and translucency lighting</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#lighting/transparencyandtranslucencylighting/transparency"  target="_self" class="level3"><span class="tocNumber">5.5.1&nbsp; </span>Transparency</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#lighting/transparencyandtranslucencylighting/translucency"  target="_self" class="level3"><span class="tocNumber">5.5.2&nbsp; </span>Translucency</a><br/>
+&nbsp;&nbsp;<a href="#lighting/occlusion"  target="_self" class="level2"><span class="tocNumber">5.6&nbsp; </span>Occlusion</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#lighting/occlusion/diffuseocclusion"  target="_self" class="level3"><span class="tocNumber">5.6.1&nbsp; </span>Diffuse occlusion</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#lighting/occlusion/specularocclusion"  target="_self" class="level3"><span class="tocNumber">5.6.2&nbsp; </span>Specular occlusion</a><br/>
+&nbsp;&nbsp;<a href="#lighting/normalmapping"  target="_self" class="level2"><span class="tocNumber">5.7&nbsp; </span>Normal mapping</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#lighting/normalmapping/reorientednormalmapping"  target="_self" class="level3"><span class="tocNumber">5.7.1&nbsp; </span>Reoriented normal mapping</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#lighting/normalmapping/udnblending"  target="_self" class="level3"><span class="tocNumber">5.7.2&nbsp; </span>UDN blending</a><br/>
+<a href="#volumetriceffects"  target="_self" class="level1"><span class="tocNumber">6&nbsp; </span>Volumetric effects</a><br/>
+&nbsp;&nbsp;<a href="#volumetriceffects/exponentialheightfog"  target="_self" class="level2"><span class="tocNumber">6.1&nbsp; </span>Exponential height fog</a><br/>
+<a href="#anti-aliasing"  target="_self" class="level1"><span class="tocNumber">7&nbsp; </span>Anti-aliasing</a><br/>
+<a href="#imagingpipeline"  target="_self" class="level1"><span class="tocNumber">8&nbsp; </span>Imaging pipeline</a><br/>
+&nbsp;&nbsp;<a href="#imagingpipeline/physicallybasedcamera"  target="_self" class="level2"><span class="tocNumber">8.1&nbsp; </span>Physically based camera</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#imagingpipeline/physicallybasedcamera/exposuresettings"  target="_self" class="level3"><span class="tocNumber">8.1.1&nbsp; </span>Exposure settings</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#imagingpipeline/physicallybasedcamera/exposurevalue"  target="_self" class="level3"><span class="tocNumber">8.1.2&nbsp; </span>Exposure value</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#imagingpipeline/physicallybasedcamera/exposure"  target="_self" class="level3"><span class="tocNumber">8.1.3&nbsp; </span>Exposure</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#imagingpipeline/physicallybasedcamera/automaticexposure"  target="_self" class="level3"><span class="tocNumber">8.1.4&nbsp; </span>Automatic exposure</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#imagingpipeline/physicallybasedcamera/bloom"  target="_self" class="level3"><span class="tocNumber">8.1.5&nbsp; </span>Bloom</a><br/>
+&nbsp;&nbsp;<a href="#imagingpipeline/opticspost-processing"  target="_self" class="level2"><span class="tocNumber">8.2&nbsp; </span>Optics post-processing</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#imagingpipeline/opticspost-processing/colorfringing"  target="_self" class="level3"><span class="tocNumber">8.2.1&nbsp; </span>Color fringing</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#imagingpipeline/opticspost-processing/lensflares"  target="_self" class="level3"><span class="tocNumber">8.2.2&nbsp; </span>Lens flares</a><br/>
+&nbsp;&nbsp;<a href="#imagingpipeline/filmicpost-processing"  target="_self" class="level2"><span class="tocNumber">8.3&nbsp; </span>Filmic post-processing</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#imagingpipeline/filmicpost-processing/contrast"  target="_self" class="level3"><span class="tocNumber">8.3.1&nbsp; </span>Contrast</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#imagingpipeline/filmicpost-processing/curves"  target="_self" class="level3"><span class="tocNumber">8.3.2&nbsp; </span>Curves</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#imagingpipeline/filmicpost-processing/levels"  target="_self" class="level3"><span class="tocNumber">8.3.3&nbsp; </span>Levels</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#imagingpipeline/filmicpost-processing/colorgrading"  target="_self" class="level3"><span class="tocNumber">8.3.4&nbsp; </span>Color grading</a><br/>
+&nbsp;&nbsp;<a href="#imagingpipeline/lightpath"  target="_self" class="level2"><span class="tocNumber">8.4&nbsp; </span>Light path</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#imagingpipeline/lightpath/clusteredforwardrendering"  target="_self" class="level3"><span class="tocNumber">8.4.1&nbsp; </span>Clustered Forward Rendering</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#imagingpipeline/lightpath/implementationnotes"  target="_self" class="level3"><span class="tocNumber">8.4.2&nbsp; </span>Implementation notes</a><br/>
+&nbsp;&nbsp;<a href="#imagingpipeline/validation"  target="_self" class="level2"><span class="tocNumber">8.5&nbsp; </span>Validation</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#imagingpipeline/validation/scenereferredvisualization"  target="_self" class="level3"><span class="tocNumber">8.5.1&nbsp; </span>Scene referred visualization</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#imagingpipeline/validation/referencerenderings"  target="_self" class="level3"><span class="tocNumber">8.5.2&nbsp; </span>Reference renderings</a><br/>
+&nbsp;&nbsp;<a href="#imagingpipeline/coordinatessystems"  target="_self" class="level2"><span class="tocNumber">8.6&nbsp; </span>Coordinates systems</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#imagingpipeline/coordinatessystems/worldcoordinatessystem"  target="_self" class="level3"><span class="tocNumber">8.6.1&nbsp; </span>World coordinates system</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#imagingpipeline/coordinatessystems/cameracoordinatessystem"  target="_self" class="level3"><span class="tocNumber">8.6.2&nbsp; </span>Camera coordinates system</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#imagingpipeline/coordinatessystems/cubemapscoordinatessystem"  target="_self" class="level3"><span class="tocNumber">8.6.3&nbsp; </span>Cubemaps coordinates system</a><br/>
+<a href="#annex"  target="_self" class="level1"><span class="tocNumber">9&nbsp; </span>Annex</a><br/>
+&nbsp;&nbsp;<a href="#annex/specularcolor"  target="_self" class="level2"><span class="tocNumber">9.1&nbsp; </span>Specular color</a><br/>
+&nbsp;&nbsp;<a href="#annex/importancesamplingfortheibl"  target="_self" class="level2"><span class="tocNumber">9.2&nbsp; </span>Importance sampling for the IBL</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#annex/importancesamplingfortheibl/choosingimportantdirections"  target="_self" class="level3"><span class="tocNumber">9.2.1&nbsp; </span>Choosing important directions</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#annex/importancesamplingfortheibl/pre-filteredimportancesampling"  target="_self" class="level3"><span class="tocNumber">9.2.2&nbsp; </span>Pre-filtered importance sampling</a><br/>
+&nbsp;&nbsp;<a href="#annex/choosingimportantdirectionsforsamplingthebrdf"  target="_self" class="level2"><span class="tocNumber">9.3&nbsp; </span>Choosing important directions for sampling the BRDF</a><br/>
+&nbsp;&nbsp;<a href="#annex/hammersleysequence"  target="_self" class="level2"><span class="tocNumber">9.4&nbsp; </span>Hammersley sequence</a><br/>
+&nbsp;&nbsp;<a href="#annex/precomputinglforimage-basedlighting"  target="_self" class="level2"><span class="tocNumber">9.5&nbsp; </span>Precomputing L for image-based lighting</a><br/>
+&nbsp;&nbsp;<a href="#annex/sphericalharmonics"  target="_self" class="level2"><span class="tocNumber">9.6&nbsp; </span>Spherical Harmonics</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#annex/sphericalharmonics/basisfunctions"  target="_self" class="level3"><span class="tocNumber">9.6.1&nbsp; </span>Basis functions</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#annex/sphericalharmonics/decompositionandreconstruction"  target="_self" class="level3"><span class="tocNumber">9.6.2&nbsp; </span>Decomposition and reconstruction</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#annex/sphericalharmonics/decompositionof%5C(%5Cleft%5C)"  target="_self" class="level3"><span class="tocNumber">9.6.3&nbsp; </span>Decomposition of \(\left< cos \theta \right>\)</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#annex/sphericalharmonics/convolution"  target="_self" class="level3"><span class="tocNumber">9.6.4&nbsp; </span>Convolution</a><br/>
+&nbsp;&nbsp;<a href="#annex/samplevalidationsceneformitsuba"  target="_self" class="level2"><span class="tocNumber">9.7&nbsp; </span>Sample validation scene for Mitsuba</a><br/>
+&nbsp;&nbsp;<a href="#annex/lightassignmentwithfroxels"  target="_self" class="level2"><span class="tocNumber">9.8&nbsp; </span>Light assignment with froxels</a><br/>
+<a href="#revisions"  target="_self" class="level1"><span class="tocNumber">10&nbsp; </span>Revisions</a><br/>
+<a href="#bibliography"  target="_self" class="level1"><span class="tocNumber">11&nbsp; </span>Bibliography</a><br/>
+</p></div><a class="target" name="about">&nbsp;</a><a class="target" name="about">&nbsp;</a><a class="target" name="toc1">&nbsp;</a><h1>About</h1>
+<p>
+
+This document is part of the <a href="https://github.com/google/filament">Filament project</a>. To report errors in this document please use the <a href="https://github.com/google/filament/issues">project's issue tracker</a>.
+</p>
+<a class="target" name="authors">&nbsp;</a><a class="target" name="about/authors">&nbsp;</a><a class="target" name="toc1.1">&nbsp;</a><h2>Authors</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://twitter.com/darthmoosious">@darthmoosious</a></li></ul>
+</p>
+<a class="target" name="overview">&nbsp;</a><a class="target" name="overview">&nbsp;</a><a class="target" name="toc2">&nbsp;</a><h1>Overview</h1>
+<p>
+
+Filament is a physically based rendering (PBR) engine for Android. The goal of Filament is to offer a set of tools and APIs for Android developers that will enable them to create high quality 2D and 3D rendering with ease.
+</p><p>
+The goal of this document is to explain the equations and theory behind the material and lighting models used in Filament. This document is intended as a reference for contributors to Filament or developers interested in the inner workings of the engine. We will provide code snippets as needed to make the relationship between theory and practice as clear as possible.
+</p><p>
+This document is not intended as a design document. It focuses solely on algorithms and its content could be used to implement PBR in any engine. However, this document explains why we chose specific algorithms/models over others.
+</p><p>
+Unless noted otherwise, all the 3D renderings present in this document have been generated in-engine (prototype or production). Many of these 3D renderings were captured during the early stages of development of Filament and do not reflect the final quality.
+</p>
+<a class="target" name="principles">&nbsp;</a><a class="target" name="overview/principles">&nbsp;</a><a class="target" name="toc2.1">&nbsp;</a><h2>Principles</h2>
+<p>
+
+Real-time rendering is an active area of research and there is a large number of equations, algorithms and implementation to choose from for every single feature that needs to be implemented (the book <em class="asterisk">Rendering real-time shadows</em>, for instance, is a 400 pages summary of dozens of shadows rendering techniques). As such, we must first define our goals (or principles, to follow Brent Burley's seminal paper Physically-based shading at Disney [<a href="#citation-burley12" target="_self">Burley12</a>]) before we can make informed decisions.
+</p><p>
+<dl><dt>Real-time mobile performance</dt><dd><p>    Our primary goal is to design and implement a rendering system able to perform efficiently on mobile platforms. The primary target will be OpenGL ES 3.x class GPUs.
+</p></dd><dt>Quality</dt><dd><p>    Our rendering system will emphasize overall picture quality. We will however accept quality compromises to support low and medium performance GPUs.
+</p></dd><dt>Ease of use</dt><dd><p>    Artists need to be able to iterate often and quickly on their assets and our rendering system must allow them to do so intuitively. We must therefore provide parameters that are easy to understand (for instance, no specular power).
+</p><p>
+    We also understand that not all developers have the luxury to work with artists. The physically based approach of our system will allow developers to craft visually plausible materials without the need to understand the theory behind our implementation.
+</p><p>
+    For both artists and developers, our system will rely on as few parameters as possible to reduce trial and error and allow users to quickly master the material model.
+</p><p>
+    In addition, any combination of parameter values should lead to physically plausible results. Physically implausible materials must be hard to create.
+</p></dd><dt>Familiarity</dt><dd><p>    Our system should use physical units everywhere possible: distances in meters or centimeters, color temperatures in Kelvin, light units in lumens or candelas, etc.
+</p></dd><dt>Flexibility</dt><dd><p>    A physically based approach must not preclude non-realistic rendering. User interfaces for instance will need unlit materials.
+</p></dd><dt>Deployment size</dt><dd><p>    While not directly related to the content of this document, it bears emphasizing our desire to keep the rendering library as small as possible so any application can bundle it without increasing the binary to undesirable sizes.
+</p></dd></dl></p>
+<a class="target" name="physicallybasedrendering">&nbsp;</a><a class="target" name="overview/physicallybasedrendering">&nbsp;</a><a class="target" name="toc2.2">&nbsp;</a><h2>Physically based rendering</h2>
+<p>
+
+We chose to adopt PBR for its benefits from an artistic and production efficient standpoints, and because it is compatible with our goals.
+</p><p>
+Physically based rendering is a rendering method that provides a more accurate representation of materials and how they interact with light when compared to traditional real-time models. The separation of materials and lighting at the core of the PBR method makes it easier to create realistic assets that look accurate in all lighting conditions.
+</p>
+<a class="target" name="notation">&nbsp;</a><a class="target" name="notation">&nbsp;</a><a class="target" name="toc3">&nbsp;</a><h1>Notation</h1>
+<p>
+
+$$
+\newcommand{NoL}{n \cdot l}
+\newcommand{NoV}{n \cdot v}
+\newcommand{NoH}{n \cdot h}
+\newcommand{VoH}{v \cdot h}
+\newcommand{LoH}{l \cdot h}
+\newcommand{fNormal}{f_{0}}
+\newcommand{fDiffuse}{f_d}
+\newcommand{fSpecular}{f_r}
+\newcommand{fX}{f_x}
+\newcommand{aa}{\alpha^2}
+\newcommand{fGrazing}{f_{90}}
+\newcommand{schlick}{F_{Schlick}}
+\newcommand{nior}{n_{ior}}
+\newcommand{Ed}{E_d}
+\newcommand{Lt}{L_{\bot}}
+\newcommand{Lout}{L_{out}}
+\newcommand{cosTheta}{\left< \cos \theta \right> }
+$$
+</p><p>
+The equations found throughout this document use the symbols described in <a href="#table_symbols" target="_self">table&nbsp;1</a>.
+</p><p>
+<div class='table'>
+<a class="target" name="table_symbols">&nbsp;</a><table class="table longtable"><tr><th  style="text-align:center"> Symbol </th><th  style="text-align:left"> Definition </th></tr>
+<tr><td  style="text-align:center"> \(v\) </td><td  style="text-align:left"> View unit vector </td></tr>
+<tr><td  style="text-align:center"> \(l\) </td><td  style="text-align:left"> Incident light unit vector </td></tr>
+<tr><td  style="text-align:center"> \(n\) </td><td  style="text-align:left"> Surface normal unit vector </td></tr>
+<tr><td  style="text-align:center"> \(h\) </td><td  style="text-align:left"> Half unit vector between \(l\) and \(v\) </td></tr>
+<tr><td  style="text-align:center"> \(f\) </td><td  style="text-align:left"> BRDF </td></tr>
+<tr><td  style="text-align:center"> \(\fDiffuse\) </td><td  style="text-align:left"> Diffuse component of a BRDF </td></tr>
+<tr><td  style="text-align:center"> \(\fSpecular\) </td><td  style="text-align:left"> Specular component of a BRDF </td></tr>
+<tr><td  style="text-align:center"> \(\alpha\) </td><td  style="text-align:left"> Roughness, remapped from using input <code>perceptualRoughness</code> </td></tr>
+<tr><td  style="text-align:center"> \(\sigma\) </td><td  style="text-align:left"> Diffuse reflectance </td></tr>
+<tr><td  style="text-align:center"> \(\Omega\) </td><td  style="text-align:left"> Spherical domain </td></tr>
+<tr><td  style="text-align:center"> \(\fNormal\) </td><td  style="text-align:left"> Reflectance at normal incidence </td></tr>
+<tr><td  style="text-align:center"> \(\fGrazing\) </td><td  style="text-align:left"> Reflectance at grazing angle </td></tr>
+<tr><td  style="text-align:center"> \(\chi^+(a)\) </td><td  style="text-align:left"> Heaviside function (1 if \(a > 0\) and 0 otherwise) </td></tr>
+<tr><td  style="text-align:center"> \(n_{ior}\) </td><td  style="text-align:left"> Index of refraction (IOR) of an interface </td></tr>
+<tr><td  style="text-align:center"> \(\left< \NoL \right>\) </td><td  style="text-align:left"> Dot product clamped to [0..1] </td></tr>
+<tr><td  style="text-align:center"> \(\left< a \right>\) </td><td  style="text-align:left"> Saturated value (clamped to [0..1]) </td></tr>
+</table><center><div class="tablecaption"><b style="font-style:normal;">Table&nbsp;1:</b> Symbols definitions</div></center></div>
+</p>
+<a class="target" name="materialsystem">&nbsp;</a><a class="target" name="materialsystem">&nbsp;</a><a class="target" name="toc4">&nbsp;</a><h1>Material system</h1>
+<p>
+
+The sections below describe multiple material models to simplify the description of various surface features such as anisotropy or the clear coat layer. In practice however some of these models are condensed into a single one. For instance, the standard model, the clear coat model and the anisotropic model can be combined to form a single, more flexible and powerful model. Please refer to the <a href="./Materials.md.html">Materials documentation</a> to get a description of the material models as implemented in Filament.
+</p>
+<a class="target" name="standardmodel">&nbsp;</a><a class="target" name="materialsystem/standardmodel">&nbsp;</a><a class="target" name="toc4.1">&nbsp;</a><h2>Standard model</h2>
+<p>
+
+The goal of our model is to represent standard material appearances. A material model is described mathematically by a BSDF (Bidirectional Scattering Distribution Function), which is itself composed of two other functions: the BRDF (Bidirectional Reflectance Distribution Function) and the BTDF (Bidirectional Transmittance Function).
+</p><p>
+Since we aim to model commonly encountered surfaces, our standard material model will focus on the BRDF and ignore the BTDF, or approximate it greatly. Our standard model will therefore only be able to correctly mimic reflective, isotropic, dielectric or conductive surfaces with short mean free paths.
+</p><p>
+The BRDF describes the surface response of a standard material as a function made of two terms:
+</p><p>
+<ul>
+<li class="minus">A diffuse component, or \(f_d\)
+</li>
+<li class="minus">A specular component, or \(f_r\)</li></ul>
+</p><p>
+The relationship between a surface, the surface normal, incident light and these terms is shown in <a href="#figure_frfd" target="_self">figure&nbsp;1</a> (we ignore subsurface scattering for now):
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_frfd">&nbsp;</a><a href="../images/diagram_fr_fd.png" target="_blank"><img class="markdeep" src="../images/diagram_fr_fd.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;1:</b> Interaction of the light with a surface using BRDF model with a diffuse term \( f_d \) and a specular term \( f_r \)</span></center></div></center>
+</p><p>
+The complete surface response can be expressed as such:
+</p><p>
+$$\begin{equation}\label{brdf}
+f(v,l)=f_d(v,l)+f_r(v,l)
+\end{equation}$$
+</p><p>
+This equation characterizes the surface response for incident light from a single direction. The full rendering equation would require to integrate \(l\) over the entire hemisphere.
+</p><p>
+Commonly encountered surfaces are usually not made of a flat interface so we need a model that can characterize the interaction of light with an irregular interface.
+</p><p>
+A microfacet BRDF is a good physically plausible BRDF for that purpose. Such BRDF states that surfaces are not smooth at a micro level, but made of a large number of randomly aligned planar surface fragments, called microfacets. <a href="#figure_microfacetvsflat" target="_self">Figure&nbsp;2</a> shows the difference between a flat interface and an irregular interface at a micro level:
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_microfacetvsflat">&nbsp;</a><a href="../images/diagram_microfacet.png" target="_blank"><img class="markdeep" src="../images/diagram_microfacet.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;2:</b> Irregular interface as modeled by a microfacet model (left) and flat interface (right)</span></center></div></center>
+</p><p>
+Only the microfacets whose normal is oriented halfway between the light direction and the view direction will reflect visible light, as shown in <a href="#figure_microfacets" target="_self">figure&nbsp;3</a>.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_microfacets">&nbsp;</a><a href="../images/diagram_macrosurface.png" target="_blank"><img class="markdeep" src="../images/diagram_macrosurface.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;3:</b> Microfacets</span></center></div></center>
+</p><p>
+However, not all microfacets with a properly oriented normal will contribute reflected light as the BRDF takes into account masking and shadowing. This is illustrated in <a href="#figure_microfacetshadowing" target="_self">figure&nbsp;4</a>.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_microfacetshadowing">&nbsp;</a><a href="../images/diagram_shadowing_masking.png" target="_blank"><img class="markdeep" src="../images/diagram_shadowing_masking.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;4:</b> Masking and shadowing of microfacets</span></center></div></center>
+</p><p>
+A microfacet BRDF is heavily influenced by a <em class="underscore">roughness</em> parameter which describes how smooth (low roughness) or how rough (high roughness) a surface is at a micro level. The smoother the surface, the more facets are aligned and the more pronounced the reflected light is. The rougher the surface, the fewer facets are oriented towards the camera and incoming light is scattered away from the camera after reflection, giving a blurry aspect to the specular highlights.
+</p><p>
+<a href="#figure_roughness" target="_self">Figure&nbsp;5</a> shows surfaces of different roughness and how light interacts with them.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_roughness">&nbsp;</a><a href="../images/diagram_roughness.png" target="_blank"><img class="markdeep" src="../images/diagram_roughness.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;5:</b> Varying roughness (from left to right, rough to smooth) and the resulting BRDF specular component lobe</span></center></div></center>
+</p><p>
+<div class="admonition note"><div class="admonition-title"> About roughness</div>
+</p><p>
+    The roughness parameter as set by the user is called <code>perceptualRoughness</code> in the shader snippets throughout this document. The variable called <code>roughness</code> is the <code>perceptualRoughness</code> with a remapping explained in section <a href="#toc4.8" target="_self">4.8</a>.</div>
+</p><p>
+A microfacet model is described by the following equation (where x stands for the specular or diffuse component):
+</p><p>
+$$\begin{equation}
+\fX(v,l) = \frac{1}{| \NoV | | \NoL |}
+\int_\Omega D(m,\alpha) G(v,l,m) f_m(v,l,m) (v \cdot m) (l \cdot m) dm
+\end{equation}$$
+</p><p>
+The term \(D\) models the distribution of the microfacets (this term is also referred to as the NDF or Normal Distribution Function). This term plays a primordial role in the appearance of surfaces as shown in <a href="#figure_roughness" target="_self">figure&nbsp;5</a>.
+</p><p>
+The term \(G\) models the visibility (or occlusion or shadow-masking) of the microfacets.
+</p><p>
+Since this equation is valid for both the specular and diffuse components, the difference lies in the microfacet BRDF \(f_m\).
+</p><p>
+It is important to note that this equation is used to integrate over the hemisphere at a <em class="underscore">micro level</em>:
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_microlevel">&nbsp;</a><a href="../images/diagram_micro_vs_macro.png" target="_blank"><img class="markdeep" src="../images/diagram_micro_vs_macro.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;6:</b> Modeling the surface response at a single point requires an integration at the micro level</span></center></div></center>
+</p><p>
+The diagram above shows that at a macro level, the surfaces is considered flat. This helps simplify our equations by assuming that a shaded fragment lit from a single direction corresponds to a single point at the surface.
+</p><p>
+At a micro level however, the surface is not flat and we cannot assume a single ray of light anymore (we can however assume that the incident rays are parallel). Since the micro facets will scatter the light in different directions given a bundle of parallel incident rays, we must integrate the surface response over a hemisphere, noted m in the above diagram.
+</p><p>
+It is obviously not practical to compute the full integration over the microfacets hemisphere for each shaded fragment. We will therefore rely on approximations of the integration for both the specular and diffuse components.
+</p>
+<a class="target" name="dielectricsandconductors">&nbsp;</a><a class="target" name="materialsystem/dielectricsandconductors">&nbsp;</a><a class="target" name="toc4.2">&nbsp;</a><h2>Dielectrics and conductors</h2>
+<p>
+
+To better understand some of the equations and behaviors shown below, we must first clearly understand the difference between metallic (conductor) and non-metallic (dielectric) surfaces.
+</p><p>
+We saw earlier that when incident light hits a surface governed by a BRDF, the light is reflected as two separate components: the diffuse reflectance and the specular reflectance. The modelization of this behavior is straightforward as shown in <a href="#figure_bsdfbrdf" target="_self">figure&nbsp;7</a>.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_bsdfbrdf">&nbsp;</a><a href="../images/diagram_fr_fd.png" target="_blank"><img class="markdeep" src="../images/diagram_fr_fd.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;7:</b> Modelization of the BRDF part of a BSDF</span></center></div></center>
+</p><p>
+This modelization is a simplification of how the light actually interacts with the surface. In reality, part of the incident light will penetrate the surface, scatter inside, and exit the surface again as diffuse reflectance. This phenomenon is illustrated in <a href="#figure_diffusescattering" target="_self">figure&nbsp;8</a>.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_diffusescattering">&nbsp;</a><a href="../images/diagram_scattering.png" target="_blank"><img class="markdeep" src="../images/diagram_scattering.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;8:</b> Scattering of diffuse light</span></center></div></center>
+</p><p>
+Here lies the difference between conductors and dielectrics. There is no subsurface scattering occurring with purely metallic materials, which means there is no diffuse component (and we will see later that this has an influence on the perceived color of the specular component). Scattering happens in dielectrics, which means they have both specular and diffuse components.
+</p><p>
+To properly modelize the BRDF we must therefore distinguish between dielectrics and conductors (scattering not shown for clarity), as shown in <a href="#figure_dielectricconductor" target="_self">figure&nbsp;9</a>.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_dielectricconductor">&nbsp;</a><a href="../images/diagram_brdf_dielectric_conductor.png" target="_blank"><img class="markdeep" src="../images/diagram_brdf_dielectric_conductor.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;9:</b> BRDF modelization for dielectric and conductor surfaces</span></center></div></center>
+</p>
+<a class="target" name="energyconservation">&nbsp;</a><a class="target" name="materialsystem/energyconservation">&nbsp;</a><a class="target" name="toc4.3">&nbsp;</a><h2>Energy conservation</h2>
+<p>
+
+Energy conservation is one of the key components of a good BRDF for physically based rendering. An energy conservative BRDF states that the total amount of specular and diffuse reflectance energy is less than the total amount of incident energy. Without an energy conservative BRDF, artists must manually ensure that the light reflected off a surface is never more intense than the incident light.
+</p>
+<a class="target" name="specularbrdf">&nbsp;</a><a class="target" name="materialsystem/specularbrdf">&nbsp;</a><a class="target" name="toc4.4">&nbsp;</a><h2>Specular BRDF</h2>
+<p>
+
+For the specular term, \(f_r\) is a mirror BRDF that can be modeled with the Fresnel law, noted \(F\) in the Cook-Torrance approximation of the microfacet model integration:
+</p><p>
+$$\begin{equation}
+f_r(v,l) = \frac{D(h, \alpha) G(v, l, \alpha) F(v, h, f0)}{4(\NoV)(\NoL)}
+\end{equation}$$
+</p><p>
+Given our real-time constraints, we must use an approximation for the three terms \(D\), \(G\) and \(F\). [<a href="#citation-karis13a" target="_self">Karis13a</a>] has compiled a great list of formulations for these three terms that can be used with the Cook-Torrance specular BRDF. The sections that follow describe the equations we picked for these terms.
+</p>
+<a class="target" name="normaldistributionfunction(speculard)">&nbsp;</a><a class="target" name="materialsystem/specularbrdf/normaldistributionfunction(speculard)">&nbsp;</a><a class="target" name="toc4.4.1">&nbsp;</a><h3>Normal distribution function (specular D)</h3>
+<p>
+
+[<a href="#citation-burley12" target="_self">Burley12</a>] observed that long-tailed normal distribution functions (NDF) are a good fit for real-world surfaces. The GGX distribution described in [<a href="#citation-walter07" target="_self">Walter07</a>] is a distribution with long-tailed falloff and short peak in the highlights, with a simple formulation suitable for real-time implementations. It is also a popular model, equivalent to the Trowbridge-Reitz distribution, in modern physically based renderers.
+</p><p>
+$$\begin{equation}
+D_{GGX}(h,\alpha) = \frac{\aa}{\pi ( (\NoH)^2 (\aa - 1) + 1)^2}
+\end{equation}$$
+</p><p>
+The GLSL implementation of the NDF, shown in <a href="#listing_speculard" target="_self">listing&nbsp;1</a>, is simple and efficient.
+</p><a class="target" name="listing_speculard">&nbsp;</a><pre class="listing tilde"><code><span class="line"></span><span class="hljs-function"><span class="hljs-type">float</span> <span class="hljs-title">D_GGX</span><span class="hljs-params">(<span class="hljs-type">float</span> NoH, <span class="hljs-type">float</span> roughness)</span> </span>{
+<span class="line"></span>    <span class="hljs-type">float</span> a = NoH * roughness;
+<span class="line"></span>    <span class="hljs-type">float</span> k = roughness / (<span class="hljs-number">1.0</span> - NoH * NoH + a * a);
+<span class="line"></span>    <span class="hljs-keyword">return</span> k * k * (<span class="hljs-number">1.0</span> / PI);
+<span class="line"></span>}</code></pre><center><div class="listingcaption tilde"><b style="font-style:normal;">Listing&nbsp;1:</b> Implementation of the specular D term in GLSL</div></center>
+<p>
+
+We can improve this implementation by using half precision floats. This optimization requires changes to the original equation as there are two problems when computing \(1 - (\NoH)^2\) in half-floats. First, this computation suffers from floating point cancellation when \((\NoH)^2\) is close to 1 (highlights). Secondly \(\NoH\) does not have enough precision around 1.
+</p><p>
+The solution involves Lagrange's identity:
+</p><p>
+$$\begin{equation}
+| a \times b |^2 = |a|^2 |b|^2 - (a \cdot b)^2
+\end{equation}$$
+</p><p>
+Since both \(n\) and \(h\) are unit vectors, \(|n \times h|^2 = 1 - (\NoH)^2\). This allows us to compute \(1 - (\NoH)^2\) directly with half precision floats by using a simple cross product. <a href="#listing_speculardfp16" target="_self">Listing&nbsp;2</a> shows the final optimized implementation.
+</p><a class="target" name="listing_speculardfp16">&nbsp;</a><pre class="listing tilde"><code><span class="line"></span><span class="hljs-meta">#define MEDIUMP_FLT_MAX    65504.0</span>
+<span class="line"></span><span class="hljs-meta">#define saturateMediump(x) min(x, MEDIUMP_FLT_MAX)</span>
+<span class="line"></span>
+<span class="line"></span><span class="hljs-type">float</span> D_GGX(<span class="hljs-type">float</span> roughness, <span class="hljs-type">float</span> NoH, <span class="hljs-keyword">const</span> <span class="hljs-type">vec3</span> n, <span class="hljs-keyword">const</span> <span class="hljs-type">vec3</span> h) {
+<span class="line"></span>    <span class="hljs-type">vec3</span> NxH = <span class="hljs-built_in">cross</span>(n, h);
+<span class="line"></span>    <span class="hljs-type">float</span> a = NoH * roughness;
+<span class="line"></span>    <span class="hljs-type">float</span> k = roughness / (<span class="hljs-built_in">dot</span>(NxH, NxH) + a * a);
+<span class="line"></span>    <span class="hljs-type">float</span> d = k * k * (<span class="hljs-number">1.0</span> / PI);
+<span class="line"></span>    <span class="hljs-keyword">return</span> saturateMediump(d);
+<span class="line"></span>}</code></pre><center><div class="listingcaption tilde"><b style="font-style:normal;">Listing&nbsp;2:</b> Implementation of the specular D term in GLSL optimized for fp16</div></center>
+<a class="target" name="geometricshadowing(specularg)">&nbsp;</a><a class="target" name="materialsystem/specularbrdf/geometricshadowing(specularg)">&nbsp;</a><a class="target" name="toc4.4.2">&nbsp;</a><h3>Geometric shadowing (specular G)</h3>
+<p>
+
+Eric Heitz showed in [<a href="#citation-heitz14" target="_self">Heitz14</a>] that the Smith geometric shadowing function is the correct and exact \(G\) term to use. The Smith formulation is the following:
+</p><p>
+$$\begin{equation}
+G(v,l,\alpha) = G_1(l,\alpha) G_1(v,\alpha)
+\end{equation}$$
+</p><p>
+\(G_1\) can in turn follow several models, and is commonly set to the GGX formulation:
+</p><p>
+$$\begin{equation}
+G_1(v,\alpha) = G_{GGX}(v,\alpha) = \frac{2 (\NoV)}{\NoV + \sqrt{\aa + (1 - \aa) (\NoV)^2}}
+\end{equation}$$
+</p><p>
+The full Smith-GGX formulation thus becomes:
+</p><p>
+$$\begin{equation}
+G(v,l,\alpha) = \frac{2 (\NoL)}{\NoL + \sqrt{\aa + (1 - \aa) (\NoL)^2}} \frac{2 (\NoV)}{\NoV + \sqrt{\aa + (1 - \aa) (\NoV)^2}}
+\end{equation}$$
+</p><p>
+We can observe that the dividends \(2 (\NoL)\) and \(2 (n \cdot v)\) allow us to simplify the original function \(f_r\) by introducing a visibility function \(V\):
+</p><p>
+$$\begin{equation}
+f_r(v,l) = D(h, \alpha) V(v, l, \alpha) F(v, h, f_0)
+\end{equation}$$
+</p><p>
+Where:
+</p><p>
+$$\begin{equation}
+V(v,l,\alpha) = \frac{G(v, l, \alpha)}{4 (\NoV) (\NoL)} = V_1(l,\alpha) V_1(v,\alpha)
+\end{equation}$$
+</p><p>
+And:
+</p><p>
+$$\begin{equation}
+V_1(v,\alpha) = \frac{1}{\NoV + \sqrt{\aa + (1 - \aa) (\NoV)^2}}
+\end{equation}$$
+</p><p>
+Heitz notes however that taking the height of the microfacets into account to correlate masking and shadowing leads to more accurate results. He defines the height-correlated Smith function thusly:
+</p><p>
+$$\begin{equation}
+G(v,l,h,\alpha) = \frac{\chi^+(\VoH) \chi^+(\LoH)}{1 + \Lambda(v) + \Lambda(l)}
+\end{equation}$$
+</p><p>
+$$\begin{equation}
+\Lambda(m) = \frac{-1 + \sqrt{1 + \aa tan^2(\theta_m)}}{2} = \frac{-1 + \sqrt{1 + \aa \frac{(1 - cos^2(\theta_m))}{cos^2(\theta_m)}}}{2}
+\end{equation}$$
+</p><p>
+Replacing \(cos(\theta_m)\) by \(\NoV\), we obtain:
+</p><p>
+$$\begin{equation}
+\Lambda(v) = \frac{1}{2} \left( \frac{\sqrt{\aa + (1 - \aa)(\NoV)^2}}{\NoV} - 1 \right)
+\end{equation}$$
+</p><p>
+From which we can derive the visibility function:
+</p><p>
+$$\begin{equation}
+V(v,l,\alpha) = \frac{0.5}{\NoL \sqrt{(\NoV)^2 (1 - \aa) + \aa} + \NoV \sqrt{(\NoL)^2 (1 - \aa) + \aa}}
+\end{equation}$$
+</p><p>
+The GLSL implementation of the visibility term, shown in <a href="#listing_specularv" target="_self">listing&nbsp;3</a>, is a bit more expensive than we would like since it requires two <code>sqrt</code> operations.
+</p><a class="target" name="listing_specularv">&nbsp;</a><pre class="listing tilde"><code><span class="line"></span><span class="hljs-function"><span class="hljs-type">float</span> <span class="hljs-title">V_SmithGGXCorrelated</span><span class="hljs-params">(<span class="hljs-type">float</span> NoV, <span class="hljs-type">float</span> NoL, <span class="hljs-type">float</span> roughness)</span> </span>{
+<span class="line"></span>    <span class="hljs-type">float</span> a2 = roughness * roughness;
+<span class="line"></span>    <span class="hljs-type">float</span> GGXV = NoL * <span class="hljs-built_in">sqrt</span>(NoV * NoV * (<span class="hljs-number">1.0</span> - a2) + a2);
+<span class="line"></span>    <span class="hljs-type">float</span> GGXL = NoV * <span class="hljs-built_in">sqrt</span>(NoL * NoL * (<span class="hljs-number">1.0</span> - a2) + a2);
+<span class="line"></span>    <span class="hljs-keyword">return</span> <span class="hljs-number">0.5</span> / (GGXV + GGXL);
+<span class="line"></span>}</code></pre><center><div class="listingcaption tilde"><b style="font-style:normal;">Listing&nbsp;3:</b> Implementation of the specular V term in GLSL</div></center>
+<p>
+
+We can optimize this visibility function by using an approximation after noticing that all the terms under the square roots are squares and that all the terms are in the \([0..1]\) range:
+</p><p>
+$$\begin{equation}
+V(v,l,\alpha) = \frac{0.5}{\NoL (\NoV (1 - \alpha) + \alpha) + \NoV (\NoL (1 - \alpha) + \alpha)}
+\end{equation}$$
+</p><p>
+This approximation is mathematically wrong but saves two square root operations and is good enough for real-time mobile applications, as shown in <a href="#listing_approximatedspecularv" target="_self">listing&nbsp;4</a>.
+</p><a class="target" name="listing_approximatedspecularv">&nbsp;</a><pre class="listing tilde"><code><span class="line"></span><span class="hljs-function"><span class="hljs-type">float</span> <span class="hljs-title">V_SmithGGXCorrelatedFast</span><span class="hljs-params">(<span class="hljs-type">float</span> NoV, <span class="hljs-type">float</span> NoL, <span class="hljs-type">float</span> roughness)</span> </span>{
+<span class="line"></span>    <span class="hljs-type">float</span> a = roughness;
+<span class="line"></span>    <span class="hljs-type">float</span> GGXV = NoL * (NoV * (<span class="hljs-number">1.0</span> - a) + a);
+<span class="line"></span>    <span class="hljs-type">float</span> GGXL = NoV * (NoL * (<span class="hljs-number">1.0</span> - a) + a);
+<span class="line"></span>    <span class="hljs-keyword">return</span> <span class="hljs-number">0.5</span> / (GGXV + GGXL);
+<span class="line"></span>}</code></pre><center><div class="listingcaption tilde"><b style="font-style:normal;">Listing&nbsp;4:</b> Implementation of the approximated specular V term in GLSL</div></center>
+<p>
+
+[<a href="#citation-hammon17" target="_self">Hammon17</a>] proposes the same approximation based on the same observation that the square root can be removed. It does so by rewriting the expressions as <em class="underscore">lerps</em>:
+</p><p>
+$$\begin{equation}
+V(v,l,\alpha) = \frac{0.5}{lerp(2 (\NoL) (\NoV), \NoL + \NoV, \alpha)}
+\end{equation}$$
+</p>
+<a class="target" name="fresnel(specularf)">&nbsp;</a><a class="target" name="materialsystem/specularbrdf/fresnel(specularf)">&nbsp;</a><a class="target" name="toc4.4.3">&nbsp;</a><h3>Fresnel (specular F)</h3>
+<p>
+
+The Fresnel effect plays an important role in the appearance of physically based materials. This effect models the fact that the amount of light the viewer sees reflected from a surface depends on the viewing angle. Large bodies of water are a perfect way to experience this phenomenon, as shown in <a href="#figure_fresnellake" target="_self">figure&nbsp;10</a>. When looking at the water straight down (at normal incidence) you can see through the water. However, when looking further out in the distance (at grazing angle, where perceived light rays are getting parallel to the surface), you will see the specular reflections on the water become more intense.
+</p><p>
+The amount of light reflected depends not only on the viewing angle, but also on the index of refraction (IOR) of the material. At normal incidence (perpendicular to the surface, or 0&deg; angle), the amount of light reflected back is noted \(\fNormal\) and can be derived from the IOR as we will see in section <a href="#toc4.8.3.2" target="_self">4.8.3.2</a>. The amount of light reflected back at grazing angle is noted \(\fGrazing\) and approaches 100% for smooth materials.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_fresnellake">&nbsp;</a><a href="../images/photo_fresnel_lake.jpg" target="_blank"><img class="markdeep" src="../images/photo_fresnel_lake.jpg" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;10:</b> The Fresnel effect is particularly evident on large bodies of water</span></center></div></center>
+</p><p>
+More formally, the Fresnel term defines how light reflects and refracts at the interface between two different media, or the ratio of reflected and transmitted energy. [<a href="#citation-schlick94" target="_self">Schlick94</a>] describes an inexpensive approximation of the Fresnel term for the Cook-Torrance specular BRDF:
+</p><p>
+$$\begin{equation}
+F_{Schlick}(v,h,\fNormal,\fGrazing) = \fNormal + (\fGrazing - \fNormal)(1 - \VoH)^5
+\end{equation}$$
+</p><p>
+The constant \(\fNormal\) represents the specular reflectance at normal incidence and is achromatic for dielectrics, and chromatic for metals. The actual value depends on the index of refraction of the interface. The GLSL implementation of this term requires the use of a <code>pow</code>, as shown in <a href="#listing_specularf" target="_self">listing&nbsp;5</a>, which can be replaced by a few multiplications.
+</p><a class="target" name="listing_specularf">&nbsp;</a><pre class="listing tilde"><code><span class="line"></span><span class="hljs-type">vec3</span> F_Schlick(<span class="hljs-type">float</span> u, <span class="hljs-type">vec3</span> f0, <span class="hljs-type">float</span> f90) {
+<span class="line"></span>    <span class="hljs-keyword">return</span> f0 + (<span class="hljs-type">vec3</span>(f90) - f0) * <span class="hljs-built_in">pow</span>(<span class="hljs-number">1.0</span> - u, <span class="hljs-number">5.0</span>);
+<span class="line"></span>}</code></pre><center><div class="listingcaption tilde"><b style="font-style:normal;">Listing&nbsp;5:</b> Implementation of the specular F term in GLSL</div></center>
+<p>
+
+This Fresnel function can be seen as interpolating between the incident specular reflectance and the reflectance at grazing angles, represented here by \(\fGrazing\). Observation of real world materials show that both dielectrics and conductors exhibit achromatic specular reflectance at grazing angles and that the Fresnel reflectance is 1.0 at 90&deg;. A more correct \(\fGrazing\) is discussed in section <a href="#toc5.6.2" target="_self">5.6.2</a>.
+</p><p>
+Using \(\fGrazing\) set to 1, the Schlick approximation for the Fresnel term can be optimized for scalar operations by refactoring the code slightly. The result is shown in <a href="#listing_scalarspecularf" target="_self">listing&nbsp;6</a>.
+</p><a class="target" name="listing_scalarspecularf">&nbsp;</a><pre class="listing tilde"><code><span class="line"></span><span class="hljs-type">vec3</span> F_Schlick(<span class="hljs-type">float</span> u, <span class="hljs-type">vec3</span> f0) {
+<span class="line"></span>    <span class="hljs-type">float</span> f = <span class="hljs-built_in">pow</span>(<span class="hljs-number">1.0</span> - u, <span class="hljs-number">5.0</span>);
+<span class="line"></span>    <span class="hljs-keyword">return</span> f + f0 * (<span class="hljs-number">1.0</span> - f);
+<span class="line"></span>}</code></pre><center><div class="listingcaption tilde"><b style="font-style:normal;">Listing&nbsp;6:</b> Scalar optimization of the specular F term in GLSL</div></center>
+<a class="target" name="diffusebrdf">&nbsp;</a><a class="target" name="materialsystem/diffusebrdf">&nbsp;</a><a class="target" name="toc4.5">&nbsp;</a><h2>Diffuse BRDF</h2>
+<p>
+
+In the diffuse term, \(f_m\) is a Lambertian function and the diffuse term of the BRDF becomes:
+</p><p>
+$$\begin{equation}
+\fDiffuse(v,l) = \frac{\sigma}{\pi} \frac{1}{| \NoV | | \NoL |}
+\int_\Omega D(m,\alpha) G(v,l,m) (v \cdot m) (l \cdot m) dm
+\end{equation}$$
+</p><p>
+Our implementation will instead use a simple Lambertian BRDF that assumes a uniform diffuse response over the microfacets hemisphere:
+</p><p>
+$$\begin{equation}
+\fDiffuse(v,l) = \frac{\sigma}{\pi}
+\end{equation}$$
+</p><p>
+In practice, the diffuse reflectance \(\sigma\) is multiplied later, as shown in <a href="#listing_diffusebrdf" target="_self">listing&nbsp;8</a>.
+</p><a class="target" name="listing_diffusebrdf">&nbsp;</a><pre class="listing tilde"><code><span class="line"></span><span class="hljs-function"><span class="hljs-built_in">float</span> <span class="hljs-title">Fd_Lambert</span>()</span> {
+<span class="line"></span>    <span class="hljs-keyword">return</span> <span class="hljs-number">1.0</span> / PI;
+<span class="line"></span>}
+<span class="line"></span>
+<span class="line"></span>vec3 Fd = diffuseColor * Fd_Lambert();</code></pre><center><div class="listingcaption tilde"><b style="font-style:normal;">Listing&nbsp;7:</b> Implementation of the diffuse Lambertian BRDF in GLSL</div></center>
+<p>
+
+The Lambertian BRDF is obviously extremely efficient and delivers results close enough to more complex models.
+</p><p>
+However, the diffuse part would ideally be coherent with the specular term and take into account the surface roughness. Both the Disney diffuse BRDF [<a href="#citation-burley12" target="_self">Burley12</a>] and Oren-Nayar model [<a href="#citation-oren94" target="_self">Oren94</a>] take the roughness into account and create some retro-reflection at grazing angles. Given our constraints we decided that the extra runtime cost does not justify the slight increase in quality. This sophisticated diffuse model also renders image-based and spherical harmonics more difficult to express and implement.
+</p><p>
+For completeness, the Disney diffuse BRDF expressed in [<a href="#citation-burley12" target="_self">Burley12</a>] is the following:
+</p><p>
+$$\begin{equation}
+\fDiffuse(v,l) = \frac{\sigma}{\pi} \schlick(n,l,1,\fGrazing) \schlick(n,v,1,\fGrazing)
+\end{equation}$$
+</p><p>
+Where:
+</p><p>
+$$\begin{equation}
+\fGrazing=0.5 + 2 \cdot \alpha cos^2(\theta_d)
+\end{equation}$$
+</p><a class="target" name="listing_diffusebrdf">&nbsp;</a><pre class="listing tilde"><code><span class="line"></span><span class="hljs-type">float</span> <span class="hljs-title function_">F_Schlick</span><span class="hljs-params">(<span class="hljs-type">float</span> u, <span class="hljs-type">float</span> f0, <span class="hljs-type">float</span> f90)</span> {
+<span class="line"></span>    <span class="hljs-keyword">return</span> f0 + (f90 - f0) * pow(<span class="hljs-number">1.0</span> - u, <span class="hljs-number">5.0</span>);
+<span class="line"></span>}
+<span class="line"></span>
+<span class="line"></span><span class="hljs-type">float</span> <span class="hljs-title function_">Fd_Burley</span><span class="hljs-params">(<span class="hljs-type">float</span> NoV, <span class="hljs-type">float</span> NoL, <span class="hljs-type">float</span> LoH, <span class="hljs-type">float</span> roughness)</span> {
+<span class="line"></span>    <span class="hljs-type">float</span> <span class="hljs-variable">f90</span> <span class="hljs-operator">=</span> <span class="hljs-number">0.5</span> + <span class="hljs-number">2.0</span> * roughness * LoH * LoH;
+<span class="line"></span>    <span class="hljs-type">float</span> <span class="hljs-variable">lightScatter</span> <span class="hljs-operator">=</span> F_Schlick(NoL, <span class="hljs-number">1.0</span>, f90);
+<span class="line"></span>    <span class="hljs-type">float</span> <span class="hljs-variable">viewScatter</span> <span class="hljs-operator">=</span> F_Schlick(NoV, <span class="hljs-number">1.0</span>, f90);
+<span class="line"></span>    <span class="hljs-keyword">return</span> lightScatter * viewScatter * (<span class="hljs-number">1.0</span> / PI);
+<span class="line"></span>}</code></pre><center><div class="listingcaption tilde"><b style="font-style:normal;">Listing&nbsp;8:</b> Implementation of the diffuse Disney BRDF in GLSL</div></center>
+<p>
+
+<a href="#figure_lambert_vs_disney" target="_self">Figure&nbsp;11</a> shows a comparison between a simple Lambertian diffuse BRDF and the higher quality Disney diffuse BRDF, using a fully rough dielectric material. For comparison purposes, the right sphere was mirrored. The surface response is very similar with both BRDFs but the Disney one exhibits some nice retro-reflections at grazing angles (look closely at the left edge of the spheres).
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_lambert_vs_disney">&nbsp;</a><a href="../images/diagram_lambert_vs_disney.png" target="_blank"><img class="markdeep" src="../images/diagram_lambert_vs_disney.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;11:</b> Comparison between the Lambertian diffuse BRDF (left) and the Disney diffuse BRDF (right)</span></center></div></center>
+</p><p>
+We could allow artists/developers to choose the Disney diffuse BRDF depending on the quality they desire and the performance of the target device. It is important to note however that the Disney diffuse BRDF is not energy conserving as expressed here.
+</p>
+<a class="target" name="standardmodelsummary">&nbsp;</a><a class="target" name="materialsystem/standardmodelsummary">&nbsp;</a><a class="target" name="toc4.6">&nbsp;</a><h2>Standard model summary</h2>
+<p>
+
+<strong class="asterisk">Specular term</strong>: a Cook-Torrance specular microfacet model, with a GGX normal distribution function, a Smith-GGX height-correlated visibility function, and a Schlick Fresnel function.
+</p><p>
+<strong class="asterisk">Diffuse term</strong>: a Lambertian diffuse model.
+</p><p>
+The full GLSL implementation of the standard model is shown in <a href="#listing_glslbrdf" target="_self">listing&nbsp;9</a>.
+</p><a class="target" name="listing_glslbrdf">&nbsp;</a><pre class="listing tilde"><code><span class="line"></span><span class="hljs-type">float</span> <span class="hljs-title function_">D_GGX</span><span class="hljs-params">(<span class="hljs-type">float</span> NoH, <span class="hljs-type">float</span> a)</span> {
+<span class="line"></span>    <span class="hljs-type">float</span> <span class="hljs-variable">a2</span> <span class="hljs-operator">=</span> a * a;
+<span class="line"></span>    <span class="hljs-type">float</span> <span class="hljs-variable">f</span> <span class="hljs-operator">=</span> (NoH * a2 - NoH) * NoH + <span class="hljs-number">1.0</span>;
+<span class="line"></span>    <span class="hljs-keyword">return</span> a2 / (PI * f * f);
+<span class="line"></span>}
+<span class="line"></span>
+<span class="line"></span>vec3 <span class="hljs-title function_">F_Schlick</span><span class="hljs-params">(<span class="hljs-type">float</span> u, vec3 f0)</span> {
+<span class="line"></span>    <span class="hljs-keyword">return</span> f0 + (vec3(<span class="hljs-number">1.0</span>) - f0) * pow(<span class="hljs-number">1.0</span> - u, <span class="hljs-number">5.0</span>);
+<span class="line"></span>}
+<span class="line"></span>
+<span class="line"></span><span class="hljs-type">float</span> <span class="hljs-title function_">V_SmithGGXCorrelated</span><span class="hljs-params">(<span class="hljs-type">float</span> NoV, <span class="hljs-type">float</span> NoL, <span class="hljs-type">float</span> a)</span> {
+<span class="line"></span>    <span class="hljs-type">float</span> <span class="hljs-variable">a2</span> <span class="hljs-operator">=</span> a * a;
+<span class="line"></span>    <span class="hljs-type">float</span> <span class="hljs-variable">GGXL</span> <span class="hljs-operator">=</span> NoV * sqrt((-NoL * a2 + NoL) * NoL + a2);
+<span class="line"></span>    <span class="hljs-type">float</span> <span class="hljs-variable">GGXV</span> <span class="hljs-operator">=</span> NoL * sqrt((-NoV * a2 + NoV) * NoV + a2);
+<span class="line"></span>    <span class="hljs-keyword">return</span> <span class="hljs-number">0.5</span> / (GGXV + GGXL);
+<span class="line"></span>}
+<span class="line"></span>
+<span class="line"></span><span class="hljs-type">float</span> <span class="hljs-title function_">Fd_Lambert</span><span class="hljs-params">()</span> {
+<span class="line"></span>    <span class="hljs-keyword">return</span> <span class="hljs-number">1.0</span> / PI;
+<span class="line"></span>}
+<span class="line"></span>
+<span class="line"></span><span class="hljs-keyword">void</span> <span class="hljs-title function_">BRDF</span><span class="hljs-params">(...)</span> {
+<span class="line"></span>    <span class="hljs-type">vec3</span> <span class="hljs-variable">h</span> <span class="hljs-operator">=</span> normalize(v + l);
+<span class="line"></span>
+<span class="line"></span>    <span class="hljs-type">float</span> <span class="hljs-variable">NoV</span> <span class="hljs-operator">=</span> abs(dot(n, v)) + <span class="hljs-number">1e-5</span>;
+<span class="line"></span>    <span class="hljs-type">float</span> <span class="hljs-variable">NoL</span> <span class="hljs-operator">=</span> clamp(dot(n, l), <span class="hljs-number">0.0</span>, <span class="hljs-number">1.0</span>);
+<span class="line"></span>    <span class="hljs-type">float</span> <span class="hljs-variable">NoH</span> <span class="hljs-operator">=</span> clamp(dot(n, h), <span class="hljs-number">0.0</span>, <span class="hljs-number">1.0</span>);
+<span class="line"></span>    <span class="hljs-type">float</span> <span class="hljs-variable">LoH</span> <span class="hljs-operator">=</span> clamp(dot(l, h), <span class="hljs-number">0.0</span>, <span class="hljs-number">1.0</span>);
+<span class="line"></span>
+<span class="line"></span>    <span class="hljs-comment">// perceptually linear roughness to roughness (see parameterization)</span>
+<span class="line"></span>    <span class="hljs-type">float</span> <span class="hljs-variable">roughness</span> <span class="hljs-operator">=</span> perceptualRoughness * perceptualRoughness;
+<span class="line"></span>
+<span class="line"></span>    <span class="hljs-type">float</span> <span class="hljs-variable">D</span> <span class="hljs-operator">=</span> D_GGX(NoH, roughness);
+<span class="line"></span>    <span class="hljs-type">vec3</span>  <span class="hljs-variable">F</span> <span class="hljs-operator">=</span> F_Schlick(LoH, f0);
+<span class="line"></span>    <span class="hljs-type">float</span> <span class="hljs-variable">V</span> <span class="hljs-operator">=</span> V_SmithGGXCorrelated(NoV, NoL, roughness);
+<span class="line"></span>
+<span class="line"></span>    <span class="hljs-comment">// specular BRDF</span>
+<span class="line"></span>    <span class="hljs-type">vec3</span> <span class="hljs-variable">Fr</span> <span class="hljs-operator">=</span> (D * V) * F;
+<span class="line"></span>
+<span class="line"></span>    <span class="hljs-comment">// diffuse BRDF</span>
+<span class="line"></span>    <span class="hljs-type">vec3</span> <span class="hljs-variable">Fd</span> <span class="hljs-operator">=</span> diffuseColor * Fd_Lambert();
+<span class="line"></span>
+<span class="line"></span>    <span class="hljs-comment">// apply lighting...</span>
+<span class="line"></span>}</code></pre><center><div class="listingcaption tilde"><b style="font-style:normal;">Listing&nbsp;9:</b> Evaluation of the BRDF in GLSL</div></center>
+<a class="target" name="improvingthebrdfs">&nbsp;</a><a class="target" name="materialsystem/improvingthebrdfs">&nbsp;</a><a class="target" name="toc4.7">&nbsp;</a><h2>Improving the BRDFs</h2>
+<p>
+
+We mentioned in section <a href="#toc4.3" target="_self">4.3</a> that energy conservation is one of the key components of a good BRDF. Unfortunately the BRDFs explored previously suffer from two problems that we will examine below.
+</p>
+<a class="target" name="energygainindiffusereflectance">&nbsp;</a><a class="target" name="materialsystem/improvingthebrdfs/energygainindiffusereflectance">&nbsp;</a><a class="target" name="toc4.7.1">&nbsp;</a><h3>Energy gain in diffuse reflectance</h3>
+<p>
+
+The Lambert diffuse BRDF does not account for the light that reflects at the surface and that is therefore not able to participate in the diffuse scattering event.
+</p><p>
+[TODO: talk about the issue with fr+fd]
+</p>
+<a class="target" name="energylossinspecularreflectance">&nbsp;</a><a class="target" name="materialsystem/improvingthebrdfs/energylossinspecularreflectance">&nbsp;</a><a class="target" name="toc4.7.2">&nbsp;</a><h3>Energy loss in specular reflectance</h3>
+<p>
+
+The Cook-Torrance BRDF we presented earlier attempts to model several events at the microfacet level but does so by accounting for a single bounce of light. This approximation can cause a loss of energy at high roughness, the surface is not energy preserving. <a href="#figure_singlevsmultibounce" target="_self">Figure&nbsp;12</a> shows why this loss of energy occurs. In the single bounce (or single scattering) model, a ray of light hitting the surface can be reflected back onto another microfacet and thus be discarded because of the masking and shadowing term. If we however account for multiple bounces (multiscattering), the same ray of light might escape the microfacet field and be reflected back towards the viewer.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_singlevsmultibounce">&nbsp;</a><a href="../images/diagram_single_vs_multi_scatter.png" target="_blank"><img class="markdeep" src="../images/diagram_single_vs_multi_scatter.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;12:</b> Single scattering (left) vs multiscattering</span></center></div></center>
+</p><p>
+Based on this simple explanation, we can intuitively deduce that the rougher a surface is, the higher the chances are that energy gets lost because of the failure to account for multiple scattering events. This loss of energy appears to darken rough materials. Metallic surfaces are particularly affected because all of their reflectance is specular. This darkening effect is illustrated in <a href="#figure_metallicroughenergyloss" target="_self">figure&nbsp;13</a>. With multiscattering, energy preservation can be achieved, as shown in <a href="#figure_metallicroughenergypreservation" target="_self">figure&nbsp;14</a>.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_metallicroughenergyloss">&nbsp;</a><a href="../images/material_metallic_energy_loss.png" target="_blank"><img class="markdeep" src="../images/material_metallic_energy_loss.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;13:</b> Darkening increases with roughness due to single scattering</span></center></div></center>
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_metallicroughenergypreservation">&nbsp;</a><a href="../images/material_metallic_energy_preservation.png" target="_blank"><img class="markdeep" src="../images/material_metallic_energy_preservation.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;14:</b> Energy preservation with multiscattering</span></center></div></center>
+</p><p>
+We can use a white furnace, a uniform lighting environment set to pure white, to validate the energy preservation property of a BRDF. When energy preservation is achieved, a purely reflective metallic surface (\(\fNormal = 1\)) should be indistinguishable from the background, no matter the roughness of said surface. <a href="#figure_whitefurnaceloss" target="_self">Figure&nbsp;15</a> shows what such a surface looks like with the specular BRDF presented in the previous sections. The loss of energy as the roughness increases is obvious. In contrast, <a href="#figure_whitefurnacepreservation" target="_self">figure&nbsp;16</a> shows that accounting for multiscattering events addresses the energy loss.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_whitefurnaceloss">&nbsp;</a><a href="../images/material_furnace_energy_loss.png" target="_blank"><img class="markdeep" src="../images/material_furnace_energy_loss.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;15:</b> Darkening increases with roughness due to single scattering</span></center></div></center>
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_whitefurnacepreservation">&nbsp;</a><a href="../images/material_furnace_energy_preservation.png" target="_blank"><img class="markdeep" src="../images/material_furnace_energy_preservation.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;16:</b> Energy preservation with multiscattering</span></center></div></center>
+</p><p>
+Multiple-scattering microfacet BRDFs are discussed in depth in [<a href="#citation-heitz16" target="_self">Heitz16</a>]. Unfortunately this paper only presents a stochastic evaluation of the multiscattering BRDF. This solution is therefore not suitable for real-time rendering. Kulla and Conty present a different approach in [<a href="#citation-kulla17" target="_self">Kulla17</a>]. Their idea is to add an energy compensation term as an additional BRDF lobe shown in equation \(\ref{energyCompensationLobe}\):
+</p><p>
+$$\begin{equation}\label{energyCompensationLobe}
+f_{ms}(l,v) = \frac{(1 - E(l)) (1 - E(v)) F_{avg}^2 E_{avg}}{\pi (1 - E_{avg}) (1 - F_{avg}(1 - E_{avg}))}
+\end{equation}$$
+</p><p>
+Where \(E\) is the directional albedo of the specular BRDF \(f_r\), with \(\fNormal\) set to 1:
+</p><p>
+$$\begin{equation}
+E(l) = \int_{\Omega} f(l,v) (\NoV) dv
+\end{equation}$$
+</p><p>
+The term \(E_{avg}\) is the cosine-weighted average of \(E\):
+</p><p>
+$$\begin{equation}
+E_{avg} = 2 \int_0^1 E(\mu) \mu d\mu
+\end{equation}$$
+</p><p>
+Similarly, \(F_{avg}\) is the cosine-weighted average of the Fresnel term:
+</p><p>
+$$\begin{equation}
+F_{avg} = 2 \int_0^1 F(\mu) \mu d\mu
+\end{equation}$$
+</p><p>
+Both terms \(E\) and \(E_{avg}\) can be precomputed and stored in lookup tables. while \(F_{avg}\) can be greatly simplified when the Schlick approximation is used:
+</p><p>
+$$\begin{equation}\label{averageFresnel}
+F_{avg} = \frac{1 + 20 \fNormal}{21}
+\end{equation}$$
+</p><p>
+This new lobe is combined with the original single scattering lobe, previously noted \(f_r\):
+</p><p>
+$$\begin{equation}
+f_{r}(l,v) = f_{ss}(l,v) + f_{ms}(l,v)
+\end{equation}$$
+</p><p>
+In [<a href="#citation-lagarde18" target="_self">Lagarde18</a>], with credit to Emmanuel Turquin, Lagarde and Golubev make the observation that equation \(\ref{averageFresnel}\) can be simplified to \(\fNormal\). They also propose to apply energy compensation by adding a scaled GGX specular lobe:
+</p><p>
+$$\begin{equation}\label{energyCompensation}
+f_{ms}(l,v) = \fNormal \frac{1 - E(l)}{E(l)} f_{ss}(l,v)
+\end{equation}$$
+</p><p>
+The key insight is that \(E(l)\) can not only be precomputed but also shared with image-based lighting pre-integration. The multiscattering energy compensation formula thus becomes:
+</p><p>
+$$\begin{equation}\label{scaledEnergyCompensationLobe}
+f_r(l,v) = f_{ss}(l,v) + \fNormal \left( \frac{1}{r} - 1 \right) f_{ss}(l,v)
+\end{equation}$$
+</p><p>
+Where \(r\) is defined as:
+</p><p>
+$$\begin{equation}
+r = \int_{\Omega} D(l,v) V(l,v) \left< \NoL \right> dl
+\end{equation}$$
+</p><p>
+We can implement specular energy compensation at a negligible cost if we store \(r\) in the DFG lookup table presented in section <a href="#toc5.3" target="_self">5.3</a>. <a href="#listing_energycompensationimpl" target="_self">Listing&nbsp;10</a> shows that the implementation is a direct conversion of equation \(\ref{scaledEnergyCompensationLobe}\).
+</p><a class="target" name="listing_energycompensationimpl">&nbsp;</a><pre class="listing tilde"><code><span class="line"></span><span class="hljs-symbol">vec3</span> energyCompensation = <span class="hljs-number">1</span>.<span class="hljs-number">0</span> + <span class="hljs-built_in">f0</span> * (<span class="hljs-number">1</span>.<span class="hljs-number">0</span> / dfg.y - <span class="hljs-number">1</span>.<span class="hljs-number">0</span>)<span class="hljs-comment">;</span>
+<span class="line"></span><span class="hljs-comment">// Scale the specular lobe to account for multiscattering</span>
+<span class="line"></span><span class="hljs-symbol">Fr</span> *= pixel.energyCompensation<span class="hljs-comment">;</span></code></pre><center><div class="listingcaption tilde"><b style="font-style:normal;">Listing&nbsp;10:</b> Implementation of the energy compensation specular lobe</div></center>
+<p>
+
+Please refer to section <a href="#toc5.3" target="_self">5.3</a> and section <a href="#toc5.3.4.7" target="_self">5.3.4.7</a> to learn how the DFG lookup table is derived and computed.
+</p>
+<a class="target" name="parameterization">&nbsp;</a><a class="target" name="materialsystem/parameterization">&nbsp;</a><a class="target" name="toc4.8">&nbsp;</a><h2>Parameterization</h2>
+<p>
+
+Disney's material model described in [<a href="#citation-burley12" target="_self">Burley12</a>] is a good starting point but its numerous parameters makes it impractical for real-time implementations. In addition, we would like our standard material model to be easy to understand and easy to use for both artists and developers.
+</p>
+<a class="target" name="standardparameters">&nbsp;</a><a class="target" name="materialsystem/parameterization/standardparameters">&nbsp;</a><a class="target" name="toc4.8.1">&nbsp;</a><h3>Standard parameters</h3>
+<p>
+
+<a href="#table_standardparameters" target="_self">Table&nbsp;2</a> describes the list of parameters that satisfy our constraints.
+</p><p>
+<div class='table'>
+<a class="target" name="table_standardparameters">&nbsp;</a><table class="table"><tr><th  style="text-align:right"> Parameter </th><th  style="text-align:left"> Definition </th></tr>
+<tr><td  style="text-align:right"> <strong class="asterisk">BaseColor</strong> </td><td  style="text-align:left"> Diffuse albedo for non-metallic surfaces, and specular color for metallic surfaces </td></tr>
+<tr><td  style="text-align:right"> <strong class="asterisk">Metallic</strong> </td><td  style="text-align:left"> Whether a surface appears to be dielectric (0.0) or conductor (1.0). Often used as a binary value (0 or 1) </td></tr>
+<tr><td  style="text-align:right"> <strong class="asterisk">Roughness</strong> </td><td  style="text-align:left"> Perceived smoothness (0.0) or roughness (1.0) of a surface. Smooth surfaces exhibit sharp reflections </td></tr>
+<tr><td  style="text-align:right"> <strong class="asterisk">Reflectance</strong> </td><td  style="text-align:left"> Fresnel reflectance at normal incidence for dielectric surfaces. This replaces an explicit index of refraction </td></tr>
+<tr><td  style="text-align:right"> <strong class="asterisk">Emissive</strong> </td><td  style="text-align:left"> Additional diffuse albedo to simulate emissive surfaces (such as neons, etc.) This parameter is mostly useful in an HDR pipeline with a bloom pass </td></tr>
+<tr><td  style="text-align:right"> <strong class="asterisk">Ambient occlusion</strong> </td><td  style="text-align:left"> Defines how much of the ambient light is accessible to a surface point. It is a per-pixel shadowing factor between 0.0 and 1.0. This parameter will be discussed in more details in the <a href="#lighting" target="_self">lighting</a> section </td></tr>
+</table><center><div class="tablecaption"><b style="font-style:normal;">Table&nbsp;2:</b> Parameters of the standard model</div></center></div>
+</p><p>
+<a href="#figure_material_parameters" target="_self">Figure&nbsp;17</a> shows how the metallic, roughness and reflectance parameters affect the appearance of a surface.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_material_parameters">&nbsp;</a><a href="../images/material_parameters.png" target="_blank"><img class="markdeep" src="../images/material_parameters.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;17:</b> From top to bottom: varying metallic, varying dielectric roughness, varying metallic roughness, varying reflectance</span></center></div></center>
+</p>
+<a class="target" name="typesandranges">&nbsp;</a><a class="target" name="materialsystem/parameterization/typesandranges">&nbsp;</a><a class="target" name="toc4.8.2">&nbsp;</a><h3>Types and ranges</h3>
+<p>
+
+It is important to understand the type and range of the different parameters of our material model, described in <a href="#table_standardparameterstypes" target="_self">table&nbsp;3</a>.
+</p><p>
+<div class='table'>
+<a class="target" name="table_standardparameterstypes">&nbsp;</a><table class="table"><tr><th  style="text-align:right"> Parameter </th><th  style="text-align:left"> Type and range </th></tr>
+<tr><td  style="text-align:right"> <strong class="asterisk">BaseColor</strong> </td><td  style="text-align:left"> Linear RGB [0..1] </td></tr>
+<tr><td  style="text-align:right"> <strong class="asterisk">Metallic</strong> </td><td  style="text-align:left"> Scalar [0..1] </td></tr>
+<tr><td  style="text-align:right"> <strong class="asterisk">Roughness</strong> </td><td  style="text-align:left"> Scalar [0..1] </td></tr>
+<tr><td  style="text-align:right"> <strong class="asterisk">Reflectance</strong> </td><td  style="text-align:left"> Scalar [0..1] </td></tr>
+<tr><td  style="text-align:right"> <strong class="asterisk">Emissive</strong> </td><td  style="text-align:left"> Linear RGB [0..1] + exposure compensation </td></tr>
+<tr><td  style="text-align:right"> <strong class="asterisk">Ambient occlusion</strong> </td><td  style="text-align:left"> Scalar [0..1] </td></tr>
+</table><center><div class="tablecaption"><b style="font-style:normal;">Table&nbsp;3:</b> Range and type of the standard model's parameters</div></center></div>
+</p><p>
+Note that the types and ranges described here are what the shader will expect. The API and/or tools UI could and should allow to specify the parameters using other types and ranges when they are more intuitive for artists.
+</p><p>
+For instance, the base color could be expressed in sRGB space and converted to linear space before being sent off to the shader. It can also be useful for artists to express the metallic, roughness and reflectance parameters as gray values between 0 and 255 (black to white).
+</p><p>
+Another example: the emissive parameter could be expressed as a color temperature and an intensity, to simulate the light emitted by a black body.
+</p>
+<a class="target" name="remapping">&nbsp;</a><a class="target" name="materialsystem/parameterization/remapping">&nbsp;</a><a class="target" name="toc4.8.3">&nbsp;</a><h3>Remapping</h3>
+<p>
+
+To make the standard material model easier and more intuitive to use for artists, we must remap the parameters <em class="underscore">baseColor</em>, <em class="underscore">roughness</em> and <em class="underscore">reflectance</em>.
+</p>
+<a class="target" name="basecolorremapping">&nbsp;</a><a class="target" name="materialsystem/parameterization/remapping/basecolorremapping">&nbsp;</a><a class="target" name="toc4.8.3.1">&nbsp;</a><h4>Base color remapping</h4>
+<p>
+
+The base color of a material is affected by the &ldquo;metallicness&rdquo; of said material. Dielectrics have achromatic specular reflectance but retain their base color as the diffuse color. Conductors on the other hand use their base color as the specular color and do not have a diffuse component.
+</p><p>
+The lighting equations must therefore use the diffuse color and \(\fNormal\) instead of the base color. The diffuse color can easily be computed from the base color, as show in <a href="#listing_basecolortodiffuse" target="_self">listing&nbsp;11</a>.
+</p><a class="target" name="listing_basecolortodiffuse">&nbsp;</a><pre class="listing tilde"><code><span class="line"></span><span class="hljs-type">vec3</span> diffuseColor = (<span class="hljs-number">1.0</span> - metallic) * baseColor.rgb;</code></pre><center><div class="listingcaption tilde"><b style="font-style:normal;">Listing&nbsp;11:</b> Conversion of base color to diffuse in GLSL</div></center>
+<a class="target" name="reflectanceremapping">&nbsp;</a><a class="target" name="materialsystem/parameterization/remapping/reflectanceremapping">&nbsp;</a><a class="target" name="toc4.8.3.2">&nbsp;</a><h4>Reflectance remapping</h4>
+<p>
+
+<strong class="asterisk">Dielectrics</strong>
+</p><p>
+The Fresnel term relies on \(\fNormal\), the specular reflectance at normal incidence angle, and is achromatic for dielectrics. We will use the remapping for dielectric surfaces described in [<a href="#citation-lagarde14" target="_self">Lagarde14</a>] :
+</p><p>
+$$\begin{equation}
+\fNormal = 0.16 \cdot reflectance^2
+\end{equation}$$
+</p><p>
+The goal is to map \(\fNormal\) onto a range that can represent the Fresnel values of both common dielectric surfaces (4% reflectance) and gemstones (8% to 16%). The mapping function is chosen to yield a 4% Fresnel reflectance value for an input reflectance of 0.5 (or 128 on a linear RGB gray scale). <a href="#figure_reflectance" target="_self">Figure&nbsp;18</a> show those common values and how they relate to the mapping function.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_reflectance">&nbsp;</a><a href="../images/diagram_reflectance.png" target="_blank"><img class="markdeep" src="../images/diagram_reflectance.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;18:</b> Common reflectance values</span></center></div></center>
+</p><p>
+If the index of refraction is known (for instance, an air-water interface has an IOR of 1.33), the Fresnel reflectance can be calculated as follows:
+</p><p>
+$$\begin{equation}\label{fresnelEquation}
+\fNormal(n_{ior}) = \frac{(\nior - 1)^2}{(\nior + 1)^2}
+\end{equation}$$
+</p><p>
+And if the reflectance value is known, we can compute the corresponding IOR:
+</p><p>
+$$\begin{equation}
+n_{ior} = \frac{2}{1 - \sqrt{\fNormal}} - 1 
+\end{equation}$$
+</p><p>
+<a href="#table_commonmatreflectance" target="_self">Table&nbsp;4</a> describes acceptable Fresnel reflectance values for various types of materials (no real world material has a value under 2%).
+</p><p>
+<div class='table'>
+<a class="target" name="table_commonmatreflectance">&nbsp;</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&nbsp;4:</b> Reflectance of common materials (source: Real-Time Rendering 4th Edition)</div></center></div>
+</p><p>
+<a href="#table_fnormalmetals" target="_self">Table&nbsp;5</a> lists the \(\fNormal\) values for a few metals. The values are given in sRGB and must be used as the base color in our material model. Please refer to the annex, section <a href="#toc9.1" target="_self">9.1</a>, for an explanation of how these sRGB colors are computed from measured data.
+</p><p>
+<div class='table'>
+<a class="target" name="table_fnormalmetals">&nbsp;</a><table class="table"><tr><th  style="text-align:right"> Metal </th><th  style="text-align:center"> \(\fNormal\) in 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: #f7f4e8; width: 60px">&nbsp;</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: #e8eaea; width: 60px">&nbsp;</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: #c1baaf; width: 60px">&nbsp;</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: #c4c6c6; width: 60px">&nbsp;</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: #d3cec6; width: 60px">&nbsp;</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: #ffd891; width: 60px">&nbsp;</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: #f9e596; width: 60px">&nbsp;</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: #f7bc9e; width: 60px">&nbsp;</div> </td></tr>
+</table><center><div class="tablecaption"><b style="font-style:normal;">Table&nbsp;5:</b> \(\fNormal\) for common metals</div></center></div>
+</p><p>
+All materials have a Fresnel reflectance of 100% at grazing angles so we will set \(\fGrazing\) in the following way when evaluating the specular BRDF \(\fSpecular\):
+</p><p>
+$$\begin{equation}
+\fGrazing = 1.0
+\end{equation}$$
+</p><p>
+<a href="#figure_grazing_reflectance" target="_self">Figure&nbsp;19</a> shows a red plastic ball. If you look closely at the edges of the sphere, you will be able to notice the achromatic specular reflectance at grazing angles.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_grazing_reflectance">&nbsp;</a><a href="../images/material_grazing_reflectance.png" target="_blank"><img class="markdeep" src="../images/material_grazing_reflectance.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;19:</b> The specular reflectance becomes achromatic at grazing angles</span></center></div></center>
+</p><p>
+<strong class="asterisk">Conductors</strong>
+</p><p>
+The specular reflectance of metallic surfaces is chromatic:
+</p><p>
+$$\begin{equation}
+\fNormal = baseColor \cdot metallic
+\end{equation}$$
+</p><p>
+<a href="#listing_fnormal" target="_self">Listing&nbsp;12</a> shows how \(\fNormal\) is computed for both dielectric and metallic materials. It shows that the color of the specular reflectance is derived from the base color in the metallic case.
+</p><a class="target" name="listing_fnormal">&nbsp;</a><pre class="listing tilde"><code><span class="line"></span><span class="hljs-symbol">vec3</span> <span class="hljs-built_in">f0</span> = <span class="hljs-number">0</span>.<span class="hljs-number">16</span> * reflectance * reflectance * (<span class="hljs-number">1</span>.<span class="hljs-number">0</span> - metallic) + baseColor * metallic<span class="hljs-comment">;</span></code></pre><center><div class="listingcaption tilde"><b style="font-style:normal;">Listing&nbsp;12:</b> Computing \(\fNormal\) for dielectric and metallic materials in GLSL</div></center>
+<a class="target" name="roughnessremappingandclamping">&nbsp;</a><a class="target" name="materialsystem/parameterization/remapping/roughnessremappingandclamping">&nbsp;</a><a class="target" name="toc4.8.3.3">&nbsp;</a><h4>Roughness remapping and clamping</h4>
+<p>
+
+The roughness set by the user, called <code>perceptualRoughness</code> here, is remapped to a perceptually linear range using the following formulation:
+</p><p>
+$$\begin{equation}
+\alpha = perceptualRoughness^2
+\end{equation}$$
+</p><p>
+<a href="#figure_roughness_remap" target="_self">Figure&nbsp;20</a> shows a silver metallic surface with increasing roughness (from 0.0 to 1.0), using the unmodified roughness value (bottom) and the remapped value (top).
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_roughness_remap">&nbsp;</a><a href="../images/material_roughness_remap.png" target="_blank"><img class="markdeep" src="../images/material_roughness_remap.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;20:</b> Roughness remapping comparison: perceptually linear roughness (top) and roughness (bottom)</span></center></div></center>
+</p><p>
+Using this visual comparison, it is obvious that the remapped roughness is easier to understand by artists and developers. Without this remapping, shiny metallic surfaces would have to be confined to a very small range between 0.0 and 0.05.
+</p><p>
+Brent Burley made similar observations in his presentation [<a href="#citation-burley12" target="_self">Burley12</a>]. After experimenting with other remappings (cubic and quadratic mappings for instance), we have reached the conclusion that this simple square remapping delivers visually pleasing and intuitive results while being cheap for real-time applications.
+</p><p>
+Last but not least, it is important to note that the roughness parameters is used in various computations at runtime where limited floating point precision can become an issue. For instance, <em class="underscore">mediump</em> precision floats are often implemented as half-floats (fp16) on mobile GPUs.
+</p><p>
+This cause problems when computing small values like \(\frac{1}{perceptualRoughness^4}\) in our lighting equations (roughness squared in the GGX computation). The smallest value that can be represented as a half-float is \(2^{-14}\) or \(6.1 \times 10^{-5}\). To avoid divisions by 0 on devices that do not support denormals, the result of \(\frac{1}{roughness^4}\) must therefore not be lower than \(6.1 \times 10^{-5}\). To do so, we must clamp the roughness to 0.089, which gives us \(6.274 \times 10^{-5}\). 
+</p><p>
+Denormals should also be avoided to prevent performance drops. The roughness can also not be set to 0 to avoid obvious divisions by 0.
+</p><p>
+Since we also want specular highlights to have a minimum size (a roughness close to 0 creates almost invisible highlights), we should clamp the roughness to a safe range in the shader. This clamping has the added benefit of correcting specular aliasing<sup><a href="#endnote-frostbiteroughnessclamp" target="_self">1</a></sup> that can appear for low roughness values.
+</p><p>
+<div class="endnote"><a class="target" name="endnote-frostbiteroughnessclamp">&nbsp;</a><sup>1</sup> The Frostbite engine clamps the roughness of analytical lights to 0.045 to reduce specular aliasing. This is possible when using single precision floats (fp32).
+</div>
+</p>
+<a class="target" name="blendingandlayering">&nbsp;</a><a class="target" name="materialsystem/parameterization/blendingandlayering">&nbsp;</a><a class="target" name="toc4.8.4">&nbsp;</a><h3>Blending and layering</h3>
+<p>
+
+As noted in [<a href="#citation-burley12" target="_self">Burley12</a>] and [<a href="#citation-neubelt13" target="_self">Neubelt13</a>], this model allows for robust blending between different materials by simply interpolating the different parameters. In particular, this allows to layer different materials using simple masks.
+</p><p>
+For instance, <a href="#figure_materialblending" target="_self">figure&nbsp;21</a> shows how the studio Ready at Dawn used material blending and layering in <em class="underscore">The Order: 1886</em> to create complex appearances from a library of simple materials (gold, copper, wood, rust, etc.).
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_materialblending">&nbsp;</a><a href="../images/material_blending.png" target="_blank"><img class="markdeep" src="../images/material_blending.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;21:</b> Material blending and layering. Source: Ready at Dawn Studios</span></center></div></center>
+</p><p>
+The blending and layering of materials is effectively an interpolation of the various parameters of the material model. <a href="#figure_material_interpolation" target="_self">Figure&nbsp;22</a> show an interpolation between shiny metallic chrome and rough red plastic. While the intermediate blended materials make little physical sense, they look plausible.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_material_interpolation">&nbsp;</a><a href="../images/material_interpolation.png" target="_blank"><img class="markdeep" src="../images/material_interpolation.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;22:</b> Interpolation from shiny chrome (left) to rough red plastic (right)</span></center></div></center>
+</p>
+<a class="target" name="craftingphysicallybasedmaterials">&nbsp;</a><a class="target" name="materialsystem/parameterization/craftingphysicallybasedmaterials">&nbsp;</a><a class="target" name="toc4.8.5">&nbsp;</a><h3>Crafting physically based materials</h3>
+<p>
+
+Designing physically based materials is fairly easy once you understand the nature of the four main parameters: base color, metallic, roughness and reflectance.
+</p><p>
+We provide a <a href="./Material%20Properties.pdf">useful chart/reference guide</a> to help artists and developers craft their own physically based materials.
+</p><p>
+<center><div class="image" style=""><a href="../images/material_chart.jpg" target="_blank"><img class="markdeep" src="../images/material_chart.jpg" /></a><center><span class="imagecaption">Crafting physically based materials</span></center></div></center>
+</p><p>
+In addition, here is a quick summary of how to use our material model:
+</p><p>
+<dl><dt>All materials</dt><dd><p>    <strong class="asterisk">Base color</strong> should be devoid of lighting information, except for micro-occlusion.
+</p><p>
+    <strong class="asterisk">Metallic</strong> is almost a binary value. Pure conductors have a metallic value of 1 and pure dielectrics have a metallic value of 0. You should try to use values close at or close to 0 and 1. Intermediate values are meant for transitions between surface types (metal to rust for instance).
+</p></dd><dt>Non-metallic materials</dt><dd><p>    <strong class="asterisk">Base color</strong> represents the reflected color and should be an sRGB value in the range 50-240 (strict range) or 30-240 (tolerant range).
+</p><p>
+    <strong class="asterisk">Metallic</strong> should be 0 or close to 0.
+</p><p>
+    <strong class="asterisk">Reflectance</strong> should be set to 127 sRGB (0.5 linear, 4% reflectance) if you cannot find a proper value. Do not use values under 90 sRGB (0.35 linear, 2% reflectance).
+</p></dd><dt>Metallic materials</dt><dd><p>    <strong class="asterisk">Base color</strong> represents both the specular color and reflectance. Use values with a luminosity of 67% to 100% (170-255 sRGB). Oxidized or dirty metals should use a lower luminosity than clean metals to take into account the non-metallic components.
+</p><p>
+    <strong class="asterisk">Metallic</strong> should be 1 or close to 1.
+</p><p>
+    <strong class="asterisk">Reflectance</strong> is ignored (calculated from the base color).
+</p></dd></dl></p>
+<a class="target" name="clearcoatmodel">&nbsp;</a><a class="target" name="materialsystem/clearcoatmodel">&nbsp;</a><a class="target" name="toc4.9">&nbsp;</a><h2>Clear coat model</h2>
+<p>
+
+The standard material model described previously is a good fit for isotropic surfaces made of a single layer. Multi-layer materials are unfortunately fairly common, particularly materials with a thin translucent layer over a standard layer. Real world examples of such materials include car paints, soda cans, lacquered wood, acrylic, etc.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_materialclearcoat">&nbsp;</a><a href="../images/material_clear_coat.png" target="_blank"><img class="markdeep" src="../images/material_clear_coat.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;23:</b> Comparison of a blue metallic surface under the standard material model (left) and the clear coat model (right)</span></center></div></center>
+</p><p>
+A clear coat layer can be simulated as an extension of the standard material model by adding a second specular lobe, which implies evaluating a second specular BRDF. To simplify the implementation and parameterization, the clear coat layer will always be isotropic and dielectric. The base layer can be anything allowed by the standard model (dielectric or conductor).
+</p><p>
+Since incoming light will traverse the clear coat layer, we must also take the loss of energy into account as shown in <a href="#figure_clearcoatmodel" target="_self">figure&nbsp;24</a>. Our model will however not simulate inter reflection and refraction behaviors.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_clearcoatmodel">&nbsp;</a><a href="../images/diagram_clear_coat.png" target="_blank"><img class="markdeep" src="../images/diagram_clear_coat.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;24:</b> Clear coat surface model</span></center></div></center>
+</p>
+<a class="target" name="clearcoatspecularbrdf">&nbsp;</a><a class="target" name="materialsystem/clearcoatmodel/clearcoatspecularbrdf">&nbsp;</a><a class="target" name="toc4.9.1">&nbsp;</a><h3>Clear coat specular BRDF</h3>
+<p>
+
+The clear coat layer will be modeled using the same Cook-Torrance microfacet BRDF used in the standard model. Since the clear coat layer is always isotropic and dielectric, with low roughness values (see section <a href="#toc4.9.3" target="_self">4.9.3</a>), we can choose cheaper DFG terms without notably sacrificing visual quality.
+</p><p>
+A survey of the terms listed in [<a href="#citation-karis13a" target="_self">Karis13a</a>] and [<a href="#citation-burley12" target="_self">Burley12</a>] shows that the Fresnel and NDF terms we already use in the standard model are not computationally more expensive than other terms. [<a href="#citation-kelemen01" target="_self">Kelemen01</a>] describes a much simpler term that can replace our Smith-GGX visibility term:
+</p><p>
+$$\begin{equation}
+V(l,h) = \frac{1}{4(\LoH)^2}
+\end{equation}$$
+</p><p>
+This masking-shadowing function is not physically based, as shown in [<a href="#citation-heitz14" target="_self">Heitz14</a>], but its simplicity makes it desirable for real-time rendering.
+</p><p>
+In summary, our clear coat BRDF is a Cook-Torrance specular microfacet model, with a GGX normal distribution function, a Kelemen visibility function, and a Schlick Fresnel function. <a href="#listing_kelemen" target="_self">Listing&nbsp;13</a> shows how trivial the GLSL implementation is.
+</p><a class="target" name="listing_kelemen">&nbsp;</a><pre class="listing tilde"><code><span class="line"></span><span class="hljs-function"><span class="hljs-type">float</span> <span class="hljs-title">V_Kelemen</span><span class="hljs-params">(<span class="hljs-type">float</span> LoH)</span> </span>{
+<span class="line"></span>    <span class="hljs-keyword">return</span> <span class="hljs-number">0.25</span> / (LoH * LoH);
+<span class="line"></span>}</code></pre><center><div class="listingcaption tilde"><b style="font-style:normal;">Listing&nbsp;13:</b> Implementation of the Kelemen visibility term in GLSL</div></center>
+<p>
+
+<strong class="asterisk">Note on the Fresnel term</strong>
+</p><p>
+The Fresnel term of the specular BRDF requires \(\fNormal\), the specular reflectance at normal incidence angle. This parameter can be computed from an index of refraction of an interface. We will assume that our clear coat layer is made of polyurethane, a common compound <a href="https://en.wikipedia.org/wiki/List_of_polyurethane_applications#Varnish">used in coatings and varnishes</a>, or similar. An air-polyurethane interface <a href="http://www.clearpur.com/transparent-polyurethanes/">has an IOR of 1.5</a>, from which we can deduce \(\fNormal\):
+</p><p>
+$$\begin{equation}
+\fNormal(1.5) = \frac{(1.5 - 1)^2}{(1.5 + 1)^2} = 0.04
+\end{equation}$$
+</p><p>
+This corresponds to a Fresnel reflectance of 4% that we know is associated with common dielectric materials.
+</p>
+<a class="target" name="integrationinthesurfaceresponse">&nbsp;</a><a class="target" name="materialsystem/clearcoatmodel/integrationinthesurfaceresponse">&nbsp;</a><a class="target" name="toc4.9.2">&nbsp;</a><h3>Integration in the surface response</h3>
+<p>
+
+Because we must take into account the loss of energy caused by the addition of the clear coat layer, we can reformulate the BRDF from equation \(\ref{brdf}\) thusly:
+</p><p>
+$$\begin{equation}
+f(v,l)=\fDiffuse(v,l) (1 - F_c) + \fSpecular(v,l) (1 - F_c) + f_c(v,l)
+\end{equation}$$
+</p><p>
+Where \(F_c\) is the Fresnel term of the clear coat BRDF and \(f_c\) the clear coat BRDF 
+</p>
+<a class="target" name="clearcoatparameterization">&nbsp;</a><a class="target" name="materialsystem/clearcoatmodel/clearcoatparameterization">&nbsp;</a><a class="target" name="toc4.9.3">&nbsp;</a><h3>Clear coat parameterization</h3>
+<p>
+
+The clear coat material model encompasses all the parameters previously defined for the standard material mode, plus two parameters described in <a href="#table_clearcoatparameters" target="_self">table&nbsp;6</a>.
+</p><p>
+<div class='table'>
+<a class="target" name="table_clearcoatparameters">&nbsp;</a><table class="table"><tr><th  style="text-align:right"> Parameter </th><th  style="text-align:left"> Definition </th></tr>
+<tr><td  style="text-align:right"> <strong class="asterisk">ClearCoat</strong> </td><td  style="text-align:left"> Strength of the clear coat layer. Scalar between 0 and 1 </td></tr>
+<tr><td  style="text-align:right"> <strong class="asterisk">ClearCoatRoughness</strong> </td><td  style="text-align:left"> Perceived smoothness or roughness of the clear coat layer. Scalar between 0 and 1 </td></tr>
+</table><center><div class="tablecaption"><b style="font-style:normal;">Table&nbsp;6:</b> Clear coat model parameters</div></center></div>
+</p><p>
+The clear coat roughness parameter is remapped and clamped in a similar way to the roughness parameter of the standard material.
+</p><p>
+<a href="#figure_clearcoat" target="_self">Figure&nbsp;25</a> and <a href="#figure_clearcoatroughness" target="_self">figure&nbsp;26</a> show how the clear coat parameters affect the appearance of a surface.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_clearcoat">&nbsp;</a><a href="../images/material_clear_coat1.png" target="_blank"><img class="markdeep" src="../images/material_clear_coat1.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;25:</b> Clear coat varying from 0.0 (left) to 1.0 (right) with metallic set to 1.0 and roughness to 0.8</span></center></div></center>
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_clearcoatroughness">&nbsp;</a><a href="../images/material_clear_coat2.png" target="_blank"><img class="markdeep" src="../images/material_clear_coat2.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;26:</b> Clear coat roughness varying from 0.0 (left) to 1.0 (right) with metallic set to 1.0, roughness to 0.8 and clear coat to 1.0</span></center></div></center>
+</p><p>
+<a href="#listing_clearcoatbrdf" target="_self">Listing&nbsp;14</a> shows the GLSL implementation of the clear coat material model after remapping, parameterization and integration in the standard surface response.
+</p><a class="target" name="listing_clearcoatbrdf">&nbsp;</a><pre class="listing tilde"><code><span class="line"></span><span class="hljs-function"><span class="hljs-type">void</span> <span class="hljs-title">BRDF</span><span class="hljs-params">(...)</span> </span>{
+<span class="line"></span>    <span class="hljs-comment">// compute Fd and Fr from standard model</span>
+<span class="line"></span>
+<span class="line"></span>    <span class="hljs-comment">// remapping and linearization of clear coat roughness</span>
+<span class="line"></span>    clearCoatPerceptualRoughness = <span class="hljs-built_in">clamp</span>(clearCoatPerceptualRoughness, <span class="hljs-number">0.089</span>, <span class="hljs-number">1.0</span>);
+<span class="line"></span>    clearCoatRoughness = clearCoatPerceptualRoughness * clearCoatPerceptualRoughness;
+<span class="line"></span>
+<span class="line"></span>    <span class="hljs-comment">// clear coat BRDF</span>
+<span class="line"></span>    <span class="hljs-type">float</span>  Dc = <span class="hljs-built_in">D_GGX</span>(clearCoatRoughness, NoH);
+<span class="line"></span>    <span class="hljs-type">float</span>  Vc = <span class="hljs-built_in">V_Kelemen</span>(clearCoatRoughness, LoH);
+<span class="line"></span>    <span class="hljs-type">float</span>  Fc = <span class="hljs-built_in">F_Schlick</span>(<span class="hljs-number">0.04</span>, LoH) * clearCoat; <span class="hljs-comment">// clear coat strength</span>
+<span class="line"></span>    <span class="hljs-type">float</span> Frc = (Dc * Vc) * Fc;
+<span class="line"></span>
+<span class="line"></span>    <span class="hljs-comment">// account for energy loss in the base layer</span>
+<span class="line"></span>    <span class="hljs-keyword">return</span> color * ((Fd + Fr * (<span class="hljs-number">1.0</span> - Fc)) * (<span class="hljs-number">1.0</span> - Fc) + Frc);
+<span class="line"></span>}</code></pre><center><div class="listingcaption tilde"><b style="font-style:normal;">Listing&nbsp;14:</b> Implementation of the clear coat BRDF in GLSL</div></center>
+<a class="target" name="baselayermodification">&nbsp;</a><a class="target" name="materialsystem/clearcoatmodel/baselayermodification">&nbsp;</a><a class="target" name="toc4.9.4">&nbsp;</a><h3>Base layer modification</h3>
+<p>
+
+The presence of a clear coat layer means that we should recompute \(\fNormal\), since it is normally based on an air-material interface. The base layer thus requires \(\fNormal\) to be computed based on a clear coat-material interface instead.
+</p><p>
+This can be achieved by computing the material's index of refraction (IOR) from \(\fNormal\), then computing a new \(\fNormal\) based on the newly computed IOR and the IOR of the clear coat layer (1.5).
+</p><p>
+First, we compute the base layer's IOR:
+</p><p>
+$$
+IOR_{base} = \frac{1 + \sqrt{\fNormal}}{1 - \sqrt{\fNormal}}
+$$
+</p><p>
+Then we compute the new \(\fNormal\) from this new index of refraction:
+</p><p>
+$$
+f_{0_{base}} = \left( \frac{IOR_{base} - 1.5}{IOR_{base} + 1.5} \right) ^2
+$$
+</p><p>
+Since the clear coat layer's IOR is fixed, we can combine both steps to simplify:
+</p><p>
+$$
+f_{0_{base}} = \frac{\left( 1 - 5 \sqrt{\fNormal} \right) ^2}{\left( 5 - \sqrt{\fNormal} \right) ^2}
+$$
+</p><p>
+We should also modify the base layer's apparent roughness based on the IOR of the clear coat layer but this is something we have opted to leave out for now.
+</p>
+<a class="target" name="anisotropicmodel">&nbsp;</a><a class="target" name="materialsystem/anisotropicmodel">&nbsp;</a><a class="target" name="toc4.10">&nbsp;</a><h2>Anisotropic model</h2>
+<p>
+
+The standard material model described previously can only describe isotropic surfaces, that is, surfaces whose properties are identical in all directions. Many real-world materials, such as brushed metal, can, however, only be replicated using an anisotropic model.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_anisotropic">&nbsp;</a><a href="../images/material_anisotropic.png" target="_blank"><img class="markdeep" src="../images/material_anisotropic.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;27:</b> Comparison of isotropic material (left) and anisotropic material (right)</span></center></div></center>
+</p>
+<a class="target" name="anisotropicspecularbrdf">&nbsp;</a><a class="target" name="materialsystem/anisotropicmodel/anisotropicspecularbrdf">&nbsp;</a><a class="target" name="toc4.10.1">&nbsp;</a><h3>Anisotropic specular BRDF</h3>
+<p>
+
+The isotropic specular BRDF described previously can be modified to handle anisotropic materials. Burley achieves this by using an anisotropic GGX NDF:
+</p><p>
+$$\begin{equation}
+D_{aniso}(h,\alpha) = \frac{1}{\pi \alpha_t \alpha_b} \frac{1}{((\frac{t \cdot h}{\alpha_t})^2 + (\frac{b \cdot h}{\alpha_b})^2 + (\NoH)^2)^2}
+\end{equation}$$
+</p><p>
+This NDF unfortunately relies on two supplemental roughness terms noted \(\alpha_b\), the roughness along the bitangent direction, and \(\alpha_t\), the roughness along the tangent direction. Neubelt and Pettineo [<a href="#citation-neubelt13" target="_self">Neubelt13</a>] propose a way to derive \(\alpha_b\) from \(\alpha_t\) by using an <em class="underscore">anisotropy</em> parameter that describes the relationship between the two roughness values for a material:
+</p><p>
+$$
+\begin{align*}
+  \alpha_t &= \alpha \\
+  \alpha_b &= lerp(0, \alpha, 1 - anisotropy)
+\end{align*}
+$$
+</p><p>
+The relationship defined in [<a href="#citation-burley12" target="_self">Burley12</a>] is different, offers more pleasant and intuitive results, but is slightly more expensive:
+</p><p>
+$$
+\begin{align*}
+  \alpha_t &= \frac{\alpha}{\sqrt{1 - 0.9 \times anisotropy}} \\
+  \alpha_b &= \alpha \sqrt{1 - 0.9 \times anisotropy}
+\end{align*}
+$$
+</p><p>
+We instead opted to follow the relationship described in [<a href="#citation-kulla17" target="_self">Kulla17</a>] as it allows creation of sharp highlights:
+</p><p>
+$$
+\begin{align*}
+  \alpha_t &= \alpha \times (1 + anisotropy) \\
+  \alpha_b &= \alpha \times (1 - anisotropy)
+\end{align*}
+$$
+</p><p>
+Note that this NDF requires the tangent and bitangent directions in addition to the normal direction. Since these directions are already needed for normal mapping, providing them may not be an issue.
+</p><p>
+The resulting implementation is described in <a href="#listing_anisotropicbrdf" target="_self">listing&nbsp;15</a>.
+</p><a class="target" name="listing_anisotropicbrdf">&nbsp;</a><pre class="listing tilde"><code><span class="line"></span><span class="hljs-type">float</span> at = <span class="hljs-built_in">max</span>(roughness * (<span class="hljs-number">1.0</span> + anisotropy), <span class="hljs-number">0.001</span>);
+<span class="line"></span><span class="hljs-type">float</span> ab = <span class="hljs-built_in">max</span>(roughness * (<span class="hljs-number">1.0</span> - anisotropy), <span class="hljs-number">0.001</span>);
+<span class="line"></span>
+<span class="line"></span><span class="hljs-type">float</span> D_GGX_Anisotropic(<span class="hljs-type">float</span> NoH, <span class="hljs-keyword">const</span> <span class="hljs-type">vec3</span> h,
+<span class="line"></span>        <span class="hljs-keyword">const</span> <span class="hljs-type">vec3</span> t, <span class="hljs-keyword">const</span> <span class="hljs-type">vec3</span> b, <span class="hljs-type">float</span> at, <span class="hljs-type">float</span> ab) {
+<span class="line"></span>    <span class="hljs-type">float</span> ToH = <span class="hljs-built_in">dot</span>(t, h);
+<span class="line"></span>    <span class="hljs-type">float</span> BoH = <span class="hljs-built_in">dot</span>(b, h);
+<span class="line"></span>    <span class="hljs-type">float</span> a2 = at * ab;
+<span class="line"></span>    <span class="hljs-keyword">highp</span> <span class="hljs-type">vec3</span> v = <span class="hljs-type">vec3</span>(ab * ToH, at * BoH, a2 * NoH);
+<span class="line"></span>    <span class="hljs-keyword">highp</span> <span class="hljs-type">float</span> v2 = <span class="hljs-built_in">dot</span>(v, v);
+<span class="line"></span>    <span class="hljs-type">float</span> w2 = a2 / v2;
+<span class="line"></span>    <span class="hljs-keyword">return</span> a2 * w2 * w2 * (<span class="hljs-number">1.0</span> / PI);
+<span class="line"></span>}</code></pre><center><div class="listingcaption tilde"><b style="font-style:normal;">Listing&nbsp;15:</b> Implementation of Burley's anisotropic NDF in GLSL</div></center>
+<p>
+
+In addition, [<a href="#citation-heitz14" target="_self">Heitz14</a>] presents an anisotropic masking-shadowing function to match the height-correlated GGX distribution. The masking-shadowing term can be greatly simplified by using the visibility function instead:
+</p><p>
+$$\begin{equation}
+G(v,l,h,\alpha) = \frac{\chi^+(\VoH) \chi^+(\LoH)}{1 + \Lambda(v) + \Lambda(l)}
+\end{equation}$$
+</p><p>
+$$\begin{equation}
+\Lambda(m) = \frac{-1 + \sqrt{1 + \alpha_0^2 tan^2(\theta_m)}}{2} = \frac{-1 + \sqrt{1 + \alpha_0^2 \frac{(1 - cos^2(\theta_m))}{cos^2(\theta_m)}}}{2}
+\end{equation}$$
+</p><p>
+Where:
+</p><p>
+$$\begin{equation}
+\alpha_0 = \sqrt{cos^2(\phi_0)\alpha_x^2 + sin^2(\phi_0)\alpha_y^2}
+\end{equation}$$
+</p><p>
+After derivation we obtain:
+</p><p>
+$$\begin{equation}
+V_{aniso}(\NoL,\NoV,\alpha) = \frac{1}{2((\NoL)\hat{\Lambda}_v+(\NoV)\hat{\Lambda}_l)} \\
+\hat{\Lambda}_v = \sqrt{\alpha^2_t(t \cdot v)^2+\alpha^2_b(b \cdot v)^2+(\NoV)^2} \\
+\hat{\Lambda}_l = \sqrt{\alpha^2_t(t \cdot l)^2+\alpha^2_b(b \cdot l)^2+(\NoL)^2}
+\end{equation}$$
+</p><p>
+The term \( \hat{\Lambda}_v \) is the same for every light and can be computed only once if needed. The resulting implementation is described in <a href="#listing_anisotropicv" target="_self">listing&nbsp;16</a>.
+</p><a class="target" name="listing_anisotropicv">&nbsp;</a><pre class="listing tilde"><code><span class="line"></span><span class="hljs-type">float</span> at = <span class="hljs-built_in">max</span>(roughness * (<span class="hljs-number">1.0</span> + anisotropy), <span class="hljs-number">0.001</span>);
+<span class="line"></span><span class="hljs-type">float</span> ab = <span class="hljs-built_in">max</span>(roughness * (<span class="hljs-number">1.0</span> - anisotropy), <span class="hljs-number">0.001</span>);
+<span class="line"></span>
+<span class="line"></span><span class="hljs-type">float</span> V_SmithGGXCorrelated_Anisotropic(<span class="hljs-type">float</span> at, <span class="hljs-type">float</span> ab, <span class="hljs-type">float</span> ToV, <span class="hljs-type">float</span> BoV,
+<span class="line"></span>        <span class="hljs-type">float</span> ToL, <span class="hljs-type">float</span> BoL, <span class="hljs-type">float</span> NoV, <span class="hljs-type">float</span> NoL) {
+<span class="line"></span>    <span class="hljs-type">float</span> lambdaV = NoL * <span class="hljs-built_in">length</span>(<span class="hljs-type">vec3</span>(at * ToV, ab * BoV, NoV));
+<span class="line"></span>    <span class="hljs-type">float</span> lambdaL = NoV * <span class="hljs-built_in">length</span>(<span class="hljs-type">vec3</span>(at * ToL, ab * BoL, NoL));
+<span class="line"></span>    <span class="hljs-type">float</span> v = <span class="hljs-number">0.5</span> / (lambdaV + lambdaL);
+<span class="line"></span>    <span class="hljs-keyword">return</span> saturateMediump(v);
+<span class="line"></span>}</code></pre><center><div class="listingcaption tilde"><b style="font-style:normal;">Listing&nbsp;16:</b> Implementation of the anisotropic visibility function in GLSL</div></center>
+<a class="target" name="anisotropicparameterization">&nbsp;</a><a class="target" name="materialsystem/anisotropicmodel/anisotropicparameterization">&nbsp;</a><a class="target" name="toc4.10.2">&nbsp;</a><h3>Anisotropic parameterization</h3>
+<p>
+
+The anisotropic material model encompasses all the parameters previously defined for the standard material mode, plus an extra parameter described in <a href="#table_anisotropicparameters" target="_self">table&nbsp;7</a>.
+</p><p>
+<div class='table'>
+<a class="target" name="table_anisotropicparameters">&nbsp;</a><table class="table"><tr><th  style="text-align:right"> Parameter </th><th  style="text-align:left"> Definition </th></tr>
+<tr><td  style="text-align:right"> <strong class="asterisk">Anisotropy</strong> </td><td  style="text-align:left"> Amount of anisotropy. Scalar between &minus;1 and 1 </td></tr>
+</table><center><div class="tablecaption"><b style="font-style:normal;">Table&nbsp;7:</b> Anisotropic model parameters</div></center></div>
+</p><p>
+No further remapping is required. Note that negative values will align the anisotropy with the bitangent direction instead of the tangent direction. <a href="#figure_anisotropyparameter" target="_self">Figure&nbsp;28</a> shows how the anisotropy parameter affect the appearance of a rough metallic surface.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_anisotropyparameter">&nbsp;</a><a href="../images/materials/anisotropy.png" target="_blank"><img class="markdeep" src="../images/materials/anisotropy.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;28:</b> Anisotropy varying from 0.0 (left) to 1.0 (right)</span></center></div></center>
+</p>
+<a class="target" name="subsurfacemodel">&nbsp;</a><a class="target" name="materialsystem/subsurfacemodel">&nbsp;</a><a class="target" name="toc4.11">&nbsp;</a><h2>Subsurface model</h2>
+<p>
+
+[TODO]
+</p>
+<a class="target" name="subsurfacespecularbrdf">&nbsp;</a><a class="target" name="materialsystem/subsurfacemodel/subsurfacespecularbrdf">&nbsp;</a><a class="target" name="toc4.11.1">&nbsp;</a><h3>Subsurface specular BRDF</h3>
+<p>
+
+[TODO]
+</p>
+<a class="target" name="subsurfaceparameterization">&nbsp;</a><a class="target" name="materialsystem/subsurfacemodel/subsurfaceparameterization">&nbsp;</a><a class="target" name="toc4.11.2">&nbsp;</a><h3>Subsurface parameterization</h3>
+<p>
+
+[TODO]
+</p>
+<a class="target" name="clothmodel">&nbsp;</a><a class="target" name="materialsystem/clothmodel">&nbsp;</a><a class="target" name="toc4.12">&nbsp;</a><h2>Cloth model</h2>
+<p>
+
+All the material models described previously are designed to simulate dense surfaces, both at a macro and at a micro level. Clothes and fabrics are however often made of loosely connected threads that absorb and scatter incident light. The microfacet BRDFs presented earlier do a poor job of recreating the nature of cloth due to their underlying assumption that a surface is made of random grooves that behave as perfect mirrors. When compared to hard surfaces, cloth is characterized by a softer specular lobe with a large falloff and the presence of fuzz lighting, caused by forward/backward scattering. Some fabrics also exhibit two-tone specular colors (velvets for instance).
+</p><p>
+<a href="#figure_materialcloth" target="_self">Figure&nbsp;29</a> shows how a traditional microfacet BRDF fails to capture the appearance of a sample of denim fabric. The surface appears rigid (almost plastic-like), more similar to a tarp than a piece of clothing. This figure also shows how important the softer specular lobe caused by absorption and scattering is to the faithful recreation of the fabric.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_materialcloth">&nbsp;</a><a href="../images/screenshot_cloth.png" target="_blank"><img class="markdeep" src="../images/screenshot_cloth.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;29:</b> Comparison of denim fabric rendered using a traditional microfacet BRDF (left) and our cloth BRDF (right)</span></center></div></center>
+</p><p>
+Velvet is an interesting use case for a cloth material model. As shown in <a href="#figure_materialvelvet" target="_self">figure&nbsp;30</a> this type of fabric exhibits strong rim lighting due to forward and backward scattering. These scattering events are caused by fibers standing straight at the surface of the fabric. When the incident light comes from the direction opposite to the view direction, the fibers will forward-scatter the light. Similarly, when the incident light from the same direction as the view direction, the fibers will scatter the light backward.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_materialvelvet">&nbsp;</a><a href="../images/screenshot_cloth_velvet.png" target="_blank"><img class="markdeep" src="../images/screenshot_cloth_velvet.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;30:</b> Velvet fabric showcasing forward and backward scattering</span></center></div></center>
+</p><p>
+Since fibers are flexible, we should in theory model the ability to groom the surface. While our model does not replicate this characteristic, it does model a visible front facing specular contribution that can be attributed to the random variance in the direction of the fibers.
+</p><p>
+It is important to note that there are types of fabrics that are still best modeled by hard surface material models. For instance, leather, silk and satin can be recreated using the standard or anisotropic material models.
+</p>
+<a class="target" name="clothspecularbrdf">&nbsp;</a><a class="target" name="materialsystem/clothmodel/clothspecularbrdf">&nbsp;</a><a class="target" name="toc4.12.1">&nbsp;</a><h3>Cloth specular BRDF</h3>
+<p>
+
+The cloth specular BRDF we use is a modified microfacet BRDF as described by Ashikhmin and Premoze in [<a href="#citation-ashikhmin07" target="_self">Ashikhmin07</a>]. In their work, Ashikhmin and Premoze note that the distribution term is what contributes most to a BRDF and that the shadowing/masking term is not necessary for their velvet distribution. The distribution term itself is an inverted Gaussian distribution. This helps achieve fuzz lighting (forward and backward scattering) while an offset is added to simulate the front facing specular contribution. The so-called velvet NDF is defined as follows:
+</p><p>
+$$\begin{equation}
+D_{velvet}(v,h,\alpha) = c_{norm}(1 + 4 exp\left(\frac{-{cot}^2\theta_{h}}{\alpha^2}\right))
+\end{equation}$$
+</p><p>
+This NDF is a variant of the NDF the same authors describe in [<a href="#citation-ashikhmin00" target="_self">Ashikhmin00</a>], notably modified to include an offset (set to 1 here) and an amplitude (4). In [<a href="#citation-neubelt13" target="_self">Neubelt13</a>], Neubelt and Pettineo propose a normalized version of this NDF:
+</p><p>
+$$\begin{equation}
+D_{velvet}(v,h,\alpha) = \frac{1}{\pi(1 + 4\alpha^2)} (1 + 4 \frac{exp\left(\frac{-{cot}^2\theta_{h}}{\alpha^2}\right)}{{sin}^4\theta_{h}})
+\end{equation}$$
+</p><p>
+For the full specular BRDF, we also follow [<a href="#citation-neubelt13" target="_self">Neubelt13</a>] and replace the traditional denominator with a smoother variant:
+</p><p>
+$$\begin{equation}\label{clothSpecularBRDF}
+f_{r}(v,h,\alpha) = \frac{D_{velvet}(v,h,\alpha)}{4(\NoL + \NoV - (\NoL)(\NoV))}
+\end{equation}$$
+</p><p>
+The implementation of the velvet NDF is presented in <a href="#listing_clothbrdf" target="_self">listing&nbsp;17</a>, optimized to properly fit in half float formats and to avoid computing a costly cotangent, relying instead on trigonometric identities. Note that we removed the Fresnel component from this BRDF.
+</p><a class="target" name="listing_clothbrdf">&nbsp;</a><pre class="listing tilde"><code><span class="line"></span><span class="hljs-function"><span class="hljs-type">float</span> <span class="hljs-title">D_Ashikhmin</span><span class="hljs-params">(<span class="hljs-type">float</span> roughness, <span class="hljs-type">float</span> NoH)</span> </span>{
+<span class="line"></span>    <span class="hljs-comment">// Ashikhmin 2007, &quot;Distribution-based BRDFs&quot;</span>
+<span class="line"></span> <span class="hljs-type">float</span> a2 = roughness * roughness;
+<span class="line"></span> <span class="hljs-type">float</span> cos2h = NoH * NoH;
+<span class="line"></span> <span class="hljs-type">float</span> sin2h = <span class="hljs-built_in">max</span>(<span class="hljs-number">1.0</span> - cos2h, <span class="hljs-number">0.0078125</span>); <span class="hljs-comment">// 2^(-14/2), so sin2h^2 &gt; 0 in fp16</span>
+<span class="line"></span> <span class="hljs-type">float</span> sin4h = sin2h * sin2h;
+<span class="line"></span> <span class="hljs-type">float</span> cot2 = -cos2h / (a2 * sin2h);
+<span class="line"></span> <span class="hljs-keyword">return</span> <span class="hljs-number">1.0</span> / (PI * (<span class="hljs-number">4.0</span> * a2 + <span class="hljs-number">1.0</span>) * sin4h) * (<span class="hljs-number">4.0</span> * <span class="hljs-built_in">exp</span>(cot2) + sin4h);
+<span class="line"></span>}</code></pre><center><div class="listingcaption tilde"><b style="font-style:normal;">Listing&nbsp;17:</b> Implementation of Ashikhmin's velvet NDF in GLSL</div></center>
+<p>
+
+In [<a href="#citation-estevez17" target="_self">Estevez17</a>] Estevez and Kulla propose a different NDF (called the &ldquo;Charlie&rdquo; sheen) that is based on an exponentiated sinusoidal instead of an inverted Gaussian. This NDF is appealing for several reasons: its parameterization feels more natural and intuitive, it provides a softer appearance and, as shown in equation \(\ref{charlieNDF}\), its implementation is simpler:
+</p><p>
+$$\begin{equation}\label{charlieNDF}
+D(m) = \frac{(2 + \frac{1}{\alpha}) sin(\theta)^{\frac{1}{\alpha}}}{2 \pi}
+\end{equation}$$
+</p><p>
+[<a href="#citation-estevez17" target="_self">Estevez17</a>] also presents a new shadowing term that we omit here because of its cost. We instead rely on the visibility term from [<a href="#citation-neubelt13" target="_self">Neubelt13</a>] (shown in equation \(\ref{clothSpecularBRDF}\) above).
+The implementation of this NDF is presented in <a href="#listing_clothcharliebrdf" target="_self">listing&nbsp;18</a>, optimized to properly fit in half float formats.
+</p><a class="target" name="listing_clothcharliebrdf">&nbsp;</a><pre class="listing tilde"><code><span class="line"></span><span class="hljs-function"><span class="hljs-type">float</span> <span class="hljs-title">D_Charlie</span><span class="hljs-params">(<span class="hljs-type">float</span> roughness, <span class="hljs-type">float</span> NoH)</span> </span>{
+<span class="line"></span>    <span class="hljs-comment">// Estevez and Kulla 2017, &quot;Production Friendly Microfacet Sheen BRDF&quot;</span>
+<span class="line"></span>    <span class="hljs-type">float</span> invAlpha  = <span class="hljs-number">1.0</span> / roughness;
+<span class="line"></span>    <span class="hljs-type">float</span> cos2h = NoH * NoH;
+<span class="line"></span>    <span class="hljs-type">float</span> sin2h = <span class="hljs-built_in">max</span>(<span class="hljs-number">1.0</span> - cos2h, <span class="hljs-number">0.0078125</span>); <span class="hljs-comment">// 2^(-14/2), so sin2h^2 &gt; 0 in fp16</span>
+<span class="line"></span>    <span class="hljs-keyword">return</span> (<span class="hljs-number">2.0</span> + invAlpha) * <span class="hljs-built_in">pow</span>(sin2h, invAlpha * <span class="hljs-number">0.5</span>) / (<span class="hljs-number">2.0</span> * PI);
+<span class="line"></span>}</code></pre><center><div class="listingcaption tilde"><b style="font-style:normal;">Listing&nbsp;18:</b> Implementation of the &ldquo;Charlie&rdquo; NDF in GLSL</div></center>
+<a class="target" name="sheencolor">&nbsp;</a><a class="target" name="materialsystem/clothmodel/clothspecularbrdf/sheencolor">&nbsp;</a><a class="target" name="toc4.12.1.1">&nbsp;</a><h4>Sheen color</h4>
+<p>
+
+To offer better control over the appearance of cloth and to give users the ability to recreate two-tone specular materials, we introduce the ability to directly modify the specular reflectance. <a href="#figure_materialclothsheen" target="_self">Figure&nbsp;31</a> shows an example of using the parameter we call &ldquo;sheen color&rdquo;.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_materialclothsheen">&nbsp;</a><a href="../images/screenshot_cloth_sheen.png" target="_blank"><img class="markdeep" src="../images/screenshot_cloth_sheen.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;31:</b> Blue fabric without (left) and with (right) sheen</span></center></div></center>
+</p>
+<a class="target" name="clothdiffusebrdf">&nbsp;</a><a class="target" name="materialsystem/clothmodel/clothdiffusebrdf">&nbsp;</a><a class="target" name="toc4.12.2">&nbsp;</a><h3>Cloth diffuse BRDF</h3>
+<p>
+
+Our cloth material model still relies on a Lambertian diffuse BRDF. It is however slightly modified to be energy conservative (akin to the energy conservation of our clear coat material model) and offers an optional subsurface scattering term. This extra term is not physically based and can be used to simulate the scattering, partial absorption and re-emission of light in certain types of fabrics.
+</p><p>
+First, here is the diffuse term without the optional subsurface scattering:
+</p><p>
+$$\begin{equation}
+f_{d}(v,h) = \frac{c_{diff}}{\pi}(1 - F(v,h))
+\end{equation}$$
+</p><p>
+Where \(F(v,h)\) is the Fresnel term of the cloth specular BRDF in equation \(\ref{clothSpecularBRDF}\). In practice we've opted to leave out the \(1 - F(v, h)\) term in the diffuse component. The effect is a bit subtle and we deemed it wasn't worth the added cost.
+</p><p>
+Subsurface scattering is implemented using the wrapped diffuse lighting technique, in its energy conservative form:
+</p><p>
+$$\begin{equation}
+f_{d}(v,h) = \frac{c_{diff}}{\pi}(1 - F(v,h)) \left< \frac{\NoL + w}{(1 + w)^2} \right> \left< c_{subsurface} + \NoL \right>
+\end{equation}$$
+</p><p>
+Where \(w\) is a value between 0 and 1 defining by how much the diffuse light should wrap around the terminator. To avoid introducing another parameter, we fix \(w = 0.5\). Note that with wrap diffuse lighting, the diffuse term must not be multiplied by \(\NoL\). The effect of this cheap
+subsurface scattering approximation can be seen in <a href="#figure_materialclothsubsurface" target="_self">figure&nbsp;32</a>.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_materialclothsubsurface">&nbsp;</a><a href="../images/screenshot_cloth_subsurface.png" target="_blank"><img class="markdeep" src="../images/screenshot_cloth_subsurface.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;32:</b> White cloth (left column) vs white cloth with brown subsurface scattering (right)</span></center></div></center>
+</p><p>
+The complete implementation of our cloth BRDF, including sheen color and optional subsurface scattering, can be found in <a href="#listing_clothfullbrdf" target="_self">listing&nbsp;19</a>.
+</p><a class="target" name="listing_clothfullbrdf">&nbsp;</a><pre class="listing tilde"><code><span class="line"></span><span class="hljs-comment">// specular BRDF</span>
+<span class="line"></span><span class="hljs-type">float</span> D = distributionCloth(roughness, NoH);
+<span class="line"></span><span class="hljs-type">float</span> V = visibilityCloth(NoV, NoL);
+<span class="line"></span><span class="hljs-type">vec3</span>  F = sheenColor;
+<span class="line"></span><span class="hljs-type">vec3</span> Fr = (D * V) * F;
+<span class="line"></span>
+<span class="line"></span><span class="hljs-comment">// diffuse BRDF</span>
+<span class="line"></span><span class="hljs-type">float</span> diffuse = diffuse(roughness, NoV, NoL, LoH);
+<span class="line"></span><span class="hljs-meta">#if defined(MATERIAL_HAS_SUBSURFACE_COLOR)</span>
+<span class="line"></span><span class="hljs-comment">// energy conservative wrap diffuse</span>
+<span class="line"></span>diffuse *= saturate((<span class="hljs-built_in">dot</span>(n, light.l) + <span class="hljs-number">0.5</span>) / <span class="hljs-number">2.25</span>);
+<span class="line"></span><span class="hljs-meta">#endif</span>
+<span class="line"></span><span class="hljs-type">vec3</span> Fd = diffuse * pixel.diffuseColor;
+<span class="line"></span>
+<span class="line"></span><span class="hljs-meta">#if defined(MATERIAL_HAS_SUBSURFACE_COLOR)</span>
+<span class="line"></span><span class="hljs-comment">// cheap subsurface scatter</span>
+<span class="line"></span>Fd *= saturate(subsurfaceColor + NoL);
+<span class="line"></span><span class="hljs-type">vec3</span> color = Fd + Fr * NoL;
+<span class="line"></span>color *= (lightIntensity * lightAttenuation) * lightColor;
+<span class="line"></span><span class="hljs-meta">#else</span>
+<span class="line"></span><span class="hljs-type">vec3</span> color = Fd + Fr;
+<span class="line"></span>color *= (lightIntensity * lightAttenuation * NoL) * lightColor;
+<span class="line"></span><span class="hljs-meta">#endif</span></code></pre><center><div class="listingcaption tilde"><b style="font-style:normal;">Listing&nbsp;19:</b> Implementation of our cloth BRDF in GLSL</div></center>
+<a class="target" name="clothparameterization">&nbsp;</a><a class="target" name="materialsystem/clothmodel/clothparameterization">&nbsp;</a><a class="target" name="toc4.12.3">&nbsp;</a><h3>Cloth parameterization</h3>
+<p>
+
+The cloth material model encompasses all the parameters previously defined for the standard material mode except for <em class="underscore">metallic</em> and <em class="underscore">reflectance</em>. Two extra parameters described in <a href="#table_clothparameters" target="_self">table&nbsp;8</a> are also available.
+</p><p>
+<div class='table'>
+<a class="target" name="table_clothparameters">&nbsp;</a><table class="table"><tr><th  style="text-align:right"> Parameter </th><th  style="text-align:left"> Definition </th></tr>
+<tr><td  style="text-align:right"> <strong class="asterisk">SheenColor</strong> </td><td  style="text-align:left"> Specular tint to create two-tone specular fabrics (defaults to 0.04 to match the standard reflectance) </td></tr>
+<tr><td  style="text-align:right"> <strong class="asterisk">SubsurfaceColor</strong> </td><td  style="text-align:left"> Tint for the diffuse color after scattering and absorption through the material </td></tr>
+</table><center><div class="tablecaption"><b style="font-style:normal;">Table&nbsp;8:</b> Cloth model parameters</div></center></div>
+</p><p>
+To create a velvet-like material, the base color can be set to black (or a dark color). Chromaticity information should instead be set on the sheen color. To create more common fabrics such as denim, cotton, etc. use the base color for chromaticity and use the default sheen color or set the sheen color to the luminance of the base color.
+</p>
+<a class="target" name="lighting">&nbsp;</a><a class="target" name="lighting">&nbsp;</a><a class="target" name="toc5">&nbsp;</a><h1>Lighting</h1>
+<p>
+
+The correctness and coherence of the lighting environment is paramount to achieving plausible visuals. After surveying existing rendering engines (such as Unity or Unreal Engine 4) as well as the traditional real-time rendering literature, it is obvious that coherency is rarely achieved.
+</p><p>
+The Unreal Engine, for instance, lets artists specify the &ldquo;brightness&rdquo; of a point light in lumens, a unit of luminous power. The brightness of directional lights is however expressed using an arbitrary unnamed unit. To match the brightness of a point light with a luminous power of 5,000 lumens, the artist must use a directional light of brightness 10. This kind of mismatch makes it difficult for artists to maintain the visual integrity of a scene when adding, removing or modifying lights.
+Using solely arbitrary units is a coherent solution but it makes reusing lighting rigs a difficult task. For instance, an outdoor scene will use a directional light of brightness 10 as the sun and all other lights will be defined relative to that value. Moving these lights to an indoor environment would make them too bright.
+</p><p>
+Our goal is therefore to make all lighting correct by default, while giving artists enough freedom to achieve the desired look. We will support a number of lights, split in two categories, direct and indirect lighting:
+</p><p>
+<strong class="asterisk">Direct lighting</strong>: punctual lights, photometric lights, area lights.
+</p><p>
+<strong class="asterisk">Indirect lighting</strong>: image based lights (IBLs), for both local<sup><a href="#endnote-localprobesmobile" target="_self">2</a></sup> and distant light probes.
+</p><p>
+<div class="endnote"><a class="target" name="endnote-localprobesmobile">&nbsp;</a><sup>2</sup> Local light probes might be too expensive to support on mobile, we will first focus our efforts on distant light probes set at infinity
+</div>
+</p>
+<a class="target" name="units">&nbsp;</a><a class="target" name="lighting/units">&nbsp;</a><a class="target" name="toc5.1">&nbsp;</a><h2>Units</h2>
+<p>
+
+The following sections will discuss how to implement various types of lights and the proposed equations make use of different symbols and units summarized in <a href="#table_lightunits" target="_self">table&nbsp;9</a>.
+</p><p>
+<div class='table'>
+<a class="target" name="table_lightunits">&nbsp;</a><table class="table"><tr><th  style="text-align:right"> Photometric term </th><th  style="text-align:center"> Notation </th><th  style="text-align:left"> Unit </th></tr>
+<tr><td  style="text-align:right"> Luminous power </td><td  style="text-align:center"> \(\Phi\) </td><td  style="text-align:left"> Lumen (\(lm\)) </td></tr>
+<tr><td  style="text-align:right"> Luminous intensity </td><td  style="text-align:center"> \(I\) </td><td  style="text-align:left"> Candela (\(cd\)) or \(\frac{lm}{sr}\) </td></tr>
+<tr><td  style="text-align:right"> Illuminance </td><td  style="text-align:center"> \(E\) </td><td  style="text-align:left"> Lux (\(lx\)) or \(\frac{lm}{m^2}\) </td></tr>
+<tr><td  style="text-align:right"> Luminance </td><td  style="text-align:center"> \(L\) </td><td  style="text-align:left"> Nit (\(nt\)) or \(\frac{cd}{m^2}\) </td></tr>
+<tr><td  style="text-align:right"> Radiant power </td><td  style="text-align:center"> \(\Phi_e\) </td><td  style="text-align:left"> Watt (\(W\)) </td></tr>
+<tr><td  style="text-align:right"> Luminous efficacy </td><td  style="text-align:center"> \(\eta\) </td><td  style="text-align:left"> Lumens per watt (\(\frac{lm}{W}\)) </td></tr>
+<tr><td  style="text-align:right"> Luminous efficiency </td><td  style="text-align:center"> \(V\) </td><td  style="text-align:left"> Percentage (%) </td></tr>
+</table><center><div class="tablecaption"><b style="font-style:normal;">Table&nbsp;9:</b> Photometric units</div></center></div>
+</p><p>
+To get properly coherent lighting, we must use light units that respect the ratio between various light intensities found in real-world scenes. These intensities can vary greatly, from around 800 \(lm\) for a household light bulb to 120,000 \(lx\) for a daylight sky and sun illumination.
+</p><p>
+The easiest way to achieve lighting coherency is to adopt physical light units. This will in turn enable full reusability of lighting rigs. Using physical light units also allows us to use a physically based camera.
+</p><p>
+<a href="#table_lighttypesunits" target="_self">Table&nbsp;10</a> shows the light unit associated with each type of light we intend to support.
+</p><p>
+<div class='table'>
+<a class="target" name="table_lighttypesunits">&nbsp;</a><table class="table"><tr><th  style="text-align:right"> Light type </th><th  style="text-align:left"> Unit </th></tr>
+<tr><td  style="text-align:right"> Directional light </td><td  style="text-align:left"> Illuminance (\(lx\) or \(\frac{lm}{m^2}\)) </td></tr>
+<tr><td  style="text-align:right"> Point light </td><td  style="text-align:left"> Luminous power (\(lm\)) </td></tr>
+<tr><td  style="text-align:right"> Spot light </td><td  style="text-align:left"> Luminous power (\(lm\)) </td></tr>
+<tr><td  style="text-align:right"> Photometric light </td><td  style="text-align:left"> Luminous intensity (\(cd\)) </td></tr>
+<tr><td  style="text-align:right"> Masked photometric light </td><td  style="text-align:left"> Luminous power (\(lm\)) </td></tr>
+<tr><td  style="text-align:right"> Area light </td><td  style="text-align:left"> Luminous power (\(lm\)) </td></tr>
+<tr><td  style="text-align:right"> Image based light </td><td  style="text-align:left"> Luminance (\(\frac{cd}{m^2}\)) </td></tr>
+</table><center><div class="tablecaption"><b style="font-style:normal;">Table&nbsp;10:</b> Intensity unity for each light type</div></center></div>
+</p><p>
+<strong class="asterisk">Notes about the radiant power unit</strong>
+</p><p>
+Even though commercially available light bulbs often display their brightness in lumens on the packaging, it is common to refer to the brightness of a light bulb by using its required energy in watts. The number of watts only indicates how much energy a bulb uses, not how bright it is. It is even more important to understand this difference now that more energy efficient bulbs are readily available (halogens, LEDs, etc.).
+</p><p>
+However, since artists might be accustomed to gauging a light's brightness by its power, we should allow users to use the power unit to define the brightness of a light. The conversion is presented in equation \(\ref{radiantPowerToLuminousPower}\).
+</p><p>
+$$\begin{equation}\label{radiantPowerToLuminousPower}
+\Phi = \Phi_e \eta
+\end{equation}$$
+</p><p>
+In equation \(\ref{radiantPowerToLuminousPower}\), \(\eta\) is the luminous efficacy of the light, expressed in lumens per watt. Knowing that the <a href="http://en.wikipedia.org/wiki/Luminous_efficacy">maximum possible luminous efficacy</a> is 683 \(\frac{lm}{W}\) we can also use luminous efficiency \(V\) (also called luminous coefficient), as shown in equation \(\ref{radiantPowerLuminousEfficiency}\).
+</p><p>
+$$\begin{equation}\label{radiantPowerLuminousEfficiency}
+\Phi = \Phi_e 683 \times V
+\end{equation}$$
+</p><p>
+<a href="#table_lighttypesefficacy" target="_self">Table&nbsp;11</a> can be used as a reference to convert watts to lumens using either the luminous efficacy or the luminous efficiency of various types of lights. More specific values are available on Wikipedia's <a href="http://en.wikipedia.org/wiki/Luminous_efficacy">luminous efficacy</a> page.
+</p><p>
+<div class='table'>
+<a class="target" name="table_lighttypesefficacy">&nbsp;</a><table class="table"><tr><th  style="text-align:right"> Light type </th><th  style="text-align:center"> Efficacy \(\eta\) </th><th  style="text-align:left"> Efficiency \(V\) </th></tr>
+<tr><td  style="text-align:right"> Incandescent </td><td  style="text-align:center"> 14-35 </td><td  style="text-align:left"> 2-5% </td></tr>
+<tr><td  style="text-align:right"> LED </td><td  style="text-align:center"> 28-100 </td><td  style="text-align:left"> 4-15% </td></tr>
+<tr><td  style="text-align:right"> Fluorescent </td><td  style="text-align:center"> 60-100 </td><td  style="text-align:left"> 9-15% </td></tr>
+</table><center><div class="tablecaption"><b style="font-style:normal;">Table&nbsp;11:</b> Efficacy and efficiency of various light types</div></center></div>
+</p>
+<a class="target" name="lightunitsvalidation">&nbsp;</a><a class="target" name="lighting/units/lightunitsvalidation">&nbsp;</a><a class="target" name="toc5.1.1">&nbsp;</a><h3>Light units validation</h3>
+<p>
+
+One of the big advantages of using physical light units is the ability to physically validate our equations. We can use specialized devices to measure three light units.
+</p>
+<a class="target" name="illuminance">&nbsp;</a><a class="target" name="lighting/units/lightunitsvalidation/illuminance">&nbsp;</a><a class="target" name="toc5.1.1.1">&nbsp;</a><h4>Illuminance</h4>
+<p>
+
+The illuminance reaching a surface can be measured using an incident light meter. For our tests, we use a <a href="http://www.sekonic.com/products/l-478d/overview.aspx">Sekonic L-478D</a>, shown in <a href="#figure_sekonic" target="_self">figure&nbsp;33</a>.
+</p><p>
+The incident light meter uses a white diffuse dome to capture the illuminance reaching a surface. It is important to orient the dome properly depending on the desired measurement. For instance, orienting the dome perpendicular to the sun on a bright clear day will give very different results than orienting the dome horizontally.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_sekonic">&nbsp;</a><a href="../images/photo_light_meter.jpg" target="_blank"><img class="markdeep" src="../images/photo_light_meter.jpg" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;33:</b> Sekonic L-478D incident light meter</span></center></div></center>
+</p>
+<a class="target" name="luminance">&nbsp;</a><a class="target" name="lighting/units/lightunitsvalidation/luminance">&nbsp;</a><a class="target" name="toc5.1.1.2">&nbsp;</a><h4>Luminance</h4>
+<p>
+
+The luminance at a surface, or the product of the incident light and the surface, can be measured using a luminance meter, also often called a spot meter. While incident light meters use a diffuse hemisphere to capture light from all directions, a spot meter uses a shield to measure incident light from a single direction. For our tests, we use a <a href="http://www.sekonic.com/products/l-478dr/accessories/np-finder-5-degree-for-l-478.aspx">Sekonic 5&deg; Viewfinder</a> that can replace the diffuser on the L-478D to measure luminance in a 5&deg; cone.
+</p><p>
+<center><div class="image" style=""><a href="../images/photo_incident_light_meter.jpg" target="_blank"><img class="markdeep" src="../images/photo_incident_light_meter.jpg" /></a><center><span class="imagecaption">Sekonic L-478D working as a luminance meter using a special viewfinder</span></center></div></center>
+</p>
+<a class="target" name="luminousintensity">&nbsp;</a><a class="target" name="lighting/units/lightunitsvalidation/luminousintensity">&nbsp;</a><a class="target" name="toc5.1.1.3">&nbsp;</a><h4>Luminous intensity</h4>
+<p>
+
+The luminous intensity of a light source cannot be measured directly but can be derived from the measured illuminance if we know the distance between the measuring device and the light source. Equation \(\ref{derivedLuminousIntensity}\) is a simple application of the inverse square law discussed in section <a href="#toc5.2.2" target="_self">5.2.2</a>.
+</p><p>
+$$\begin{equation}\label{derivedLuminousIntensity}
+I = E \cdot d^2
+\end{equation}$$
+</p>
+<a class="target" name="directlighting">&nbsp;</a><a class="target" name="lighting/directlighting">&nbsp;</a><a class="target" name="toc5.2">&nbsp;</a><h2>Direct lighting</h2>
+<p>
+
+We have defined the light units for all the light types supported by the renderer in the section above but we have not defined the light unit for the result of the lighting equations. Choosing physical light units means that we will compute luminance values in our shaders, and therefore that all our light evaluation functions will compute the luminance \(L_{out}\) (or outgoing radiance) at any given point. The luminance depends on the illuminance \(E\) and the BSDF \(f(v,l)\) :
+</p><p>
+$$\begin{equation}\label{luminanceEquation}
+L_{out} = f(v,l)E
+\end{equation}$$
+</p>
+<a class="target" name="directionallights">&nbsp;</a><a class="target" name="lighting/directlighting/directionallights">&nbsp;</a><a class="target" name="toc5.2.1">&nbsp;</a><h3>Directional lights</h3>
+<p>
+
+The main purpose of directional lights is to recreate important light sources for outdoor environment, i.e. the sun and/or the moon. While directional lights do not truly exist in the physical world, any light source sufficiently far from the light receptor can be assumed to be directional (i.e. all the incident light rays are parallel, as shown in  <a href="#figure_directionallight" target="_self">figure&nbsp;34</a>).
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_directionallight">&nbsp;</a><a href="../images/diagram_directional_light.png" target="_blank"><img class="markdeep" src="../images/diagram_directional_light.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;34:</b> Interaction between a directional light and a surface. The light source is a virtual construct that can only be represented by a direction</span></center></div></center>
+</p><p>
+This approximation proves to work incredibly well for the diffuse response of a surface but the specular response is incorrect. The Frostbite engine solves this problem by treating the &ldquo;sun&rdquo; directional light as a disc area light. However, our tests have shown that the quality increase does not justify the added computational costs.
+</p><p>
+We earlier stated that we chose an illuminance light unit (\(lx\)) for directional lights. This is in part due to the fact that we can easily find illuminance values for the sky and the sun (online or with a light meter) but also to simplify the luminance equation described in \(\ref{luminanceEquation}\).
+</p><p>
+$$\begin{equation}\label{directionalLuminanceEquation}
+L_{out} = f(v,l) E_{\bot} \left< \NoL \right>
+\end{equation}$$
+</p><p>
+In the simplified luminance equation \(\ref{directionalLuminanceEquation}\), \(E_{\bot}\) is the illuminance of the light source for a surface perpendicular to said light source. If the directional light source simulates the sun, \(E_{\bot}\) is the illuminance of the sun for a surface perpendicular to the sun direction.
+</p><p>
+<a href="#table_sunskyilluminance" target="_self">Table&nbsp;12</a> provides useful reference values for the sun and sky illumination, measured<sup><a href="#endnote-illuminancemeasures" target="_self">3</a></sup> on a clear day in March, in California.
+</p><p>
+<div class='table'>
+<a class="target" name="table_sunskyilluminance">&nbsp;</a><table class="table"><tr><th  style="text-align:right"> Light </th><th  style="text-align:right"> 10am </th><th  style="text-align:right"> 12pm </th><th  style="text-align:right"> 5:30pm </th></tr>
+<tr><td  style="text-align:right"> \(Sky_{\bot} + Sun_{\bot}\) </td><td  style="text-align:right"> 120,000 </td><td  style="text-align:right"> 130,000 </td><td  style="text-align:right"> 90,000 </td></tr>
+<tr><td  style="text-align:right"> \(Sky_{\bot}\) </td><td  style="text-align:right"> 20,000 </td><td  style="text-align:right"> 25,000 </td><td  style="text-align:right"> 9,000 </td></tr>
+<tr><td  style="text-align:right"> \(Sun_{\bot}\) </td><td  style="text-align:right"> 100,000 </td><td  style="text-align:right"> 105,000 </td><td  style="text-align:right"> 81,000 </td></tr>
+</table><center><div class="tablecaption"><b style="font-style:normal;">Table&nbsp;12:</b> Illuminance values in \(lx\) (a full moon has an illuminance of 1 \(lx\))</div></center></div>
+</p><p>
+Dynamic directional lights are particularly cheap to evaluate at runtime, as shown in <a href="#listing_glsldirectionallight" target="_self">listing&nbsp;20</a>.
+</p><a class="target" name="listing_glsldirectionallight">&nbsp;</a><pre class="listing tilde"><code><span class="line"></span><span class="hljs-type">vec3</span> l = <span class="hljs-built_in">normalize</span>(-lightDirection);
+<span class="line"></span><span class="hljs-type">float</span> NoL = <span class="hljs-built_in">clamp</span>(<span class="hljs-built_in">dot</span>(n, l), <span class="hljs-number">0.0</span>, <span class="hljs-number">1.0</span>);
+<span class="line"></span>
+<span class="line"></span><span class="hljs-comment">// lightIntensity is the illuminance</span>
+<span class="line"></span><span class="hljs-comment">// at perpendicular incidence in lux</span>
+<span class="line"></span><span class="hljs-type">float</span> illuminance = lightIntensity * NoL;
+<span class="line"></span><span class="hljs-type">vec3</span> luminance = BSDF(v, l) * illuminance;</code></pre><center><div class="listingcaption tilde"><b style="font-style:normal;">Listing&nbsp;20:</b> Implementation of directional lights in GLSL</div></center>
+<p>
+
+<a href="#figure_directionallighttest" target="_self">Figure&nbsp;35</a> shows the effect of lighting a simple scene with a directional light setup to approximate a midday Sun (illuminance set to 110,000 \(lx\)). For illustration purposes, only direct lighting is shown.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_directionallighttest">&nbsp;</a><a href="../images/screenshot_directional_light.png" target="_blank"><img class="markdeep" src="../images/screenshot_directional_light.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;35:</b> Series of dielectric materials of varying roughness under a directional light</span></center></div></center>
+</p><p>
+<div class="endnote"><a class="target" name="endnote-illuminancemeasures">&nbsp;</a><sup>3</sup> Measurements taken with an incident light meter (Sekonic L-478D)
+</div>
+</p>
+<a class="target" name="punctuallights">&nbsp;</a><a class="target" name="lighting/directlighting/punctuallights">&nbsp;</a><a class="target" name="toc5.2.2">&nbsp;</a><h3>Punctual lights</h3>
+<p>
+
+Our engine will support two types of punctual lights, commonly found in most if not all rendering engines: point lights and spot lights. These types of lights are traditionally physically inaccurate for two reasons:
+</p><p>
+<ol start=1>
+<li class="number">They are truly punctual and infinitesimally small.
+</li>
+<li class="number">They do not follow the <a href="http://en.wikipedia.org/wiki/Inverse-square_law">inverse square law</a>.</li></ol>
+</p><p>
+The first issue can be addressed with area lights but, given the cheaper nature of punctual lights it is deemed practical to use infinitesimally small punctual lights whenever possible.
+</p><p>
+The second issue is easy to fix. For a given punctual light, the perceived intensity decreases proportionally to the square of the distance from the viewer (more precisely, the light receptor).
+</p><p>
+For punctual lights following the inverse square law, the term \(E\) of equation \( \ref{luminanceEquation} \) is expressed in equation \(\ref{punctualLightEquation}\), where \(d\) is the distance from a point at the surface to the light.
+</p><p>
+$$\begin{equation}\label{punctualLightEquation}
+E = L_{in} \left< \NoL \right> = \frac{I}{d^2} \left< \NoL \right>
+\end{equation}$$
+</p><p>
+The difference between point and spot lights lies in how \(E\) is computed, and in particular how the luminous intensity \(I\) is computed from the luminous power \(\Phi\).
+</p>
+<a class="target" name="pointlights">&nbsp;</a><a class="target" name="lighting/directlighting/punctuallights/pointlights">&nbsp;</a><a class="target" name="toc5.2.2.1">&nbsp;</a><h4>Point lights</h4>
+<p>
+
+A point light is defined only by a position in space, as shown in <a href="#figure_pointlight" target="_self">figure&nbsp;36</a>.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_pointlight">&nbsp;</a><a href="../images/diagram_point_light.png" target="_blank"><img class="markdeep" src="../images/diagram_point_light.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;36:</b> Interaction between a point light and a surface. The attenuation only depends on the distance to the light</span></center></div></center>
+</p><p>
+The luminous power of a point light is calculated by integrating the luminous intensity over the light's solid angle, as show in equation \(\ref{pointLightLuminousPower}\). The luminous intensity can then be easily derived from the luminous power.
+</p><p>
+$$\begin{equation}\label{pointLightLuminousPower}
+\Phi = \int_{\Omega} I dl = \int_{0}^{2\pi} \int_{0}^{\pi} I d\theta d\phi = 4 \pi I \\
+I = \frac{\Phi}{4 \pi}
+\end{equation}$$
+</p><p>
+By simple substitution of \(I\) in \(\ref{punctualLightEquation}\) and \(E\) in \( \ref{luminanceEquation} \) we can formulate the luminance equation of a point light as a function of the luminous power (see \( \ref{pointLightLuminanceEquation} \)).
+</p><p>
+$$\begin{equation}\label{pointLightLuminanceEquation}
+L_{out} = f(v,l) \frac{\Phi}{4 \pi d^2} \left< \NoL \right>
+\end{equation}$$
+</p><p>
+<a href="#figure_pointlighttest" target="_self">Figure&nbsp;37</a> shows the effect of lighting a simple scene with a point light subject to distance attenuation. Light falloff is exaggerated for illustration purposes.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_pointlighttest">&nbsp;</a><a href="../images/screenshot_point_light.png" target="_blank"><img class="markdeep" src="../images/screenshot_point_light.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;37:</b> Inverse square law applied to point lights evaluation</span></center></div></center>
+</p>
+<a class="target" name="spotlights">&nbsp;</a><a class="target" name="lighting/directlighting/punctuallights/spotlights">&nbsp;</a><a class="target" name="toc5.2.2.2">&nbsp;</a><h4>Spot lights</h4>
+<p>
+
+A spot light is defined by a position in space, a direction vector and two cone angles, \( \theta_{inner} \) and \( \theta_{outer} \) (see <a href="#figure_spotlight" target="_self">figure&nbsp;38</a>). These two angles are used to define the angular falloff attenuation of the spot light. The light evaluation function of a spot light must therefore take into account both the inverse square law and these two angles to properly evaluate the luminance attenuation.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_spotlight">&nbsp;</a><a href="../images/diagram_spot_light.png" target="_blank"><img class="markdeep" src="../images/diagram_spot_light.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;38:</b> Interaction between a spot light and a surface. The attenuation depends on the distance to the light and the angle between the surface the spot light's direction vector</span></center></div></center>
+</p><p>
+Equation \( \ref{spotLightLuminousPower} \) describes how the luminous power of a spot light can be calculated in a similar fashion to point lights, using \( \theta_{outer} \) the outer angle of the spot light's cone in the range [0..\(\pi\)].
+</p><p>
+$$\begin{equation}\label{spotLightLuminousPower}
+\Phi = \int_{\Omega} I dl = \int_{0}^{2\pi} \int_{0}^{\theta_{outer}} I d\theta d\phi = 2 \pi (1 - cos\frac{\theta_{outer}}{2})I \\
+I = \frac{\Phi}{2 \pi (1 - cos\frac{\theta_{outer}}{2})}
+\end{equation}$$
+</p><p>
+While this formulation is physically correct, it makes spot lights a little difficult to use: changing the outer angle of the cone changes the illumination levels. <a href="#figure_spotlighttestfocused" target="_self">Figure&nbsp;39</a> shows the same scene lit by a spot light, with an outer angle of 55&deg; and an outer angle of 15&deg;. Observes how the illumination level increases as the cone aperture decreases.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_spotlighttestfocused">&nbsp;</a><a href="../images/screenshot_spot_light_focused.png" target="_blank"><img class="markdeep" src="../images/screenshot_spot_light_focused.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;39:</b> Comparison of spot light outer angles, 55&deg; (left) and 15&deg; (right)</span></center></div></center>
+</p><p>
+The coupling of illumination and the outer cone means that an artist cannot tweak the influence cone of a spot light without also changing the perceived illumination. It therefore makes sense to provide artists with a parameter to disable this coupling. Equations \( \ref{spotLightLuminousPowerB} \) shows how to formulate the luminous power for that purpose.
+</p><p>
+$$\begin{equation}\label{spotLightLuminousPowerB}
+\Phi = \pi I \\
+I = \frac{\Phi}{\pi} \\
+\end{equation}$$
+</p><p>
+With this new formulation to compute the luminous intensity, the test scene in <a href="#figure_spotlighttest" target="_self">figure&nbsp;40</a> exhibits similar illumination levels with both cone apertures.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_spotlighttest">&nbsp;</a><a href="../images/screenshot_spot_light.png" target="_blank"><img class="markdeep" src="../images/screenshot_spot_light.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;40:</b> Comparison of spot light outer angles, 55&deg; (left) and 15&deg; (right)</span></center></div></center>
+</p><p>
+This new formulation can also be considered physically based if the spot's reflector is replaced with a matte, diffuse mask that absorbs light perfectly.
+</p><p>
+The spot light evaluation function can be expressed in two ways:
+</p><p>
+<ul>
+<li class="minus"><strong class="asterisk">With a light absorber</strong>
+  $$\begin{equation}\label{spotAbsorber}
+  L_{out} = f(v,l) \frac{\Phi}{\pi d^2} \left< \NoL \right> \lambda(l)
+  \end{equation}$$
+</li>
+<li class="minus"><strong class="asterisk">With a light reflector</strong>
+  $$\begin{equation}\label{spotReflector}
+  L_{out} = f(v,l) \frac{\Phi}{2 \pi (1 - cos\frac{\theta_{outer}}{2}) d^2} \left< \NoL \right> \lambda(l)
+  \end{equation}$$</li></ul>
+</p><p>
+The term \( \lambda(l) \) in equations \( \ref{spotAbsorber} \) and \( \ref{spotReflector} \) is the spot's angle attenuation factor described in equation
+ \( \ref{spotAngleAtt} \) below.
+</p><p>
+$$\begin{equation}\label{spotAngleAtt}
+\lambda(l) = \frac{l \cdot spotDirection - cos\theta_{outer}}{cos\theta_{inner} - cos\theta_{outer}}
+\end{equation}$$
+</p>
+<a class="target" name="attenuationfunction">&nbsp;</a><a class="target" name="lighting/directlighting/punctuallights/attenuationfunction">&nbsp;</a><a class="target" name="toc5.2.2.3">&nbsp;</a><h4>Attenuation function</h4>
+<p>
+
+A proper evaluation of the inverse square law attenuation factor is mandatory for physically based punctual lights. The simple mathematical formulation is unfortunately impractical for implementation purposes:
+</p><p>
+<ol start=1>
+<li class="number">The division by the squared distance can lead to divides by 0 when objects intersect or &ldquo;touch&rdquo; light sources.
+</p><p>
+</li>
+<li class="number">The influence sphere of each light is infinite (\( \frac{I}{d^2} \) is asymptotic, it never reaches 0) which means that to correctly shade a pixel we need to evaluate every light in the world.</li></ol>
+</p><p>
+The first issue can be solved easily by setting the assumption that punctual lights are not truly punctual but instead small area lights. To do this we can simply treat punctual lights as spheres of 1 cm radius, as show in equation \(\ref{finitePunctualLight}\).
+</p><p>
+$$\begin{equation}\label{finitePunctualLight}
+E = \frac{I}{max(d^2, {0.01}^2)}
+\end{equation}$$
+</p><p>
+We can solve the second issue by introducing an influence radius for each light. There are several advantages to this solution. Tools can quickly show artists what parts of the world will be influenced by every light (the tool just needs to draw a sphere centered on each light). The rendering engine can cull lights more aggressively using this extra piece of information and artists/developers can assist the engine by manually tweaking the influence radius of a light.
+</p><p>
+Mathematically, the illuminance of a light should smoothly reach zero at the limit defined by the influence radius. [<a href="#citation-karis13b" target="_self">Karis13b</a>] proposes to window the inverse square function in such a way that the majority of the light's influence remains unaffected. The proposed windowing is described in equation \(\ref{attenuationWindowing}\), where \(r\) is the light's radius of influence.
+</p><p>
+$$\begin{equation}\label{attenuationWindowing}
+E = \frac{I}{max(d^2, {0.01}^2)} \left< 1 - \frac{d^4}{r^4} \right>^2
+\end{equation}$$
+</p><p>
+<a href="#listing_glslpunctuallight" target="_self">Listing&nbsp;21</a> demonstrates how to implement physically based punctual lights in GLSL. Note that the light intensity used in this piece of code is the luminous intensity \(I\) in \(cd\), converted from the luminous power  CPU-side. This snippet is not optimized and some of the computations can be offloaded to the CPU (for instance the square of the light's inverse falloff radius, or the spot scale and angle).
+</p><a class="target" name="listing_glslpunctuallight">&nbsp;</a><pre class="listing tilde"><code><span class="line"></span><span class="hljs-type">float</span> getSquareFalloffAttenuation(<span class="hljs-type">vec3</span> posToLight, <span class="hljs-type">float</span> lightInvRadius) {
+<span class="line"></span>    <span class="hljs-type">float</span> distanceSquare = <span class="hljs-built_in">dot</span>(posToLight, posToLight);
+<span class="line"></span>    <span class="hljs-type">float</span> factor = distanceSquare * lightInvRadius * lightInvRadius;
+<span class="line"></span>    <span class="hljs-type">float</span> smoothFactor = <span class="hljs-built_in">max</span>(<span class="hljs-number">1.0</span> - factor * factor, <span class="hljs-number">0.0</span>);
+<span class="line"></span>    <span class="hljs-keyword">return</span> (smoothFactor * smoothFactor) / <span class="hljs-built_in">max</span>(distanceSquare, <span class="hljs-number">1e-4</span>);
+<span class="line"></span>}
+<span class="line"></span>
+<span class="line"></span><span class="hljs-type">float</span> getSpotAngleAttenuation(<span class="hljs-type">vec3</span> l, <span class="hljs-type">vec3</span> lightDir,
+<span class="line"></span>        <span class="hljs-type">float</span> innerAngle, <span class="hljs-type">float</span> outerAngle) {
+<span class="line"></span>    <span class="hljs-comment">// the scale and offset computations can be done CPU-side</span>
+<span class="line"></span>    <span class="hljs-type">float</span> cosOuter = <span class="hljs-built_in">cos</span>(outerAngle);
+<span class="line"></span>    <span class="hljs-type">float</span> spotScale = <span class="hljs-number">1.0</span> / <span class="hljs-built_in">max</span>(<span class="hljs-built_in">cos</span>(innerAngle) - cosOuter, <span class="hljs-number">1e-4</span>)
+<span class="line"></span>    <span class="hljs-type">float</span> spotOffset = -cosOuter * spotScale
+<span class="line"></span>
+<span class="line"></span>    <span class="hljs-type">float</span> cd = <span class="hljs-built_in">dot</span>(<span class="hljs-built_in">normalize</span>(-lightDir), l);
+<span class="line"></span>    <span class="hljs-type">float</span> attenuation = <span class="hljs-built_in">clamp</span>(cd * spotScale + spotOffset, <span class="hljs-number">0.0</span>, <span class="hljs-number">1.0</span>);
+<span class="line"></span>    <span class="hljs-keyword">return</span> attenuation * attenuation;
+<span class="line"></span>}
+<span class="line"></span>
+<span class="line"></span><span class="hljs-type">vec3</span> evaluatePunctualLight() {
+<span class="line"></span>    <span class="hljs-type">vec3</span> l = <span class="hljs-built_in">normalize</span>(posToLight);
+<span class="line"></span>    <span class="hljs-type">float</span> NoL = <span class="hljs-built_in">clamp</span>(<span class="hljs-built_in">dot</span>(n, l), <span class="hljs-number">0.0</span>, <span class="hljs-number">1.0</span>);
+<span class="line"></span>    <span class="hljs-type">vec3</span> posToLight = lightPosition - worldPosition;
+<span class="line"></span>
+<span class="line"></span>    <span class="hljs-type">float</span> attenuation;
+<span class="line"></span>    attenuation  = getSquareFalloffAttenuation(posToLight, lightInvRadius);
+<span class="line"></span>    attenuation *= getSpotAngleAttenuation(l, lightDir, innerAngle, outerAngle);
+<span class="line"></span>
+<span class="line"></span>    <span class="hljs-type">vec3</span> luminance = (BSDF(v, l) * lightIntensity * attenuation * NoL) * lightColor;
+<span class="line"></span>    <span class="hljs-keyword">return</span> luminance;
+<span class="line"></span>}</code></pre><center><div class="listingcaption tilde"><b style="font-style:normal;">Listing&nbsp;21:</b> Implementation of punctual lights in GLSL</div></center>
+<a class="target" name="photometriclights">&nbsp;</a><a class="target" name="lighting/directlighting/photometriclights">&nbsp;</a><a class="target" name="toc5.2.3">&nbsp;</a><h3>Photometric lights</h3>
+<p>
+
+Punctual lights are an extremely practical and efficient way to light a scene but do not give artists enough control over the light distribution. The field of architectural lighting design concerns itself with designing lighting systems to serve humans needs by taking into account:
+</p><p>
+<ul>
+<li class="minus">The amount of light provided
+</li>
+<li class="minus">The color of the light
+</li>
+<li class="minus">The distribution of light within the space</li></ul>
+</p><p>
+The lighting system we have described so far can easily address the first two points but we need a way to define the distribution of light within the space. Light distribution is especially important for indoor scenes or for some types of outdoor scenes or even road lighting. <a href="#figure_lightdistributiontest" target="_self">Figure&nbsp;41</a> shows scenes where the light distribution is controlled by the artist. This type of distribution control is widely used when putting objects on display (museums, stores or galleries for instance).
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_lightdistributiontest">&nbsp;</a><a href="../images/screenshot_photometric_lights.png" target="_blank"><img class="markdeep" src="../images/screenshot_photometric_lights.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;41:</b> Controlling the distribution of a point light</span></center></div></center>
+</p><p>
+Photometric lights use a photometric profile to describe their intensity distribution. There are two commonly used formats, IES (Illuminating Engineering Society) and EULUMDAT (European Lumen Data format) but we will focus on the former. IES profiles are supported by many tools and engines, such as Unreal Engine 4, Frostbite, Renderman, Maya and Killzone. In addition, IES light profiles are commonly made available by bulbs and luminaires manufacturers (Philips offers <a href="http://www.usa.lighting.philips.com/connect/tools_literature/photometric_data_1.wpd">an extensive array of IES files</a> for download for instance). Photometric profiles are particularly useful when they measure a luminaire or light fixture, in which the light source is partially covered. The luminaire will block the light emitted in certain directions, thus shaping the light distribution.
+</p><p>
+<center><div class="image" style=""><a href="../images/photo_photometric_lights.jpg" target="_blank"><img class="markdeep" src="../images/photo_photometric_lights.jpg" /></a><center><span class="imagecaption">Example of a real world luminaires that can be described by photometric profiles</span></center></div></center>
+</p><p>
+An IES profile stores luminous intensity for various angles on a sphere around the measured light source. This spherical coordinate system is usually referred to as the photometric web, which can be visualized using specialized tools such as <a href="http://www.photometricviewer.com/">IESviewer</a>. <a href="#figure_xarrow" target="_self">Figure&nbsp;42</a> below shows the photometric web of the XArrow IES profile <a href="http://renderman.pixar.com/view/DP25764">provided by Pixar</a> for use with Renderman. This picture also shows a rendering in 3D space of the XArrow IES profile by our tool <code>lightgen</code>.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_xarrow">&nbsp;</a><a href="../images/screenshot_xarrow.png" target="_blank"><img class="markdeep" src="../images/screenshot_xarrow.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;42:</b> The XArrow IES profile rendered as a photometric web and as a point light in 3D space</span></center></div></center>
+</p><p>
+The IES format is poorly documented and it is not uncommon to find syntax variations between files found on the Internet. The best resource to understand IES profile is Ian Ashdown's &ldquo;Parsing the IESNA LM-63 photometric data file&rdquo; document [<a href="#citation-ashdown98" target="_self">Ashdown98</a>]. Succinctly, an IES profiles stores luminous intensities in candela at various angles around the light source. For each measured horizontal angle, a series of luminous intensities at different vertical angles is provided. It is however fairly common for measured light sources to be horizontally symmetrical. The XArrow profile shown above is a good example: intensities vary with vertical angles (vertical axis) but are symmetrical on the horizontal axis. The range of vertical angles in an IES profile is 0 to 180&deg; and the range of horizontal angles is 0 to 360&deg;.
+</p><p>
+<a href="#figure_lightensamples" target="_self">Figure&nbsp;43</a> shows the series of IES profiles provided by Pixar for Renderman, rendered using our <code>lightgen</code> tool.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_lightensamples">&nbsp;</a><a href="../images/screenshot_lightgen_samples.png" target="_blank"><img class="markdeep" src="../images/screenshot_lightgen_samples.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;43:</b> Series of IES light profiles rendered with lightgen</span></center></div></center>
+</p><p>
+IES profiles can be applied directly to any punctual light, point or spot. To do so, we must first process the IES profile and generate a photometric profile as a texture. For performance considerations, the photometric profile we generate is a 1D texture that represents the average luminous intensity for all horizontal angles at a specific vertical angle (i.e., each pixel represents a vertical angle). To truly represent a photometric light, we should use a 2D texture but since most lights are fully, or mostly, symmetrical on the horizontal plane, we can accept this approximation. The values stored in the texture are normalized by the inverse maximum intensity defined in the IES profile. This allows us to easily store the texture in any float format or, at the cost of a bit of precision, in a luminance 8-bit texture (grayscale PNG for instance). Storing normalized values also allows us to treat photometric profiles as a mask:
+</p><p>
+<dl><dt>Photometric profile as a mask</dt><dd><p>    The luminous intensity is defined by the artist by setting the luminous power of the light, as with any other punctual light. The artist defined intensity is divided by the intensity of the light computed from the IES profile. IES profiles contain a luminous intensity but it is only valid for a bare light bulb whereas the measured intensity values take into account the light fixture. To measure the intensity of the luminaire, instead of the bulb, we perform a Monte-Carlo integration of the unit sphere using the intensities from the profile<sup><a href="#endnote-xarrowintensity" target="_self">4</a></sup>.
+</p></dd><dt>Photometric profile</dt><dd><p>    The luminous intensity comes from the profile itself. All the values sampled from the 1D texture are simply multiplied by the maximum intensity. We also provide a multiplier for convenience.
+</p></dd></dl>The photometric profile can be applied at rendering time as a simple attenuation. The luminance equation \( \ref{photometricLightEvaluation} \) describes the photometric point light evaluation function.
+</p><p>
+$$\begin{equation}\label{photometricLightEvaluation}
+L_{out} = f(v,l) \frac{I}{d^2} \left< \NoL \right> \Psi(l)
+\end{equation}$$
+</p><p>
+The term \( \Psi(l) \) is the photometric attenuation function. It depends on the light vector, but also on the direction of the light. Spot lights already possess a direction vector but we need to introduce one for photometric point lights as well.
+</p><p>
+The photometric attenuation function can be easily implemented in GLSL by adding a new attenuation factor to the implementation of punctual lights (<a href="#listing_glslpunctuallight" target="_self">listing&nbsp;21</a>). The modified implementation is show in <a href="#listing_glslphotometricpunctuallight" target="_self">listing&nbsp;22</a>.
+</p><a class="target" name="listing_glslphotometricpunctuallight">&nbsp;</a><pre class="listing tilde"><code><span class="line"></span><span class="hljs-type">float</span> getPhotometricAttenuation(<span class="hljs-type">vec3</span> posToLight, <span class="hljs-type">vec3</span> lightDir) {
+<span class="line"></span>    <span class="hljs-type">float</span> cosTheta = <span class="hljs-built_in">dot</span>(-posToLight, lightDir);
+<span class="line"></span>    <span class="hljs-type">float</span> angle = <span class="hljs-built_in">acos</span>(cosTheta) * (<span class="hljs-number">1.0</span> / PI);
+<span class="line"></span>    <span class="hljs-keyword">return</span> texture2DLodEXT(lightProfileMap, <span class="hljs-type">vec2</span>(angle, <span class="hljs-number">0.0</span>), <span class="hljs-number">0.0</span>).r;
+<span class="line"></span>}
+<span class="line"></span>
+<span class="line"></span><span class="hljs-type">vec3</span> evaluatePunctualLight() {
+<span class="line"></span>    <span class="hljs-type">vec3</span> l = <span class="hljs-built_in">normalize</span>(posToLight);
+<span class="line"></span>    <span class="hljs-type">float</span> NoL = <span class="hljs-built_in">clamp</span>(<span class="hljs-built_in">dot</span>(n, l), <span class="hljs-number">0.0</span>, <span class="hljs-number">1.0</span>);
+<span class="line"></span>    <span class="hljs-type">vec3</span> posToLight = lightPosition - worldPosition;
+<span class="line"></span>
+<span class="line"></span>    <span class="hljs-type">float</span> attenuation;
+<span class="line"></span>    attenuation  = getSquareFalloffAttenuation(posToLight, lightInvRadius);
+<span class="line"></span>    attenuation *= getSpotAngleAttenuation(l, lightDirection, innerAngle, outerAngle);
+<span class="line"></span>    attenuation *= getPhotometricAttenuation(l, lightDirection);
+<span class="line"></span>
+<span class="line"></span>    <span class="hljs-type">float</span> luminance = (BSDF(v, l) * lightIntensity * attenuation * NoL) * lightColor;
+<span class="line"></span>    <span class="hljs-keyword">return</span> luminance;
+<span class="line"></span>}</code></pre><center><div class="listingcaption tilde"><b style="font-style:normal;">Listing&nbsp;22:</b> Implementation of attenuation from photometric profiles in GLSL</div></center>
+<p>
+
+The light intensity is computed CPU-side (<a href="#listing_photometriclightintensity" target="_self">listing&nbsp;23</a>) and depends on whether the photometric profile is used as a mask.
+</p><a class="target" name="listing_photometriclightintensity">&nbsp;</a><pre class="listing tilde"><code><span class="line"></span><span class="hljs-type">float</span> multiplier;
+<span class="line"></span><span class="hljs-comment">// Photometric profile used as a mask</span>
+<span class="line"></span><span class="hljs-keyword">if</span> (photometricLight.<span class="hljs-built_in">isMasked</span>()) {
+<span class="line"></span>    <span class="hljs-comment">// The desired intensity is set by the artist</span>
+<span class="line"></span>    <span class="hljs-comment">// The integrated intensity comes from a Monte-Carlo</span>
+<span class="line"></span>    <span class="hljs-comment">// integration over the unit sphere around the luminaire</span>
+<span class="line"></span>    multiplier = photometricLight.<span class="hljs-built_in">getDesiredIntensity</span>() /
+<span class="line"></span>            photometricLight.<span class="hljs-built_in">getIntegratedIntensity</span>();
+<span class="line"></span>} <span class="hljs-keyword">else</span> {
+<span class="line"></span>    <span class="hljs-comment">// Multiplier provided for convenience, set to 1.0 by default</span>
+<span class="line"></span>    multiplier = photometricLight.<span class="hljs-built_in">getMultiplier</span>();
+<span class="line"></span>}
+<span class="line"></span>
+<span class="line"></span><span class="hljs-comment">// The max intensity in cd comes from the IES profile</span>
+<span class="line"></span><span class="hljs-type">float</span> lightIntensity = photometricLight.<span class="hljs-built_in">getMaxIntensity</span>() * multiplier;</code></pre><center><div class="listingcaption tilde"><b style="font-style:normal;">Listing&nbsp;23:</b> Computing the intensity of a photometric light on the CPU</div></center>
+<p>
+
+<div class="endnote"><a class="target" name="endnote-xarrowintensity">&nbsp;</a><sup>4</sup> The XArrow profile declares a luminous intensity of 1,750 lm but a Monte-Carlo integration shows an intensity of only 350 lm.
+</div>
+</p>
+<a class="target" name="arealights">&nbsp;</a><a class="target" name="lighting/directlighting/arealights">&nbsp;</a><a class="target" name="toc5.2.4">&nbsp;</a><h3>Area lights</h3>
+<p>
+
+[TODO]
+</p>
+<a class="target" name="lightsparameterization">&nbsp;</a><a class="target" name="lighting/directlighting/lightsparameterization">&nbsp;</a><a class="target" name="toc5.2.5">&nbsp;</a><h3>Lights parameterization</h3>
+<p>
+
+Similarly to the parameterization of the standard material model, our goal is to make lights parameterization intuitive and easy to use for artists and developers alike. In that spirit, we decided to separate the light color (or hue) from the light intensity. A light color will therefore be defined as a linear RGB color (or sRGB in the tools UI for convenience).
+</p><p>
+The full list of light parameters is presented in <a href="#table_lightparameters" target="_self">table&nbsp;13</a>.
+</p><p>
+<div class='table'>
+<a class="target" name="table_lightparameters">&nbsp;</a><table class="table longtable"><tr><th  style="text-align:right"> Parameter </th><th  style="text-align:left"> Definition </th></tr>
+<tr><td  style="text-align:right"> <strong class="asterisk">Type</strong> </td><td  style="text-align:left"> Directional, point, spot or area </td></tr>
+<tr><td  style="text-align:right"> <strong class="asterisk">Direction</strong> </td><td  style="text-align:left"> Used for directional lights, spot lights, photometric point lights, and linear and tubular area lights (orientation) </td></tr>
+<tr><td  style="text-align:right"> <strong class="asterisk">Color</strong> </td><td  style="text-align:left"> The color of emitted light, as a linear RGB color. Can be specified as an sRGB color or a color temperature in the tools </td></tr>
+<tr><td  style="text-align:right"> <strong class="asterisk">Intensity</strong> </td><td  style="text-align:left"> The light's brightness. The unit depends on the type of light </td></tr>
+<tr><td  style="text-align:right"> <strong class="asterisk">Falloff radius</strong> </td><td  style="text-align:left"> Maximum distance of influence </td></tr>
+<tr><td  style="text-align:right"> <strong class="asterisk">Inner angle</strong> </td><td  style="text-align:left"> Angle of the inner cone for spot lights, in degrees </td></tr>
+<tr><td  style="text-align:right"> <strong class="asterisk">Outer angle</strong> </td><td  style="text-align:left"> Angle of the outer cone for spot lights, in degrees </td></tr>
+<tr><td  style="text-align:right"> <strong class="asterisk">Length</strong> </td><td  style="text-align:left"> Length of the area light, used to create linear or tubular lights </td></tr>
+<tr><td  style="text-align:right"> <strong class="asterisk">Radius</strong> </td><td  style="text-align:left"> Radius of the area light, used to create spherical or tubular lights </td></tr>
+<tr><td  style="text-align:right"> <strong class="asterisk">Photometric profile</strong> </td><td  style="text-align:left"> Texture representing a photometric light profile, works only for punctual lights </td></tr>
+<tr><td  style="text-align:right"> <strong class="asterisk">Masked profile</strong> </td><td  style="text-align:left"> Boolean indicating whether the IES profile is used as a mask or not. When used as a mask, the light's brightness will be multiplied by the ratio between the user specified intensity and the integrated IES profile intensity. When not used as a mask, the user specified intensity is ignored but the IES multiplier is used instead </td></tr>
+<tr><td  style="text-align:right"> <strong class="asterisk">Photometric multiplier</strong> </td><td  style="text-align:left"> Brightness multiplier for photometric lights (if IES as mask is turned off) </td></tr>
+</table><center><div class="tablecaption"><b style="font-style:normal;">Table&nbsp;13:</b> Light types parameters</div></center></div>
+</p><p>
+<strong class="asterisk">Note</strong>: to simplify the implementation, all luminous powers will converted to luminous intensities (\(cd\)) before being sent to the shader. The conversion is light dependent and is explained in the previous sections.
+</p><p>
+<strong class="asterisk">Note</strong>: the light type can be inferred from other parameters (e.g. a point light has a length, radius, inner angle and outer angle of 0).
+</p>
+<a class="target" name="colortemperature">&nbsp;</a><a class="target" name="lighting/directlighting/lightsparameterization/colortemperature">&nbsp;</a><a class="target" name="toc5.2.5.1">&nbsp;</a><h4>Color temperature</h4>
+<p>
+
+However, real-world artificial lights are often defined by their color temperature, measured in Kelvin (K). The color temperature of a light source is the temperature of an ideal black-body radiator that radiates light of comparable hue to that of the light source. For convenience, the tools should allow the artist to specify the hue of a light source as a color temperature (a meaningful range is 1,000 K to 12,500 K).
+</p><p>
+To compute RGB values from a temperature, we can use the Planckian locus, shown in <a href="#figure_planckianlocus" target="_self">figure&nbsp;44</a>. This locus is the path that the color of an incandescent black body takes in a chromaticity space as the body's temperature changes.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_planckianlocus">&nbsp;</a><a href="../images/diagram_planckian_locus.png" target="_blank"><img class="markdeep" src="../images/diagram_planckian_locus.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;44:</b> The Planckian locus visualized on a CIE 1931 chromaticity diagram (source: Wikipedia)</span></center></div></center>
+</p><p>
+The easiest way to compute RGB values from this locus is to use the formula described in [<a href="#citation-krystek85" target="_self">Krystek85</a>]. Krystek's algorithm (equation \(\ref{krystek}\)) works in the CIE 1960 (UCS) space, using the following formula where \(T\) is the desired temperature, and \(u\) and \(v\) the coordinates in UCS.
+</p><p>
+$$\begin{equation}\label{krystek}
+u(T) = \frac{0.860117757 + 1.54118254 \times 10^{-4}T + 1.28641212 \times 10^{-7}T^2}{1 + 8.42420235 \times 10^{-4}T + 7.08145163 \times 10^{-7}T^2} \\
+v(T) = \frac{0.317398726 + 4.22806245
+ \times 10^{-5}T + 4.20481691 \times 10^{-8}T^2}{1 - 2.89741816
+ \times 10^{-5}T + 1.61456053 \times 10^{-7}T^2}
+\end{equation}$$
+</p><p>
+This approximation is accurate to roughly \( 9 \times 10^{-5} \) in the range 1,000K to 15,000K. From the CIE 1960 space we can compute the coordinates in xyY space (CIES 1931), using the formula from equation \(\ref{cieToxyY}\).
+</p><p>
+$$\begin{equation}\label{cieToxyY}
+x = \frac{3u}{2u - 8v + 4} \\
+y = \frac{2v}{2u - 8v + 4}
+\end{equation}$$
+</p><p>
+The formulas above are valid for black body color temperatures, and therefore correlated color temperatures of standard illuminants. If we wish to compute the precise chromaticity coordinates of standard CIE illuminants in the D series we can use equation \(\ref{seriesDtoxyY}\).
+</p><p>
+$$\begin{equation}\label{seriesDtoxyY}
+x = \begin{cases} 0.244063 + 0.09911 \frac{10^3}{T} + 2.9678 \frac{10^6}{T^2} - 4.6070 \frac{10^9}{T^3} & 4,000K \le T \le 7,000K \\
+0.237040 + 0.24748 \frac{10^3}{T} + 1.9018 \frac{10^6}{T^2} - 2.0064 \frac{10^9}{T^3} & 7,000K \le T \le 25,000K \end{cases} \\
+y = -3x^2 + 2.87 x - 0.275
+\end{equation}$$
+</p><p>
+From the xyY space, we can then convert to the CIE XYZ space (equation \(\ref{xyYtoXYZ}\)).
+</p><p>
+$$\begin{equation}\label{xyYtoXYZ}
+X = \frac{xY}{y} \\
+Z = \frac{(1 - x - y)Y}{y}
+\end{equation}$$
+</p><p>
+For our needs, we will fix \(Y = 1\). This allows us to convert from the XYZ space to linear RGB with a simple 3&times;3 matrix, as shown in equation \(\ref{XYZtoRGB}\).
+</p><p>
+$$\begin{equation}\label{XYZtoRGB}
+\left[ \begin{matrix} R \\ G \\ B \end{matrix} \right] = M^{-1} \left[ \begin{matrix} X \\ Y \\ Z \end{matrix} \right]
+\end{equation}$$
+</p><p>
+The transformation matrix M is calculated from the target RGB color space primaries. Equation \( \ref{XYZtoRGBValues} \) shows the conversion using the inverse matrix for the sRGB color space.
+</p><p>
+$$\begin{equation}\label{XYZtoRGBValues}
+\left[ \begin{matrix} R \\ G \\ B \end{matrix} \right] = \left[ \begin{matrix} 3.2404542 & -1.5371385 & -0.4985314 \\ -0.9692660 & 1.8760108 & 0.0415560 \\ 0.0556434 & -0.2040259 & 1.0572252 \end{matrix} \right] \left[ \begin{matrix} X \\ Y \\ Z \end{matrix} \right]
+\end{equation}$$
+</p><p>
+The result of these operations is a linear RGB triplet in the sRGB color space. Since we care about the chromaticity of the results, we must apply a normalization step to avoid clamping values greater than 1.0 and distort resulting colors:
+</p><p>
+$$\begin{equation}\label{normalizedRGB}
+\hat{C}_{linear} = \frac{C_{linear}}{max(C_{linear})}
+\end{equation}$$
+</p><p>
+We must finally apply the sRGB opto-electronic conversion function (OECF, shown in equation \( \ref{OECFsRGB} \)) to obtain a displayable value (the value should remain linear if passed to the renderer for shading).
+</p><p>
+$$\begin{equation}\label{OECFsRGB}
+C_{sRGB} = \begin{cases} 12.92 \times \hat{C}_{linear} & \hat{C}_{linear} \le 0.0031308 \\
+1.055 \times \hat{C}_{linear}^{\frac{1}{2.4}} - 0.055 & \hat{C}_{linear} \gt 0.0031308 \end{cases}
+\end{equation}$$
+</p><p>
+For convenience, <a href="#figure_colortemperaturescalecct" target="_self">figure&nbsp;45</a> shows the range of correlated color temperatures from 1,000K to 12,500K. All the colors used below assume CIE \( D_{65} \) as the white point (as is the case in the sRGB color space).
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_colortemperaturescalecct">&nbsp;</a><a href="../images/diagram_color_temperature_cct.png" target="_blank"><img class="markdeep" src="../images/diagram_color_temperature_cct.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;45:</b> Scale of correlated color temperatures</span></center></div></center>
+</p><p>
+Similarly, <a href="#figure_colortemperaturescalecie" target="_self">figure&nbsp;46</a> shows the range of CIE standard illuminants series D from 1,000K to 12,500K.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_colortemperaturescalecie">&nbsp;</a><a href="../images/diagram_color_temperature_cie.png" target="_blank"><img class="markdeep" src="../images/diagram_color_temperature_cie.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;46:</b> Scale of CIE standard illuminants series D</span></center></div></center>
+</p><p>
+For reference, <a href="#figure_colortemperaturescalecctclamped" target="_self">figure&nbsp;47</a> shows the range of correlated color temperatures without the normalization step presented in equation \(\ref{normalizedRGB}\).
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_colortemperaturescalecctclamped">&nbsp;</a><a href="../images/diagram_color_temperature_cct_clamped.png" target="_blank"><img class="markdeep" src="../images/diagram_color_temperature_cct_clamped.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;47:</b> Unnormalized scale of correlated color temperatures</span></center></div></center>
+</p><p>
+<a href="#table_colortemperaturesamples" target="_self">Table&nbsp;14</a> presents the correlated color temperature of various common light sources as sRGB color swatches. These colors are relative to the \( D_{65} \) white point, so their perceived hue might vary based on your display's white point. See <a href="http://jila.colorado.edu/~ajsh/colour/Tspectrum.html">What colour is the Sun?</a> for more information.
+</p><p>
+<div class='table'>
+<a class="target" name="table_colortemperaturesamples">&nbsp;</a><table class="table longtable"><tr><th  style="text-align:right"> Temperature (K) </th><th  style="text-align:left"> Light source </th><th  style="text-align:left"> Color </th></tr>
+<tr><td  style="text-align:right"> 1,700-1,800 </td><td  style="text-align:left"> Match flame </td><td  style="text-align:left"> <div style="background-color: #ff7d00; width: 60px">&nbsp;</div> </td></tr>
+<tr><td  style="text-align:right"> 1,850-1,930 </td><td  style="text-align:left"> Candle flame </td><td  style="text-align:left"> <div style="background-color: #ff8701; width: 60px">&nbsp;</div> </td></tr>
+<tr><td  style="text-align:right"> 2,000-3,000 </td><td  style="text-align:left"> Sun at sunrise/sunset </td><td  style="text-align:left"> <div style="background-color: #ffa64c; width: 60px">&nbsp;</div> </td></tr>
+<tr><td  style="text-align:right"> 2,500-2,900 </td><td  style="text-align:left"> Household tungsten lightbulb </td><td  style="text-align:left"> <div style="background-color: #ffb05e; width: 60px">&nbsp;</div> </td></tr>
+<tr><td  style="text-align:right"> 3,000 </td><td  style="text-align:left"> Tungsten lamp 1K </td><td  style="text-align:left"> <div style="background-color: #ffb86f; width: 60px">&nbsp;</div> </td></tr>
+<tr><td  style="text-align:right"> 3,200-3,500 </td><td  style="text-align:left"> Quartz lights </td><td  style="text-align:left"> <div style="background-color: #ffbf7b; width: 60px">&nbsp;</div> </td></tr>
+<tr><td  style="text-align:right"> 3,200-3,700 </td><td  style="text-align:left"> Fluorescent lights </td><td  style="text-align:left"> <div style="background-color: #ffbf7b; width: 60px">&nbsp;</div> </td></tr>
+<tr><td  style="text-align:right"> 3,275 </td><td  style="text-align:left"> Tungsten lamp 2K </td><td  style="text-align:left"> <div style="background-color: #ffc180; width: 60px">&nbsp;</div> </td></tr>
+<tr><td  style="text-align:right"> 3,380 </td><td  style="text-align:left"> Tungsten lamp 5K, 10K </td><td  style="text-align:left"> <div style="background-color: #ffc486; width: 60px">&nbsp;</div> </td></tr>
+<tr><td  style="text-align:right"> 5,000-5,400 </td><td  style="text-align:left"> Sun at noon </td><td  style="text-align:left"> <div style="background-color: #ffe9d7; width: 60px">&nbsp;</div> </td></tr>
+<tr><td  style="text-align:right"> 5,500-6,500 </td><td  style="text-align:left"> Daylight (sun + sky) </td><td  style="text-align:left"> <div style="background-color: #fff3f1; width: 60px">&nbsp;</div> </td></tr>
+<tr><td  style="text-align:right"> 5,500-6,500 </td><td  style="text-align:left"> Sun through clouds/haze </td><td  style="text-align:left"> <div style="background-color: #fff3f1; width: 60px">&nbsp;</div> </td></tr>
+<tr><td  style="text-align:right"> 6,000-7,500 </td><td  style="text-align:left"> Overcast sky </td><td  style="text-align:left"> <div style="background-color: #faf6ff; width: 60px">&nbsp;</div> </td></tr>
+<tr><td  style="text-align:right"> 6,500 </td><td  style="text-align:left"> RGB monitor white point </td><td  style="text-align:left"> <div style="background-color: #fff8fe; width: 60px">&nbsp;</div> </td></tr>
+<tr><td  style="text-align:right"> 7,000-8,000 </td><td  style="text-align:left"> Shaded areas outdoors </td><td  style="text-align:left"> <div style="background-color: #ebecff; width: 60px">&nbsp;</div> </td></tr>
+<tr><td  style="text-align:right"> 8,000-10,000 </td><td  style="text-align:left"> Partly cloudy sky </td><td  style="text-align:left"> <div style="background-color: #d6e0ff; width: 60px">&nbsp;</div> </td></tr>
+</table><center><div class="tablecaption"><b style="font-style:normal;">Table&nbsp;14:</b> Normalized correlated color temperatures for common light sources</div></center></div>
+</p>
+<a class="target" name="pre-exposedlights">&nbsp;</a><a class="target" name="lighting/directlighting/pre-exposedlights">&nbsp;</a><a class="target" name="toc5.2.6">&nbsp;</a><h3>Pre-exposed lights</h3>
+<p>
+
+Physically based rendering and physical light units pose an interesting challenge: how to store and handle the large range of values produced by the lighting code? Assuming computations performed at full precision in the shaders, we still want to be able to store the linear output of the lighting pass in a reasonably sized buffer (<code>RGB16F</code> or equivalent). The most obvious and easiest way to achieve this is to simply apply the camera exposure (see the <a href="#physicallybasedcamera" target="_self">Physically based camera</a> section for more information) before writing out the result of the lighting pass. This simple step is shown in <a href="#listing_preexposedlighting" target="_self">listing&nbsp;24</a>:
+</p><a class="target" name="listing_preexposedlighting">&nbsp;</a><pre class="listing tilde"><code><span class="line"></span>fragColor = luminance * camera.exposure;</code></pre><center><div class="listingcaption tilde"><b style="font-style:normal;">Listing&nbsp;24:</b> The output of the lighting pass is pre-exposed to fit in half-float buffers</div></center>
+<p>
+
+This solution solves the storage problem but requires intermediate computations to be performed with single precision floats. We would instead prefer to perform all (or at least most) of the lighting work using half precision floats instead. Doing so can greatly improve performance and power usage, particularly on mobile devices. Half precision floats are however ill-suited for this kind of work as common illuminance and luminance values (for the sun for instance) can exceed their range. The solution is to simply pre-expose the lights themselves instead of the result of the lighting pass. This can be done efficiently on the CPU if updating a light's constant buffer is cheap. This can also be done on the GPU, as shown in <a href="#listing_preexposedlights" target="_self">listing&nbsp;25</a>.
+</p><a class="target" name="listing_preexposedlights">&nbsp;</a><pre class="listing tilde"><code><span class="line"></span><span class="hljs-comment">// The inputs must be highp/single precision,</span>
+<span class="line"></span><span class="hljs-comment">// both for range (intensity) and precision (exposure)</span>
+<span class="line"></span><span class="hljs-comment">// The output is mediump/half precision</span>
+<span class="line"></span><span class="hljs-type">float</span> computePreExposedIntensity(<span class="hljs-keyword">highp</span> <span class="hljs-type">float</span> intensity, <span class="hljs-keyword">highp</span> <span class="hljs-type">float</span> exposure) {
+<span class="line"></span>    <span class="hljs-keyword">return</span> intensity * exposure;
+<span class="line"></span>}
+<span class="line"></span>
+<span class="line"></span>Light getPointLight(<span class="hljs-type">uint</span> <span class="hljs-keyword">index</span>) {
+<span class="line"></span>    Light light;
+<span class="line"></span>    <span class="hljs-type">uint</span> lightIndex = <span class="hljs-comment">// fetch light index;</span>
+<span class="line"></span>
+<span class="line"></span>    <span class="hljs-comment">// the intensity must be highp/single precision</span>
+<span class="line"></span>    <span class="hljs-keyword">highp</span> <span class="hljs-type">vec4</span> colorIntensity  = lightsUniforms.lights[lightIndex][<span class="hljs-number">1</span>];
+<span class="line"></span>
+<span class="line"></span>    <span class="hljs-comment">// pre-expose the light</span>
+<span class="line"></span>    light.colorIntensity.w = computePreExposedIntensity(
+<span class="line"></span>            colorIntensity.w, frameUniforms.exposure);
+<span class="line"></span>
+<span class="line"></span>    <span class="hljs-keyword">return</span> light;
+<span class="line"></span>}</code></pre><center><div class="listingcaption tilde"><b style="font-style:normal;">Listing&nbsp;25:</b> Pre-exposing lights allows the entire shading pipeline to use half precision floats</div></center>
+<p>
+
+In practice we pre-expose the following lights:
+</p><p>
+<ul>
+<li class="minus">Punctual lights (point and spot): on the GPU
+</li>
+<li class="minus">Directional light: on the CPU
+</li>
+<li class="minus">IBLs: on the CPU
+</li>
+<li class="minus">Material emissive: on the GPU</li></ul>
+</p>
+<a class="target" name="imagebasedlights">&nbsp;</a><a class="target" name="lighting/imagebasedlights">&nbsp;</a><a class="target" name="toc5.3">&nbsp;</a><h2>Image based lights</h2>
+<p>
+
+In real life, light comes from every direction either directly from light sources or indirectly after bouncing off objects in the environment, being partially absorbed in the process. In a way the whole environment around an object can be seen as a light source. Images, in particular cubemaps, are a great way to encode such an “environment light”. This is called Image Based Lighting (IBL) or sometimes Indirect Lighting.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_iblball">&nbsp;</a><a href="../images/screenshot_ball_ibl.png" target="_blank"><img class="markdeep" src="../images/screenshot_ball_ibl.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;48:</b> The object shown here is lit only by image-encoded environment lights. Notice the subtle lighting effects that can be applied using this technique.</span></center></div></center>
+</p><p>
+There are limitations with image-based lighting. Obviously the environment image must be acquired somehow and as we'll see below it needs to be pre-processed before it can be used for lighting. Typically, the environment image is acquired offline in the real world, or generated by the engine either offline or at run time; either way, local or distant probes are used.
+</p><p>
+These probes can be used to acquire the distant or local environment. In this document, we're focusing on distant environment probes, where the light is assumed to come from infinitely far away (which means every point on the object's surface uses the same environment map).
+</p><p>
+The whole environment contributes light to a given point on the object's surface; this is called <em class="underscore">irradiance</em> (\(E\)). The resulting light bouncing off of the object is called radiance (\(L_{out}\)). Incident lighting must be applied consistently to the diffuse and specular parts of the BRDF.
+</p><p>
+The radiance \(L_{out}\) resulting from the interaction between an image based light's (IBL) irradiance and a material model (BRDF) \(f(\Theta)\)<sup><a href="#endnote-ibl1" target="_self">5</a></sup> is computed as follows:
+</p><p>
+$$\begin{equation}
+L_{out}(n, v, \Theta) = \int_\Omega  f(l, v, \Theta) L_{\bot}(l) \left< \NoL \right> dl 
+\end{equation}$$ 
+</p><p>
+Note that here we're looking at the behavior of the surface at <strong class="asterisk">macro</strong> level (not to be confused with the micro level equation), which is why it only depends on \(\vec n\) and \(\vec v\). Essentially, we're applying the BRDF to “point-lights” coming from all directions and encoded in the IBL.
+</p>
+<a class="target" name="ibltypes">&nbsp;</a><a class="target" name="lighting/imagebasedlights/ibltypes">&nbsp;</a><a class="target" name="toc5.3.1">&nbsp;</a><h3>IBL Types </h3>
+<p>
+
+There are four common types of IBLs used in modern rendering engines:
+</p><p>
+<ul>
+<li class="minus"><strong class="asterisk">Distant light probes</strong>, used to capture lighting information at &ldquo;infinity&rdquo;, where parallax can be ignored. Distant probes typically contain the sky, distant landscape features or buildings, etc. They are either captured by the engine or acquired from a camera as high dynamic range images (HDRI).
+</p><p>
+</li>
+<li class="minus"><strong class="asterisk">Local light probes</strong>, used to capture a certain area of the world from a specific point of view. The capture is projected on a cube or sphere depending on the surrounding geometry. Local probes are more accurate than distance probes and are particularly useful to add local reflections to materials.
+</p><p>
+</li>
+<li class="minus"><strong class="asterisk">Planar reflections</strong>, used to capture reflections by rendering the scene mirrored by a plane. This technique works only for flat surfaces such as building floors, roads and water.
+</p><p>
+</li>
+<li class="minus"><strong class="asterisk">Screen space reflection</strong>, used to capture reflections based on the rendered scene (using the previous frame for instance) by ray-marching in the depth buffer. SSR gives great result but can be very expensive.</li></ul>
+</p><p>
+In addition we must distinguish between static and dynamic IBLs. Implementing a fully dynamic day/night cycle requires for instance to recompute the distant light probes dynamically<sup><a href="#endnote-ibltypes1" target="_self">6</a></sup>. Both planar and screen space reflections are inherently dynamic.
+</p>
+<a class="target" name="iblunit">&nbsp;</a><a class="target" name="lighting/imagebasedlights/iblunit">&nbsp;</a><a class="target" name="toc5.3.2">&nbsp;</a><h3>IBL Unit </h3>
+<p>
+
+As discussed previously in the direct <a href="#lighting" target="_self">lighting</a> section, all our lights must use physical units. As such our IBLs will use the luminance unit \(\frac{cd}{m^2}\), which is also the output unit of all our direct lighting equations. Using the luminance unit is straightforward for light probes captures by the engine (dynamically or statically offline).
+</p><p>
+High dynamic range images are a bit more delicate to handle however. Cameras do not record measured luminance but a device-dependent value that is only <em class="underscore">related</em> to the original scene luminance. As such, we must provide artists with a multiplier that allows them to recover, or at the very least closely approximate, the original absolute luminance.
+</p><p>
+To properly reconstruct the luminance of an HDRI for IBL, artists must do more than simply take photos of the environment and record extra information:
+</p><p>
+<ul>
+<li class="minus"><strong class="asterisk">Color calibration</strong>: using a gray card or a <a href="http://en.wikipedia.org/wiki/ColorChecker">MacBeth ColorChecker</a>
+</p><p>
+</li>
+<li class="minus"><strong class="asterisk">Camera settings</strong>: aperture, shutter and ISO
+</p><p>
+</li>
+<li class="minus"><strong class="asterisk">Luminance samples</strong>: using a spot/luminance meter</li></ul>
+</p><p>
+[TODO] Measure and list common luminance values (clear sky, interior, etc.)
+</p>
+<a class="target" name="processinglightprobes">&nbsp;</a><a class="target" name="lighting/imagebasedlights/processinglightprobes">&nbsp;</a><a class="target" name="toc5.3.3">&nbsp;</a><h3>Processing light probes </h3>
+<p>
+
+We saw previously that the radiance of an IBL is computed by integrating over the surface's hemisphere. Since this would obviously be too expensive to do in real-time, we must first pre-process our light probes to convert them into a format better suited for real-time interactions.
+</p><p>
+The sections below will discuss the techniques used to accelerate the evaluation of light probes:
+</p><p>
+<ul>
+<li class="minus"><strong class="asterisk">Specular reflectance</strong>: pre-filtered importance sampling and split-sum approximation
+</p><p>
+</li>
+<li class="minus"><strong class="asterisk">Diffuse reflectance</strong>: irradiance map and spherical harmonics</li></ul>
+</p>
+<a class="target" name="distantlightprobes">&nbsp;</a><a class="target" name="lighting/imagebasedlights/distantlightprobes">&nbsp;</a><a class="target" name="toc5.3.4">&nbsp;</a><h3>Distant light probes </h3>
+<a class="target" name="diffusebrdfintegration">&nbsp;</a><a class="target" name="lighting/imagebasedlights/distantlightprobes/diffusebrdfintegration">&nbsp;</a><a class="target" name="toc5.3.4.1">&nbsp;</a><h4>Diffuse BRDF integration </h4>
+<p>
+
+Using the Lambertian BRDF<sup><a href="#endnote-ibldiffuse1" target="_self">7</a></sup>, we get the radiance:
+</p><p>
+$$
+\begin{align*}
+   f_d(\sigma) &= \frac{\sigma}{\pi} \\
+L_d(n, \sigma) &= \int_{\Omega} f_d(\sigma) L_{\bot}(l) \left< \NoL \right> dl \\
+               &= \frac{\sigma}{\pi} \int_{\Omega} L_{\bot}(l) \left< \NoL \right> dl \\
+               &= \frac{\sigma}{\pi} E_d(n) \quad \text{with the irradiance} \; 
+        E_d(n) = \int_{\Omega} L_{\bot}(l) \left< \NoL \right> dl
+\end{align*}
+$$
+</p><p>
+Or in the discrete domain:
+</p><p>
+$$ E_d(n) \equiv \sum_{\forall \, i \in image} L_{\bot}(s_i) \left< n \cdot s_i \right> \Omega_s $$
+</p><p>
+\(\Omega_s\) is the solid-angle<sup><a href="#endnote-ibldiffuse2" target="_self">8</a></sup> associated to sample \(i\).
+</p><p>
+The irradiance integral \(\Ed\) can be trivially, albeit slowly<sup><a href="#endnote-ibldiffuse3" target="_self">9</a></sup>, precomputed and stored into a cubemap for efficient access at runtime. Typically, <em class="underscore">image</em> is a cubemap or an equirectangular image. The term \( \frac{\sigma}{\pi} \) is independent of the IBL and is added at runtime to obtain the <em class="underscore">radiance</em>.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_ibloriginal">&nbsp;</a><a href="../images/ibl/ibl_river_roughness_m0.png" target="_blank"><img class="markdeep" src="../images/ibl/ibl_river_roughness_m0.png" style="max-width:100%;" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;49:</b> Image-based environment</span></center></div></center>
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_iblirradiance">&nbsp;</a><a href="../images/ibl/ibl_irradiance.png" target="_blank"><img class="markdeep" src="../images/ibl/ibl_irradiance.png" style="max-width:100%;" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;50:</b> Image-based irradiance map using the Lambertian BRDF</span></center></div></center>
+</p><p>
+<div class="endnote"><a class="target" name="endnote-ibl1">&nbsp;</a><sup>5</sup> \(\Theta\) represents the parameters of the material model \(f\), i.e.: <em class="underscore">roughness</em>, albedo and so on...
+</div>
+</p><p>
+<div class="endnote"><a class="target" name="endnote-ibltypes1">&nbsp;</a><sup>6</sup> This can be done through blending of static probes or by spreading the workload over time
+</div>
+</p><p>
+<div class="endnote"><a class="target" name="endnote-ibldiffuse1">&nbsp;</a><sup>7</sup> The Lambertian BRDF doesn't depend on \(\vec l\), \(\vec v\) or \(\theta\), so \(L_d(n,v,\theta) \equiv L_d(n,\sigma)\)
+</div>
+</p><p>
+<div class="endnote"><a class="target" name="endnote-ibldiffuse2">&nbsp;</a><sup>8</sup> \(\Omega_s\) can be approximated by \(\frac{2\pi}{6 \cdot width \cdot height}\) for a cubemap
+</div>
+</p><p>
+<div class="endnote"><a class="target" name="endnote-ibldiffuse3">&nbsp;</a><sup>9</sup> \(O(12\,n^2\,m^2)\), with \(n\) and \(m\) respectively the dimensions of the environment and the precomputed cubemap
+</div>
+</p><p>
+However, the irradiance can also be approximated very closely by a decomposition into Spherical Harmonics (SH, described in more details in the <a href="#sphericalharmonics" target="_self">Spherical Harmonics</a> section) and calculated at runtime cheaply. It is usually best to avoid texture fetches on mobile and free-up a texture unit. Even if it is stored into a cubemap, it is orders of magnitude faster to pre-compute the integral using SH decomposition followed by a rendering.
+</p><p>
+SH decomposition is similar in concept to a Fourier transform, it expresses the signal over an orthonormal base in the frequency domain. The properties that interests us most are:
+</p><p>
+<ul>
+<li class="minus">Very few coefficients are needed to encode \(\cosTheta\)
+</p><p>
+</li>
+<li class="minus">Convolutions by a kernel that <em class="underscore">has a circular symmetry</em> are very inexpensive and become products in SH space</li></ul>
+</p><p>
+In practice only 4 or 9 coefficients (i.e.: 2 or 3 bands) are enough for \(\cosTheta\) meaning we don't need more either for \(\Lt\).
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_iblsh3">&nbsp;</a><a href="../images/ibl/ibl_irradiance_sh3.png" target="_blank"><img class="markdeep" src="../images/ibl/ibl_irradiance_sh3.png" style="max-width:100%;" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;51:</b> 3 bands (9 coefficients)</span></center></div></center>
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_iblsh2">&nbsp;</a><a href="../images/ibl/ibl_irradiance_sh2.png" target="_blank"><img class="markdeep" src="../images/ibl/ibl_irradiance_sh2.png" style="max-width:100%;" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;52:</b> 2 bands (4 coefficients)</span></center></div></center>
+</p><p>
+In practice we pre-convolve \(\Lt\) with \(\cosTheta\) and pre-scale these coefficients by the basis scaling factors \(K_l^m\) so that the reconstruction code is as simple as possible in the shader:
+</p><a class="target" name="listing_irradiancesh">&nbsp;</a><pre class="listing tilde"><code><span class="line"></span>vec3 irradianceSH(vec3 n) {
+<span class="line"></span>    // uniform vec3 sphericalHarmonics<span class="hljs-selector-attr">[9]</span>
+<span class="line"></span>    // We can use only the first <span class="hljs-number">2</span> bands for better performance
+<span class="line"></span>    return
+<span class="line"></span>          sphericalHarmonics<span class="hljs-selector-attr">[0]</span>
+<span class="line"></span>        + sphericalHarmonics<span class="hljs-selector-attr">[1]</span> * (n<span class="hljs-selector-class">.y</span>)
+<span class="line"></span>        + sphericalHarmonics<span class="hljs-selector-attr">[2]</span> * (n<span class="hljs-selector-class">.z</span>)
+<span class="line"></span>        + sphericalHarmonics<span class="hljs-selector-attr">[3]</span> * (n<span class="hljs-selector-class">.x</span>)
+<span class="line"></span>        + sphericalHarmonics<span class="hljs-selector-attr">[4]</span> * (n<span class="hljs-selector-class">.y</span> * n<span class="hljs-selector-class">.x</span>)
+<span class="line"></span>        + sphericalHarmonics<span class="hljs-selector-attr">[5]</span> * (n<span class="hljs-selector-class">.y</span> * n<span class="hljs-selector-class">.z</span>)
+<span class="line"></span>        + sphericalHarmonics<span class="hljs-selector-attr">[6]</span> * (<span class="hljs-number">3.0</span> * n<span class="hljs-selector-class">.z</span> * n<span class="hljs-selector-class">.z</span> - <span class="hljs-number">1.0</span>)
+<span class="line"></span>        + sphericalHarmonics<span class="hljs-selector-attr">[7]</span> * (n<span class="hljs-selector-class">.z</span> * n<span class="hljs-selector-class">.x</span>)
+<span class="line"></span>        + sphericalHarmonics<span class="hljs-selector-attr">[8]</span> * (n<span class="hljs-selector-class">.x</span> * n<span class="hljs-selector-class">.x</span> - n<span class="hljs-selector-class">.y</span> * n<span class="hljs-selector-class">.y</span>);
+<span class="line"></span>}</code></pre><center><div class="listingcaption tilde"><b style="font-style:normal;">Listing&nbsp;26:</b> GLSL code to reconstruct the irradiance from the pre-scaled SH</div></center>
+<p>
+
+Note that with 2 bands, the computation above becomes a single \(4 \times 4\) matrix-by-vector multiply.
+</p><p>
+Additionally, because of the pre-scaling by \(K_l^m\), the SH coefficients can be thought of as colors, in particular <code>sphericalHarmonics[0]</code> is directly the average irradiance.
+</p>
+<a class="target" name="specularbrdfintegration">&nbsp;</a><a class="target" name="lighting/imagebasedlights/distantlightprobes/specularbrdfintegration">&nbsp;</a><a class="target" name="toc5.3.4.2">&nbsp;</a><h4>Specular BRDF integration </h4>
+<p>
+
+As we've seen above, the radiance \(\Lout\) resulting from the interaction between an IBL's irradiance and a BRDF is:
+</p><p>
+$$\begin{equation}\label{specularBRDFIntegration}
+\Lout(n, v, \Theta) = \int_\Omega f(l, v, \Theta) \Lt(l) \left< \NoL \right> \partial l 
+\end{equation}$$ 
+</p><p>
+We recognize the convolution of \(\Lt\) by \(f(l, v, \Theta) \left< \NoL \right>\), 
+i.e.: the environment is <em class="asterisk">filtered</em> using the BRDF as a kernel. Indeed at higher roughness, 
+specular reflections look more <em class="asterisk">blurry</em>.
+</p><p>
+Plugging the expression of \(f\) in equation \(\ref{specularBRDFIntegration}\), we obtain:
+</p><p>
+$$\begin{equation}
+\Lout(n,v,\Theta) = \int_\Omega D(l, v, \alpha) F(l, v, f_0, f_{90}) V(l, v, \alpha) \left< \NoL \right> \Lt(l) \partial l
+\end{equation}$$ 
+</p><p>
+This expression depends on \(v\), \(\alpha\), \(f_0\) and \(f_{90}\) inside the integral, 
+which makes its evaluation extremely costly and unsuitable for real-time on mobile 
+(even using pre-filtered importance sampling). 
+</p>
+<a class="target" name="simplifyingthebrdfintegration">&nbsp;</a><a class="target" name="lighting/imagebasedlights/distantlightprobes/specularbrdfintegration/simplifyingthebrdfintegration">&nbsp;</a><a class="target" name="toc5.3.4.2.1">&nbsp;</a><h5>Simplifying the BRDF integration </h5>
+<p>
+
+Since there is no closed-form solution or an easy way to compute the \(\Lout\) integral, we use a simplified
+equation instead: \(\hat{I}\), whereby we assume that \(v = n\), that is the view direction \(v\) is always
+equal to the surface normal \(n\). Clearly, this assumption will break all view-dependant effects of 
+the convolution, such as the increased blur in reflections closer to the viewer 
+(a.k.a. stretchy reflections). 
+</p><p>
+Such a simplification would also have a severe impact on constant environments, such as the white 
+furnace, because it would affect the magnitude of the constant (i.e. DC) term of the result. We
+can at least correct for that by using a scale factor, \(K\), in our simplified integral, which
+will make sure the average irradiance stay correct when chosen properly.
+</p><p>
+<ul>
+    <li class="minus">\(I\) is our original integral, i.e.: \(I(g) = \int_\Omega g(l) \left< \NoL \right> \partial l\)
+</li>
+    <li class="minus">\(\hat{I}\) is the simplified integral where \(v = n\)
+</li>
+    <li class="minus">\(K\) is a scale factor that ensures the average irradiance is unchanged by \(\hat{I}\)
+</li>
+    <li class="minus">\(\tilde{I}\) is our final approximation of \(I\), \(\tilde{I} = \hat{I} \times K\)</li></ul>
+</p><p>
+Because \(I\) is an integral multiplications can be distributed over it. i.e.: \(I(g()f()) = I(g())I(f())\).
+</p><p>
+Armed with that,
+</p><p>
+$$\begin{equation}
+I( f(\Theta) \Lt ) \approx \tilde{I}( f(\Theta) \Lt )                       \\
+\tilde{I}( f(\Theta) \Lt ) = K \times \hat{I}( f(\Theta) \Lt )              \\
+K = \frac{I(f(\Theta))}{\hat{I}(f(\Theta))}
+\end{equation}$$ 
+</p><p>
+From the equation above we can see that \(\tilde{I}\) is equivalent to \(I\)  when \(\Lt\) is a constant,
+and yields the correct result:
+</p><p>
+$$\begin{align*}
+\tilde{I}(f(\Theta)\Lt^{constant}) &= \Lt^{constant} \hat{I}(f(\Theta)) \frac{I(f(\Theta))}{\hat{I}(f(\Theta))} \\
+                                   &= \Lt^{constant} I(f(\Theta))                                               \\
+                                   &= I(f(\Theta)\Lt^{constant})
+\end{align*}$$
+</p><p>
+Similarly, we can also demonstrate that the result is correct when \(v = n\), since in that case \(I = \hat{I}\):
+</p><p>
+$$\begin{align*}
+\tilde{I}(f(\Theta)\Lt) &= I(f(\Theta)\Lt) \frac{I(f(\Theta))}{I(f(\Theta))}    \\
+                        &= I(f(\Theta)\Lt)
+\end{align*}$$
+</p><p>
+Finally, we can show that the scale factor \(K\) satisfies our average irradiance (\(\bar{\Lt}\))
+requirement by plugging \(\Lt = \bar{\Lt} + (\Lt - \bar{\Lt}) = \bar{\Lt} + \Delta\Lt\) into \(\tilde{I}\):
+</p><p>
+$$\begin{align*}
+\tilde{I}(f(\Theta)\Lt) &= \tilde{I}\left[f\left(\Theta\right) \left(\bar{\Lt} + \Delta\Lt\right)\right] \\
+                        &= K \times \hat{I}\left[f\left(\Theta\right) \left(\bar{\Lt} + \Delta\Lt\right)\right] \\
+                        &= K \times \left[\hat{I}\left(f\left(\Theta\right)\bar{\Lt}\right) + \hat{I}\left(f\left(\Theta\right)\Delta\Lt\right)\right] \\ 
+                        &= K \times \hat{I}\left(f\left(\Theta\right)\bar{\Lt}\right) + K \times \hat{I}\left(f\left(\Theta\right) \Delta\Lt\right) \\
+                        &= \tilde{I}\left(f\left(\Theta\right)\bar{\Lt}\right) + \tilde{I}\left(f\left(\Theta\right) \Delta\Lt\right) \\
+                        &= I\left(f\left(\Theta\right)\bar{\Lt}\right) + \tilde{I}\left(f\left(\Theta\right) \Delta\Lt\right)
+\end{align*}$$
+</p><p>
+The above result shows that the average irradiance is computed correctly, i.e.: \(I(f(\Theta)\bar{\Lt})\).
+</p><p>
+A way to think about this approximation is that it splits the radiance \(\Lt\) in two parts, 
+the average \(\bar{\Lt}\) and the delta from the average \(\Delta\Lt\) and computes the correct
+integration of the average part then adds the simplified integration of the delta part:
+</p><p>
+$$\begin{equation}
+approximation(\Lt) = correct(\bar{\Lt}) + simplified(\Lt - \bar{\Lt})
+\end{equation}$$ 
+</p><p>
+Now, let's look at each term:
+</p><p>
+$$\begin{equation}\label{iblPartialEquations}
+\hat{I}(f(n, \alpha) \Lt) = \int_\Omega f(l, n, \alpha) \Lt(l) \left< \NoL \right> \partial l   \\
+\hat{I}(f(n, \alpha))     = \int_\Omega f(l, n, \alpha)        \left< \NoL \right> \partial l   \\
+I(f(n, v, \alpha))        = \int_\Omega f(l, n, v, \alpha)     \left< \NoL \right> \partial l
+\end{equation}$$
+</p><p>
+All three of these equations can be easily pre-calculated and stored in look-up tables, as explained 
+below.
+</p>
+<a class="target" name="discretedomain">&nbsp;</a><a class="target" name="lighting/imagebasedlights/distantlightprobes/specularbrdfintegration/discretedomain">&nbsp;</a><a class="target" name="toc5.3.4.2.2">&nbsp;</a><h5>Discrete Domain </h5>
+<p>
+
+In the discrete domain the equations in \ref{iblPartialEquations} become:
+</p><p>
+$$\begin{equation}
+\hat{I}(f(n, \alpha) \Lt) \equiv \frac{1}{N}\sum_{\forall \, i \in image} f(l_i, n, \alpha) \Lt(l_i) \left<\NoL\right>  \\
+\hat{I}(f(n, \alpha))     \equiv \frac{1}{N}\sum_{\forall \, i \in image} f(l_i, n, \alpha)          \left<\NoL\right>  \\
+I(f(n, v, \alpha))        \equiv \frac{1}{N}\sum_{\forall \, i \in image} f(l_i, n, v, \alpha)       \left<\NoL\right>
+\end{equation}$$
+</p><p>
+However, in practice we're using <em class="underscore">importance sampling</em> which needs to take the \(pdf\) of the distribution
+into account and adds a term \(\frac{4\left<\VoH\right>}{D(h_i, \alpha)\left<\NoH\right>}\).
+See <a href="#importancesamplingfortheibl" target="_self">Importance Sampling For The IBL</a> section:
+</p><p>
+$$\begin{equation}\label{iblImportanceSampling}
+\hat{I}(f(n, \alpha) \Lt) \equiv \frac{4}{N}\sum_i^N f(l_i, n, \alpha)    \frac{\left<\VoH\right>}{D(h_i, \alpha)\left<\NoH\right>} \Lt(l_i) \left<\NoL\right>  \\
+\hat{I}(f(n, \alpha))     \equiv \frac{4}{N}\sum_i^N f(l_i, n, \alpha)    \frac{\left<\VoH\right>}{D(h_i, \alpha)\left<\NoH\right>}          \left<\NoL\right>  \\
+I(f(n, v, \alpha))        \equiv \frac{4}{N}\sum_i^N f(l_i, n, v, \alpha) \frac{\left<\VoH\right>}{D(h_i, \alpha)\left<\NoH\right>}          \left<\NoL\right>
+\end{equation}$$
+</p><p>
+Recalling that for \(\hat{I}\), we assume that \(v = n\), equations \ref{iblImportanceSampling},
+simplifies to:
+</p><p>
+$$\begin{equation}
+\hat{I}(f(n, \alpha) \Lt) \equiv \frac{4}{N}\sum_i^N \frac{f(l_i, n,    \alpha)}{D(h_i, \alpha)} \Lt(l_i) \left<\NoL\right>  \\
+\hat{I}(f(n, \alpha))     \equiv \frac{4}{N}\sum_i^N \frac{f(l_i, n,    \alpha)}{D(h_i, \alpha)}          \left<\NoL\right>  \\
+I(f(n, v, \alpha))        \equiv \frac{4}{N}\sum_i^N \frac{f(l_i, n, v, \alpha)}{D(h_i, \alpha)} \frac{\left<\VoH\right>}{\left<\NoH\right>} \left<\NoL\right>
+\end{equation}$$
+</p><p>
+Then, the first two equations can be merged together such that \(LD(n, \alpha) = \frac{\hat{I}(f(n, \alpha) \Lt)}{\hat{I}(f(n, \alpha))}\)
+</p><p>
+$$\begin{equation}\label{iblLD}
+LD(n, \alpha)       \equiv \frac{\sum_i^N \frac{f(l_i, n, \alpha)}{D(h_i, \alpha)} \Lt(l_i) \left<\NoL\right>}{\sum_i^N \frac{f(l_i, n, \alpha)}{D(h_i, \alpha)}\left<\NoL\right>}
+\end{equation}$$
+$$\begin{equation}\label{iblDFV}
+I(f(n, v, \alpha))  \equiv \frac{4}{N}\sum_i^N \frac{f(l_i, n, v, \alpha)}{D(h_i, \alpha)} \frac{\left<\VoH\right>}{\left<\NoH\right>} \left<\NoL\right>
+\end{equation}$$
+</p><p>
+Note that at this point, we could almost compute both remaining equations off-line. The only difficulty
+is that we don't know \(f_0\) nor \(f_{90}\) when we precompute those integrals. We will see below that
+we can incorporate these terms at runtime for equation \ref{iblDFV}, alas, this is not possible for
+equation \ref{iblLD} and we have to assume \(f_0 = f_{90} = 1\) (i.e.: the fresnel term always evaluates to 1).
+</p><p>
+We also have to deal with the visibility term of the brdf, in practice keeping it yields to slightly
+worst results compared to the ground truth, so we also set \(V = 1\).
+</p><p>
+Let's substitute \(f\) in equations \ref{iblLD} and \ref{iblDFV}:
+</p><p>
+$$\begin{equation}
+f(l_i, n, \alpha) = D(h_i, \alpha)F(f_0, f_{90}, \left<\VoH\right>)V(l_i, v, \alpha)
+\end{equation}$$
+</p><p>
+The first simplification is that the term \(D(h_i, \alpha)\) in the brdf cancels out with the
+denominator (which came from the \(pdf\) due to importance sampling) and F and V disappear since we
+assume their value is 1. 
+</p><p>
+$$\begin{equation}
+LD(n, \alpha)       \equiv \frac{\sum_i^N V(l_i, v, \alpha)\left<\NoL\right>\Lt(l_i) }{\sum_i^N \left<\NoL\right>}
+\end{equation}$$
+$$\begin{equation}\label{iblFV}
+I(f(n, v, \alpha))  \equiv \frac{4}{N}\sum_i^N \color{green}{F(f_0, f_{90}, \left<\VoH\right>)} V(l_i, v, \alpha)\frac{\left<\VoH\right>}{\left<\NoH\right>} \left<\NoL\right>
+\end{equation}$$
+</p><p>
+Now, let's substitute the fresnel term into equation \ref{iblFV}:
+</p><p>
+$$\begin{equation}
+F(f_0, f_{90}, \left<\VoH\right>) = f_0 (1 - F_c(\left<\VoH\right>)) + f_{90} F_c(\left<\VoH\right>) \\
+F_c(\left<\VoH\right>) = (1 - \left<\VoH\right>)^5
+\end{equation}$$
+</p><p>
+$$\begin{equation}
+I(f(n, v, \alpha))  \equiv \frac{4}{N}\sum_i^N \left[\color{green}{f_0 (1 - F_c(\left<\VoH\right>)) + f_{90} F_c(\left<\VoH\right>)}\right] V(l_i, v, \alpha)\frac{\left<\VoH\right>}{\left<\NoH\right>} \left<\NoL\right> \\
+\end{equation}$$
+</p><p>
+$$
+\begin{align*}
+I(f(n, v, \alpha))  \equiv & \color{green}{f_0   } \frac{4}{N}\sum_i^N  \color{green}{(1 - F_c(\left<\VoH\right>))} V(l_i, v, \alpha)\frac{\left<\VoH\right>}{\left<\NoH\right>} \left<\NoL\right> \\
+                    +      & \color{green}{f_{90}} \frac{4}{N}\sum_i^N  \color{green}{     F_c(\left<\VoH\right>) } V(l_i, v, \alpha)\frac{\left<\VoH\right>}{\left<\NoH\right>} \left<\NoL\right>
+\end{align*}
+$$
+</p><p>
+And finally, we extract the equations that can be calculated off-line (i.e.: the part that doesn't 
+depend on the runtime parameters \(f_0\) and \(f_{90}\)):
+</p><p>
+$$\begin{equation}\label{iblAllEquations}
+DFG_1(\alpha, \left<\NoV\right>) = \frac{4}{N}\sum_i^N  \color{green}{(1 - F_c(\left<\VoH\right>))} V(l_i, v, \alpha)\frac{\left<\VoH\right>}{\left<\NoH\right>} \left<\NoL\right> \\
+DFG_2(\alpha, \left<\NoV\right>) = \frac{4}{N}\sum_i^N  \color{green}{     F_c(\left<\VoH\right>) } V(l_i, v, \alpha)\frac{\left<\VoH\right>}{\left<\NoH\right>} \left<\NoL\right> \\
+I(f(n, v, \alpha))  \equiv   \color{green}{f_0} \color{red}{DFG_1(\alpha, \left<\NoV\right>)} + \color{green}{f_{90}} \color{red}{DFG_2(\alpha, \left<\NoV\right>)}
+\end{equation}$$
+</p><p>
+Notice that \(DFG_1\) and \(DFG_2\) only depend on \(\NoV\), that is the angle between the normal \(n\) and
+the view direction \(v\). This is true because the integral is symmetrical with respect to \(n\). 
+When integrating, we can choose any \(v\) we please as long as it satisfies \(\NoV\) 
+(e.g.: when calculating \(\VoH\)).
+</p><p>
+Putting everything back together:
+</p><p>
+$$
+\begin{align*}
+\Lout(n,v,\alpha,f_0,f_{90})     &\simeq \big[ f_0 \color{red}{DFG_1(\NoV, \alpha)} + f_{90} \color{red}{DFG_2(\NoV, \alpha)} \big] \times LD(n, \alpha) \\
+DFG_1(\alpha, \left<\NoV\right>) &=      \frac{4}{N}\sum_i^N  \color{green}{(1 - F_c(\left<\VoH\right>))} V(l_i, v, \alpha)\frac{\left<\VoH\right>}{\left<\NoH\right>} \left<\NoL\right> \\
+DFG_2(\alpha, \left<\NoV\right>) &=      \frac{4}{N}\sum_i^N  \color{green}{     F_c(\left<\VoH\right>) } V(l_i, v, \alpha)\frac{\left<\VoH\right>}{\left<\NoH\right>} \left<\NoL\right> \\
+LD(n, \alpha)                    &=      \frac{\sum_i^N V(l_i, n, \alpha)\left<\NoL\right>\Lt(l_i) }{\sum_i^N \left<\NoL\right>}
+\end{align*}     
+$$
+</p>
+<a class="target" name="the%5C(dfg_1%5C)and%5C(dfg_2%5C)termvisualized">&nbsp;</a><a class="target" name="lighting/imagebasedlights/distantlightprobes/the%5C(dfg_1%5C)and%5C(dfg_2%5C)termvisualized">&nbsp;</a><a class="target" name="toc5.3.4.3">&nbsp;</a><h4>The \(DFG_1\) and \(DFG_2\) term visualized </h4>
+<p>
+
+Both \(DFG_1\) and \(DFG_2\) can either be pre-calculated in a regular 2D texture indexed by \((\NoV, \alpha)\) 
+and sampled bilinearly, or computed at runtime using an analytic approximation of the surfaces. 
+See sample code in the annex. 
+The pre-calculated textures are shown in <a href="#table_texturedfg" target="_self">table&nbsp;15</a>. 
+A C++ implementation of the pre-computation can be found in section <a href="#toc9.5" target="_self">9.5</a>.
+</p><p>
+<div class='table'>
+<a class="target" name="table_texturedfg">&nbsp;</a><table class="table"><tr><th  style="text-align:left"> \(DFG_1\) </th><th  style="text-align:left"> \(DFG_2\) </th><th  style="text-align:left"> \({ DFG_1, DFG_2, 0 }\) </th></tr>
+<tr><td  style="text-align:left"> <a href="../images/ibl/dfg1.png" target="_blank"><img class="markdeep" src="../images/ibl/dfg1.png" /></a> </td><td  style="text-align:left"> <a href="../images/ibl/dfg2.png" target="_blank"><img class="markdeep" src="../images/ibl/dfg2.png" /></a> </td><td  style="text-align:left"> <a href="../images/ibl/dfg.png" target="_blank"><img class="markdeep" src="../images/ibl/dfg.png" /></a> </td></tr>
+</table><center><div class="tablecaption"><b style="font-style:normal;">Table&nbsp;15:</b> Y axis: \(\alpha\). X axis: \(cos \theta\)</div></center></div>
+</p><p>
+\(DFG_1\) and \(DFG_2\)  are conveniently within the \([0, 1]\) range, however 8-bits textures don't have
+enough precision and will cause problems. 
+Unfortunately, on mobile, 16-bits or float textures are not ubiquitous and there are a limited 
+number of samplers. 
+Despite the attractive simplicity of the shader code using a texture, it might be better to use an 
+analytic approximation. Note however that since we only need to store two terms, 
+OpenGL ES 3.0's RG16F texture format is a good candidate.
+</p><p>
+Such analytic approximation is described in [<a href="#citation-karis14" target="_self">Karis14</a>], itself based on [<a href="#citation-lazarov13" target="_self">Lazarov13</a>]. 
+[<a href="#citation-narkowicz14" target="_self">Narkowicz14</a>] is another interesting approximation. Note that these two approximations are not
+compatible with the energy compensation term presented in section <a href="#toc5.3.4.7" target="_self">5.3.4.7</a>.
+<a href="#table_textureapproxdfg" target="_self">Table&nbsp;16</a> presents a visual representation of these approximations.
+<div class='table'>
+<a class="target" name="table_textureapproxdfg">&nbsp;</a><table class="table"><tr><th  style="text-align:left"> \(DFG_1\) </th><th  style="text-align:left"> \(DFG_2\) </th><th  style="text-align:left"> \({ DFG_1, DFG_2, 0 }\) </th></tr>
+<tr><td  style="text-align:left"> <a href="../images/ibl/dfg1_approx.png" target="_blank"><img class="markdeep" src="../images/ibl/dfg1_approx.png" /></a> </td><td  style="text-align:left"> <a href="../images/ibl/dfg2_approx.png" target="_blank"><img class="markdeep" src="../images/ibl/dfg2_approx.png" /></a> </td><td  style="text-align:left"> <a href="../images/ibl/dfg_approx.png" target="_blank"><img class="markdeep" src="../images/ibl/dfg_approx.png" /></a> </td></tr>
+</table><center><div class="tablecaption"><b style="font-style:normal;">Table&nbsp;16:</b> Y axis: \(\alpha\). X axis: \(cos \theta\)</div></center></div>
+</p>
+<a class="target" name="the%5C(ld%5C)termvisualized">&nbsp;</a><a class="target" name="lighting/imagebasedlights/distantlightprobes/the%5C(ld%5C)termvisualized">&nbsp;</a><a class="target" name="toc5.3.4.4">&nbsp;</a><h4>The \(LD\) term visualized </h4>
+<p>
+
+\(LD\) is the convolution of the environment by a function that only depends on the \(\alpha\) parameter
+(itself related to the roughness, see section <a href="#toc4.8.3.3" target="_self">4.8.3.3</a>).
+\(LD\) can conveniently be stored in a mip-mapped cubemap where increasing LODs receive the environment
+pre-filtered with increasing roughness. This works well because this convolution is a
+powerful low-pass filter. To make good use of each mipmap level, it is necessary to remap
+\(\alpha\); we find that using a power remapping with \(\gamma = 2\) works well and is convenient.
+</p><p>
+$$
+\begin{align*}
+    \alpha       &= perceptualRoughness^2                        \\
+    lod_{\alpha} &= \alpha^{\frac{1}{2}} = perceptualRoughness   \\
+\end{align*}
+$$
+</p><p>
+See an example below:
+</p><p>
+<table width="100%"><tr valign="top"><td>
+</p><p>
+<center><div class="image" style=""><a href="../images/ibl/ibl_river_roughness_m0.png" target="_blank"><img class="markdeep" src="../images/ibl/ibl_river_roughness_m0.png" style="max-width:100%;" /></a><center><span class="imagecaption">\(\alpha=0.0\)</span></center></div></center>
+</p><p>
+</td></tr><tr valign="top"><td>
+</p><p>
+<center><div class="image" style=""><a href="../images/ibl/ibl_river_roughness_m1.png" target="_blank"><img class="markdeep" src="../images/ibl/ibl_river_roughness_m1.png" style="max-width:100%;" /></a><center><span class="imagecaption">\(\alpha=0.2\)</span></center></div></center>
+</p><p>
+</td></tr><tr valign="top"><td>
+</p><p>
+<center><div class="image" style=""><a href="../images/ibl/ibl_river_roughness_m2.png" target="_blank"><img class="markdeep" src="../images/ibl/ibl_river_roughness_m2.png" style="max-width:100%;" /></a><center><span class="imagecaption">\(\alpha=0.4\)</span></center></div></center>
+</p><p>
+</td></tr><tr valign="top"><td>
+</p><p>
+<center><div class="image" style=""><a href="../images/ibl/ibl_river_roughness_m3.png" target="_blank"><img class="markdeep" src="../images/ibl/ibl_river_roughness_m3.png" style="max-width:100%;" /></a><center><span class="imagecaption">\(0.6\)</span></center></div></center>
+</p><p>
+</td></tr><tr valign="top"><td>
+</p><p>
+<center><div class="image" style=""><a href="../images/ibl/ibl_river_roughness_m4.png" target="_blank"><img class="markdeep" src="../images/ibl/ibl_river_roughness_m4.png" style="max-width:100%;" /></a><center><span class="imagecaption">\(0.8\)</span></center></div></center>
+</p><p>
+</td></tr></table>
+</p>
+<a class="target" name="indirectspecularandindirectdiffusecomponentsvisualized">&nbsp;</a><a class="target" name="lighting/imagebasedlights/distantlightprobes/indirectspecularandindirectdiffusecomponentsvisualized">&nbsp;</a><a class="target" name="toc5.3.4.5">&nbsp;</a><h4>Indirect specular and indirect diffuse components visualized </h4>
+<p>
+
+<a href="#figure_iblvisualized" target="_self">Figure&nbsp;53</a> shows how indirect lighting interacts with dielectrics and conductors. Direct lighting was removed for illustration purposes.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_iblvisualized">&nbsp;</a><a href="../images/ibl/ibl_visualization.jpg" target="_blank"><img class="markdeep" src="../images/ibl/ibl_visualization.jpg" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;53:</b> Indirect diffuse and specular decomposition</span></center></div></center>
+</p>
+<a class="target" name="iblevaluationimplementation">&nbsp;</a><a class="target" name="lighting/imagebasedlights/distantlightprobes/iblevaluationimplementation">&nbsp;</a><a class="target" name="toc5.3.4.6">&nbsp;</a><h4>IBL evaluation implementation </h4>
+<p>
+
+<a href="#listing_iblevaluation" target="_self">Listing&nbsp;27</a> presents a GLSL implementation to evaluate the IBL, using the various textures described in the previous sections. 
+</p><a class="target" name="listing_iblevaluation">&nbsp;</a><pre class="listing tilde"><code><span class="line"></span><span class="hljs-type">vec3</span> ibl(<span class="hljs-type">vec3</span> n, <span class="hljs-type">vec3</span> v, <span class="hljs-type">vec3</span> diffuseColor, <span class="hljs-type">vec3</span> f0, <span class="hljs-type">vec3</span> f90,
+<span class="line"></span>        <span class="hljs-type">float</span> perceptualRoughness) {
+<span class="line"></span>    <span class="hljs-type">vec3</span> r = <span class="hljs-built_in">reflect</span>(n);
+<span class="line"></span>    <span class="hljs-type">vec3</span> Ld = <span class="hljs-built_in">textureCube</span>(irradianceEnvMap, r) * diffuseColor;
+<span class="line"></span>    <span class="hljs-type">float</span> lod = computeLODFromRoughness(perceptualRoughness);
+<span class="line"></span>    <span class="hljs-type">vec3</span> Lld = <span class="hljs-built_in">textureCube</span>(prefilteredEnvMap, r, lod);
+<span class="line"></span>    <span class="hljs-type">vec2</span> Ldfg = <span class="hljs-built_in">textureLod</span>(dfgLut, <span class="hljs-type">vec2</span>(<span class="hljs-built_in">dot</span>(n, v), perceptualRoughness), <span class="hljs-number">0.0</span>).xy;
+<span class="line"></span>    <span class="hljs-type">vec3</span> Lr =  (f0 * Ldfg.x + f90 * Ldfg.y) * Lld;
+<span class="line"></span>    <span class="hljs-keyword">return</span> Ld + Lr;
+<span class="line"></span>}</code></pre><center><div class="listingcaption tilde"><b style="font-style:normal;">Listing&nbsp;27:</b> GLSL implementation of image based lighting evaluation</div></center>
+<p>
+
+We can however save a couple of texture lookups by using Spherical Harmonics instead of an 
+irradiance cubemap and the analytical approximation of the \(DFG\) LUT, as shown in <a href="#listing_optimizediblevaluation" target="_self">listing&nbsp;28</a>.
+</p><a class="target" name="listing_optimizediblevaluation">&nbsp;</a><pre class="listing tilde"><code><span class="line"></span><span class="hljs-type">vec3</span> irradianceSH(<span class="hljs-type">vec3</span> n) {
+<span class="line"></span>    <span class="hljs-comment">// uniform vec3 sphericalHarmonics[9]</span>
+<span class="line"></span>    <span class="hljs-comment">// We can use only the first 2 bands for better performance</span>
+<span class="line"></span>    <span class="hljs-keyword">return</span>
+<span class="line"></span>          sphericalHarmonics[<span class="hljs-number">0</span>]
+<span class="line"></span>        + sphericalHarmonics[<span class="hljs-number">1</span>] * (n.y)
+<span class="line"></span>        + sphericalHarmonics[<span class="hljs-number">2</span>] * (n.z)
+<span class="line"></span>        + sphericalHarmonics[<span class="hljs-number">3</span>] * (n.x)
+<span class="line"></span>        + sphericalHarmonics[<span class="hljs-number">4</span>] * (n.y * n.x)
+<span class="line"></span>        + sphericalHarmonics[<span class="hljs-number">5</span>] * (n.y * n.z)
+<span class="line"></span>        + sphericalHarmonics[<span class="hljs-number">6</span>] * (<span class="hljs-number">3.0</span> * n.z * n.z - <span class="hljs-number">1.0</span>)
+<span class="line"></span>        + sphericalHarmonics[<span class="hljs-number">7</span>] * (n.z * n.x)
+<span class="line"></span>        + sphericalHarmonics[<span class="hljs-number">8</span>] * (n.x * n.x - n.y * n.y);
+<span class="line"></span>}
+<span class="line"></span>
+<span class="line"></span><span class="hljs-comment">// <span class="hljs-doctag">NOTE:</span> this is the DFG LUT implementation of the function above</span>
+<span class="line"></span><span class="hljs-type">vec2</span> prefilteredDFG_LUT(<span class="hljs-type">float</span> coord, <span class="hljs-type">float</span> NoV) {
+<span class="line"></span>    <span class="hljs-comment">// coord = sqrt(roughness), which is the mapping used by the</span>
+<span class="line"></span>    <span class="hljs-comment">// IBL prefiltering code when computing the mipmaps</span>
+<span class="line"></span>    <span class="hljs-keyword">return</span> <span class="hljs-built_in">textureLod</span>(dfgLut, <span class="hljs-type">vec2</span>(NoV, coord), <span class="hljs-number">0.0</span>).rg;
+<span class="line"></span>}
+<span class="line"></span>
+<span class="line"></span><span class="hljs-type">vec3</span> evaluateSpecularIBL(<span class="hljs-type">vec3</span> r, <span class="hljs-type">float</span> perceptualRoughness) {
+<span class="line"></span>    <span class="hljs-comment">// This assumes a 256x256 cubemap, with 9 mip levels</span>
+<span class="line"></span>    <span class="hljs-type">float</span> lod = <span class="hljs-number">8.0</span> * perceptualRoughness;
+<span class="line"></span>    <span class="hljs-comment">// decodeEnvironmentMap() either decodes RGBM or is a no-op if the</span>
+<span class="line"></span>    <span class="hljs-comment">// cubemap is stored in a float texture</span>
+<span class="line"></span>    <span class="hljs-keyword">return</span> decodeEnvironmentMap(textureCubeLodEXT(environmentMap, r, lod));
+<span class="line"></span>}
+<span class="line"></span>
+<span class="line"></span><span class="hljs-type">vec3</span> evaluateIBL(<span class="hljs-type">vec3</span> n, <span class="hljs-type">vec3</span> v, <span class="hljs-type">vec3</span> diffuseColor, <span class="hljs-type">vec3</span> f0, <span class="hljs-type">vec3</span> f90, <span class="hljs-type">float</span> perceptualRoughness) {
+<span class="line"></span>    <span class="hljs-type">float</span> NoV = <span class="hljs-built_in">max</span>(<span class="hljs-built_in">dot</span>(n, v), <span class="hljs-number">0.0</span>);
+<span class="line"></span>    <span class="hljs-type">vec3</span> r = <span class="hljs-built_in">reflect</span>(-v, n);
+<span class="line"></span>
+<span class="line"></span>    <span class="hljs-comment">// Specular indirect</span>
+<span class="line"></span>    <span class="hljs-type">vec3</span> indirectSpecular = evaluateSpecularIBL(r, perceptualRoughness);
+<span class="line"></span>    <span class="hljs-type">vec2</span> env = prefilteredDFG_LUT(perceptualRoughness, NoV);
+<span class="line"></span>    <span class="hljs-type">vec3</span> specularColor = f0 * env.x + f90 * env.y;
+<span class="line"></span>
+<span class="line"></span>    <span class="hljs-comment">// Diffuse indirect</span>
+<span class="line"></span>    <span class="hljs-comment">// We multiply by the Lambertian BRDF to compute radiance from irradiance</span>
+<span class="line"></span>    <span class="hljs-comment">// With the Disney BRDF we would have to remove the Fresnel term that</span>
+<span class="line"></span>    <span class="hljs-comment">// depends on NoL (it would be rolled into the SH). The Lambertian BRDF</span>
+<span class="line"></span>    <span class="hljs-comment">// can be baked directly in the SH to save a multiplication here</span>
+<span class="line"></span>    <span class="hljs-type">vec3</span> indirectDiffuse = <span class="hljs-built_in">max</span>(irradianceSH(n), <span class="hljs-number">0.0</span>) * Fd_Lambert();
+<span class="line"></span>
+<span class="line"></span>    <span class="hljs-comment">// Indirect contribution</span>
+<span class="line"></span>    <span class="hljs-keyword">return</span> diffuseColor * indirectDiffuse + indirectSpecular * specularColor;
+<span class="line"></span>}</code></pre><center><div class="listingcaption tilde"><b style="font-style:normal;">Listing&nbsp;28:</b> GLSL implementation of image based lighting evaluation</div></center>
+<a class="target" name="pre-integrationformultiscattering">&nbsp;</a><a class="target" name="lighting/imagebasedlights/distantlightprobes/pre-integrationformultiscattering">&nbsp;</a><a class="target" name="toc5.3.4.7">&nbsp;</a><h4>Pre-integration for multiscattering </h4>
+<p>
+
+In section <a href="#toc4.7.2" target="_self">4.7.2</a> we discussed how to use a second scaled specular lobe 
+to compensate for the energy loss due to only accounting for a single scattering event in our BRDF.
+This energy compensation lobe is scaled by a term that depends on \(r\) defined in the following way:
+</p><p>
+$$\begin{equation}
+r = \int_{\Omega} D(l,v) V(l,v) \left< \NoL \right> \partial l
+\end{equation}$$
+</p><p>
+Or, evaluated with importance sampling (See <a href="#importancesamplingfortheibl" target="_self">Importance Sampling For The IBL</a> section):
+</p><p>
+$$\begin{equation}
+r \equiv  \frac{4}{N}\sum_i^N  V(l_i, v, \alpha)\frac{\left<\VoH\right>}{\left<\NoH\right>} \left<\NoL\right>
+\end{equation}$$
+</p><p>
+This equality is very similar to the terms \(DFG_1\) and \(DFG_2\) seen in equation \(\ref{iblAllEquations}\).
+In fact, it's the same, except without the Fresnel term.
+</p><p>
+By making the further assumption that \(f_{90} = 1\), we can rewrite \(DFG_1\) and \(DFG_2\) and the
+\(\Lout\) reconstruction:
+</p><p>
+$$
+\begin{align*}
+\Lout(n,v,\alpha,f_0)                           &\simeq \big[ (1 - f_0) \color{red}{DFG_1^{multiscatter}(\NoV, \alpha)} + f_0 \color{red}{DFG_2^{multiscatter}(\NoV, \alpha)} \big] \times LD(n, \alpha) \\
+DFG_1^{multiscatter}(\alpha, \left<\NoV\right>) &=      \frac{4}{N}\sum_i^N  \color{green}{F_c(\left<\VoH\right>)} V(l_i, v, \alpha)\frac{\left<\VoH\right>}{\left<\NoH\right>} \left<\NoL\right> \\
+DFG_2^{multiscatter}(\alpha, \left<\NoV\right>) &=      \frac{4}{N}\sum_i^N                                        V(l_i, v, \alpha)\frac{\left<\VoH\right>}{\left<\NoH\right>} \left<\NoL\right> \\
+LD(n, \alpha)                                   &=      \frac{\sum_i^N V(l_i, n, \alpha)\left<\NoL\right>\Lt(l_i) }{\sum_i^N V(l_i, n, \alpha)\left<\NoL\right>}
+\end{align*}     
+$$
+</p><p>
+These two new \(DFG\) terms simply need to replace the ones used in the implementation shown in section <a href="#toc9.5" target="_self">9.5</a>:
+</p><a class="target" name="listing_multiscatteriblpreintegration">&nbsp;</a><pre class="listing tilde"><code><span class="line"></span><span class="hljs-type">float</span> Fc = <span class="hljs-built_in">pow</span>(<span class="hljs-number">1</span> - VoH, <span class="hljs-number">5.0f</span>);
+<span class="line"></span>r.x += Gv * Fc;
+<span class="line"></span>r.y += Gv;</code></pre><center><div class="listingcaption tilde"><b style="font-style:normal;">Listing&nbsp;29:</b> C++ implementation of the \(L_{DFG}\) term for multiscattering</div></center>
+<p>
+
+To perform the reconstruction we need to slightly modify <a href="#listing_multiscatteriblevaluation" target="_self">listing&nbsp;30</a>:
+</p><a class="target" name="listing_multiscatteriblevaluation">&nbsp;</a><pre class="listing tilde"><code><span class="line"></span><span class="hljs-type">vec2</span> dfg = <span class="hljs-built_in">textureLod</span>(dfgLut, <span class="hljs-type">vec2</span>(<span class="hljs-built_in">dot</span>(n, v), perceptualRoughness), <span class="hljs-number">0.0</span>).xy;
+<span class="line"></span><span class="hljs-comment">// (1 - f0) * dfg.x + f0 * dfg.y</span>
+<span class="line"></span><span class="hljs-type">vec3</span> specularColor = <span class="hljs-built_in">mix</span>(dfg.xxx, dfg.yyy, f0);</code></pre><center><div class="listingcaption tilde"><b style="font-style:normal;">Listing&nbsp;30:</b> GLSL implementation of image based lighting evaluation, with multiscattering LUT</div></center>
+<a class="target" name="summary">&nbsp;</a><a class="target" name="lighting/imagebasedlights/distantlightprobes/summary">&nbsp;</a><a class="target" name="toc5.3.4.8">&nbsp;</a><h4>Summary </h4>
+<p>
+
+In order to calculate the specular contribution of distant image-based lights, we had to make a few
+approximations and compromises:
+</p><p>
+<ul>
+    <li class="minus">\(v = n\), by far the assumption contributing to the largest error when integrating the
+          non-constant part of the IBL. This results in the complete loss of roughness anisotropy
+          with respect to the view point.
+</p><p>
+</li>
+    <li class="minus">Roughness contribution for the non-constant part of the IBL is quantized and trilinear filtering
+          is used to interpolate between these levels. This is most visible at low roughnes (e.g.: around 0.0625
+          for a 9 LODs cubemap).
+</p><p>
+</li>
+    <li class="minus">Because mipmap levels are used to store the pre-integrated environment, they can't be used for
+          texture minification, as they ought to. This can causes aliasing or moiré artifacts in high frequency 
+          regions or the environment at low roughness and/or distant or small objects. 
+          This can also impact performance due to the resulting poor cache access pattern. 
+</p><p>
+</li>
+    <li class="minus">No Fresnel for the non-constant part of the IBL.
+</p><p>
+</li>
+    <li class="minus">Visibility = 1 for the non-constant part of the IBL.
+</p><p>
+</li>
+    <li class="minus">Schlick's Fresnel
+</p><p>
+</li>
+    <li class="minus">\(f_{90} = 1\) in the multiscattering case.</li></ul>
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_iblprefiltervsimportancesampling">&nbsp;</a><a href="../images/ibl/ibl_prefilter_vs_reference.png" target="_blank"><img class="markdeep" src="../images/ibl/ibl_prefilter_vs_reference.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;54:</b>
+</span></center></div></center>
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_iblstretchyreflectionloss">&nbsp;</a><a href="../images/ibl/ibl_stretchy_reflections_error.png" target="_blank"><img class="markdeep" src="../images/ibl/ibl_stretchy_reflections_error.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;55:</b>
+</span></center></div></center>
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_iblroughnessinlods0">&nbsp;</a><a href="../images/ibl/ibl_trilinear_0.png" target="_blank"><img class="markdeep" src="../images/ibl/ibl_trilinear_0.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;56:</b>
+</span></center></div></center>
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_iblroughnessinlods1">&nbsp;</a><a href="../images/ibl/ibl_trilinear_1.png" target="_blank"><img class="markdeep" src="../images/ibl/ibl_trilinear_1.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;57:</b>
+</span></center></div></center>
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_iblmoirepattern">&nbsp;</a><a href="../images/ibl/ibl_no_mipmaping.png" target="_blank"><img class="markdeep" src="../images/ibl/ibl_no_mipmaping.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;58:</b>
+</span></center></div></center>
+</p>
+<a class="target" name="clearcoat">&nbsp;</a><a class="target" name="lighting/imagebasedlights/clearcoat">&nbsp;</a><a class="target" name="toc5.3.5">&nbsp;</a><h3>Clear coat </h3>
+<p>
+
+When sampling the IBL, the clear coat layer is calculated as a second specular lobe. This specular lobe is oriented along the view direction since we cannot reasonably integrate over the hemisphere. <a href="#listing_clearcoatibl" target="_self">Listing&nbsp;31</a> demonstrates this approximation in practice. It also shows the energy conservation step. It is important to note that this second specular lobe is computed exactly the same way as the main specular lobe, using the same DFG approximation.
+</p><a class="target" name="listing_clearcoatibl">&nbsp;</a><pre class="listing tilde"><code><span class="line"></span><span class="hljs-comment">// clearCoat_NoV == shading_NoV if the clear coat layer doesn&#x27;t have its own normal map</span>
+<span class="line"></span><span class="hljs-type">float</span> Fc = <span class="hljs-built_in">F_Schlick</span>(<span class="hljs-number">0.04</span>, <span class="hljs-number">1.0</span>, clearCoat_NoV) * clearCoat;
+<span class="line"></span><span class="hljs-comment">// base layer attenuation for energy compensation</span>
+<span class="line"></span>iblDiffuse  *= <span class="hljs-number">1.0</span> - Fc;
+<span class="line"></span>iblSpecular *= <span class="hljs-built_in">sq</span>(<span class="hljs-number">1.0</span> - Fc);
+<span class="line"></span>iblSpecular += <span class="hljs-built_in">specularIBL</span>(r, clearCoatPerceptualRoughness) * Fc;</code></pre><center><div class="listingcaption tilde"><b style="font-style:normal;">Listing&nbsp;31:</b> GLSL implementation of the clear coat specular lobe for image-based lighting</div></center>
+<a class="target" name="anisotropy">&nbsp;</a><a class="target" name="lighting/imagebasedlights/anisotropy">&nbsp;</a><a class="target" name="toc5.3.6">&nbsp;</a><h3>Anisotropy </h3>
+<p>
+
+[<a href="#citation-mcauley15" target="_self">McAuley15</a>] describes a technique called “bent reflection vector”, based [<a href="#citation-revie12" target="_self">Revie12</a>]. The bent reflection vector is a rough approximation of anisotropic lighting but the alternative is to use importance sampling. This approximation is sufficiently cheap to compute and provides good results, as shown in <a href="#figure_anisotropicibl1" target="_self">figure&nbsp;59</a> and <a href="#figure_anisotropicibl2" target="_self">figure&nbsp;60</a>.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_anisotropicibl1">&nbsp;</a><a href="../images/screenshot_anisotropic_ibl1.jpg" target="_blank"><img class="markdeep" src="../images/screenshot_anisotropic_ibl1.jpg" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;59:</b> Anisotropic indirect specular reflections using bent normals (left: roughness 0.3, right: roughness: 0.0; both: anisotropy 1.0)</span></center></div></center>
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_anisotropicibl2">&nbsp;</a><a href="../images/screenshot_anisotropic_ibl2.jpg" target="_blank"><img class="markdeep" src="../images/screenshot_anisotropic_ibl2.jpg" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;60:</b> Anisotropic reflections with varying roughness, metallicness, etc.</span></center></div></center>
+</p><p>
+The implementation of this technique is straightforward, as demonstrated in <a href="#listing_bentreflectionvector" target="_self">listing&nbsp;32</a>.
+</p><a class="target" name="listing_bentreflectionvector">&nbsp;</a><pre class="listing tilde"><code><span class="line"></span><span class="hljs-type">vec3</span> anisotropicTangent = <span class="hljs-built_in">cross</span>(bitangent, v);
+<span class="line"></span><span class="hljs-type">vec3</span> anisotropicNormal = <span class="hljs-built_in">cross</span>(anisotropicTangent, bitangent);
+<span class="line"></span><span class="hljs-type">vec3</span> bentNormal = <span class="hljs-built_in">normalize</span>(<span class="hljs-built_in">mix</span>(n, anisotropicNormal, anisotropy));
+<span class="line"></span><span class="hljs-type">vec3</span> r = <span class="hljs-built_in">reflect</span>(-v, bentNormal);</code></pre><center><div class="listingcaption tilde"><b style="font-style:normal;">Listing&nbsp;32:</b> GLSL implementation of the bent reflection vector</div></center>
+<p>
+
+This technique can be made more useful by accepting negative <code>anisotropy</code> values, as shown in <a href="#listing_bentreflectionvectordirection" target="_self">listing&nbsp;33</a>. When the anisotropy is negative, the highlights are not in the direction of the tangent, but in the direction of the bitangent instead.
+</p><a class="target" name="listing_bentreflectionvectordirection">&nbsp;</a><pre class="listing tilde"><code><span class="line"></span><span class="hljs-type">vec3</span> anisotropicDirection = anisotropy &gt;= <span class="hljs-number">0.0</span> ? bitangent : tangent;
+<span class="line"></span><span class="hljs-type">vec3</span> anisotropicTangent = <span class="hljs-built_in">cross</span>(anisotropicDirection, v);
+<span class="line"></span><span class="hljs-type">vec3</span> anisotropicNormal = <span class="hljs-built_in">cross</span>(anisotropicTangent, anisotropicDirection);
+<span class="line"></span><span class="hljs-type">vec3</span> bentNormal = <span class="hljs-built_in">normalize</span>(<span class="hljs-built_in">mix</span>(n, anisotropicNormal, anisotropy));
+<span class="line"></span><span class="hljs-type">vec3</span> r = <span class="hljs-built_in">reflect</span>(-v, bentNormal);</code></pre><center><div class="listingcaption tilde"><b style="font-style:normal;">Listing&nbsp;33:</b> GLSL implementation of the bent reflection vector</div></center>
+<p>
+
+<a href="#figure_anisotropicdirection" target="_self">Figure&nbsp;61</a> demonstrates this modified implementation in practice.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_anisotropicdirection">&nbsp;</a><a href="../images/screenshot_anisotropy_direction.png" target="_blank"><img class="markdeep" src="../images/screenshot_anisotropy_direction.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;61:</b> Control of the anisotropy direction using positive (left) and negative (right) values</span></center></div></center>
+</p>
+<a class="target" name="subsurface">&nbsp;</a><a class="target" name="lighting/imagebasedlights/subsurface">&nbsp;</a><a class="target" name="toc5.3.7">&nbsp;</a><h3>Subsurface </h3>
+<p>
+
+[TODO] Explain subsurface and IBL
+</p>
+<a class="target" name="cloth">&nbsp;</a><a class="target" name="lighting/imagebasedlights/cloth">&nbsp;</a><a class="target" name="toc5.3.8">&nbsp;</a><h3>Cloth </h3>
+<p>
+
+The IBL implementation for the cloth material model is more complicated than for the other material models. The main difference stems from the use of a different NDF (&ldquo;Charlie&rdquo; vs height-correlated Smith GGX). As described in this section, we use the split-sum approximation to compute the DFG term of the BRDF when computing an IBL. This DFG term is designed for a different BRDF and cannot be used for the cloth BRDF. Since we designed our  cloth BRDF to not need a Fresnel term, we can generate a single DG term in the 3rd channel of the DFG LUT. The result is shown in <a href="#figure_dfgclothlut" target="_self">figure&nbsp;62</a>.
+</p><p>
+The DG term is generated using uniform sampling as recommended in [<a href="#citation-estevez17" target="_self">Estevez17</a>]. With uniform sampling the \(pdf\) is simply \(\frac{1}{2\pi}\) and we must still use the Jacobian \(\frac{1}{4\left< \VoH \right>}\).
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_dfgclothlut">&nbsp;</a><a href="../images/ibl/dfg_cloth.png" target="_blank"><img class="markdeep" src="../images/ibl/dfg_cloth.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;62:</b> DFG LUT with a 3rd channel encoding the DG term of the cloth BRDF</span></center></div></center>
+</p><p>
+The remainder of the image-based lighting implementation follows the same steps as the implementation of regular lights, including the optional subsurface scattering term and its wrap diffuse component. Just as with the clear coat IBL implementation, we cannot integrate over the hemisphere and use the view direction as the dominant light direction to compute the wrap diffuse component.
+</p><a class="target" name="listing_clothapprox">&nbsp;</a><pre class="listing tilde"><code><span class="line"></span><span class="hljs-type">float</span> diffuse = <span class="hljs-built_in">Fd_Lambert</span>() * ambientOcclusion;
+<span class="line"></span><span class="hljs-meta">#<span class="hljs-keyword">if</span> defined(SHADING_MODEL_CLOTH)</span>
+<span class="line"></span><span class="hljs-meta">#<span class="hljs-keyword">if</span> defined(MATERIAL_HAS_SUBSURFACE_COLOR)</span>
+<span class="line"></span>diffuse *= <span class="hljs-built_in">saturate</span>((NoV + <span class="hljs-number">0.5</span>) / <span class="hljs-number">2.25</span>);
+<span class="line"></span><span class="hljs-meta">#<span class="hljs-keyword">endif</span></span>
+<span class="line"></span><span class="hljs-meta">#<span class="hljs-keyword">endif</span></span>
+<span class="line"></span>
+<span class="line"></span>vec3 indirectDiffuse = <span class="hljs-built_in">irradianceIBL</span>(n) * diffuse;
+<span class="line"></span><span class="hljs-meta">#<span class="hljs-keyword">if</span> defined(SHADING_MODEL_CLOTH) &amp;&amp; defined(MATERIAL_HAS_SUBSURFACE_COLOR)</span>
+<span class="line"></span>indirectDiffuse *= <span class="hljs-built_in">saturate</span>(subsurfaceColor + NoV);
+<span class="line"></span><span class="hljs-meta">#<span class="hljs-keyword">endif</span></span>
+<span class="line"></span>
+<span class="line"></span>vec3 ibl = diffuseColor * indirectDiffuse + indirectSpecular * specularColor;</code></pre><center><div class="listingcaption tilde"><b style="font-style:normal;">Listing&nbsp;34:</b> GLSL implementation of the DFG approximation for the cloth NDF</div></center>
+<p>
+
+It is important to note that this only addresses part of the IBL problem. The pre-filtered specular environment maps described earlier are convolved with the standard shading model's BRDF, which differs from the cloth BRDF. To get accurate result we should in theory provide one set of IBLs per BRDF used in the engine. Providing a second set of IBLs is however not practical for our use case so we decided to rely on the existing IBLs instead.
+</p>
+<a class="target" name="staticlighting">&nbsp;</a><a class="target" name="lighting/staticlighting">&nbsp;</a><a class="target" name="toc5.4">&nbsp;</a><h2>Static lighting</h2>
+<p>
+
+[TODO] Spherical-harmonics or spherical-gaussian lightmaps, irradiance volumes, PRT?…
+</p>
+<a class="target" name="transparencyandtranslucencylighting">&nbsp;</a><a class="target" name="lighting/transparencyandtranslucencylighting">&nbsp;</a><a class="target" name="toc5.5">&nbsp;</a><h2>Transparency and translucency lighting</h2>
+<p>
+
+Transparent and translucent materials are important to add realism and correctness to scenes. Filament must therefore provide lighting models for both types of materials to allow artists to properly recreate realistic scenes. Translucency can also be used effectively in a number of non-realistic settings.
+</p>
+<a class="target" name="transparency">&nbsp;</a><a class="target" name="lighting/transparencyandtranslucencylighting/transparency">&nbsp;</a><a class="target" name="toc5.5.1">&nbsp;</a><h3>Transparency</h3>
+<p>
+
+To properly light a transparent surface, we must first understand how the material's opacity is applied. Observe a window and you will see that the diffuse reflectance is transparent. On the other hand, the brighter the specular reflectance, the less opaque the window appears. This effect can be seen in <a href="#figure_cameratransparency" target="_self">figure&nbsp;63</a>: the scene is properly reflected onto the glass surfaces but the specular highlight of the sun is bright enough to appear opaque.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_cameratransparency">&nbsp;</a><a href="../images/screenshot_camera_transparency.jpg" target="_blank"><img class="markdeep" src="../images/screenshot_camera_transparency.jpg" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;63:</b> Example of a complex object where lit surface transparency plays an important role</span></center></div></center>
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_litcar">&nbsp;</a><a href="../images/screenshot_car.jpg" target="_blank"><img class="markdeep" src="../images/screenshot_car.jpg" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;64:</b> Example of a complex object where lit surface transparency plays an important role</span></center></div></center>
+</p><p>
+To properly implement opacity, we will use the premultiplied alpha format. Given a desired opacity noted \( \alpha_{opacity} \) and a diffuse color \( \sigma \) (linear, unpremultiplied), we can compute the effective opacity of a fragment.
+</p><p>
+$$\begin{align*}
+color &= \sigma * \alpha_{opacity} \\
+opacity &= \alpha_{opacity}
+\end{align*}$$
+</p><p>
+The physical interpretation is that the RGB components of the source color define how much light is emitted by the pixel, whereas the alpha component defines how much of the light behind the pixel is blocked by said pixel. We must therefore use the following blending functions:
+</p><p>
+$$\begin{align*}
+Blend_{src} &= 1 \\
+Blend_{dst} &= 1 - src_{\alpha}
+\end{align*}$$
+</p><p>
+The GLSL implementation of these equations is presented in <a href="#listing_surfacetransparency" target="_self">listing&nbsp;35</a>.
+</p><a class="target" name="listing_surfacetransparency">&nbsp;</a><pre class="listing tilde"><code><span class="line"></span><span class="hljs-comment">// baseColor has already been premultiplied</span>
+<span class="line"></span><span class="hljs-type">vec4</span> shadeSurface(<span class="hljs-type">vec4</span> baseColor) {
+<span class="line"></span>    <span class="hljs-type">float</span> alpha = baseColor.a;
+<span class="line"></span>
+<span class="line"></span>    <span class="hljs-type">vec3</span> diffuseColor = evaluateDiffuseLighting();
+<span class="line"></span>    <span class="hljs-type">vec3</span> specularColor = evaluateSpecularLighting();    
+<span class="line"></span>
+<span class="line"></span>    <span class="hljs-keyword">return</span> <span class="hljs-type">vec4</span>(diffuseColor + specularColor, alpha);
+<span class="line"></span>}</code></pre><center><div class="listingcaption tilde"><b style="font-style:normal;">Listing&nbsp;35:</b> Implementation of lit surface transparency in GLSL</div></center>
+<a class="target" name="translucency">&nbsp;</a><a class="target" name="lighting/transparencyandtranslucencylighting/translucency">&nbsp;</a><a class="target" name="toc5.5.2">&nbsp;</a><h3>Translucency</h3>
+<p>
+
+Translucent materials can be divided into two categories:
+</p><p>
+<ul>
+<li class="minus">Surface translucency
+</li>
+<li class="minus"> Volume translucency</li></ul>
+</p><p>
+Volume translucency is useful to light particle systems, for instance clouds or smoke. Surface translucency can be used to imitate materials with transmitted scattering such as wax, marble, skin, etc.
+</p><p>
+[TODO] Surface translucency (BRDF+BTDF, BSSRDF)
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_translucency">&nbsp;</a><a href="../images/screenshot_translucency.png" target="_blank"><img class="markdeep" src="../images/screenshot_translucency.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;65:</b> Front-lit translucent object (left) and back-lit translucent object (right), using approximated BTDF and BSSRDF. Model: Lucy from the Stanford University Computer Graphics Laboratory</span></center></div></center>
+</p>
+<a class="target" name="occlusion">&nbsp;</a><a class="target" name="lighting/occlusion">&nbsp;</a><a class="target" name="toc5.6">&nbsp;</a><h2>Occlusion</h2>
+<p>
+
+Occlusion is an important darkening factor used to recreate shadowing at various scales:
+</p><p>
+<dl><table><tr valign=top><td><dt>Small&nbsp;scale</dt></td><td><dd><p>    Micro-occlusion used to handle creases, cracks and cavities.
+</p></dd></td></tr><tr valign=top><td><dt>Medium&nbsp;scale</dt></td><td><dd><p>    Macro-occlusion used to handle occlusion by an object's own geometry or by geometry baked in normal maps (bricks, etc.).
+</p></dd></td></tr><tr valign=top><td><dt>Large&nbsp;scale</dt></td><td><dd><p>    Occlusion coming from contact between objects, or from an object's own geometry.
+</p></dd></td></tr></table></dl>We currently ignore micro-occlusion, which is often exposed in tools and engines under the form of a &ldquo;cavity map&rdquo;. Sébastien Lagarde offers an interesting discussion in [<a href="#citation-lagarde14" target="_self">Lagarde14</a>] on how micro-occlusion is handled in Frostbite: diffuse micro-occlusion is pre-baked in diffuse maps and specular micro-occlusion is pre-baked in reflectance textures.
+In our system, micro-occlusion can simply be baked in the base color map. This must be done knowing that the specular light will not be affected by micro-occlusion.
+</p><p>
+Medium scale ambient occlusion is pre-baked in ambient occlusion maps, exposed as a material parameter, as seen in the material <a href="#parameterization" target="_self">parameterization</a> section earlier.
+</p><p>
+Large scale ambient occlusion is often computed using screen-space techniques such as <em class="asterisk">SSAO</em> (screen-space ambient occlusion), <em class="asterisk">HBAO</em> (horizon based ambient occlusion), etc. Note that these techniques can also contribute to medium scale ambient occlusion when the camera is close enough to surfaces.
+</p><p>
+<strong class="asterisk">Note</strong>: to prevent over darkening when using both medium and large scale occlusion, Lagarde recommends to use \(min({AO}_{medium}, {AO}_{large})\).
+</p>
+<a class="target" name="diffuseocclusion">&nbsp;</a><a class="target" name="lighting/occlusion/diffuseocclusion">&nbsp;</a><a class="target" name="toc5.6.1">&nbsp;</a><h3>Diffuse occlusion</h3>
+<p>
+
+Morgan McGuire formalizes ambient occlusion in the context of physically based rendering in [<a href="#citation-mcguire10" target="_self">McGuire10</a>]. In his formulation, McGuire defines an ambient illumination function \( L_a \), which in our case is encoded with spherical harmonics. He also defines a visibility function \(V\), with \(V(l)=1\) if there is an unoccluded line of sight from the surface in direction \(l\), and 0 otherwise.
+</p><p>
+With these two functions, the ambient term of the rendering equation can be expressed as shown in equation \(\ref{diffuseAO}\).
+</p><p>
+$$\begin{equation}\label{diffuseAO}
+L(l,v) = \int_{\Omega} f(l,v) L_a(l) V(l) \left< \NoL \right> dl
+\end{equation}$$
+</p><p>
+This expression can be approximated by separating the visibility term from the illumination function, as shown in equation \(\ref{diffuseAOApprox}\).
+</p><p>
+$$\begin{equation}\label{diffuseAOApprox}
+L(l,v) \approx \left( \pi \int_{\Omega} f(l,v) L_a(l) dl \right) \left( \frac{1}{\pi} \int_{\Omega} V(l) \left< \NoL \right> dl \right)
+\end{equation}$$
+</p><p>
+This approximation is only exact when the distant light \( L_a \) is constant and \(f\) is a Lambertian term. McGuire states however that this approximation is reasonable if both functions are relatively smooth over most of the sphere. This happens to be the case with a distant light probe (IBL).
+</p><p>
+The left term of this approximation is the pre-computed diffuse component of our IBL. The right term is a scalar factor between 0 and 1 that indicates the fractional accessibility of a point. Its opposite is the diffuse ambient occlusion term, show in equation \(\ref{diffuseAOTerm}\).
+</p><p>
+$$\begin{equation}\label{diffuseAOTerm}
+{AO} = 1 - \frac{1}{\pi} \int_{\Omega} V(l) \left< \NoL \right> dl
+\end{equation}$$
+</p><p>
+Since we use a pre-computed diffuse term, we cannot compute the exact accessibility of shaded points at runtime. To compensate for this lack of information in our precomputed term, we partially reconstruct incident lighting by applying an ambient occlusion factor specific to the surface's material at the shaded point.
+</p><p>
+In practice, baked ambient occlusion is stored as a grayscale texture which can often be lower resolution than other textures (base color or normals for instance). It is important to note that the ambient occlusion property of our material model intends to recreate macro-level diffuse ambient occlusion. While this approximation is not physically correct, it constitutes an acceptable tradeoff of quality vs performance.
+</p><p>
+<a href="#figure_aocomparison" target="_self">Figure&nbsp;66</a> shows two different materials without and with diffuse ambient occlusion. Notice how the material ambient occlusion is used to recreate the natural shadowing that occurs between the different tiles. Without ambient occlusion, both materials appear too flat.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_aocomparison">&nbsp;</a><a href="../images/screenshot_ao.jpg" target="_blank"><img class="markdeep" src="../images/screenshot_ao.jpg" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;66:</b> Comparison of materials without diffuse ambient occlusion (left) and with (right)</span></center></div></center>
+</p><p>
+Applying baked diffuse ambient occlusion in a GLSL shader is straightforward, as shown in <a href="#listing_bakeddiffuseao" target="_self">listing&nbsp;36</a>.
+</p><a class="target" name="listing_bakeddiffuseao">&nbsp;</a><pre class="listing tilde"><code><span class="line"></span><span class="hljs-comment">// diffuse indirect</span>
+<span class="line"></span><span class="hljs-type">vec3</span> indirectDiffuse = <span class="hljs-built_in">max</span>(irradianceSH(n), <span class="hljs-number">0.0</span>) * Fd_Lambert();
+<span class="line"></span><span class="hljs-comment">// ambient occlusion</span>
+<span class="line"></span>indirectDiffuse *= <span class="hljs-built_in">texture2D</span>(aoMap, outUV).r;</code></pre><center><div class="listingcaption tilde"><b style="font-style:normal;">Listing&nbsp;36:</b> Implementation of baked diffuse ambient occlusion in GLSL</div></center>
+<p>
+
+Note how the ambient occlusion term is only applied to indirect lighting.
+</p>
+<a class="target" name="specularocclusion">&nbsp;</a><a class="target" name="lighting/occlusion/specularocclusion">&nbsp;</a><a class="target" name="toc5.6.2">&nbsp;</a><h3>Specular occlusion</h3>
+<p>
+
+Specular micro-occlusion can be derived from \(\fNormal\), itself derived from the diffuse color. The derivation is based on the knowledge that no real-world material has a reflectance lower than 2%. Values in the 0-2% range can therefore be treated as pre-baked specular occlusion used to smoothly extinguish the Fresnel term.
+</p><a class="target" name="listing_specularmicroocclusion">&nbsp;</a><pre class="listing tilde"><code><span class="line"></span><span class="hljs-type">float</span> f90 = <span class="hljs-built_in">clamp</span>(<span class="hljs-built_in">dot</span>(f0, <span class="hljs-number">50.0</span> * <span class="hljs-number">0.33</span>), <span class="hljs-number">0.0</span>, <span class="hljs-number">1.0</span>);
+<span class="line"></span><span class="hljs-comment">// cheap luminance approximation</span>
+<span class="line"></span><span class="hljs-type">float</span> f90 = <span class="hljs-built_in">clamp</span>(<span class="hljs-number">50.0</span> * f0.g, <span class="hljs-number">0.0</span>, <span class="hljs-number">1.0</span>);</code></pre><center><div class="listingcaption tilde"><b style="font-style:normal;">Listing&nbsp;37:</b> Pre-baked specular occlusion in GLSL</div></center>
+<p>
+
+The derivations mentioned earlier for ambient occlusion assume Lambertian surfaces and are only valid for indirect diffuse lighting. The lack of information about surface accessibility is particularly harmful to the reconstruction of indirect specular lighting. It usually manifests itself as light leaks.
+</p><p>
+Sébastien Lagarde proposes an empirical approach to derive the specular occlusion term from the diffuse occlusion term in [<a href="#citation-lagarde14" target="_self">Lagarde14</a>]. The result does not have any physical basis but produces visually pleasant results. The goal of his formulation is return the diffuse occlusion term unmodified for rough surfaces. For smooth surfaces, the formulation, implemented in <a href="#listing_specularocclusion" target="_self">listing&nbsp;38</a>, reduces the influence of occlusion at normal incidence and increases it at grazing angles.
+</p><a class="target" name="listing_specularocclusion">&nbsp;</a><pre class="listing tilde"><code><span class="line"></span><span class="hljs-type">float</span> computeSpecularAO(<span class="hljs-type">float</span> NoV, <span class="hljs-type">float</span> ao, <span class="hljs-type">float</span> roughness) {
+<span class="line"></span>    <span class="hljs-keyword">return</span> <span class="hljs-built_in">clamp</span>(<span class="hljs-built_in">pow</span>(NoV + ao, <span class="hljs-built_in">exp2</span>(<span class="hljs-number">-16.0</span> * roughness - <span class="hljs-number">1.0</span>)) - <span class="hljs-number">1.0</span> + ao, <span class="hljs-number">0.0</span>, <span class="hljs-number">1.0</span>);
+<span class="line"></span>}
+<span class="line"></span>
+<span class="line"></span><span class="hljs-comment">// specular indirect</span>
+<span class="line"></span><span class="hljs-type">vec3</span> indirectSpecular = evaluateSpecularIBL(r, perceptualRoughness);
+<span class="line"></span><span class="hljs-comment">// ambient occlusion</span>
+<span class="line"></span><span class="hljs-type">float</span> ao = <span class="hljs-built_in">texture2D</span>(aoMap, outUV).r;
+<span class="line"></span>indirectSpecular *= computeSpecularAO(NoV, ao, roughness);</code></pre><center><div class="listingcaption tilde"><b style="font-style:normal;">Listing&nbsp;38:</b> Implementation of Lagarde's specular occlusion factor in GLSL</div></center>
+<p>
+
+Note how the specular occlusion factor is only applied to indirect lighting.
+</p>
+<a class="target" name="horizonspecularocclusion">&nbsp;</a><a class="target" name="lighting/occlusion/specularocclusion/horizonspecularocclusion">&nbsp;</a><a class="target" name="toc5.6.2.1">&nbsp;</a><h4>Horizon specular occlusion</h4>
+<p>
+
+When computing the specular IBL contribution for a surface that uses a normal map, it is possible to end up with a reflection vector pointing towards the surface. If this reflection vector is used for shading directly, the surface will be lit in places where it should not be lit (assuming opaque surfaces). This is another occurrence of light leaking that can easily be minimized using a simple technique described by Jeff Russell [<a href="#citation-russell15" target="_self">Russell15</a>].
+</p><p>
+The key idea is to occlude light coming from behind the surface. This can easily be achieved since a negative dot product between the reflected vector and the surface's normal indicates a reflection vector pointing towards the surface. Our implementation shown in <a href="#listing_horizonocclusion" target="_self">listing&nbsp;39</a> is similar to Russell's, albeit without the artist controlled horizon fading factor.
+</p><a class="target" name="listing_horizonocclusion">&nbsp;</a><pre class="listing tilde"><code><span class="line"></span><span class="hljs-comment">// specular indirect</span>
+<span class="line"></span><span class="hljs-type">vec3</span> indirectSpecular = evaluateSpecularIBL(r, perceptualRoughness);
+<span class="line"></span>
+<span class="line"></span><span class="hljs-comment">// horizon occlusion with falloff, should be computed for direct specular too</span>
+<span class="line"></span><span class="hljs-type">float</span> horizon = <span class="hljs-built_in">min</span>(<span class="hljs-number">1.0</span> + <span class="hljs-built_in">dot</span>(r, n), <span class="hljs-number">1.0</span>);
+<span class="line"></span>indirectSpecular *= horizon * horizon;</code></pre><center><div class="listingcaption tilde"><b style="font-style:normal;">Listing&nbsp;39:</b> Implementation of horizon specular occlusion in GLSL</div></center>
+<p>
+
+Horizon specular occlusion fading is cheap but can easily be omitted to improve performance as needed.
+</p>
+<a class="target" name="normalmapping">&nbsp;</a><a class="target" name="lighting/normalmapping">&nbsp;</a><a class="target" name="toc5.7">&nbsp;</a><h2>Normal mapping</h2>
+<p>
+
+There are two common use cases of normal maps: replacing high-poly meshes with low-poly meshes (using a base map) and adding surface details (using a detail map).
+</p><p>
+Let's imagine that we want to render a piece of furniture covered in tufted leather. Modeling the geometry to accurately represent the tufted pattern would require too many triangles so we instead bake a high-poly mesh into a normal map. Once the base map is applied to a simplified mesh (in this case, a quad), we get the result in <a href="#figure_normalmapped" target="_self">figure&nbsp;67</a>. The base map used to create this effect is shown in <a href="#figure_basenormalmap" target="_self">figure&nbsp;68</a>.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_normalmapped">&nbsp;</a><a href="../images/screenshot_normal_mapping.jpg" target="_blank"><img class="markdeep" src="../images/screenshot_normal_mapping.jpg" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;67:</b> Low-poly mesh without normal mapping (left) and with (right)</span></center></div></center>
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_basenormalmap">&nbsp;</a><a href="../images/screenshot_normal_map.jpg" target="_blank"><img class="markdeep" src="../images/screenshot_normal_map.jpg" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;68:</b> Normal map used as a base map</span></center></div></center>
+</p><p>
+A simple problem arises if we now want to combine this base map with a second normal map. For instance, let's use the detail map shown in <a href="#figure_detailnormalmap" target="_self">figure&nbsp;69</a> to add cracks in the leather.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_detailnormalmap">&nbsp;</a><a href="../images/screenshot_normal_map_detail.jpg" target="_blank"><img class="markdeep" src="../images/screenshot_normal_map_detail.jpg" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;69:</b> Normal map used as a detail map</span></center></div></center>
+</p><p>
+Given the nature of normal maps (XYZ components stored in tangent space), it is fairly obvious that naive approaches such as linear or overlay blending cannot work. We will use two more advanced techniques: a mathematically correct one and an approximation suitable for real-time shading.
+</p>
+<a class="target" name="reorientednormalmapping">&nbsp;</a><a class="target" name="lighting/normalmapping/reorientednormalmapping">&nbsp;</a><a class="target" name="toc5.7.1">&nbsp;</a><h3>Reoriented normal mapping</h3>
+<p>
+
+Colin Barré-Brisebois and Stephen Hill propose in [<a href="#citation-hill12" target="_self">Hill12</a>] a mathematically sound solution called <em class="asterisk">Reoriented Normal Mapping</em>, which consists in rotating the basis of the detail map onto the normal from the base map. This technique relies on the shortest arc quaternion to apply the rotation, which greatly simplifies thanks to the properties of the tangent space.
+</p><p>
+Following the simplifications described in [<a href="#citation-hill12" target="_self">Hill12</a>], we can produce the GLSL implementation shown in <a href="#listing_reorientednormalmapping" target="_self">listing&nbsp;40</a>.
+</p><a class="target" name="listing_reorientednormalmapping">&nbsp;</a><pre class="listing tilde"><code><span class="line"></span><span class="hljs-type">vec3</span> t = <span class="hljs-built_in">texture</span>(baseMap,   uv).xyz * <span class="hljs-type">vec3</span>( <span class="hljs-number">2.0</span>,  <span class="hljs-number">2.0</span>, <span class="hljs-number">2.0</span>) + <span class="hljs-type">vec3</span>(<span class="hljs-number">-1.0</span>, <span class="hljs-number">-1.0</span>,  <span class="hljs-number">0.0</span>);
+<span class="line"></span><span class="hljs-type">vec3</span> u = <span class="hljs-built_in">texture</span>(detailMap, uv).xyz * <span class="hljs-type">vec3</span>(<span class="hljs-number">-2.0</span>, <span class="hljs-number">-2.0</span>, <span class="hljs-number">2.0</span>) + <span class="hljs-type">vec3</span>( <span class="hljs-number">1.0</span>,  <span class="hljs-number">1.0</span>, <span class="hljs-number">-1.0</span>);
+<span class="line"></span><span class="hljs-type">vec3</span> r = <span class="hljs-built_in">normalize</span>(t * <span class="hljs-built_in">dot</span>(t, u) - u * t.z);
+<span class="line"></span><span class="hljs-keyword">return</span> r;</code></pre><center><div class="listingcaption tilde"><b style="font-style:normal;">Listing&nbsp;40:</b> Implementation of reoriented normal mapping in GLSL</div></center>
+<p>
+
+Note that this implementation assumes that the normals are stored uncompressed and in the [0..1] range in the source textures.
+</p><p>
+The normalization step is not strictly necessary and can be skipped if the technique is used at runtime. If so, the computation of <code>r</code> becomes <code>t * dot(t, u) / t.z - u</code>.
+</p><p>
+Since this technique is slightly more expensive than the one described below, we will mostly use it offline. We therefore provide a simple offline tool to combine two normal maps. <a href="#figure_blendednormalmaps" target="_self">Figure&nbsp;70</a> presents the output of the tool with the base map and the detail map shown previously.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_blendednormalmaps">&nbsp;</a><a href="../images/screenshot_normal_map_blended.jpg" target="_blank"><img class="markdeep" src="../images/screenshot_normal_map_blended.jpg" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;70:</b> Blended normal and detail map (left) and resulting render when combined with a diffuse map (right)</span></center></div></center>
+</p>
+<a class="target" name="udnblending">&nbsp;</a><a class="target" name="lighting/normalmapping/udnblending">&nbsp;</a><a class="target" name="toc5.7.2">&nbsp;</a><h3>UDN blending</h3>
+<p>
+
+The technique called UDN blending, described in [<a href="#citation-hill12" target="_self">Hill12</a>], is a variant of the partial derivative blending technique. Its main advantage is the low number of shader instructions it requires (see <a href="#listing_udnblending" target="_self">listing&nbsp;41</a>). While it leads to a reduction in details over flat areas, UDN blending is interesting if blending must be performed at runtime.
+</p><a class="target" name="listing_udnblending">&nbsp;</a><pre class="listing tilde"><code><span class="line"></span><span class="hljs-type">vec3</span> t = <span class="hljs-built_in">texture</span>(baseMap,   uv).xyz * <span class="hljs-number">2.0</span> - <span class="hljs-number">1.0</span>;
+<span class="line"></span><span class="hljs-type">vec3</span> u = <span class="hljs-built_in">texture</span>(detailMap, uv).xyz * <span class="hljs-number">2.0</span> - <span class="hljs-number">1.0</span>;
+<span class="line"></span><span class="hljs-type">vec3</span> r = <span class="hljs-built_in">normalize</span>(t.xy + u.xy, t.z);
+<span class="line"></span><span class="hljs-keyword">return</span> r;</code></pre><center><div class="listingcaption tilde"><b style="font-style:normal;">Listing&nbsp;41:</b> Implementation of UDN blending in GLSL</div></center>
+<p>
+
+The results are visually close to Reoriented Normal Mapping but a careful comparison of the data shows that UDN is indeed less correct. <a href="#figure_blendednormalmapsudn" target="_self">Figure&nbsp;71</a> presents the result of the UDN blending approach using the same source data as in the previous examples.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_blendednormalmapsudn">&nbsp;</a><a href="../images/screenshot_normal_map_blended_udn.jpg" target="_blank"><img class="markdeep" src="../images/screenshot_normal_map_blended_udn.jpg" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;71:</b> Blended normal and detail map using the UDN blending technique</span></center></div></center>
+</p>
+<a class="target" name="volumetriceffects">&nbsp;</a><a class="target" name="volumetriceffects">&nbsp;</a><a class="target" name="toc6">&nbsp;</a><h1>Volumetric effects</h1>
+<a class="target" name="exponentialheightfog">&nbsp;</a><a class="target" name="volumetriceffects/exponentialheightfog">&nbsp;</a><a class="target" name="toc6.1">&nbsp;</a><h2>Exponential height fog</h2>
+<p>
+
+<center><div class="image" style=""><a class="target" name="figure_exponentialheightfog1">&nbsp;</a><a href="../images/screenshot_fog1.jpg" target="_blank"><img class="markdeep" src="../images/screenshot_fog1.jpg" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;72:</b> Example of directional in-scattering with exponential height fog</span></center></div></center>
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_exponentialheightfog2">&nbsp;</a><a href="../images/screenshot_fog2.jpg" target="_blank"><img class="markdeep" src="../images/screenshot_fog2.jpg" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;73:</b> Example of directional in-scattering with exponential height fog</span></center></div></center>
+</p>
+<a class="target" name="anti-aliasing">&nbsp;</a><a class="target" name="anti-aliasing">&nbsp;</a><a class="target" name="toc7">&nbsp;</a><h1>Anti-aliasing</h1>
+<p>
+
+[TODO] MSAA, geometric AA (normals and roughness), shader anti-aliasing (object-space shading?)
+</p>
+<a class="target" name="imagingpipeline">&nbsp;</a><a class="target" name="imagingpipeline">&nbsp;</a><a class="target" name="toc8">&nbsp;</a><h1>Imaging pipeline</h1>
+<p>
+
+The <a href="#lighting" target="_self">lighting</a> section of this document describes how light interacts with surfaces in the scene in a physically based manner. To achieve plausible results, we must go a step further and consider the transformations necessary to convert the scene luminance, as computed by our lighting equations, into displayable pixel values.
+</p><p>
+The series of transformations we are going to use form the following imaging pipeline:
+</p><p>
+<svg class="diagram" xmlns="http://www.w3.org/2000/svg" version="1.1" height="432" width="672" style="margin:0 auto 0 auto;"><g transform="translate(8,16 )">
+<path d="M 8,0 L 8,64 " style="fill:none;"/>
+<path d="M 120,0 L 120,64 " style="fill:none;"/>
+<path d="M 176,0 L 176,64 " style="fill:none;"/>
+<path d="M 296,0 L 296,64 " style="fill:none;"/>
+<path d="M 352,0 L 352,64 " style="fill:none;"/>
+<path d="M 352,112 L 352,176 " style="fill:none;"/>
+<path d="M 352,224 L 352,288 " style="fill:none;"/>
+<path d="M 352,336 L 352,400 " style="fill:none;"/>
+<path d="M 416,64 L 416,104 " style="fill:none;"/>
+<path d="M 416,176 L 416,216 " style="fill:none;"/>
+<path d="M 416,288 L 416,328 " style="fill:none;"/>
+<path d="M 480,0 L 480,64 " style="fill:none;"/>
+<path d="M 480,112 L 480,176 " style="fill:none;"/>
+<path d="M 480,224 L 480,288 " style="fill:none;"/>
+<path d="M 480,336 L 480,400 " style="fill:none;"/>
+<path d="M 536,336 L 536,400 " style="fill:none;"/>
+<path d="M 648,336 L 648,400 " style="fill:none;"/>
+<path d="M 8,0 L 120,0 " style="fill:none;"/>
+<path d="M 176,0 L 296,0 " style="fill:none;"/>
+<path d="M 352,0 L 480,0 " style="fill:none;"/>
+<path d="M 120,32 L 168,32 " style="fill:none;"/>
+<path d="M 296,32 L 344,32 " style="fill:none;"/>
+<path d="M 8,64 L 120,64 " style="fill:none;"/>
+<path d="M 176,64 L 296,64 " style="fill:none;"/>
+<path d="M 352,64 L 480,64 " style="fill:none;"/>
+<path d="M 352,112 L 480,112 " style="fill:none;"/>
+<path d="M 352,176 L 480,176 " style="fill:none;"/>
+<path d="M 352,224 L 480,224 " style="fill:none;"/>
+<path d="M 352,288 L 480,288 " style="fill:none;"/>
+<path d="M 352,336 L 480,336 " style="fill:none;"/>
+<path d="M 536,336 L 648,336 " style="fill:none;"/>
+<path d="M 480,368 L 528,368 " style="fill:none;"/>
+<path d="M 352,400 L 480,400 " style="fill:none;"/>
+<path d="M 536,400 L 648,400 " style="fill:none;"/>
+<polygon points="536,368 524,362.4 524,373.6 "  style="stroke:none" transform="rotate(0,528,368 )"/>
+<polygon points="424,328 412,322.4 412,333.6 "  style="stroke:none" transform="rotate(90,416,328 )"/>
+<polygon points="424,216 412,210.4 412,221.6 "  style="stroke:none" transform="rotate(90,416,216 )"/>
+<polygon points="424,104 412,98.4 412,109.6 "  style="stroke:none" transform="rotate(90,416,104 )"/>
+<polygon points="352,32 340,26.4 340,37.6 "  style="stroke:none" transform="rotate(0,344,32 )"/>
+<polygon points="176,32 164,26.4 164,37.6 "  style="stroke:none" transform="rotate(0,168,32 )"/>
+<g transform="translate(0,0)"><text text-anchor="middle" x="48" y="20">S</text><text text-anchor="middle" x="56" y="20">c</text><text text-anchor="middle" x="64" y="20">e</text><text text-anchor="middle" x="72" y="20">n</text><text text-anchor="middle" x="80" y="20">e</text><text text-anchor="middle" x="200" y="20">N</text><text text-anchor="middle" x="208" y="20">o</text><text text-anchor="middle" x="216" y="20">r</text><text text-anchor="middle" x="224" y="20">m</text><text text-anchor="middle" x="232" y="20">a</text><text text-anchor="middle" x="240" y="20">l</text><text text-anchor="middle" x="248" y="20">i</text><text text-anchor="middle" x="256" y="20">z</text><text text-anchor="middle" x="264" y="20">e</text><text text-anchor="middle" x="272" y="20">d</text><text text-anchor="middle" x="32" y="36">l</text><text text-anchor="middle" x="40" y="36">u</text><text text-anchor="middle" x="48" y="36">m</text><text text-anchor="middle" x="56" y="36">i</text><text text-anchor="middle" x="64" y="36">n</text><text text-anchor="middle" x="72" y="36">a</text><text text-anchor="middle" x="80" y="36">n</text><text text-anchor="middle" x="88" y="36">c</text><text text-anchor="middle" x="96" y="36">e</text><text text-anchor="middle" x="200" y="36">l</text><text text-anchor="middle" x="208" y="36">u</text><text text-anchor="middle" x="216" y="36">m</text><text text-anchor="middle" x="224" y="36">i</text><text text-anchor="middle" x="232" y="36">n</text><text text-anchor="middle" x="240" y="36">a</text><text text-anchor="middle" x="248" y="36">n</text><text text-anchor="middle" x="256" y="36">c</text><text text-anchor="middle" x="264" y="36">e</text><text text-anchor="middle" x="368" y="36">W</text><text text-anchor="middle" x="376" y="36">h</text><text text-anchor="middle" x="384" y="36">i</text><text text-anchor="middle" x="392" y="36">t</text><text text-anchor="middle" x="400" y="36">e</text><text text-anchor="middle" x="416" y="36">b</text><text text-anchor="middle" x="424" y="36">a</text><text text-anchor="middle" x="432" y="36">l</text><text text-anchor="middle" x="440" y="36">a</text><text text-anchor="middle" x="448" y="36">n</text><text text-anchor="middle" x="456" y="36">c</text><text text-anchor="middle" x="464" y="36">e</text><text text-anchor="middle" x="216" y="52">(</text><text text-anchor="middle" x="224" y="52">H</text><text text-anchor="middle" x="232" y="52">D</text><text text-anchor="middle" x="240" y="52">R</text><text text-anchor="middle" x="248" y="52">)</text><text text-anchor="middle" x="368" y="148">C</text><text text-anchor="middle" x="376" y="148">o</text><text text-anchor="middle" x="384" y="148">l</text><text text-anchor="middle" x="392" y="148">o</text><text text-anchor="middle" x="400" y="148">r</text><text text-anchor="middle" x="416" y="148">g</text><text text-anchor="middle" x="424" y="148">r</text><text text-anchor="middle" x="432" y="148">a</text><text text-anchor="middle" x="440" y="148">d</text><text text-anchor="middle" x="448" y="148">i</text><text text-anchor="middle" x="456" y="148">n</text><text text-anchor="middle" x="464" y="148">g</text><text text-anchor="middle" x="368" y="260">T</text><text text-anchor="middle" x="376" y="260">o</text><text text-anchor="middle" x="384" y="260">n</text><text text-anchor="middle" x="392" y="260">e</text><text text-anchor="middle" x="408" y="260">m</text><text text-anchor="middle" x="416" y="260">a</text><text text-anchor="middle" x="424" y="260">p</text><text text-anchor="middle" x="432" y="260">p</text><text text-anchor="middle" x="440" y="260">i</text><text text-anchor="middle" x="448" y="260">n</text><text text-anchor="middle" x="456" y="260">g</text><text text-anchor="middle" x="576" y="356">P</text><text text-anchor="middle" x="584" y="356">i</text><text text-anchor="middle" x="592" y="356">x</text><text text-anchor="middle" x="600" y="356">e</text><text text-anchor="middle" x="608" y="356">l</text><text text-anchor="middle" x="400" y="372">O</text><text text-anchor="middle" x="408" y="372">E</text><text text-anchor="middle" x="416" y="372">T</text><text text-anchor="middle" x="424" y="372">F</text><text text-anchor="middle" x="576" y="372">v</text><text text-anchor="middle" x="584" y="372">a</text><text text-anchor="middle" x="592" y="372">l</text><text text-anchor="middle" x="600" y="372">u</text><text text-anchor="middle" x="608" y="372">e</text><text text-anchor="middle" x="576" y="388">(</text><text text-anchor="middle" x="584" y="388">L</text><text text-anchor="middle" x="592" y="388">D</text><text text-anchor="middle" x="600" y="388">R</text><text text-anchor="middle" x="608" y="388">)</text></g></g></svg>
+</p><p>
+<strong class="asterisk">Note</strong>: the <em class="asterisk">OETF</em> step is the application of the opto-electronic transfer function of the target color space. For clarity this diagram does not include post-processing steps such as vignette, bloom, etc. These effects will be discussed separately.
+</p><p>
+[TODO] Color spaces (ACES, sRGB, Rec. 709, Rec. 2020, etc.), gamma/linear, etc.
+</p>
+<a class="target" name="physicallybasedcamera">&nbsp;</a><a class="target" name="imagingpipeline/physicallybasedcamera">&nbsp;</a><a class="target" name="toc8.1">&nbsp;</a><h2>Physically based camera</h2>
+<p>
+
+The first step in the image transformation process is to use a physically based camera to properly expose the scene's outgoing luminance.
+</p>
+<a class="target" name="exposuresettings">&nbsp;</a><a class="target" name="imagingpipeline/physicallybasedcamera/exposuresettings">&nbsp;</a><a class="target" name="toc8.1.1">&nbsp;</a><h3>Exposure settings</h3>
+<p>
+
+Because we use photometric units throughout the lighting pipeline, the light reaching the camera is an energy expressed in luminance \(L\), in \(cd.m^{-2}\). Light incident to the camera sensor can cover a large range of values, from \(10^{-5}cd.m^{-2}\) for starlight to \(10^{9}cd.m^{-2}\) for the sun. Since we obviously cannot manipulate and even less record such a large range of values, we need to remap them.
+</p><p>
+This range remapping is done in a camera by exposing the sensor for a certain time. To maximize the use of the limited range of the sensor, the scene's light range is centered around the &ldquo;middle gray&rdquo;, a value halfway between black and white. The exposition is therefore achieved by manipulating, either manually or automatically, 3 settings:
+</p><p>
+<ul>
+<li class="minus">Aperture
+</li>
+<li class="minus">Shutter speed
+</li>
+<li class="minus">Sensitivity (also called gain)</li></ul>
+</p><p>
+<dl><dt>Aperture</dt><dd><p>    Noted \(N\) and expressed in f-stops ƒ, this setting controls how open or closed the camera system's aperture is. Since an f-stop indicate the ratio of the lens' focal length to the diameter of the entrance pupil, high-values (ƒ/16) indicate a small aperture and small values (ƒ/1.4) indicate a wide aperture. In addition to the exposition, the aperture setting controls the depth of field.
+</p></dd><dt>Shutter speed</dt><dd><p>    Noted \(t\) and expressed in seconds \(s\), this setting controls how long the aperture remains opened (it also controls the timing of the sensor shutter(s), whether electronic or mechanical). In addition to the exposition, the shutter speed controls motion blur.
+</p></dd><dt>Sensitivity</dt><dd><p>    Noted \(S\) and expressed in ISO, this setting controls how the light reaching the sensor is quantized. Because of its unit, this setting is often referred to as simply the &ldquo;ISO&rdquo; or &ldquo;ISO setting&rdquo;. In addition to the exposition, the sensitivity setting controls the amount of noise.
+</p></dd></dl></p>
+<a class="target" name="exposurevalue">&nbsp;</a><a class="target" name="imagingpipeline/physicallybasedcamera/exposurevalue">&nbsp;</a><a class="target" name="toc8.1.2">&nbsp;</a><h3>Exposure value</h3>
+<p>
+
+Since referring to these 3 settings in our equations would be unwieldy, we instead summarize the “exposure triangle” by an exposure value, noted EV<sup><a href="#endnote-reciprocity" target="_self">10</a></sup>.
+</p><p>
+The EV is expressed in a base-2 logarithmic scale, with a difference of 1 EV called a stop. One positive stop (+1 EV) corresponds to a factor of two in luminance and one negative stop (&minus;1 EV) corresponds to a factor of half in luminance.
+</p><p>
+Equation \( \ref{ev} \) shows the <a href="https://en.wikipedia.org/wiki/Exposure_value">formal definition of EV</a>.
+</p><p>
+$$\begin{equation}\label{ev}
+EV = log_2(\frac{N^2}{t})
+\end{equation}$$
+</p><p>
+Note that this definition is only function of the aperture and shutter speed, but not the sensitivity. An exposure value is by convention defined for ISO 100, or \( EV_{100} \), and because we wish to work with this convention, we need to be able to express \( EV_{100} \) as a function of the sensitivity.
+</p><p>
+Since we know that EV is a base-2 logarithmic scale in which each stop increases or decreases the brightness by a factor of 2, we can formally define \( EV_{S} \), the exposure value at given sensitivity (equation \(\ref{evS}\)).
+</p><p>
+$$\begin{equation}\label{evS}
+{EV}_S = EV_{100} + log_2(\frac{S}{100})
+\end{equation}$$
+</p><p>
+Calculating the \( EV_{100} \) as a function of the 3 camera settings is trivial, as shown in \(\ref{ev100}\).
+</p><p>
+$$\begin{equation}\label{ev100}
+{EV}_{100} = EV_{S} - log_2(\frac{S}{100}) = log_2(\frac{N^2}{t}) - log_2(\frac{S}{100})
+\end{equation}$$
+</p><p>
+Note that the operator (photographer, etc.) can achieve the same exposure (and therefore EV) with several combinations of aperture, shutter speed and sensitivity. This allows some artistic control in the process (depth of field vs motion blur vs grain).
+</p><p>
+<div class="endnote"><a class="target" name="endnote-reciprocity">&nbsp;</a><sup>10</sup> We assume a digital sensor, which means we don't need to take reciprocity failure into account
+</div>
+</p>
+<a class="target" name="exposurevalueandluminance">&nbsp;</a><a class="target" name="imagingpipeline/physicallybasedcamera/exposurevalue/exposurevalueandluminance">&nbsp;</a><a class="target" name="toc8.1.2.1">&nbsp;</a><h4>Exposure value and luminance</h4>
+<p>
+
+A camera, similar to a spot meter, is able to measure the average luminance of a scene and convert it into EV to achieve automatic exposure, or at the very least offer the user exposure guidance.
+</p><p>
+It is possible to define EV as a function of the scene luminance \(L\), given a per-device calibration constant \(K\) (equation \( \ref{evK} \)).
+</p><p>
+$$\begin{equation}\label{evK}
+EV = log_2(\frac{L \times S}{K})
+\end{equation}$$
+</p><p>
+That constant \(K\) is the reflected-light meter constant, which varies between manufacturers. We could find two common values for this constant: 12.5, used by Canon, Nikon and Sekonic, and 14, used by Pentax and Minolta. Given the wide availability of Canon and Nikon cameras, as well as our own usage of Sekonic light meters, we will choose to use \( K = 12.5 \).
+</p><p>
+Since we want to work with \( EV_{100} \), we can substitute \(K\) and \(S\) in equation \( \ref{evK} \) to obtain equation \( \ref{ev100L} \).
+</p><p>
+$$\begin{equation}\label{ev100L}
+EV = log_2(L \frac{100}{12.5})
+\end{equation}$$
+</p><p>
+Given this relationship, it would be possible to implement automatic exposure in our engine by first measuring the average luminance of a frame. An easy way to achieve this is to simply downsample a luminance buffer down to 1 pixel and read the remaining value. This technique is unfortunately rarely stable and can easily be affected by extreme values. Many games use a different approach which consists in using a luminance histogram to remove extreme values.
+</p><p>
+For validation and testing purposes, the luminance can be computed from a given EV:
+</p><p>
+$$\begin{equation}
+L = 2^{EV_{100}} \times \frac{12.5}{100} = 2^{EV_{100} - 3}
+\end{equation}$$
+</p>
+<a class="target" name="exposurevalueandilluminance">&nbsp;</a><a class="target" name="imagingpipeline/physicallybasedcamera/exposurevalue/exposurevalueandilluminance">&nbsp;</a><a class="target" name="toc8.1.2.2">&nbsp;</a><h4>Exposure value and illuminance</h4>
+<p>
+
+It is possible to define EV as a function of the illuminance \(E\), given a per-device calibration constant \(C\):
+</p><p>
+$$\begin{equation}\label{evC}
+EV = log_2(\frac{E \times S}{C})
+\end{equation}$$
+</p><p>
+The constant \(C\) is the incident-light meter constant, which varies between manufacturers and/or types of sensors. There are two common types of sensors: flat and hemispherical. For flat sensors, a common value is 250. With hemispherical sensors, we could find two common values: 320, used by Minolta, and 340, used by Sekonic.
+</p><p>
+Since we want to work with \( EV_{100} \), we can substitute \(S\) \( \ref{evC} \) to obtain equation \( \ref{ev100C} \).
+</p><p>
+$$\begin{equation}\label{ev100C}
+EV = log_2(E \frac{100}{C})
+\end{equation}$$
+</p><p>
+The illuminance can then be computed from a given EV. For a flat sensor with \( C = 250 \) we obtain equation \( \ref{eFlatSensor} \).
+</p><p>
+$$\begin{equation}\label{eFlatSensor}
+E = 2^{EV_{100}} \times 2.5
+\end{equation}$$
+</p><p>
+For a hemispherical sensor with \( C = 340 \) we obtain equation \( \ref{eHemisphereSensor} \)
+</p><p>
+$$\begin{equation}\label{eHemisphereSensor}
+E = 2^{EV_{100}} \times 3.4
+\end{equation}$$
+</p>
+<a class="target" name="exposurecompensation">&nbsp;</a><a class="target" name="imagingpipeline/physicallybasedcamera/exposurevalue/exposurecompensation">&nbsp;</a><a class="target" name="toc8.1.2.3">&nbsp;</a><h4>Exposure compensation</h4>
+<p>
+
+Even though an exposure value actually indicates combinations of camera settings, it is often used by photographers to describe light intensity. This is why cameras let photographers apply an exposure compensation to over or under-expose an image. This setting can be used for artistic control but also to achieve proper exposure (snow for instance will be exposed for as 18% middle-gray).
+</p><p>
+Applying an exposure compensation \(EC\) is a simple as adding an offset to the exposure value, as shown in equation \( \ref{ec} \).
+</p><p>
+$$\begin{equation}\label{ec}
+EV_{100}' = EV_{100} - EC
+\end{equation}$$
+</p><p>
+This equation uses a negative sign because we are using \(EC\) in f-stops to adjust the final exposure. Increasing the EV is akin to closing down the aperture of the lens (or reducing shutter speed or reducing sensitivity). A higher EV will produce darker images.
+</p>
+<a class="target" name="exposure">&nbsp;</a><a class="target" name="imagingpipeline/physicallybasedcamera/exposure">&nbsp;</a><a class="target" name="toc8.1.3">&nbsp;</a><h3>Exposure</h3>
+<p>
+
+To convert the scene luminance into normalized luminance, we must use the <a href="https://en.wikipedia.org/wiki/Exposure_value#Camera_settings_vs._photometric_exposure">photometric exposure</a> (or luminous exposure), or amount of scene luminance that reaches the camera sensor. The photometric exposure, expressed in lux seconds and noted \(H\), is given by equation \( \ref{photometricExposure} \).
+</p><p>
+$$\begin{equation}\label{photometricExposure}
+H = \frac{q \cdot t}{N^2} L
+\end{equation}$$
+</p><p>
+Where \(L\) is the luminance of the scene, \(t\) the shutter speed, \(N\) the aperture and \(q\) the lens and vignetting attenuation (typically \( q = 0.65 \)<sup><a href="#endnote-lensattenuation" target="_self">11</a></sup>). This definition does not take the sensor sensitivity into account. To do so, we must use one of the three ways to relate photometric exposure and sensitivity: saturation-based speed, noise-based speed and standard output sensitivity.
+</p><p>
+We choose the saturation-based speed relation, which gives us \( H_{sat} \), the maximum possible exposure that does not lead to clipped or bloomed camera output (equation \( \ref{hSat} \)).
+</p><p>
+$$\begin{equation}\label{hSat}
+H_{sat} = \frac{78}{S_{sat}}
+\end{equation}$$
+</p><p>
+We combine equations \( \ref{hSat} \) and \( \ref{photometricExposure} \) in equation \( \ref{lmax} \) to compute the maximum luminance \( L_{max} \) that will saturate the sensor given exposure settings \(S\), \(N\) and \(t\).
+</p><p>
+$$\begin{equation}\label{lmax}
+L_{max} = \frac{N^2}{q \cdot t} \frac{78}{S}
+\end{equation}$$
+</p><p>
+This maximum luminance can then be used to normalize incident luminance \(L\) as shown in equation \( \ref{normalizedLuminance} \).
+</p><p>
+$$\begin{equation}\label{normalizedLuminance}
+L' = L \frac{1}{L_{max}}
+\end{equation}$$
+</p><p>
+\( L_{max} \) can be simplified using equation \( \ref{ev} \), \( S = 100 \) and \( q = 0.65 \):
+</p><p>
+$$\begin{align*}
+L_{max} &= \frac{N^2}{t} \frac{78}{q \cdot S} \\
+L_{max} &= 2^{EV_{100}} \frac{78}{q \cdot S} \\
+L_{max} &= 2^{EV_{100}} \times 1.2
+\end{align*}$$
+</p><p>
+<a href="#listing_fragmentexposure" target="_self">Listing&nbsp;42</a> shows how the exposure term can be applied directly to the pixel color computed in a fragment shader.
+</p><a class="target" name="listing_fragmentexposure">&nbsp;</a><pre class="listing tilde"><code><span class="line"></span><span class="hljs-comment">// Computes the camera&#x27;s EV100 from exposure settings</span>
+<span class="line"></span><span class="hljs-comment">// aperture in f-stops</span>
+<span class="line"></span><span class="hljs-comment">// shutterSpeed in seconds</span>
+<span class="line"></span><span class="hljs-comment">// sensitivity in ISO</span>
+<span class="line"></span><span class="hljs-type">float</span> <span class="hljs-title function_">exposureSettings</span><span class="hljs-params">(<span class="hljs-type">float</span> aperture, <span class="hljs-type">float</span> shutterSpeed, <span class="hljs-type">float</span> sensitivity)</span> {
+<span class="line"></span>    <span class="hljs-keyword">return</span> log2((aperture * aperture) / shutterSpeed * <span class="hljs-number">100.0</span> / sensitivity);
+<span class="line"></span>}
+<span class="line"></span>
+<span class="line"></span><span class="hljs-comment">// Computes the exposure normalization factor from</span>
+<span class="line"></span><span class="hljs-comment">// the camera&#x27;s EV100</span>
+<span class="line"></span><span class="hljs-type">float</span> <span class="hljs-title function_">exposure</span><span class="hljs-params">(<span class="hljs-type">float</span> ev100)</span> {
+<span class="line"></span>    <span class="hljs-keyword">return</span> <span class="hljs-number">1.0</span> / (pow(<span class="hljs-number">2.0</span>, ev100) * <span class="hljs-number">1.2</span>);
+<span class="line"></span>}
+<span class="line"></span>
+<span class="line"></span><span class="hljs-type">float</span> <span class="hljs-variable">ev100</span> <span class="hljs-operator">=</span> exposureSettings(aperture, shutterSpeed, sensitivity);
+<span class="line"></span><span class="hljs-type">float</span> <span class="hljs-variable">exposure</span> <span class="hljs-operator">=</span> exposure(ev100);
+<span class="line"></span>
+<span class="line"></span><span class="hljs-type">vec4</span> <span class="hljs-variable">color</span> <span class="hljs-operator">=</span> evaluateLighting();
+<span class="line"></span>color.rgb *= exposure;</code></pre><center><div class="listingcaption tilde"><b style="font-style:normal;">Listing&nbsp;42:</b> Implementation of exposure in GLSL</div></center>
+<p>
+
+In practice the exposure factor can be pre-computed on the CPU to save shader instructions.
+</p><p>
+<div class="endnote"><a class="target" name="endnote-lensattenuation">&nbsp;</a><sup>11</sup> See <em class="asterisk">Film Speed, Measurements and calculations</em> on Wikipedia (<a href="https://en.wikipedia.org/wiki/Film_speed)" class="url">https://en.wikipedia.org/wiki/Film_speed)</a>
+</div>
+</p>
+<a class="target" name="automaticexposure">&nbsp;</a><a class="target" name="imagingpipeline/physicallybasedcamera/automaticexposure">&nbsp;</a><a class="target" name="toc8.1.4">&nbsp;</a><h3>Automatic exposure</h3>
+<p>
+
+The process described above relies on artists setting the camera exposure settings manually. This can prove cumbersome in practice since camera movements and/or dynamic effects can greatly affect the scene's luminance. Since we know how to compute the exposure value from a given luminance (see section <a href="#toc8.1.2.1" target="_self">8.1.2.1</a>), we can transform our camera into a spot meter. To do so, we need to measure the scene's luminance.
+</p><p>
+There are two common techniques used to measure the scene's luminance:
+</p><p>
+<ul>
+<li class="minus"><strong class="asterisk">Luminance downsampling</strong>, by downsampling the previous frame successively until obtaining a 1&times;1 log luminance buffer that can be read on the CPU (this could also be achieved using a compute shader). The result is the average log luminance of the scene. The first downsampling must extract the luminance of each pixel first. This technique can be unstable and its output should be smoothed over time.
+</li>
+<li class="minus"><strong class="asterisk">Using a luminance histogram</strong>, to find the average log luminance. This technique has an advantage over the previous one as it allows to ignore extreme values and offers more stable results.</li></ul>
+</p><p>
+Note that both methods will find the average luminance after multiplication by the albedo. This is not entirely correct but the alternative is to keep a luminance buffer that contains the luminance of each pixel before multiplication by the surface albedo. This is expensive both computationally and memory-wise.
+</p><p>
+These two techniques also limit the metering system to average metering, where each pixel has the same influence (or weight) over the final exposure. Cameras typically offer 3 modes of metering:
+</p><p>
+<dl><dt>Spot metering</dt><dd><p>    In which only a small circle in the center of the image contributes to the final exposure. That circle is usually 1 to 5% of the total image size.
+</p></dd><dt>Center-weighted metering</dt><dd><p>    Gives more influence to scene luminance values located in the center of the screen.
+</p></dd><dt>Multi-zone or matrix metering</dt><dd><p>    A metering mode that differs for each manufacturer. The goal of this mode is to prioritize exposure for the most important parts of the scene. This is often achieved by splitting the image into a grid and by classifying each cell (using focus information, min/max luminance, etc.). Advanced implementations attempt to compare the scene to a known dataset to achieve proper exposure (backlit sunset, overcast snowy day, etc.).
+</p></dd></dl></p>
+<a class="target" name="spotmetering">&nbsp;</a><a class="target" name="imagingpipeline/physicallybasedcamera/automaticexposure/spotmetering">&nbsp;</a><a class="target" name="toc8.1.4.1">&nbsp;</a><h4>Spot metering</h4>
+<p>
+
+The weight \(w\) of each luminance value to use when computing the scene luminance is given by equation \( \ref{spotMetering} \).
+</p><p>
+$$\begin{equation}\label{spotMetering}
+w(x,y) = \begin{cases} 1 & \left| p_{x,y} - s_{x,y} \right| \le s_r \\ 0 & \left| p_{x,y} - s_{x,y} \right| \gt s_r \end{cases}
+\end{equation}$$
+</p><p>
+Where \(p\) is the position of the pixel, \(s\) the center of the spot and \( s_r \) the radius of the spot.
+</p>
+<a class="target" name="center-weightedmetering">&nbsp;</a><a class="target" name="imagingpipeline/physicallybasedcamera/automaticexposure/center-weightedmetering">&nbsp;</a><a class="target" name="toc8.1.4.2">&nbsp;</a><h4>Center-weighted metering</h4>
+<p>
+
+$$\begin{equation}\label{centerMetering}
+w(x,y) = smooth(\left| p_{x,y} - c \right| \times \frac{2}{width} )
+\end{equation}$$
+</p><p>
+Where \(c\) is the center of the time and \( smooth() \) a smoothing function such as GLSL's <code>smoothstep()</code>.
+</p>
+<a class="target" name="adaptation">&nbsp;</a><a class="target" name="imagingpipeline/physicallybasedcamera/automaticexposure/adaptation">&nbsp;</a><a class="target" name="toc8.1.4.3">&nbsp;</a><h4>Adaptation</h4>
+<p>
+
+To smooth the result of the metering, we can use equation \( \ref{adaptation} \), an exponential feedback loop as described by Pattanaik et al. in [Pattanaik00].
+</p><p>
+$$\begin{equation}\label{adaptation}
+L_{avg} = L_{avg} + (L - L_{avg}) \times (1 - e^{-\Delta t \cdot \tau})
+\end{equation}$$
+</p><p>
+Where \( \Delta t \) is the delta time from the previous frame and \(\tau\) a constant that controls the adaptation rate.
+</p>
+<a class="target" name="bloom">&nbsp;</a><a class="target" name="imagingpipeline/physicallybasedcamera/bloom">&nbsp;</a><a class="target" name="toc8.1.5">&nbsp;</a><h3>Bloom</h3>
+<p>
+
+Because the EV scale is almost perceptually linear, the exposure value is also often used as a light unit. This means we could let artists specify the intensity of lights or emissive surfaces using exposure compensation as a unit. The intensity of emitted light would therefore be relative to the exposure settings. Using exposure compensation as a light unit should be avoided whenever possible but can be useful to force (or cancel) a bloom effect around emissive surfaces independently of the camera settings (for instance, a lightsaber in a game should always bloom).
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_bloom">&nbsp;</a><a href="../images/screenshot_bloom.jpg" target="_blank"><img class="markdeep" src="../images/screenshot_bloom.jpg" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;74:</b> Saturated photosites on a sensor create a blooming effect in the bright parts of the scene</span></center></div></center>
+</p><p>
+With \(c\) the bloom color and \( EV_{100} \) the current exposure value, we can easily compute the luminance of the bloom value as show in equation \( \ref{bloomEV} \).
+</p><p>
+$$\begin{equation}\label{bloomEV}
+EV_{bloom} = EV_{100} + EC \\
+L_{bloom} = c \times 2^{EV_{bloom} - 3}
+\end{equation}$$
+</p><p>
+Equation \( \ref{bloomEV} \) can be used in a fragment shader to implement emissive blooms, as shown in <a href="#listing_fragmentemissive" target="_self">listing&nbsp;43</a>.
+</p><a class="target" name="listing_fragmentemissive">&nbsp;</a><pre class="listing tilde"><code><span class="line"></span><span class="hljs-type">vec4</span> surfaceShading() {
+<span class="line"></span>    <span class="hljs-type">vec4</span> color = evaluateLights();
+<span class="line"></span>    <span class="hljs-comment">// rgb = color, w = exposure compensation</span>
+<span class="line"></span>    <span class="hljs-type">vec4</span> emissive = getEmissive();
+<span class="line"></span>    color.rgb += emissive.rgb * <span class="hljs-built_in">pow</span>(<span class="hljs-number">2.0</span>, ev100 + emissive.w - <span class="hljs-number">3.0</span>);
+<span class="line"></span>    color.rgb *= exposure;
+<span class="line"></span>    <span class="hljs-keyword">return</span> color;
+<span class="line"></span>}</code></pre><center><div class="listingcaption tilde"><b style="font-style:normal;">Listing&nbsp;43:</b> Implementation of emissive bloom in GLSL</div></center>
+<a class="target" name="opticspost-processing">&nbsp;</a><a class="target" name="imagingpipeline/opticspost-processing">&nbsp;</a><a class="target" name="toc8.2">&nbsp;</a><h2>Optics post-processing</h2>
+<a class="target" name="colorfringing">&nbsp;</a><a class="target" name="imagingpipeline/opticspost-processing/colorfringing">&nbsp;</a><a class="target" name="toc8.2.1">&nbsp;</a><h3>Color fringing</h3>
+<p>
+
+[TODO]
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_fringing">&nbsp;</a><a href="../images/screenshot_fringing.jpg" target="_blank"><img class="markdeep" src="../images/screenshot_fringing.jpg" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;75:</b> Example of color fringing: look at the ear on the left or the chin at the bottom.</span></center></div></center>
+</p>
+<a class="target" name="lensflares">&nbsp;</a><a class="target" name="imagingpipeline/opticspost-processing/lensflares">&nbsp;</a><a class="target" name="toc8.2.2">&nbsp;</a><h3>Lens flares</h3>
+<p>
+
+[TODO] Notes: there is a physically based approach to generating lens flares, by tracing rays through the optical assembly of the lens, but we are going to use an image-based approach. This approach is cheaper and has a few welcome benefits such as free emitters occlusion and unlimited light sources support.
+</p>
+<a class="target" name="filmicpost-processing">&nbsp;</a><a class="target" name="imagingpipeline/filmicpost-processing">&nbsp;</a><a class="target" name="toc8.3">&nbsp;</a><h2>Filmic post-processing</h2>
+<p>
+
+[TODO] Perform post-processing on the scene referred data (linear space, before tone-mapping) as much as possible
+</p><p>
+It is important to provide color correction tools to give artists greater artistic control over the final image. These tools are found in every photo or video processing application, such as Adobe Photoshop or Adobe After Effects.
+</p>
+<a class="target" name="contrast">&nbsp;</a><a class="target" name="imagingpipeline/filmicpost-processing/contrast">&nbsp;</a><a class="target" name="toc8.3.1">&nbsp;</a><h3>Contrast</h3>
+<a class="target" name="curves">&nbsp;</a><a class="target" name="imagingpipeline/filmicpost-processing/curves">&nbsp;</a><a class="target" name="toc8.3.2">&nbsp;</a><h3>Curves</h3>
+<a class="target" name="levels">&nbsp;</a><a class="target" name="imagingpipeline/filmicpost-processing/levels">&nbsp;</a><a class="target" name="toc8.3.3">&nbsp;</a><h3>Levels</h3>
+<a class="target" name="colorgrading">&nbsp;</a><a class="target" name="imagingpipeline/filmicpost-processing/colorgrading">&nbsp;</a><a class="target" name="toc8.3.4">&nbsp;</a><h3>Color grading</h3>
+<a class="target" name="lightpath">&nbsp;</a><a class="target" name="imagingpipeline/lightpath">&nbsp;</a><a class="target" name="toc8.4">&nbsp;</a><h2>Light path</h2>
+<p>
+
+The light path, or rendering method, used by the engine can have serious performance implications and may impose strong limitations on how many lights can be used in a scene. There are traditionally two different rendering methods used by 3D engines forward and deferred rendering.
+</p><p>
+Our goal is to use a rendering method that obeys the following constraints:
+</p><p>
+<ul>
+<li class="minus">Low bandwidth requirements
+</li>
+<li class="minus">Multiple dynamic lights per pixel</li></ul>
+</p><p>
+Additionally, we would like to easily support:
+</p><p>
+<ul>
+<li class="minus">MSAA
+</li>
+<li class="minus">Transparency
+</li>
+<li class="minus">Multiple material models</li></ul>
+</p><p>
+Deferred rendering is used by many modern 3D rendering engines to easily support dozens, hundreds or even thousands of light source (amongst other benefits). This method is unfortunately very expensive in terms of bandwidth. With our default PBR material model, our G-buffer would use between 160 and 192 bits per pixel, which would translate directly to rather high bandwidth requirements.
+</p><p>
+Forward rendering methods on the other hand have historically been bad at handling multiple lights. A common implementation is to render the scene multiple times, once per visible light, and to blend (add) the results. Another technique consists in assigning a fixed maximum of lights to each object in the scene. This is however impractical when objects occupy a vast amount of space in the world (building, road, etc.).
+</p><p>
+Tiled shading can be applied to both forward and deferred rendering methods. The idea is to split the screen in a grid of tiles and for each tile, find the list of lights that affect the pixels within that tile. This has the advantage of reducing overdraw (in deferred rendering) and shading computations of large objects (in forward rendering). This technique suffers however from depth discontinuities issues that can lead to large amounts of extraneous work.
+</p><p>
+The scene displayed in <a href="#figure_sponza" target="_self">figure&nbsp;76</a> was rendered using clustered forward rendering.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_sponza">&nbsp;</a><a href="../images/screenshot_sponza.jpg" target="_blank"><img class="markdeep" src="../images/screenshot_sponza.jpg" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;76:</b> Clustered forward rendering with dozens of dynamic lights and MSAA</span></center></div></center>
+</p><p>
+<a href="#figure_sponzatiles" target="_self">Figure&nbsp;77</a> shows the same scene split in tiles (in this case, a 1280&times;720 render target with 80&times;80px tiles).
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_sponzatiles">&nbsp;</a><a href="../images/screenshot_sponza_tiles.jpg" target="_blank"><img class="markdeep" src="../images/screenshot_sponza_tiles.jpg" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;77:</b> Tiled shading (16&times;9 tiles)</span></center></div></center>
+</p>
+<a class="target" name="clusteredforwardrendering">&nbsp;</a><a class="target" name="imagingpipeline/lightpath/clusteredforwardrendering">&nbsp;</a><a class="target" name="toc8.4.1">&nbsp;</a><h3>Clustered Forward Rendering</h3>
+<p>
+
+We decided to explore another method called Clustered Shading, in its forward variant. Clustered shading expands on the idea of tiled rendering but adds a segmentation on the 3rd axis. The “clustering” is done in view space, by splitting the frustum into a 3D grid.
+</p><p>
+The frustum is first sliced on the depth axis as show in <a href="#figure_sponzaslices" target="_self">figure&nbsp;78</a>.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_sponzaslices">&nbsp;</a><a href="../images/screenshot_sponza_slices.jpg" target="_blank"><img class="markdeep" src="../images/screenshot_sponza_slices.jpg" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;78:</b> Depth slicing (16 slices)</span></center></div></center>
+</p><p>
+And the depth slices are then combined with the screen tiles to &ldquo;voxelize&rdquo; the frustum. We call each cluster a froxel as it makes it clear what they represent (a voxel in frustum space). The result of the &ldquo;froxelization&rdquo; pass is shown in <a href="#figure_froxel1" target="_self">figure&nbsp;79</a> and <a href="#figure_froxel2" target="_self">figure&nbsp;80</a>.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_froxel1">&nbsp;</a><a href="../images/screenshot_sponza_froxels1.jpg" target="_blank"><img class="markdeep" src="../images/screenshot_sponza_froxels1.jpg" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;79:</b> Frustum voxelization (5&times;3 tiles, 8 depth slices)</span></center></div></center>
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_froxel2">&nbsp;</a><a href="../images/screenshot_sponza_froxels2.jpg" target="_blank"><img class="markdeep" src="../images/screenshot_sponza_froxels2.jpg" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;80:</b> Frustum voxelization (5&times;3 tiles, 8 depth slices)</span></center></div></center>
+</p><p>
+Before rendering a frame, each light in the scene is assigned to any froxel it intersects with. The result of the lights assignment pass is a list of lights for each froxel. During the rendering pass, we can compute the ID of the froxel a fragment belongs to and therefore the list of lights that can affect that fragment.
+</p><p>
+The depth slicing is not linear, but exponential. In a typical scene, there will be more pixels close to the near plane than to the far plane. An exponential grid of froxels will therefore improve the assignment of lights where it matters the most.
+</p><p>
+<a href="#figure_froxeldistribution" target="_self">Figure&nbsp;81</a> shows how much world space unit each depth slice uses with exponential slicing.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_froxeldistribution">&nbsp;</a><a href="../images/diagram_froxels1.png" target="_blank"><img class="markdeep" src="../images/diagram_froxels1.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;81:</b> Near: 0.1m, Far: 100m, 16 slices</span></center></div></center>
+</p><p>
+A simple exponential voxelization is unfortunately not enough. The graphic above clearly illustrates how world space is distributed across slices but it fails to show what happens close to the near plane. If we examine the same distribution in a smaller range (0.1m to 7m) we can see an interesting problem appear as shown in <a href="#figure_froxeldistributionclose" target="_self">figure&nbsp;82</a>.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_froxeldistributionclose">&nbsp;</a><a href="../images/diagram_froxels2.png" target="_blank"><img class="markdeep" src="../images/diagram_froxels2.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;82:</b> Depth distribution in the 0.1-7m range</span></center></div></center>
+</p><p>
+This graphic shows that a simple exponential distribution uses up half of the slices very close to the camera. In this particular case, we use 8 slices out of 16in the first 5 meters. Since dynamic world lights are either point lights (spheres) or spot lights (cones), such a fine resolution is completely unnecessary so close to the near plane.
+</p><p>
+Our solution is to manually tweak the size of the first froxel depending on the scene and the near and far planes. By doing so, we can better distribute the remaining froxels across the frustum. <a href="#figure_froxeldistributionexp" target="_self">Figure&nbsp;83</a> shows for instance what happens when we use a special froxel between 0.1m and 5m.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_froxeldistributionexp">&nbsp;</a><a href="../images/diagram_froxels3.png" target="_blank"><img class="markdeep" src="../images/diagram_froxels3.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;83:</b> Near: 0.1, Far: 100m, 16 slices, Special froxel: 0.1-5m</span></center></div></center>
+</p><p>
+This new distribution is much more efficient and allows a better assignment of the lights throughout the entire frustum.
+</p>
+<a class="target" name="implementationnotes">&nbsp;</a><a class="target" name="imagingpipeline/lightpath/implementationnotes">&nbsp;</a><a class="target" name="toc8.4.2">&nbsp;</a><h3>Implementation notes</h3>
+<p>
+
+Lights assignment can be done in two different ways, on the GPU or on the CPU.
+</p>
+<a class="target" name="gpulightsassignment">&nbsp;</a><a class="target" name="imagingpipeline/lightpath/implementationnotes/gpulightsassignment">&nbsp;</a><a class="target" name="toc8.4.2.1">&nbsp;</a><h4>GPU lights assignment</h4>
+<p>
+
+This implementation requires OpenGL ES 3.1 and support for compute shaders. The lights are stored in Shader Storage Buffer Objects (SSBO) and passed to a compute shader that assigns each light to the corresponding froxels.
+</p><p>
+The frustum voxelization can be executed only once by a first compute shader (as long as the projection matrix does not change), and the lights assignment can be performed each frame by another compute shader.
+</p><p>
+The threading model of compute shaders is particularly well suited for this task. We simply invoke as many workgroups as we have froxels (we can directly map the X, Y and Z workgroup counts to our froxel grid resolution). Each workground will in turn be threaded and traverse all the lights to assign.
+</p><p>
+Intersection tests imply simple sphere/frustum or cone/frustum tests.
+</p><p>
+See the annex for the source code of a GPU implementation (point lights only).
+</p>
+<a class="target" name="cpulightsassignment">&nbsp;</a><a class="target" name="imagingpipeline/lightpath/implementationnotes/cpulightsassignment">&nbsp;</a><a class="target" name="toc8.4.2.2">&nbsp;</a><h4>CPU lights assignment</h4>
+<p>
+
+On non-OpenGL ES 3.1 devices, lights assignment can be performed efficiently on the CPU. The algorithm is different from the GPU implementation. Instead of iterating over every light for each froxel, the engine will “rasterize” each light as froxels. For instance, given a point light’s center and radius, it is trivial to compute the list of froxels it intersects with.
+</p><p>
+This technique has the added benefit of providing tighter culling than in the GPU variant. The CPU implementation can also more easily generate a packed list of lights.
+</p>
+<a class="target" name="shading">&nbsp;</a><a class="target" name="imagingpipeline/lightpath/implementationnotes/shading">&nbsp;</a><a class="target" name="toc8.4.2.3">&nbsp;</a><h4>Shading</h4>
+<p>
+
+The list of lights per froxel can be passed to the fragment shader either as an SSBO (OpenGL ES 3.1) or a texture.
+</p>
+<a class="target" name="fromdepthtofroxel">&nbsp;</a><a class="target" name="imagingpipeline/lightpath/implementationnotes/fromdepthtofroxel">&nbsp;</a><a class="target" name="toc8.4.2.4">&nbsp;</a><h4>From depth to froxel</h4>
+<p>
+
+Given a near plane \(n\), a far plane \(f\), a maximum number of depth slices \(m\) and a linear depth value \(z\) in the range [0..1], equation \(\ref{zToCluster}\) can be used to compute the index of the cluster for a given position.
+</p><p>
+$$\begin{equation}\label{zToCluster}
+zToCluster(z,n,f,m)=floor \left( max \left( log2(z) \frac{m}{-log2(\frac{n}{f})} + m, 0 \right) \right)
+\end{equation}$$
+</p><p>
+This formula suffers however from the resolution issue mentioned previously. We can fix it by introducing \(sn\), a special near value that defines the extent of the first froxel (the first froxel occupies the range [n..sn], the remaining froxels [sn..f]).
+</p><p>
+$$\begin{equation}\label{zToClusterFix}
+zToCluster(z,n,sn,f,m)=floor \left( max \left( log2(z) \frac{m-1}{-log2(\frac{sn}{f})} + m, 0 \right) \right)
+\end{equation}$$
+</p><p>
+Equation \(\ref{linearZ}\) can be used to compute a linear depth value from <code>gl_FragCoord.z</code> (assuming a standard OpenGL projection matrix).
+</p><p>
+$$\begin{equation}\label{linearZ}
+linearZ(z)=\frac{n}{f+z(n-f)}
+\end{equation}$$
+</p><p>
+This equation can be simplified by pre-computing two terms \(c0\) and \(c1\), as shown in equation \(\ref{linearZFix}\).
+</p><p>
+$$\begin{equation}\label{linearZFix}
+c1 = \frac{f}{n} \\
+c0 = 1 - c1 \\
+linearZ(z)=\frac{1}{z \cdot c0 + c1}
+\end{equation}$$
+</p><p>
+This simplification is important because we pass the linear z value to a <code>log2</code> in \(\ref{zToClusterFix}\). Since the division becomes a negation under a logarithmic, we can avoid a division by using \(-log2(z \cdot c0 + c1)\) instead.
+</p><p>
+All put together, computing the froxel index of a given fragment can be implemented fairly easily as shown in <a href="#listing_fragcoordtofroxel" target="_self">listing&nbsp;44</a>.
+</p><a class="target" name="listing_fragcoordtofroxel">&nbsp;</a><pre class="listing tilde"><code><span class="line"></span><span class="hljs-meta">#define MAX_LIGHT_COUNT 16 // max number of lights per froxel</span>
+<span class="line"></span>
+<span class="line"></span><span class="hljs-keyword">uniform</span> <span class="hljs-type">uvec4</span> froxels; <span class="hljs-comment">// res x, res y, count y, count y</span>
+<span class="line"></span><span class="hljs-keyword">uniform</span> <span class="hljs-type">vec4</span> zParams;  <span class="hljs-comment">// c0, c1, index scale, index bias</span>
+<span class="line"></span>
+<span class="line"></span><span class="hljs-type">uint</span> getDepthSlice() {
+<span class="line"></span>    <span class="hljs-keyword">return</span> <span class="hljs-type">uint</span>(<span class="hljs-built_in">max</span>(<span class="hljs-number">0.0</span>, <span class="hljs-built_in">log2</span>(zParams.x * <span class="hljs-built_in">gl_FragCoord</span>.z + zParams.y) *
+<span class="line"></span>            zParams.z + zParams.w));
+<span class="line"></span>}
+<span class="line"></span>
+<span class="line"></span><span class="hljs-type">uint</span> getFroxelOffset(<span class="hljs-type">uint</span> depthSlice) {
+<span class="line"></span>    <span class="hljs-type">uvec2</span> froxelCoord = <span class="hljs-type">uvec2</span>(<span class="hljs-built_in">gl_FragCoord</span>.xy) / froxels.xy;
+<span class="line"></span>    froxelCoord.y = (froxels.w - <span class="hljs-number">1</span>u) - froxelCoord.y;
+<span class="line"></span>
+<span class="line"></span>    <span class="hljs-type">uint</span> <span class="hljs-keyword">index</span> = froxelCoord.x + froxelCoord.y * froxels.z +
+<span class="line"></span>            depthSlice * froxels.z * froxels.w;
+<span class="line"></span>    <span class="hljs-keyword">return</span> <span class="hljs-keyword">index</span> * MAX_FROXEL_LIGHT_COUNT;
+<span class="line"></span>}
+<span class="line"></span>
+<span class="line"></span><span class="hljs-type">uint</span> slice = getDepthSlice();
+<span class="line"></span><span class="hljs-type">uint</span> <span class="hljs-keyword">offset</span> = getFroxelOffset(slice);
+<span class="line"></span>
+<span class="line"></span><span class="hljs-comment">// Compute lighting...</span></code></pre><center><div class="listingcaption tilde"><b style="font-style:normal;">Listing&nbsp;44:</b> GLSL implementation to compute a froxel index from a fragment's screen coordinates</div></center>
+<p>
+
+Several uniforms must be pre-computed for perform the index evaluation efficiently. The code used to pre-compute these uniforms can be found in listing ?.
+</p><pre class="listing tilde"><code><span class="line"></span>froxels[<span class="hljs-number">0</span>] = TILE_RESOLUTION_IN_PX;
+<span class="line"></span>froxels[<span class="hljs-number">1</span>] = TILE_RESOLUTION_IN_PX;
+<span class="line"></span>froxels[<span class="hljs-number">2</span>] = numberOfTilesInX;
+<span class="line"></span>froxels[<span class="hljs-number">3</span>] = numberOfTilesInY;
+<span class="line"></span>
+<span class="line"></span>zParams[<span class="hljs-number">0</span>] = <span class="hljs-number">1.0</span>f - Z_FAR / Z_NEAR;
+<span class="line"></span>zParams[<span class="hljs-number">1</span>] = Z_FAR / Z_NEAR;
+<span class="line"></span>zParams[<span class="hljs-number">2</span>] = (MAX_DEPTH_SLICES - <span class="hljs-number">1</span>) / <span class="hljs-built_in">log2</span>(Z_SPECIAL_NEAR / Z_FAR);
+<span class="line"></span>zParams[<span class="hljs-number">3</span>] = MAX_DEPTH_SLICES;</code></pre><center><div class="listingcaption tilde">[Listing ?]</div></center>
+<a class="target" name="fromfroxeltodepth">&nbsp;</a><a class="target" name="imagingpipeline/lightpath/implementationnotes/fromfroxeltodepth">&nbsp;</a><a class="target" name="toc8.4.2.5">&nbsp;</a><h4>From froxel to depth</h4>
+<p>
+
+Given a froxel index \(i\), a special near plane \(sn\), a far plane \(f\) and a maximum number of depth slices \(m\), equation \(\ref{clusterToZ}\) computes the minimum depth of a given froxel.
+</p><p>
+$$\begin{equation}\label{clusterToZ}
+clusterToZ(i \ge 1,sn,f,m)=2^{(i-m) \frac{-log2(\frac{sn}{f})}{m-1}}
+\end{equation}$$
+</p><p>
+For \(i=0\), the z value is 0. The result of this equation is in the [0..1] range and should be multiplied by \(f\) to get a distance in world units.
+</p><p>
+The compute shader implementation should use <code>exp2</code> instead of a <code>pow</code>. The division can be precomputed and passed as a uniform.
+</p>
+<a class="target" name="validation">&nbsp;</a><a class="target" name="imagingpipeline/validation">&nbsp;</a><a class="target" name="toc8.5">&nbsp;</a><h2>Validation</h2>
+<p>
+
+Given the complexity of our lighting system, it is important to validate our implementation. We will do so in several ways: using reference renderings, light measurements and data visualization.
+</p><p>
+[TODO] Explain light measurement validation (reading EV from the render target and comparing against values measure with light meters/cameras, etc.)
+</p>
+<a class="target" name="scenereferredvisualization">&nbsp;</a><a class="target" name="imagingpipeline/validation/scenereferredvisualization">&nbsp;</a><a class="target" name="toc8.5.1">&nbsp;</a><h3>Scene referred visualization</h3>
+<p>
+
+A quick and easy way to validate a scene's lighting is to modify the shader to output colors that provide an intuitive mapping to relevant data. This can easily be done by using a custom debug tone-mapping operator that outputs fake colors.
+</p>
+<a class="target" name="luminancestops">&nbsp;</a><a class="target" name="imagingpipeline/validation/scenereferredvisualization/luminancestops">&nbsp;</a><a class="target" name="toc8.5.1.1">&nbsp;</a><h4>Luminance stops</h4>
+<p>
+
+With emissive materials and IBLs, it is fairly easy to obtain a scene in which specular highlights are brighter than their apparent caster. This type of issue can be difficult to observe after tone-mapping and quantization but is fairly obvious in the scene-referred space. <a href="#figure_luminanceviz" target="_self">Figure&nbsp;84</a> shows how the custom operator described in <a href="#listing_tonemapluminanceviz" target="_self">listing&nbsp;45</a> is used to show the exposed luminance of a scene.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_luminanceviz">&nbsp;</a><a href="../images/screenshot_luminance_debug.png" target="_blank"><img class="markdeep" src="../images/screenshot_luminance_debug.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;84:</b> Visualizing luminance by color coding the stops: cyan is middle gray, blue is 1 stop darker, green 1 stop brighter, etc.</span></center></div></center>
+</p><a class="target" name="listing_tonemapluminanceviz">&nbsp;</a><pre class="listing tilde"><code><span class="line"></span><span class="hljs-type">vec3</span> Tonemap_DisplayRange(<span class="hljs-keyword">const</span> <span class="hljs-type">vec3</span> x) {
+<span class="line"></span>    <span class="hljs-comment">// The 5th color in the array (cyan) represents middle gray (18%)</span>
+<span class="line"></span>    <span class="hljs-comment">// Every stop above or below middle gray causes a color shift</span>
+<span class="line"></span>    <span class="hljs-type">float</span> v = <span class="hljs-built_in">log2</span>(luminance(x) / <span class="hljs-number">0.18</span>);
+<span class="line"></span>    v = <span class="hljs-built_in">clamp</span>(v + <span class="hljs-number">5.0</span>, <span class="hljs-number">0.0</span>, <span class="hljs-number">15.0</span>);
+<span class="line"></span>    <span class="hljs-type">int</span> <span class="hljs-keyword">index</span> = <span class="hljs-type">int</span>(<span class="hljs-built_in">floor</span>(v));
+<span class="line"></span>    <span class="hljs-keyword">return</span> <span class="hljs-built_in">mix</span>(debugColors[<span class="hljs-keyword">index</span>], debugColors[<span class="hljs-built_in">min</span>(<span class="hljs-number">15</span>, <span class="hljs-keyword">index</span> + <span class="hljs-number">1</span>)], <span class="hljs-built_in">fract</span>(v));
+<span class="line"></span>}
+<span class="line"></span>
+<span class="line"></span><span class="hljs-keyword">const</span> <span class="hljs-type">vec3</span> debugColors[<span class="hljs-number">16</span>] = <span class="hljs-type">vec3</span>[](
+<span class="line"></span>     <span class="hljs-type">vec3</span>(<span class="hljs-number">0.0</span>, <span class="hljs-number">0.0</span>, <span class="hljs-number">0.0</span>),         <span class="hljs-comment">// black</span>
+<span class="line"></span>     <span class="hljs-type">vec3</span>(<span class="hljs-number">0.0</span>, <span class="hljs-number">0.0</span>, <span class="hljs-number">0.1647</span>),      <span class="hljs-comment">// darkest blue</span>
+<span class="line"></span>     <span class="hljs-type">vec3</span>(<span class="hljs-number">0.0</span>, <span class="hljs-number">0.0</span>, <span class="hljs-number">0.3647</span>),      <span class="hljs-comment">// darker blue</span>
+<span class="line"></span>     <span class="hljs-type">vec3</span>(<span class="hljs-number">0.0</span>, <span class="hljs-number">0.0</span>, <span class="hljs-number">0.6647</span>),      <span class="hljs-comment">// dark blue</span>
+<span class="line"></span>     <span class="hljs-type">vec3</span>(<span class="hljs-number">0.0</span>, <span class="hljs-number">0.0</span>, <span class="hljs-number">0.9647</span>),      <span class="hljs-comment">// blue</span>
+<span class="line"></span>     <span class="hljs-type">vec3</span>(<span class="hljs-number">0.0</span>, <span class="hljs-number">0.9255</span>, <span class="hljs-number">0.9255</span>),   <span class="hljs-comment">// cyan</span>
+<span class="line"></span>     <span class="hljs-type">vec3</span>(<span class="hljs-number">0.0</span>, <span class="hljs-number">0.5647</span>, <span class="hljs-number">0.0</span>),      <span class="hljs-comment">// dark green</span>
+<span class="line"></span>     <span class="hljs-type">vec3</span>(<span class="hljs-number">0.0</span>, <span class="hljs-number">0.7843</span>, <span class="hljs-number">0.0</span>),      <span class="hljs-comment">// green</span>
+<span class="line"></span>     <span class="hljs-type">vec3</span>(<span class="hljs-number">1.0</span>, <span class="hljs-number">1.0</span>, <span class="hljs-number">0.0</span>),         <span class="hljs-comment">// yellow</span>
+<span class="line"></span>     <span class="hljs-type">vec3</span>(<span class="hljs-number">0.90588</span>, <span class="hljs-number">0.75294</span>, <span class="hljs-number">0.0</span>), <span class="hljs-comment">// yellow-orange</span>
+<span class="line"></span>     <span class="hljs-type">vec3</span>(<span class="hljs-number">1.0</span>, <span class="hljs-number">0.5647</span>, <span class="hljs-number">0.0</span>),      <span class="hljs-comment">// orange</span>
+<span class="line"></span>     <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="hljs-comment">// bright red</span>
+<span class="line"></span>     <span class="hljs-type">vec3</span>(<span class="hljs-number">0.8392</span>, <span class="hljs-number">0.0</span>, <span class="hljs-number">0.0</span>),      <span class="hljs-comment">// red</span>
+<span class="line"></span>     <span class="hljs-type">vec3</span>(<span class="hljs-number">1.0</span>, <span class="hljs-number">0.0</span>, <span class="hljs-number">1.0</span>),         <span class="hljs-comment">// magenta</span>
+<span class="line"></span>     <span class="hljs-type">vec3</span>(<span class="hljs-number">0.6</span>, <span class="hljs-number">0.3333</span>, <span class="hljs-number">0.7882</span>),   <span class="hljs-comment">// purple</span>
+<span class="line"></span>     <span class="hljs-type">vec3</span>(<span class="hljs-number">1.0</span>, <span class="hljs-number">1.0</span>, <span class="hljs-number">1.0</span>)          <span class="hljs-comment">// white</span>
+<span class="line"></span>);</code></pre><center><div class="listingcaption tilde"><b style="font-style:normal;">Listing&nbsp;45:</b> GLSL implementation of a custom debug tone-mapping operator for luminance visualization</div></center>
+<a class="target" name="referencerenderings">&nbsp;</a><a class="target" name="imagingpipeline/validation/referencerenderings">&nbsp;</a><a class="target" name="toc8.5.2">&nbsp;</a><h3>Reference renderings</h3>
+<p>
+
+To validate our implementation against reference renderings, we will use a commercial-grade Open Source physically based offline path tracer called Mitsuba. Mitsuba offers many different integrators, samplers and material models, which should allow us to provide fair comparisons with our real-time renderer. This path tracer also relies on a simple XML scene description format that should be easy to automatically generate from our own scene descriptions.
+</p><p>
+<a href="#figure_mitsubareference" target="_self">Figure&nbsp;85</a> and <a href="#figure_filamentreference" target="_self">figure&nbsp;86</a> show a simple scene, a perfectly smooth dielectric sphere, rendered respectively with Mitsuba and Filament.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_mitsubareference">&nbsp;</a><a href="../images/screenshot_ref_mitsuba.jpg" target="_blank"><img class="markdeep" src="../images/screenshot_ref_mitsuba.jpg" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;85:</b> Rendered in 2048&times;1440 in 1 minute and 42 seconds on a 12 core 2013 MacPro</span></center></div></center>
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_filamentreference">&nbsp;</a><a href="../images/screenshot_ref_filament.jpg" target="_blank"><img class="markdeep" src="../images/screenshot_ref_filament.jpg" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;86:</b> Rendered in 2048&times;1440 with MSAA 4x at 60 fps on a Nexus 9 device (Tegra K1 GPU)</span></center></div></center>
+</p><p>
+The parameters used to render both scenes are the following:
+</p><p>
+<strong class="asterisk">Filament</strong>
+</p><p>
+<ul>
+<li class="minus">Material
+<ul>
+  <li class="minus">Base color: sRGB 0.81, 0, 0
+</li>
+  <li class="minus">Metallic: 0
+</li>
+  <li class="minus">Roughness: 0
+</li>
+  <li class="minus">Reflectance: 0.5
+</li></ul>
+<li class="minus">Indirect light: IBL
+<ul>
+  <li class="minus">256&times;256 cubemap generated by cmgen from office.exr
+</li>
+  <li class="minus">Multiplier: 35,000
+</li></ul>
+<li class="minus">Direct light: directional light
+<ul>
+  <li class="minus">Linear color: 1.0, 0.96, 0.95
+</li>
+  <li class="minus">Intensity: 120,000 lux
+</li></ul>
+<li class="minus">Exposure
+<ul>
+  <li class="minus">Aperture: f/16
+</li>
+  <li class="minus">Shutter speed: 1/125s
+</li>
+  <li class="minus">ISO: 100</li></ul></li></ul>
+</p><p>
+<strong class="asterisk">Mitsuba</strong>
+</p><p>
+<ul>
+<li class="minus">BSDF: roughplastic
+<ul>
+  <li class="minus">Distribution: GGX
+</li>
+  <li class="minus">Alpha: 0
+</li>
+  <li class="minus">Diffuse reflectance: sRGB 0.81, 0, 0
+</li></ul>
+<li class="minus">Emitter: environment map
+<ul>
+  <li class="minus">Source: office.exr
+</li>
+  <li class="minus">Scale: 35,000
+</li></ul>
+<li class="minus">Emitter: directional
+<ul>
+  <li class="minus">Irradiance: linear RGB 120,000 115,200 114,000
+</li></ul>
+<li class="minus">Film: LDR
+<ul>
+  <li class="minus">Exposure: &minus;15.23, computed from log2(filamentExposure)
+</li></ul>
+<li class="minus">Integrator: path
+</li>
+<li class="minus">Sampler: ldsampler
+<ul>
+  <li class="minus">Sample count: 256</li></ul></li></ul>
+</p><p>
+The full Mitsuba scene can be found as an annex. Both scenes were rendered at the same resolution (2048&times;1440).
+</p>
+<a class="target" name="comparison">&nbsp;</a><a class="target" name="imagingpipeline/validation/referencerenderings/comparison">&nbsp;</a><a class="target" name="toc8.5.2.1">&nbsp;</a><h4>Comparison</h4>
+<p>
+
+The slight differences between the two renderings come from the various approximations used by Filament: RGBM 256&times;256 reflection probe, RGBM 1024&times;1024 background map, Lambert diffuse, split-sum approximation, analytical approximation of the DFG term, etc.
+</p><p>
+<a href="#figure_referencecomparison" target="_self">Figure&nbsp;87</a> shows the luminance gradient of the images produced by both engines. The comparison was performed on LDR images.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_referencecomparison">&nbsp;</a><a href="../images/screenshot_ref_comparison.png" target="_blank"><img class="markdeep" src="../images/screenshot_ref_comparison.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;87:</b> Luminance gradients from Mitsuba (left) and Filament (right)</span></center></div></center>
+</p><p>
+The biggest difference is visible at grazing angles, which is most likely explained by Filament's use of a Lambertian diffuse term. The Disney diffuse term and its grazing retro-reflections would move Filament closer to Mitsuba.
+</p>
+<a class="target" name="coordinatessystems">&nbsp;</a><a class="target" name="imagingpipeline/coordinatessystems">&nbsp;</a><a class="target" name="toc8.6">&nbsp;</a><h2>Coordinates systems</h2>
+<a class="target" name="worldcoordinatessystem">&nbsp;</a><a class="target" name="imagingpipeline/coordinatessystems/worldcoordinatessystem">&nbsp;</a><a class="target" name="toc8.6.1">&nbsp;</a><h3>World coordinates system</h3>
+<p>
+
+Filament uses a Y-up, right-handed coordinate system.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_coordinates">&nbsp;</a><a href="../images/screenshot_coordinates.jpg" target="_blank"><img class="markdeep" src="../images/screenshot_coordinates.jpg" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;88:</b> Red +X, green +Y, blue +Z (rendered in Marmoset Toolbag).</span></center></div></center>
+</p>
+<a class="target" name="cameracoordinatessystem">&nbsp;</a><a class="target" name="imagingpipeline/coordinatessystems/cameracoordinatessystem">&nbsp;</a><a class="target" name="toc8.6.2">&nbsp;</a><h3>Camera coordinates system</h3>
+<p>
+
+Filament's Camera looks towards its local -Z axis. That is, when placing a camera in the world
+without any transform applied to it, the camera looks down the world's -Z axis.
+</p>
+<a class="target" name="cubemapscoordinatessystem">&nbsp;</a><a class="target" name="imagingpipeline/coordinatessystems/cubemapscoordinatessystem">&nbsp;</a><a class="target" name="toc8.6.3">&nbsp;</a><h3>Cubemaps coordinates system</h3>
+<p>
+
+All cubemaps used in Filament follow the OpenGL convention for face
+alignment shown in <a href="#figure_cubemapcoordinates" target="_self">figure&nbsp;89</a>.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_cubemapcoordinates">&nbsp;</a><a href="../images/screenshot_cubemap_coordinates.png" target="_blank"><img class="markdeep" src="../images/screenshot_cubemap_coordinates.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;89:</b> Horizontal cross representation of a cubemap following the OpenGL faces alignment convention.</span></center></div></center>
+</p><p>
+Note that environment background and reflection probes are mirrored (see section <a href="#toc8.6.3.1" target="_self">8.6.3.1</a>).
+</p>
+<a class="target" name="mirroring">&nbsp;</a><a class="target" name="imagingpipeline/coordinatessystems/cubemapscoordinatessystem/mirroring">&nbsp;</a><a class="target" name="toc8.6.3.1">&nbsp;</a><h4>Mirroring</h4>
+<p>
+
+To simplify the rendering of reflections, IBL cubemaps are stored mirrored on the X axis. This is
+the default behaviour of the <code>cmgen</code> tool. This means that an IBL cubemap used as environment 
+background needs to be mirrored again at runtime. 
+An easy way to achieve this for skyboxes is to use textured back faces. Filament does
+this by default.
+</p>
+<a class="target" name="equirectangularenvironmentmaps">&nbsp;</a><a class="target" name="imagingpipeline/coordinatessystems/cubemapscoordinatessystem/equirectangularenvironmentmaps">&nbsp;</a><a class="target" name="toc8.6.3.2">&nbsp;</a><h4>Equirectangular environment maps</h4>
+<p>
+
+To convert equirectangular environment maps to horizontal/vertical cross cubemaps we position the
++Z face in the center of the source rectilinear environment map.
+</p>
+<a class="target" name="worldspaceorientationofenvironmentmapsandskyboxes">&nbsp;</a><a class="target" name="imagingpipeline/coordinatessystems/cubemapscoordinatessystem/worldspaceorientationofenvironmentmapsandskyboxes">&nbsp;</a><a class="target" name="toc8.6.3.3">&nbsp;</a><h4>World space orientation of environment maps and Skyboxes</h4>
+<p>
+
+When specifying a skybox or an IBL in Filament, the specified cubemap is oriented such that its 
+-Z face points towards the +Z axis of the world (this is because filament assumes mirrored cubemaps, 
+see section <a href="#toc8.6.3.1" target="_self">8.6.3.1</a>). However, because environments and skyboxes are expected to be pre-mirrored, 
+their -Z (back) face points towards the world's -Z axis as expected (and the camera looks toward that 
+direction by default, see section <a href="#toc8.6.2" target="_self">8.6.2</a>).
+</p>
+<a class="target" name="annex">&nbsp;</a><a class="target" name="annex">&nbsp;</a><a class="target" name="toc9">&nbsp;</a><h1>Annex</h1>
+<a class="target" name="specularcolor">&nbsp;</a><a class="target" name="annex/specularcolor">&nbsp;</a><a class="target" name="toc9.1">&nbsp;</a><h2>Specular color</h2>
+<p>
+
+The specular color of a metallic surface, or \(\fNormal\), can be computed directly from measured spectral data. Online databases such as <a href="https://refractiveindex.info/?shelf=3d&book=metals&page=brass">Refractive Index</a> provide tables of complex IOR measured at different wavelengths for various materials.
+</p><p>
+Earlier in this document, we presented equation \(\ref{fresnelEquation}\) to compute the Fresnel reflectance at normal incidence for a dielectric surface given its IOR. The same equation can be rewritten for conductors by using complex numbers to represent the surface's IOR:
+</p><p>
+$$\begin{equation}
+c_{ior} = n_{ior} + ik
+\end{equation}$$
+</p><p>
+Equation \(\ref{fresnelComplexIOR}\) presents the resulting Fresnel formula, where \(c^*\) is the conjugate of the complex number \(c\):
+</p><p>
+$$\begin{equation}\label{fresnelComplexIOR}
+\fNormal(c_{ior}) = \frac{(c_{ior} - 1)(c_{ior}^* - 1)}{(c_{ior} + 1)(c_{ior}^* + 1)}
+\end{equation}$$
+</p><p>
+To compute the specular color of a material we need to evaluate the complex Fresnel equation at each spectral sample of complex IOR over the visible spectrum. For each spectral sample, we obtain a spectral reflectance sample. To find the RGB color at normal incidence, we must multiply each sample by the CIE XYZ CMFs (color matching functions) and the spectral power distribution of the desired illuminant. We choose the standard illuminant D65 because we want to compute a color in the sRGB color space.
+</p><p>
+We then sum (integrate) and normalize all the samples to obtain \(\fNormal\) in the XYZ color space. From there, a simple color space conversion yields a linear sRGB color or a non-linear sRGB color after applying the opto-electronic transfer function (OETF, commonly known as &ldquo;gamma&rdquo; curve). Note that for some materials such as gold the final sRGB color might fall out of gamut. We use a simple normalization step as a cheap form of gamut remapping but it would be interesting to consider computing values in a color space with a wider gamut (for instance BT.2020).
+</p><p>
+To achieve the desired result we used the ICE 1931 2&deg; CMFs, from 360nm to 830nm at 1nm intervals (<a href="http://cvrl.ioo.ucl.ac.uk/cmfs.htm">source</a>), and the CIE Standard Illuminant D65 relative spectral power distribution, from 300nm to 830nm, at 5nm intervals (<a href="http://files.cie.co.at/204.xls">source</a>).
+</p><p>
+Our implementation is presented in <a href="#listing_specularcolorimpl" target="_self">listing&nbsp;46</a>, with the actual data omitted for brevity.
+</p><a class="target" name="listing_specularcolorimpl">&nbsp;</a><pre class="listing tilde"><code><span class="line"></span><span class="hljs-comment">// CIE 1931 2-deg color matching functions (CMFs), from 360nm to 830nm,</span>
+<span class="line"></span><span class="hljs-comment">// at 1nm intervals</span>
+<span class="line"></span><span class="hljs-comment">//</span>
+<span class="line"></span><span class="hljs-comment">// Data source:</span>
+<span class="line"></span><span class="hljs-comment">//     http://cvrl.ioo.ucl.ac.uk/cmfs.htm</span>
+<span class="line"></span><span class="hljs-comment">//     http://cvrl.ioo.ucl.ac.uk/database/text/cmfs/ciexyz31.htm</span>
+<span class="line"></span><span class="hljs-type">const</span> <span class="hljs-type">size_t</span> CIE_XYZ_START = <span class="hljs-number">360</span>;
+<span class="line"></span><span class="hljs-type">const</span> <span class="hljs-type">size_t</span> CIE_XYZ_COUNT = <span class="hljs-number">471</span>;
+<span class="line"></span><span class="hljs-type">const</span> float3 CIE_XYZ[CIE_XYZ_COUNT] = { ... };
+<span class="line"></span>
+<span class="line"></span><span class="hljs-comment">// CIE Standard Illuminant D65 relative spectral power distribution,</span>
+<span class="line"></span><span class="hljs-comment">// from 300nm to 830, at 5nm intervals</span>
+<span class="line"></span><span class="hljs-comment">//</span>
+<span class="line"></span><span class="hljs-comment">// Data source:</span>
+<span class="line"></span><span class="hljs-comment">//     https://en.wikipedia.org/wiki/Illuminant_D65</span>
+<span class="line"></span><span class="hljs-comment">//     https://cielab.xyz/pdf/CIE_sel_colorimetric_tables.xls</span>
+<span class="line"></span><span class="hljs-type">const</span> <span class="hljs-type">size_t</span> CIE_D65_INTERVAL = <span class="hljs-number">5</span>;
+<span class="line"></span><span class="hljs-type">const</span> <span class="hljs-type">size_t</span> CIE_D65_START = <span class="hljs-number">300</span>;
+<span class="line"></span><span class="hljs-type">const</span> <span class="hljs-type">size_t</span> CIE_D65_END = <span class="hljs-number">830</span>;
+<span class="line"></span><span class="hljs-type">const</span> <span class="hljs-type">size_t</span> CIE_D65_COUNT = <span class="hljs-number">107</span>;
+<span class="line"></span><span class="hljs-type">const</span> <span class="hljs-type">float</span> CIE_D65[CIE_D65_COUNT] = { ... };
+<span class="line"></span>
+<span class="line"></span><span class="hljs-keyword">struct</span> <span class="hljs-title class_">Sample</span> {
+<span class="line"></span>    <span class="hljs-type">float</span> w = <span class="hljs-number">0.0f</span>; <span class="hljs-comment">// wavelength</span>
+<span class="line"></span>    std::complex&lt;<span class="hljs-type">float</span>&gt; ior; <span class="hljs-comment">// complex IOR, n + ik</span>
+<span class="line"></span>};
+<span class="line"></span>
+<span class="line"></span><span class="hljs-function"><span class="hljs-type">static</span> <span class="hljs-type">float</span> <span class="hljs-title">illuminantD65</span><span class="hljs-params">(<span class="hljs-type">float</span> w)</span> </span>{
+<span class="line"></span>    <span class="hljs-keyword">auto</span> i0 = <span class="hljs-built_in">size_t</span>((w - CIE_D65_START) / CIE_D65_INTERVAL);
+<span class="line"></span>    uint2 indexBounds{i0, std::<span class="hljs-built_in">min</span>(i0 + <span class="hljs-number">1</span>, CIE_D65_END)};
+<span class="line"></span>
+<span class="line"></span>    float2 wavelengthBounds = CIE_D65_START + float2{indexBounds} * CIE_D65_INTERVAL;
+<span class="line"></span>    <span class="hljs-type">float</span> t = (w - wavelengthBounds.x) / (wavelengthBounds.y - wavelengthBounds.x);
+<span class="line"></span>    <span class="hljs-keyword">return</span> <span class="hljs-built_in">lerp</span>(CIE_D65[indexBounds.x], CIE_D65[indexBounds.y], t);
+<span class="line"></span>}
+<span class="line"></span>
+<span class="line"></span><span class="hljs-comment">// For std::lower_bound</span>
+<span class="line"></span><span class="hljs-type">bool</span> <span class="hljs-keyword">operator</span>&lt;(<span class="hljs-type">const</span> Sample&amp; lhs, <span class="hljs-type">const</span> Sample&amp; rhs) {
+<span class="line"></span>    <span class="hljs-keyword">return</span> lhs.w &lt; rhs.w;
+<span class="line"></span>}
+<span class="line"></span>
+<span class="line"></span><span class="hljs-comment">// The wavelength w must be between 360nm and 830nm</span>
+<span class="line"></span><span class="hljs-function"><span class="hljs-type">static</span> std::complex&lt;<span class="hljs-type">float</span>&gt; <span class="hljs-title">findSample</span><span class="hljs-params">(<span class="hljs-type">const</span> std::vector&lt;sample&gt;&amp; samples, <span class="hljs-type">float</span> w)</span> </span>{
+<span class="line"></span>    <span class="hljs-keyword">auto</span> i1 = std::<span class="hljs-built_in">lower_bound</span>(
+<span class="line"></span>         samples.<span class="hljs-built_in">begin</span>(), samples.<span class="hljs-built_in">end</span>(), Sample{w, <span class="hljs-number">0.0f</span> + <span class="hljs-number">0.0</span><span class="hljs-keyword">if</span>});
+<span class="line"></span>    <span class="hljs-keyword">auto</span> i0 = i1 - <span class="hljs-number">1</span>;
+<span class="line"></span>
+<span class="line"></span>    <span class="hljs-comment">// Interpolate the complex IORs</span>
+<span class="line"></span>    <span class="hljs-type">float</span> t = (w - i0-&gt;w) / (i1-&gt;w - i0-&gt;w);
+<span class="line"></span>    <span class="hljs-type">float</span> n = <span class="hljs-built_in">lerp</span>(i0-&gt;ior.<span class="hljs-built_in">real</span>(), i1-&gt;ior.<span class="hljs-built_in">real</span>(), t);
+<span class="line"></span>    <span class="hljs-type">float</span> k = <span class="hljs-built_in">lerp</span>(i0-&gt;ior.<span class="hljs-built_in">imag</span>(), i1-&gt;ior.<span class="hljs-built_in">imag</span>(), t);
+<span class="line"></span>    <span class="hljs-keyword">return</span> { n, k };
+<span class="line"></span>}
+<span class="line"></span>
+<span class="line"></span><span class="hljs-function"><span class="hljs-type">static</span> <span class="hljs-type">float</span> <span class="hljs-title">fresnel</span><span class="hljs-params">(<span class="hljs-type">const</span> std::complex&lt;<span class="hljs-type">float</span>&gt;&amp; sample)</span> </span>{
+<span class="line"></span>    <span class="hljs-keyword">return</span> (((sample - (<span class="hljs-number">1.0f</span> + <span class="hljs-number">0</span><span class="hljs-keyword">if</span>)) * (std::<span class="hljs-built_in">conj</span>(sample) - (<span class="hljs-number">1.0f</span> + <span class="hljs-number">0</span><span class="hljs-keyword">if</span>))) /
+<span class="line"></span>            ((sample + (<span class="hljs-number">1.0f</span> + <span class="hljs-number">0</span><span class="hljs-keyword">if</span>)) * (std::<span class="hljs-built_in">conj</span>(sample) + (<span class="hljs-number">1.0f</span> + <span class="hljs-number">0</span><span class="hljs-keyword">if</span>)))).<span class="hljs-built_in">real</span>();
+<span class="line"></span>}
+<span class="line"></span>
+<span class="line"></span><span class="hljs-function"><span class="hljs-type">static</span> float3 <span class="hljs-title">XYZ_to_sRGB</span><span class="hljs-params">(<span class="hljs-type">const</span> float3&amp; v)</span> </span>{
+<span class="line"></span>    <span class="hljs-type">const</span> mat3f XYZ_sRGB{
+<span class="line"></span>             <span class="hljs-number">3.2404542f</span>, <span class="hljs-number">-0.9692660f</span>,  <span class="hljs-number">0.0556434f</span>,
+<span class="line"></span>            <span class="hljs-number">-1.5371385f</span>,  <span class="hljs-number">1.8760108f</span>, <span class="hljs-number">-0.2040259f</span>,
+<span class="line"></span>            <span class="hljs-number">-0.4985314f</span>,  <span class="hljs-number">0.0415560f</span>,  <span class="hljs-number">1.0572252f</span>
+<span class="line"></span>    };
+<span class="line"></span>    <span class="hljs-keyword">return</span> XYZ_sRGB * v;
+<span class="line"></span>}
+<span class="line"></span>
+<span class="line"></span><span class="hljs-comment">// Outputs a linear sRGB color</span>
+<span class="line"></span><span class="hljs-function"><span class="hljs-type">static</span> float3 <span class="hljs-title">computeColor</span><span class="hljs-params">(<span class="hljs-type">const</span> std::vector&lt;sample&gt;&amp; samples)</span> </span>{
+<span class="line"></span>    float3 xyz{<span class="hljs-number">0.0f</span>};
+<span class="line"></span>    <span class="hljs-type">float</span> y = <span class="hljs-number">0.0f</span>;
+<span class="line"></span>
+<span class="line"></span>    <span class="hljs-keyword">for</span> (<span class="hljs-type">size_t</span> i = <span class="hljs-number">0</span>; i &lt; CIE_XYZ_COUNT; i++) {
+<span class="line"></span>        <span class="hljs-comment">// Current wavelength</span>
+<span class="line"></span>        <span class="hljs-type">float</span> w = CIE_XYZ_START + i;
+<span class="line"></span>
+<span class="line"></span>        <span class="hljs-comment">// Find most appropriate CIE XYZ sample for the wavelength</span>
+<span class="line"></span>        <span class="hljs-keyword">auto</span> sample = <span class="hljs-built_in">findSample</span>(samples, w);
+<span class="line"></span>        <span class="hljs-comment">// Compute Fresnel reflectance at normal incidence</span>
+<span class="line"></span>        <span class="hljs-type">float</span> f0 = <span class="hljs-built_in">fresnel</span>(sample);
+<span class="line"></span>
+<span class="line"></span>        <span class="hljs-comment">// We need to multiply by the spectral power distribution of the illuminant</span>
+<span class="line"></span>        <span class="hljs-type">float</span> d65 = <span class="hljs-built_in">illuminantD65</span>(w);
+<span class="line"></span>
+<span class="line"></span>        xyz += f0 * CIE_XYZ[i] * d65;
+<span class="line"></span>        y += CIE_XYZ[i].y * d65;
+<span class="line"></span>    }
+<span class="line"></span>
+<span class="line"></span>    <span class="hljs-comment">// Normalize so that 100% reflectance at every wavelength yields Y=1</span>
+<span class="line"></span>    xyz /= y;
+<span class="line"></span>
+<span class="line"></span>    float3 linear = <span class="hljs-built_in">XYZ_to_sRGB</span>(xyz);
+<span class="line"></span>
+<span class="line"></span>    <span class="hljs-comment">// Normalize out-of-gamut values</span>
+<span class="line"></span>    <span class="hljs-keyword">if</span> (<span class="hljs-built_in">any</span>(<span class="hljs-built_in">greaterThan</span>(linear, float3{<span class="hljs-number">1.0f</span>}))) linear *= <span class="hljs-number">1.0f</span> / <span class="hljs-built_in">max</span>(linear);
+<span class="line"></span>
+<span class="line"></span>    <span class="hljs-keyword">return</span> linear;
+<span class="line"></span>}</code></pre><center><div class="listingcaption tilde"><b style="font-style:normal;">Listing&nbsp;46:</b> C++ implementation to compute the base color of a metallic surface from spectral data</div></center>
+<p>
+
+Special thanks to Naty Hoffman for his valuable help on this topic.
+</p>
+<a class="target" name="importancesamplingfortheibl">&nbsp;</a><a class="target" name="annex/importancesamplingfortheibl">&nbsp;</a><a class="target" name="toc9.2">&nbsp;</a><h2>Importance sampling for the IBL</h2>
+<p>
+
+In the discrete domain, the integral can be approximated with sampling as defined in equation \(\ref{iblSampling}\).
+</p><p>
+$$\begin{equation}\label{iblSampling}
+\Lout(n,v,\Theta) \equiv \frac{1}{N} \sum_{i}^{N} f(l_{i}^{uniform},v,\Theta) L_{\perp}(l_i) \left< n \cdot l_i^{uniform} \right>
+\end{equation}$$
+</p><p>
+Unfortunately, we would need too many samples to evaluate this integral. A technique commonly used
+is to choose samples that are more &ldquo;important&rdquo; more often, this is called <em class="underscore">importance sampling</em>.
+In our case we'll use the distribution of micro-facets normals, \(D_{ggx}\), as the distribution of
+important samples.
+</p><p>
+The evaluation of \( \Lout(n,v,\Theta) \) with importance sampling is presented in equation \(\ref{annexIblImportanceSampling}\).
+</p><p>
+$$\begin{equation}\label{annexIblImportanceSampling}
+\Lout(n,v,\Theta) \equiv \frac{1}{N} \sum_{i}^{N} \frac{f(l_{i},v,\Theta)}{p(l_i,v,\Theta)} L_{\perp}(l_i) \left< n \cdot l_i \right>
+\end{equation}$$
+</p><p>
+In equation \(\ref{annexIblImportanceSampling}\), \(p\) is the probability density function (PDF) of the
+distribution of <em class="underscore">important direction samples</em> \(l_i\). These samples depend on \(h_i\), \(v\) and \(\alpha\).
+The definition of the PDF is shown in equation \(\ref{iblPDF}\).
+</p><p>
+\(h_i\) is given by the distribution we chose, see section <a href="#toc9.2.1" target="_self">9.2.1</a> for more details.
+</p><p>
+The <em class="underscore">important direction samples</em> \(l_i\) are calculated as the reflection of \(v\) around \(h_i\), and therefore
+<strong class="asterisk">do not</strong> have the same PDF as \(h_i\). The PDF of a transformed distribution is given by:
+</p><p>
+$$\begin{equation}
+p(T_r(x)) = p(x) |J(T_r)|^{-1}
+\end{equation}$$
+</p><p>
+Where \(|J(T_r)|\) is the determinant of the Jacobian of the transform. In our case we're considering
+the transform from \(h_i\) to \(l_i\) and the determinant of its Jacobian is given in \ref{iblPDF}.
+</p><p>
+$$\begin{equation}\label{iblPDF}
+p(l,v,\Theta) = D(h,\alpha) \left< \NoH \right> |J_{h \rightarrow l}|^{-1} \\
+|J_{h \rightarrow l}| = 4 \left< \VoH \right>
+\end{equation}$$
+</p>
+<a class="target" name="choosingimportantdirections">&nbsp;</a><a class="target" name="annex/importancesamplingfortheibl/choosingimportantdirections">&nbsp;</a><a class="target" name="toc9.2.1">&nbsp;</a><h3>Choosing important directions</h3>
+<p>
+
+Refer to section <a href="#toc9.3" target="_self">9.3</a> for more details. Given a uniform distribution \((\zeta_{\phi},\zeta_{\theta})\) the important direction \(l\) is defined by equation \(\ref{importantDirection}\).
+</p><p>
+$$\begin{equation}\label{importantDirection}
+\phi = 2 \pi \zeta_{\phi} \\
+\theta = cos^{-1} \sqrt{\frac{1 - \zeta_{\theta}}{(\alpha^2 - 1)\zeta_{\theta}+1}} \\
+l = \{ cos \phi sin \theta, sin \phi sin \theta, cos \theta \}
+\end{equation}$$
+</p><p>
+Typically, \( (\zeta_{\phi},\zeta_{\theta}) \) are chosen using the Hammersley uniform distribution algorithm described in section <a href="#toc9.4" target="_self">9.4</a>.
+</p>
+<a class="target" name="pre-filteredimportancesampling">&nbsp;</a><a class="target" name="annex/importancesamplingfortheibl/pre-filteredimportancesampling">&nbsp;</a><a class="target" name="toc9.2.2">&nbsp;</a><h3>Pre-filtered importance sampling</h3>
+<p>
+
+Importance sampling considers only the PDF to generate important directions; in particular, it is oblivious to the actual content of the IBL. If the latter contains high frequencies in areas without a lot of samples, the integration won’t be accurate. This can be somewhat mitigated by using a technique called <em class="underscore">pre-filtered importance sampling</em>, in addition this allows the integral to converge with many fewer samples.
+</p><p>
+Pre-filtered importance sampling uses several images of the environment increasingly low-pass filtered. This is typically implemented very efficiently with mipmaps and a box filter. The LOD is selected based on the sample importance, that is, low probability samples use a higher LOD index (more filtered).
+</p><p>
+This technique is described in details in [<a href="#citation-krivanek08" target="_self">Krivanek08</a>].
+</p><p>
+The cubemap LOD is determined in the following way:
+</p><p>
+$$\begin{align*}
+lod &= log_4 \left( K\frac{\Omega_s}{\Omega_p} \right) \\
+K &= 4.0 \\
+\Omega_s &= \frac{1}{N \cdot p(l_i)} \\
+\Omega_p &\approx \frac{4\pi}{6 \cdot width \cdot height}
+\end{align*}$$
+</p><p>
+Where \(K\) is a constant determined empirically, \(p\) the PDF of the BRDF, \( \Omega_{s} \) the solid angle associated to the sample and \(\Omega_p\) the solid angle associated with the texel in the cubemap.
+</p><p>
+Cubemap sampling is done using seamless trilinear filtering. It is extremely important to sample the cubemap correctly across faces using OpenGL's seamless sampling feature or any other technique that avoids/reduces seams.
+</p><p>
+<a href="#table_importancesamplingviz" target="_self">Table&nbsp;17</a> shows a comparison between importance sampling and pre-filtered importance sampling when applied to <a href="#figure_importancesamplingref" target="_self">figure&nbsp;90</a>.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_importancesamplingref">&nbsp;</a><a href="../images/image_is_original.png" target="_blank"><img class="markdeep" src="../images/image_is_original.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;90:</b> Importance sampling image reference</span></center></div></center>
+</p><p>
+<div class='table'>
+<a class="target" name="table_importancesamplingviz">&nbsp;</a><table class="table"><tr><th  style="text-align:left"> Samples </th><th  style="text-align:left"> Importance sampling </th><th  style="text-align:left"> Pre-filtered importance sampling </th></tr>
+<tr><td  style="text-align:left"> 4096 </td><td  style="text-align:left"> <a href="../images/image_is_4096.png" target="_blank"><img class="markdeep" src="../images/image_is_4096.png" /></a> </td><td  style="text-align:left"> &nbsp; </td></tr>
+<tr><td  style="text-align:left"> 1024 </td><td  style="text-align:left"> <a href="../images/image_is_1024.png" target="_blank"><img class="markdeep" src="../images/image_is_1024.png" /></a> </td><td  style="text-align:left"> <a href="../images/image_fis_1024.png" target="_blank"><img class="markdeep" src="../images/image_fis_1024.png" /></a> </td></tr>
+<tr><td  style="text-align:left"> 32 </td><td  style="text-align:left"> <a href="../images/image_is_32.png" target="_blank"><img class="markdeep" src="../images/image_is_32.png" /></a> </td><td  style="text-align:left"> <a href="../images/image_fis_32.png" target="_blank"><img class="markdeep" src="../images/image_fis_32.png" /></a> </td></tr>
+</table><center><div class="tablecaption"><b style="font-style:normal;">Table&nbsp;17:</b> Importance sampling vs pre-filtered importance sampling with \(\alpha = 0.4\)</div></center></div>
+</p><p>
+The reference renderer used in the comparison below performs no approximation. In particular, it does not assume \(v = n\) and does not perform the split sum approximation.  The pre-filtered renderer uses all the techniques discussed in this section: pre-filtered cubemaps, the analytic formulation of the DFG term, and of course the split sum approximation.
+</p><p>
+Left: reference renderer, right: pre-filtered importance sampling.
+</p><p>
+<table width="100%"><tr valign="top"><td>
+</p><p>
+<center><a href="../images/image_is_ref_1.png" target="_blank"><img class="markdeep" src="../images/image_is_ref_1.png" /></a></center>
+</p><p>
+</td><td>
+</p><p>
+ <center><a href="../images/image_filtered_1.png" target="_blank"><img class="markdeep" src="../images/image_filtered_1.png" /></a></center>
+</p><p>
+</td></tr><tr valign="top"><td>
+</p><p>
+<center><a href="../images/image_is_ref_2.png" target="_blank"><img class="markdeep" src="../images/image_is_ref_2.png" /></a></center>
+</p><p>
+</td><td>
+</p><p>
+ <center><a href="../images/image_filtered_2.png" target="_blank"><img class="markdeep" src="../images/image_filtered_2.png" /></a></center>
+</p><p>
+</td></tr><tr valign="top"><td>
+</p><p>
+<center><a href="../images/image_is_ref_3.png" target="_blank"><img class="markdeep" src="../images/image_is_ref_3.png" /></a></center>
+</p><p>
+</td><td>
+</p><p>
+ <center><a href="../images/image_filtered_3.png" target="_blank"><img class="markdeep" src="../images/image_filtered_3.png" /></a></center>
+</p><p>
+</td></tr><tr valign="top"><td>
+</p><p>
+<center><a href="../images/image_is_ref_4.png" target="_blank"><img class="markdeep" src="../images/image_is_ref_4.png" /></a></center>
+</p><p>
+</td><td>
+</p><p>
+ <center><a href="../images/image_filtered_4.png" target="_blank"><img class="markdeep" src="../images/image_filtered_4.png" /></a></center>
+</p><p>
+</td></tr></table>
+</p>
+<a class="target" name="choosingimportantdirectionsforsamplingthebrdf">&nbsp;</a><a class="target" name="annex/choosingimportantdirectionsforsamplingthebrdf">&nbsp;</a><a class="target" name="toc9.3">&nbsp;</a><h2>Choosing important directions for sampling the BRDF</h2>
+<p>
+
+For simplicity we use the \( D \) term of the BRDF as the PDF, however the PDF must be normalized such that the integral over the hemisphere is 1:
+</p><p>
+$$\begin{equation}
+\int_{\Omega}p(m)dm = 1 \\
+\int_{\Omega}D(m)(n \cdot m)dm = 1 \\
+\int_{\phi=0}^{2\pi}\int_{\theta=0}^{\frac{\pi}{2}}D(\theta,\phi) cos \theta sin \theta d\theta d\phi = 1 \\
+\end{equation}$$
+</p><p>
+The PDF of the BRDF can therefore be expressed as in equation \(\ref{importantPDF}\):
+</p><p>
+$$\begin{equation}\label{importantPDF}
+p(\theta,\phi) = \frac{\alpha^2}{\pi(cos^2\theta (\alpha^2-1) + 1)^2} cos\theta sin\theta
+\end{equation}$$
+</p><p>
+The term \(sin\theta\) comes from the differential solid angle \(sin\theta d\phi d\theta\) since we integrate over a sphere. We sample \(\theta\) and \(\phi\) independently:
+</p><p>
+$$\begin{align*}
+p(\theta) &= \int_0^{2\pi} p(\theta,\phi) d\phi = \frac{2\alpha^2}{(cos^2\theta (\alpha^2-1) + 1)^2} cos\theta sin\theta \\
+p(\phi) &= \frac{p(\theta,\phi)}{p(\phi)} = \frac{1}{2\pi}
+\end{align*}$$
+</p><p>
+The expression of \( p(\phi) \) is true for an isotropic distribution of normals.
+</p><p>
+We then calculate the cumulative distribution function (CDF) for each variable:
+</p><p>
+$$\begin{align*}
+P(s_{\phi}) &= \int_{0}^{s_{\phi}} p(\phi) d\phi = \frac{s_{\phi}}{2\pi} \\
+P(s_{\theta}) &= \int_{0}^{s_{\theta}} p(\theta) d\theta = 2 \alpha^2 \left( \frac{1}{(2\alpha^4-4\alpha^2+2) cos(s_{\theta})^2 + 2\alpha^2 - 2} - \frac{1}{2\alpha^4-2\alpha^2} \right)
+\end{align*}$$
+</p><p>
+We set \( P(s_{\phi}) \) and \( P(s_{\theta}) \) to random variables \( \zeta_{\phi} \) and \( \zeta_{\theta} \) and solve for \( s_{\phi} \) and \( s_{\theta} \) respectively:
+</p><p>
+$$\begin{align*}
+P(s_{\phi}) &= \zeta_{\phi} \rightarrow s_{\phi} = 2\pi\zeta_{\phi} \\
+P(s_{\theta}) &= \zeta_{\theta} \rightarrow s_{\theta} = cos^{-1} \sqrt{\frac{1-\zeta_{\theta}}{(\alpha^2-1)\zeta_{\theta}+1}}
+\end{align*}$$
+</p><p>
+So given a uniform distribution \( (\zeta_{\phi},\zeta_{\theta}) \), our important direction \(l\) is defined as:
+</p><p>
+$$\begin{align*}
+\phi &= 2\pi\zeta_{\phi} \\
+\theta &= cos^{-1} \sqrt{\frac{1-\zeta_{\theta}}{(\alpha^2-1)\zeta_{\theta}+1}} \\
+l &= \{ cos\phi sin\theta,sin\phi sin\theta,cos\theta \}
+\end{align*}$$
+</p>
+<a class="target" name="hammersleysequence">&nbsp;</a><a class="target" name="annex/hammersleysequence">&nbsp;</a><a class="target" name="toc9.4">&nbsp;</a><h2>Hammersley sequence</h2>
+<pre class="listing tilde"><code><span class="line"></span>vec2f hammersley(uint i, <span class="hljs-built_in">float</span> numSamples) {
+<span class="line"></span>    uint bits = i;
+<span class="line"></span>    bits = (bits &lt;&lt; <span class="hljs-string">16) | (bits &gt;&gt; 16</span>);
+<span class="line"></span>    bits = ((bits &amp; <span class="hljs-number">0</span>x55555555) &lt;&lt; <span class="hljs-number">1</span>) | ((bits &amp; <span class="hljs-number">0</span>xAAAAAAAA) &gt;&gt; <span class="hljs-number">1</span>);
+<span class="line"></span>    bits = ((bits &amp; <span class="hljs-number">0</span>x33333333) &lt;&lt; <span class="hljs-number">2</span>) | ((bits &amp; <span class="hljs-number">0</span>xCCCCCCCC) &gt;&gt; <span class="hljs-number">2</span>);
+<span class="line"></span>    bits = ((bits &amp; <span class="hljs-number">0</span>x0F0F0F0F) &lt;&lt; <span class="hljs-number">4</span>) | ((bits &amp; <span class="hljs-number">0</span>xF0F0F0F0) &gt;&gt; <span class="hljs-number">4</span>);
+<span class="line"></span>    bits = ((bits &amp; <span class="hljs-number">0</span>x00FF00FF) &lt;&lt; <span class="hljs-number">8</span>) | ((bits &amp; <span class="hljs-number">0</span>xFF00FF00) &gt;&gt; <span class="hljs-number">8</span>);
+<span class="line"></span>    return vec2f(i / numSamples, bits / exp2(<span class="hljs-number">32</span>));
+<span class="line"></span>}</code></pre><center><div class="listingcaption tilde">[C++ implementation of a Hammersley sequence generator]</div></center>
+<a class="target" name="precomputinglforimage-basedlighting">&nbsp;</a><a class="target" name="annex/precomputinglforimage-basedlighting">&nbsp;</a><a class="target" name="toc9.5">&nbsp;</a><h2>Precomputing L for image-based lighting</h2>
+<p>
+
+The term \( L_{DFG} \) is only dependent on \( \NoV \). Below, the normal is arbitrarily set to \( n=\left[0, 0, 1\right] \) and \(v\) is chosen to satisfy \( \NoV \). The vector \( h_i \) is the \( D_{GGX}(\alpha) \) important direction sample \(i\).
+</p><pre class="listing tilde"><code><span class="line"></span><span class="hljs-type">float</span> <span class="hljs-title function_">GDFG</span><span class="hljs-params">(<span class="hljs-type">float</span> NoV, <span class="hljs-type">float</span> NoL, <span class="hljs-type">float</span> a)</span> {
+<span class="line"></span>    <span class="hljs-type">float</span> <span class="hljs-variable">a2</span> <span class="hljs-operator">=</span> a * a;
+<span class="line"></span>    <span class="hljs-type">float</span> <span class="hljs-variable">GGXL</span> <span class="hljs-operator">=</span> NoV * sqrt((-NoL * a2 + NoL) * NoL + a2);
+<span class="line"></span>    <span class="hljs-type">float</span> <span class="hljs-variable">GGXV</span> <span class="hljs-operator">=</span> NoL * sqrt((-NoV * a2 + NoV) * NoV + a2);
+<span class="line"></span>    <span class="hljs-keyword">return</span> (<span class="hljs-number">2</span> * NoL) / (GGXV + GGXL);
+<span class="line"></span>}
+<span class="line"></span>
+<span class="line"></span>float2 <span class="hljs-title function_">DFG</span><span class="hljs-params">(<span class="hljs-type">float</span> NoV, <span class="hljs-type">float</span> a)</span> {
+<span class="line"></span>    float3 V;
+<span class="line"></span>    V.x = sqrt(<span class="hljs-number">1.0f</span> - NoV*NoV);
+<span class="line"></span>    V.y = <span class="hljs-number">0.0f</span>;
+<span class="line"></span>    V.z = NoV;
+<span class="line"></span>
+<span class="line"></span>    <span class="hljs-type">float2</span> <span class="hljs-variable">r</span> <span class="hljs-operator">=</span> <span class="hljs-number">0.0f</span>;
+<span class="line"></span>    <span class="hljs-keyword">for</span> (<span class="hljs-type">uint</span> <span class="hljs-variable">i</span> <span class="hljs-operator">=</span> <span class="hljs-number">0</span>; i &lt; sampleCount; i++) {
+<span class="line"></span>        <span class="hljs-type">float2</span> <span class="hljs-variable">Xi</span> <span class="hljs-operator">=</span> hammersley(i, sampleCount);
+<span class="line"></span>        <span class="hljs-type">float3</span> <span class="hljs-variable">H</span> <span class="hljs-operator">=</span> importanceSampleGGX(Xi, a, N);
+<span class="line"></span>        <span class="hljs-type">float3</span> <span class="hljs-variable">L</span> <span class="hljs-operator">=</span> <span class="hljs-number">2.0f</span> * dot(V, H) * H - V;
+<span class="line"></span>
+<span class="line"></span>        <span class="hljs-type">float</span> <span class="hljs-variable">VoH</span> <span class="hljs-operator">=</span> saturate(dot(V, H));
+<span class="line"></span>        <span class="hljs-type">float</span> <span class="hljs-variable">NoL</span> <span class="hljs-operator">=</span> saturate(L.z);
+<span class="line"></span>        <span class="hljs-type">float</span> <span class="hljs-variable">NoH</span> <span class="hljs-operator">=</span> saturate(H.z);
+<span class="line"></span>
+<span class="line"></span>        <span class="hljs-keyword">if</span> (NoL &gt; <span class="hljs-number">0.0f</span>) {
+<span class="line"></span>            <span class="hljs-type">float</span> <span class="hljs-variable">G</span> <span class="hljs-operator">=</span> GDFG(NoV, NoL, a);
+<span class="line"></span>            <span class="hljs-type">float</span> <span class="hljs-variable">Gv</span> <span class="hljs-operator">=</span> G * VoH / NoH;
+<span class="line"></span>            <span class="hljs-type">float</span> <span class="hljs-variable">Fc</span> <span class="hljs-operator">=</span> pow(<span class="hljs-number">1</span> - VoH, <span class="hljs-number">5.0f</span>);
+<span class="line"></span>            r.x += Gv * (<span class="hljs-number">1</span> - Fc);
+<span class="line"></span>            r.y += Gv * Fc;
+<span class="line"></span>        }
+<span class="line"></span>    }
+<span class="line"></span>    <span class="hljs-keyword">return</span> r * (<span class="hljs-number">1.0f</span> / sampleCount);
+<span class="line"></span>}</code></pre><center><div class="listingcaption tilde">[C++ implementation of the \( L_{DFG} \) term]</div></center>
+<a class="target" name="sphericalharmonics">&nbsp;</a><a class="target" name="annex/sphericalharmonics">&nbsp;</a><a class="target" name="toc9.6">&nbsp;</a><h2>Spherical Harmonics</h2>
+<p>
+<div class='table'>
+<a class="target" name="table_shsymbols">&nbsp;</a><table class="table"><tr><th  style="text-align:center"> Symbol </th><th  style="text-align:left"> Definition </th></tr>
+<tr><td  style="text-align:center"> \(K^m_l\) </td><td  style="text-align:left"> Normalization factors </td></tr>
+<tr><td  style="text-align:center"> \(P^m_l(x)\) </td><td  style="text-align:left"> Associated Legendre polynomials </td></tr>
+<tr><td  style="text-align:center"> \(y^m_l\) </td><td  style="text-align:left"> Spherical harmonics bases, or SH bases </td></tr>
+<tr><td  style="text-align:center"> \(L^m_l\) </td><td  style="text-align:left"> SH coefficients of the \(L(s)\) function defined on the unit sphere </td></tr>
+</table><center><div class="tablecaption"><b style="font-style:normal;">Table&nbsp;18:</b> Spherical harmonics symbols definitions</div></center></div>
+</p>
+<a class="target" name="basisfunctions">&nbsp;</a><a class="target" name="annex/sphericalharmonics/basisfunctions">&nbsp;</a><a class="target" name="toc9.6.1">&nbsp;</a><h3>Basis functions</h3>
+<p>
+
+Spherical parameterization of points on the surface of the unit sphere:
+</p><p>
+$$\begin{equation}
+\{ x, y, z \} = \{ cos \phi sin \theta, sin \phi sin \theta, cos \theta \}
+\end{equation}$$
+</p><p>
+The complex spherical harmonics bases are given by:
+</p><p>
+$$\begin{equation}
+Y^m_l(\theta, \phi) = K^m_l e^{im\theta} P^{|m|}_l(cos \theta), l \in N, -l <= m <= l
+\end{equation}$$
+</p><p>
+However we only need the real bases:
+</p><p>
+$$\begin{align*}
+y^{m > 0}_l &= \sqrt{2} K^m_l cos(m \phi) P^m_l(cos \theta) \\
+y^{m < 0}_l &= \sqrt{2} K^m_l sin(|m| \phi) P^{|m|}_l(cos \theta) \\
+y^0_l &= K^0_l P^0_l(cos \theta)
+\end{align*}$$
+</p><p>
+The normalization factors are given by:
+</p><p>
+$$\begin{equation}
+K^m_l = \sqrt{\frac{(2l + 1)(l - |m|)!}{4 \pi (l + |m|)!}}
+\end{equation}$$
+</p><p>
+The associated Legendre polynomials \(P^{|m|}_l\) can be calculated from the following recursions:
+</p><p>
+$$\begin{equation}\label{shRecursions}
+P^0_0(x) = 1 \\
+P^0_1(x) = x \\
+P^l_l(x) = (-1)^l (2l - 1)!! (1 - x^2)^{\frac{l}{2}} \\
+P^m_l(x) = \frac{((2l - 1) x P^m_{l - 1} - (l + m - 1) P^m_{l - 2})}{l - m} \\
+\end{equation}$$
+</p><p>
+Computing \(y^{|m|}_l\) requires to compute \(P^{|m|}_l(z)\) first.
+This can be accomplished fairly easily using the recursions in equation \(\ref{shRecursions}\).
+The third recursion can be used to &ldquo;move diagonally&rdquo; in <a href="#table_basisfunctions" target="_self">table&nbsp;20</a>, i.e. calculating \(y^0_0\), \(y^1_1\), \(y^2_2\) etc.
+Then, the fourth recursion can be used to move vertically.
+<div class='table'>
+<a class="target" name="table_basisfunctions">&nbsp;</a><table class="table"><tr><th  style="text-align:center"> Band index </th><th  style="text-align:center"> Basis functions \(-l <= m <= l\) </th></tr>
+<tr><td  style="text-align:center"> \(l = 0\) </td><td  style="text-align:center"> \(y^0_0\) </td></tr>
+<tr><td  style="text-align:center"> \(l = 1\) </td><td  style="text-align:center"> \(y^{-1}_1\) \(y^0_1\) \(y^1_1\) </td></tr>
+<tr><td  style="text-align:center"> \(l = 2\) </td><td  style="text-align:center"> \(y^{-2}_2\) \(y^{-1}_2\) \(y^0_2\) \(y^1_2\) \(y^2_2\) </td></tr>
+</table><center><div class="tablecaption"><b style="font-style:normal;">Table&nbsp;19:</b> Basis functions per band</div></center></div>
+</p><p>
+It’s also fairly easy to compute the trigonometric terms recursively:
+</p><p>
+$$\begin{align*}
+C_m &\equiv cos(m \phi)sin(\theta)^m \\
+S_m &\equiv sin(m \phi)sin(\theta)^m \\
+\{ x, y, z \} &= \{ cos \phi sin \theta, sin \phi sin \theta, cos \theta \}
+\end{align*}$$
+</p><p>
+Using the angle sum trigonometric identities:
+</p><p>
+$$\begin{align*}
+cos(m \phi + \phi) &= cos(m \phi) cos(\phi) - sin(m \phi) sin(\phi) \Leftrightarrow C_{m + 1} = x C_m - y S_m \\
+sin(m \phi + \phi) &= sin(m \phi) cos(\phi) + cos(m \phi) sin(\phi) \Leftrightarrow S_{m + 1} = x S_m - y C_m
+\end{align*}$$
+</p><p>
+<a href="#listing_nonnormalizedshbasis" target="_self">Listing&nbsp;47</a> shows the C++ code to compute the non-normalized SH basis \(\frac{y^m_l(s)}{\sqrt{2} K^m_l}\):
+</p><a class="target" name="listing_nonnormalizedshbasis">&nbsp;</a><pre class="listing tilde"><code><span class="line"></span><span class="hljs-function"><span class="hljs-type">static</span> <span class="hljs-keyword">inline</span> <span class="hljs-type">size_t</span> <span class="hljs-title">SHindex</span><span class="hljs-params">(<span class="hljs-type">ssize_t</span> m, <span class="hljs-type">size_t</span> l)</span> </span>{
+<span class="line"></span>    <span class="hljs-keyword">return</span> l * (l + <span class="hljs-number">1</span>) + m;
+<span class="line"></span>}
+<span class="line"></span>
+<span class="line"></span><span class="hljs-function"><span class="hljs-type">void</span> <span class="hljs-title">computeShBasis</span><span class="hljs-params">(
+<span class="line"></span>        <span class="hljs-type">double</span>* <span class="hljs-type">const</span> SHb,
+<span class="line"></span>        <span class="hljs-type">size_t</span> numBands,
+<span class="line"></span>        <span class="hljs-type">const</span> vec3&amp; s)</span>
+<span class="line"></span></span>{
+<span class="line"></span>    <span class="hljs-comment">// handle m=0 separately, since it produces only one coefficient</span>
+<span class="line"></span>    <span class="hljs-type">double</span> Pml_2 = <span class="hljs-number">0</span>;
+<span class="line"></span>    <span class="hljs-type">double</span> Pml_1 = <span class="hljs-number">1</span>;
+<span class="line"></span>    SHb[<span class="hljs-number">0</span>] =  Pml_1;
+<span class="line"></span>    <span class="hljs-keyword">for</span> (<span class="hljs-type">ssize_t</span> l = <span class="hljs-number">1</span>; l &lt; numBands; l++) {
+<span class="line"></span>        <span class="hljs-type">double</span> Pml = ((<span class="hljs-number">2</span> * l - <span class="hljs-number">1</span>) * Pml_1 * s.z - (l - <span class="hljs-number">1</span>) * Pml_2) / l;
+<span class="line"></span>        Pml_2 = Pml_1;
+<span class="line"></span>        Pml_1 = Pml;
+<span class="line"></span>        SHb[<span class="hljs-built_in">SHindex</span>(<span class="hljs-number">0</span>, l)] = Pml;
+<span class="line"></span>    }
+<span class="line"></span>    <span class="hljs-type">double</span> Pmm = <span class="hljs-number">1</span>;
+<span class="line"></span>    <span class="hljs-keyword">for</span> (<span class="hljs-type">ssize_t</span> m = <span class="hljs-number">1</span>; m &lt; numBands ; m++) {
+<span class="line"></span>        Pmm = (<span class="hljs-number">1</span> - <span class="hljs-number">2</span> * m) * Pmm;
+<span class="line"></span>        <span class="hljs-type">double</span> Pml_2 = Pmm;
+<span class="line"></span>        <span class="hljs-type">double</span> Pml_1 = (<span class="hljs-number">2</span> * m + <span class="hljs-number">1</span>)*Pmm*s.z;
+<span class="line"></span>        <span class="hljs-comment">// l == m</span>
+<span class="line"></span>        SHb[<span class="hljs-built_in">SHindex</span>(-m, m)] = Pml_2;
+<span class="line"></span>        SHb[<span class="hljs-built_in">SHindex</span>( m, m)] = Pml_2;
+<span class="line"></span>        <span class="hljs-keyword">if</span> (m + <span class="hljs-number">1</span> &lt; numBands) {
+<span class="line"></span>            <span class="hljs-comment">// l == m+1</span>
+<span class="line"></span>            SHb[<span class="hljs-built_in">SHindex</span>(-m, m + <span class="hljs-number">1</span>)] = Pml_1;
+<span class="line"></span>            SHb[<span class="hljs-built_in">SHindex</span>( m, m + <span class="hljs-number">1</span>)] = Pml_1;
+<span class="line"></span>            <span class="hljs-keyword">for</span> (<span class="hljs-type">ssize_t</span> l = m + <span class="hljs-number">2</span>; l &lt; numBands; l++) {
+<span class="line"></span>                <span class="hljs-type">double</span> Pml = ((<span class="hljs-number">2</span> * l - <span class="hljs-number">1</span>) * Pml_1 * s.z - (l + m - <span class="hljs-number">1</span>) * Pml_2)
+<span class="line"></span>                        / (l - m);
+<span class="line"></span>                Pml_2 = Pml_1;
+<span class="line"></span>                Pml_1 = Pml;
+<span class="line"></span>                SHb[<span class="hljs-built_in">SHindex</span>(-m, l)] = Pml;
+<span class="line"></span>                SHb[<span class="hljs-built_in">SHindex</span>( m, l)] = Pml;
+<span class="line"></span>            }
+<span class="line"></span>        }
+<span class="line"></span>    }
+<span class="line"></span>    <span class="hljs-type">double</span> Cm = s.x;
+<span class="line"></span>    <span class="hljs-type">double</span> Sm = s.y;
+<span class="line"></span>    <span class="hljs-keyword">for</span> (<span class="hljs-type">ssize_t</span> m = <span class="hljs-number">1</span>; m &lt;= numBands ; m++) {
+<span class="line"></span>        <span class="hljs-keyword">for</span> (<span class="hljs-type">ssize_t</span> l = m; l &lt; numBands ; l++) {
+<span class="line"></span>            SHb[<span class="hljs-built_in">SHindex</span>(-m, l)] *= Sm;
+<span class="line"></span>            SHb[<span class="hljs-built_in">SHindex</span>( m, l)] *= Cm;
+<span class="line"></span>        }
+<span class="line"></span>        <span class="hljs-type">double</span> Cm1 = Cm * s.x - Sm * s.y;
+<span class="line"></span>        <span class="hljs-type">double</span> Sm1 = Sm * s.x + Cm * s.y;
+<span class="line"></span>        Cm = Cm1;
+<span class="line"></span>        Sm = Sm1;
+<span class="line"></span>    }
+<span class="line"></span>}</code></pre><center><div class="listingcaption tilde"><b style="font-style:normal;">Listing&nbsp;47:</b> C++ implementation to compute a non-normalized SH basis</div></center>
+<p>
+
+Normalized SH basis functions \(y^m_l(s)\) for the first 3 bands:
+<div class='table'>
+<a class="target" name="table_basisfunctions">&nbsp;</a><table class="table"><tr><th  style="text-align:center"> Band </th><th  style="text-align:center"> \(m = -2\) </th><th  style="text-align:center"> \(m = -1\) </th><th  style="text-align:center"> \(m = 0\) </th><th  style="text-align:center"> \(m = 1\) </th><th  style="text-align:center"> \(m = 2\)                     </th></tr>
+<tr><td  style="text-align:center"> \(l = 0\) </td><td  style="text-align:center">  </td><td  style="text-align:center">  </td><td  style="text-align:center"> \(\frac{1}{2}\sqrt{\frac{1}{\pi}}\) </td><td  style="text-align:center">  </td><td  style="text-align:center">  </td></tr>
+<tr><td  style="text-align:center"> \(l = 1\) </td><td  style="text-align:center">  </td><td  style="text-align:center"> \(-\frac{1}{2}\sqrt{\frac{3}{\pi}}y\) </td><td  style="text-align:center"> \(\frac{1}{2}\sqrt{\frac{3}{\pi}}z\) </td><td  style="text-align:center"> \(-\frac{1}{2}\sqrt{\frac{3}{\pi}}x\) </td><td  style="text-align:center">  </td></tr>
+<tr><td  style="text-align:center"> \(l = 2\) </td><td  style="text-align:center"> \(\frac{1}{2}\sqrt{\frac{15}{\pi}}xy\) </td><td  style="text-align:center"> \(-\frac{1}{2}\sqrt{\frac{15}{\pi}}yz\) </td><td  style="text-align:center"> \(\frac{1}{4}\sqrt{\frac{5}{\pi}}(2z^2 - x^2 - y^2)\) </td><td  style="text-align:center"> \(-\frac{1}{2}\sqrt{\frac{15}{\pi}}xz\) </td><td  style="text-align:center"> \(\frac{1}{4}\sqrt{\frac{15}{\pi}}(x^2 - y^2)\)  </td></tr>
+</table><center><div class="tablecaption"><b style="font-style:normal;">Table&nbsp;20:</b> Normalized basis functions per band</div></center></div>
+</p>
+<a class="target" name="decompositionandreconstruction">&nbsp;</a><a class="target" name="annex/sphericalharmonics/decompositionandreconstruction">&nbsp;</a><a class="target" name="toc9.6.2">&nbsp;</a><h3>Decomposition and reconstruction</h3>
+<p>
+
+A function \(L(s)\) defined on a sphere is projected to the SH basis as follows:
+</p><p>
+$$\begin{equation}
+L^m_l = \int_\Omega L(s) y^m_l(s) ds \\
+L^m_l = \int_{\theta = 0}^{\pi} \int_{\phi = 0}^{2\pi} L(\theta, \phi) y^m_l(\theta, \phi) sin \theta d\theta d\phi
+\end{equation}$$
+</p><p>
+Note that each \(L^m_l\) is a vector of 3 values, one for each RGB color channel.
+</p><p>
+The inverse transformation, or reconstruction, or rendering, from the SH coefficients is given by:
+</p><p>
+$$\begin{equation}
+\hat{L}(s) = \sum_l \sum_{m = -l}^l L^m_l y^m_l(s)
+\end{equation}$$
+</p>
+<a class="target" name="decompositionof%5C(%5Cleft%5C)">&nbsp;</a><a class="target" name="annex/sphericalharmonics/decompositionof%5C(%5Cleft%5C)">&nbsp;</a><a class="target" name="toc9.6.3">&nbsp;</a><h3>Decomposition of \(\left< cos \theta \right>\)</h3>
+<p>
+
+Since \(\left< cos \theta \right>\) does not depend on \(\phi\) (azimuthal independence), the integral simplifies to:
+</p><p>
+$$\begin{align*}
+C^0_l &= 2\pi \int_0^{\pi} \left< cos \theta \right> y^0_l(\theta) sin \theta d\theta \\
+C^0_l &= 2\pi K^m_l \int_0^{\frac{\pi}{2}} P^0_l(cos \theta) cos \theta sin \theta d\theta \\
+C^m_l &= 0, m != 0
+\end{align*}$$
+</p><p>
+In [<a href="#citation-ramamoorthi01" target="_self">Ramamoorthi01</a>] an analytical solution to the integral is described:
+</p><p>
+$$\begin{align*}
+C_1 &= \sqrt{\frac{\pi}{3}} \\
+C_{odd} &= 0 \\
+C_{l, even} &= 2\pi \sqrt{\frac{2l + 1}{4\pi}} \frac{(-1)^{\frac{l}{2} - 1}}{(l + 2)(l - 1)} \frac{l!}{2^l (\frac{l!}{2})^2}
+\end{align*}$$
+</p><p>
+The first few coefficients are:
+</p><p>
+$$\begin{align*}
+C_0 &= +0.88623 \\
+C_1 &= +1.02333 \\
+C_2 &= +0.49542 \\
+C_3 &= +0.00000 \\
+C_4 &= -0.11078
+\end{align*}$$
+</p><p>
+Very few coefficients are needed to reasonably approximate \(\left< cos \theta \right>\), as shown in <a href="#figure_shcosthetaapprox" target="_self">figure&nbsp;91</a>.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_shcosthetaapprox">&nbsp;</a><a href="../images/chart_sh_cos_thera_approx.png" target="_blank"><img class="markdeep" src="../images/chart_sh_cos_thera_approx.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;91:</b> Approximation of \(cos \theta\) with SH coefficients</span></center></div></center>
+</p>
+<a class="target" name="convolution">&nbsp;</a><a class="target" name="annex/sphericalharmonics/convolution">&nbsp;</a><a class="target" name="toc9.6.4">&nbsp;</a><h3>Convolution</h3>
+<p>
+
+Convolutions by a kernel \(h\) that has a circular symmetry can be applied directly and easily in SH space:
+</p><p>
+$$\begin{equation}
+(h * f)^m_l = \sqrt{\frac{4\pi}{2l + 1}} h^0_l(s) f^m_l(s)
+\end{equation}$$
+</p><p>
+Conveniently, \(\sqrt{\frac{4\pi}{2l + 1}} = \frac{1}{K^0_l}\), so in practice we pre-multiply \(C_l\) by \(\frac{1}{K^0_l}\) and we get a simpler expression:
+</p><p>
+$$\begin{equation}
+\hat{C}_{l, even} = 2\pi \frac{(-1)^{\frac{l}{2} - 1}}{(l + 2)(l - 1)} \frac{l!}{2^l (\frac{l!}{2})^2} \\
+\hat{C}_1 = \frac{2\pi}{3}
+\end{equation}$$
+</p><p>
+Here is the C++ code to compute \(\hat{C}_l\):
+</p><pre class="listing tilde"><code><span class="line"></span><span class="hljs-function"><span class="hljs-type">static</span> <span class="hljs-type">double</span> <span class="hljs-title">factorial</span><span class="hljs-params">(<span class="hljs-type">size_t</span> n, <span class="hljs-type">size_t</span> d = <span class="hljs-number">1</span>)</span></span>;
+<span class="line"></span>
+<span class="line"></span><span class="hljs-comment">// &lt; cos(theta) &gt; SH coefficients pre-multiplied by 1 / K(0,l)</span>
+<span class="line"></span><span class="hljs-function"><span class="hljs-type">double</span> <span class="hljs-title">computeTruncatedCosSh</span><span class="hljs-params">(<span class="hljs-type">size_t</span> l)</span> </span>{
+<span class="line"></span>    <span class="hljs-keyword">if</span> (l == <span class="hljs-number">0</span>) {
+<span class="line"></span>        <span class="hljs-keyword">return</span> M_PI;
+<span class="line"></span>    } <span class="hljs-keyword">else</span> <span class="hljs-keyword">if</span> (l == <span class="hljs-number">1</span>) {
+<span class="line"></span>        <span class="hljs-keyword">return</span> <span class="hljs-number">2</span> * M_PI / <span class="hljs-number">3</span>;
+<span class="line"></span>    } <span class="hljs-keyword">else</span> <span class="hljs-keyword">if</span> (l &amp; <span class="hljs-number">1</span>) {
+<span class="line"></span>        <span class="hljs-keyword">return</span> <span class="hljs-number">0</span>;
+<span class="line"></span>    }
+<span class="line"></span>    <span class="hljs-type">const</span> <span class="hljs-type">size_t</span> l_2 = l / <span class="hljs-number">2</span>;
+<span class="line"></span>    <span class="hljs-type">double</span> A0 = ((l_2 &amp; <span class="hljs-number">1</span>) ? <span class="hljs-number">1.0</span> : <span class="hljs-number">-1.0</span>) / ((l + <span class="hljs-number">2</span>) * (l - <span class="hljs-number">1</span>));
+<span class="line"></span>    <span class="hljs-type">double</span> A1 = <span class="hljs-built_in">factorial</span>(l, l_2) / (<span class="hljs-built_in">factorial</span>(l_2) * (<span class="hljs-number">1</span> &lt;&lt; l));
+<span class="line"></span>    <span class="hljs-keyword">return</span> <span class="hljs-number">2</span> * M_PI * A0 * A1;
+<span class="line"></span>}
+<span class="line"></span>
+<span class="line"></span><span class="hljs-comment">// returns n! / d!</span>
+<span class="line"></span><span class="hljs-function"><span class="hljs-type">double</span> <span class="hljs-title">factorial</span><span class="hljs-params">(<span class="hljs-type">size_t</span> n, <span class="hljs-type">size_t</span> d )</span> </span>{
+<span class="line"></span>   d = std::<span class="hljs-built_in">max</span>(<span class="hljs-built_in">size_t</span>(<span class="hljs-number">1</span>), d);
+<span class="line"></span>   n = std::<span class="hljs-built_in">max</span>(<span class="hljs-built_in">size_t</span>(<span class="hljs-number">1</span>), n);
+<span class="line"></span>   <span class="hljs-type">double</span> r = <span class="hljs-number">1.0</span>;
+<span class="line"></span>   <span class="hljs-keyword">if</span> (n == d) {
+<span class="line"></span>       <span class="hljs-comment">// intentionally left blank</span>
+<span class="line"></span>   } <span class="hljs-keyword">else</span> <span class="hljs-keyword">if</span> (n &gt; d) {
+<span class="line"></span>       <span class="hljs-keyword">for</span> ( ; n&gt;d ; n--) {
+<span class="line"></span>           r *= n;
+<span class="line"></span>       }
+<span class="line"></span>   } <span class="hljs-keyword">else</span> {
+<span class="line"></span>       <span class="hljs-keyword">for</span> ( ; d&gt;n ; d--) {
+<span class="line"></span>           r *= d;
+<span class="line"></span>       }
+<span class="line"></span>       r = <span class="hljs-number">1.0</span> / r;
+<span class="line"></span>   }
+<span class="line"></span>   <span class="hljs-keyword">return</span> r;
+<span class="line"></span>}</code></pre>
+<a class="target" name="samplevalidationsceneformitsuba">&nbsp;</a><a class="target" name="annex/samplevalidationsceneformitsuba">&nbsp;</a><a class="target" name="toc9.7">&nbsp;</a><h2>Sample validation scene for Mitsuba</h2>
+<pre class="listing tilde"><code><span class="line"></span><span class="hljs-tag">&lt;<span class="hljs-name">scene</span> <span class="hljs-attr">version</span>=<span class="hljs-string">&quot;0.5.0&quot;</span>&gt;</span>
+<span class="line"></span>    <span class="hljs-tag">&lt;<span class="hljs-name">integrator</span> <span class="hljs-attr">type</span>=<span class="hljs-string">&quot;path&quot;</span>/&gt;</span>
+<span class="line"></span>
+<span class="line"></span>    <span class="hljs-tag">&lt;<span class="hljs-name">shape</span> <span class="hljs-attr">type</span>=<span class="hljs-string">&quot;serialized&quot;</span> <span class="hljs-attr">id</span>=<span class="hljs-string">&quot;sphere_mesh&quot;</span>&gt;</span>
+<span class="line"></span>        <span class="hljs-tag">&lt;<span class="hljs-name">string</span> <span class="hljs-attr">name</span>=<span class="hljs-string">&quot;filename&quot;</span> <span class="hljs-attr">value</span>=<span class="hljs-string">&quot;plastic_sphere.serialized&quot;</span>/&gt;</span>
+<span class="line"></span>        <span class="hljs-tag">&lt;<span class="hljs-name">integer</span> <span class="hljs-attr">name</span>=<span class="hljs-string">&quot;shapeIndex&quot;</span> <span class="hljs-attr">value</span>=<span class="hljs-string">&quot;0&quot;</span>/&gt;</span>
+<span class="line"></span>
+<span class="line"></span>        <span class="hljs-tag">&lt;<span class="hljs-name">bsdf</span> <span class="hljs-attr">type</span>=<span class="hljs-string">&quot;roughplastic&quot;</span>&gt;</span>
+<span class="line"></span>            <span class="hljs-tag">&lt;<span class="hljs-name">string</span> <span class="hljs-attr">name</span>=<span class="hljs-string">&quot;distribution&quot;</span> <span class="hljs-attr">value</span>=<span class="hljs-string">&quot;ggx&quot;</span>/&gt;</span>
+<span class="line"></span>            <span class="hljs-tag">&lt;<span class="hljs-name">float</span> <span class="hljs-attr">name</span>=<span class="hljs-string">&quot;alpha&quot;</span> <span class="hljs-attr">value</span>=<span class="hljs-string">&quot;0.0&quot;</span>/&gt;</span>
+<span class="line"></span>            <span class="hljs-tag">&lt;<span class="hljs-name">srgb</span> <span class="hljs-attr">name</span>=<span class="hljs-string">&quot;diffuseReflectance&quot;</span> <span class="hljs-attr">value</span>=<span class="hljs-string">&quot;0.81, 0.0, 0.0&quot;</span>/&gt;</span>
+<span class="line"></span>        <span class="hljs-tag">&lt;/<span class="hljs-name">bsdf</span>&gt;</span>
+<span class="line"></span>    <span class="hljs-tag">&lt;/<span class="hljs-name">shape</span>&gt;</span>
+<span class="line"></span>
+<span class="line"></span>    <span class="hljs-tag">&lt;<span class="hljs-name">emitter</span> <span class="hljs-attr">type</span>=<span class="hljs-string">&quot;envmap&quot;</span>&gt;</span>
+<span class="line"></span>        <span class="hljs-tag">&lt;<span class="hljs-name">string</span> <span class="hljs-attr">name</span>=<span class="hljs-string">&quot;filename&quot;</span> <span class="hljs-attr">value</span>=<span class="hljs-string">&quot;../../environments/office/office.exr&quot;</span>/&gt;</span>
+<span class="line"></span>        <span class="hljs-tag">&lt;<span class="hljs-name">float</span> <span class="hljs-attr">name</span>=<span class="hljs-string">&quot;scale&quot;</span> <span class="hljs-attr">value</span>=<span class="hljs-string">&quot;35000.0&quot;</span> /&gt;</span>
+<span class="line"></span>        <span class="hljs-tag">&lt;<span class="hljs-name">boolean</span> <span class="hljs-attr">name</span>=<span class="hljs-string">&quot;cache&quot;</span> <span class="hljs-attr">value</span>=<span class="hljs-string">&quot;false&quot;</span> /&gt;</span>
+<span class="line"></span>    <span class="hljs-tag">&lt;/<span class="hljs-name">emitter</span>&gt;</span>
+<span class="line"></span>
+<span class="line"></span>    <span class="hljs-tag">&lt;<span class="hljs-name">emitter</span> <span class="hljs-attr">type</span>=<span class="hljs-string">&quot;directional&quot;</span>&gt;</span>
+<span class="line"></span>        <span class="hljs-tag">&lt;<span class="hljs-name">vector</span> <span class="hljs-attr">name</span>=<span class="hljs-string">&quot;direction&quot;</span> <span class="hljs-attr">x</span>=<span class="hljs-string">&quot;-1&quot;</span> <span class="hljs-attr">y</span>=<span class="hljs-string">&quot;-1&quot;</span> <span class="hljs-attr">z</span>=<span class="hljs-string">&quot;1&quot;</span> /&gt;</span>
+<span class="line"></span>        <span class="hljs-tag">&lt;<span class="hljs-name">rgb</span> <span class="hljs-attr">name</span>=<span class="hljs-string">&quot;irradiance&quot;</span> <span class="hljs-attr">value</span>=<span class="hljs-string">&quot;120000.0, 115200.0, 114000.0&quot;</span> /&gt;</span>
+<span class="line"></span>    <span class="hljs-tag">&lt;/<span class="hljs-name">emitter</span>&gt;</span>
+<span class="line"></span>
+<span class="line"></span>    <span class="hljs-tag">&lt;<span class="hljs-name">sensor</span> <span class="hljs-attr">type</span>=<span class="hljs-string">&quot;perspective&quot;</span>&gt;</span>
+<span class="line"></span>        <span class="hljs-tag">&lt;<span class="hljs-name">float</span> <span class="hljs-attr">name</span>=<span class="hljs-string">&quot;farClip&quot;</span> <span class="hljs-attr">value</span>=<span class="hljs-string">&quot;12.0&quot;</span>/&gt;</span>
+<span class="line"></span>        <span class="hljs-tag">&lt;<span class="hljs-name">float</span> <span class="hljs-attr">name</span>=<span class="hljs-string">&quot;focusDistance&quot;</span> <span class="hljs-attr">value</span>=<span class="hljs-string">&quot;4.1&quot;</span>/&gt;</span>
+<span class="line"></span>        <span class="hljs-tag">&lt;<span class="hljs-name">float</span> <span class="hljs-attr">name</span>=<span class="hljs-string">&quot;fov&quot;</span> <span class="hljs-attr">value</span>=<span class="hljs-string">&quot;45&quot;</span>/&gt;</span>
+<span class="line"></span>        <span class="hljs-tag">&lt;<span class="hljs-name">string</span> <span class="hljs-attr">name</span>=<span class="hljs-string">&quot;fovAxis&quot;</span> <span class="hljs-attr">value</span>=<span class="hljs-string">&quot;y&quot;</span>/&gt;</span>
+<span class="line"></span>        <span class="hljs-tag">&lt;<span class="hljs-name">float</span> <span class="hljs-attr">name</span>=<span class="hljs-string">&quot;nearClip&quot;</span> <span class="hljs-attr">value</span>=<span class="hljs-string">&quot;0.01&quot;</span>/&gt;</span>
+<span class="line"></span>        <span class="hljs-tag">&lt;<span class="hljs-name">transform</span> <span class="hljs-attr">name</span>=<span class="hljs-string">&quot;toWorld&quot;</span>&gt;</span>
+<span class="line"></span>
+<span class="line"></span>            <span class="hljs-tag">&lt;<span class="hljs-name">lookat</span> <span class="hljs-attr">target</span>=<span class="hljs-string">&quot;0, 0, 0&quot;</span> <span class="hljs-attr">origin</span>=<span class="hljs-string">&quot;0, 0, -3.1&quot;</span> <span class="hljs-attr">up</span>=<span class="hljs-string">&quot;0, 1, 0&quot;</span>/&gt;</span>
+<span class="line"></span>        <span class="hljs-tag">&lt;/<span class="hljs-name">transform</span>&gt;</span>
+<span class="line"></span>
+<span class="line"></span>        <span class="hljs-tag">&lt;<span class="hljs-name">sampler</span> <span class="hljs-attr">type</span>=<span class="hljs-string">&quot;ldsampler&quot;</span>&gt;</span>
+<span class="line"></span>            <span class="hljs-tag">&lt;<span class="hljs-name">integer</span> <span class="hljs-attr">name</span>=<span class="hljs-string">&quot;sampleCount&quot;</span> <span class="hljs-attr">value</span>=<span class="hljs-string">&quot;256&quot;</span>/&gt;</span>
+<span class="line"></span>        <span class="hljs-tag">&lt;/<span class="hljs-name">sampler</span>&gt;</span>
+<span class="line"></span>
+<span class="line"></span>        <span class="hljs-tag">&lt;<span class="hljs-name">film</span> <span class="hljs-attr">type</span>=<span class="hljs-string">&quot;ldrfilm&quot;</span>&gt;</span>
+<span class="line"></span>            <span class="hljs-tag">&lt;<span class="hljs-name">integer</span> <span class="hljs-attr">name</span>=<span class="hljs-string">&quot;height&quot;</span> <span class="hljs-attr">value</span>=<span class="hljs-string">&quot;1440&quot;</span>/&gt;</span>
+<span class="line"></span>            <span class="hljs-tag">&lt;<span class="hljs-name">integer</span> <span class="hljs-attr">name</span>=<span class="hljs-string">&quot;width&quot;</span> <span class="hljs-attr">value</span>=<span class="hljs-string">&quot;2048&quot;</span>/&gt;</span>
+<span class="line"></span>            <span class="hljs-tag">&lt;<span class="hljs-name">float</span> <span class="hljs-attr">name</span>=<span class="hljs-string">&quot;exposure&quot;</span> <span class="hljs-attr">value</span>=<span class="hljs-string">&quot;-15.23&quot;</span> /&gt;</span>
+<span class="line"></span>            <span class="hljs-tag">&lt;<span class="hljs-name">rfilter</span> <span class="hljs-attr">type</span>=<span class="hljs-string">&quot;gaussian&quot;</span>/&gt;</span>
+<span class="line"></span>        <span class="hljs-tag">&lt;/<span class="hljs-name">film</span>&gt;</span>
+<span class="line"></span>    <span class="hljs-tag">&lt;/<span class="hljs-name">sensor</span>&gt;</span>
+<span class="line"></span><span class="hljs-tag">&lt;/<span class="hljs-name">scene</span>&gt;</span></code></pre>
+<a class="target" name="lightassignmentwithfroxels">&nbsp;</a><a class="target" name="annex/lightassignmentwithfroxels">&nbsp;</a><a class="target" name="toc9.8">&nbsp;</a><h2>Light assignment with froxels</h2>
+<p>
+
+Assigning lights to froxels can be implemented on the GPU using two compute shaders. The first one, shown in <a href="#listing_froxelgeneration" target="_self">listing&nbsp;48</a>, creates the froxels data (4 planes + a min Z and max Z per froxel) in an SSBO and needs to be run only once. The shader requires the following uniforms:
+</p><p>
+<dl><table><tr valign=top><td><dt>Projection&nbsp;matrix</dt></td><td><dd><p>    The projection matrix used to render the scene (view space to clip space transformation).
+</p></dd></td></tr><tr valign=top><td><dt>Inverse&nbsp;projection&nbsp;matrix</dt></td><td><dd><p>    The inverse of the projection matrix used to render the scene (clip space to view space transformation).
+</p></dd></td></tr><tr valign=top><td><dt>Depth&nbsp;parameters</dt></td><td><dd><p>    \(-log2(\frac{z_{lighnear}}{z_{far}}) \frac{1}{maxSlices-1}\), maximum number of depth slices, Z near and Z far.
+</p></dd></td></tr><tr valign=top><td><dt>Clip&nbsp;space&nbsp;size</dt></td><td><dd><p>    \(\frac{F_x \times F_r}{w} \times 2\), with \(F_x\) the number of tiles on the X axis, \(F_r\) the resolution in pixels of a tile and w the width in pixels of the render target.
+</p></dd></td></tr></table></dl></p><a class="target" name="listing_froxelgeneration">&nbsp;</a><pre class="listing tilde"><code><span class="line"></span><span class="hljs-meta">#version 310 es</span>
+<span class="line"></span>
+<span class="line"></span><span class="hljs-keyword">precision</span> <span class="hljs-keyword">highp</span> <span class="hljs-type">float</span>;
+<span class="line"></span><span class="hljs-keyword">precision</span> <span class="hljs-keyword">highp</span> <span class="hljs-type">int</span>;
+<span class="line"></span>
+<span class="line"></span>
+<span class="line"></span><span class="hljs-meta">#define FROXEL_RESOLUTION 80u</span>
+<span class="line"></span>
+<span class="line"></span><span class="hljs-keyword">layout</span>(<span class="hljs-keyword">local_size_x</span> = <span class="hljs-number">1</span>, <span class="hljs-keyword">local_size_y</span> = <span class="hljs-number">1</span>, <span class="hljs-keyword">local_size_z</span> = <span class="hljs-number">1</span>) <span class="hljs-keyword">in</span>;
+<span class="line"></span>
+<span class="line"></span><span class="hljs-keyword">layout</span>(<span class="hljs-keyword">location</span> = <span class="hljs-number">0</span>) <span class="hljs-keyword">uniform</span> <span class="hljs-type">mat4</span> projectionMatrix;
+<span class="line"></span><span class="hljs-keyword">layout</span>(<span class="hljs-keyword">location</span> = <span class="hljs-number">1</span>) <span class="hljs-keyword">uniform</span> <span class="hljs-type">mat4</span> projectionInverseMatrix;
+<span class="line"></span><span class="hljs-keyword">layout</span>(<span class="hljs-keyword">location</span> = <span class="hljs-number">2</span>) <span class="hljs-keyword">uniform</span> <span class="hljs-type">vec4</span> depthParams; <span class="hljs-comment">// index scale, index bias, near, far</span>
+<span class="line"></span><span class="hljs-keyword">layout</span>(<span class="hljs-keyword">location</span> = <span class="hljs-number">3</span>) <span class="hljs-keyword">uniform</span> <span class="hljs-type">float</span> clipSpaceSize;
+<span class="line"></span>
+<span class="line"></span>struct Froxel {
+<span class="line"></span>    <span class="hljs-comment">// <span class="hljs-doctag">NOTE:</span> the planes should be stored in vec4[4] but the</span>
+<span class="line"></span>    <span class="hljs-comment">// Adreno shader compiler has a bug that causes the data</span>
+<span class="line"></span>    <span class="hljs-comment">// to not be read properly inside the loop</span>
+<span class="line"></span>    <span class="hljs-type">vec4</span> plane0;
+<span class="line"></span>    <span class="hljs-type">vec4</span> plane1;
+<span class="line"></span>    <span class="hljs-type">vec4</span> plane2;
+<span class="line"></span>    <span class="hljs-type">vec4</span> plane3;
+<span class="line"></span>    <span class="hljs-type">vec2</span> minMaxZ;
+<span class="line"></span>};
+<span class="line"></span>
+<span class="line"></span><span class="hljs-keyword">layout</span>(<span class="hljs-keyword">binding</span> = <span class="hljs-number">0</span>, <span class="hljs-keyword">std140</span>) <span class="hljs-keyword">writeonly</span> <span class="hljs-keyword">restrict</span> <span class="hljs-keyword">buffer</span> FroxelBuffer {
+<span class="line"></span>    Froxel data[];
+<span class="line"></span>} froxels;
+<span class="line"></span>
+<span class="line"></span><span class="hljs-keyword">shared</span> <span class="hljs-type">vec4</span> corners[<span class="hljs-number">4</span>];
+<span class="line"></span><span class="hljs-keyword">shared</span> <span class="hljs-type">vec2</span> minMaxZ;
+<span class="line"></span>
+<span class="line"></span><span class="hljs-type">vec4</span> projectionToView(<span class="hljs-type">vec4</span> p) {
+<span class="line"></span>    p = projectionInverseMatrix * p;
+<span class="line"></span>    <span class="hljs-keyword">return</span> p / p.w;
+<span class="line"></span>}
+<span class="line"></span>
+<span class="line"></span><span class="hljs-type">vec4</span> createPlane(<span class="hljs-type">vec4</span> b, <span class="hljs-type">vec4</span> c) {
+<span class="line"></span>    <span class="hljs-comment">// standard plane equation, with a at (0, 0, 0)</span>
+<span class="line"></span>    <span class="hljs-keyword">return</span> <span class="hljs-type">vec4</span>(<span class="hljs-built_in">normalize</span>(<span class="hljs-built_in">cross</span>(c.xyz, b.xyz)), <span class="hljs-number">1.0</span>);
+<span class="line"></span>}
+<span class="line"></span>
+<span class="line"></span><span class="hljs-type">void</span> main() {
+<span class="line"></span>    <span class="hljs-type">uint</span> <span class="hljs-keyword">index</span> = <span class="hljs-built_in">gl_WorkGroupID</span>.x + <span class="hljs-built_in">gl_WorkGroupID</span>.y * <span class="hljs-built_in">gl_NumWorkGroups</span>.x +
+<span class="line"></span>            <span class="hljs-built_in">gl_WorkGroupID</span>.z * <span class="hljs-built_in">gl_NumWorkGroups</span>.x * <span class="hljs-built_in">gl_NumWorkGroups</span>.y;
+<span class="line"></span>
+<span class="line"></span>    <span class="hljs-keyword">if</span> (<span class="hljs-built_in">gl_LocalInvocationIndex</span> == <span class="hljs-number">0</span>u) {
+<span class="line"></span>        <span class="hljs-comment">// first tile the screen and build the frustum for the current tile</span>
+<span class="line"></span>        <span class="hljs-type">vec2</span> renderTargetSize = <span class="hljs-type">vec2</span>(FROXEL_RESOLUTION * <span class="hljs-built_in">gl_NumWorkGroups</span>.xy);
+<span class="line"></span>        <span class="hljs-type">vec2</span> frustumMin = <span class="hljs-type">vec2</span>(FROXEL_RESOLUTION * <span class="hljs-built_in">gl_WorkGroupID</span>.xy);
+<span class="line"></span>        <span class="hljs-type">vec2</span> frustumMax = <span class="hljs-type">vec2</span>(FROXEL_RESOLUTION * (<span class="hljs-built_in">gl_WorkGroupID</span>.xy + <span class="hljs-number">1</span>u));
+<span class="line"></span>
+<span class="line"></span>        corners[<span class="hljs-number">0</span>] = <span class="hljs-type">vec4</span>(
+<span class="line"></span>            frustumMin.x / renderTargetSize.x * clipSpaceSize - <span class="hljs-number">1.0</span>,
+<span class="line"></span>            (renderTargetSize.y - frustumMin.y) / renderTargetSize.y
+<span class="line"></span>       * clipSpaceSize - <span class="hljs-number">1.0</span>,
+<span class="line"></span>            <span class="hljs-number">1.0</span>,
+<span class="line"></span>            <span class="hljs-number">1.0</span>
+<span class="line"></span>        );
+<span class="line"></span>        corners[<span class="hljs-number">1</span>] = <span class="hljs-type">vec4</span>(
+<span class="line"></span>            frustumMax.x / renderTargetSize.x * clipSpaceSize - <span class="hljs-number">1.0</span>,
+<span class="line"></span>            (renderTargetSize.y - frustumMin.y) / renderTargetSize.y
+<span class="line"></span>       * clipSpaceSize - <span class="hljs-number">1.0</span>,
+<span class="line"></span>            <span class="hljs-number">1.0</span>,
+<span class="line"></span>            <span class="hljs-number">1.0</span>
+<span class="line"></span>        );
+<span class="line"></span>        corners[<span class="hljs-number">2</span>] = <span class="hljs-type">vec4</span>(
+<span class="line"></span>            frustumMax.x / renderTargetSize.x * clipSpaceSize - <span class="hljs-number">1.0</span>,
+<span class="line"></span>            (renderTargetSize.y - frustumMax.y) / renderTargetSize.y
+<span class="line"></span>       * clipSpaceSize - <span class="hljs-number">1.0</span>,
+<span class="line"></span>            <span class="hljs-number">1.0</span>,
+<span class="line"></span>            <span class="hljs-number">1.0</span>
+<span class="line"></span>        );
+<span class="line"></span>        corners[<span class="hljs-number">3</span>] = <span class="hljs-type">vec4</span>(
+<span class="line"></span>            frustumMin.x / renderTargetSize.x * clipSpaceSize - <span class="hljs-number">1.0</span>,
+<span class="line"></span>            (renderTargetSize.y - frustumMax.y) / renderTargetSize.y
+<span class="line"></span>       * clipSpaceSize - <span class="hljs-number">1.0</span>,
+<span class="line"></span>            <span class="hljs-number">1.0</span>,
+<span class="line"></span>            <span class="hljs-number">1.0</span>
+<span class="line"></span>        );
+<span class="line"></span>
+<span class="line"></span>        <span class="hljs-type">uint</span> froxelSlice = <span class="hljs-built_in">gl_WorkGroupID</span>.z;
+<span class="line"></span>        minMaxZ = <span class="hljs-type">vec2</span>(<span class="hljs-number">0.0</span>, <span class="hljs-number">0.0</span>);
+<span class="line"></span>        <span class="hljs-keyword">if</span> (froxelSlice &gt; <span class="hljs-number">0</span>u) {
+<span class="line"></span>            minMaxZ.x = <span class="hljs-built_in">exp2</span>((<span class="hljs-type">float</span>(froxelSlice) - depthParams.y) * depthParams.x)
+<span class="line"></span>                    * depthParams.w;
+<span class="line"></span>        }
+<span class="line"></span>        minMaxZ.y = <span class="hljs-built_in">exp2</span>((<span class="hljs-type">float</span>(froxelSlice + <span class="hljs-number">1</span>u) - depthParams.y) * depthParams.x)
+<span class="line"></span>                * depthParams.w;
+<span class="line"></span>    }
+<span class="line"></span>
+<span class="line"></span>    <span class="hljs-keyword">if</span> (<span class="hljs-built_in">gl_LocalInvocationIndex</span> == <span class="hljs-number">0</span>u) {
+<span class="line"></span>        <span class="hljs-type">vec4</span> frustum[<span class="hljs-number">4</span>];
+<span class="line"></span>        frustum[<span class="hljs-number">0</span>] = projectionToView(corners[<span class="hljs-number">0</span>]);
+<span class="line"></span>        frustum[<span class="hljs-number">1</span>] = projectionToView(corners[<span class="hljs-number">1</span>]);
+<span class="line"></span>        frustum[<span class="hljs-number">2</span>] = projectionToView(corners[<span class="hljs-number">2</span>]);
+<span class="line"></span>        frustum[<span class="hljs-number">3</span>] = projectionToView(corners[<span class="hljs-number">3</span>]);
+<span class="line"></span>
+<span class="line"></span>        froxels.data[<span class="hljs-keyword">index</span>].plane0 = createPlane(frustum[<span class="hljs-number">0</span>], frustum[<span class="hljs-number">1</span>]);
+<span class="line"></span>        froxels.data[<span class="hljs-keyword">index</span>].plane1 = createPlane(frustum[<span class="hljs-number">1</span>], frustum[<span class="hljs-number">2</span>]);
+<span class="line"></span>        froxels.data[<span class="hljs-keyword">index</span>].plane2 = createPlane(frustum[<span class="hljs-number">2</span>], frustum[<span class="hljs-number">3</span>]);
+<span class="line"></span>        froxels.data[<span class="hljs-keyword">index</span>].plane3 = createPlane(frustum[<span class="hljs-number">3</span>], frustum[<span class="hljs-number">0</span>]);
+<span class="line"></span>        froxels.data[<span class="hljs-keyword">index</span>].minMaxZ = minMaxZ;
+<span class="line"></span>    }
+<span class="line"></span>}</code></pre><center><div class="listingcaption tilde"><b style="font-style:normal;">Listing&nbsp;48:</b> GLSL implementation of froxels data generation (compute shader)</div></center>
+<p>
+
+The second compute shader, shown in <a href="#listing_froxelevaluation" target="_self">listing&nbsp;49</a>, runs every frame (if the camera and/or lights have changed) and assigns all the lights to their respective froxels. This shader relies only on a couple of uniforms (the number of point/spot lights and the view matrix) and four SSBOs:
+</p><p>
+<dl><dt>Light index buffer</dt><dd><p>    For each froxel, the index of each light that affects said froxel. The indices for point lights are written first and if there is enough space left, the indices for spot lights are written as well. A sentinel of value 0&times;7fffffffu separates point and spot lights and/or marks the end of the froxel's list of lights. Each froxel has a maximum number of lights (point + spot).
+</p></dd><dt>Point lights buffer</dt><dd><p>    Array of structures describing the scene's point lights.
+</p></dd><dt>Spot lights buffer</dt><dd><p>    Array of structures describing the scene's spot lights.
+</p></dd><dt>Froxels buffer</dt><dd><p>    The list of froxels represented by planes, created by the previous compute shader.
+</p></dd></dl></p><a class="target" name="listing_froxelevaluation">&nbsp;</a><pre class="listing tilde"><code><span class="line"></span><span class="hljs-meta">#version 310 es</span>
+<span class="line"></span><span class="hljs-keyword">precision</span> <span class="hljs-keyword">highp</span> <span class="hljs-type">float</span>;
+<span class="line"></span><span class="hljs-keyword">precision</span> <span class="hljs-keyword">highp</span> <span class="hljs-type">int</span>;
+<span class="line"></span>
+<span class="line"></span><span class="hljs-meta">#define LIGHT_BUFFER_SENTINEL 0x7fffffffu</span>
+<span class="line"></span><span class="hljs-meta">#define MAX_FROXEL_LIGHT_COUNT 32u</span>
+<span class="line"></span>
+<span class="line"></span><span class="hljs-meta">#define THREADS_PER_FROXEL_X 8u</span>
+<span class="line"></span><span class="hljs-meta">#define THREADS_PER_FROXEL_Y 8u</span>
+<span class="line"></span><span class="hljs-meta">#define THREADS_PER_FROXEL_Z 1u</span>
+<span class="line"></span><span class="hljs-meta">#define THREADS_PER_FROXEL (THREADS_PER_FROXEL_X * \</span>
+<span class="line"></span>        THREADS_PER_FROXEL_Y * THREADS_PER_FROXEL_Z)
+<span class="line"></span>
+<span class="line"></span><span class="hljs-keyword">layout</span>(<span class="hljs-keyword">local_size_x</span> = THREADS_PER_FROXEL_X,
+<span class="line"></span>       <span class="hljs-keyword">local_size_y</span> = THREADS_PER_FROXEL_Y,
+<span class="line"></span>       <span class="hljs-keyword">local_size_z</span> = THREADS_PER_FROXEL_Z) <span class="hljs-keyword">in</span>;
+<span class="line"></span>
+<span class="line"></span><span class="hljs-comment">// x = point lights, y = spot lights</span>
+<span class="line"></span><span class="hljs-keyword">layout</span>(<span class="hljs-keyword">location</span> = <span class="hljs-number">0</span>) <span class="hljs-keyword">uniform</span> <span class="hljs-type">uvec2</span> totalLightCount;
+<span class="line"></span><span class="hljs-keyword">layout</span>(<span class="hljs-keyword">location</span> = <span class="hljs-number">1</span>) <span class="hljs-keyword">uniform</span> <span class="hljs-type">mat4</span> viewMatrix;
+<span class="line"></span>
+<span class="line"></span><span class="hljs-keyword">layout</span>(<span class="hljs-keyword">binding</span> = <span class="hljs-number">0</span>, <span class="hljs-keyword">packed</span>) <span class="hljs-keyword">writeonly</span> <span class="hljs-keyword">restrict</span> <span class="hljs-keyword">buffer</span> LightIndexBuffer {
+<span class="line"></span>    <span class="hljs-type">uint</span> <span class="hljs-keyword">index</span>[];
+<span class="line"></span>} lightIndexBuffer;
+<span class="line"></span>
+<span class="line"></span>struct PointLight {
+<span class="line"></span>    <span class="hljs-type">vec4</span> positionFalloff; <span class="hljs-comment">// x, y, z, falloff</span>
+<span class="line"></span>    <span class="hljs-type">vec4</span> colorIntensity;  <span class="hljs-comment">// r, g, b, intensity</span>
+<span class="line"></span>    <span class="hljs-type">vec4</span> directionIES;    <span class="hljs-comment">// dir x, dir y, dir z, IES profile index</span>
+<span class="line"></span>};
+<span class="line"></span>
+<span class="line"></span><span class="hljs-keyword">layout</span>(<span class="hljs-keyword">binding</span> = <span class="hljs-number">1</span>, <span class="hljs-keyword">std140</span>) <span class="hljs-keyword">readonly</span> <span class="hljs-keyword">restrict</span> <span class="hljs-keyword">buffer</span> PointLightBuffer {
+<span class="line"></span>    PointLight lights[];
+<span class="line"></span>} pointLights;
+<span class="line"></span>
+<span class="line"></span>struct SpotLight {
+<span class="line"></span>    <span class="hljs-type">vec4</span> positionFalloff; <span class="hljs-comment">// x, y, z, falloff</span>
+<span class="line"></span>    <span class="hljs-type">vec4</span> colorIntensity;  <span class="hljs-comment">// r, g, b, intensity</span>
+<span class="line"></span>    <span class="hljs-type">vec4</span> directionIES;    <span class="hljs-comment">// dir x, dir y, dir z, IES profile index</span>
+<span class="line"></span>    <span class="hljs-type">vec4</span> angle;           <span class="hljs-comment">// angle scale, angle offset, unused, unused</span>
+<span class="line"></span>};
+<span class="line"></span>
+<span class="line"></span><span class="hljs-keyword">layout</span>(<span class="hljs-keyword">binding</span> = <span class="hljs-number">2</span>, <span class="hljs-keyword">std140</span>) <span class="hljs-keyword">readonly</span> <span class="hljs-keyword">restrict</span> <span class="hljs-keyword">buffer</span> SpotLightBuffer {
+<span class="line"></span>    SpotLight lights[];
+<span class="line"></span>} spotLights;
+<span class="line"></span>
+<span class="line"></span>struct Froxel {
+<span class="line"></span>    <span class="hljs-comment">// <span class="hljs-doctag">NOTE:</span> the planes should be stored in vec4[4] but the</span>
+<span class="line"></span>    <span class="hljs-comment">// Adreno shader compiler has a bug that causes the data</span>
+<span class="line"></span>    <span class="hljs-comment">// to not be read properly inside the loop</span>
+<span class="line"></span>    <span class="hljs-type">vec4</span> plane0;
+<span class="line"></span>    <span class="hljs-type">vec4</span> plane1;
+<span class="line"></span>    <span class="hljs-type">vec4</span> plane2;
+<span class="line"></span>    <span class="hljs-type">vec4</span> plane3;
+<span class="line"></span>    <span class="hljs-type">vec2</span> minMaxZ;
+<span class="line"></span>};
+<span class="line"></span>
+<span class="line"></span><span class="hljs-keyword">layout</span>(<span class="hljs-keyword">binding</span> = <span class="hljs-number">3</span>, <span class="hljs-keyword">std140</span>) <span class="hljs-keyword">readonly</span> <span class="hljs-keyword">restrict</span> <span class="hljs-keyword">buffer</span> FroxelBuffer {
+<span class="line"></span>    Froxel data[];
+<span class="line"></span>} froxels;
+<span class="line"></span>
+<span class="line"></span><span class="hljs-keyword">shared</span> <span class="hljs-type">uint</span> groupLightCounter;
+<span class="line"></span><span class="hljs-keyword">shared</span> <span class="hljs-type">uint</span> groupLightIndexBuffer[MAX_FROXEL_LIGHT_COUNT];
+<span class="line"></span>
+<span class="line"></span><span class="hljs-type">float</span> signedDistanceFromPlane(<span class="hljs-type">vec4</span> p, <span class="hljs-type">vec4</span> plane) {
+<span class="line"></span>    <span class="hljs-comment">// plane.w == 0.0, simplify computation</span>
+<span class="line"></span>    <span class="hljs-keyword">return</span> <span class="hljs-built_in">dot</span>(plane.xyz, p.xyz);
+<span class="line"></span>}
+<span class="line"></span>
+<span class="line"></span><span class="hljs-type">void</span> synchronize() {
+<span class="line"></span>    <span class="hljs-built_in">memoryBarrierShared</span>();
+<span class="line"></span>    <span class="hljs-built_in">barrier</span>();
+<span class="line"></span>}
+<span class="line"></span>
+<span class="line"></span><span class="hljs-type">void</span> main() {
+<span class="line"></span>    <span class="hljs-keyword">if</span> (<span class="hljs-built_in">gl_LocalInvocationIndex</span> == <span class="hljs-number">0</span>u) {
+<span class="line"></span>        groupLightCounter = <span class="hljs-number">0</span>u;
+<span class="line"></span>    }
+<span class="line"></span>    <span class="hljs-built_in">memoryBarrierShared</span>();
+<span class="line"></span>
+<span class="line"></span>    <span class="hljs-type">uint</span> froxelIndex = <span class="hljs-built_in">gl_WorkGroupID</span>.x + <span class="hljs-built_in">gl_WorkGroupID</span>.y * <span class="hljs-built_in">gl_NumWorkGroups</span>.x +
+<span class="line"></span>            <span class="hljs-built_in">gl_WorkGroupID</span>.z * <span class="hljs-built_in">gl_NumWorkGroups</span>.x * <span class="hljs-built_in">gl_NumWorkGroups</span>.y;
+<span class="line"></span>    Froxel current = froxels.data[froxelIndex];
+<span class="line"></span>
+<span class="line"></span>    <span class="hljs-type">uint</span> <span class="hljs-keyword">offset</span> = <span class="hljs-built_in">gl_LocalInvocationID</span>.x +
+<span class="line"></span>         <span class="hljs-built_in">gl_LocalInvocationID</span>.y * THREADS_PER_FROXEL_X;
+<span class="line"></span>    <span class="hljs-keyword">for</span> (<span class="hljs-type">uint</span> i = <span class="hljs-number">0</span>u; i &lt; totalLightCount.x &amp;&amp;
+<span class="line"></span>      groupLightCounter &lt; MAX_FROXEL_LIGHT_COUNT &amp;&amp;
+<span class="line"></span>            <span class="hljs-keyword">offset</span> + i &lt; totalLightCount.x; i += THREADS_PER_FROXEL) {
+<span class="line"></span>
+<span class="line"></span>        <span class="hljs-type">uint</span> currentLight = <span class="hljs-keyword">offset</span> + i;
+<span class="line"></span>
+<span class="line"></span>        <span class="hljs-type">vec4</span> center = pointLights.lights[currentLight].positionFalloff;
+<span class="line"></span>        center.xyz = (viewMatrix * <span class="hljs-type">vec4</span>(center.xyz, <span class="hljs-number">1.0</span>)).xyz;
+<span class="line"></span>        <span class="hljs-type">float</span> r = <span class="hljs-built_in">inversesqrt</span>(center.w);
+<span class="line"></span>
+<span class="line"></span>        <span class="hljs-keyword">if</span> (-center.z + r &gt; current.minMaxZ.x &amp;&amp;
+<span class="line"></span>                -center.z - r &lt;= current.minMaxZ.y) {
+<span class="line"></span>            <span class="hljs-keyword">if</span> (signedDistanceFromPlane(center, current.plane0) &lt; r &amp;&amp;
+<span class="line"></span>                signedDistanceFromPlane(center, current.plane1) &lt; r &amp;&amp;
+<span class="line"></span>                signedDistanceFromPlane(center, current.plane2) &lt; r &amp;&amp;
+<span class="line"></span>                signedDistanceFromPlane(center, current.plane3) &lt; r) {
+<span class="line"></span>
+<span class="line"></span>                <span class="hljs-type">uint</span> <span class="hljs-keyword">index</span> = <span class="hljs-built_in">atomicAdd</span>(groupLightCounter, <span class="hljs-number">1</span>u);
+<span class="line"></span>                groupLightIndexBuffer[<span class="hljs-keyword">index</span>] = currentLight;
+<span class="line"></span>            }
+<span class="line"></span>        }
+<span class="line"></span>    }
+<span class="line"></span>
+<span class="line"></span>    synchronize();
+<span class="line"></span>
+<span class="line"></span>    <span class="hljs-type">uint</span> pointLightCount = groupLightCounter;
+<span class="line"></span>    <span class="hljs-keyword">offset</span> = froxelIndex * MAX_FROXEL_LIGHT_COUNT;
+<span class="line"></span>
+<span class="line"></span>    <span class="hljs-keyword">for</span> (<span class="hljs-type">uint</span> i = <span class="hljs-built_in">gl_LocalInvocationIndex</span>; i &lt; pointLightCount;
+<span class="line"></span>            i += THREADS_PER_FROXEL) {
+<span class="line"></span>        lightIndexBuffer.<span class="hljs-keyword">index</span>[<span class="hljs-keyword">offset</span> + i] = groupLightIndexBuffer[i];
+<span class="line"></span>    }
+<span class="line"></span>
+<span class="line"></span>    <span class="hljs-keyword">if</span> (<span class="hljs-built_in">gl_LocalInvocationIndex</span> == <span class="hljs-number">0</span>u) {
+<span class="line"></span>        <span class="hljs-keyword">if</span> (pointLightCount &lt; MAX_FROXEL_LIGHT_COUNT) {
+<span class="line"></span>            lightIndexBuffer.<span class="hljs-keyword">index</span>[<span class="hljs-keyword">offset</span> + pointLightCount] = LIGHT_BUFFER_SENTINEL;
+<span class="line"></span>        }
+<span class="line"></span>    }
+<span class="line"></span>}</code></pre><center><div class="listingcaption tilde"><b style="font-style:normal;">Listing&nbsp;49:</b> GLSL implementation of assigning lights to froxels (compute shader)</div></center>
+<a class="target" name="revisions">&nbsp;</a><a class="target" name="revisions">&nbsp;</a><a class="target" name="toc10">&nbsp;</a><h1>Revisions</h1>
+<p>
+
+<table class="schedule"><tr valign="top"><td style="width:100px;padding-right:15px" rowspan="2"><a class="target" name="schedule1_2018-8-3">&nbsp;</a>Friday<br/>3&nbsp;August&nbsp;2018</td><td><b>First public version</b></td></tr><tr valign="top"><td style="padding-bottom:25px">
+</p><p>
+</td></tr><tr valign="top"><td style="width:100px;padding-right:15px" rowspan="2"><a class="target" name="schedule1_2018-8-7">&nbsp;</a>Tuesday<br/>7&nbsp;August&nbsp;2018</td><td><b>Cloth model</b></td></tr><tr valign="top"><td style="padding-bottom:25px">
+</p><p>
+<ul>
+ <li class="minus">Added description of the &ldquo;Charlie&rdquo; NDF</li></ul>
+</p><p>
+</td></tr><tr valign="top"><td style="width:100px;padding-right:15px" rowspan="2"><a class="target" name="schedule1_2018-8-9">&nbsp;</a>Thursday<br/>9&nbsp;August&nbsp;2018</td><td><b>Lighting</b></td></tr><tr valign="top"><td style="padding-bottom:25px">
+</p><p>
+<ul>
+ <li class="minus">Added explanation about pre-exposed lights</li></ul>
+</p><p>
+</td></tr><tr valign="top"><td style="width:100px;padding-right:15px" rowspan="2"><a class="target" name="schedule1_2018-8-15">&nbsp;</a>Wednesday<br/>15&nbsp;August&nbsp;2018</td><td><b>Fresnel</b></td></tr><tr valign="top"><td style="padding-bottom:25px">
+</p><p>
+<ul>
+ <li class="minus">Added a description of the Fresnel effect in section <a href="#toc4.4.3" target="_self">4.4.3</a></li></ul>
+</p><p>
+</td></tr><tr valign="top"><td style="width:100px;padding-right:15px" rowspan="2"><a class="target" name="schedule1_2018-8-17">&nbsp;</a>Friday<br/>17&nbsp;August&nbsp;2018</td><td><b>Specular color</b></td></tr><tr valign="top"><td style="padding-bottom:25px">
+</p><p>
+<ul>
+ <li class="minus">Added section <a href="#toc9.1" target="_self">9.1</a> to explain how the base color of various metals is computed</li></ul>
+</p><p>
+</td></tr><tr valign="top"><td style="width:100px;padding-right:15px" rowspan="2"><a class="target" name="schedule1_2018-8-21">&nbsp;</a>Tuesday<br/>21&nbsp;August&nbsp;2018</td><td><b>Multiscattering</b></td></tr><tr valign="top"><td style="padding-bottom:25px">
+</p><p>
+<ul>
+ <li class="minus">Added section <a href="#toc4.7.2" target="_self">4.7.2</a> on how to compensate for energy loss in single scattering BRDFs</li></ul>
+</p><p>
+</td></tr><tr valign="top"><td style="width:100px;padding-right:15px" rowspan="2"><a class="target" name="schedule1_2019-2-20">&nbsp;</a>Wednesday<br/>20&nbsp;February&nbsp;2019</td><td><b>Cloth shading</b></td></tr><tr valign="top"><td style="padding-bottom:25px">
+</p><p>
+<ul>
+ <li class="minus">Removed Fresnel term from the cloth BRDF
+</li>
+ <li class="minus">Removed cloth DFG approximations, replaced with a new channel in the DFG LUT</li></ul>
+</p><p>
+</td></tr></table>
+</p>
+<a class="target" name="bibliography">&nbsp;</a><a class="target" name="bibliography">&nbsp;</a><a class="target" name="toc11">&nbsp;</a><h1>Bibliography</h1>
+<p>
+<div class="bib">[<a class="target" name="citation-ashdown98">&nbsp;</a><b>Ashdown98</b>] Ian Ashdown. 1998. Parsing the IESNA LM-63 photometric data file. <a href="http://lumen.iee.put.poznan.pl/kw/iesna.txt" class="url">http://lumen.iee.put.poznan.pl/kw/iesna.txt</a>
+</div><div class="bib">[<a class="target" name="citation-ashikhmin00">&nbsp;</a><b>Ashikhmin00</b>] Michael Ashikhmin, Simon Premoze and Peter Shirley. A Microfacet-based BRDF Generator. <em class="asterisk">SIGGRAPH '00 Proceedings</em>, 65-74.
+</div><div class="bib">[<a class="target" name="citation-ashikhmin07">&nbsp;</a><b>Ashikhmin07</b>] Michael Ashikhmin and Simon Premoze. 2007. Distribution-based BRDFs.
+</div><div class="bib">[<a class="target" name="citation-burley12">&nbsp;</a><b>Burley12</b>] Brent Burley. 2012. Physically Based Shading at Disney. <em class="asterisk">Physically Based Shading in Film and Game Production, ACM SIGGRAPH 2012 Courses</em>.
+</div><div class="bib">[<a class="target" name="citation-estevez17">&nbsp;</a><b>Estevez17</b>] Alejandro Conty Estevez and Christopher Kulla. 2017. Production Friendly Microfacet Sheen BRDF. <em class="asterisk">ACM SIGGRAPH 2017</em>.
+</div><div class="bib">[<a class="target" name="citation-hammon17">&nbsp;</a><b>Hammon17</b>] Earl Hammon. 217. PBR Diffuse Lighting for GGX+Smith Microsurfaces. <em class="asterisk">GDC 2017</em>.
+</div><div class="bib">[<a class="target" name="citation-heitz14">&nbsp;</a><b>Heitz14</b>] Eric Heitz. 2014. Understanding the Masking-Shadowing Function
+in Microfacet-Based BRDFs. <em class="asterisk">Journal of Computer Graphics Techniques</em>, 3 (2).
+</div><div class="bib">[<a class="target" name="citation-heitz16">&nbsp;</a><b>Heitz16</b>] Eric Heitz et al. 2016. Multiple-Scattering Microfacet BSDFs with the Smith Model. <em class="asterisk">ACM SIGGRAPH 2016</em>.
+</div><div class="bib">[<a class="target" name="citation-hill12">&nbsp;</a><b>Hill12</b>] Colin Barré-Brisebois and Stephen Hill. 2012. Blending in Detail. <a href="http://blog.selfshadow.com/publications/blending-in-detail/" class="url">http://blog.selfshadow.com/publications/blending-in-detail/</a>
+</div><div class="bib">[<a class="target" name="citation-karis13a">&nbsp;</a><b>Karis13a</b>] Brian Karis. 2013. Specular BRDF Reference. <a href="http://graphicrants.blogspot.com/2013/08/specular-brdf-reference.html" class="url">http://graphicrants.blogspot.com/2013/08/specular-brdf-reference.html</a>
+</div><div class="bib">[<a class="target" name="citation-karis13b">&nbsp;</a><b>Karis13b</b>] Brian Karis, 2013. Real Shading in Unreal Engine 4. <a href="https://blog.selfshadow.com/publications/s2013-shading-course/karis/s2013_pbs_epic_notes_v2.pdf" class="url">https://blog.selfshadow.com/publications/s2013-shading-course/karis/s2013_pbs_epic_notes_v2.pdf</a>
+</div><div class="bib">[<a class="target" name="citation-karis14">&nbsp;</a><b>Karis14</b>] Brian Karis. 2014. Physically Based Shading on Mobile. <a href="https://www.unrealengine.com/blog/physically-based-shading-on-mobile" class="url">https://www.unrealengine.com/blog/physically-based-shading-on-mobile</a>
+</div><div class="bib">[<a class="target" name="citation-kelemen01">&nbsp;</a><b>Kelemen01</b>] Csaba Kelemen et al. 2001. A Microfacet Based Coupled Specular-Matte BRDF Model with Importance Sampling. <em class="asterisk">Eurographics Short Presentations</em>.
+</div><div class="bib">[<a class="target" name="citation-krystek85">&nbsp;</a><b>Krystek85</b>] M. Krystek. 1985. An algorithm to calculate correlated color temperature. <em class="asterisk">Color Research & Application</em>, 10 (1), 38–40.
+</div><div class="bib">[<a class="target" name="citation-krivanek08">&nbsp;</a><b>Krivanek08</b>] Jaroslave Krivànek and Mark Colbert. 2008. Real-time Shading with Filtered Importance Sampling. <em class="asterisk">Eurographics Symposium on Rendering 2008</em>, Volume 27, Number 4.
+</div><div class="bib">[<a class="target" name="citation-kulla17">&nbsp;</a><b>Kulla17</b>] Christopher Kulla and Alejandro Conty. 2017. Revisiting Physically Based Shading at Imageworks. <em class="asterisk">ACM SIGGRAPH 2017</em>
+</div><div class="bib">[<a class="target" name="citation-lagarde14">&nbsp;</a><b>Lagarde14</b>] Sébastien Lagarde and Charles de Rousiers. 2014. Moving Frostbite to PBR. <em class="asterisk">Physically Based Shading in Theory and Practice, ACM SIGGRAPH 2014 Courses</em>.
+</div><div class="bib">[<a class="target" name="citation-lagarde18">&nbsp;</a><b>Lagarde18</b>] Sébastien Lagarde and Evgenii Golubev. 2018. The road toward unified rendering with Unity’s high definition rendering pipeline. <em class="asterisk">Advances in Real-Time Rendering in Games, ACM SIGGRAPH 2018 Courses</em>.
+</div><div class="bib">[<a class="target" name="citation-lazarov13">&nbsp;</a><b>Lazarov13</b>] Dimitar Lazarov. 2013. Physically-Based Shading in Call of Duty: Black Ops. <em class="asterisk">Physically Based Shading in Theory and Practice, ACM SIGGRAPH 2013 Courses</em>.
+</div><div class="bib">[<a class="target" name="citation-mcauley15">&nbsp;</a><b>McAuley15</b>] Stephen McAuley. 2015. Rendering the World of Far Cry 4. <em class="asterisk">GDC 2015</em>.
+</div><div class="bib">[<a class="target" name="citation-mcguire10">&nbsp;</a><b>McGuire10</b>] Morgan McGuire. 2010. Ambient Occlusion Volumes. <em class="asterisk">High Performance Graphics</em>.
+</div><div class="bib">[<a class="target" name="citation-narkowicz14">&nbsp;</a><b>Narkowicz14</b>] Krzysztof Narkowicz. 2014. Analytical DFG Term for IBL. <a href="https://knarkowicz.wordpress.com/2014/12/27/analytical-dfg-term-for-ibl" class="url">https://knarkowicz.wordpress.com/2014/12/27/analytical-dfg-term-for-ibl</a>
+</div><div class="bib">[<a class="target" name="citation-neubelt13">&nbsp;</a><b>Neubelt13</b>] David Neubelt and Matt Pettineo. 2013. Crafting a Next-Gen Material Pipeline for The Order: 1886. <em class="asterisk">Physically Based Shading in Theory and Practice, ACM SIGGRAPH 2013 Courses</em>.
+</div><div class="bib">[<a class="target" name="citation-oren94">&nbsp;</a><b>Oren94</b>] Michael Oren and Shree K. Nayar. 1994. Generalization of lambert's reflectance model. <em class="asterisk">SIGGRAPH</em>, 239–246. ACM.
+</div><div class="bib">[<a class="target" name="citation-pattanaik00">&nbsp;</a><b>Pattanaik00</b>] Sumanta Pattanaik00 et al. 2000. Time-Dependent Visual Adaptation
+For Fast Realistic Image Display. <em class="asterisk">SIGGRAPH '00 Proceedings of the 27th annual conference on Computer graphics and interactive techniques</em>, 47-54.
+</div><div class="bib">[<a class="target" name="citation-ramamoorthi01">&nbsp;</a><b>Ramamoorthi01</b>] Ravi Ramamoorthi and Pat Hanrahan. 2001. On the relationship between radiance and irradiance: determining the illumination from images of a convex Lambertian object. <em class="asterisk">Journal of the Optical Society of America</em>, Volume 18, Number 10, October 2001.
+</div><div class="bib">[<a class="target" name="citation-revie12">&nbsp;</a><b>Revie12</b>] Donald Revie. 2012.  Implementing Fur in Deferred Shading. <em class="asterisk">GPU Pro 2</em>, Chapter 2.
+</div><div class="bib">[<a class="target" name="citation-russell15">&nbsp;</a><b>Russell15</b>] Jeff Russell. 2015. Horizon Occlusion for Normal Mapped Reflections. <a href="http://marmosetco.tumblr.com/post/81245981087" class="url">http://marmosetco.tumblr.com/post/81245981087</a>
+</div><div class="bib">[<a class="target" name="citation-schlick94">&nbsp;</a><b>Schlick94</b>] Christophe Schlick. 1994. An Inexpensive BRDF Model for Physically-Based Rendering. <em class="asterisk">Computer Graphics Forum</em>, 13 (3), 233–246.
+</div><div class="bib">[<a class="target" name="citation-walter07">&nbsp;</a><b>Walter07</b>] Bruce Walter et al. 2007. Microfacet Models for Refraction through Rough Surfaces. <em class="asterisk">Proceedings of the Eurographics Symposium on Rendering</em>.
+</div>
+</sample></float></sample></float></float></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&nbsp;1.18&nbsp;&nbsp;</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);">&#x2712;</div></div><script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.6/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
\ No newline at end of file
diff --git a/docs_src/src/main/materials.md b/docs_src/src/main/materials.md
new file mode 100644
index 00000000000..fd09d3438b2
--- /dev/null
+++ b/docs_src/src/main/materials.md
@@ -0,0 +1,2471 @@
+<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">
+<style>img { max-width: 100%; }</style>
+<script type="text/x-mathjax-config">MathJax.Hub.Config({ TeX: { equationNumbers: {autoNumber: "AMS"} } });</script><span style="display:none">$$\newcommand{\n}{\hat{n}}\newcommand{\thetai}{\theta_\mathrm{i}}\newcommand{\thetao}{\theta_\mathrm{o}}\newcommand{\d}[1]{\mathrm{d}#1}\newcommand{\w}{\hat{\omega}}\newcommand{\wi}{\w_\mathrm{i}}\newcommand{\wo}{\w_\mathrm{o}}\newcommand{\wh}{\w_\mathrm{h}}\newcommand{\Li}{L_\mathrm{i}}\newcommand{\Lo}{L_\mathrm{o}}\newcommand{\Le}{L_\mathrm{e}}\newcommand{\Lr}{L_\mathrm{r}}\newcommand{\Lt}{L_\mathrm{t}}\newcommand{\O}{\mathrm{O}}\newcommand{\degrees}{{^{\large\circ}}}\newcommand{\T}{\mathsf{T}}\newcommand{\mathset}[1]{\mathbb{#1}}\newcommand{\Real}{\mathset{R}}\newcommand{\Integer}{\mathset{Z}}\newcommand{\Boolean}{\mathset{B}}\newcommand{\Complex}{\mathset{C}}\newcommand{\un}[1]{\,\mathrm{#1}}$$
+</span>
+<span class="md"><p><title>Filament Materials Guide</title><div class="title"> Filament Materials Guide </div>
+<div class="afterTitles"></div>
+</p><p>
+<center><a href="../images/filament_logo.png" target="_blank"><img class="markdeep" src="../images/filament_logo.png" /></a></center>
+</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&nbsp; </span>About</a><br/>
+&nbsp;&nbsp;<a href="#about/authors"  target="_self" class="level2"><span class="tocNumber">1.1&nbsp; </span>Authors</a><br/>
+<a href="#overview"  target="_self" class="level1"><span class="tocNumber">2&nbsp; </span>Overview</a><br/>
+&nbsp;&nbsp;<a href="#overview/coreconcepts"  target="_self" class="level2"><span class="tocNumber">2.1&nbsp; </span>Core concepts</a><br/>
+<a href="#materialmodels"  target="_self" class="level1"><span class="tocNumber">3&nbsp; </span>Material models</a><br/>
+&nbsp;&nbsp;<a href="#materialmodels/litmodel"  target="_self" class="level2"><span class="tocNumber">3.1&nbsp; </span>Lit model</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialmodels/litmodel/basecolor"  target="_self" class="level3"><span class="tocNumber">3.1.1&nbsp; </span>Base color</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialmodels/litmodel/metallic"  target="_self" class="level3"><span class="tocNumber">3.1.2&nbsp; </span>Metallic</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialmodels/litmodel/roughness"  target="_self" class="level3"><span class="tocNumber">3.1.3&nbsp; </span>Roughness</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialmodels/litmodel/non-metals"  target="_self" class="level3"><span class="tocNumber">3.1.4&nbsp; </span>Non-metals</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialmodels/litmodel/metals"  target="_self" class="level3"><span class="tocNumber">3.1.5&nbsp; </span>Metals</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialmodels/litmodel/refraction"  target="_self" class="level3"><span class="tocNumber">3.1.6&nbsp; </span>Refraction</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialmodels/litmodel/reflectance"  target="_self" class="level3"><span class="tocNumber">3.1.7&nbsp; </span>Reflectance</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialmodels/litmodel/sheencolor"  target="_self" class="level3"><span class="tocNumber">3.1.8&nbsp; </span>Sheen color</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialmodels/litmodel/sheenroughness"  target="_self" class="level3"><span class="tocNumber">3.1.9&nbsp; </span>Sheen roughness</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialmodels/litmodel/clearcoat"  target="_self" class="level3"><span class="tocNumber">3.1.10&nbsp; </span>Clear coat</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialmodels/litmodel/clearcoatroughness"  target="_self" class="level3"><span class="tocNumber">3.1.11&nbsp; </span>Clear coat roughness</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialmodels/litmodel/anisotropy"  target="_self" class="level3"><span class="tocNumber">3.1.12&nbsp; </span>Anisotropy</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialmodels/litmodel/anisotropydirection"  target="_self" class="level3"><span class="tocNumber">3.1.13&nbsp; </span>Anisotropy direction</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialmodels/litmodel/ambientocclusion"  target="_self" class="level3"><span class="tocNumber">3.1.14&nbsp; </span>Ambient occlusion</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialmodels/litmodel/normal"  target="_self" class="level3"><span class="tocNumber">3.1.15&nbsp; </span>Normal</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialmodels/litmodel/bentnormal"  target="_self" class="level3"><span class="tocNumber">3.1.16&nbsp; </span>Bent normal</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialmodels/litmodel/clearcoatnormal"  target="_self" class="level3"><span class="tocNumber">3.1.17&nbsp; </span>Clear coat normal</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialmodels/litmodel/emissive"  target="_self" class="level3"><span class="tocNumber">3.1.18&nbsp; </span>Emissive</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialmodels/litmodel/post-lightingcolor"  target="_self" class="level3"><span class="tocNumber">3.1.19&nbsp; </span>Post-lighting color</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialmodels/litmodel/indexofrefraction"  target="_self" class="level3"><span class="tocNumber">3.1.20&nbsp; </span>Index of refraction</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialmodels/litmodel/transmission"  target="_self" class="level3"><span class="tocNumber">3.1.21&nbsp; </span>Transmission</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialmodels/litmodel/absorption"  target="_self" class="level3"><span class="tocNumber">3.1.22&nbsp; </span>Absorption</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialmodels/litmodel/micro-thicknessandthickness"  target="_self" class="level3"><span class="tocNumber">3.1.23&nbsp; </span>Micro-thickness and thickness</a><br/>
+&nbsp;&nbsp;<a href="#materialmodels/subsurfacemodel"  target="_self" class="level2"><span class="tocNumber">3.2&nbsp; </span>Subsurface model</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialmodels/subsurfacemodel/thickness"  target="_self" class="level3"><span class="tocNumber">3.2.1&nbsp; </span>Thickness</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialmodels/subsurfacemodel/subsurfacecolor"  target="_self" class="level3"><span class="tocNumber">3.2.2&nbsp; </span>Subsurface color</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialmodels/subsurfacemodel/subsurfacepower"  target="_self" class="level3"><span class="tocNumber">3.2.3&nbsp; </span>Subsurface power</a><br/>
+&nbsp;&nbsp;<a href="#materialmodels/clothmodel"  target="_self" class="level2"><span class="tocNumber">3.3&nbsp; </span>Cloth model</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialmodels/clothmodel/sheencolor"  target="_self" class="level3"><span class="tocNumber">3.3.1&nbsp; </span>Sheen color</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialmodels/clothmodel/subsurfacecolor"  target="_self" class="level3"><span class="tocNumber">3.3.2&nbsp; </span>Subsurface color</a><br/>
+&nbsp;&nbsp;<a href="#materialmodels/unlitmodel"  target="_self" class="level2"><span class="tocNumber">3.4&nbsp; </span>Unlit model</a><br/>
+&nbsp;&nbsp;<a href="#materialmodels/specularglossiness"  target="_self" class="level2"><span class="tocNumber">3.5&nbsp; </span>Specular glossiness</a><br/>
+<a href="#materialdefinitions"  target="_self" class="level1"><span class="tocNumber">4&nbsp; </span>Material definitions</a><br/>
+&nbsp;&nbsp;<a href="#materialdefinitions/format"  target="_self" class="level2"><span class="tocNumber">4.1&nbsp; </span>Format</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/format/differenceswithjson"  target="_self" class="level3"><span class="tocNumber">4.1.1&nbsp; </span>Differences with JSON</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/format/example"  target="_self" class="level3"><span class="tocNumber">4.1.2&nbsp; </span>Example</a><br/>
+&nbsp;&nbsp;<a href="#materialdefinitions/materialblock"  target="_self" class="level2"><span class="tocNumber">4.2&nbsp; </span>Material block</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/general:name"  target="_self" class="level3"><span class="tocNumber">4.2.1&nbsp; </span>General: name</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/general:featurelevel"  target="_self" class="level3"><span class="tocNumber">4.2.2&nbsp; </span>General: featureLevel</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/general:shadingmodel"  target="_self" class="level3"><span class="tocNumber">4.2.3&nbsp; </span>General: shadingModel</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/general:parameters"  target="_self" class="level3"><span class="tocNumber">4.2.4&nbsp; </span>General: parameters</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/general:constants"  target="_self" class="level3"><span class="tocNumber">4.2.5&nbsp; </span>General: constants</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/general:variantfilter"  target="_self" class="level3"><span class="tocNumber">4.2.6&nbsp; </span>General: variantFilter</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/general:flipuv"  target="_self" class="level3"><span class="tocNumber">4.2.7&nbsp; </span>General: flipUV</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/general:quality"  target="_self" class="level3"><span class="tocNumber">4.2.8&nbsp; </span>General: quality</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/general:instanced"  target="_self" class="level3"><span class="tocNumber">4.2.9&nbsp; </span>General: instanced</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/general:vertexdomaindevicejittered"  target="_self" class="level3"><span class="tocNumber">4.2.10&nbsp; </span>General: vertexDomainDeviceJittered</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/vertexandattributes:requires"  target="_self" class="level3"><span class="tocNumber">4.2.11&nbsp; </span>Vertex and attributes: requires</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/vertexandattributes:variables"  target="_self" class="level3"><span class="tocNumber">4.2.12&nbsp; </span>Vertex and attributes: variables</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/vertexandattributes:vertexdomain"  target="_self" class="level3"><span class="tocNumber">4.2.13&nbsp; </span>Vertex and attributes: vertexDomain</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/vertexandattributes:interpolation"  target="_self" class="level3"><span class="tocNumber">4.2.14&nbsp; </span>Vertex and attributes: interpolation</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/blendingandtransparency:blending"  target="_self" class="level3"><span class="tocNumber">4.2.15&nbsp; </span>Blending and transparency: blending</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/blendingandtransparency:blendfunction"  target="_self" class="level3"><span class="tocNumber">4.2.16&nbsp; </span>Blending and transparency: blendFunction</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/blendingandtransparency:postlightingblending"  target="_self" class="level3"><span class="tocNumber">4.2.17&nbsp; </span>Blending and transparency: postLightingBlending</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/blendingandtransparency:transparency"  target="_self" class="level3"><span class="tocNumber">4.2.18&nbsp; </span>Blending and transparency: transparency</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/blendingandtransparency:maskthreshold"  target="_self" class="level3"><span class="tocNumber">4.2.19&nbsp; </span>Blending and transparency: maskThreshold</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/blendingandtransparency:refractionmode"  target="_self" class="level3"><span class="tocNumber">4.2.20&nbsp; </span>Blending and transparency: refractionMode</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/blendingandtransparency:refractiontype"  target="_self" class="level3"><span class="tocNumber">4.2.21&nbsp; </span>Blending and transparency: refractionType</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/rasterization:culling"  target="_self" class="level3"><span class="tocNumber">4.2.22&nbsp; </span>Rasterization: culling</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/rasterization:colorwrite"  target="_self" class="level3"><span class="tocNumber">4.2.23&nbsp; </span>Rasterization: colorWrite</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/rasterization:depthwrite"  target="_self" class="level3"><span class="tocNumber">4.2.24&nbsp; </span>Rasterization: depthWrite</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/rasterization:depthculling"  target="_self" class="level3"><span class="tocNumber">4.2.25&nbsp; </span>Rasterization: depthCulling</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/rasterization:doublesided"  target="_self" class="level3"><span class="tocNumber">4.2.26&nbsp; </span>Rasterization: doubleSided</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/rasterization:alphatocoverage"  target="_self" class="level3"><span class="tocNumber">4.2.27&nbsp; </span>Rasterization: alphaToCoverage</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/lighting:reflections"  target="_self" class="level3"><span class="tocNumber">4.2.28&nbsp; </span>Lighting: reflections</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/lighting:shadowmultiplier"  target="_self" class="level3"><span class="tocNumber">4.2.29&nbsp; </span>Lighting: shadowMultiplier</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/lighting:transparentshadow"  target="_self" class="level3"><span class="tocNumber">4.2.30&nbsp; </span>Lighting: transparentShadow</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/lighting:clearcoatiorchange"  target="_self" class="level3"><span class="tocNumber">4.2.31&nbsp; </span>Lighting: clearCoatIorChange</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/lighting:multibounceambientocclusion"  target="_self" class="level3"><span class="tocNumber">4.2.32&nbsp; </span>Lighting: multiBounceAmbientOcclusion</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/lighting:specularambientocclusion"  target="_self" class="level3"><span class="tocNumber">4.2.33&nbsp; </span>Lighting: specularAmbientOcclusion</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/anti-aliasing:specularantialiasing"  target="_self" class="level3"><span class="tocNumber">4.2.34&nbsp; </span>Anti-aliasing: specularAntiAliasing</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/anti-aliasing:specularantialiasingvariance"  target="_self" class="level3"><span class="tocNumber">4.2.35&nbsp; </span>Anti-aliasing: specularAntiAliasingVariance</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/anti-aliasing:specularantialiasingthreshold"  target="_self" class="level3"><span class="tocNumber">4.2.36&nbsp; </span>Anti-aliasing: specularAntiAliasingThreshold</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/shading:customsurfaceshading"  target="_self" class="level3"><span class="tocNumber">4.2.37&nbsp; </span>Shading: customSurfaceShading</a><br/>
+&nbsp;&nbsp;<a href="#materialdefinitions/vertexblock"  target="_self" class="level2"><span class="tocNumber">4.3&nbsp; </span>Vertex block</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/vertexblock/materialvertexinputs"  target="_self" class="level3"><span class="tocNumber">4.3.1&nbsp; </span>Material vertex inputs</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/vertexblock/customvertexattributes"  target="_self" class="level3"><span class="tocNumber">4.3.2&nbsp; </span>Custom vertex attributes</a><br/>
+&nbsp;&nbsp;<a href="#materialdefinitions/fragmentblock"  target="_self" class="level2"><span class="tocNumber">4.4&nbsp; </span>Fragment block</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/fragmentblock/preparematerialfunction"  target="_self" class="level3"><span class="tocNumber">4.4.1&nbsp; </span>prepareMaterial function</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/fragmentblock/materialfragmentinputs"  target="_self" class="level3"><span class="tocNumber">4.4.2&nbsp; </span>Material fragment inputs</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/fragmentblock/customsurfaceshading"  target="_self" class="level3"><span class="tocNumber">4.4.3&nbsp; </span>Custom surface shading</a><br/>
+&nbsp;&nbsp;<a href="#materialdefinitions/shaderpublicapis"  target="_self" class="level2"><span class="tocNumber">4.5&nbsp; </span>Shader public APIs</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/shaderpublicapis/types"  target="_self" class="level3"><span class="tocNumber">4.5.1&nbsp; </span>Types</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/shaderpublicapis/math"  target="_self" class="level3"><span class="tocNumber">4.5.2&nbsp; </span>Math</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/shaderpublicapis/matrices"  target="_self" class="level3"><span class="tocNumber">4.5.3&nbsp; </span>Matrices</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/shaderpublicapis/frameconstants"  target="_self" class="level3"><span class="tocNumber">4.5.4&nbsp; </span>Frame constants</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/shaderpublicapis/materialglobals"  target="_self" class="level3"><span class="tocNumber">4.5.5&nbsp; </span>Material globals</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/shaderpublicapis/vertexonly"  target="_self" class="level3"><span class="tocNumber">4.5.6&nbsp; </span>Vertex only</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/shaderpublicapis/fragmentonly"  target="_self" class="level3"><span class="tocNumber">4.5.7&nbsp; </span>Fragment only</a><br/>
+<a href="#compilingmaterials"  target="_self" class="level1"><span class="tocNumber">5&nbsp; </span>Compiling materials</a><br/>
+&nbsp;&nbsp;<a href="#compilingmaterials/shadervalidation"  target="_self" class="level2"><span class="tocNumber">5.1&nbsp; </span>Shader validation</a><br/>
+&nbsp;&nbsp;<a href="#compilingmaterials/flags"  target="_self" class="level2"><span class="tocNumber">5.2&nbsp; </span>Flags</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#compilingmaterials/flags/&mdash;platform"  target="_self" class="level3"><span class="tocNumber">5.2.1&nbsp; </span>&mdash;platform</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#compilingmaterials/flags/&mdash;api"  target="_self" class="level3"><span class="tocNumber">5.2.2&nbsp; </span>&mdash;api</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#compilingmaterials/flags/&mdash;optimize-size"  target="_self" class="level3"><span class="tocNumber">5.2.3&nbsp; </span>&mdash;optimize-size</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#compilingmaterials/flags/&mdash;reflect"  target="_self" class="level3"><span class="tocNumber">5.2.4&nbsp; </span>&mdash;reflect</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#compilingmaterials/flags/&mdash;variant-filter"  target="_self" class="level3"><span class="tocNumber">5.2.5&nbsp; </span>&mdash;variant-filter</a><br/>
+<a href="#handlingcolors"  target="_self" class="level1"><span class="tocNumber">6&nbsp; </span>Handling colors</a><br/>
+&nbsp;&nbsp;<a href="#handlingcolors/linearcolors"  target="_self" class="level2"><span class="tocNumber">6.1&nbsp; </span>Linear colors</a><br/>
+&nbsp;&nbsp;<a href="#handlingcolors/pre-multipliedalpha"  target="_self" class="level2"><span class="tocNumber">6.2&nbsp; </span>Pre-multiplied alpha</a><br/>
+<a href="#samplerusageinmaterials"  target="_self" class="level1"><span class="tocNumber">7&nbsp; </span>Sampler usage in Materials</a><br/>
+&nbsp;&nbsp;<a href="#samplerusageinmaterials/featurelevel1and2"  target="_self" class="level2"><span class="tocNumber">7.1&nbsp; </span>Feature level 1 and 2</a><br/>
+&nbsp;&nbsp;<a href="#samplerusageinmaterials/featurelevel3"  target="_self" class="level2"><span class="tocNumber">7.2&nbsp; </span>Feature level 3</a><br/>
+</p></div><a class="target" name="about">&nbsp;</a><a class="target" name="about">&nbsp;</a><a class="target" name="toc1">&nbsp;</a><h1>About</h1>
+<p>
+
+This document is part of the <a href="https://github.com/google/filament">Filament project</a>. To report errors in this document please use the <a href="https://github.com/google/filament/issues">project's issue tracker</a>.
+</p>
+<a class="target" name="authors">&nbsp;</a><a class="target" name="about/authors">&nbsp;</a><a class="target" name="toc1.1">&nbsp;</a><h2>Authors</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://twitter.com/darthmoosious">@darthmoosious</a></li></ul>
+</p>
+<a class="target" name="overview">&nbsp;</a><a class="target" name="overview">&nbsp;</a><a class="target" name="toc2">&nbsp;</a><h1>Overview</h1>
+<p>
+
+Filament is a physically based rendering (PBR) engine for Android. Filament offers a customizable
+material system that you can use to create both simple and complex materials. This document
+describes all the features available to materials and how to create your own material.
+</p>
+<a class="target" name="coreconcepts">&nbsp;</a><a class="target" name="overview/coreconcepts">&nbsp;</a><a class="target" name="toc2.1">&nbsp;</a><h2>Core concepts</h2>
+<p>
+
+<dl><dt>Material</dt><dd><p>    A material defines the visual appearance of a surface. To completely describe and render a
+    surface, a material provides the following information:
+</p><p>
+<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>Material model</dt><dd><p>    Also called <em class="underscore">shading model</em> or <em class="underscore">lighting model</em>, the material model defines the intrinsic
+    properties of a surface. These properties have a direct influence on the way lighting is
+    computed and therefore on the appearance of a surface.
+</p></dd><dt>Material definition</dt><dd><p>    A text file that describes all the information required by a material. This is the file that you
+    will directly author to create new materials.
+</p></dd><dt>Material package</dt><dd><p>    At runtime, materials are loaded from <em class="underscore">material packages</em> compiled from material definitions
+    using the <code>matc</code> tool. A material package contains all the information required to describe a
+    material, and shaders generated for the target runtime platforms. This is necessary because
+    different platforms (Android, macOS, Linux, etc.) use different graphics APIs or different
+    variants of similar graphics APIs (OpenGL vs OpenGL ES for instance).
+</p></dd><dt>Material instance</dt><dd><p>    A material instance is a reference to a material and a set of values for the different values of
+    that material. Material instances are not covered in this document as they are created and
+    manipulated directly from code using Filament's APIs.
+</p></dd></dl></p>
+<a class="target" name="materialmodels">&nbsp;</a><a class="target" name="materialmodels">&nbsp;</a><a class="target" name="toc3">&nbsp;</a><h1>Material models</h1>
+<p>
+
+Filament materials can use one of the following material models:
+</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>
+<a class="target" name="litmodel">&nbsp;</a><a class="target" name="materialmodels/litmodel">&nbsp;</a><a class="target" name="toc3.1">&nbsp;</a><h2>Lit model</h2>
+<p>
+
+The lit model is Filament's standard material model. This physically-based shading model was
+designed after to offer good interoperability with other common tools and engines such as <em class="underscore">Unity 5</em>,
+<em class="underscore">Unreal Engine 4</em>, <em class="underscore">Substance Designer</em> or <em class="underscore">Marmoset Toolbag</em>.
+</p><p>
+This material model can be used to describe many non-metallic surfaces (<em class="underscore">dielectrics</em>)
+or metallic surfaces (<em class="underscore">conductors</em>).
+</p><p>
+The appearance of a material using the standard model is controlled using the properties described
+in <a href="#table_standardproperties" target="_self">table&nbsp;1</a>.
+</p><p>
+<div class='table'>
+<a class="target" name="table_standardproperties">&nbsp;</a><table class="table longtable"><tr><th  style="text-align:right"> Property </th><th  style="text-align:left"> Definition </th></tr>
+<tr><td  style="text-align:right"> <strong class="asterisk">baseColor</strong> </td><td  style="text-align:left"> Diffuse albedo for non-metallic surfaces, and specular color for metallic surfaces </td></tr>
+<tr><td  style="text-align:right"> <strong class="asterisk">metallic</strong> </td><td  style="text-align:left"> Whether a surface appears to be dielectric (0.0) or conductor (1.0). Often used as a binary value (0 or 1) </td></tr>
+<tr><td  style="text-align:right"> <strong class="asterisk">roughness</strong> </td><td  style="text-align:left"> Perceived smoothness (1.0) or roughness (0.0) of a surface. Smooth surfaces exhibit sharp reflections </td></tr>
+<tr><td  style="text-align:right"> <strong class="asterisk">reflectance</strong> </td><td  style="text-align:left"> Fresnel reflectance at normal incidence for dielectric surfaces. This directly controls the strength of the reflections </td></tr>
+<tr><td  style="text-align:right"> <strong class="asterisk">sheenColor</strong> </td><td  style="text-align:left"> Strength of the sheen layer </td></tr>
+<tr><td  style="text-align:right"> <strong class="asterisk">sheenRoughness</strong> </td><td  style="text-align:left"> Perceived smoothness or roughness of the sheen layer </td></tr>
+<tr><td  style="text-align:right"> <strong class="asterisk">clearCoat</strong> </td><td  style="text-align:left"> Strength of the clear coat layer </td></tr>
+<tr><td  style="text-align:right"> <strong class="asterisk">clearCoatRoughness</strong> </td><td  style="text-align:left"> Perceived smoothness or roughness of the clear coat layer </td></tr>
+<tr><td  style="text-align:right"> <strong class="asterisk">anisotropy</strong> </td><td  style="text-align:left"> Amount of anisotropy in either the tangent or bitangent direction </td></tr>
+<tr><td  style="text-align:right"> <strong class="asterisk">anisotropyDirection</strong> </td><td  style="text-align:left"> Local surface direction in tangent space </td></tr>
+<tr><td  style="text-align:right"> <strong class="asterisk">ambientOcclusion</strong> </td><td  style="text-align:left"> Defines how much of the ambient light is accessible to a surface point. It is a per-pixel shadowing factor between 0.0 and 1.0 </td></tr>
+<tr><td  style="text-align:right"> <strong class="asterisk">normal</strong> </td><td  style="text-align:left"> A detail normal used to perturb the surface using <em class="underscore">bump mapping</em> (<em class="underscore">normal mapping</em>) </td></tr>
+<tr><td  style="text-align:right"> <strong class="asterisk">bentNormal</strong> </td><td  style="text-align:left"> A normal pointing in the average unoccluded direction. Can be used to improve indirect lighting quality </td></tr>
+<tr><td  style="text-align:right"> <strong class="asterisk">clearCoatNormal</strong> </td><td  style="text-align:left"> A detail normal used to perturb the clear coat layer using <em class="underscore">bump mapping</em> (<em class="underscore">normal mapping</em>) </td></tr>
+<tr><td  style="text-align:right"> <strong class="asterisk">emissive</strong> </td><td  style="text-align:left"> Additional diffuse albedo to simulate emissive surfaces (such as neons, etc.) This property is mostly useful in an HDR pipeline with a bloom pass </td></tr>
+<tr><td  style="text-align:right"> <strong class="asterisk">postLightingColor</strong> </td><td  style="text-align:left"> Additional color that can be blended with the result of the lighting computations. See <code>postLightingBlending</code> </td></tr>
+<tr><td  style="text-align:right"> <strong class="asterisk">ior</strong> </td><td  style="text-align:left"> Index of refraction, either for refractive objects or as an alternative to reflectance </td></tr>
+<tr><td  style="text-align:right"> <strong class="asterisk">transmission</strong> </td><td  style="text-align:left"> Defines how much of the diffuse light of a dielectric is transmitted through the object, in other words this defines how transparent an object is </td></tr>
+<tr><td  style="text-align:right"> <strong class="asterisk">absorption</strong> </td><td  style="text-align:left"> Absorption factor for refractive objects </td></tr>
+<tr><td  style="text-align:right"> <strong class="asterisk">microThickness</strong> </td><td  style="text-align:left"> Thickness of the thin layer of refractive objects </td></tr>
+<tr><td  style="text-align:right"> <strong class="asterisk">thickness</strong> </td><td  style="text-align:left"> Thickness of the solid volume of refractive objects </td></tr>
+</table><center><div class="tablecaption"><b style="font-style:normal;">Table&nbsp;1:</b> Properties of the standard model</div></center></div>
+</p><p>
+The type and range of each property is described in <a href="#table_standardpropertiestypes" target="_self">table&nbsp;2</a>.
+<div class='table'>
+<a class="target" name="table_standardpropertiestypes">&nbsp;</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"> &nbsp; </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"> &nbsp; </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"> &nbsp; </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"> [&minus;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"> &nbsp; </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"> &nbsp; </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"> &nbsp; </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"> &nbsp; </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"> &nbsp; </td></tr>
+</table><center><div class="tablecaption"><b style="font-style:normal;">Table&nbsp;2:</b> Range and type of the standard model's properties</div></center></div>
+</p><p>
+<div class="admonition note"><div class="admonition-title"> About linear RGB</div>
+</p><p>
+    Several material model properties expect RGB colors. Filament materials use RGB colors in linear
+    space and you must take proper care of supplying colors in that space. See the <a href="#linearcolors" target="_self">Linear colors</a> section for more information.</div>
+</p><p>
+<div class="admonition note"><div class="admonition-title"> About pre-multiplied RGB</div>
+</p><p>
+    Filament materials expect colors to use pre-multiplied alpha. See the <a href="#pre-multipliedalpha" target="_self">Pre-multiplied alpha</a> section for more information.</div>
+</p><p>
+<div class="admonition note"><div class="admonition-title"> About <code>absorption</code></div>
+</p><p>
+    The light attenuation through the material is defined as \(e^{-absorption \cdot distance}\),
+    and the distance depends on the <code>thickness</code> parameter. If <code>thickness</code> is not provided, then
+    the <code>absorption</code> parameter is used directly and the light attenuation through the material
+    becomes \(1 - absorption\). To obtain a certain color at a desired distance, the above
+    equation can be inverted such as \(absorption = -\frac{ln(color)}{distance}\).</div>
+</p><p>
+<div class="admonition note"><div class="admonition-title"> About <code>ior</code> and <code>reflectance</code></div>
+</p><p>
+    The index of refraction (IOR) and the reflectance represent the same physical attribute,
+    therefore they don't need to be both specified. Typically, only the reflectance is specified,
+    and the IOR is deduced automatically. When only the IOR is specified, the reflectance is then
+    deduced automatically. It is possible to specify both, in which case their values are kept
+    as-is, which can lead to physically impossible materials, however, this might be desirable
+    for artistic reasons.</div>
+</p><p>
+<div class="admonition note"><div class="admonition-title"> About <code>thickness</code> and <code>microThickness</code> for refraction</div>
+</p><p>
+    <code>thickness</code> represents the thickness of solid objects in the direction of the normal, for
+    satisfactory results, this should be provided per fragment (e.g.: as a texture) or at least per
+    vertex. <code>microThickness</code> represent the thickness of the thin layer of an object, and can
+    generally be provided as a constant value. For example, a 1mm thin hollow sphere of radius 1m,
+    would have a <code>thickness</code> of 1 and a <code>microThickness</code> of 0.001. Currently <code>thickness</code> is not
+    used when <code>refractionType</code> is set to <code>thin</code>.</div>
+</p>
+<a class="target" name="basecolor">&nbsp;</a><a class="target" name="materialmodels/litmodel/basecolor">&nbsp;</a><a class="target" name="toc3.1.1">&nbsp;</a><h3>Base color</h3>
+<p>
+
+The <code>baseColor</code> property defines the perceived color of an object (sometimes called albedo). The
+effect of <code>baseColor</code> depends on the nature of the surface, controlled by the <code>metallic</code> property
+explained in the <a href="#metallic" target="_self">Metallic</a> section.
+</p><p>
+<dl><dt>Non-metals (dielectrics)</dt><dd><p>  Defines the diffuse color of the surface. Real-world values are typically found in the range
+  \([10..240]\) if the value is encoded between 0 and 255, or in the range \([0.04..0.94]\) between 0
+  and 1. Several examples of base colors for non-metallic surfaces can be found in
+  <a href="#table_basecolorsdielectrics" target="_self">table&nbsp;3</a>.
+</p></dd></dl><div class='table'>
+<a class="target" name="table_basecolorsdielectrics">&nbsp;</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">&nbsp;</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">&nbsp;</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">&nbsp;</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">&nbsp;</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">&nbsp;</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">&nbsp;</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">&nbsp;</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">&nbsp;</div> </td></tr>
+</table><center><div class="tablecaption"><b style="font-style:normal;">Table&nbsp;3:</b> <code>baseColor</code> for common non-metals</div></center></div>
+</p><p>
+<dl><dt>Metals (conductors)</dt><dd><p>  Defines the specular color of the surface. Real-world values are typically found in the range
+  \([170..255]\) if the value is encoded between 0 and 255, or in the range \([0.66..1.0]\) between 0 and
+  1. Several examples of base colors for metallic surfaces can be found in <a href="#table_basecolorsconductors" target="_self">table&nbsp;4</a>.
+</p></dd></dl><div class='table'>
+<a class="target" name="table_basecolorsconductors">&nbsp;</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">&nbsp;</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">&nbsp;</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">&nbsp;</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">&nbsp;</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">&nbsp;</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">&nbsp;</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">&nbsp;</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">&nbsp;</div> </td></tr>
+</table><center><div class="tablecaption"><b style="font-style:normal;">Table&nbsp;4:</b> <code>baseColor</code> for common metals</div></center></div>
+</p>
+<a class="target" name="metallic">&nbsp;</a><a class="target" name="materialmodels/litmodel/metallic">&nbsp;</a><a class="target" name="toc3.1.2">&nbsp;</a><h3>Metallic</h3>
+<p>
+
+The <code>metallic</code> property defines whether the surface is a metallic (<em class="underscore">conductor</em>) or a non-metallic
+(<em class="underscore">dielectric</em>) surface. This property should be used as a binary value, set to either 0 or 1.
+Intermediate values are only truly useful to create transitions between different types of surfaces
+when using textures.
+</p><p>
+This property can dramatically change the appearance of a surface. Non-metallic surfaces have
+chromatic diffuse reflection and achromatic specular reflection (reflected light does not change
+color). Metallic surfaces do not have any diffuse reflection and chromatic specular reflection
+(reflected light takes on the color of the surfaced as defined by <code>baseColor</code>). 
+</p><p>
+The effect of <code>metallic</code> is shown in <a href="#figure_metallicproperty" target="_self">figure&nbsp;1</a> (click on the image to see a
+larger version).
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_metallicproperty">&nbsp;</a><a href="../images/materials/metallic.png" target="_blank"><img class="markdeep" src="../images/materials/metallic.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;1:</b> <code>metallic</code> varying from 0.0
+</span></center></div></center>
+</p>
+<a class="target" name="roughness">&nbsp;</a><a class="target" name="materialmodels/litmodel/roughness">&nbsp;</a><a class="target" name="toc3.1.3">&nbsp;</a><h3>Roughness</h3>
+<p>
+
+The <code>roughness</code> property controls the perceived smoothness of the surface. When <code>roughness</code> is set
+to 0, the surface is perfectly smooth and highly glossy. The rougher a surface is, the &ldquo;blurrier&rdquo;
+the reflections are. This property is often called <em class="underscore">glossiness</em> in other engines and tools, and is
+simply the opposite of the roughness (<code>roughness = 1 - glossiness</code>).
+</p>
+<a class="target" name="non-metals">&nbsp;</a><a class="target" name="materialmodels/litmodel/non-metals">&nbsp;</a><a class="target" name="toc3.1.4">&nbsp;</a><h3>Non-metals</h3>
+<p>
+
+The effect of <code>roughness</code> on non-metallic surfaces is shown in <a href="#figure_roughnessproperty" target="_self">figure&nbsp;2</a> (click
+on the image to see a larger version).
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_roughnessproperty">&nbsp;</a><a href="../images/materials/dielectric_roughness.png" target="_blank"><img class="markdeep" src="../images/materials/dielectric_roughness.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;2:</b> Dielectric <code>roughness</code> varying from 0.0
+</span></center></div></center>
+</p>
+<a class="target" name="metals">&nbsp;</a><a class="target" name="materialmodels/litmodel/metals">&nbsp;</a><a class="target" name="toc3.1.5">&nbsp;</a><h3>Metals</h3>
+<p>
+
+The effect of <code>roughness</code> on metallic surfaces is shown in <a href="#figure_roughnessconductorproperty" target="_self">figure&nbsp;3</a>
+(click on the image to see a larger version).
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_roughnessconductorproperty">&nbsp;</a><a href="../images/materials/conductor_roughness.png" target="_blank"><img class="markdeep" src="../images/materials/conductor_roughness.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;3:</b> Conductor <code>roughness</code> varying from 0.0
+</span></center></div></center>
+</p>
+<a class="target" name="refraction">&nbsp;</a><a class="target" name="materialmodels/litmodel/refraction">&nbsp;</a><a class="target" name="toc3.1.6">&nbsp;</a><h3>Refraction</h3>
+<p>
+
+When refraction through an object is enabled (using a <code>refractonType</code> of <code>thin</code> or <code>solid</code>), the
+<code>roughness</code> property will also affect the refractions, as shown in <a href="#figure_roughnessrefractionproperty" target="_self">figure&nbsp;4</a> (click on the image to see a larger version).
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_roughnessrefractionproperty">&nbsp;</a><a href="../images/materials/refraction_roughness.png" target="_blank"><img class="markdeep" src="../images/materials/refraction_roughness.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;4:</b> Refractive sphere with <code>roughness</code> varying from 0.0
+</span></center></div></center>
+</p>
+<a class="target" name="reflectance">&nbsp;</a><a class="target" name="materialmodels/litmodel/reflectance">&nbsp;</a><a class="target" name="toc3.1.7">&nbsp;</a><h3>Reflectance</h3>
+<p>
+
+The <code>reflectance</code> property only affects non-metallic surfaces. This property can be used to control
+the specular intensity and index of refraction of materials. This value is defined
+between 0 and 1 and represents a remapping of a  percentage of reflectance. For instance, the
+default value of 0.5 corresponds to a reflectance of 4%. Values below 0.35 (2% reflectance) should
+be avoided as no real-world materials have such low reflectance.
+</p><p>
+The effect of <code>reflectance</code> on non-metallic surfaces is shown in <a href="#figure_reflectanceproperty" target="_self">figure&nbsp;5</a>
+(click on the image to see a larger version).
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_reflectanceproperty">&nbsp;</a><a href="../images/materials/reflectance.png" target="_blank"><img class="markdeep" src="../images/materials/reflectance.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;5:</b> <code>reflectance</code> varying from 0.0 (left)
+</span></center></div></center>
+</p><p>
+<a href="#figure_reflectance" target="_self">Figure&nbsp;6</a> shows common values and how they relate to the mapping function.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_reflectance">&nbsp;</a><a href="../images/diagram_reflectance.png" target="_blank"><img class="markdeep" src="../images/diagram_reflectance.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;6:</b> Common reflectance values</span></center></div></center>
+</p><p>
+<a href="#table_commonmatreflectance" target="_self">Table&nbsp;5</a> describes acceptable reflectance values for various types of materials
+(no real world material has a value under 2%).
+</p><p>
+<div class='table'>
+<a class="target" name="table_commonmatreflectance">&nbsp;</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&nbsp;5:</b> Reflectance of common materials</div></center></div>
+</p><p>
+Note that the <code>reflectance</code> property also defines the index of refraction of the surface.
+When this property is defined it is not necessary to define the <code>ior</code> property. Setting
+either of these properties will automatically compute the other property. It is possible
+to specify both, in which case their values are kept as-is, which can lead to physically
+impossible materials, however, this might be desirable for artistic reasons.
+</p><p>
+The <code>reflectance</code> property is designed as a normalized property in the range 0..1 which makes
+it easy to define from a texture.
+</p><p>
+See section <a href="#toc3.1.20" target="_self">3.1.20</a> for more information about the <code>ior</code> property and refractive
+indices.
+</p>
+<a class="target" name="sheencolor">&nbsp;</a><a class="target" name="materialmodels/litmodel/sheencolor">&nbsp;</a><a class="target" name="toc3.1.8">&nbsp;</a><h3>Sheen color</h3>
+<p>
+
+The sheen color controls the color appearance and strength of an optional sheen layer on top of the
+base layer described by the properties above. The sheen layer always sits below the clear coat layer
+if such a layer is present.
+</p><p>
+The sheen layer can be used to represent cloth and fabric materials. Please refer to 
+section <a href="#toc3.3" target="_self">3.3</a> for more information about cloth and fabric materials.
+</p><p>
+The effect of <code>sheenColor</code> is shown in <a href="#figure_materialsheencolor" target="_self">figure&nbsp;7</a>
+(click on the image to see a larger version).
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_materialsheencolor">&nbsp;</a><a href="../images/screenshot_sheen_color.png" target="_blank"><img class="markdeep" src="../images/screenshot_sheen_color.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;7:</b> Different sheen colors</span></center></div></center>
+</p><p>
+<div class="admonition note">If you do not need the other properties offered by the standard lit material model but want to
+    create a cloth-like or fabric-like appearance, it is more efficient to use the dedicated cloth
+    model described in section <a href="#toc3.3" target="_self">3.3</a>.</div>
+</p>
+<a class="target" name="sheenroughness">&nbsp;</a><a class="target" name="materialmodels/litmodel/sheenroughness">&nbsp;</a><a class="target" name="toc3.1.9">&nbsp;</a><h3>Sheen roughness</h3>
+<p>
+
+The <code>sheenRoughness</code> property is similar to the <code>roughness</code> property but applies only to the
+sheen layer.
+</p><p>
+The effect of <code>sheenRoughness</code> on a rough metal is shown in <a href="#figure_sheenroughnessproperty" target="_self">figure&nbsp;8</a>
+(click on the image to see a larger version). In this picture, the base layer is a dark blue, with
+<code>metallic</code> set to <code>0.0</code> and <code>roughness</code> set to <code>1.0</code>.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_sheenroughnessproperty">&nbsp;</a><a href="../images/materials/sheen_roughness.png" target="_blank"><img class="markdeep" src="../images/materials/sheen_roughness.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;8:</b> <code>sheenRoughness</code> varying from 0.0
+</span></center></div></center>
+</p>
+<a class="target" name="clearcoat">&nbsp;</a><a class="target" name="materialmodels/litmodel/clearcoat">&nbsp;</a><a class="target" name="toc3.1.10">&nbsp;</a><h3>Clear coat</h3>
+<p>
+
+Multi-layer materials are fairly common, particularly materials with a thin translucent
+layer over a base layer. Real world examples of such materials include car paints, soda cans,
+lacquered wood and acrylic.
+</p><p>
+The <code>clearCoat</code> property can be used to describe materials with two layers. The clear coat layer
+will always be isotropic and dielectric.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_clearcoat">&nbsp;</a><a href="../images/material_carbon_fiber.png" target="_blank"><img class="markdeep" src="../images/material_carbon_fiber.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;9:</b> Comparison of a carbon-fiber material under the standard material model
+</span></center></div></center>
+</p><p>
+The <code>clearCoat</code> property controls the strength of the clear coat layer. This should be treated as a
+binary value, set to either 0 or 1. Intermediate values are useful to control transitions between
+parts of the surface that have a clear coat layers and parts that don't.
+</p><p>
+The effect of <code>clearCoat</code> on a rough metal is shown in <a href="#figure_clearcoatproperty" target="_self">figure&nbsp;10</a>
+(click on the image to see a larger version).
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_clearcoatproperty">&nbsp;</a><a href="../images/materials/clear_coat.png" target="_blank"><img class="markdeep" src="../images/materials/clear_coat.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;10:</b> <code>clearCoat</code> varying from 0.0
+</span></center></div></center>
+</p><p>
+<div class="admonition warning">The clear coat layer effectively doubles the cost of specular computations. Do not assign a
+    value, even 0.0, to the clear coat property if you don't need this second layer.</div>
+</p><p>
+<div class="admonition note">The clear coat layer is added on top of the sheen layer if present.</div>
+</p>
+<a class="target" name="clearcoatroughness">&nbsp;</a><a class="target" name="materialmodels/litmodel/clearcoatroughness">&nbsp;</a><a class="target" name="toc3.1.11">&nbsp;</a><h3>Clear coat roughness</h3>
+<p>
+
+The <code>clearCoatRoughness</code> property is similar to the <code>roughness</code> property but applies only to the
+clear coat layer.
+</p><p>
+The effect of <code>clearCoatRoughness</code> on a rough metal is shown in <a href="#figure_clearcoatroughnessproperty" target="_self">figure&nbsp;11</a>
+(click on the image to see a larger version).
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_clearcoatroughnessproperty">&nbsp;</a><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"><b style="font-style:normal;">Figure&nbsp;11:</b> <code>clearCoatRoughness</code> varying from 0.0
+</span></center></div></center>
+</p>
+<a class="target" name="anisotropy">&nbsp;</a><a class="target" name="materialmodels/litmodel/anisotropy">&nbsp;</a><a class="target" name="toc3.1.12">&nbsp;</a><h3>Anisotropy</h3>
+<p>
+
+Many real-world materials, such as brushed metal, can only be replicated using an anisotropic
+reflectance model. A material can be changed from the default isotropic model to an anisotropic
+model by using the <code>anisotropy</code> property.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_anisotropic">&nbsp;</a><a href="../images/material_anisotropic.png" target="_blank"><img class="markdeep" src="../images/material_anisotropic.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;12:</b> Comparison of isotropic material
+</span></center></div></center>
+</p><p>
+The effect of <code>anisotropy</code> on a rough metal is shown in <a href="#figure_anisotropyproperty" target="_self">figure&nbsp;13</a>
+(click on the image to see a larger version).
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_anisotropyproperty">&nbsp;</a><a href="../images/materials/anisotropy.png" target="_blank"><img class="markdeep" src="../images/materials/anisotropy.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;13:</b> <code>anisotropy</code> varying from 0.0
+</span></center></div></center>
+</p><p>
+The <a href="#figure_anisotropydir" target="_self">figure&nbsp;14</a> below shows how the direction of the anisotropic highlights can be
+controlled by using either positive or negative values: positive values define anisotropy in the
+tangent direction and negative values in the bitangent direction.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_anisotropydir">&nbsp;</a><a href="../images/screenshot_anisotropy_direction.png" target="_blank"><img class="markdeep" src="../images/screenshot_anisotropy_direction.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;14:</b> Positive (left) vs negative
+</span></center></div></center>
+</p><p>
+<div class="admonition tip">The anisotropic material model is slightly more expensive than the standard material model. Do
+    not assign a value (even 0.0) to the <code>anisotropy</code> property if you don't need anisotropy.</div>
+</p>
+<a class="target" name="anisotropydirection">&nbsp;</a><a class="target" name="materialmodels/litmodel/anisotropydirection">&nbsp;</a><a class="target" name="toc3.1.13">&nbsp;</a><h3>Anisotropy direction</h3>
+<p>
+
+The <code>anisotropyDirection</code> property defines the direction of the surface at a given point and thus
+control the shape of the specular highlights. It is specified as vector of 3 values that usually
+come from a texture, encoding the directions local to the surface in tangent space. Because the
+direction is in tangent space, the Z component should be set to 0.
+</p><p>
+The effect of <code>anisotropyDirection</code> on a metal is shown in <a href="#figure_anisotropydirectionproperty" target="_self">figure&nbsp;16</a>
+(click on the image to see a larger version).
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_anisotropydirectionproperty">&nbsp;</a><a href="../images/screenshot_anisotropy.png" target="_blank"><img class="markdeep" src="../images/screenshot_anisotropy.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;15:</b> Anisotropic metal rendered
+</span></center></div></center>
+</p><p>
+The result shown in <a href="#figure_anisotropydirectionproperty" target="_self">figure&nbsp;16</a> was obtained using the direction map shown
+in <a href="#figure_anisotropydirectionproperty" target="_self">figure&nbsp;16</a>.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_anisotropydirectionproperty">&nbsp;</a><a href="../images/screenshot_anisotropy_map.jpg" target="_blank"><img class="markdeep" src="../images/screenshot_anisotropy_map.jpg" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;16:</b> Example of Lighting: specularAmbientOcclusiona direction map</span></center></div></center>
+</p>
+<a class="target" name="ambientocclusion">&nbsp;</a><a class="target" name="materialmodels/litmodel/ambientocclusion">&nbsp;</a><a class="target" name="toc3.1.14">&nbsp;</a><h3>Ambient occlusion</h3>
+<p>
+
+The <code>ambientOcclusion</code> property defines how much of the ambient light is accessible to a surface
+point. It is a per-pixel shadowing factor between 0.0 (fully shadowed) and 1.0 (fully lit). This
+property only affects diffuse indirect lighting (image-based lighting), not direct lights such as
+directional, point and spot lights, nor specular lighting.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_aoexample">&nbsp;</a><a href="../images/screenshot_ao.jpg" target="_blank"><img class="markdeep" src="../images/screenshot_ao.jpg" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;17:</b> Comparison of materials without diffuse ambient occlusion
+</span></center></div></center>
+</p>
+<a class="target" name="normal">&nbsp;</a><a class="target" name="materialmodels/litmodel/normal">&nbsp;</a><a class="target" name="toc3.1.15">&nbsp;</a><h3>Normal</h3>
+<p>
+
+The <code>normal</code> property defines the normal of the surface at a given point. It usually comes from a
+<em class="underscore">normal map</em> texture, which allows to vary the property per-pixel. The normal is supplied in tangent
+space, which means that +Z points outside of the surface.
+</p><p>
+For example, let's imagine that we want to render a piece of furniture covered in tufted leather.
+Modeling the geometry to accurately represent the tufted pattern would require too many triangles
+so we instead bake a high-poly mesh into a normal map. Once the base map is applied to a simplified
+mesh, we get the result in <a href="#figure_normalmapped" target="_self">figure&nbsp;18</a>.
+</p><p>
+Note that the <code>normal</code> property affects the <em class="underscore">base layer</em> and not the clear coat layer.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_normalmapped">&nbsp;</a><a href="../images/screenshot_normal_mapping.jpg" target="_blank"><img class="markdeep" src="../images/screenshot_normal_mapping.jpg" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;18:</b> Low-poly mesh without normal mapping (left)
+</span></center></div></center>
+</p><p>
+<div class="admonition warning">Using a normal map increases the runtime cost of the material model.</div>
+</p>
+<a class="target" name="bentnormal">&nbsp;</a><a class="target" name="materialmodels/litmodel/bentnormal">&nbsp;</a><a class="target" name="toc3.1.16">&nbsp;</a><h3>Bent normal</h3>
+<p>
+
+The <code>bentNormal</code> property defines the average unoccluded direction at a point on the surface. It is
+used to improve the accuracy of indirect lighting. Bent normals can also improve the quality of
+specular ambient occlusion (see section <a href="#toc4.2.33" target="_self">4.2.33</a> about
+<code>specularAmbientOcclusion</code>).
+</p><p>
+Bent normals can greatly increase the visual fidelity of an asset with various cavities and concave
+areas, as shown in <a href="#figure_bentnormalmapped" target="_self">figure&nbsp;19</a>. See the areas of the ears, nostrils and eyes for
+instance.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_bentnormalmapped">&nbsp;</a><a href="../images/material_bent_normal.gif" target="_blank"><img class="markdeep" src="../images/material_bent_normal.gif" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;19:</b> Example of a model rendered with and without a bent normal map. Both
+</span></center></div></center>
+</p>
+<a class="target" name="clearcoatnormal">&nbsp;</a><a class="target" name="materialmodels/litmodel/clearcoatnormal">&nbsp;</a><a class="target" name="toc3.1.17">&nbsp;</a><h3>Clear coat normal</h3>
+<p>
+
+The <code>clearCoatNormal</code> property defines the normal of the clear coat layer at a given point. It
+behaves otherwise like the <code>normal</code> property.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_clearcoatnormalmapped">&nbsp;</a><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"><b style="font-style:normal;">Figure&nbsp;20:</b> A material with a clear coat normal
+</span></center></div></center>
+</p><p>
+<div class="admonition warning">Using a clear coat normal map increases the runtime cost of the material model.</div>
+</p>
+<a class="target" name="emissive">&nbsp;</a><a class="target" name="materialmodels/litmodel/emissive">&nbsp;</a><a class="target" name="toc3.1.18">&nbsp;</a><h3>Emissive</h3>
+<p>
+
+The <code>emissive</code> property can be used to simulate additional light emitted by the surface. It is
+defined as a <code>float4</code> value that contains an RGB intensity in nits as well as an exposure
+weight (in the alpha channel).
+</p><p>
+The intensity in nits allows an emissive surface to function as a light and can be used to recreate
+real world surfaces. For instance a computer display has an intensity between 200 and 1,000 nits.
+</p><p>
+If you prefer to work in EV (or f-stops), you can simplify multiply your emissive color by the
+output of the API <code>filament::Exposure::luminance(ev)</code>. This API returns the luminance in nits of
+the specific EV. You can perform this conversion yourself using the following formula, where \(L\)
+is the final intensity in nits: \( L = 2^{EV - 3} \).
+</p><p>
+The exposure weight carried in the alpha channel can be used to undo the camera exposure, and thus
+force an emissive surface to bloom. When the exposure weight is set to 0, the emissive intensity is
+not affected by the camera exposure. When the weight is set to 1, the intensity is multiplied by
+the camera exposure like with any regular light.
+</p>
+<a class="target" name="post-lightingcolor">&nbsp;</a><a class="target" name="materialmodels/litmodel/post-lightingcolor">&nbsp;</a><a class="target" name="toc3.1.19">&nbsp;</a><h3>Post-lighting color</h3>
+<p>
+
+The <code>postLightingColor</code> can be used to modify the surface color after lighting computations. This
+property has no physical meaning and only exists to implement specific effects or to help with
+debugging. This property is defined as a <code>float4</code> value containing a pre-multiplied RGB color in
+linear space.
+</p><p>
+The post-lighting color is blended with the result of lighting according to the blending mode
+specified by the <code>postLightingBlending</code> material option. Please refer to the documentation of
+this option for more information.
+</p><p>
+<div class="admonition tip"><code>postLightingColor</code> can be used as a simpler <code>emissive</code> property by setting
+    <code>postLightingBlending</code> to <code>add</code> and by providing an RGB color with alpha set to <code>0.0</code>.</div>
+</p>
+<a class="target" name="indexofrefraction">&nbsp;</a><a class="target" name="materialmodels/litmodel/indexofrefraction">&nbsp;</a><a class="target" name="toc3.1.20">&nbsp;</a><h3>Index of refraction</h3>
+<p>
+
+The <code>ior</code> property only affects non-metallic surfaces. This property can be used to control the
+index of refraction and the specular intensity of materials. The <code>ior</code> property is intended to
+be used with refractive (transmissive) materials, which are enabled when the <code>refractionMode</code> is
+set to <code>cubemap</code> or <code>screenspace</code>. It can also be used on non-refractive objects as an alternative
+to setting the reflectance.
+</p><p>
+The index of refraction (or refractive index) of a material is a dimensionless number that describes
+how fast light travels through that material. The higher the number, the slower light travels
+through the medium. More importantly for rendering materials, the refractive index determines how
+the path light travels is bent when entering the material. Higher indices of refraction will cause
+light to bend further away from the initial path.
+</p><p>
+<a href="#table_commonmatior" target="_self">Table&nbsp;6</a> describes acceptable refractive indices for various types of materials.
+<div class='table'>
+<a class="target" name="table_commonmatior">&nbsp;</a><table class="table"><tr><th  style="text-align:right"> Material </th><th  style="text-align:left"> IOR </th></tr>
+<tr><td  style="text-align:right"> Air </td><td  style="text-align:left"> 1.0 </td></tr>
+<tr><td  style="text-align:right"> Water </td><td  style="text-align:left"> 1.33 </td></tr>
+<tr><td  style="text-align:right"> Common liquids </td><td  style="text-align:left"> 1.33 to 1.5 </td></tr>
+<tr><td  style="text-align:right"> Common gemstones </td><td  style="text-align:left"> 1.58 to 2.33 </td></tr>
+<tr><td  style="text-align:right"> Plastics, glass </td><td  style="text-align:left"> 1.5 to 1.58 </td></tr>
+<tr><td  style="text-align:right"> Other dielectric materials </td><td  style="text-align:left"> 1.33 to 1.58 </td></tr>
+</table><center><div class="tablecaption"><b style="font-style:normal;">Table&nbsp;6:</b> Index of refraction of common materials</div></center></div>
+</p><p>
+The appearance of a refractive material will greatly depend on the <code>refractionType</code> and
+<code>refractionMode</code> settings of the material. Refer to section <a href="#toc4.2.21" target="_self">4.2.21</a> and section <a href="#toc4.2.20" target="_self">4.2.20</a>
+for more information.
+</p><p>
+The effect of <code>ior</code> when <code>refractionMode</code> is set to <code>cubemap</code> and <code>refractionType</code> is set to <code>solid</code>
+can be seen in <a href="#figure_iorproperty2" target="_self">figure&nbsp;21</a> (click on the image to see a larger version).
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_iorproperty2">&nbsp;</a><a href="../images/materials/ior.png" target="_blank"><img class="markdeep" src="../images/materials/ior.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;21:</b> <code>transmission</code> varying from 1.0
+</span></center></div></center>
+</p><p>
+<a href="#figure_iorproperty" target="_self">Figure&nbsp;22</a> shows the comparison of a sphere of <code>ior</code> 1.0 with a sphere of <code>ior</code> 1.33, with
+the <code>refractionMode</code> set to <code>screenspace</code> and the <code>refractionType</code> set to <code>solid</code>
+(click on the image to see a larger version).
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_iorproperty">&nbsp;</a><a href="../images/material_ior.png" target="_blank"><img class="markdeep" src="../images/material_ior.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;22:</b> <code>ior</code> of 1.0 (left) and 1.33 (right)</span></center></div></center>
+</p><p>
+Note that the <code>ior</code> property also defines the reflectance (or specular intensity) of the surface.
+When this property is defined it is not necessary to define the <code>reflectance</code> property. Setting
+either of these properties will automatically compute the other property. It is possible to specify
+both, in which case their values are kept as-is, which can lead to physically impossible materials,
+however, this might be desirable for artistic reasons.
+</p><p>
+See the <a href="#reflectance" target="_self">Reflectance</a> section for more information on the <code>reflectance</code> property.
+</p><p>
+<div class="admonition tip">Refractive materials are affected by the <code>roughness</code> property. Rough materials will scatter
+    light, creating a diffusion effect useful to recreate &ldquo;blurry&rdquo; appearances such as frosted
+    glass, certain plastics, etc.</div>
+</p>
+<a class="target" name="transmission">&nbsp;</a><a class="target" name="materialmodels/litmodel/transmission">&nbsp;</a><a class="target" name="toc3.1.21">&nbsp;</a><h3>Transmission</h3>
+<p>
+
+The <code>transmission</code> property defines what ratio of diffuse light is transmitted through a refractive
+material. This property only affects materials with a <code>refractionMode</code> set to <code>cubemap</code> or
+<code>screenspace</code>.
+</p><p>
+When <code>transmission</code> is set to 0, no amount of light is transmitted and the diffuse component of
+the surface is 100% visible. When <code>transmission</code> is set to 1, all the light is transmitted and the
+diffuse component is not visible anymore, only the specular component is.
+</p><p>
+The effect of <code>transmission</code> on a glossy dielectric (<code>ior</code> of 1.5, <code>refractionMode</code> set to
+<code>cubemap</code>, <code>refractionType</code> set to <code>solid</code>) is shown in <a href="#figure_transmissionproperty" target="_self">figure&nbsp;23</a>
+(click on the image to see a larger version).
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_transmissionproperty">&nbsp;</a><a href="../images/materials/transmission.png" target="_blank"><img class="markdeep" src="../images/materials/transmission.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;23:</b> <code>transmission</code> varying from 0.0
+</span></center></div></center>
+</p><p>
+<div class="admonition tip">The <code>transmission</code> property is useful to create decals, paint, etc. at the surface of refractive
+    materials.</div>
+</p>
+<a class="target" name="absorption">&nbsp;</a><a class="target" name="materialmodels/litmodel/absorption">&nbsp;</a><a class="target" name="toc3.1.22">&nbsp;</a><h3>Absorption</h3>
+<p>
+
+The <code>absorption</code> property defines the absorption coefficients of light transmitted through the
+material. <a href="#figure_absorptionexample" target="_self">Figure&nbsp;24</a> shows the effect of <code>absorption</code> on a refracting object with
+an index of refraction of 1.5 and a base color set to white.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_absorptionexample">&nbsp;</a><a href="../images/material_absorption.png" target="_blank"><img class="markdeep" src="../images/material_absorption.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;24:</b> Refracting object without (left)
+</span></center></div></center>
+</p><p>
+Transmittance through a volume is exponential with respect to the optical depth (defined either
+with <code>microThickness</code> or <code>thickness</code>). The computed color follows the following formula:
+</p><p>
+$$color \cdot e^{-absorption \cdot distance}$$
+</p><p>
+Where <code>distance</code> is either <code>microThickness</code> or <code>thickness</code>, that is the distance light will travel
+through the material at a given point. If no thickness/distance is specified, the computed color
+follows this formula instead:
+</p><p>
+$$color \cdot (1 - absorption)$$
+</p><p>
+The effect of varying the <code>absorption</code> coefficients is shown in <a href="#figure_absorptionproperty" target="_self">figure&nbsp;25</a>
+(click on the image to see a larger version). In this picture, the object has a fixed <code>thickness</code>
+of 4.5 and an index of refraction set to 1.3.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_absorptionproperty">&nbsp;</a><a href="../images/materials/absorption.png" target="_blank"><img class="markdeep" src="../images/materials/absorption.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;25:</b> <code>absorption</code> varying from (0.0, 0.02, 0.14)
+</span></center></div></center>
+</p><p>
+Setting the absorption coefficients directly can be unintuitive which is why we recommend working
+with a <em class="underscore">transmittance color</em> and a <em class="underscore">&ldquo;at distance&rdquo;</em> factor instead. These two parameters allow an
+artist to specify the precise color the material should have at a specified distance through the
+volume. The value to pass to <code>absorption</code> can be computed this way:
+</p><p>
+$$absorption = -\frac{ln(transmittanceColor)}{atDistance}$$
+</p><p>
+While this computation can be done in the material itself we recommend doing it offline whenever
+possible. Filament provides an API for this purpose, <code>Color::absorptionAtDistance()</code>.
+</p>
+<a class="target" name="micro-thicknessandthickness">&nbsp;</a><a class="target" name="materialmodels/litmodel/micro-thicknessandthickness">&nbsp;</a><a class="target" name="toc3.1.23">&nbsp;</a><h3>Micro-thickness and thickness</h3>
+<p>
+
+The <code>microThickness</code> and <code>thickness</code> properties define the optical depth of the material of a
+refracting object. <code>microThickness</code> is used when <code>refractionType</code> is set to <code>thin</code>, and <code>thickness</code>
+is used when <code>refractionType</code> is set to <code>volume</code>.
+</p><p>
+<code>thickness</code> represents the thickness of solid objects in the direction of the normal, for
+satisfactory results, this should be provided per fragment (e.g.: as a texture) or at least per
+vertex.
+</p><p>
+<code>microThickness</code> represent the thickness of the thin layer (shell) of an object, and can generally
+be provided as a constant value. For example, a 1mm thin hollow sphere of radius 1m, would have a
+<code>thickness</code> of 1 and a <code>microThickness</code> of 0.001. Currently <code>thickness</code> is not used when
+<code>refractionType</code> is set to <code>thin</code>. Both properties are made available for possible future use.
+</p><p>
+Both <code>thickness</code> and <code>microThickness</code> are used to compute the transmitted color of the material
+when the <code>absorption</code> property is set. In solid volumes, <code>thickness</code> will also affect how light
+rays are refracted.
+</p><p>
+The effect <code>thickness</code> in a solid volume with <code>refractionMode</code> set to <code>screenSpace</code> is shown in
+<a href="#figure_thicknessproperty" target="_self">figure&nbsp;26</a> (click on the image to see a larger version). Note how the <code>thickness</code>
+value not only changes the effect of <code>absorption</code> but also modifies the direction of the refracted
+light.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_thicknessproperty">&nbsp;</a><a href="../images/materials/thickness.png" target="_blank"><img class="markdeep" src="../images/materials/thickness.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;26:</b> <code>thickness</code> varying from 0.0
+</span></center></div></center>
+</p><p>
+<a href="#figure_varyingthickness" target="_self">Figure&nbsp;27</a> shows what a prism with spatially varying <code>thickness</code> looks like when
+the <code>refractionType</code> is set to <code>solid</code> and <code>absorption</code> coefficients are set.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_varyingthickness">&nbsp;</a><a href="../images/material_thickness.png" target="_blank"><img class="markdeep" src="../images/material_thickness.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;27:</b> <code>thickness</code> varying from 0.0 at the top of the prism to 3.0 at the
+</span></center></div></center>
+</p>
+<a class="target" name="subsurfacemodel">&nbsp;</a><a class="target" name="materialmodels/subsurfacemodel">&nbsp;</a><a class="target" name="toc3.2">&nbsp;</a><h2>Subsurface model</h2>
+<a class="target" name="thickness">&nbsp;</a><a class="target" name="materialmodels/subsurfacemodel/thickness">&nbsp;</a><a class="target" name="toc3.2.1">&nbsp;</a><h3>Thickness</h3>
+<a class="target" name="subsurfacecolor">&nbsp;</a><a class="target" name="materialmodels/subsurfacemodel/subsurfacecolor">&nbsp;</a><a class="target" name="toc3.2.2">&nbsp;</a><h3>Subsurface color</h3>
+<a class="target" name="subsurfacepower">&nbsp;</a><a class="target" name="materialmodels/subsurfacemodel/subsurfacepower">&nbsp;</a><a class="target" name="toc3.2.3">&nbsp;</a><h3>Subsurface power</h3>
+<a class="target" name="clothmodel">&nbsp;</a><a class="target" name="materialmodels/clothmodel">&nbsp;</a><a class="target" name="toc3.3">&nbsp;</a><h2>Cloth model</h2>
+<p>
+
+All the material models described previously are designed to simulate dense surfaces, both at a
+macro and at a micro level. Clothes and fabrics are however often made of loosely connected threads
+that absorb and scatter incident light. When compared to hard surfaces, cloth is characterized by
+a softer specular lob with a large falloff and the presence of fuzz lighting, caused by
+forward/backward scattering. Some fabrics also exhibit two-tone specular colors
+(velvets for instance).
+</p><p>
+<a href="#figure_materialcloth" target="_self">Figure&nbsp;28</a> shows how the standard material model fails to capture the appearance of a
+sample of denim fabric. The surface appears rigid (almost plastic-like), more similar to a tarp
+than a piece of clothing. This figure also shows how important the softer specular lobe caused by
+absorption and scattering is to the faithful recreation of the fabric.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_materialcloth">&nbsp;</a><a href="../images/screenshot_cloth.png" target="_blank"><img class="markdeep" src="../images/screenshot_cloth.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;28:</b> Comparison of denim fabric rendered using the standard model
+</span></center></div></center>
+</p><p>
+Velvet is an interesting use case for a cloth material model. As shown in <a href="#figure_materialvelvet" target="_self">figure&nbsp;29</a>
+this type of fabric exhibits strong rim lighting due to forward and backward scattering. These
+scattering events are caused by fibers standing straight at the surface of the fabric. When the
+incident light comes from the direction opposite to the view direction, the fibers will forward
+scatter the light. Similarly, when the incident light from the same direction as the view
+direction, the fibers will scatter the light backward.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_materialvelvet">&nbsp;</a><a href="../images/screenshot_cloth_velvet.png" target="_blank"><img class="markdeep" src="../images/screenshot_cloth_velvet.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;29:</b> Velvet fabric showcasing forward and
+</span></center></div></center>
+</p><p>
+It is important to note that there are types of fabrics that are still best modeled by hard surface
+material models. For instance, leather, silk and satin can be recreated using the standard or
+anisotropic material models.
+</p><p>
+The cloth material model encompasses all the parameters previously defined for the standard
+material mode except for <em class="underscore">metallic</em> and <em class="underscore">reflectance</em>. Two extra parameters described in
+<a href="#table_clothproperties" target="_self">table&nbsp;7</a> are also available.
+</p><p>
+<div class='table'>
+<a class="target" name="table_clothproperties">&nbsp;</a><table class="table"><tr><th  style="text-align:right"> Parameter </th><th  style="text-align:left"> Definition </th></tr>
+<tr><td  style="text-align:right"> <strong class="asterisk">sheenColor</strong> </td><td  style="text-align:left"> Specular tint to create two-tone specular fabrics (defaults to \(\sqrt{baseColor}\)) </td></tr>
+<tr><td  style="text-align:right"> <strong class="asterisk">subsurfaceColor</strong> </td><td  style="text-align:left"> Tint for the diffuse color after scattering and absorption through the material </td></tr>
+</table><center><div class="tablecaption"><b style="font-style:normal;">Table&nbsp;7:</b> Cloth model parameters</div></center></div>
+</p><p>
+The type and range of each property is described in <a href="#table_clothpropertiestypes" target="_self">table&nbsp;8</a>.
+<div class='table'>
+<a class="target" name="table_clothpropertiestypes">&nbsp;</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&nbsp;8:</b> Range and type of the cloth model's properties</div></center></div>
+</p><p>
+To create a velvet-like material, the base color can be set to black (or a dark color).
+Chromaticity information should instead be set on the sheen color. To create more common fabrics
+such as denim, cotton, etc. use the base color for chromaticity and use the default sheen color
+or set the sheen color to the luminance of the base color.
+</p><p>
+<div class="admonition tip">To see the effect of the <code>roughness</code> parameter make sure the <code>sheenColor</code> is brighter than
+    <code>baseColor</code>. This can be used to create a fuzz effect. Taking the luminance of <code>baseColor</code>
+    as the <code>sheenColor</code> will produce a fairly natural effect that works for common cloth. A dark
+    <code>baseColor</code> combined with a bright/saturated <code>sheenColor</code> can be used to create velvet.</div>
+</p><p>
+<div class="admonition tip">The <code>subsurfaceColor</code> parameter should be used with care. High values can interfere with shadows
+    in some areas. It is best suited for subtle transmission effects through the material.</div>
+</p>
+<a class="target" name="sheencolor">&nbsp;</a><a class="target" name="materialmodels/clothmodel/sheencolor">&nbsp;</a><a class="target" name="toc3.3.1">&nbsp;</a><h3>Sheen color</h3>
+<p>
+
+The <code>sheenColor</code> property can be used to directly modify the specular reflectance. It offers
+better control over the appearance of cloth and gives give the ability to create
+two-tone specular materials.
+</p><p>
+The effect of <code>sheenColor</code> is shown in <a href="#figure_materialclothsheen" target="_self">figure&nbsp;30</a>
+(click on the image to see a larger version).
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_materialclothsheen">&nbsp;</a><a href="../images/screenshot_cloth_sheen.png" target="_blank"><img class="markdeep" src="../images/screenshot_cloth_sheen.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;30:</b> Blue fabric without (left) and with (right) sheen</span></center></div></center>
+</p>
+<a class="target" name="subsurfacecolor">&nbsp;</a><a class="target" name="materialmodels/clothmodel/subsurfacecolor">&nbsp;</a><a class="target" name="toc3.3.2">&nbsp;</a><h3>Subsurface color</h3>
+<p>
+
+The <code>subsurfaceColor</code> property is not physically-based and can be used to simulate the scattering,
+partial absorption and re-emission of light in certain types of fabrics. This is particularly
+useful to create softer fabrics.
+</p><p>
+<div class="admonition warning">The cloth material model is more expensive to compute when the <code>subsurfaceColor</code> property is used.</div>
+</p><p>
+The effect of <code>subsurfaceColor</code> is shown in <a href="#figure_materialclothsubsurface" target="_self">figure&nbsp;31</a>
+(click on the image to see a larger version).
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_materialclothsubsurface">&nbsp;</a><a href="../images/screenshot_cloth_subsurface.png" target="_blank"><img class="markdeep" src="../images/screenshot_cloth_subsurface.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;31:</b> White cloth (left column) vs white cloth with
+</span></center></div></center>
+</p>
+<a class="target" name="unlitmodel">&nbsp;</a><a class="target" name="materialmodels/unlitmodel">&nbsp;</a><a class="target" name="toc3.4">&nbsp;</a><h2>Unlit model</h2>
+<p>
+
+The unlit material model can be used to turn off all lighting computations. Its primary purpose is
+to render pre-lit elements such as a cubemap, external content (such as a video or camera stream),
+user interfaces, visualization/debugging etc. The unlit model exposes only two properties described
+in <a href="#table_unlitproperties" target="_self">table&nbsp;9</a>.
+<div class='table'>
+<a class="target" name="table_unlitproperties">&nbsp;</a><table class="table"><tr><th  style="text-align:right"> Property </th><th  style="text-align:left"> Definition </th></tr>
+<tr><td  style="text-align:right"> <strong class="asterisk">baseColor</strong> </td><td  style="text-align:left"> Surface diffuse color </td></tr>
+<tr><td  style="text-align:right"> <strong class="asterisk">emissive</strong> </td><td  style="text-align:left"> Additional diffuse color to simulate emissive surfaces. This property is mostly useful in an HDR pipeline with a bloom pass </td></tr>
+<tr><td  style="text-align:right"> <strong class="asterisk">postLightingColor</strong> </td><td  style="text-align:left"> Additional color to blend with base color and emissive </td></tr>
+</table><center><div class="tablecaption"><b style="font-style:normal;">Table&nbsp;9:</b> Properties of the standard model</div></center></div>
+</p><p>
+The type and range of each property is described in <a href="#table_unlitpropertiestypes" target="_self">table&nbsp;10</a>.
+<div class='table'>
+<a class="target" name="table_unlitpropertiestypes">&nbsp;</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&nbsp;10:</b> Range and type of the unlit model's properties</div></center></div>
+</p><p>
+The value of <code>postLightingColor</code> is blended with the sum of <code>emissive</code> and <code>baseColor</code> according to
+the blending mode specified by the <code>postLightingBlending</code> material option.
+</p><p>
+<a href="#figure_materialunlit" target="_self">Figure&nbsp;32</a> shows an example of the unlit material model
+(click on the image to see a larger version).
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_materialunlit">&nbsp;</a><a href="../images/screenshot_unlit.jpg" target="_blank"><img class="markdeep" src="../images/screenshot_unlit.jpg" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;32:</b> The unlit model is used to render debug information</span></center></div></center>
+</p>
+<a class="target" name="specularglossiness">&nbsp;</a><a class="target" name="materialmodels/specularglossiness">&nbsp;</a><a class="target" name="toc3.5">&nbsp;</a><h2>Specular glossiness</h2>
+<p>
+
+This alternative lighting model exists to comply with legacy standards. Since it is not a
+physically-based formulation, we do not recommend using it except when loading legacy assets.
+</p><p>
+This model encompasses the parameters previously defined for the standard lit mode except for
+<em class="underscore">metallic</em>, <em class="underscore">reflectance</em>, and <em class="underscore">roughness</em>. It adds parameters for <em class="underscore">specularColor</em> and <em class="underscore">glossiness</em>.
+<div class='table'>
+<a class="target" name="table_glossinessproperties">&nbsp;</a><table class="table"><tr><th  style="text-align:right"> Parameter </th><th  style="text-align:left"> Definition </th></tr>
+<tr><td  style="text-align:right"> <strong class="asterisk">baseColor</strong> </td><td  style="text-align:left"> Surface diffuse color </td></tr>
+<tr><td  style="text-align:right"> <strong class="asterisk">specularColor</strong> </td><td  style="text-align:left"> Specular tint (defaults to black) </td></tr>
+<tr><td  style="text-align:right"> <strong class="asterisk">glossiness</strong> </td><td  style="text-align:left"> Glossiness (defaults to 0.0) </td></tr>
+</table><center><div class="tablecaption"><b style="font-style:normal;">Table&nbsp;11:</b> Properties of the specular-glossiness shading model</div></center></div>
+</p><p>
+The type and range of each property is described in <a href="#table_glossinesspropertiestypes" target="_self">table&nbsp;12</a>.
+<div class='table'>
+<a class="target" name="table_glossinesspropertiestypes">&nbsp;</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&nbsp;12:</b> Range and type of the specular-glossiness model's properties</div></center></div>
+</p>
+<a class="target" name="materialdefinitions">&nbsp;</a><a class="target" name="materialdefinitions">&nbsp;</a><a class="target" name="toc4">&nbsp;</a><h1>Material definitions</h1>
+<p>
+
+A material definition is a text file that describes all the information required by a material:
+</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>
+<a class="target" name="format">&nbsp;</a><a class="target" name="materialdefinitions/format">&nbsp;</a><a class="target" name="toc4.1">&nbsp;</a><h2>Format</h2>
+<p>
+
+The material definition format is a format loosely based on <a href="https://www.json.org/">JSON</a> that we
+call <em class="underscore">JSONish</em>. At the top level a material definition is composed of 3 different blocks that use
+the JSON object notation:
+</p><pre class="listing tilde"><code><span class="line"></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 minimum viable material definition must contain a <code>material</code> preamble and a <code>fragment</code> block. The
+<code>vertex</code> block is optional.
+</p>
+<a class="target" name="differenceswithjson">&nbsp;</a><a class="target" name="materialdefinitions/format/differenceswithjson">&nbsp;</a><a class="target" name="toc4.1.1">&nbsp;</a><h3>Differences with JSON</h3>
+<p>
+
+In JSON, an object is made of key/value <em class="underscore">pairs</em>. A JSON pair has the following syntax:
+</p><pre class="listing tilde"><code><span class="line"></span><span class="hljs-attr">&quot;key&quot;</span> <span class="hljs-punctuation">:</span> value</code></pre><p>
+Where value can be a string, number, object, array or a literal (<code>true</code>, <code>false</code> or <code>null</code>). While
+this syntax is perfectly valid in a material definition, a variant without quotes around strings is
+also accepted in JSONish:
+</p><pre class="listing tilde"><code><span class="line"></span>key <span class="hljs-punctuation">:</span> value</code></pre><p>
+Quotes remain mandatory when the string contains spaces.
+</p><p>
+The <code>vertex</code> and <code>fragment</code> blocks contain unescaped, unquoted GLSL code, which is not valid in JSON.
+</p><p>
+Single-line C++-style comments are allowed.
+</p><p>
+The key of a pair is case-sensitive.
+</p><p>
+The value of a pair is not case-sensitive.
+</p>
+<a class="target" name="example">&nbsp;</a><a class="target" name="materialdefinitions/format/example">&nbsp;</a><a class="target" name="toc4.1.2">&nbsp;</a><h3>Example</h3>
+<p>
+
+The following code listing shows an example of a valid material definition. This definition uses
+the <em class="underscore">lit</em> material model (see <a href="#litmodel" target="_self">Lit model</a> section), uses the default opaque blending mode, requires
+that a set of UV coordinates be presented in the rendered mesh and defines 3 user parameters. The
+following sections of this document describe the <code>material</code> and <code>fragment</code> blocks in detail.
+</p><pre class="listing tilde"><code><span class="line"></span>material <span class="hljs-punctuation">{</span>
+<span class="line"></span>    name <span class="hljs-punctuation">:</span> <span class="hljs-string">&quot;Textured material&quot;</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>
+<a class="target" name="materialblock">&nbsp;</a><a class="target" name="materialdefinitions/materialblock">&nbsp;</a><a class="target" name="toc4.2">&nbsp;</a><h2>Material block</h2>
+<p>
+
+The material block is mandatory block that contains a list of property pairs to describe all
+non-shader data.
+</p>
+<a class="target" name="general:name">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/general:name">&nbsp;</a><a class="target" name="toc4.2.1">&nbsp;</a><h3>General: name</h3>
+<p>
+
+<dl><table><tr valign=top><td><dt>Type</dt></td><td><dd><p>     <code>string</code>
+</p></dd></td></tr><tr valign=top><td><dt>Value</dt></td><td><dd><p>      Any string. Double quotes are required if the name contains spaces.
+</p></dd></td></tr><tr valign=top><td><dt>Description</dt></td><td><dd><p>      Sets the name of the material. The name is retained at runtime for debugging purpose.
+</p></dd></td></tr></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">&quot;Wet pavement&quot;</span>
+<span class="line"></span><span class="hljs-punctuation">}</span></code></pre>
+<a class="target" name="general:featurelevel">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/general:featurelevel">&nbsp;</a><a class="target" name="toc4.2.2">&nbsp;</a><h3>General: featureLevel</h3>
+<p>
+
+<dl><table><tr valign=top><td><dt>Type</dt></td><td><dd><p>     <code>number</code>
+</p></dd></td></tr><tr valign=top><td><dt>Value</dt></td><td><dd><p>      An integer value, either 1, 2 or 3. Defaults to 1.
+</p></dd></td></tr></table></dl><div class='table'>
+<a class="target" name="table_featurelevels">&nbsp;</a><table class="table"><tr><th  style="text-align:left"> Feature Level </th><th  style="text-align:left"> Guaranteed features </th></tr>
+<tr><td  style="text-align:left"> 1 </td><td  style="text-align:left"> 9 textures per material </td></tr>
+<tr><td  style="text-align:left"> 2 </td><td  style="text-align:left"> 9 textures per material, cubemap arrays, ESSL 3.10 </td></tr>
+<tr><td  style="text-align:left"> 3 </td><td  style="text-align:left"> 12 textures per material, cubemap arrays, ESSL 3.10 </td></tr>
+</table><center><div class="tablecaption"><b style="font-style:normal;">Table&nbsp;13:</b> Feature levels</div></center></div>
+</p><p>
+<dl><dt>Description</dt><dd><p>      Sets the feature level of the material. Each feature level defines a set of features the
+      material can use. If the material uses a feature not supported by the selected level, <code>matc</code>
+      will generate an error during compilation. A given feature level is guaranteed to support
+      all features of lower feature levels.
+</p></dd></dl></p><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>Bugs</dt></td><td><dd><p>      <code>matc</code> doesn't verify that a material is not using features above its selected feature level.
+</p></dd></td></tr></table></dl></p>
+<a class="target" name="general:shadingmodel">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/general:shadingmodel">&nbsp;</a><a class="target" name="toc4.2.3">&nbsp;</a><h3>General: shadingModel</h3>
+<p>
+
+<dl><table><tr valign=top><td><dt>Type</dt></td><td><dd><p>     <code>string</code>
+</p></dd></td></tr><tr valign=top><td><dt>Value</dt></td><td><dd><p>      Any of <code>lit</code>, <code>subsurface</code>, <code>cloth</code>, <code>unlit</code>, <code>specularGlossiness</code>. Defaults to <code>lit</code>.
+</p></dd></td></tr><tr valign=top><td><dt>Description</dt></td><td><dd><p>      Selects the material model as described in the <a href="#materialmodels" target="_self">Material models</a> 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">&quot;subsurface&quot;</span>
+<span class="line"></span><span class="hljs-punctuation">}</span></code></pre>
+<a class="target" name="general:parameters">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/general:parameters">&nbsp;</a><a class="target" name="toc4.2.4">&nbsp;</a><h3>General: parameters</h3>
+<p>
+
+<dl><dt>Type</dt><dd><p>     array of parameter objects
+</p></dd><dt>Value</dt><dd><p>      Each entry is an object with the properties <code>name</code> and <code>type</code>, both of <code>string</code> type. The
+      name must be a valid GLSL identifier. Entries also have an optional <code>precision</code>, which can be
+      one of <code>default</code> (best precision for the platform, typically <code>high</code> on desktop, <code>medium</code> on
+      mobile), <code>low</code>, <code>medium</code>, <code>high</code>. The type must be one of the types described in
+      <a href="#table_materialparamstypes" target="_self">table&nbsp;14</a>.
+</p></dd></dl><div class='table'>
+<a class="target" name="table_materialparamstypes">&nbsp;</a><table class="table longtable"><tr><th  style="text-align:left"> Type </th><th  style="text-align:left"> Description </th></tr>
+<tr><td  style="text-align:left"> bool </td><td  style="text-align:left"> Single boolean </td></tr>
+<tr><td  style="text-align:left"> bool2 </td><td  style="text-align:left"> Vector of 2 booleans </td></tr>
+<tr><td  style="text-align:left"> bool3 </td><td  style="text-align:left"> Vector of 3 booleans </td></tr>
+<tr><td  style="text-align:left"> bool4 </td><td  style="text-align:left"> Vector of 4 booleans </td></tr>
+<tr><td  style="text-align:left"> float </td><td  style="text-align:left"> Single float </td></tr>
+<tr><td  style="text-align:left"> float2 </td><td  style="text-align:left"> Vector of 2 floats </td></tr>
+<tr><td  style="text-align:left"> float3 </td><td  style="text-align:left"> Vector of 3 floats </td></tr>
+<tr><td  style="text-align:left"> float4 </td><td  style="text-align:left"> Vector of 4 floats </td></tr>
+<tr><td  style="text-align:left"> int </td><td  style="text-align:left"> Single integer </td></tr>
+<tr><td  style="text-align:left"> int2 </td><td  style="text-align:left"> Vector of 2 integers </td></tr>
+<tr><td  style="text-align:left"> int3 </td><td  style="text-align:left"> Vector of 3 integers </td></tr>
+<tr><td  style="text-align:left"> int4 </td><td  style="text-align:left"> Vector of 4 integers </td></tr>
+<tr><td  style="text-align:left"> uint </td><td  style="text-align:left"> Single unsigned integer </td></tr>
+<tr><td  style="text-align:left"> uint2 </td><td  style="text-align:left"> Vector of 2 unsigned integers </td></tr>
+<tr><td  style="text-align:left"> uint3 </td><td  style="text-align:left"> Vector of 3 unsigned integers </td></tr>
+<tr><td  style="text-align:left"> uint4 </td><td  style="text-align:left"> Vector of 4 unsigned integers </td></tr>
+<tr><td  style="text-align:left"> float3&times;3 </td><td  style="text-align:left"> Matrix of 3&times;3 floats </td></tr>
+<tr><td  style="text-align:left"> float4&times;4 </td><td  style="text-align:left"> Matrix of 4&times;4 floats </td></tr>
+<tr><td  style="text-align:left"> sampler2d </td><td  style="text-align:left"> 2D texture </td></tr>
+<tr><td  style="text-align:left"> sampler2dArray </td><td  style="text-align:left"> Array of 2D textures </td></tr>
+<tr><td  style="text-align:left"> samplerExternal </td><td  style="text-align:left"> External texture (platform-specific) </td></tr>
+<tr><td  style="text-align:left"> samplerCubemap </td><td  style="text-align:left"> Cubemap texture </td></tr>
+</table><center><div class="tablecaption"><b style="font-style:normal;">Table&nbsp;14:</b> Material parameter types</div></center></div>
+</p><p>
+<dl><dt>Samplers</dt><dd><p>      Sampler types can also specify a <code>format</code> which can be either <code>int</code> or <code>float</code> (defaults to
+      <code>float</code>).
+</p></dd><dt>Arrays</dt><dd><p>      A parameter can define an array of values by appending <code>[size]</code> after the type name, where
+      <code>size</code> is a positive integer. For instance: <code>float[9]</code> declares an array of nine <code>float</code>
+      values. This syntax does not apply to samplers as arrays are treated as separate types.
+</p></dd><dt>Description</dt><dd><p>      Lists the parameters required by your material. These parameters can be set at runtime using
+      Filament's material API. Accessing parameters from the shaders varies depending on the type of
+      parameter:
+</p><p>
+<ul>
+    <li class="minus"><strong class="asterisk">Samplers types</strong>: use the parameter name prefixed with <code>materialParams_</code>. For instance,
+          <code>materialParams_myTexture</code>.
+</li>
+    <li class="minus"><strong class="asterisk">Other types</strong>: use the parameter name as the field of a structure called <code>materialParams</code>.
+          For instance, <code>materialParams.myColor</code>.</li></ul>
+</p></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>
+<a class="target" name="general:constants">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/general:constants">&nbsp;</a><a class="target" name="toc4.2.5">&nbsp;</a><h3>General: constants</h3>
+<p>
+
+<dl><dt>Type</dt><dd><p>    array of constant objects
+</p></dd><dt>Value</dt><dd><p>    Each entry is an object with the properties <code>name</code> and <code>type</code>, both of <code>string</code> type. The name
+    must be a valid GLSL identifier. Entries also have an optional <code>default</code>, which can either be a
+    <code>bool</code> or <code>number</code>, depending on the <code>type</code> of the constant. The type must be one of the types
+    described in <a href="#table_materialconstantstypes" target="_self">table&nbsp;15</a>.
+</p></dd></dl><div class='table'>
+<a class="target" name="table_materialconstantstypes">&nbsp;</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&nbsp;15:</b> Material constants types</div></center></div>
+</p><p>
+<dl><dt>Description</dt><dd><p>    Lists the constant parameters accepted by your material. These constants can be set, or
+    &ldquo;specialized&rdquo;, at runtime when loading a material package. Multiple materials can be loaded from
+    the same material package with differing constant parameter specializations. Once a material is
+    loaded from a material package, its constant parameters cannot be changed. Compared to regular
+    parameters, constant parameters allow the compiler to generate more efficient code. Access
+    constant parameters from the shader by prefixing the name with <code>materialConstant_</code>. For example,
+    a constant parameter named <code>myConstant</code> is accessed in the shader as
+    <code>materialConstant_myConstant</code>. If a constant parameter is not set at runtime, the default is
+    used.
+</p></dd></dl></p><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>
+<a class="target" name="general:variantfilter">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/general:variantfilter">&nbsp;</a><a class="target" name="toc4.2.6">&nbsp;</a><h3>General: variantFilter</h3>
+<p>
+
+<dl><dt>Type</dt><dd><p>     array of <code>string</code>
+</p></dd><dt>Value</dt><dd><p>      Each entry must be any of <code>dynamicLighting</code>, <code>directionalLighting</code>, <code>shadowReceiver</code>,
+      <code>skinning</code>, <code>ssr</code>, or <code>stereo</code>.
+</p></dd><dt>Description</dt><dd><p>      Used to specify a list of shader variants that the application guarantees will never be
+      needed. These shader variants are skipped during the code generation phase, thus reducing
+      the overall size of the material.
+      Note that some variants may automatically be filtered out. For instance, all lighting related
+      variants (<code>directionalLighting</code>, etc.) are filtered out when compiling an <code>unlit</code> material.
+      Use the variant filter with caution, filtering out a variant required at runtime may lead
+      to crashes.
+</p></dd></dl>Description of the variants:
+</p><p>
+<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">&quot;Invisible shadow plane&quot;</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>
+<a class="target" name="general:flipuv">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/general:flipuv">&nbsp;</a><a class="target" name="toc4.2.7">&nbsp;</a><h3>General: flipUV</h3>
+<p>
+
+<dl><dt>Type</dt><dd><p>     <code>boolean</code>
+</p></dd><dt>Value</dt><dd><p>      <code>true</code> or <code>false</code>. Defaults to <code>true</code>.
+</p></dd><dt>Description</dt><dd><p>     When set to <code>true</code> (default value), the Y coordinate of UV attributes will be flipped when
+     read by this material's vertex shader. Flipping is equivalent to <code>y = 1.0 - y</code>. When set
+     to <code>false</code>, flipping is disabled and the UV attributes are read as is.
+</p></dd></dl></p><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>
+<a class="target" name="general:quality">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/general:quality">&nbsp;</a><a class="target" name="toc4.2.8">&nbsp;</a><h3>General: quality</h3>
+<p>
+
+<dl><dt>Type</dt><dd><p>     <code>string</code>
+</p></dd><dt>Value</dt><dd><p>      Any of <code>low</code>, <code>normal</code>, <code>high</code>, <code>default</code>. Defaults to <code>default</code>.
+</p></dd><dt>Description</dt><dd><p>     Set some global quality parameters of the material. <code>low</code> enables optimizations that can
+     slightly affect correctness and is the default on mobile platforms. <code>normal</code> does not affect
+     correctness and is otherwise similar to <code>low</code>. <code>high</code> enables quality settings that can
+     adversely affect performance and is the default on desktop platforms.
+</p></dd></dl></p><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>
+<a class="target" name="general:instanced">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/general:instanced">&nbsp;</a><a class="target" name="toc4.2.9">&nbsp;</a><h3>General: instanced</h3>
+<p>
+
+<dl><dt>Type</dt><dd><p>     <code>boolean</code>
+</p></dd><dt>Value</dt><dd><p>      <code>true</code> or <code>false</code>. Defaults to <code>false</code>.
+</p></dd><dt>Description</dt><dd><p>     Allows a material to access the instance index (i.e.: <strong class="asterisk"><code>gl_InstanceIndex</code></strong>) of instanced
+     primitives using <code>getInstanceIndex()</code> in the material's shader code. Never use
+     <strong class="asterisk"><code>gl_InstanceIndex</code></strong> directly. This is typically used with
+     <code>RenderableManager::Builder::instances()</code>. <code>getInstanceIndex()</code> is available in both the
+     vertex and fragment shader.
+</p></dd></dl></p><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>
+<a class="target" name="general:vertexdomaindevicejittered">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/general:vertexdomaindevicejittered">&nbsp;</a><a class="target" name="toc4.2.10">&nbsp;</a><h3>General: vertexDomainDeviceJittered</h3>
+<p>
+
+<dl><dt>Type</dt><dd><p>     <code>boolean</code>
+</p></dd><dt>Value</dt><dd><p>      <code>true</code> or <code>false</code>. Defaults to <code>false</code>.
+</p></dd><dt>Description</dt><dd><p>     Only meaningful for <code>vertexDomain:Device</code> materials, this parameter specifies whether the
+     filament clip-space transforms need to be applied or not, which affects TAA and guard bands.
+     Generally it needs to be applied because by definition <code>vertexDomain:Device</code> materials
+     vertices are not transformed and used <em class="asterisk">as is</em>.
+     However, if the vertex shader uses for instance <code>getViewFromClipMatrix()</code> (or other
+     matrices based on the projection), the clip-space transform is already applied.
+     Setting this parameter incorrectly can prevent TAA or the guard bands to work correctly.
+</p></dd></dl></p><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>
+<a class="target" name="vertexandattributes:requires">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/vertexandattributes:requires">&nbsp;</a><a class="target" name="toc4.2.11">&nbsp;</a><h3>Vertex and attributes: requires</h3>
+<p>
+
+<dl><dt>Type</dt><dd><p>     array of <code>string</code>
+</p></dd><dt>Value</dt><dd><p>      Each entry must be any of <code>uv0</code>, <code>uv1</code>, <code>color</code>, <code>position</code>, <code>tangents</code>, <code>custom0</code>
+      through <code>custom7</code>.
+</p></dd><dt>Description</dt><dd><p>      Lists the vertex attributes required by the material. The <code>position</code> attribute is always
+      required and does not need to be specified. The <code>tangents</code> attribute is automatically required
+      when selecting any shading model that is not <code>unlit</code>. See the shader sections of this document
+      for more information on how to access these attributes from the shaders.
+</p></dd></dl></p><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>
+<a class="target" name="vertexandattributes:variables">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/vertexandattributes:variables">&nbsp;</a><a class="target" name="toc4.2.12">&nbsp;</a><h3>Vertex and attributes: variables</h3>
+<p>
+
+<dl><dt>Type</dt><dd><p>     array of <code>string</code>
+</p></dd><dt>Value</dt><dd><p>      Up to 4 strings, each must be a valid GLSL identifier.
+</p></dd><dt>Description</dt><dd><p>      Defines custom interpolants (or variables) that are output by the material's vertex shader.
+      Each entry of the array defines the name of an  interpolant. The full name in the fragment
+      shader is the name of the interpolant with the <code>variable_</code> prefix. For instance, if you
+      declare a variable called <code>eyeDirection</code> you can access it in the fragment shader using
+      <code>variable_eyeDirection</code>. In the vertex shader, the interpolant name is simply a member of
+      the <code>MaterialVertexInputs</code> structure (<code>material.eyeDirection</code> in your example). Each
+      interpolant is of type <code>float4</code> (<code>vec4</code>) in the shaders. By default the precision of the
+      interpolant is <code>highp</code> in <em class="asterisk">both</em> the vertex and fragment shaders.
+      An alternate syntax can be used to specify both the name and precision of the interpolant.
+      In this case the specified precision is used as-is in both fragment and vertex stages, in
+      particular if <code>default</code> is specified the default precision is used is the fragment shader
+      (<code>mediump</code>) and in the vertex shader (<code>highp</code>).
+</p></dd></dl></p><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>
+<a class="target" name="vertexandattributes:vertexdomain">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/vertexandattributes:vertexdomain">&nbsp;</a><a class="target" name="toc4.2.13">&nbsp;</a><h3>Vertex and attributes: vertexDomain</h3>
+<p>
+
+<dl><dt>Type</dt><dd><p>     <code>string</code>
+</p></dd><dt>Value</dt><dd><p>      Any of <code>object</code>, <code>world</code>, <code>view</code>, <code>device</code>. Defaults to <code>object</code>.
+</p></dd><dt>Description</dt><dd><p>      Defines the domain (or coordinate space) of the rendered mesh. The domain influences how the
+      vertices are transformed in the vertex shader. The possible domains are:
+</p><p>
+<ul>
+     <li class="minus"><strong class="asterisk">Object</strong>: the vertices are defined in the object (or model) coordinate space. The
+            vertices are transformed using the rendered object's transform matrix
+</li>
+     <li class="minus"><strong class="asterisk">World</strong>: the vertices are defined in world coordinate space. The vertices are not
+            transformed using the rendered object's transform.
+</li>
+     <li class="minus"><strong class="asterisk">View</strong>: the vertices are defined in view (or eye or camera) coordinate space. The
+            vertices are not transformed using the rendered object's transform.
+</li>
+     <li class="minus"><strong class="asterisk">Device</strong>:  the vertices are defined in normalized device (or clip) coordinate space.
+            The vertices are not transformed using the rendered object's transform.</li></ul>
+</p></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>
+<a class="target" name="vertexandattributes:interpolation">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/vertexandattributes:interpolation">&nbsp;</a><a class="target" name="toc4.2.14">&nbsp;</a><h3>Vertex and attributes: interpolation</h3>
+<p>
+
+<dl><dt>Type</dt><dd><p>     <code>string</code>
+</p></dd><dt>Value</dt><dd><p>      Any of <code>smooth</code>, <code>flat</code>. Defaults to <code>smooth</code>.
+</p></dd><dt>Description</dt><dd><p>      Defines how interpolants (or variables) are interpolated between vertices. When this property
+      is set to <code>smooth</code>, a perspective correct interpolation is performed on each interpolant.
+      When set to <code>flat</code>, no interpolation is performed and all the fragments within a given
+      triangle will be shaded the same.
+</p></dd></dl></p><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>
+<a class="target" name="blendingandtransparency:blending">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/blendingandtransparency:blending">&nbsp;</a><a class="target" name="toc4.2.15">&nbsp;</a><h3>Blending and transparency: blending</h3>
+<p>
+
+<dl><dt>Type</dt><dd><p>     <code>string</code>
+</p></dd><dt>Value</dt><dd><p>      Any of <code>opaque</code>, <code>transparent</code>, <code>fade</code>, <code>add</code>, <code>masked</code>, <code>multiply</code>, <code>screen</code>, <code>custom</code>. Defaults to <code>opaque</code>.
+</p></dd><dt>Description</dt><dd><p>      Defines how/if the rendered object is blended with the content of the render target.
+      The possible blending modes are:
+</p><p>
+<ul>
+    <li class="minus"><strong class="asterisk">Opaque</strong>: blending is disabled, the alpha channel of the material's output is ignored.
+</li>
+    <li class="minus"><strong class="asterisk">Transparent</strong>: blending is enabled. The material's output is alpha composited with the
+          render target, using Porter-Duff's <code>source over</code> rule. This blending mode assumes
+          pre-multiplied alpha.
+</li>
+    <li class="minus"><strong class="asterisk">Fade</strong>: acts as <code>transparent</code> but transparency is also applied to specular lighting. In
+          <code>transparent</code> mode, the material's alpha values only applies to diffuse lighting. This
+          blending mode is useful to fade lit objects in and out.
+</li>
+    <li class="minus"><strong class="asterisk">Add</strong>: blending is enabled. The material's output is added to the content of the
+          render target.
+</li>
+    <li class="minus"><strong class="asterisk">Multiply</strong>: blending is enabled. The material's output is multiplied with the content of the
+          render target, darkening the content.
+</li>
+    <li class="minus"><strong class="asterisk">Screen</strong>: blending is enabled. Effectively the opposite of the <code>multiply</code>, the content of the
+          render target is brightened.
+</li>
+    <li class="minus"><strong class="asterisk">Masked</strong>: blending is disabled. This blending mode enables alpha masking. The alpha channel
+          of the material's output defines whether a fragment is discarded or not. Additionally,
+          ALPHA_TO_COVERAGE is enabled for non-translucent views. See the maskThreshold section for more
+          information.
+</li>
+    <li class="minus"><strong class="asterisk">Custom</strong>: blending is enabled. But the blending function is user specified. See <code>blendFunction</code>.</li></ul>
+</p></dd></dl><div class="admonition note">When <code>blending</code> is set to <code>masked</code>, alpha to coverage is automatically enabled for the material.
+    If this behavior is undesirable, refer to the <a href="#rasterization:alphatocoverage" target="_self">Rasterization: alphaToCoverage</a> section to turn
+    alpha 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>
+<a class="target" name="blendingandtransparency:blendfunction">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/blendingandtransparency:blendfunction">&nbsp;</a><a class="target" name="toc4.2.16">&nbsp;</a><h3>Blending and transparency: blendFunction</h3>
+<p>
+
+<dl><dt>Type</dt><dd><p>     <code>object</code>
+</p></dd><dt>Fields</dt><dd><p>      <code>srcRGB</code>, <code>srcA</code>, <code>dstRGB</code>, <code>dstA</code>
+</p></dd><dt>Description</dt><dd><p>        - <em class="asterisk">srcRGB</em>: source function applied to the RGB channels
+        - <em class="asterisk">srcA</em>: source function applied to the alpha channel
+        - <em class="asterisk">srcRGB</em>: destination function applied to the RGB channels
+        - <em class="asterisk">srcRGB</em>: destination function applied to the alpha channel
+        The values possible for each functions are one of <code>zero</code>, <code>one</code>, <code>srcColor</code>, <code>oneMinusSrcColor</code>,
+               <code>dstColor</code>, <code>oneMinusDstColor</code>, <code>srcAlpha</code>, <code>oneMinusSrcAlpha</code>, <code>dstAlpha</code>,
+               <code>oneMinusDstAlpha</code>, <code>srcAlphaSaturate</code>
+</p></dd></dl></p><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>
+<a class="target" name="blendingandtransparency:postlightingblending">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/blendingandtransparency:postlightingblending">&nbsp;</a><a class="target" name="toc4.2.17">&nbsp;</a><h3>Blending and transparency: postLightingBlending</h3>
+<p>
+
+<dl><dt>Type</dt><dd><p>     <code>string</code>
+</p></dd><dt>Value</dt><dd><p>      Any of <code>opaque</code>, <code>transparent</code>, <code>add</code>. Defaults to <code>transparent</code>.
+</p></dd><dt>Description</dt><dd><p>      Defines how the <code>postLightingColor</code> material property is blended with the result of the
+      lighting computations. The possible blending modes are:
+</p><p>
+<ul>
+    <li class="minus"><strong class="asterisk">Opaque</strong>: blending is disabled, the material will output <code>postLightingColor</code> directly.
+</li>
+    <li class="minus"><strong class="asterisk">Transparent</strong>: blending is enabled. The material's computed color is alpha composited with
+          the <code>postLightingColor</code>, using Porter-Duff's <code>source over</code> rule. This blending mode assumes
+          pre-multiplied alpha.
+</li>
+    <li class="minus"><strong class="asterisk">Add</strong>: blending is enabled. The material's computed color is added to <code>postLightingColor</code>.
+</li>
+    <li class="minus"><strong class="asterisk">Multiply</strong>: blending is enabled. The material's computed color is multiplied with <code>postLightingColor</code>.
+</li>
+    <li class="minus"><strong class="asterisk">Screen</strong>: blending is enabled. The material's computed color is inverted and multiplied with <code>postLightingColor</code>,
+          and the result is added to the material's computed color.</li></ul>
+</p></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>
+<a class="target" name="blendingandtransparency:transparency">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/blendingandtransparency:transparency">&nbsp;</a><a class="target" name="toc4.2.18">&nbsp;</a><h3>Blending and transparency: transparency</h3>
+<p>
+
+<dl><dt>Type</dt><dd><p>     <code>string</code>
+</p></dd><dt>Value</dt><dd><p>      Any of <code>default</code>, <code>twoPassesOneSide</code> or <code>twoPassesTwoSides</code>. Defaults to <code>default</code>.
+</p></dd><dt>Description</dt><dd><p>      Controls how transparent objects are rendered. It is only valid when the <code>blending</code> mode is
+      not <code>opaque</code> and <code>refractionMode</code> is <code>none</code>. None of these methods can accurately render
+      concave geometry, but in practice they are often good enough.
+</p></dd></dl>The three possible transparency modes are:
+</p><p>
+<ul>
+<li class="minus"><code>default</code>: the transparent object is rendered normally (as seen in <a href="#figure_transparencydefault" target="_self">figure&nbsp;33</a>),
+   honoring the <code>culling</code> mode, etc.
+</li>
+<li class="minus"><code>twoPassesOneSide</code>: the transparent object is first rendered in the depth buffer, then again in
+  the color buffer, honoring the <code>culling</code> mode. This effectively renders only half of the
+  transparent object as shown in <a href="#figure_transparencytwopassesoneside" target="_self">figure&nbsp;34</a>.
+</li>
+<li class="minus"><code>twoPassesTwoSides</code>: the transparent object is rendered twice in the color buffer: first with its
+  back faces, then with its front faces. This mode lets you render both set of faces while reducing
+  or eliminating sorting issues, as shown in <a href="#figure_transparencytwopassestwosides" target="_self">figure&nbsp;35</a>.
+  <code>twoPassesTwoSides</code> 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>
+<center><div class="image" style=""><a class="target" name="figure_transparencydefault">&nbsp;</a><a href="../images/screenshot_transparency_default.png" target="_blank"><img class="markdeep" src="../images/screenshot_transparency_default.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;33:</b> This double sided model shows the type of sorting issues transparent
+</span></center></div></center>
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_transparencytwopassesoneside">&nbsp;</a><a href="../images/screenshot_twopasses_oneside.png" target="_blank"><img class="markdeep" src="../images/screenshot_twopasses_oneside.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;34:</b> In <code>twoPassesOneSide</code> mode, only one set of faces is visible
+</span></center></div></center>
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_transparencytwopassestwosides">&nbsp;</a><a href="../images/screenshot_twopasses_twosides.png" target="_blank"><img class="markdeep" src="../images/screenshot_twopasses_twosides.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;35:</b> In <code>twoPassesTwoSides</code> mode, both set of faces are visible
+</span></center></div></center>
+</p>
+<a class="target" name="blendingandtransparency:maskthreshold">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/blendingandtransparency:maskthreshold">&nbsp;</a><a class="target" name="toc4.2.19">&nbsp;</a><h3>Blending and transparency: maskThreshold</h3>
+<p>
+
+<dl><dt>Type</dt><dd><p>     <code>number</code>
+</p></dd><dt>Value</dt><dd><p>      A value between <code>0.0</code> and <code>1.0</code>. Defaults to <code>0.4</code>.
+</p></dd><dt>Description</dt><dd><p>      Sets the minimum alpha value a fragment must have to not be discarded when the <code>blending</code> mode
+      is set to <code>masked</code>. If the fragment is not discarded, its source alpha is set to 1. When the
+      blending mode is not <code>masked</code>, this value is ignored. This value can be used to controlled the
+      appearance of alpha-masked objects.
+</p></dd></dl></p><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>
+<a class="target" name="blendingandtransparency:refractionmode">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/blendingandtransparency:refractionmode">&nbsp;</a><a class="target" name="toc4.2.20">&nbsp;</a><h3>Blending and transparency: refractionMode</h3>
+<p>
+
+<dl><dt>Type</dt><dd><p>     <code>string</code>
+</p></dd><dt>Value</dt><dd><p>      Any of <code>none</code>, <code>cubemap</code>, <code>screenspace</code>. Defaults to <code>none</code>.
+</p></dd><dt>Description</dt><dd><p>      Activates refraction when set to anything but <code>none</code>. A value of <code>cubemap</code> will only use the
+      IBL cubemap as source of refraction, while this is significantly more efficient, no scene
+      objects will be refracted, only the distant environment encoded in the cubemap. This mode is
+      adequate for an object viewer for instance. A value of <code>screenspace</code> will employ the more
+      advanced screen-space refraction algorithm which allows opaque objects in the scene to be
+      refracted. In <code>cubemap</code> mode, refracted rays are assumed to emerge from the center of the
+      object and the <code>thickness</code> parameter is only used for computing the absorption, but has no
+      impact on the refraction itself. In <code>screenspace</code> mode, refracted rays are assumed to travel
+      parallel to the view direction when they exit the refractive medium.
+</p></dd></dl></p><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>
+<a class="target" name="blendingandtransparency:refractiontype">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/blendingandtransparency:refractiontype">&nbsp;</a><a class="target" name="toc4.2.21">&nbsp;</a><h3>Blending and transparency: refractionType</h3>
+<p>
+
+<dl><dt>Type</dt><dd><p>     <code>string</code>
+</p></dd><dt>Value</dt><dd><p>      Any of <code>solid</code>, <code>thin</code>. Defaults to <code>solid</code>.
+</p></dd><dt>Description</dt><dd><p>      This is only meaningful when <code>refractionMode</code> is set to anything but <code>none</code>. <code>refractionType</code>
+      defines the refraction model used. <code>solid</code> is used for thick objects such as a crystal ball,
+      an ice cube or as sculpture. <code>thin</code> is used for thin objects such as a window, an ornament
+      ball or a soap bubble. In <code>solid</code> mode all refracive objects are assumed to be a sphere
+      tangent to the entry point and of radius <code>thickness</code>. In <code>thin</code> mode, all refractive objects
+      are assumed to be flat and thin and of thickness <code>thickness</code>.
+</p></dd></dl></p><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>
+<a class="target" name="rasterization:culling">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/rasterization:culling">&nbsp;</a><a class="target" name="toc4.2.22">&nbsp;</a><h3>Rasterization: culling</h3>
+<p>
+
+<dl><table><tr valign=top><td><dt>Type</dt></td><td><dd><p>     <code>string</code>
+</p></dd></td></tr><tr valign=top><td><dt>Value</dt></td><td><dd><p>      Any of <code>none</code>, <code>front</code>, <code>back</code>, <code>frontAndBack</code>. Defaults to <code>back</code>.
+</p></dd></td></tr><tr valign=top><td><dt>Description</dt></td><td><dd><p>      Defines which triangles should be culled: none, front-facing triangles, back-facing
+      triangles or all.
+</p></dd></td></tr></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>
+<a class="target" name="rasterization:colorwrite">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/rasterization:colorwrite">&nbsp;</a><a class="target" name="toc4.2.23">&nbsp;</a><h3>Rasterization: colorWrite</h3>
+<p>
+
+<dl><table><tr valign=top><td><dt>Type</dt></td><td><dd><p>     <code>boolean</code>
+</p></dd></td></tr><tr valign=top><td><dt>Value</dt></td><td><dd><p>      <code>true</code> or <code>false</code>. Defaults to <code>true</code>.
+</p></dd></td></tr><tr valign=top><td><dt>Description</dt></td><td><dd><p>      Enables or disables writes to the color buffer.
+</p></dd></td></tr></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>
+<a class="target" name="rasterization:depthwrite">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/rasterization:depthwrite">&nbsp;</a><a class="target" name="toc4.2.24">&nbsp;</a><h3>Rasterization: depthWrite</h3>
+<p>
+
+<dl><table><tr valign=top><td><dt>Type</dt></td><td><dd><p>     <code>boolean</code>
+</p></dd></td></tr><tr valign=top><td><dt>Value</dt></td><td><dd><p>      <code>true</code> or <code>false</code>. Defaults to <code>true</code> for opaque materials, <code>false</code> for transparent materials.
+</p></dd></td></tr><tr valign=top><td><dt>Description</dt></td><td><dd><p>      Enables or disables writes to the depth buffer.
+</p></dd></td></tr></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>
+<a class="target" name="rasterization:depthculling">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/rasterization:depthculling">&nbsp;</a><a class="target" name="toc4.2.25">&nbsp;</a><h3>Rasterization: depthCulling</h3>
+<p>
+
+<dl><dt>Type</dt><dd><p>     <code>boolean</code>
+</p></dd><dt>Value</dt><dd><p>      <code>true</code> or <code>false</code>. Defaults to <code>true</code>.
+</p></dd><dt>Description</dt><dd><p>      Enables or disables depth testing. When depth testing is disabled, an object rendered with
+      this material will always appear on top of other opaque objects.
+</p></dd></dl></p><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>
+<a class="target" name="rasterization:doublesided">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/rasterization:doublesided">&nbsp;</a><a class="target" name="toc4.2.26">&nbsp;</a><h3>Rasterization: doubleSided</h3>
+<p>
+
+<dl><dt>Type</dt><dd><p>     <code>boolean</code>
+</p></dd><dt>Value</dt><dd><p>      <code>true</code> or <code>false</code>. Defaults to <code>false</code>.
+</p></dd><dt>Description</dt><dd><p>      Enables two-sided rendering and its capability to be toggled at run time. When set to <code>true</code>,
+      <code>culling</code> is automatically set to <code>none</code>; if the triangle is back-facing, the triangle's
+      normal is flipped to become front-facing. When explicitly set to <code>false</code>, this allows the
+      double-sidedness to be toggled at run time.
+</p></dd></dl></p><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">&quot;Double sided material&quot;</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>
+<a class="target" name="rasterization:alphatocoverage">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/rasterization:alphatocoverage">&nbsp;</a><a class="target" name="toc4.2.27">&nbsp;</a><h3>Rasterization: alphaToCoverage</h3>
+<p>
+
+<dl><dt>Type</dt><dd><p>     <code>boolean</code>
+</p></dd><dt>Value</dt><dd><p>      <code>true</code> or <code>false</code>. Defaults to <code>false</code>.
+</p></dd><dt>Description</dt><dd><p>      Enables or disables alpha to coverage. When alpha to coverage is enabled, the coverage of
+      fragment is derived from its alpha. This property is only meaningful when MSAA is enabled.
+      Note: setting <code>blending</code> to <code>masked</code> automatically enables alpha to coverage. If this is not
+      desired, you can override this behavior by setting alpha to coverage to false as in the
+      example below.
+</p></dd></dl></p><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">&quot;Alpha to coverage&quot;</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>
+<a class="target" name="lighting:reflections">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/lighting:reflections">&nbsp;</a><a class="target" name="toc4.2.28">&nbsp;</a><h3>Lighting: reflections</h3>
+<p>
+
+<dl><dt>Type</dt><dd><p>     <code>string</code>
+</p></dd><dt>Value</dt><dd><p>      <code>default</code> or <code>screenspace</code>. Defaults to <code>default</code>.
+</p></dd><dt>Description</dt><dd><p>      Controls the source of specular reflections for this material. When this property is set to
+      <code>default</code>, reflections only come image-based lights. When this property is set to
+      <code>screenspace</code>, reflections come from the screen space's color buffer in addition to
+      image-based lights.
+</p></dd></dl></p><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">&quot;Glossy metal&quot;</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>
+<a class="target" name="lighting:shadowmultiplier">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/lighting:shadowmultiplier">&nbsp;</a><a class="target" name="toc4.2.29">&nbsp;</a><h3>Lighting: shadowMultiplier</h3>
+<p>
+
+<dl><dt>Type</dt><dd><p>     <code>boolean</code>
+</p></dd><dt>Value</dt><dd><p>      <code>true</code> or <code>false</code>. Defaults to <code>false</code>.
+</p></dd><dt>Description</dt><dd><p>      Only available in the <code>unlit</code> shading model. If this property is enabled, the final color
+      computed by the material is multiplied by the shadowing factor (or visibility). This allows to
+      create transparent shadow-receiving objects (for instance an invisible ground plane in AR).
+      This is only supported with shadows from directional lights.
+</p></dd></dl></p><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">&quot;Invisible shadow plane&quot;</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>
+<a class="target" name="lighting:transparentshadow">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/lighting:transparentshadow">&nbsp;</a><a class="target" name="toc4.2.30">&nbsp;</a><h3>Lighting: transparentShadow</h3>
+<p>
+
+<dl><dt>Type</dt><dd><p>     <code>boolean</code>
+</p></dd><dt>Value</dt><dd><p>      <code>true</code> or <code>false</code>. Defaults to <code>false</code>.
+</p></dd><dt>Description</dt><dd><p>      Enables transparent shadows on this material. When this feature is enabled, Filament emulates
+      transparent shadows using a dithering pattern: they work best with variance shadow maps (VSM)
+      and blurring enabled. The opacity of the shadow derives directly from the alpha channel of
+      the material's <code>baseColor</code> property. Transparent shadows can be enabled on opaque objects,
+      making them compatible with refractive/transmissive objects that are otherwise considered
+      opaque.
+</p></dd></dl></p><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">&quot;Clear plastic with stickers&quot;</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 class="target" name="figure_transparentshadow">&nbsp;</a><a href="../images/screenshot_transparent_shadows.jpg" target="_blank"><img class="markdeep" src="../images/screenshot_transparent_shadows.jpg" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;36:</b> Objects rendered with transparent shadows and blurry VSM with a
+</span></center></div></center>
+</p>
+<a class="target" name="lighting:clearcoatiorchange">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/lighting:clearcoatiorchange">&nbsp;</a><a class="target" name="toc4.2.31">&nbsp;</a><h3>Lighting: clearCoatIorChange</h3>
+<p>
+
+<dl><dt>Type</dt><dd><p>     <code>boolean</code>
+</p></dd><dt>Value</dt><dd><p>      <code>true</code> or <code>false</code>. Defaults to <code>true</code>.
+</p></dd><dt>Description</dt><dd><p>     When adding a clear coat layer, the change in index of refraction (IoR) is taken into account
+     to modify the specular color of the base layer. This appears to darken <code>baseColor</code>. When this
+     effect is disabled, <code>baseColor</code> is left unmodified. See <a href="#figure_clearcoatiorchange" target="_self">figure&nbsp;37</a> for an
+     example 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>
+<center><div class="image" style=""><a class="target" name="figure_clearcoatiorchange">&nbsp;</a><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"><b style="font-style:normal;">Figure&nbsp;37:</b> The same rough metallic ball with a clear coat layer rendered
+</span></center></div></center>
+</p>
+<a class="target" name="lighting:multibounceambientocclusion">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/lighting:multibounceambientocclusion">&nbsp;</a><a class="target" name="toc4.2.32">&nbsp;</a><h3>Lighting: multiBounceAmbientOcclusion</h3>
+<p>
+
+<dl><dt>Type</dt><dd><p>     <code>boolean</code>
+</p></dd><dt>Value</dt><dd><p>      <code>true</code> or <code>false</code>. Defaults to <code>false</code> on mobile, <code>true</code> on desktop.
+</p></dd><dt>Description</dt><dd><p>     Multi-bounce ambient occlusion takes into account interreflections when applying ambient
+     occlusion to image-based lighting. Turning this feature on avoids over-darkening occluded
+     areas. It also takes the surface color into account to generate colored ambient occlusion.
+     <a href="#figure_multibounceao" target="_self">Figure&nbsp;38</a> compares the ambient occlusion term of a surface with and without
+     multi-bounce ambient occlusion. Notice how multi-bounce ambient occlusion introduces color
+     in the occluded areas. <a href="#figure_multibounceaoanimated" target="_self">Figure&nbsp;39</a> toggles between multi-bounce ambient
+     occlusion on and off on a lit brick material to highlight the effects of this property.
+</p></dd></dl></p><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>
+<center><div class="image" style=""><a class="target" name="figure_multibounceao">&nbsp;</a><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"><b style="font-style:normal;">Figure&nbsp;38:</b> Brick texture amient occlusion map rendered with multi-bounce ambient
+</span></center></div></center>
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_multibounceaoanimated">&nbsp;</a><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"><b style="font-style:normal;">Figure&nbsp;39:</b> Brick texture rendered with multi-bounce ambient
+</span></center></div></center>
+</p>
+<a class="target" name="lighting:specularambientocclusion">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/lighting:specularambientocclusion">&nbsp;</a><a class="target" name="toc4.2.33">&nbsp;</a><h3>Lighting: specularAmbientOcclusion</h3>
+<p>
+
+<dl><dt>Type</dt><dd><p>     <code>string</code>
+</p></dd><dt>Value</dt><dd><p>      <code>none</code>, <code>simple</code> or <code>bentNormals</code>. Defaults to <code>none</code> on mobile, <code>simple</code> on desktop. For
+      compatibility reasons, <code>true</code> and <code>false</code> are also accepted and map respectively to <code>simple</code>
+      and <code>none</code>.
+</p></dd><dt>Description</dt><dd><p>     Static ambient occlusion maps and dynamic ambient occlusion (SSAO, etc.) apply to diffuse
+     indirect lighting. When setting this property to other than <code>none</code>, a new ambient occlusion
+     term is derived from the surface roughness and applied to specular indirect lighting.
+     This effect helps remove unwanted specular reflections as shown in <a href="#figure_specularao" target="_self">figure&nbsp;40</a>.
+     When this value is set to <code>simple</code>, Filament uses a cheap but approximate method of computing
+     the specular ambient occlusion term. If this value is set to <code>bentNormals</code>, Filament will use
+     a much more accurate but much more expensive method.
+</p></dd></dl></p><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 class="target" name="figure_specularao">&nbsp;</a><a href="../images/screenshot_specular_ao.gif" target="_blank"><img class="markdeep" src="../images/screenshot_specular_ao.gif" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;40:</b> Comparison of specular ambient occlusion on and off. The effect is
+</span></center></div></center>
+</p>
+<a class="target" name="anti-aliasing:specularantialiasing">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/anti-aliasing:specularantialiasing">&nbsp;</a><a class="target" name="toc4.2.34">&nbsp;</a><h3>Anti-aliasing: specularAntiAliasing</h3>
+<p>
+
+<dl><dt>Type</dt><dd><p>     <code>boolean</code>
+</p></dd><dt>Value</dt><dd><p>      <code>true</code> or <code>false</code>. Defaults to <code>false</code>.
+</p></dd><dt>Description</dt><dd><p>     Reduces specular aliasing and preserves the shape of specular highlights as an object moves
+     away from the camera. This anti-aliasing solution is particularly effective on glossy materials
+     (low roughness) but increases the cost of the material. The strength of the anti-aliasing
+     effect can be controlled using two other properties: <code>specularAntiAliasingVariance</code> and
+     <code>specularAntiAliasingThreshold</code>.
+</p></dd></dl></p><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>
+<a class="target" name="anti-aliasing:specularantialiasingvariance">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/anti-aliasing:specularantialiasingvariance">&nbsp;</a><a class="target" name="toc4.2.35">&nbsp;</a><h3>Anti-aliasing: specularAntiAliasingVariance</h3>
+<p>
+
+<dl><dt>Type</dt><dd><p>     <code>float</code>
+</p></dd><dt>Value</dt><dd><p>      A value between 0 and 1, set to 0.15 by default.
+</p></dd><dt>Description</dt><dd><p>     Sets the screen space variance of the filter kernel used when applying specular anti-aliasing.
+     Higher values will increase the effect of the filter but may increase roughness in unwanted
+     areas.
+</p></dd></dl></p><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>
+<a class="target" name="anti-aliasing:specularantialiasingthreshold">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/anti-aliasing:specularantialiasingthreshold">&nbsp;</a><a class="target" name="toc4.2.36">&nbsp;</a><h3>Anti-aliasing: specularAntiAliasingThreshold</h3>
+<p>
+
+<dl><dt>Type</dt><dd><p>     <code>float</code>
+</p></dd><dt>Value</dt><dd><p>      A value between 0 and 1, set to 0.2 by default.
+</p></dd><dt>Description</dt><dd><p>     Sets the clamping threshold used to suppress estimation errors when applying specular
+     anti-aliasing. When set to 0, specular anti-aliasing is disabled.
+</p></dd></dl></p><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>
+<a class="target" name="shading:customsurfaceshading">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/shading:customsurfaceshading">&nbsp;</a><a class="target" name="toc4.2.37">&nbsp;</a><h3>Shading: customSurfaceShading</h3>
+<p>
+
+<dl><dt>Type</dt><dd><p>     <code>bool</code>
+</p></dd><dt>Value</dt><dd><p>      <code>true</code> or <code>false</code>. Defaults to <code>false</code>.
+</p></dd><dt>Description</dt><dd><p>     Enables custom surface shading when set to true. When surface shading is enabled, the fragment
+     shader must provide an extra function that will be invoked for every light in the scene that
+     may influence the current fragment. Please refer to the <a href="#customsurfaceshading" target="_self">Custom surface shading</a> section below
+     for 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>
+<a class="target" name="vertexblock">&nbsp;</a><a class="target" name="materialdefinitions/vertexblock">&nbsp;</a><a class="target" name="toc4.3">&nbsp;</a><h2>Vertex block</h2>
+<p>
+
+The vertex block is optional and can be used to control the vertex shading stage of the material.
+The vertex block must contain valid
+<a href="https://www.khronos.org/registry/OpenGL/specs/es/3.0/GLSL_ES_Specification_3.00.pdf">ESSL 3.0</a> code
+(the version of GLSL supported in OpenGL ES 3.0). You are free to create multiple functions inside
+the vertex block but you <strong class="asterisk">must</strong> declare the <code>materialVertex</code> function:
+</p><pre class="listing tilde"><code><span class="line"></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 function will be invoked automatically at runtime by the shading system and gives you the
+ability to read and modify material properties using the <code>MaterialVertexInputs</code> structure. This full
+definition of the structure can be found in the <a href="#materialvertexinputs" target="_self">Material vertex inputs</a> section.
+</p><p>
+You can use this structure to compute your custom variables/interpolants or to modify the value of
+the attributes. For instance, the following vertex blocks modifies both the color and the UV
+coordinates of the vertex over time:
+</p><pre class="listing tilde"><code><span class="line"></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 addition to the <code>MaterialVertexInputs</code> structure, your vertex shading code can use all the public
+APIs listed in the <a href="#shaderpublicapis" target="_self">Shader public APIs</a> section.
+</p>
+<a class="target" name="materialvertexinputs">&nbsp;</a><a class="target" name="materialdefinitions/vertexblock/materialvertexinputs">&nbsp;</a><a class="target" name="toc4.3.1">&nbsp;</a><h3>Material vertex inputs</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 tip"><div class="admonition-title"> worldPosition</div>
+</p><p>
+    To achieve good precision, the <code>worldPosition</code> coordinate in the vertex shader is shifted by the
+    camera position. To get the true world-space position, users can use
+    <code>getUserWorldPosition()</code>, however be aware that the true world-position might not
+    be able to fit in a <code>float</code> or might be represented with severely reduced precision.</div>
+</p><p>
+<div class="admonition tip"><div class="admonition-title"> UV attributes</div>
+</p><p>
+    By default the vertex shader of a material will flip the Y coordinate of the UV attributes
+    of the current mesh: <code>material.uv0 = vec2(mesh_uv0.x, 1.0 - mesh_uv0.y)</code>. You can control
+    this behavior using the <code>flipUV</code> property and setting it to <code>false</code>.</div>
+</p>
+<a class="target" name="customvertexattributes">&nbsp;</a><a class="target" name="materialdefinitions/vertexblock/customvertexattributes">&nbsp;</a><a class="target" name="toc4.3.2">&nbsp;</a><h3>Custom vertex attributes</h3>
+<p>
+
+You can use up to 8 custom vertex attributes, all of type <code>float4</code>. These attributes can be accessed
+using the vertex block shader functions <code>getCustom0()</code> to <code>getCustom7()</code>. However, before using
+custom attributes, you <em class="asterisk">must</em> declare those attributes as required in the <code>requires</code> property of
+the material:
+</p><pre class="listing tilde"><code><span class="line"></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>
+<a class="target" name="fragmentblock">&nbsp;</a><a class="target" name="materialdefinitions/fragmentblock">&nbsp;</a><a class="target" name="toc4.4">&nbsp;</a><h2>Fragment block</h2>
+<p>
+
+The fragment block must be used to control the fragment shading stage of the material. The fragment
+block must contain valid
+<a href="https://www.khronos.org/registry/OpenGL/specs/es/3.0/GLSL_ES_Specification_3.00.pdf">ESSL 3.0</a>
+code (the version of GLSL supported in OpenGL ES 3.0). You are free to create multiple functions
+inside the fragment block but you <strong class="asterisk">must</strong> declare the <code>material</code> function:
+</p><pre class="listing tilde"><code><span class="line"></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 function will be invoked automatically at runtime by the shading system and gives you the
+ability to read and modify material properties using the <code>MaterialInputs</code> structure. This full
+definition of the structure can be found in the <a href="#materialfragmentinputs" target="_self">Material fragment inputs</a> section. The full
+definition of the various members of the structure can be found in the <a href="#materialmodels" target="_self">Material models</a> section
+of this document.
+</p><p>
+The goal of the <code>material()</code> function is to compute the material properties specific to the selected
+shading model. For instance, here is a fragment block that creates a glossy red metal using the
+standard lit shading model:
+</p><pre class="listing tilde"><code><span class="line"></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>
+<a class="target" name="preparematerialfunction">&nbsp;</a><a class="target" name="materialdefinitions/fragmentblock/preparematerialfunction">&nbsp;</a><a class="target" name="toc4.4.1">&nbsp;</a><h3>prepareMaterial function</h3>
+<p>
+
+Note that you <strong class="asterisk">must</strong> call <code>prepareMaterial(material)</code> before exiting the  <code>material()</code> function.
+This <code>prepareMaterial</code> function sets up the internal state of the material model. Some of the APIs
+described in the Fragment APIs section - like <code>shading_normal</code> for instance - can only be accessed
+<em class="underscore">after</em> invoking <code>prepareMaterial()</code>.
+</p><p>
+It is also important to remember that the <code>normal</code> property - as described in the Material fragment
+inputs section - only has an effect when modified <em class="underscore">before</em> calling <code>prepareMaterial()</code>. Here is an
+example of a fragment shader that properly modifies the <code>normal</code> property to implement a glossy red
+plastic with bump mapping:
+</p><pre class="listing tilde"><code><span class="line"></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>
+<a class="target" name="materialfragmentinputs">&nbsp;</a><a class="target" name="materialdefinitions/fragmentblock/materialfragmentinputs">&nbsp;</a><a class="target" name="toc4.4.2">&nbsp;</a><h3>Material fragment inputs</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 &quot;solid&quot;</span>
+<span class="line"></span>}</code></pre>
+<a class="target" name="customsurfaceshading">&nbsp;</a><a class="target" name="materialdefinitions/fragmentblock/customsurfaceshading">&nbsp;</a><a class="target" name="toc4.4.3">&nbsp;</a><h3>Custom surface shading</h3>
+<p>
+
+When <code>customSurfaceShading</code> is set to <code>true</code> in the material block, the fragment block <strong class="asterisk">must</strong>
+declare and implement the <code>surfaceShading</code> function:
+</p><pre class="listing tilde"><code><span class="line"></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 function will be invoked for every light (directional, spot or point) in the scene that may
+influence the current fragment. The <code>surfaceShading</code> is invoked with 3 sets of data:
+</p><p>
+<ul>
+<li class="minus"><code>MaterialInputs</code>, as described in the <a href="#materialfragmentinputs" target="_self">Material fragment inputs</a> section and prepared in the
+  <code>material</code> function explained above
+</li>
+<li class="minus"><code>ShadingData</code>, a structure containing values derived from <code>MaterialInputs</code> (see below)
+</li>
+<li class="minus"><code>LightData</code>, a structure containing values specific to the light being currently
+   evaluated (see below)</li></ul>
+</p><p>
+The <code>surfaceShading</code> function must return an RGB color in linear sRGB. Alpha blending and alpha
+masking are handled outside of this function and must therefore be ignored.
+</p><p>
+<div class="admonition note"><div class="admonition-title"> About shadowed fragments</div>
+</p><p>
+    The <code>surfaceShading</code> function is invoked even when a fragment is known to be fully in the shadow
+    of the current light (<code>lightData.NdotL &lt;= 0.0</code> or <code>lightData.visibility &lt;= 0.0</code>). This gives
+    more flexibility to the <code>surfaceShading</code> function as it provides a simple way to handle constant
+    ambient lighting for instance.</div>
+</p><p>
+<div class="admonition warning"><div class="admonition-title"> Shading models</div>
+</p><p>
+    Custom surface shading only works with the <code>lit</code> shading model. Attempting to use any other
+    model will result in an error.</div>
+</p>
+<a class="target" name="shadingdatastructure">&nbsp;</a><a class="target" name="materialdefinitions/fragmentblock/customsurfaceshading/shadingdatastructure">&nbsp;</a><a class="target" name="toc4.4.3.1">&nbsp;</a><h4>Shading data structure</h4>
+<pre class="listing tilde"><code><span class="line"></span>struct ShadingData {
+<span class="line"></span>    <span class="hljs-comment">// The material&#x27;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&#x27;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>
+<a class="target" name="lightdatastructure">&nbsp;</a><a class="target" name="materialdefinitions/fragmentblock/customsurfaceshading/lightdatastructure">&nbsp;</a><a class="target" name="toc4.4.3.2">&nbsp;</a><h4>Light data structure</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&#x27;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&#x27;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 &lt;= 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&#x27;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>
+<a class="target" name="example">&nbsp;</a><a class="target" name="materialdefinitions/fragmentblock/customsurfaceshading/example">&nbsp;</a><a class="target" name="toc4.4.3.3">&nbsp;</a><h4>Example</h4>
+<p>
+
+The material below shows how to use custom surface shading to implement a simplified toon shader:
+</p><pre class="listing tilde"><code><span class="line"></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 result can be seen in <a href="#figure_toonshading" target="_self">figure&nbsp;41</a>.
+</p><p>
+<center><div class="image" style=""><a class="target" name="figure_toonshading">&nbsp;</a><a href="../images/screenshot_toon_shading.png" target="_blank"><img class="markdeep" src="../images/screenshot_toon_shading.png" /></a><center><span class="imagecaption"><b style="font-style:normal;">Figure&nbsp;41:</b> simple toon shading implemented with custom
+</span></center></div></center>
+</p>
+<a class="target" name="shaderpublicapis">&nbsp;</a><a class="target" name="materialdefinitions/shaderpublicapis">&nbsp;</a><a class="target" name="toc4.5">&nbsp;</a><h2>Shader public APIs</h2>
+<a class="target" name="types">&nbsp;</a><a class="target" name="materialdefinitions/shaderpublicapis/types">&nbsp;</a><a class="target" name="toc4.5.1">&nbsp;</a><h3>Types</h3>
+<p>
+
+While GLSL types can be used directly (<code>vec4</code> or <code>mat4</code>) we recommend the use of the following
+type aliases:
+<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&times;4</strong> </td><td  style="text-align:center"> mat4 </td><td  style="text-align:left"> A 4&times;4 float matrix </td></tr>
+<tr><td  style="text-align:left"> <strong class="asterisk">float3&times;3</strong> </td><td  style="text-align:center"> mat3 </td><td  style="text-align:left"> A 3&times;3 float matrix </td></tr>
+</table></div>
+</p>
+<a class="target" name="math">&nbsp;</a><a class="target" name="materialdefinitions/shaderpublicapis/math">&nbsp;</a><a class="target" name="toc4.5.2">&nbsp;</a><h3>Math</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&times;4Float3(float4&times;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&times;3Float3(float4&times;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>
+<a class="target" name="matrices">&nbsp;</a><a class="target" name="materialdefinitions/shaderpublicapis/matrices">&nbsp;</a><a class="target" name="toc4.5.3">&nbsp;</a><h3>Matrices</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&times;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&times;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&times;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&times;4 </td><td  style="text-align:left"> Matrix that converts from clip (NDC) space to view/eye space </td></tr>
+<tr><td  style="text-align:left"> <strong class="asterisk">getClipFromWorldMatrix()</strong> </td><td  style="text-align:center"> float4&times;4 </td><td  style="text-align:left"> Matrix that converts from world to clip (NDC) space </td></tr>
+<tr><td  style="text-align:left"> <strong class="asterisk">getWorldFromClipMatrix()</strong> </td><td  style="text-align:center"> float4&times;4 </td><td  style="text-align:left"> Matrix that converts from clip (NDC) space to world space </td></tr>
+</table></div>
+</p>
+<a class="target" name="frameconstants">&nbsp;</a><a class="target" name="materialdefinitions/shaderpublicapis/frameconstants">&nbsp;</a><a class="target" name="toc4.5.4">&nbsp;</a><h3>Frame constants</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&times;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 tip"><div class="admonition-title"> world space</div>
+</p><p>
+    To achieve good precision, the &ldquo;world space&rdquo; in Filament's shading system does not necessarily
+    match the API-level world space. To obtain the position of the API-level camera, custom
+    materials can use <code>getUserWorldFromWorldMatrix()</code> to transform <code>getWorldCameraPosition()</code>.</div>
+</p>
+<a class="target" name="materialglobals">&nbsp;</a><a class="target" name="materialdefinitions/shaderpublicapis/materialglobals">&nbsp;</a><a class="target" name="toc4.5.5">&nbsp;</a><h3>Material globals</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>
+<a class="target" name="vertexonly">&nbsp;</a><a class="target" name="materialdefinitions/shaderpublicapis/vertexonly">&nbsp;</a><a class="target" name="toc4.5.6">&nbsp;</a><h3>Vertex only</h3>
+<p>
+
+The following APIs are only available from the vertex block:
+<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&times;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&times;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>
+<a class="target" name="fragmentonly">&nbsp;</a><a class="target" name="materialdefinitions/shaderpublicapis/fragmentonly">&nbsp;</a><a class="target" name="toc4.5.7">&nbsp;</a><h3>Fragment only</h3>
+<p>
+
+The following APIs are only available from the fragment block:
+<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&times;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 &ldquo;Filmic&rdquo; 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 &ldquo;Filmic&rdquo; 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 tip"><div class="admonition-title"> world-space</div>
+</p><p>
+    To obtain API-level world-space coordinates, custom materials should use <code>getUserWorldPosition()</code>
+    or use <code>getUserWorldFromWorldMatrix()</code>. Note that API-level world-space coordinates should
+    never or rarely be used because they may not fit in a float3 or have severely reduced precision.</div>
+</p><p>
+<div class="admonition tip"><div class="admonition-title"> sampling from render targets</div>
+</p><p>
+    When sampling from a <code>filament::Texture</code> that is attached to a <code>filament::RenderTarget</code> for
+    materials in the surface domain, please use <code>uvToRenderTargetUV</code> to transform the texture
+    coordinate. This will flip the coordinate depending on which backend is being used.</div>
+</p>
+<a class="target" name="compilingmaterials">&nbsp;</a><a class="target" name="compilingmaterials">&nbsp;</a><a class="target" name="toc5">&nbsp;</a><h1>Compiling materials</h1>
+<p>
+
+Material packages can be compiled from material definitions using the command line tool called
+<code>matc</code>. The simplest way to use <code>matc</code> is to specify an input material definition (<code>car_paint.mat</code>
+in the example below) and an output material package (<code>car_paint.filamat</code> in the example below):
+</p><pre class="listing backtick"><code><span class="line"></span>$ matc -o ./materials/bin/car_paint.filamat ./materials/src/car_paint.mat</code></pre>
+<a class="target" name="shadervalidation">&nbsp;</a><a class="target" name="compilingmaterials/shadervalidation">&nbsp;</a><a class="target" name="toc5.1">&nbsp;</a><h2>Shader validation</h2>
+<p>
+
+<code>matc</code> attempts to validate shaders when compiling a material package. The example below shows an
+example of an error message generated when compiling a material definition containing a typo in the
+fragment shader (<code>metalic</code> instead of <code>metallic</code>). The reported line numbers are line numbers in the
+source material definition file.
+</p><pre class="listing backtick"><code><span class="line"></span>ERROR: 0:13: &#x27;metalic&#x27; : no such field in structure
+<span class="line"></span>ERROR: 0:13: &#x27;&#x27; : 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>
+<a class="target" name="flags">&nbsp;</a><a class="target" name="compilingmaterials/flags">&nbsp;</a><a class="target" name="toc5.2">&nbsp;</a><h2>Flags</h2>
+<p>
+
+The command line flags relevant to application development are described in <a href="#table_matcflags" target="_self">table&nbsp;16</a>.
+<div class='table'>
+<a class="target" name="table_matcflags">&nbsp;</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">&mdash;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">&mdash;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">&mdash;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">&mdash;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">&mdash;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">&mdash;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&nbsp;16:</b> List of <code>matc</code> flags</div></center></div>
+</p><p>
+<code>matc</code> offers a few other flags that are irrelevant to application developers and for internal
+use only.
+</p>
+<a class="target" name="--platform">&nbsp;</a><a class="target" name="compilingmaterials/flags/&mdash;platform">&nbsp;</a><a class="target" name="toc5.2.1">&nbsp;</a><h3>&mdash;platform</h3>
+<p>
+
+By default, <code>matc</code> generates material packages containing shaders for all supported platforms. If
+you wish to reduce the size of your material packages, it is recommended to select only the
+appropriate target platform. For instance, to compile a material package for Android only, run
+the following command:
+</p><pre class="listing backtick"><code><span class="line"></span>$ matc -p mobile -o ./materials/bin/car_paint.filamat ./materials/src/car_paint.mat</code></pre>
+<a class="target" name="--api">&nbsp;</a><a class="target" name="compilingmaterials/flags/&mdash;api">&nbsp;</a><a class="target" name="toc5.2.2">&nbsp;</a><h3>&mdash;api</h3>
+<p>
+
+By default, <code>matc</code> generates material packages containing shaders for the OpenGL API. You can choose
+to generate shaders for the Vulkan API in addition to the OpenGL shaders. If you intend on targeting
+only Vulkan capable devices, you can reduce the size of the material packages by generating only
+the set of Vulkan shaders:
+</p><pre class="listing backtick"><code><span class="line"></span>$ matc -a vulkan -o ./materials/bin/car_paint.filamat ./materials/src/car_paint.mat</code></pre>
+<a class="target" name="--optimize-size">&nbsp;</a><a class="target" name="compilingmaterials/flags/&mdash;optimize-size">&nbsp;</a><a class="target" name="toc5.2.3">&nbsp;</a><h3>&mdash;optimize-size</h3>
+<p>
+
+This flag applies fewer optimization techniques to try and keep the final material as small as
+possible. If the compiled material is deemed too large by default, using this flag might be
+a good compromise between runtime performance and size.
+</p>
+<a class="target" name="--reflect">&nbsp;</a><a class="target" name="compilingmaterials/flags/&mdash;reflect">&nbsp;</a><a class="target" name="toc5.2.4">&nbsp;</a><h3>&mdash;reflect</h3>
+<p>
+
+This flag was designed to help build tools around <code>matc</code>. It allows you to print out specific
+metadata in JSON format. The example below prints out the list of parameters defined in Filament's
+standard skybox material. It produces a list of 2 parameters, named <code>showSun</code> and <code>skybox</code>,
+respectively a boolean and a cubemap texture.
+</p><pre class="listing backtick"><code><span class="line"></span>$ matc --reflect parameters filament/src/materials/skybox.mat 
+<span class="line"></span>{
+<span class="line"></span>  &quot;parameters&quot;: [
+<span class="line"></span>    {
+<span class="line"></span>      &quot;name&quot;: &quot;showSun&quot;,
+<span class="line"></span>      &quot;type&quot;: &quot;bool&quot;,
+<span class="line"></span>      &quot;size&quot;: &quot;1&quot;
+<span class="line"></span>    },
+<span class="line"></span>    {
+<span class="line"></span>      &quot;name&quot;: &quot;skybox&quot;,
+<span class="line"></span>      &quot;type&quot;: &quot;samplerCubemap&quot;,
+<span class="line"></span>      &quot;format&quot;: &quot;float&quot;,
+<span class="line"></span>      &quot;precision&quot;: &quot;default&quot;
+<span class="line"></span>    }
+<span class="line"></span>  ]
+<span class="line"></span>}</code></pre>
+<a class="target" name="--variant-filter">&nbsp;</a><a class="target" name="compilingmaterials/flags/&mdash;variant-filter">&nbsp;</a><a class="target" name="toc5.2.5">&nbsp;</a><h3>&mdash;variant-filter</h3>
+<p>
+
+This flag can be used to further reduce the size of a compiled material. It is used to specify a
+list of shader variants that the application guarantees will never be needed. These shader variants
+are skipped during the code generation phase of <code>matc</code>, thus reducing the overall size of the
+material.
+</p><p>
+The variants must be specified as a comma-separated list, using one of the following available
+variants:
+</p><p>
+<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:
+</p><pre class="listing backtick"><code><span class="line"></span>--variant-filter=skinning,shadowReceiver</code></pre><p>
+Note that some variants may automatically be filtered out. For instance, all lighting related
+variants (<code>directionalLighting</code>, etc.) are filtered out when compiling an <code>unlit</code> material.
+</p><p>
+When this flag is used, the specified variant filters are merged with the variant filters specified
+in the material itself.
+</p><p>
+Use this flag with caution, filtering out a variant required at runtime may lead to crashes.
+</p>
+<a class="target" name="handlingcolors">&nbsp;</a><a class="target" name="handlingcolors">&nbsp;</a><a class="target" name="toc6">&nbsp;</a><h1>Handling colors</h1>
+<a class="target" name="linearcolors">&nbsp;</a><a class="target" name="handlingcolors/linearcolors">&nbsp;</a><a class="target" name="toc6.1">&nbsp;</a><h2>Linear colors</h2>
+<p>
+
+If the color data comes from a texture, simply make sure you use an sRGB texture to benefit from
+automatic hardware conversion from sRGB to linear. If the color data is passed as a parameter to
+the material you can convert from sRGB to linear by running the following algorithm on each
+color channel:
+</p><pre class="listing tilde"><code><span class="line"></span><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 &lt;= <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 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>
+<a class="target" name="pre-multipliedalpha">&nbsp;</a><a class="target" name="handlingcolors/pre-multipliedalpha">&nbsp;</a><a class="target" name="toc6.2">&nbsp;</a><h2>Pre-multiplied alpha</h2>
+<p>
+
+A color uses pre-multiplied alpha if its RGB components are multiplied by the alpha channel:
+</p><pre class="listing tilde"><code><span class="line"></span><span class="hljs-comment">// Compute pre-multiplied color</span>
+<span class="line"></span>color.rgb *= color.a;</code></pre><p>
+If the color is sampled from a texture, you can simply ensure that the texture data is
+pre-multiplied ahead of time. On Android, any texture uploaded from a
+<a href="https://developer.android.com/reference/android/graphics/Bitmap.html">Bitmap</a> will be
+pre-multiplied by default.
+</p>
+<a class="target" name="samplerusageinmaterials">&nbsp;</a><a class="target" name="samplerusageinmaterials">&nbsp;</a><a class="target" name="toc7">&nbsp;</a><h1>Sampler usage in Materials</h1>
+<p>
+
+The number of usable sampler parameters (e.g.: type is <code>sampler2d</code>) in materials is limited and
+depends on the material properties, shading model, feature level and variant filter.
+</p>
+<a class="target" name="featurelevel1and2">&nbsp;</a><a class="target" name="samplerusageinmaterials/featurelevel1and2">&nbsp;</a><a class="target" name="toc7.1">&nbsp;</a><h2>Feature level 1 and 2</h2>
+<p>
+
+<code>unlit</code> materials can use up to 12 samplers by default.
+</p><p>
+<code>lit</code> materials can use up to 9 samplers by default, however if <code>refractionMode</code> or <code>reflectionMode</code>
+is set to <code>screenspace</code> that number is reduced to 8.
+</p><p>
+Finally if <code>variantFilter</code> contains the <code>fog</code> filter, an extra sampler is made available, such that
+<code>unlit</code> materials can use up to 13 and <code>lit</code> materials up to 10 samplers by default.
+</p>
+<a class="target" name="featurelevel3">&nbsp;</a><a class="target" name="samplerusageinmaterials/featurelevel3">&nbsp;</a><a class="target" name="toc7.2">&nbsp;</a><h2>Feature level 3</h2>
+<p>
+
+16 samplers are available.
+</p><p>
+<div class="admonition tip"><div class="admonition-title"> external samplers</div>
+</p><p>
+               Be aware that <code>external</code> samplers account for 2 regular samplers.</div>
+</p><p>
+</p></span><div id="mdContextMenu" style="visibility:hidden"></div><div class="markdeepFooter"><i>formatted by <a href="https://casual-effects.com/markdeep" style="color:#999">Markdeep&nbsp;1.18&nbsp;&nbsp;</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);">&#x2712;</div></div><script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.6/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
\ No newline at end of file
diff --git a/docs_src/src/notes/README.md b/docs_src/src/notes/README.md
new file mode 100644
index 00000000000..32856227d9c
--- /dev/null
+++ b/docs_src/src/notes/README.md
@@ -0,0 +1,3 @@
+# Technical Notes
+
+Documents that pertain to components and use cases of the project.
\ No newline at end of file
diff --git a/docs_src/src/notes/debugging.md b/docs_src/src/notes/debugging.md
new file mode 100644
index 00000000000..0301348cdf8
--- /dev/null
+++ b/docs_src/src/notes/debugging.md
@@ -0,0 +1,3 @@
+# Debugging
+
+Helpful documents for specific debugging needs.
diff --git a/docs_src/src/notes/libs.md b/docs_src/src/notes/libs.md
new file mode 100644
index 00000000000..2417ed94364
--- /dev/null
+++ b/docs_src/src/notes/libs.md
@@ -0,0 +1,3 @@
+# Libraries
+
+Collection of README.md from the `/libs` folder.
\ No newline at end of file
diff --git a/docs_src/src/notes/metal_debugging.md b/docs_src/src/notes/metal_debugging.md
new file mode 100644
index 00000000000..91548cb0f05
--- /dev/null
+++ b/docs_src/src/notes/metal_debugging.md
@@ -0,0 +1,42 @@
+# Debugging Metal
+
+## Enable Metal Validation
+
+To enable the Metal validation layers when running a sample through the command-line, set the
+following environment variable:
+
+```
+export METAL_DEVICE_WRAPPER_TYPE=1
+```
+
+You should then see the following output when running a sample with the Metal backend:
+
+```
+2020-10-13 18:01:44.101 gltf_viewer[73303:4946828] Metal API Validation Enabled
+```
+
+## Metal Frame Capture from gltf_viewer
+
+To capture Metal frames from within gltf_viewer:
+
+### 1. Create an Info.plist file
+
+Create an `Info.plist` file in the same directory as `gltf_viewer` (`cmake/samples`). Set its
+contents to:
+
+```
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>MetalCaptureEnabled</key>
+    <true/>
+</dict>
+</plist>
+```
+
+### 2. Capture a frame
+
+Run gltf_viewer as normal, and hit the "Capture frame" button under the Debug menu. The captured
+frame will be saved to `filament.gputrace` in the current working directory. This file can then be
+opened with Xcode for inspection.
diff --git a/filament/docs/SpirvDebugging.md b/docs_src/src/notes/spirv_debugging.md
similarity index 100%
rename from filament/docs/SpirvDebugging.md
rename to docs_src/src/notes/spirv_debugging.md
diff --git a/filament/docs/optimizations.cfg b/docs_src/src/notes/spirv_debugging_optimizations.cfg
similarity index 100%
rename from filament/docs/optimizations.cfg
rename to docs_src/src/notes/spirv_debugging_optimizations.cfg
diff --git a/docs_src/src/notes/tools.md b/docs_src/src/notes/tools.md
new file mode 100644
index 00000000000..001db45daf5
--- /dev/null
+++ b/docs_src/src/notes/tools.md
@@ -0,0 +1,3 @@
+# Tools
+
+Collection of README.md from the `/tools` folder.
\ No newline at end of file
diff --git a/filament/docs/Versioning.md b/docs_src/src/notes/versioning.md
similarity index 100%
rename from filament/docs/Versioning.md
rename to docs_src/src/notes/versioning.md
diff --git a/docs_src/src/notes/vulkan_debugging.md b/docs_src/src/notes/vulkan_debugging.md
new file mode 100644
index 00000000000..9120d5c6ba0
--- /dev/null
+++ b/docs_src/src/notes/vulkan_debugging.md
@@ -0,0 +1,15 @@
+# Debugging Vulkan
+
+## Enable Validation Logs
+
+Simply install the LunarG SDK (it's fast and easy), then make sure you've got the following
+environment variables set up in your **bashrc** file. For example:
+
+```
+export VULKAN_SDK='/path_to_home/VulkanSDK/1.3.216.0/x86_64'
+export VK_LAYER_PATH="$VULKAN_SDK/etc/explicit_layer.d"
+export PATH="$VULKAN_SDK/bin:$PATH"
+```
+
+As long as you're running a debug build of Filament, you should now see extra debugging spew in your
+console if there are any errors or performance issues being caught by validation.
diff --git a/docs_src/src/samples/README.md b/docs_src/src/samples/README.md
new file mode 100644
index 00000000000..3d9213b7386
--- /dev/null
+++ b/docs_src/src/samples/README.md
@@ -0,0 +1,5 @@
+# Tutorials and Samples
+
+New users of Filament are encouraged to peruse through the samples to get a better
+understanding of basic API usage.  Additionally, you will find detailed tutorials
+for [iOS](ios.md) and [web](web.md).
\ No newline at end of file
diff --git a/site/content/posts/cocoapods.md b/docs_src/src/samples/ios.md
similarity index 93%
rename from site/content/posts/cocoapods.md
rename to docs_src/src/samples/ios.md
index 0369e3f64ad..081a8bb60c6 100644
--- a/site/content/posts/cocoapods.md
+++ b/docs_src/src/samples/ios.md
@@ -1,35 +1,32 @@
----
-title: "CocoaPods Hello Triangle"
-date: 2020-07-09T14:48:51-07:00
----
+# CocoaPods Hello Triangle
 
 As of release 1.8.0, you can install Filament in your iOS application using CocoaPods.
 
 This guide will walk you through creating a basic "hello triangle" iOS application using Filament and the Metal backend.
 
-![a rotating triangle](rotating-triangle.gif)
+![a rotating triangle](../images/ios_sample/rotating-triangle.gif)
 
 The full source for this example is [here](https://github.com/google/filament/tree/main/ios/samples/HelloCocoaPods). If you're just looking to get something up and running quickly, download the project, `pod install`, build, and run.
 
 We'll be walking through 7 steps to get the rotating triangle up and running. All of the code we'll be writing will be in a single ViewController.mm file, and you can follow along [here](https://github.com/google/filament/blob/main/ios/samples/HelloCocoaPods/HelloCocoaPods/ViewController.mm).
 
-- [1. Creating a Boilerplate App]({{< ref "#creating-a-boilerplate-app-with-filament" >}})
-- [2. Instantiating Filament]({{< ref "#instantiating-the-filament-engine" >}})
-- [3. Creating a SwapChain]({{< ref "#creating-a-swapchain" >}})
-- [4. Clearing the Screen]({{< ref "#clearing-the-screen" >}})
-- [5. Drawing a Triangle]({{< ref "#drawing-a-triangle" >}})
-- [6. Compiling a Custom Material]({{< ref "#compiling-a-custom-material" >}})
-- [7. Animating the Triangle]({{< ref "#animating-the-triangle" >}})
+- [1. Creating a Boilerplate App]("#creating-a-boilerplate-app-with-filament)
+- [2. Instantiating Filament](#instantiating-the-filament-engine)
+- [3. Creating a SwapChain](#creating-a-swapchain)
+- [4. Clearing the Screen](#clearing-the-screen)
+- [5. Drawing a Triangle](#drawing-a-triangle)
+- [6. Compiling a Custom Material](#compiling-a-custom-material)
+- [7. Animating the Triangle](#animating-the-triangle)
 
 ## Creating a Boilerplate App with Filament
 
 We'll start fresh by creating a new Single View App in Xcode.
 
-![create a single view app in Xcodde](single-view-app.png)
+![create a single view app in Xcodde](../images/ios_sample/single-view-app.png)
 
 Give your app a name, and use the default options.
 
-![use the default options in Xcode](default-options.png)
+![use the default options in Xcode](../images/ios_sample/default-options.png)
 
 If you haven't used CocoaPods before, I recommend watching [this Route 85 video](https://www.youtube.com/watch?v=iEAjvNRdZa0) to help you get set up.
 
@@ -57,7 +54,7 @@ Before we do anything with Filament, we first need to include the appropriate he
 
 You should be able to simply change the extension of the default ViewController from .m to .mm, though I've found Xcode to be buggy with this on occasion. To make sure Xcode recognizes it as an Objective-C++ file, check that the type of file is "Objective-C++ Source".
 
-![change the type of ViewController.m to Objective-C++](obj-cpp.png)
+![change the type of ViewController.m to Objective-C++](../images/ios_sample/obj-cpp.png)
 
 Then, add the following to the top of ViewController.
 
@@ -110,9 +107,9 @@ We could set up our own `CAMetalLayer` if we wanted to, but Apple provides a `MT
 
 Inside Main.storyboard, change the type of ViewController's view to a `MTKView`.
 
-![ViewController view](view.png)
+![ViewController view](../images/ios_sample/view.png)
 
-![change type of MTKView](mtkview.gif)
+![change type of MTKView](../images/ios_sample/mtkview.gif)
 
 Include the SwapChain.h and MTKView.h headers and make the `ViewController` conform to the `MTKViewDelegate` protocol.
 
@@ -276,7 +273,7 @@ The `beginFrame` method instructs Filament to start rendering to our specific `S
 
 At this point, you should be able to build and run the app, and you'll see a blue screen.
 
-![blue screen after clearing](blue-screen.png)
+![blue screen after clearing](../images/ios_sample/blue-screen.png)
 
 ## Drawing a Triangle
 
@@ -373,7 +370,7 @@ _engine->destroy(_vertexBuffer);
 
 If you build and run the app now, you should see a plain white triangle. When we created the renderable, we didn't specify any specific `Material` to use, so Filament used a default, white material. Let's create a custom material to color the triangle.
 
-![a white triangle](white-triangle.png)
+![a white triangle](../images/ios_sample/white-triangle.png)
 
 ## Compiling a Custom Material
 
@@ -460,7 +457,7 @@ _engine->destroy(_material);
 
 Build and run. You should see the same triangle, but with colors.
 
-![the triangle with our custom material](colored-triangle.png)
+![the triangle with our custom material](../images/ios_sample/colored-triangle.png)
 
 ## Animating the Triangle
 
@@ -500,7 +497,7 @@ Create a new function, `update`, and add call it inside the `drawInMTKView:` met
 
 Now we should see the triangle rotate around its z axis.
 
-![a rotating triangle](rotating-triangle.gif)
+![a rotating triangle](../images/ios_sample/rotating-triangle.gif)
 
 ## Next Steps
 
diff --git a/site/content/webgl/index.md b/docs_src/src/samples/web.md
similarity index 84%
rename from site/content/webgl/index.md
rename to docs_src/src/samples/web.md
index eb8dfcd224a..9f61c338a21 100644
--- a/site/content/webgl/index.md
+++ b/docs_src/src/samples/web.md
@@ -1,8 +1,4 @@
----
-title: "Web Docs / Demos"
-date: 2018-10-30T13:13:14-07:00
-menu: main
----
+# Web Docs
 
 ## tutorials
 
diff --git a/docs_src/theme/css/chrome.css b/docs_src/theme/css/chrome.css
new file mode 100644
index 00000000000..3a412c2282d
--- /dev/null
+++ b/docs_src/theme/css/chrome.css
@@ -0,0 +1,644 @@
+/* CSS for UI elements (a.k.a. chrome) */
+
+html {
+    scrollbar-color: var(--scrollbar) var(--bg);
+}
+#searchresults a,
+.content a:link,
+a:visited,
+a > .hljs {
+    color: var(--links);
+}
+
+/*
+    body-container is necessary because mobile browsers don't seem to like
+    overflow-x on the body tag when there is a <meta name="viewport"> tag.
+*/
+#body-container {
+    /*
+        This is used when the sidebar pushes the body content off the side of
+        the screen on small screens. Without it, dragging on mobile Safari
+        will want to reposition the viewport in a weird way.
+    */
+    overflow-x: clip;
+}
+
+/* Menu Bar */
+
+#menu-bar,
+#menu-bar-hover-placeholder {
+    z-index: 101;
+    margin: auto calc(0px - var(--page-padding));
+}
+#menu-bar {
+    position: relative;
+    display: flex;
+    flex-wrap: wrap;
+    background-color: var(--bg);
+    border-block-end-color: var(--bg);
+    border-block-end-width: 1px;
+    border-block-end-style: solid;
+}
+#menu-bar.sticky,
+#menu-bar-hover-placeholder:hover + #menu-bar,
+#menu-bar:hover,
+html.sidebar-visible #menu-bar {
+    position: -webkit-sticky;
+    position: sticky;
+    top: 0 !important;
+}
+#menu-bar-hover-placeholder {
+    position: sticky;
+    position: -webkit-sticky;
+    top: 0;
+    height: var(--menu-bar-height);
+}
+#menu-bar.bordered {
+    border-block-end-color: var(--table-border-color);
+}
+#menu-bar i, #menu-bar .icon-button {
+    position: relative;
+    padding: 0 8px;
+    z-index: 10;
+    line-height: var(--menu-bar-height);
+    cursor: pointer;
+    transition: color 0.5s;
+}
+@media only screen and (max-width: 420px) {
+    #menu-bar i, #menu-bar .icon-button {
+        padding: 0 5px;
+    }
+}
+
+.icon-button {
+    border: none;
+    background: none;
+    padding: 0;
+    color: inherit;
+}
+.icon-button i {
+    margin: 0;
+}
+
+.right-buttons {
+    margin: 0 15px;
+}
+.right-buttons a {
+    text-decoration: none;
+}
+
+.left-buttons {
+    display: flex;
+    margin: 0 5px;
+}
+html:not(.js) .left-buttons button {
+    display: none;
+}
+
+.menu-title {
+    display: inline-block;
+    font-weight: 200;
+    font-size: 2.4rem;
+    line-height: var(--menu-bar-height);
+    text-align: center;
+    margin: 0;
+    flex: 1;
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+}
+.menu-title {
+    cursor: pointer;
+}
+
+.menu-bar,
+.menu-bar:visited,
+.nav-chapters,
+.nav-chapters:visited,
+.mobile-nav-chapters,
+.mobile-nav-chapters:visited,
+.menu-bar .icon-button,
+.menu-bar a i {
+    color: var(--icons);
+}
+
+.menu-bar i:hover,
+.menu-bar .icon-button:hover,
+.nav-chapters:hover,
+.mobile-nav-chapters i:hover {
+    color: var(--icons-hover);
+}
+
+/* Nav Icons */
+
+.nav-chapters {
+    font-size: 2.5em;
+    text-align: center;
+    text-decoration: none;
+
+    position: fixed;
+    top: 0;
+    bottom: 0;
+    margin: 0;
+    max-width: 150px;
+    min-width: 90px;
+
+    display: flex;
+    justify-content: center;
+    align-content: center;
+    flex-direction: column;
+
+    transition: color 0.5s, background-color 0.5s;
+}
+
+.nav-chapters:hover {
+    text-decoration: none;
+    background-color: var(--theme-hover);
+    transition: background-color 0.15s, color 0.15s;
+}
+
+.nav-wrapper {
+    margin-block-start: 50px;
+    display: none;
+}
+
+.mobile-nav-chapters {
+    font-size: 2.5em;
+    text-align: center;
+    text-decoration: none;
+    width: 90px;
+    border-radius: 5px;
+    background-color: var(--sidebar-bg);
+}
+
+/* Only Firefox supports flow-relative values */
+.previous { float: left; }
+[dir=rtl] .previous { float: right; }
+
+/* Only Firefox supports flow-relative values */
+.next {
+    float: right;
+    right: var(--page-padding);
+}
+[dir=rtl] .next {
+    float: left;
+    right: unset;
+    left: var(--page-padding);
+}
+
+/* Use the correct buttons for RTL layouts*/
+[dir=rtl] .previous i.fa-angle-left:before {content:"\f105";}
+[dir=rtl] .next i.fa-angle-right:before { content:"\f104"; }
+
+@media only screen and (max-width: 1080px) {
+    .nav-wide-wrapper { display: none; }
+    .nav-wrapper { display: block; }
+}
+
+/* sidebar-visible */
+@media only screen and (max-width: 1380px) {
+    #sidebar-toggle-anchor:checked ~ .page-wrapper .nav-wide-wrapper { display: none; }
+    #sidebar-toggle-anchor:checked ~ .page-wrapper .nav-wrapper { display: block; }
+}
+
+/* Inline code */
+
+:not(pre) > .hljs {
+    display: inline;
+    padding: 0.1em 0.3em;
+    border-radius: 3px;
+}
+
+:not(pre):not(a) > .hljs {
+    color: var(--inline-code-color);
+    overflow-x: initial;
+}
+
+a:hover > .hljs {
+    text-decoration: underline;
+}
+
+pre {
+    position: relative;
+}
+pre > .buttons {
+    position: absolute;
+    z-index: 100;
+    right: 0px;
+    top: 2px;
+    margin: 0px;
+    padding: 2px 0px;
+
+    color: var(--sidebar-fg);
+    cursor: pointer;
+    visibility: hidden;
+    opacity: 0;
+    transition: visibility 0.1s linear, opacity 0.1s linear;
+}
+pre:hover > .buttons {
+    visibility: visible;
+    opacity: 1
+}
+pre > .buttons :hover {
+    color: var(--sidebar-active);
+    border-color: var(--icons-hover);
+    background-color: var(--theme-hover);
+}
+pre > .buttons i {
+    margin-inline-start: 8px;
+}
+pre > .buttons button {
+    cursor: inherit;
+    margin: 0px 5px;
+    padding: 4px 4px 3px 5px;
+    font-size: 23px;
+
+    border-style: solid;
+    border-width: 1px;
+    border-radius: 4px;
+    border-color: var(--icons);
+    background-color: var(--theme-popup-bg);
+    transition: 100ms;
+    transition-property: color,border-color,background-color;
+    color: var(--icons);
+}
+
+pre > .buttons button.clip-button {
+    padding: 2px 4px 0px 6px;
+}
+pre > .buttons button.clip-button::before {
+    /* clipboard image from octicons (https://github.com/primer/octicons/tree/v2.0.0) MIT license
+     */
+    content: url('data:image/svg+xml,<svg width="21" height="20" viewBox="0 0 24 25" \
+xmlns="http://www.w3.org/2000/svg" aria-label="Copy to clipboard">\
+<path d="M18 20h2v3c0 1-1 2-2 2H2c-.998 0-2-1-2-2V5c0-.911.755-1.667 1.667-1.667h5A3.323 3.323 0 \
+0110 0a3.323 3.323 0 013.333 3.333h5C19.245 3.333 20 4.09 20 5v8.333h-2V9H2v14h16v-3zM3 \
+7h14c0-.911-.793-1.667-1.75-1.667H13.5c-.957 0-1.75-.755-1.75-1.666C11.75 2.755 10.957 2 10 \
+2s-1.75.755-1.75 1.667c0 .911-.793 1.666-1.75 1.666H4.75C3.793 5.333 3 6.09 3 7z"/>\
+<path d="M4 19h6v2H4zM12 11H4v2h8zM4 17h4v-2H4zM15 15v-3l-4.5 4.5L15 21v-3l8.027-.032L23 15z"/>\
+</svg>');
+    filter: var(--copy-button-filter);
+}
+pre > .buttons button.clip-button:hover::before {
+    filter: var(--copy-button-filter-hover);
+}
+
+@media (pointer: coarse) {
+    pre > .buttons button {
+        /* On mobile, make it easier to tap buttons. */
+        padding: 0.3rem 1rem;
+    }
+
+    .sidebar-resize-indicator {
+        /* Hide resize indicator on devices with limited accuracy */
+        display: none;
+    }
+}
+pre > code {
+    display: block;
+    padding: 1rem;
+}
+
+/* FIXME: ACE editors overlap their buttons because ACE does absolute
+   positioning within the code block which breaks padding. The only solution I
+   can think of is to move the padding to the outer pre tag (or insert a div
+   wrapper), but that would require fixing a whole bunch of CSS rules.
+*/
+.hljs.ace_editor {
+  padding: 0rem 0rem;
+}
+
+pre > .result {
+    margin-block-start: 10px;
+}
+
+/* Search */
+
+#searchresults a {
+    text-decoration: none;
+}
+
+mark {
+    border-radius: 2px;
+    padding-block-start: 0;
+    padding-block-end: 1px;
+    padding-inline-start: 3px;
+    padding-inline-end: 3px;
+    margin-block-start: 0;
+    margin-block-end: -1px;
+    margin-inline-start: -3px;
+    margin-inline-end: -3px;
+    background-color: var(--search-mark-bg);
+    transition: background-color 300ms linear;
+    cursor: pointer;
+}
+
+mark.fade-out {
+    background-color: rgba(0,0,0,0) !important;
+    cursor: auto;
+}
+
+.searchbar-outer {
+    margin-inline-start: auto;
+    margin-inline-end: auto;
+    max-width: var(--content-max-width);
+}
+
+#searchbar {
+    width: 100%;
+    margin-block-start: 5px;
+    margin-block-end: 0;
+    margin-inline-start: auto;
+    margin-inline-end: auto;
+    padding: 10px 16px;
+    transition: box-shadow 300ms ease-in-out;
+    border: 1px solid var(--searchbar-border-color);
+    border-radius: 3px;
+    background-color: var(--searchbar-bg);
+    color: var(--searchbar-fg);
+}
+#searchbar:focus,
+#searchbar.active {
+    box-shadow: 0 0 3px var(--searchbar-shadow-color);
+}
+
+.searchresults-header {
+    font-weight: bold;
+    font-size: 1em;
+    padding-block-start: 18px;
+    padding-block-end: 0;
+    padding-inline-start: 5px;
+    padding-inline-end: 0;
+    color: var(--searchresults-header-fg);
+}
+
+.searchresults-outer {
+    margin-inline-start: auto;
+    margin-inline-end: auto;
+    max-width: var(--content-max-width);
+    border-block-end: 1px dashed var(--searchresults-border-color);
+}
+
+ul#searchresults {
+    list-style: none;
+    padding-inline-start: 20px;
+}
+ul#searchresults li {
+    margin: 10px 0px;
+    padding: 2px;
+    border-radius: 2px;
+}
+ul#searchresults li.focus {
+    background-color: var(--searchresults-li-bg);
+}
+ul#searchresults span.teaser {
+    display: block;
+    clear: both;
+    margin-block-start: 5px;
+    margin-block-end: 0;
+    margin-inline-start: 20px;
+    margin-inline-end: 0;
+    font-size: 0.8em;
+}
+ul#searchresults span.teaser em {
+    font-weight: bold;
+    font-style: normal;
+}
+
+/* Sidebar */
+
+.sidebar {
+    position: fixed;
+    left: 0;
+    top: 0;
+    bottom: 0;
+    width: var(--sidebar-width);
+    font-size: 0.875em;
+    box-sizing: border-box;
+    -webkit-overflow-scrolling: touch;
+    overscroll-behavior-y: contain;
+    background-color: var(--sidebar-bg);
+    color: var(--sidebar-fg);
+}
+.sidebar-iframe-inner {
+    background-color: var(--sidebar-bg);
+    color: var(--sidebar-fg);
+    padding: 10px 10px;
+    margin: 0;
+    font-size: 1.4rem;
+}
+.sidebar-iframe-outer {
+    border: none;
+    height: 100%;
+    position: absolute;
+    top: 0;
+    bottom: 0;
+    left: 0;
+    right: 0;
+}
+[dir=rtl] .sidebar { left: unset; right: 0; }
+.sidebar-resizing {
+    -moz-user-select: none;
+    -webkit-user-select: none;
+    -ms-user-select: none;
+    user-select: none;
+}
+html:not(.sidebar-resizing) .sidebar {
+    transition: transform 0.3s; /* Animation: slide away */
+}
+.sidebar code {
+    line-height: 2em;
+}
+.sidebar .flogo {
+    max-height: 90px;
+    padding: 5px;
+}
+.sidebar .sidebar-scrollbox {
+    overflow-y: auto;
+    position: absolute;
+    top: 100px;
+    bottom: 0;
+    left: 0;
+    right: 0;
+    padding: 10px 10px;
+}
+.sidebar .sidebar-resize-handle {
+    position: absolute;
+    cursor: col-resize;
+    width: 0;
+    right: calc(var(--sidebar-resize-indicator-width) * -1);
+    top: 0;
+    bottom: 0;
+    display: flex;
+    align-items: center;
+}
+
+.sidebar-resize-handle .sidebar-resize-indicator {
+    width: 100%;
+    height: 12px;
+    background-color: var(--icons);
+    margin-inline-start: var(--sidebar-resize-indicator-space);
+}
+
+[dir=rtl] .sidebar .sidebar-resize-handle {
+    left: calc(var(--sidebar-resize-indicator-width) * -1);
+    right: unset;
+}
+.js .sidebar .sidebar-resize-handle {
+    cursor: col-resize;
+    width: calc(var(--sidebar-resize-indicator-width) - var(--sidebar-resize-indicator-space));
+}
+/* sidebar-hidden */
+#sidebar-toggle-anchor:not(:checked) ~ .sidebar {
+    transform: translateX(calc(0px - var(--sidebar-width) - var(--sidebar-resize-indicator-width)));
+    z-index: -1;
+}
+[dir=rtl] #sidebar-toggle-anchor:not(:checked) ~ .sidebar {
+    transform: translateX(calc(var(--sidebar-width) + var(--sidebar-resize-indicator-width)));
+}
+.sidebar::-webkit-scrollbar {
+    background: var(--sidebar-bg);
+}
+.sidebar::-webkit-scrollbar-thumb {
+    background: var(--scrollbar);
+}
+
+/* sidebar-visible */
+#sidebar-toggle-anchor:checked ~ .page-wrapper {
+    transform: translateX(calc(var(--sidebar-width) + var(--sidebar-resize-indicator-width)));
+}
+[dir=rtl] #sidebar-toggle-anchor:checked ~ .page-wrapper {
+    transform: translateX(calc(0px - var(--sidebar-width) - var(--sidebar-resize-indicator-width)));
+}
+@media only screen and (min-width: 620px) {
+    #sidebar-toggle-anchor:checked ~ .page-wrapper {
+        transform: none;
+        margin-inline-start: calc(var(--sidebar-width) + var(--sidebar-resize-indicator-width));
+    }
+    [dir=rtl] #sidebar-toggle-anchor:checked ~ .page-wrapper {
+        transform: none;
+    }
+}
+
+.chapter {
+    list-style: none outside none;
+    padding-inline-start: 0;
+    line-height: 2.2em;
+}
+
+.chapter ol {
+    width: 100%;
+}
+
+.chapter li {
+    display: flex;
+    color: var(--sidebar-non-existant);
+}
+.chapter li a {
+    display: block;
+    padding: 0;
+    text-decoration: none;
+    color: var(--sidebar-fg);
+}
+
+.chapter li a:hover {
+    color: var(--sidebar-active);
+}
+
+.chapter li a.active {
+    color: var(--sidebar-active);
+}
+
+.chapter li > a.toggle {
+    cursor: pointer;
+    display: block;
+    margin-inline-start: auto;
+    padding: 0 10px;
+    user-select: none;
+    opacity: 0.68;
+}
+
+.chapter li > a.toggle div {
+    transition: transform 0.5s;
+}
+
+/* collapse the section */
+.chapter li:not(.expanded) + li > ol {
+    display: none;
+}
+
+.chapter li.chapter-item {
+    line-height: 1.5em;
+    margin-block-start: 0.6em;
+}
+
+.chapter li.expanded > a.toggle div {
+    transform: rotate(90deg);
+}
+
+.spacer {
+    width: 100%;
+    height: 3px;
+    margin: 5px 0px;
+}
+.chapter .spacer {
+    background-color: var(--sidebar-spacer);
+}
+
+@media (-moz-touch-enabled: 1), (pointer: coarse) {
+    .chapter li a { padding: 5px 0; }
+    .spacer { margin: 10px 0; }
+}
+
+.section {
+    list-style: none outside none;
+    padding-inline-start: 20px;
+    line-height: 1.9em;
+}
+
+/* Theme Menu Popup */
+
+.theme-popup {
+    position: absolute;
+    left: 10px;
+    top: var(--menu-bar-height);
+    z-index: 1000;
+    border-radius: 4px;
+    font-size: 0.7em;
+    color: var(--fg);
+    background: var(--theme-popup-bg);
+    border: 1px solid var(--theme-popup-border);
+    margin: 0;
+    padding: 0;
+    list-style: none;
+    display: none;
+    /* Don't let the children's background extend past the rounded corners. */
+    overflow: hidden;
+}
+[dir=rtl] .theme-popup { left: unset;  right: 10px; }
+.theme-popup .default {
+    color: var(--icons);
+}
+.theme-popup .theme {
+    width: 100%;
+    border: 0;
+    margin: 0;
+    padding: 2px 20px;
+    line-height: 25px;
+    white-space: nowrap;
+    text-align: start;
+    cursor: pointer;
+    color: inherit;
+    background: inherit;
+    font-size: inherit;
+}
+.theme-popup .theme:hover {
+    background-color: var(--theme-hover);
+}
+
+.theme-selected::before {
+    display: inline-block;
+    content: "✓";
+    margin-inline-start: -14px;
+    width: 14px;
+}
diff --git a/docs_src/theme/favicon.png b/docs_src/theme/favicon.png
new file mode 100644
index 00000000000..7bc766e4946
Binary files /dev/null and b/docs_src/theme/favicon.png differ
diff --git a/docs_src/theme/index.hbs b/docs_src/theme/index.hbs
new file mode 100644
index 00000000000..4f8a40f97d7
--- /dev/null
+++ b/docs_src/theme/index.hbs
@@ -0,0 +1,323 @@
+<!DOCTYPE HTML>
+<html lang="{{ language }}" class="{{ default_theme }} sidebar-visible" dir="{{ text_direction }}">
+    <head>
+        <!-- Book generated using mdBook -->
+        <meta charset="UTF-8">
+        <title>{{ title }}</title>
+        {{#if is_print }}
+        <meta name="robots" content="noindex">
+        {{/if}}
+        {{#if base_url}}
+        <base href="{{ base_url }}">
+        {{/if}}
+
+
+        <!-- Custom HTML head -->
+        {{> head}}
+
+        <meta name="description" content="{{ description }}">
+        <meta name="viewport" content="width=device-width, initial-scale=1">
+        <meta name="theme-color" content="#ffffff">
+
+        <link rel="shortcut icon" href="{{ path_to_root }}favicon.png">
+        <link rel="stylesheet" href="{{ path_to_root }}css/variables.css">
+        <link rel="stylesheet" href="{{ path_to_root }}css/general.css">
+        <link rel="stylesheet" href="{{ path_to_root }}css/chrome.css">
+        {{#if print_enable}}
+        <link rel="stylesheet" href="{{ path_to_root }}css/print.css" media="print">
+        {{/if}}
+
+        <!-- Fonts -->
+        <link rel="stylesheet" href="{{ path_to_root }}FontAwesome/css/font-awesome.css">
+        {{#if copy_fonts}}
+        <link rel="stylesheet" href="{{ path_to_root }}fonts/fonts.css">
+        {{/if}}
+
+        <!-- Highlight.js Stylesheets -->
+        <link rel="stylesheet" href="{{ path_to_root }}highlight.css">
+        <link rel="stylesheet" href="{{ path_to_root }}tomorrow-night.css">
+        <link rel="stylesheet" href="{{ path_to_root }}ayu-highlight.css">
+
+        <!-- Custom theme stylesheets -->
+        {{#each additional_css}}
+        <link rel="stylesheet" href="{{ ../path_to_root }}{{ this }}">
+        {{/each}}
+
+        {{#if mathjax_support}}
+        <!-- MathJax -->
+        <script async src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+        {{/if}}
+
+        <!-- Provide site root to javascript -->
+        <script>
+            var path_to_root = "{{ path_to_root }}";
+            var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "{{ preferred_dark_theme }}" : "{{ default_theme }}";
+        </script>
+        <!-- Start loading toc.js asap -->
+        <script src="{{ path_to_root }}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('{{ default_theme }}')
+            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="{{ path_to_root }}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="{{ path_to_root }}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">
+                {{> header}}
+                <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>
+                        <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>
+                        {{#if search_enabled}}
+                        <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>
+                        {{/if}}
+                    </div>
+
+                    <h1 class="menu-title">{{ book_title }}</h1>
+
+                    <div class="right-buttons">
+                        {{#if print_enable}}
+                        <a href="{{ path_to_root }}print.html" title="Print this book" aria-label="Print this book">
+                            <i id="print-button" class="fa fa-print"></i>
+                        </a>
+                        {{/if}}
+                        {{#if git_repository_url}}
+                        <a href="{{git_repository_url}}" title="Git repository" aria-label="Git repository">
+                            <i id="git-repository-button" class="fa {{git_repository_icon}}"></i>
+                        </a>
+                        {{/if}}
+                        {{#if git_repository_edit_url}}
+                        <a href="{{git_repository_edit_url}}" title="Suggest an edit" aria-label="Suggest an edit">
+                            <i id="git-edit-button" class="fa fa-edit"></i>
+                        </a>
+                        {{/if}}
+
+                    </div>
+                </div>
+
+                {{#if search_enabled}}
+                <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>
+                {{/if}}
+
+                <!-- 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>
+                        {{{ content }}}
+                    </main>
+
+                    <nav class="nav-wrapper" aria-label="Page navigation">
+                        <!-- Mobile navigation buttons -->
+                        {{#previous}}
+                            <a rel="prev" href="{{ path_to_root }}{{link}}" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
+                                <i class="fa fa-angle-left"></i>
+                            </a>
+                        {{/previous}}
+
+                        {{#next}}
+                            <a rel="next prefetch" href="{{ path_to_root }}{{link}}" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
+                                <i class="fa fa-angle-right"></i>
+                            </a>
+                        {{/next}}
+
+                        <div style="clear: both"></div>
+                    </nav>
+                </div>
+            </div>
+
+            <nav class="nav-wide-wrapper" aria-label="Page navigation">
+                {{#previous}}
+                    <a rel="prev" href="{{ path_to_root }}{{link}}" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
+                        <i class="fa fa-angle-left"></i>
+                    </a>
+                {{/previous}}
+
+                {{#next}}
+                    <a rel="next prefetch" href="{{ path_to_root }}{{link}}" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
+                        <i class="fa fa-angle-right"></i>
+                    </a>
+                {{/next}}
+            </nav>
+
+        </div>
+
+        {{#if live_reload_endpoint}}
+        <!-- Livereload script (if served using the cli tool) -->
+        <script>
+            const wsProtocol = location.protocol === 'https:' ? 'wss:' : 'ws:';
+            const wsAddress = wsProtocol + "//" + location.host + "/" + "{{{live_reload_endpoint}}}";
+            const socket = new WebSocket(wsAddress);
+            socket.onmessage = function (event) {
+                if (event.data === "reload") {
+                    socket.close();
+                    location.reload();
+                }
+            };
+
+            window.onbeforeunload = function() {
+                socket.close();
+            }
+        </script>
+        {{/if}}
+
+        {{#if google_analytics}}
+        <!-- Google Analytics Tag -->
+        <script>
+            var localAddrs = ["localhost", "127.0.0.1", ""];
+
+            // make sure we don't activate google analytics if the developer is
+            // inspecting the book locally...
+            if (localAddrs.indexOf(document.location.hostname) === -1) {
+                (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
+                (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
+                m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
+                })(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
+
+                ga('create', '{{google_analytics}}', 'auto');
+                ga('send', 'pageview');
+            }
+        </script>
+        {{/if}}
+
+        {{#if playground_line_numbers}}
+        <script>
+            window.playground_line_numbers = true;
+        </script>
+        {{/if}}
+
+        {{#if playground_copyable}}
+        <script>
+            window.playground_copyable = true;
+        </script>
+        {{/if}}
+
+        {{#if playground_js}}
+        <script src="{{ path_to_root }}ace.js"></script>
+        <script src="{{ path_to_root }}editor.js"></script>
+        <script src="{{ path_to_root }}mode-rust.js"></script>
+        <script src="{{ path_to_root }}theme-dawn.js"></script>
+        <script src="{{ path_to_root }}theme-tomorrow_night.js"></script>
+        {{/if}}
+
+        {{#if search_js}}
+        <script src="{{ path_to_root }}elasticlunr.min.js"></script>
+        <script src="{{ path_to_root }}mark.min.js"></script>
+        <script src="{{ path_to_root }}searcher.js"></script>
+        {{/if}}
+
+        <script src="{{ path_to_root }}clipboard.min.js"></script>
+        <script src="{{ path_to_root }}highlight.js"></script>
+        <script src="{{ path_to_root }}book.js"></script>
+
+        <!-- Custom JS scripts -->
+        {{#each additional_js}}
+        <script src="{{ ../path_to_root }}{{this}}"></script>
+        {{/each}}
+
+        {{#if is_print}}
+        {{#if mathjax_support}}
+        <script>
+        window.addEventListener('load', function() {
+            MathJax.Hub.Register.StartupHook('End', function() {
+                window.setTimeout(window.print, 100);
+            });
+        });
+        </script>
+        {{else}}
+        <script>
+        window.addEventListener('load', function() {
+            window.setTimeout(window.print, 100);
+        });
+        </script>
+        {{/if}}
+        {{/if}}
+
+    </div>
+    </body>
+</html>
diff --git a/filament/docs/Debugging.md b/filament/docs/Debugging.md
deleted file mode 100644
index a29f175874f..00000000000
--- a/filament/docs/Debugging.md
+++ /dev/null
@@ -1,79 +0,0 @@
-# Filament Debugging
-
-## Debugging Vulkan on Linux
-
-### Enable Validation Logs
-
-Simply install the LunarG SDK (it's fast and easy), then make sure you've got the following
-environment variables set up in your **bashrc** file. For example:
-
-```
-export VULKAN_SDK='/path_to_home/VulkanSDK/1.3.216.0/x86_64'
-export VK_LAYER_PATH="$VULKAN_SDK/etc/explicit_layer.d"
-export PATH="$VULKAN_SDK/bin:$PATH"
-```
-
-As long as you're running a debug build of Filament, you should now see extra debugging spew in your
-console if there are any errors or performance issues being caught by validation.
-
-### Frame Capture in RenderDoc
-
-The following instructions assume you've already installed the LunarG SDK and therefore have the
-`VK_LAYER_PATH` environment variable.
-
-1. Modify `VulkanDriver.cpp` by defining `ENABLE_RENDERDOC`
-1. Download the RenderDoc tarball for Linux and unzip it somewhere.
-1. Find `renderdoc_capture.json` in the unzipped folders and copy it to `VK_LAYER_PATH`. For
-example:
-```
-cp ~/Downloads/renderdoc_1.0/etc/vulkan/implicit_layer.d/renderdoc_capture.json ${VK_LAYER_PATH}
-```
-1. Edit `${VK_LAYER_PATH}/renderdoc_capture.json` and update the `library_path` attribute.
-1. Launch RenderDoc by running `renderdoc_1.0/bin/qrenderdoc`.
-1. Go to the **Launch Application** tab and click the ellipses next to **Environment Variables**.
-1. Add VK_LAYER_PATH so that it matches whatever you've got set in your **bashrc**.
-1. Save yourself some time in the future by clicking **Save Settings** after setting up the working
-directory, executable path, etc.
-1. Click **Launch** in RenderDoc, then press **F12** in your app.  You should see a new capture show up in
-RenderDoc.
-
-## Enable Metal Validation
-
-To enable the Metal validation layers when running a sample through the command-line, set the
-following environment variable:
-
-```
-export METAL_DEVICE_WRAPPER_TYPE=1
-```
-
-You should then see the following output when running a sample with the Metal backend:
-
-```
-2020-10-13 18:01:44.101 gltf_viewer[73303:4946828] Metal API Validation Enabled
-```
-
-## Metal Frame Capture from gltf_viewer
-
-To capture Metal frames from within gltf_viewer:
-
-### 1. Create an Info.plist file
-
-Create an `Info.plist` file in the same directory as `gltf_viewer` (`cmake/samples`). Set its
-contents to:
-
-```
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-<plist version="1.0">
-<dict>
-    <key>MetalCaptureEnabled</key>
-    <true/>
-</dict>
-</plist>
-```
-
-### 2. Capture a frame
-
-Run gltf_viewer as normal, and hit the "Capture frame" button under the Debug menu. The captured
-frame will be saved to `filament.gputrace` in the current working directory. This file can then be
-opened with Xcode for inspection.
diff --git a/filament/docs/Vulkan.md.html b/filament/docs/Vulkan.md.html
deleted file mode 100644
index 2a8902f3455..00000000000
--- a/filament/docs/Vulkan.md.html
+++ /dev/null
@@ -1,279 +0,0 @@
-<meta charset="utf-8">
-<link href="https://fonts.googleapis.com/css?family=Montserrat" rel="stylesheet">
-<style>
-    img { max-width: 100px !important }
-    .md, body, .md h1, .md div.title, .md a  {
-        font-family: "Montserrat", sans-serif;
-        color: #555;
-    }
-    .md div.title { color: #a55 }
-    .md a  { color: #55a }
-</style>
-
-**Vulkan Backend**
-          *Last updated: 26 October 2022*
-
-![](../../docs/images/filament_logo.png)
-
------
-
-This document is a high-level "state of the union" for Filament's Vulkan backend. Some of the
-details may be out of date by the time you read it, but we hope to keep it reasonably well
-maintained, which is why it lives as a markdown document in our source tree.
-
-# Architecture
-
-At a high level, the Vulkan backend is composed of the **driver**, a set of **helpers**, and
-a set of **handle types**.
-
-The driver is responsible for implementing all `DriverAPI` entry points, as well as managing a
-single `VkDevice` and `VkInstance`.
-
-************************************************************************************************
-*                                                                                              *
-*   .---------------------------------------.                                                  *
-*  |            Client Application           |                                                 *
-*   '------------------+--------------------'                                                  *
-*                      |                                                                       *
-*                      v                                                                       *
-*   .----------------------------------------.     .--------------------------------------.    *
-*  |        Filament Rendering Engine         |   |          filament::SwapChain           |   *
-*   '------------------+---------------------'     '------------------+-------------------'    *
-*                      |                                              |                        *
-*                      v                                              v                        *
-*   .----------------------------------------.     .---------------------------------------.   *
-*  |                                          |   |                                         |  *
-*  |       VulkanDriver : DriverBase          |   |     VulkanSwapChain : HwSwapChain       |  *
-*  |                                          |   |                                         |  *
-*  |------------------------------------------|   |-----------------------------------------|  *
-*  |                                          |   |                                         |  *
-*  |    Helpers            VulkanContext      |   |    VulkanTexture    VulkanTexture       |  *
-*  |  .--------------.    .---------------.   |   |   .----------------+----------------.   |  *
-*  |  | PipelineCache|   | VkDevice        |  |   |  | VkImage         | VkImage         |  |  *
-*  |  +--------------+   | VkInstance      |  |   |  | VkImageView     | VkImageView     |  |  *
-*  |  | Disposer     |   | VulkanCommands  |  |   |  |                 |                 |  |  *
-*  |  +--------------+    '---------------'   |   |   '----------------+----------------'   |  *
-*  |  | FboCache     |                        |   |                                         |  *
-*  |  +--------------+                        |   |                                         |  *
-*  |  | SamplerCache |                        |   |                                         |  *
-*  |  +--------------+                        |   |                                         |  *
-*  |  | StagePool    |                        |    '---------------------------------------'   *
-*  |  '--------------'                        |                                                *
-*  |                                          |                                                *
-*  |                                          |                                                *
-*  |                                          |                                                *
-*   '----------------------------------------'                                                 *
-*                                                                                              *
-************************************************************************************************
-
-# Overview
-
-## VulkanDriver and VulkanContext
-
-The `VulkanDriver` class is the bridge between the backend and the Filament engine, and is kept as
-minimal as possible. Most of the actual logic is contained in methods in `VulkanContext` and in the
-handle types rather than directly in `VulkanDriver`.
-
-In a self-imposed design constraint, we have decided that every method in `VulkanDriver` must be an
-override; it should have no private methods other than the handle allocators. This reins in
-complexity because it must implement every method in `DriverAPI` while dealing with Vulkan itself,
-which has an extremely low-level API.
-
-## Command buffers
-
-The `VulkanCommands` class creates command buffers on the fly and maintains a chain of semaphores
-to ensure that submitted command buffers are executed serially.
-
-## Handle types
-
-This sole purpose of `VulkanHandles.h` is to declare structs that descend from the hardware handles
-that are defined in `DriverBase.h`.
-
-Most of the handle types do not contain much logic, but they often do more than mere wrapping of
-Vk objects. Notably, `VulkanRenderTarget` does not have a straightforward mapping to any one Vk
-object. See its class comment for details. Also, `VulkanTexture` and `VulkanSwapChain` have their
-own cpps file because of complexity around layouts and subresources.
-
-VulkanProgram
-: Descends from `HwProgram`, owns a pair of `VkShaderModule`.
-
-VulkanRenderTarget
-: Descends from `HwRenderTarget`, contains references to `VulkanTexture` objects.
-
-VulkanSwapChain
-: Descends from `HwSwapChain`, has a reference to `VkSurfaceKHR` and `VkSwapchainKHR`.
-
-VulkanVertexBuffer
-: Descends from `HwVertexBuffer`, owns a set of `VkBuffer`.
-
-VulkanIndexBuffer
-: Descends from `HwIndexBuffer`, owns a `VkBuffer`.
-
-VulkanSamplerGroup
-: Descends from `HwSamplerGroup`, does not own Vk objects.
-
-VulkanTexture
-: Descends from `HwTexture`, owns a `VkImage` and a set of `VkImageLayout`.
-
-VulkanRenderPrimitive
-: Descends from `HwRenderPrimitive`, does not own Vk objects.
-
-One special case is `VulkanBuffer`, which is not a handle class. It encapulates functionality shared
-between `VulkanIndexBuffer` and `VulkanVertexBuffer`.
-
-## Helpers
-
-`VulkanDriver` owns one instance of each helper. They are not part of a class hierarchy but
-they do follow a common set of conventions. For example, most of them implement a `gc()` method
-that is called once per frame to free unused objects.
-
-VulkanPipelineCache
-: Cache of VkDescriptorSet, VkPipeline, and VkPipelineLayout.
-
-VulkanDisposer
-: Holds reference counts to Vulkan objects in order to defer their destruction.
-
-VulkanFboCache
-: Cache of VkRenderPass and VkFramebuffer. Contains weak references to VkImage handles, but does not
-  own any pixel data. The cache key for render passes is quite complex because it needs to include
-  image layout information in a compact way. For details see the comments in the `RenderPassKey`
-  declaration.
-
-VulkanStagePool
-: Pool of VkBuffer objects that can be memory mapped (shared between host and device).
-
-VulkanSamplerCache
-: This is our simplest cache object because Vulkan samplers are fairly lightweight and re-usable.
-
-## Folder layout and namespacing
-
-With the exception of BlueVK, all Vulkan-specific code lives in `backend/src/vulkan`, which has
-no subfolders. All backend-specific types and functions live directly in the `filament::backend`
-namespace, and we simply prefix our names with "Vulkan" when necessary to avoid ambiguation with
-OpenGL.
-
-# Image Layout Strategy
-
-Adhering to a coherent strategy for image layout transitions is crucial. Without this, validation
-errors (and actual black screens with some GPU vendors) occur far too easily and can feel like
-whack-a-mole.
-
-Vulkan provides several mechanisms for transitioning layout (render passes, barriers) so the
-strategy outlined below specifies which mechanism should be used in various scenarios.
-
-The current image layouts are tracked at the subresource level in `VulkanTexture` using a
-specialized STL-ish container that we designed for this purpose:
-[RangeMap](https://github.com/google/filament/blob/main/libs/utils/include/utils/RangeMap.h).
-
-In the past we tried to avoid tracking since it theoritically duplicates state that exists in the
-GPU vendor's driver. However in practice this was impossible to manage, because complex logic was
-required to deduce the current layout. Also, tracking lets us use `assert_invariant` in many places
-to ensure that the behavior described in this document is implemented properly.  It is much easier
-to catch errors with asserts than with validation.
-
-As of this writing, the current rules are:
-
-(1) **Read-Only Color Textures**
-
-These should be created in an UNDEFINED state and stay that way until data gets uploaded into them,
-at which point the appropriate subresources are transitioned to TRANSFER_DST_OPTIMAL for the upload,
-then to SHADER_READ_ONLY_OPTIMAL, both times using a barrier.  Note that a subresource might be
-updated several times; each time it undergoes these two transitions.
-
-If a shader samples from a texture whose mipmaps are only partially loaded, we might see validation
-warnings about how some subresources are in an UNDEFINED layout.  However if we are properly using
-the `createTextureView` driver API, then the Vulkan backend will not bind those particular
-subresources, so validation should not complain.
-
-(2) **Writeable Color Textures**
-
-During construction of the HwTexture, these are transitioned to GENERAL using a barrier.
-
-GENERAL layout is not recommended by AMD best practices but in our case we wish to avoid thrashing
-the layout between COLOR_ATTACHMENT_OPTIMAL and SHADER_READ_ONLY_OPTIMAL for post-processing
-effects.  Moreover we do not have a priori knowledge about blitting and read pixels usage.
-
-(3) **Depth Textures**
-
-During construction of the HwTexture, these are transitioned to GENERAL using a barrier.
-
-Note that some post-processing passes (e.g. SSAO) sample from the depth buffer while also enabling
-depth testing. Using GENERAL makes this legal.
-
-(4) **Swap Chain Textures**
-
-During construction, these are transitioned to GENERAL using a barrier. They are then transitioned
-to PRESENT at the end of the frame using a barrier, and transitioned back to GENERAL using the first
-render pass of the frame.
-
-Note that we transition to PRESENT using a barrier, but with some GPU vendors it might be preferable
-to transition them using the last render pass. However we have no way of knowing ahead of time which
-pass is last.
-
-Note that Filament allows swap chains to be used as blit targets and blit sources (e.g. for
-ReadPixels). Using GENERAL makes this easier to manage.
-
-(5) **Headless Swap Chain Textures**
-
-These follow the same rules as writeable color texture and depth textures.
-
-# VulkanPipelineCache
-
-Uniforms, samplers, and shaders are not directly bindable in Vulkan; instead they are bound through
-indirection layers called *pipelines* and *descriptor sets*. The `VulkanPipelineCache` class allows
-the driver to call methods that are conceptually simple like `bindUniformBuffer`, even though no
-such function exists in the low-level Vulkan API.
-
-Although it is actually just another cache manager, `VulkanPipelineCache` has a fairly rich set of
-public methods. See its header file for details.
-
-The pipeline cache also manages the *layout objects*, which constrain the number of uniform buffers
-and samplers that can be bound simultaneously (see `VkDescriptorSetLayout` and `VkPipelineLayout`).
-
-# Memory Allocation
-
-Some architectures (e.g. Adreno) only allow a small number of `VkDeviceMemory` objects to exist at
-once, so we consolidate these using a simple third-party library
-([vk_mem_alloc](https://github.com/GPUOpen-LibrariesAndSDKs/VulkanMemoryAllocator)). This library is
-used each time the backend needs to create a `VkBuffer` or `VkImage`. See `VulkanStagePool` for a
-usage example.
-
-# BlueVK
-
-BlueVK loads in functions for all Vulkan entry points and supported extensions. On Android, this
-is not absolutely necessary since core functionality is available through static linking. However,
-we found that in practice it is simpler to use BlueVK across all platforms because of its ability
-to load extensions.
-
-The BlueVK C++ source is generated from a Python script that consumes `vk.xml`. This XML file is an
-API specification maintained by Khronos on GitHub.
-
-None of the source files in the  Vulkan backend include `vulkan.h` directly,  instead they include
-the BlueVK header, which in turn includes the Vulkan headers.
-
-!!! Note
-    Each time we update BlueVK by feeding it the latest `vk.xml`, we should also update the
-    Vulkan headers that are checked in to `libs/bluevk/include/vulkan`. If BlueVK and the Vulkan
-    headers are not updated concurrently, this will cause build errors.
-
-# Top Issues
-
-Here we list some of the most significant issues and to-be-done items for the Vulkan backend.
-
-- Improve the UBO strategy
-    - Currently we use staging buffers and perform lots of copies (host-to-host, then host-to-device)
-    - Consider an approach similar to MetalDriver, which effectively implements double-buffering
-      using a pool of shared mem buffers
-- Consider using subpasses for the depth prepass
-- We lazily create pipeline objects
-        1. This is notoriously slow in Vulkan
-        2. We do lots of state hashing for this
-        3. Vulkan has special pipeline cache objects that we aren't using yet, but...
-        4. It might be better to enhance our driver API to allow a priori construction
-- We need more automated testing
-- We don't *quite* have feature parity with the OpenGL backend
-    - No support for streaming camera texture yet
-        - This is possible, even in Android O, just haven't gotten around to it yet
-
-<script src="https://casual-effects.com/markdeep/latest/markdeep.min.js"></script>
-<script>window.alreadyProcessedMarkdeep||(document.body.style.visibility="visible")</script>