Update README

Rename Windows CI artifact to filament-windows.tgz (#138 )
Fix Windows build (#137 )
2018-08-24 12:37:11 -07:00 · 2018-08-24 10:44:36 -07:00 · 2018-08-24 10:35:21 -07:00 · 2018-08-24 10:26:35 -07:00 · 2018-08-24 10:24:48 -07:00 · 2018-08-24 10:13:16 -07:00
2518 changed files with 51471 additions and 28015 deletions
@@ -0,0 +1,30 @@
+---
+name: Bug report
+about: Create a report to help us improve
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. ...
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Desktop (please complete the following information):**
+ - OS: [e.g. iOS]
+ - GPU: [e.g. NVIDIA GTX 1080]
+ - Backend: [OpenGL/Vulkan]
+
+**Smartphone (please complete the following information):**
+ - Device: [e.g. Pixel 2]
+ - OS: [e.g. Android Pie 9.0]
+
+**Additional context**
+Add any other context about the problem here.
@@ -0,0 +1,17 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is.
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**OS and backend**
+Is this feature OS/backend specific? If so, explain why.
@@ -1,18 +1,8 @@
 # ==================================================================================================
 # CMake
 # ==================================================================================================
-if(${CMAKE_SOURCE_DIR} STREQUAL ${CMAKE_BINARY_DIR})
-    message(FATAL_ERROR "Prevented in-tree build. Create a sub-directory and invoke cmake from there.")
-endif()
 cmake_minimum_required(VERSION 3.1)

-if (WIN32)
-    # On Windows we need to instruct cmake to generate the .def in order to get the .lib required
-    # when linking against dlls. CL.EXE will not generate .lib without .def file (or without pragma
-    # __declspec(dllexport) in front of each functions).
-    set(CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS ON)
-endif()
-
 # ==================================================================================================
 # Project declaration
 # ==================================================================================================
@@ -24,6 +14,8 @@ project(TNT)

 option(ENABLE_JAVA "Compile Java projects, requires a JDK and the JAVA_HOME env var" ON)

+option(USE_EXTERNAL_GLES3 "Experimental: Compile Filament against OpenGL ES 3" OFF)
+
 # ==================================================================================================
 # OS specific
 # ==================================================================================================
@@ -32,10 +24,10 @@ if (UNIX AND NOT APPLE AND NOT ANDROID)
 endif()

 if (WIN32)
-    # .exe and .dll must be together in the same folder to work.
-    set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib)
-    set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib)
-    set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin)
+    # On Windows we need to instruct cmake to generate the .def in order to get the .lib required
+    # when linking against dlls. CL.EXE will not generate .lib without .def file (or without pragma
+    # __declspec(dllexport) in front of each functions).
+    set(CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS ON)

    # TODO: Figure out why pdb generation messes with incremental compilaton.
    # IN RELEASE_WITH_DEBUG_INFO, generate debug info in .obj, no in pdb.
@@ -57,21 +49,56 @@ endif()
 #  Paths
 # ==================================================================================================
 # Where our external libs are
-set(EXTERNAL ${CMAKE_SOURCE_DIR}/third_party)
+set(EXTERNAL ${CMAKE_CURRENT_SOURCE_DIR}/third_party)

 # Where our libraries are
-set(LIBRARIES ${CMAKE_SOURCE_DIR}/libs)
+set(LIBRARIES ${CMAKE_CURRENT_SOURCE_DIR}/libs)

 # Where our filament code is
-set(FILAMENT ${CMAKE_SOURCE_DIR})
+set(FILAMENT ${CMAKE_CURRENT_SOURCE_DIR})

 # Where our tools are
-set(TOOLS ${CMAKE_SOURCE_DIR}/tools)
+set(TOOLS ${CMAKE_CURRENT_SOURCE_DIR}/tools)
+
+# ==================================================================================================
+# Compiler check
+# ==================================================================================================
+set(MIN_CLANG_VERSION "5.0")
+
+if (CMAKE_C_COMPILER_ID MATCHES "Clang")
+    if (CMAKE_C_COMPILER_VERSION VERSION_LESS MIN_CLANG_VERSION)
+        message(FATAL_ERROR "Detected C compiler Clang ${CMAKE_C_COMPILER_VERSION} < ${MIN_CLANG_VERSION}")
+    endif()
+else()
+    message(FATAL_ERROR "Detected C compiler ${CMAKE_C_COMPILER_ID} is unsupported")
+endif()
+
+if (CMAKE_CXX_COMPILER_ID MATCHES "Clang")
+    if (CMAKE_CXX_COMPILER_VERSION VERSION_LESS MIN_CLANG_VERSION)
+        message(FATAL_ERROR "Detected CXX compiler Clang ${CMAKE_CXX_COMPILER_VERSION} < ${MIN_CLANG_VERSION}")
+    endif()
+else()
+    message(FATAL_ERROR "Detected CXX compiler ${CMAKE_CXX_COMPILER_ID} is unsupported")
+endif()
+
+# Detect use of the clang-cl.exe frontend, which does not support all of clangs normal options
+if ("${CMAKE_CXX_COMPILER_ID}" STREQUAL "Clang" AND "${CMAKE_CXX_SIMULATE_ID}" STREQUAL "MSVC")
+    set(CLANG_CL true)
+endif()

 # ==================================================================================================
 # General compiler flags
 # ==================================================================================================
-set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -std=c++14 -fstrict-aliasing -Wno-unknown-pragmas -Wno-unused-function")
+set(CXX_STANDARD "-std=c++14")
+if (WIN32)
+    set(CXX_STANDARD "/std:c++14")
+endif()
+
+set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} ${CXX_STANDARD} -fstrict-aliasing -Wno-unknown-pragmas -Wno-unused-function")
+
+if (USE_EXTERNAL_GLES3)
+    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -DUSE_EXTERNAL_GLES3")
+endif()

 if (WIN32)
    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -D_USE_MATH_DEFINES=1")
@@ -97,6 +124,13 @@ if (CYGWIN)
    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fno-exceptions -fno-rtti")
 endif()

+if (CLANG_CL)
+    # Since the "secure" replacements that MSVC suggests are not portable, disable
+    # the deprecation warnings. Also disable warnings about use of POSIX functions (i.e. "unlink").
+    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -D_CRT_SECURE_NO_WARNINGS -D_CRT_NONSTDC_NO_DEPRECATE")
+    set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -D_CRT_SECURE_NO_WARNINGS -D_CRT_NONSTDC_NO_DEPRECATE")
+endif()
+
 # Add colors to ninja builds
 if (UNIX AND CMAKE_GENERATOR STREQUAL "Ninja")
    set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -fcolor-diagnostics")
@@ -106,7 +140,9 @@ endif()
 # ==================================================================================================
 # Release compiler flags
 # ==================================================================================================
-set(CMAKE_CXX_FLAGS_RELEASE "${CMAKE_CXX_FLAGS_RELEASE} -fomit-frame-pointer -ffunction-sections -fdata-sections")
+if (NOT CLANG_CL)
+    set(CMAKE_CXX_FLAGS_RELEASE "${CMAKE_CXX_FLAGS_RELEASE} -fomit-frame-pointer -ffunction-sections -fdata-sections")
+endif()

 # On Android RELEASE builds, we disable exceptions and RTTI to save some space (about 75 KiB
 # saved by -fno-exception and 10 KiB saved by -fno-rtti).
@@ -127,11 +163,11 @@ set(CMAKE_CXX_FLAGS_DEBUG "${CMAKE_CXX_FLAGS_DEBUG} ${EXTRA_SANITIZE_OPTIONS}")
 # Linker flags
 # ==================================================================================================
 # Strip unused sections
-set(GC_SECTIONS "--gc-sections")
-set(B_SYMBOLIC_FUNCTIONS "-Bsymbolic-functions")
+set(GC_SECTIONS "-Wl,--gc-sections")
+set(B_SYMBOLIC_FUNCTIONS "-Wl,-Bsymbolic-functions")

 if (APPLE)
-    set(GC_SECTIONS "-dead_strip")
+    set(GC_SECTIONS "-Wl,-dead_strip")
    set(B_SYMBOLIC_FUNCTIONS "")

    # tell ranlib to ignore empty compilation units
@@ -140,10 +176,13 @@ if (APPLE)
    # prevents ar from invoking ranlib, let CMake do it
    set(CMAKE_C_ARCHIVE_CREATE   "<CMAKE_AR> qc -S <TARGET> <LINK_FLAGS> <OBJECTS>")
    set(CMAKE_CXX_ARCHIVE_CREATE "<CMAKE_AR> qc -S <TARGET> <LINK_FLAGS> <OBJECTS>")
+elseif (CLANG_CL)
+    set(GC_SECTIONS "")
+    set(B_SYMBOLIC_FUNCTIONS "")
 endif()

-set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS}  -Wl,${GC_SECTIONS}")
-set(CMAKE_SHARED_LINKER_FLAGS "${CMAKE_SHARED_LINKER_FLAGS} -Wl,${GC_SECTIONS} -Wl,${B_SYMBOLIC_FUNCTIONS}")
+set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} ${GC_SECTIONS}")
+set(CMAKE_SHARED_LINKER_FLAGS "${CMAKE_SHARED_LINKER_FLAGS} ${GC_SECTIONS} ${B_SYMBOLIC_FUNCTIONS}")

 # ==================================================================================================
 # Project flags
@@ -203,6 +242,7 @@ add_subdirectory(${EXTERNAL}/libgtest/tnt)
 add_subdirectory(${LIBRARIES}/filabridge)
 add_subdirectory(${LIBRARIES}/filaflat)
 add_subdirectory(${LIBRARIES}/filamat)
+add_subdirectory(${LIBRARIES}/image)
 add_subdirectory(${LIBRARIES}/math)
 add_subdirectory(${LIBRARIES}/utils)
 add_subdirectory(${FILAMENT}/filament)
@@ -218,12 +258,14 @@ if (APPLE)
    add_subdirectory(${EXTERNAL}/moltenvk/tnt)
 endif()

+set (FILAMENT_SAMPLES_BINARY_DIR ${PROJECT_BINARY_DIR}/samples)
+
 if (NOT ANDROID)
    add_subdirectory(${FILAMENT}/samples)

    add_subdirectory(${LIBRARIES}/bluegl)
    add_subdirectory(${LIBRARIES}/filagui)
-    add_subdirectory(${LIBRARIES}/image)
+    add_subdirectory(${LIBRARIES}/imageio)

    add_subdirectory(${FILAMENT}/java)

@@ -246,6 +288,7 @@ if (NOT ANDROID)
    add_subdirectory(${TOOLS}/filamesh)
    add_subdirectory(${TOOLS}/matc)
    add_subdirectory(${TOOLS}/matinfo)
+    add_subdirectory(${TOOLS}/mipgen)
    add_subdirectory(${TOOLS}/normal-blending)
    add_subdirectory(${TOOLS}/roughness-prefilter)
    add_subdirectory(${TOOLS}/skygen)
@@ -254,5 +297,5 @@ endif()

 # Generate exported executables for cross-compiled builds (Android)
 if (NOT CMAKE_CROSSCOMPILING)
-    export(TARGETS matc cmgen FILE ${CMAKE_SOURCE_DIR}/${IMPORT_EXECUTABLES_DIR}/ImportExecutables-${CMAKE_BUILD_TYPE}.cmake)
+    export(TARGETS matc cmgen FILE ${FILAMENT}/${IMPORT_EXECUTABLES_DIR}/ImportExecutables-${CMAKE_BUILD_TYPE}.cmake)
 endif()
@@ -1,9 +1,13 @@
-![Filament logo](docs/images/filament_logo_small.png)
-
 # Filament

-Filament is a physically based rendering engine for Android, Linux, macOS and Windows. This
-rendering engine was designed to be as small as possible and as efficient as possible on Android.
+<img alt="Android" src="build/img/android.png" width="20px" height="20px" hspace="2px"/>![Android Build Status](https://filament-build.storage.googleapis.com/badges/build_status_android.svg)
+<img alt="Linux" src="build/img/linux.png" width="20px" height="20px" hspace="2px"/>![Linux Build Status](https://filament-build.storage.googleapis.com/badges/build_status_linux.svg)
+<img alt="macOS" src="build/img/macos.png" width="20px" height="20px" hspace="2px"/>![MacOS Build Status](https://filament-build.storage.googleapis.com/badges/build_status_mac.svg)
+<img alt="Windows" src="build/img/windows.png" width="20px" height="20px" hspace="2px"/>![Windows Build Status](https://filament-build.storage.googleapis.com/badges/build_status_windows.svg)
+
+Filament is a real-time physically based rendering engine for Android, Linux, macOS and Windows.
+This rendering engine was designed to be as small as possible and as efficient as possible
+on Android.

 Filament is currently used in the
 [Sceneform](https://developers.google.com/ar/develop/java/sceneform/) library both at runtime on
@@ -11,14 +15,15 @@ Android devices and as the renderer inside the Android Studio plugin.

 ## Documentation

- [Filament](https://google.github.io/filament/Filament.md.html), an in-depth explanation of the graphics capabilities and
-  implementation of Filament. This document explains the math and reasoning behind most of our
-  decisions.
- [Materials](https://google.github.io/filament//Materials.md.html), the full reference documentation for our material system.
-  This document explains our different material models, how to use the material compiler `matc` and
-  how to write custom materials.
- [Material Properties](https://google.github.io/filament/Material%20Properties.pdf), a reference sheet for the standard
-  material model.
+- [Filament](https://google.github.io/filament/Filament.md.html), an in-depth explanation of
+  real-time physically based rendering, the graphics capabilities and implementation of Filament.
+  This document explains the math and reasoning behind most of our decisions. This document is a
+  good introduction to PBR for graphics programmers.
+- [Materials](https://google.github.io/filament//Materials.md.html), the full reference
+  documentation for our material system. This document explains our different material models, how
+  to use the material compiler `matc` and how to write custom materials.
+- [Material Properties](https://google.github.io/filament/Material%20Properties.pdf), a reference
+  sheet for the standard material model.

 ## Samples

@@ -41,6 +46,7 @@ Here are a few sample materials rendered with Filament:

 - Native C++ API for Android, Linux, macOS and Windows
 - Java/JNI API for Android, Linux, macOS and Windows
+- [Python bindings](https://github.com/artometa/pyfilament)

 ### Backends

@@ -91,6 +97,7 @@ Many other features have been either prototyped or planned:
  - `docs`:                  Documentation
    - `math`:                Mathematica notebooks used to explore BRDFs, equations, etc.
  - `filament`:              Filament engine
+  - `ide`:                   Configuration files for IDEs (CLion, etc.)
  - `java`:                  Java bindings for Filament libraries
  - `libs`:                  Libraries
    - `bluegl`:                OpenGL bindings for macOS, Linux and Windows
@@ -99,7 +106,8 @@ Many other features have been either prototyped or planned:
    - `filaflat`:              Serialization/deserialization library used for materials
    - `filagui`:               Helper library for [Dear ImGui](https://github.com/ocornut/imgui)
    - `filamat`:               Material generation library
-    - `image`:                 Image library, only intended for internal use
+    - `image`:                 Image filtering and simple transforms
+    - `imageio`:               Image file reading / writing, only intended for internal use
    - `math`:                  Math library
    - `utils`:                 Utility library (threads, memory, data structures, etc.)
  - `samples`:               Sample desktop applications
@@ -110,6 +118,7 @@ Many other features have been either prototyped or planned:
    - `filamesh`:            Mesh converter
    - `matc`:                Material compiler
    - `matinfo`              Displays information about materials compiled with `matc`
+    - `mipgen`               Generates a series of miplevels from a source image.
    - `normal-blending`:     Tool to blend normal maps
    - `roughness-prefilter`: Pre-filters a roughness map from a normal map to reduce aliasing 
    - `skygen`:              Physically-based sky environment texture generator
@@ -117,9 +126,10 @@ Many other features have been either prototyped or planned:

 ## Building Filament

+### Prerequisites
+
 To build Filament, you must first install the following tools:

- repo
 - CMake 3.4 (or more recent)
 - clang 5.0 (or more recent)
 - [ninja 1.8](https://github.com/ninja-build/ninja/wiki/Pre-built-Ninja-packages) (or more recent)
@@ -141,6 +151,9 @@ To build Filament for Android you must also install the following:

 Make sure the environment variable `ANDROID_HOME` points to the location of your Android SDK.

+By default our build system will attempt to compile the Java bindings. To do so, the environment
+variable `JAVA_HOME` should point to the location of your JDK.
+
 ### IDE

 We recommend using CLion to develop for Filament. Simply open the root directory's CMakeList.txt
@@ -176,39 +189,68 @@ To install the libraries and executables in `out/debug/` and `out/release/`, add
 You can force a clean build by adding the `-c` flag. The script offers more features described
 by executing `build.sh -h`.

-You can skip building the Java based components of the projects by using the `-j` flag:
+### Disabling Java builds
+
+By default our build system will attempt to compile the Java bindings. If you wish to skip this
+compilation step simply pass the `-j` flag to `build.sh`:

 ```
 $ ./build.sh -j release
 ```

-#### Linux
+If you use CMake directly instead of the build script, pass `-DENABLE_JAVA=OFF` to CMake instead.
+
+### Linux

 Make sure you've installed the following dependencies:

 - `libglu1-mesa-dev`
- `libc++-dev`
+- `libc++-dev` (`libcxx-devel` on Fedora)
 - `libc++abi-dev`
 - `ninja-build`

+In addition your distribution might require:
+
+- `libxi-dev`
+
 Then invoke `cmake`:

 ```
-$ mkdir build-release
-$ cd build-release
-$ cmake -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=../dist-linux ..
+$ mkdir out/cmake-release
+$ cd out/cmake-release
+$ cmake -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=../release/filament ../..
+```
+
+If you experience link errors you must ensure that you are using `libc++abi` by passing this
+extra parameter to `cmake`:
+
+```
+-DFILAMENT_REQUIRES_CXXABI=true
 ```

 Your Linux distribution might default to `gcc` instead of `clang`, if that's the case invoke
 `cmake` with the following command:

 ```
-$ mkdir build-release
-$ cd build-release
-$ cmake -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=../dist-linux ..
+$ mkdir out/cmake-release
+$ cd out/cmake-release
+# Or use a specific version of clang, for instance /usr/bin/clang-5.0
+$ CC=/usr/bin/clang CXX=/usr/bin/clang++ \
+    cmake -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=../release/filament ../..
 ```

-And then invoke `ninja`:
+You can also export the `CC` and `CXX` environment variables to always point to `clang`. Another
+solution is to use `update-alternatives` to both change the default compiler, and point to a
+specific version of clang:
+
+```
+$ update-alternatives --install /usr/bin/cc cc /usr/bin/clang 100
+$ update-alternatives --install /usr/bin/c++ c++ /usr/bin/clang++ 100
+$ update-alternatives --install /usr/bin/clang clang /usr/bin/clang-5.0 100
+$ update-alternatives --install /usr/bin/clang++ clang++ /usr/bin/clang++-5.0 100
+```
+
+Finally, invoke `ninja`:

 ```
 $ ninja
@@ -216,7 +258,7 @@ $ ninja

 This will build Filament, its tests and samples, and various host tools.

-#### macOS
+### macOS

 To compile Filament you must have the most recent version of Xcode installed and you need to
 make sure the command line tools are setup by running:
@@ -236,9 +278,9 @@ export JAVA_HOME="$(/usr/libexec/java_home)"
 Then run `cmake` and `ninja` to trigger a build:

 ```
-$ mkdir build-release
-$ cd build-release
-$ cmake -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=../dist-darwin ..
+$ mkdir out/cmake-release
+$ cd out/cmake-release
+$ cmake -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=../release/filament ../..
 $ ninja
 ```

@@ -252,27 +294,23 @@ Google employees require additional steps which can be found here [go/filawin](h
 Install the following components:

 - [Windows 10 SDK](https://developer.microsoft.com/en-us/windows/downloads/windows-10-sdk)
- [Visual Studio 2015](https://www.visualstudio.com/downloads) (request MSDN membership if
-  needed)
- [Clang 7 for MSVC](http://prereleases.llvm.org/win-snapshots/LLVM-7.0.0-r323406-win32.exe)
- [Python 3.7](https://www.python.org/ftp/python/3.7.0/python-3.7.0b1.exe)
+- [Visual Studio 2015](https://www.visualstudio.com/downloads)
+- [Clang 6](http://releases.llvm.org/download.html)
+- [Python 3.7](https://www.python.org/ftp/python/3.7.0/python-3.7.0.exe)
 - [Git 2.16.1 or later](https://github.com/git-for-windows/git/releases/download/v2.16.1.windows.4/PortableGit-2.16.1.4-64-bit.7z.exe)
- [Cmake 3.4](https://cmake.org/files/v3.11/cmake-3.11.0-rc1-win64-x64.msi)
- [repo](https://storage.googleapis.com/git-repo-downloads/repo), add it to PATH (open the
-  Control Panel > System and Security > System >  Advanced System Settings > Environment variables)
+- [Cmake 3.11 or later](https://cmake.org/files/v3.11/cmake-3.11.0-rc1-win64-x64.msi)

-Open an x86_64 VS 2015 terminal (click the start button, type "x86" and select:
-"x86_64 cross tools command prompt for VS 2015").
+Open an VS2015 x64 Native Tools terminal (click the start button, type "x64 native tools" and select: "VS2015 x64 Native Tools Command Prompt").

 Create a working directory:
 ```
-> mkdir cmake-windows
-> cd cmake-windows
+> mkdir out/cmake-release
+> cd out/cmake-release
 ```

 Create the msBuild project:
 ```
-> cmake -T"LLVM-vs2014" -G "Visual Studio 14 2015 Win64" ..
+> cmake -T"LLVM-vs2014" -G "Visual Studio 14 2015 Win64" ../..
 ```

 Check out the output and make sure Clang for Windows frontend was found. You should see a line
@@ -283,12 +321,12 @@ Clang:C:/Program Files/LLVM/msbuild-bin/cl.exe

 You are now ready to build:
 ```
-> msbuild  TNT.sln /t:material_sandbox /m /p:configuration=Debug /v:d
+> msbuild  TNT.sln /t:material_sandbox /m /p:configuration=Debug
 ```

 Run it:
 ```
-> bin\Debug\material_sandbox.exe ..\filament\assets\models\monkey\monkey.obj
+> samples\material_sandbox.exe ..\..\assets\models\monkey\monkey.obj
 ```

 #### Tips
@@ -301,6 +339,29 @@ Run it:
 - The msBuild project is what is used by Visual Studio behind the scene to build. Building from VS
  or from the command-line is the same thing.

+#### Building with Ninja on Windows
+
+Alternatively, you can use [Ninja](https://ninja-build.org/) to build for Windows. An MSVC
+installation is still necessary.
+
+First, install the dependencies listed under [Windows](#Windows) as well as Ninja. Then open up a
+VS2015 x64 Native Tools terminal as before. Create a build directory inside Filament and run the
+following CMake command:
+
+```
+cmake .. -G Ninja ^
+-DCMAKE_CXX_COMPILER:PATH="C:\Program Files\LLVM\bin\clang-cl.exe" ^
+-DCMAKE_C_COMPILER:PATH="C:\Program Files\LLVM\bin\clang-cl.exe" ^
+-DCMAKE_LINKER:PATH="C:\Program Files\LLVM\bin\lld-link.exe" ^
+-DCMAKE_BUILD_TYPE=Release
+```
+
+You should then be able to build by invoking Ninja:
+
+```
+ninja
+```
+
 #### Development tips

 - Before shipping a binary, make sure you used Release profile and make sure you have no libc/libc++
@@ -313,7 +374,7 @@ Run it:
 To confirm Filament was properly built, run the following command from the build directory:

 ```
-./samples/material_sandbox --ibl=../samples/envs/office ../assets/models/sphere/sphere.obj
+./samples/material_sandbox --ibl=../../samples/envs/office ../../assets/models/sphere/sphere.obj
 ```

 ### Android
@@ -365,10 +426,10 @@ $ $SDK/ndk-bundle/build/tools/make_standalone_toolchain.py --arch arm64 --api 24
 Then invoke CMake in a build directory of your choice, inside of filament's directory:

 ```
-$ mkdir android-build-release-aarch64
-$ cd android-build-release-aarch64
-$ cmake -G Ninja -DCMAKE_TOOLCHAIN_FILE=../build/toolchain-aarch64-linux-android.cmake \
-        -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=../dist ..
+$ mkdir out/android-build-release-aarch64
+$ cd out/android-build-release-aarch64
+$ cmake -G Ninja -DCMAKE_TOOLCHAIN_FILE=../../build/toolchain-aarch64-linux-android.cmake \
+        -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=../android-release/filament ../..
 ```

 And then invoke `ninja`:
@@ -383,9 +444,9 @@ or
 $ ninja install/strip
 ```

-This will generate Filament's Android binaries in `dist`. This location is important to build the
-Android Studio projects located in `filament/android`. After install, the library binaries should
-be found in `dist/lib/arm64-v8a`.
+This will generate Filament's Android binaries in `out/android-release`. This location is important
+to build the Android Studio projects located in `filament/android`. After install, the library
+binaries should be found in `out/android-release/filament/lib/arm64-v8a`.

 #### ARM 32-bit target (armeabi-v7a)

@@ -410,10 +471,10 @@ $ $SDK/ndk-bundle/build/tools/make_standalone_toolchain.py --arch arm --api 24 \
 Then invoke CMake in a build directory of your choice, inside of filament's directory:

 ```
-$ mkdir android-build-release-arm
-$ cd android-build-release-arm
-$ cmake -G Ninja -DCMAKE_TOOLCHAIN_FILE=../build/toolchain-arm7-linux-android.cmake \
-        -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=../dist ..
+$ mkdir out/android-build-release-arm
+$ cd out/android-build-release-arm
+$ cmake -G Ninja -DCMAKE_TOOLCHAIN_FILE=../../build/toolchain-arm7-linux-android.cmake \
+        -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=../android-release/filament ../..
 ```

 And then invoke `ninja`:
@@ -428,9 +489,9 @@ or
 $ ninja install/strip
 ```

-This will generate Filament's Android binaries in `dist`. This location is important to build the
-Android Studio projects located in `filament/android`. After install, the library binaries should
-be found in `dist/lib/armeabi-v7a`.
+This will generate Filament's Android binaries in `out/android-release`. This location is important
+to build the Android Studio projects located in `filament/android`. After install, the library
+binaries should be found in `out/android-release/filament/lib/armeabi-v7a`.

 #### Intel 64-bit target (x86_64)

@@ -455,10 +516,10 @@ $ $SDK/ndk-bundle/build/tools/make_standalone_toolchain.py --arch x86_64 --api 2
 Then invoke CMake in a build directory of your choice, sibling of filament's directory:

 ```
-$ mkdir android-build-release-x86_64
-$ cd android-build-release-x86_64
-$ cmake -G Ninja -DCMAKE_TOOLCHAIN_FILE=../filament/build/toolchain-x86_64-linux-android.cmake \
-        -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=../dist ..
+$ mkdir out/android-build-release-x86_64
+$ cd out/android-build-release-x86_64
+$ cmake -G Ninja -DCMAKE_TOOLCHAIN_FILE=../../filament/build/toolchain-x86_64-linux-android.cmake \
+        -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=../out/android-release/filament ../..
 ```

 And then invoke `ninja`:
@@ -473,9 +534,9 @@ or
 $ ninja install/strip
 ```

-This will generate Filament's Android binaries in `dist`. This location is important to build the
-Android Studio projects located in `filament/android`. After install, the library binaries should
-be found in `dist/lib/x86_64`.
+This will generate Filament's Android binaries in `out/android-release`. This location is important
+to build the Android Studio projects located in `filament/android`. After install, the library
+binaries should be found in `out/android-release/filament/lib/x86_64`.

 #### Intel 32-bit target (x86)

@@ -500,10 +561,10 @@ $ $SDK/ndk-bundle/build/tools/make_standalone_toolchain.py --arch x86 --api 24 \
 Then invoke CMake in a build directory of your choice, sibling of filament's directory:

 ```
-$ mkdir android-build-release-x86
-$ cd android-build-release-x86
-$ cmake -G Ninja -DCMAKE_TOOLCHAIN_FILE=../filament/build/toolchain-x86-linux-android.cmake \
-        -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=../dist ..
+$ mkdir out/android-build-release-x86
+$ cd out/android-build-release-x86
+$ cmake -G Ninja -DCMAKE_TOOLCHAIN_FILE=../../filament/build/toolchain-x86-linux-android.cmake \
+        -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=../out/android-release/filament ../..
 ```

 And then invoke `ninja`:
@@ -518,12 +579,21 @@ or
 $ ninja install/strip
 ```

-This will generate Filament's Android binaries in `dist`. This location is important to build the
-Android Studio projects located in `filament/android`. After install, the library binaries should
-be found in `dist/lib/x86`.
+This will generate Filament's Android binaries in `out/android-release`. This location is important
+to build the Android Studio projects located in `filament/android`. After install, the library
+binaries should be found in `out/android-release/filament/lib/x86`.

 ### AAR

+Before you attempt to build the AAR, make sure you've compiled and installed the native libraries
+as explained in the sections above. You must have the following ABIs built in
+`out/android-release/filament/lib/`:
+
+- `arm64-v8a`
+- `armeabi-v7a`
+- `x86_64`
+- `x86`
+
 To build Filament's AAR simply open the Android Studio project in `android/filament-android`. The
 AAR is a universal AAR that contains all supported build targets:

@@ -535,6 +605,16 @@ AAR is a universal AAR that contains all supported build targets:
 To filter out unneeded ABIs, rely on the `abiFilters` of the project that links against Filament's
 AAR.

+Alternatively you can build the AAR from the command line by executing the following the
+`android/filament-android` directory:
+
+```
+$ ./gradlew -Pfilament_dist_dir=../../out/android-release/filament assembleRelease
+```
+
+The `-Pfilament_dist_dir` can be used to specify a different installation directory (it must match
+the CMake install prefix used in the previous steps).
+
 ### Using Filament's AAR

 Create a new module in your project and select _Import .JAR or .AAR Package_ when prompted. Make
@@ -585,7 +665,7 @@ generate a `filamesh ` file from an FBX/OBJ asset, run the `filamesh` tool
 (`./tools/filamesh/filamesh` in your build directory):

 ```
-filamesh assets/models/monkey/monkey.obj monkey.filamesh
+filamesh ./assets/models/monkey/monkey.obj monkey.filamesh
 ```

 Most samples accept an IBL that must be generated using the `cmgen` tool (`./tools/filamesh/cmgen`
@@ -625,7 +705,7 @@ Renderer* renderer = engine->createRenderer();
 To render a frame you must then create a `View`, a `Scene` and a `Camera`:

 ```c++
-Camera* = engine->createCamera();
+Camera* camera = engine->createCamera();
 View* view = engine->createView();
 Scene* scene = engine->createScene();

@@ -12,7 +12,7 @@ buildscript {
        jcenter()
    }
    dependencies {
-        classpath 'com.android.tools.build:gradle:3.0.1'
+        classpath 'com.android.tools.build:gradle:3.1.3'
    }
 }

@@ -25,16 +25,16 @@ allprojects {

 apply plugin: 'com.android.library'

-def filament_path = file("../../out/release/filament").absolutePath
+def filament_path = file("../../out/android-release/filament").absolutePath
 if (project.hasProperty("filament_dist_dir")) {
    filament_path = file("$filament_dist_dir").absolutePath
 }

 android {
-    compileSdkVersion 26
+    compileSdkVersion 28
    defaultConfig {
        minSdkVersion 14
-        targetSdkVersion 26
+        targetSdkVersion 28
        versionCode 1
        versionName "1.0"

@@ -81,7 +81,7 @@ android {

 dependencies {
    implementation fileTree(include: ['*.jar'], dir: 'libs')
-    implementation 'com.android.support:support-annotations:27.0.2'
+    implementation 'com.android.support:support-annotations:27.1.1'
 }

 group = "com.google.android.filament"
@@ -1,6 +1,6 @@
-#Wed Dec 13 19:09:17 PST 2017
+#Sun Aug 05 15:12:47 PDT 2018
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-4.1-all.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-4.4-all.zip
@@ -155,6 +155,13 @@ Java_com_google_android_filament_LightManager_nBuilderBuild(JNIEnv *env, jclass
    return jboolean(builder->build(*engine, (Entity &) entity) == LightManager::Builder::Success);
 }

+extern "C" JNIEXPORT jint JNICALL
+Java_com_google_android_filament_LightManager_nGetType(JNIEnv* env,
+        jclass type, jlong nativeLightManager, jint i) {
+    LightManager *lm = (LightManager *) nativeLightManager;
+    return (jint)lm->getType((LightManager::Instance) i);
+}
+
 extern "C" JNIEXPORT void JNICALL
 Java_com_google_android_filament_LightManager_nSetPosition(JNIEnv *env, jclass type,
        jlong nativeLightManager, jint i, jfloat x, jfloat y, jfloat z) {
@@ -172,6 +172,11 @@ public class LightManager {
        }
    }

+    @NonNull
+    public Type getType(@EntityInstance int i) {
+        return Type.values()[nGetType(mNativeObject, i)];
+    }
+
    public void setPosition(@EntityInstance int i, float x, float y, float z) {
        nSetPosition(mNativeObject, i, x, y, z);
    }
@@ -283,6 +288,8 @@ public class LightManager {
    private static native void nBuilderHaloSize(long nativeBuilder, float haloSize);
    private static native void nBuilderHaloFalloff(long nativeBuilder, float haloFalloff);

+
+    private static native int nGetType(long nativeLightManager, int i);
    private static native void nSetPosition(long nativeLightManager, int i, float x, float y, float z);
    private static native void nGetPosition(long nativeLightManager, int i, float[] out);
    private static native void nSetDirection(long nativeLightManager, int i, float x, float y, float z);
@@ -34,6 +34,8 @@ function print_help {
    echo "        Restrict the number of make/ninja jobs."
    echo "    -t"
    echo "        Generate the Android toolchain, requires \$ANDROID_HOME to be set."
+    echo "    -u"
+    echo "        Run all unit tests, will trigger a debug build if needed."
    echo "    -v"
    echo "        Add Vulkan support to the Android build."
    echo ""
@@ -75,6 +77,8 @@ ISSUE_ARCHIVES=false

 ISSUE_CMAKE_ALWAYS=false

+RUN_TESTS=false
+
 ENABLE_JAVA=ON

 INSTALL_COMMAND=
@@ -315,14 +319,35 @@ function validate_build_command {
            exit 1
        fi
    fi
+    # Make sure we have Java
+    javac_binary=`which javac`
+    if [ "$JAVA_HOME" == "" ] || [ ! "$javac_binary" ]; then
+        echo "Warning: JAVA_HOME is not set, skipping Java projects"
+        ENABLE_JAVA=OFF
+    fi
    set -e
 }

+function run_test {
+    test=$1
+    # The input string might contain arguments, so we use "set -- $test" to replace $1 with the
+    # first whitespace-separated token in the string.
+    set -- $test
+    test_name=`basename $1`
+    ./out/cmake-debug/$test --gtest_output="xml:out/test-results/$test_name/sponge_log.xml"
+}
+
+function run_tests {
+    while read test; do
+        run_test "$test"
+    done < build/common/test_list.txt
+}
+
 # Beginning of the script

 pushd `dirname $0` > /dev/null

-while getopts ":hacfijmp:tv" opt; do
+while getopts ":hacfijmp:tuv" opt; do
    case ${opt} in
        h)
            print_help
@@ -367,6 +392,10 @@ while getopts ":hacfijmp:tv" opt; do
        t)
            GENERATE_TOOLCHAINS=true
            ;;
+        u)
+            ISSUE_DEBUG_BUILD=true
+            RUN_TESTS=true
+            ;;
        v)
            VULKAN_ANDROID_OPTION="-DFILAMENT_SUPPORTS_VULKAN=ON"
            echo "Enabling support for Vulkan in the core Filament library."
@@ -426,3 +455,7 @@ fi
 if [ "$ISSUE_ANDROID_BUILD" == "true" ]; then
    build_android
 fi
+
+if [ "$RUN_TESTS" == "true" ]; then
+    run_tests
+fi
@@ -18,10 +18,13 @@ LC_UNAME=`echo $UNAME | tr '[:upper:]' '[:lower:]'`
 #     $GENERATE_ARCHIVES
 #     $BUILD_DEBUG
 #     $BUILD_RELEASE
+source `dirname $0`/../common/ci-common.sh
 if [  "$LC_UNAME" == "linux" ]; then
    source `dirname $0`/../linux/ci-common.sh
+elif [ "$LC_UNAME" == "darwin" ]; then
+    source `dirname $0`/../mac/ci-common.sh
 fi
-source `dirname $0`/../linux/build-common.sh
+source `dirname $0`/../common/build-common.sh

 pushd `dirname $0`/../.. > /dev/null
 ./build.sh -p android -c $GENERATE_ARCHIVES $BUILD_DEBUG $BUILD_RELEASE
@@ -2,8 +2,9 @@

 action {
  define_artifacts {
-    regex: "git/filament/out/*.tgz"
-    regex: "git/filament/out/*.aar"
-    strip_prefix: "git/filament/out"
+    regex: "github/filament/out/*.tgz"
+    regex: "github/filament/out/*.aar"
+    strip_prefix: "github/filament/out"
+    regex: "**/*sponge_log.xml"
  }
 }
@@ -13,6 +13,7 @@ echo "Building $TARGET target"
 BUILD_DEBUG=
 BUILD_RELEASE=
 GENERATE_ARCHIVES=
+RUN_TESTS=

 if [ "$TARGET" == "presubmit" ]; then
    BUILD_RELEASE=release
@@ -32,4 +33,5 @@ if [ "$TARGET" == "continuous" ]; then
    BUILD_DEBUG=debug
    BUILD_RELEASE=release
    GENERATE_ARCHIVES=-a
+    RUN_TESTS=-u
 fi
@@ -0,0 +1,6 @@
+#!/bin/bash
+
+if [ "$KOKORO_BUILD_ID" ]; then
+    echo "Running job $KOKORO_JOB_NAME"
+    TARGET=`echo "$KOKORO_JOB_NAME" | awk -F "/" '{print $NF}'`
+fi
@@ -0,0 +1,7 @@
+filament/test/test_filament --gtest_filter=-FilamentTest.FroxelData
+filament/test/test_filament_exposure --gtest_filter=-FilamentExposureWithEngineTest.SetExposure:FilamentExposureWithEngineTest.ComputeEV100
+libs/math/test_math
+libs/image/test_image compare libs/image/tests/reference/
+libs/utils/test_utils
+tools/matc/test_matc
+tools/cmgen/test_cmgen compare
@@ -15,8 +15,9 @@ set -x
 #     $GENERATE_ARCHIVES
 #     $BUILD_DEBUG
 #     $BUILD_RELEASE
+source `dirname $0`/../common/ci-common.sh
 source `dirname $0`/ci-common.sh
-source `dirname $0`/build-common.sh
+source `dirname $0`/../common/build-common.sh

 pushd `dirname $0`/../.. > /dev/null
-./build.sh -c $GENERATE_ARCHIVES $BUILD_DEBUG $BUILD_RELEASE
+./build.sh -c $RUN_TESTS $GENERATE_ARCHIVES $BUILD_DEBUG $BUILD_RELEASE
@@ -9,9 +9,6 @@ CXX_VERSION=5.0.2
 # CI runs on Ubuntu 14.04, we need to install clang-5.0 and th
 # appropriate libc++ ourselves
 if [ "$KOKORO_BUILD_ID" ]; then
-    echo "Running job $KOKORO_JOB_NAME"
-    TARGET=`echo "$KOKORO_JOB_NAME" | awk -F "/" '{print $NF}'`
-
    sudo ln -s /usr/include/x86_64-linux-gnu/asm /usr/include/asm

    sudo apt-add-repository "deb http://apt.llvm.org/trusty/ llvm-toolchain-trusty-$CLANG_VERSION main"
@@ -2,8 +2,9 @@

 action {
  define_artifacts {
-    regex: "git/filament/out/*.tgz"
-    regex: "git/filament/out/*.aar"
-    strip_prefix: "git/filament/out"
+    regex: "github/filament/out/*.tgz"
+    regex: "github/filament/out/*.aar"
+    strip_prefix: "github/filament/out"
+    regex: "**/*sponge_log.xml"
  }
 }
@@ -11,12 +11,9 @@
 set -e
 set -x

-curl -OL https://github.com/ninja-build/ninja/releases/download/v1.8.2/ninja-mac.zip
-unzip -q ninja-mac.zip
-chmod +x ninja
-export PATH="$PWD:$PATH"
-
-source `dirname $0`/../linux/build-common.sh
+source `dirname $0`/../common/ci-common.sh
+source `dirname $0`/ci-common.sh
+source `dirname $0`/../common/build-common.sh

 pushd `dirname $0`/../.. > /dev/null
-./build.sh -c $GENERATE_ARCHIVES $BUILD_DEBUG $BUILD_RELEASE
+./build.sh -c $RUN_TESTS $GENERATE_ARCHIVES $BUILD_DEBUG $BUILD_RELEASE
@@ -0,0 +1,6 @@
+#!/bin/bash
+
+curl -OL https://github.com/ninja-build/ninja/releases/download/v1.8.2/ninja-mac.zip
+unzip -q ninja-mac.zip
+chmod +x ninja
+export PATH="$PWD:$PATH"
@@ -2,8 +2,9 @@

 action {
  define_artifacts {
-    regex: "git/filament/out/*.tgz"
-    regex: "git/filament/out/*.aar"
-    strip_prefix: "git/filament/out"
+    regex: "github/filament/out/*.tgz"
+    regex: "github/filament/out/*.aar"
+    strip_prefix: "github/filament/out"
+    regex: "**/*sponge_log.xml"
  }
 }
@@ -0,0 +1,43 @@
+@echo off
+
+:: Install build dependencies
+call %~dp0ci-common.bat
+if errorlevel 1 exit /b %errorlevel%
+
+:: Put Visual Studio tools on the PATH
+call "C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\vcvarsall.bat" amd64
+if errorlevel 1 exit /b %errorlevel%
+
+:: Ensure that the necessary build tools are on the PATH
+call %~dp0validate-build-dependencies.bat
+if errorlevel 1 exit /b %errorlevel%
+
+ninja --version
+clang-cl --version
+lld-link --version
+cmake --version
+
+cd github\filament
+
+mkdir out\cmake-release
+cd out\cmake-release
+if errorlevel 1 exit /b %errorlevel%
+
+cmake ..\.. -G Ninja ^
+    -DCMAKE_CXX_COMPILER:PATH="clang-cl.exe" ^
+    -DCMAKE_C_COMPILER:PATH="clang-cl.exe" ^
+    -DCMAKE_LINKER:PATH="lld-link.exe" ^
+    -DCMAKE_BUILD_TYPE=Release
+if errorlevel 1 exit /b %errorlevel%
+
+ninja
+if errorlevel 1 exit /b %errorlevel%
+
+ninja install
+if errorlevel 1 exit /b %errorlevel%
+
+:: Create an archive
+dir .\install
+7z a -ttar -so ..\filament-release.tar .\install\* | 7z a -si ..\filament-windows.tgz
+
+echo Done!
@@ -0,0 +1,9 @@
+if defined KOKORO_BUILD_ID (
+    choco install llvm --version 6.0.1 -y
+    if errorlevel 1 exit /b %errorlevel%
+
+    :: refreshenv is necessary to put LLVM on path
+    refreshenv
+)
+
+exit /b 0
@@ -0,0 +1,10 @@
+# Format: //devtools/kokoro/config/proto/build.proto
+
+action {
+  define_artifacts {
+    regex: "github/filament/out/*.tgz"
+    regex: "github/filament/out/*.aar"
+    strip_prefix: "github/filament/out"
+    regex: "**/*sponge_log.xml"
+  }
+}
@@ -0,0 +1,3 @@
+# Format: //devtools/kokoro/config/proto/build.proto
+
+build_file: "filament/build/windows/build.bat"
@@ -0,0 +1,3 @@
+# Format: //devtools/kokoro/config/proto/build.proto
+
+build_file: "filament/build/windows/build.bat"
@@ -0,0 +1,3 @@
+# Format: //devtools/kokoro/config/proto/build.proto
+
+build_file: "filament/build/windows/build.bat"
@@ -0,0 +1,36 @@
+@echo off
+
+:: Check that rc.exe is available on PATH
+where rc 1>NUL 2>&1
+if errorlevel 1 (
+    echo Error: could not find rc, exiting
+    exit /b 1
+)
+
+:: Check that Clang is installed
+where clang-cl 1>NUL 2>&1
+if errorlevel 1 (
+    echo Error: could not find clang-cl, exiting
+    exit /b 1
+)
+where lld-link 1>NUL 2>&1
+if errorlevel 1 (
+    echo Error: could not find lld-link, exiting
+    exit /b 1
+)
+
+:: Check that Ninja is installed
+where ninja 1>NUL 2>&1
+if errorlevel 1 (
+    echo Error: could not find ninja, exiting
+    exit /b 1
+)
+
+:: Check that CMake is installed
+where cmake 1>NUL 2>&1
+if errorlevel 1 (
+    echo Error: could not find cmake, exiting
+    exit /b 1
+)
+
+exit /b 0
@@ -2,11 +2,16 @@

 <style>img { max-width: 100%; }</style>

-                   **Filament Materials**
-            Crafting physically-based materials
-
 ![](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)
+
 # Overview

 Filament is a physically based rendering (PBR) engine for Android. Filament offers a customizable
@@ -78,6 +83,7 @@ in table [standardProperties].
 **anisotropyDirection** | Local surface direction
 **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_)
+**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
 [Table [standardProperties]: Properties of the standard model]

@@ -95,6 +101,7 @@ The type and range of each property is described in table [standardPropertiesTyp
 **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
+**clearCoatNormal**     | float3   |  [0..1]                  | Linear RGB, encodes a direction vector in tangent space
 **emissive**            | float4   |  rgb=[0..1], a=[-n..n]   | Alpha is the exposure compensation
 [Table [standardPropertiesTypes]: Range and type of the standard model's properties]

@@ -139,14 +146,14 @@ Metals (conductors)

    Metal  |        sRGB         |  Hexadecimal |               Color
 ----------:|:-------------------:|:------------:|-------------------------------------------------------
-Silver     | 0.98, 0.98, 0.96    | #faf9f5     | <div style="background-color: #faf9f5; width: 60px">&nbsp;</div>
-Aluminum   | 0.96, 0.96, 0.96    | #f4f5f5     | <div style="background-color: #f4f5f5; width: 60px">&nbsp;</div>
-Titanium   | 0.81, 0.78, 0.76    | #cec8c2     | <div style="background-color: #cec8c2; width: 60px">&nbsp;</div>
-Iron       | 0.76, 0.74, 0.73    | #c0bdba     | <div style="background-color: #c0bdba; width: 60px">&nbsp;</div>
-Platinum   | 0.84, 0.82, 0.79    | #d6d1c8     | <div style="background-color: #d6d1c8; width: 60px">&nbsp;</div>
-Gold       | 1.00, 0.87, 0.62    | #fedc9d     | <div style="background-color: #fedc9d; width: 60px">&nbsp;</div>
-Brass      | 0.96, 0.89, 0.68    | #f4e4ad     | <div style="background-color: #f4e4ad; width: 60px">&nbsp;</div>
-Copper     | 0.98, 0.85, 0.72    | #fbd8b8     | <div style="background-color: #fbd8b8; width: 60px">&nbsp;</div>
+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
@@ -212,14 +219,19 @@ Table [commonMatReflectance] describes acceptable reflectance values for various
 (no real world material has a value under 2%).


-          Material         |      Reflectance      |   Property value
--------------------------:|:---------------------:|:------------------
-Glass                      | 3.5%                  | 0.46
-Water                      | 2%                    | 0.35
-Common liquids             | 2% to 4%              | 0.35 to 0.5
-Common gemstones           | 8% to 16%             | 0.70 to 1.0
-Other dielectric materials | 2% to 5%              | 0.35 to 0.56
-Default value              | 4%                    | 0.50
+          Material         |    Reflectance   |  Property value
+--------------------------:|:-----------------|:----------------
+Water                      | 2%               | 0.35
+Fabric                     | 4% to 5.6%       | 0.5 to 0.59
+Common liquids             | 2% to 4%         | 0.35 to 0.5
+Common gemstones           | 5% to 16%        | 0.56 to 1.0
+Plastics, glass            | 4% to 5%         | 0.5 to 0.56
+Other dielectric materials | 2% to 5%         | 0.35 to 0.56
+Eyes                       | 2.5%             | 0.39
+Skin                       | 2.8%             | 0.42
+Hair                       | 4.6%             | 0.54
+Teeth                      | 5.8%             | 0.6
+Default value              | 4%               | 0.5
 [Table [commonMatReflectance]: Reflectance of common materials]

 ### Clear coat
@@ -331,6 +343,17 @@ and with (right)](images/screenshot_normal_mapping.jpg)

 !!! Warning
    Using a normal map increases the runtime cost of the material model.
+    
+### 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

@@ -1234,6 +1257,7 @@ struct MaterialInputs {
    // not available when the shading model is subsurface or cloth
    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)

@@ -1516,4 +1540,4 @@ 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.

-<!-- Markdeep: --><style class="fallback">body{visibility:hidden;white-space:pre;font-family:monospace}</style><script src="js/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>
+<!-- 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>
--- a/Show More
+++ b/Show More