Update release notes for v1.4.0

* Add the ability to modify clip space coordinates in the vertex shader

This introduces MaterialVertexInputs.clipSpaceTransform, a mat4 that
is applied to gl_Position before exiting the vertex stage.

* Address code review comments

.github/workflows/presubmit.yml

@@ -0,0 +1,57 @@
+name: Presubmit
+
+on: [pull_request]
+
+jobs:
+  build-desktop:
+    name: build-desktop
+    runs-on: ${{ matrix.os }}
+
+    strategy:
+      matrix:
+        os: [macos-latest, ubuntu-latest]
+
+    steps:
+      - uses: actions/checkout@v1
+      - name: Run build script
+        run: |
+          WORKFLOW_OS=`echo \`uname\` | sed "s/Darwin/mac/" | tr [:upper:] [:lower:]`
+          cd build/$WORKFLOW_OS && ./build.sh ${TARGET}
+        env:
+          TARGET: presubmit
+
+  build-android:
+    name: build-android
+    runs-on: macos-latest
+
+    steps:
+      - uses: actions/checkout@v1
+      - name: Run build script
+        run: |
+          cd build/android && ./build.sh ${TARGET}
+        env:
+          TARGET: presubmit
+
+  build-ios:
+    name: build-iOS
+    runs-on: macos-latest
+
+    steps:
+      - uses: actions/checkout@v1
+      - name: Run build script
+        run: |
+          cd build/ios && ./build.sh ${TARGET}
+        env:
+          TARGET: presubmit
+
+  build-web:
+    name: build-web
+    runs-on: macos-latest
+
+    steps:
+      - uses: actions/checkout@v1
+      - name: Run build script
+        run: |
+          cd build/web && ./build.sh ${TARGET}
+        env:
+          TARGET: presubmit

.gitignore

@@ -3,7 +3,7 @@
 imgui.ini
 cmake-*
 ImportExecutables-*.cmake
-out
+/out*
 dist
 dist-*
 toolchains
@@ -11,3 +11,5 @@ filament/docs/html/**
 .vscode
 gltf_baker.ini
 *tmp*.png
+civetweb.txt
+/TAGS

CMakeLists.txt

@@ -50,19 +50,22 @@ if (WIN32)
         set(CRT_FLAGS_DEBUG "/MDd")
     endif()
 
-    # TODO: Figure out why pdb generation messes with incremental compilaton.
-    # IN RELEASE_WITH_DEBUG_INFO, generate debug info in .obj, no in pdb.
-    set(CMAKE_CXX_FLAGS_RELWITHDEBINFO "${CMAKE_CXX_FLAGS_RELWITHDEBINFO} ${CRT_FLAGS_RELEASE} /Z7")
-    set(CMAKE_C_FLAGS_RELWITHDEBINFO "${CMAKE_C_FLAGS_RELWITHDEBINFO} ${CRT_FLAGS_RELEASE} /Z7")
+    if (CMAKE_C_COMPILER_ID MATCHES "Clang")
+        # TODO: Figure out why pdb generation messes with incremental compilaton.
+        # IN RELEASE_WITH_DEBUG_INFO, generate debug info in .obj, no in pdb.
+        set(CMAKE_CXX_FLAGS_RELWITHDEBINFO "${CMAKE_CXX_FLAGS_RELWITHDEBINFO} ${CRT_FLAGS_RELEASE} /Z7")
+        set(CMAKE_C_FLAGS_RELWITHDEBINFO "${CMAKE_C_FLAGS_RELWITHDEBINFO} ${CRT_FLAGS_RELEASE} /Z7")
+
+        # In DEBUG, avoid generating a PDB file which seems to mess with incremental compilation.
+        # Instead generate debug info directly inside obj files.
+        set(CMAKE_CXX_FLAGS_DEBUG "${CMAKE_CXX_FLAGS_DEBUG} ${CRT_FLAGS_DEBUG} /Z7")
+        set(CMAKE_C_FLAGS_DEBUG "${CMAKE_C_FLAGS_DEBUG} ${CRT_FLAGS_DEBUG} /Z7")
+    endif()
 
     # In RELEASE, also generate PDBs.
     set(CMAKE_CXX_FLAGS_RELEASE "${CMAKE_CXX_FLAGS_RELEASE} ${CRT_FLAGS_RELEASE} /Zi")
     set(CMAKE_C_FLAGS_RELEASE "${CMAKE_C_FLAGS_RELEASE} ${CRT_FLAGS_RELEASE} /Zi")
 
-    # In DEBUG, avoid generating a PDB file which seems to mess with incremental compilation.
-    # Instead generate debug info directly inside obj files.
-    set(CMAKE_CXX_FLAGS_DEBUG "${CMAKE_CXX_FLAGS_DEBUG} ${CRT_FLAGS_DEBUG} /Z7")
-    set(CMAKE_C_FLAGS_DEBUG "${CMAKE_C_FLAGS_DEBUG} ${CRT_FLAGS_DEBUG} /Z7")
 endif()
 
 # ==================================================================================================
@@ -71,7 +74,7 @@ endif()
 # ==================================================================================================
 
 find_package(embree 3.0 QUIET PATHS /usr/lib64/cmake)
-if (embree_FOUND AND NOT ANDROID)
+if (embree_FOUND AND NOT ANDROID AND NOT IOS)
     message("Found embree in ${embree_DIR}")
     set(MKLDNN_THREADING "TBB")
     include(third_party/OpenImageDenoise/cmake/resource.cmake)
@@ -113,7 +116,7 @@ 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()
+elseif (NOT MSVC)
     message(FATAL_ERROR "Detected C compiler ${CMAKE_C_COMPILER_ID} is unsupported")
 endif()
 
@@ -121,13 +124,17 @@ 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()
+elseif (NOT MSVC)
     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)
+if ("${CMAKE_CXX_COMPILER_ID}" STREQUAL "Clang")
+    if ("${CMAKE_CXX_SIMULATE_ID}" STREQUAL "MSVC")
+        set(CLANG_CL true)
+    endif()
+elseif (MSVC)
+    set(MSVC_NATIVE true)
 endif()
 
 # ==================================================================================================
@@ -152,7 +159,12 @@ 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 (MSVC_NATIVE)
+    set(CXX_STANDARD "/std:c++latest")
+    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} ${CXX_STANDARD} /W0 /Zc:__cplusplus")
+else()
+    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} ${CXX_STANDARD} -fstrict-aliasing -Wno-unknown-pragmas -Wno-unused-function")
+endif()
 
 if (USE_EXTERNAL_GLES3)
     set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -DUSE_EXTERNAL_GLES3")
@@ -173,7 +185,7 @@ if (CYGWIN)
     set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fno-exceptions -fno-rtti")
 endif()
 
-if (CLANG_CL)
+if (CLANG_CL OR MSVC)
     # 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")
@@ -189,7 +201,7 @@ endif()
 # ==================================================================================================
 # Release compiler flags
 # ==================================================================================================
-if (NOT CLANG_CL)
+if (NOT CLANG_CL AND NOT MSVC)
     set(CMAKE_CXX_FLAGS_RELEASE "${CMAKE_CXX_FLAGS_RELEASE} -fomit-frame-pointer -ffunction-sections -fdata-sections")
 endif()
 
@@ -207,7 +219,7 @@ endif()
 #  -fsanitize=address causes a crash with assimp, which we can't explain for now
 #set(EXTRA_SANITIZE_OPTIONS "-fsanitize=undefined -fsanitize=address")
 # clang-cl.exe on Windows does not support -fstack-protector.
-if (NOT CLANG_CL)
+if (NOT CLANG_CL AND NOT MSVC)
     set(CMAKE_CXX_FLAGS_DEBUG "${CMAKE_CXX_FLAGS_DEBUG} -fstack-protector")
 endif()
 set(CMAKE_CXX_FLAGS_DEBUG "${CMAKE_CXX_FLAGS_DEBUG} ${EXTRA_SANITIZE_OPTIONS}")
@@ -324,18 +336,23 @@ endif()
 # ==================================================================================================
 # Functions
 # ==================================================================================================
+## The MSVC compiler has a limitation on literal string length which is reached when all the
+## licenses are concatenated together into a large string... so split them into multiple strings.
 function(list_licenses OUTPUT MODULES)
-    file(WRITE ${OUTPUT} "R\"FILAMENT__(\n")
+    set(STR_OPENER "R\"FILAMENT__(")
+    set(STR_CLOSER ")FILAMENT__\"")
+    set(CONTENT)
     set(_MODULES ${MODULES} ${ARGN})
     foreach(module ${_MODULES})
         set(license_path "../../third_party/${module}/LICENSE")
         get_filename_component(fullname "${license_path}" ABSOLUTE)
-        file(APPEND ${OUTPUT} "License and copyrights for ${module}:\n\n")
-        file(READ ${license_path} license)
-        file(APPEND ${OUTPUT} ${license})
-        file(APPEND ${OUTPUT} "\n\n")
+        string(APPEND CONTENT "${STR_OPENER}License and copyrights for ${module}:\n${STR_CLOSER},\n")
+        file(READ ${license_path} license_long)
+        string(REPLACE "\n" "${STR_CLOSER},\n${STR_OPENER}" license ${license_long})
+        string(APPEND CONTENT ${STR_OPENER}${license}\n${STR_CLOSER},)
+        string(APPEND CONTENT "\n\n")
     endforeach()
-    file(APPEND ${OUTPUT} ")FILAMENT__\"\n")
+    configure_file(${FILAMENT}/build/licenses.inc.in ${OUTPUT})
 endfunction(list_licenses)
 
 # ==================================================================================================
@@ -423,6 +440,7 @@ add_subdirectory(${EXTERNAL}/meshoptimizer)
 add_subdirectory(${EXTERNAL}/cgltf/tnt)
 add_subdirectory(${EXTERNAL}/xatlas/tnt)
 add_subdirectory(${EXTERNAL}/stb/tnt)
+add_subdirectory(${EXTERNAL}/getopt)
 
 if (FILAMENT_BUILD_FILAMAT)
     # spirv-tools must come before filamat, as filamat relies on the presence of the
@@ -459,14 +477,15 @@ if (NOT ANDROID AND NOT WEBGL AND NOT IOS)
     add_subdirectory(${LIBRARIES}/bluegl)
     add_subdirectory(${LIBRARIES}/filagui)
     add_subdirectory(${LIBRARIES}/imageio)
+    add_subdirectory(${LIBRARIES}/matdbg)
 
     add_subdirectory(${FILAMENT}/java/filamat)
     add_subdirectory(${FILAMENT}/java/filament)
     add_subdirectory(${FILAMENT}/samples)
 
     add_subdirectory(${EXTERNAL}/astcenc/tnt)
+    add_subdirectory(${EXTERNAL}/civetweb/tnt)
     add_subdirectory(${EXTERNAL}/etc2comp)
-    add_subdirectory(${EXTERNAL}/getopt)
     add_subdirectory(${EXTERNAL}/imgui/tnt)
     add_subdirectory(${EXTERNAL}/libassimp/tnt)
     add_subdirectory(${EXTERNAL}/libpng/tnt)
@@ -474,6 +493,7 @@ if (NOT ANDROID AND NOT WEBGL AND NOT IOS)
     add_subdirectory(${EXTERNAL}/libz/tnt)
     add_subdirectory(${EXTERNAL}/skylight/tnt)
     add_subdirectory(${EXTERNAL}/tinyexr/tnt)
+
     add_subdirectory(${TOOLS}/cmgen)
     add_subdirectory(${TOOLS}/filamesh)
     add_subdirectory(${TOOLS}/glslminifier)
@@ -485,10 +505,11 @@ if (NOT ANDROID AND NOT WEBGL AND NOT IOS)
     add_subdirectory(${TOOLS}/roughness-prefilter)
     add_subdirectory(${TOOLS}/skygen)
     add_subdirectory(${TOOLS}/specular-color)
-endif()
 
-if (DENOISE_LIBRARY)
-    add_subdirectory(${EXTERNAL}/OpenImageDenoise/tnt)
+    if (DENOISE_LIBRARY)
+        add_subdirectory(${EXTERNAL}/OpenImageDenoise/tnt)
+    endif()
+
 endif()
 
 # Generate exported executables for cross-compiled builds (Android, WebGL, and iOS)

README.md

@@ -142,6 +142,7 @@ and tools.
   - `ibl`:                 IBL generation tools
   - `image`:               Image filtering and simple transforms
   - `imageio`:             Image file reading / writing, only intended for internal use
+  - `matdbg`:              DebugServer for inspecting shaders at run-time (debug builds only)
   - `math`:                Math library
   - `rays`:                Simple path tracer used for baking ambient occlusion, etc.
   - `utils`:               Utility library (threads, memory, data structures, etc.)
@@ -189,9 +190,9 @@ Building the `rays` library (used for light baking) is optional and requires the
 
 To build Filament for Android you must also install the following:
 
-- Android Studio 3.3
+- Android Studio 3.5
 - Android SDK
-- Android NDK 19 or higher
+- Android NDK "side-by-side" 20 or higher
 
 ### Environment variables
 

RELEASE_NOTES.md

@@ -3,6 +3,35 @@
 This file contains one line summaries of commits that are worthy of mentioning in release notes.
 A new header is inserted each time a *tag* is created.
 
+## v1.4.0
+
+- API Breakage: Simplified public-facing Fence API.
+- Minimum API level on Android is now API 19 instead of API 21.
+- Filament can now be built with msvc 2019.
+- Added the ability to modify clip space coordinates in the vertex shader.
+- Added missing API documentation.
+- Improved existing API documentation.
+- Added `Camera::setExposure(float)` to directly control the camera's exposure.
+- Backface culling can now be toggled on material instances.
+- Face direction is now reversed when transforms have negative scale.
+- Dielectrics now behave properly under a white furnace (energy preserving and conserving).
+- Clear coat roughness now remains in the 0..1 (previously remapped to the 0..0.6 range).
+- gltfio: Fixed several limitations with ubershader mode.
+- gltfio: Fixed a transforms issue with non-uniform scale.
+- webgl: Fixed an issue with JPEG textures.
+- Windows: Fix link error in debug builds.
+- matdbg: Web server must now be enabled with an environment variable.
+- matdbg: Added support for editing GLSL and MSL code.
+
+## v1.3.2
+
+- Added optional web server for real-time inspection of shader code.
+- Added basic #include support in material files.
+- Fixed potential Metal memory leak.
+- Fixed intermittent memory overflow in wasm builds.
+- Fix bad normal mapping with skinning.
+- Java clients can now call getNativeObject().
+
 ## v1.3.1
 
 - Unified Filament Sceneform and npm releases.

android/build/filament-tasks.gradle

@@ -116,6 +116,7 @@ class MaterialCompiler extends DefaultTask {
 // This task handles incremental builds
 class IblGenerator extends DefaultTask {
     File cmgenPath
+    String cmgenArgs = null;
 
     @SuppressWarnings("GroovyUnusedDeclaration")
     @InputFile
@@ -155,9 +156,13 @@ class IblGenerator extends DefaultTask {
 
             project.exec {
                 standardOutput out
+                if (!cmgenArgs) {
+                    cmgenArgs = '--format=rgb32f --extract-blur=0.08 --extract=' + outputDir.absolutePath
+                }
+                cmgenArgs = cmgenArgs + " " + file
                 errorOutput err
                 executable "${cmgenPath}"
-                args('--format=rgb32f', '--extract-blur=0.08', "--extract=${outputDir.absolutePath}", file)
+                args(cmgenArgs.split())
             }
         }
 

android/filamat-android/.gitignore

@@ -9,3 +9,4 @@
 /build
 /captures
 .externalNativeBuild
+/.cxx

android/filamat-android/build.gradle

@@ -13,7 +13,7 @@ buildscript {
         jcenter()
     }
     dependencies {
-        classpath 'com.android.tools.build:gradle:3.4.1'
+        classpath 'com.android.tools.build:gradle:3.5.0'
     }
 }
 
@@ -25,7 +25,7 @@ allprojects {
 }
 
 group = "com.google.android.filament"
-version = "0.1"
+version = "1.3"
 
 apply plugin: 'com.android.library'
 
@@ -35,10 +35,10 @@ if (project.hasProperty("filament_dist_dir")) {
 }
 
 android {
-    compileSdkVersion 28
+    compileSdkVersion 29
     defaultConfig {
         minSdkVersion 14
-        targetSdkVersion 28
+        targetSdkVersion 29
         versionCode 1
         versionName "1.0"
 
@@ -47,7 +47,7 @@ android {
         externalNativeBuild {
             cmake {
                 arguments.add("-DANDROID_PIE=ON")
-                arguments.add("-DANDROID_PLATFORM=android-21")
+                arguments.add("-DANDROID_PLATFORM=android-19")
                 arguments.add("-DANDROID_STL=c++_static")
                 arguments.add("-DFILAMENT_DIST_DIR=${filament_path}".toString())
                 cppFlags.add("-std=c++14")

android/filamat-android/gradle/wrapper/gradle-wrapper.properties

@@ -1,5 +1,5 @@
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-5.4-bin.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-5.4.1-all.zip
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists

android/filamat-android/src/main/java/com/google/android/filament/filamat/MaterialBuilder.java

@@ -99,14 +99,15 @@ public class MaterialBuilder {
         UV1,                    // texture coordinates (float2)
         BONE_INDICES,           // indices of 4 bones (uvec4)
         BONE_WEIGHTS,           // weights of the 4 bones (normalized float4)
-        CUSTOM0,
-        CUSTOM1,
-        CUSTOM2,
-        CUSTOM3,
-        CUSTOM4,
-        CUSTOM5,
-        CUSTOM6,
-        CUSTOM7
+        UNUSED,                 // reserved for future use
+        CUSTOM0,                // custom or MORPH_POSITION_0
+        CUSTOM1,                // custom or MORPH_POSITION_1
+        CUSTOM2,                // custom or MORPH_POSITION_2
+        CUSTOM3,                // custom or MORPH_POSITION_3
+        CUSTOM4,                // custom or MORPH_TANGENTS_0
+        CUSTOM5,                // custom or MORPH_TANGENTS_1
+        CUSTOM6,                // custom or MORPH_TANGENTS_2
+        CUSTOM7                 // custom or MORPH_TANGENTS_3
     }
 
     public enum BlendingMode {

android/filament-android/.gitignore

@@ -9,3 +9,4 @@
 /build
 /captures
 .externalNativeBuild
+/.cxx

android/filament-android/.idea/codeStyles/Project.xml

@@ -1,29 +1,113 @@
 <component name="ProjectCodeStyleConfiguration">
   <code_scheme name="Project" version="173">
-    <Objective-C-extensions>
-      <file>
-        <option name="com.jetbrains.cidr.lang.util.OCDeclarationKind" value="Import" />
-        <option name="com.jetbrains.cidr.lang.util.OCDeclarationKind" value="Macro" />
-        <option name="com.jetbrains.cidr.lang.util.OCDeclarationKind" value="Typedef" />
-        <option name="com.jetbrains.cidr.lang.util.OCDeclarationKind" value="Enum" />
-        <option name="com.jetbrains.cidr.lang.util.OCDeclarationKind" value="Constant" />
-        <option name="com.jetbrains.cidr.lang.util.OCDeclarationKind" value="Global" />
-        <option name="com.jetbrains.cidr.lang.util.OCDeclarationKind" value="Struct" />
-        <option name="com.jetbrains.cidr.lang.util.OCDeclarationKind" value="FunctionPredecl" />
-        <option name="com.jetbrains.cidr.lang.util.OCDeclarationKind" value="Function" />
-      </file>
-      <class>
-        <option name="com.jetbrains.cidr.lang.util.OCDeclarationKind" value="Property" />
-        <option name="com.jetbrains.cidr.lang.util.OCDeclarationKind" value="Synthesize" />
-        <option name="com.jetbrains.cidr.lang.util.OCDeclarationKind" value="InitMethod" />
-        <option name="com.jetbrains.cidr.lang.util.OCDeclarationKind" value="StaticMethod" />
-        <option name="com.jetbrains.cidr.lang.util.OCDeclarationKind" value="InstanceMethod" />
-        <option name="com.jetbrains.cidr.lang.util.OCDeclarationKind" value="DeallocMethod" />
-      </class>
-      <extensions>
-        <pair source="cpp" header="h" fileNamingConvention="NONE" />
-        <pair source="c" header="h" fileNamingConvention="NONE" />
-      </extensions>
-    </Objective-C-extensions>
+    <codeStyleSettings language="XML">
+      <arrangement>
+        <rules>
+          <section>
+            <rule>
+              <match>
+                <AND>
+                  <NAME>xmlns:android</NAME>
+                  <XML_ATTRIBUTE />
+                  <XML_NAMESPACE>^$</XML_NAMESPACE>
+                </AND>
+              </match>
+            </rule>
+          </section>
+          <section>
+            <rule>
+              <match>
+                <AND>
+                  <NAME>xmlns:.*</NAME>
+                  <XML_ATTRIBUTE />
+                  <XML_NAMESPACE>^$</XML_NAMESPACE>
+                </AND>
+              </match>
+              <order>BY_NAME</order>
+            </rule>
+          </section>
+          <section>
+            <rule>
+              <match>
+                <AND>
+                  <NAME>.*:id</NAME>
+                  <XML_ATTRIBUTE />
+                  <XML_NAMESPACE>http://schemas.android.com/apk/res/android</XML_NAMESPACE>
+                </AND>
+              </match>
+            </rule>
+          </section>
+          <section>
+            <rule>
+              <match>
+                <AND>
+                  <NAME>.*:name</NAME>
+                  <XML_ATTRIBUTE />
+                  <XML_NAMESPACE>http://schemas.android.com/apk/res/android</XML_NAMESPACE>
+                </AND>
+              </match>
+            </rule>
+          </section>
+          <section>
+            <rule>
+              <match>
+                <AND>
+                  <NAME>name</NAME>
+                  <XML_ATTRIBUTE />
+                  <XML_NAMESPACE>^$</XML_NAMESPACE>
+                </AND>
+              </match>
+            </rule>
+          </section>
+          <section>
+            <rule>
+              <match>
+                <AND>
+                  <NAME>style</NAME>
+                  <XML_ATTRIBUTE />
+                  <XML_NAMESPACE>^$</XML_NAMESPACE>
+                </AND>
+              </match>
+            </rule>
+          </section>
+          <section>
+            <rule>
+              <match>
+                <AND>
+                  <NAME>.*</NAME>
+                  <XML_ATTRIBUTE />
+                  <XML_NAMESPACE>^$</XML_NAMESPACE>
+                </AND>
+              </match>
+              <order>BY_NAME</order>
+            </rule>
+          </section>
+          <section>
+            <rule>
+              <match>
+                <AND>
+                  <NAME>.*</NAME>
+                  <XML_ATTRIBUTE />
+                  <XML_NAMESPACE>http://schemas.android.com/apk/res/android</XML_NAMESPACE>
+                </AND>
+              </match>
+              <order>ANDROID_ATTRIBUTE_ORDER</order>
+            </rule>
+          </section>
+          <section>
+            <rule>
+              <match>
+                <AND>
+                  <NAME>.*</NAME>
+                  <XML_ATTRIBUTE />
+                  <XML_NAMESPACE>.*</XML_NAMESPACE>
+                </AND>
+              </match>
+              <order>BY_NAME</order>
+            </rule>
+          </section>
+        </rules>
+      </arrangement>
+    </codeStyleSettings>
   </code_scheme>
 </component>

android/filament-android/build.gradle

@@ -13,7 +13,7 @@ buildscript {
         jcenter()
     }
     dependencies {
-        classpath 'com.android.tools.build:gradle:3.4.1'
+        classpath 'com.android.tools.build:gradle:3.5.0'
     }
 }
 
@@ -25,7 +25,7 @@ allprojects {
 }
 
 group = "com.google.android.filament"
-version = "0.1"
+version = "1.3"
 
 apply plugin: 'com.android.library'
 
@@ -35,13 +35,13 @@ if (project.hasProperty("filament_dist_dir")) {
 }
 
 android {
-    compileSdkVersion 28
+    compileSdkVersion 29
     defaultConfig {
-        // Our minSdkVersion is actually 21, we lie and say 14 here so apps don't have
+        // Our minSdkVersion is actually 19, we lie and say 14 here so apps don't have
         // to increase their minSdkVersion unnecessarily. It is however up to them to
-        // ensure they do not initialize Filament on API levels < 21.
+        // ensure they do not initialize Filament on API levels < 19.
         minSdkVersion 14
-        targetSdkVersion 28
+        targetSdkVersion 29
         versionCode 1
         versionName "1.0"
 
@@ -50,7 +50,7 @@ android {
         externalNativeBuild {
             cmake {
                 arguments.add("-DANDROID_PIE=ON")
-                arguments.add("-DANDROID_PLATFORM=android-21")
+                arguments.add("-DANDROID_PLATFORM=android-19")
                 arguments.add("-DANDROID_STL=c++_static")
                 arguments.add("-DFILAMENT_DIST_DIR=${filament_path}".toString())
                 cppFlags.add("-std=c++14")

android/filament-android/gradle/wrapper/gradle-wrapper.properties

@@ -1,5 +1,5 @@
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-5.4-bin.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-5.4.1-all.zip
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists

android/filament-android/src/main/cpp/Engine.cpp

@@ -154,9 +154,9 @@ Java_com_google_android_filament_Engine_nDestroyScene(JNIEnv*, jclass,
 
 extern "C" JNIEXPORT jlong JNICALL
 Java_com_google_android_filament_Engine_nCreateFence(JNIEnv*, jclass,
-        jlong nativeEngine, jint fenceType) {
+        jlong nativeEngine) {
     Engine* engine = (Engine*) nativeEngine;
-    return (jlong) engine->createFence((Fence::Type) fenceType);
+    return (jlong) engine->createFence();
 }
 
 extern "C" JNIEXPORT void JNICALL

android/filament-android/src/main/cpp/MaterialInstance.cpp

@@ -316,3 +316,11 @@ Java_com_google_android_filament_MaterialInstance_nSetDoubleSided(JNIEnv*,
     MaterialInstance* instance = (MaterialInstance*) nativeMaterialInstance;
     instance->setDoubleSided(doubleSided);
 }
+
+extern "C"
+JNIEXPORT void JNICALL
+Java_com_google_android_filament_MaterialInstance_nSetCullingMode(JNIEnv*,
+        jclass, jlong nativeMaterialInstance, jlong cullingMode) {
+    MaterialInstance* instance = (MaterialInstance*) nativeMaterialInstance;
+    instance->setCullingMode((MaterialInstance::CullingMode) cullingMode);
+}

android/filament-android/src/main/cpp/Texture.cpp

@@ -177,7 +177,7 @@ Java_com_google_android_filament_Texture_nSetImage(JNIEnv* env, jclass, jlong na
             (Texture::Type) type, (size_t) stride, (size_t) alignment);
 
     AutoBuffer nioBuffer(env, storage, 0);
-    if (sizeInBytes > (remaining << nioBuffer.getShift())) {
+    if (sizeInBytes > (size_t(remaining) << nioBuffer.getShift())) {
         // BufferOverflowException
         return -1;
     }
@@ -199,8 +199,7 @@ extern "C" JNIEXPORT jint JNICALL
 Java_com_google_android_filament_Texture_nSetImageCompressed(JNIEnv *env, jclass,
         jlong nativeTexture, jlong nativeEngine, jint level, jint xoffset, jint yoffset,
         jint width, jint height, jobject storage,  jint remaining,
-        jint left, jint bottom, jint type, jint alignment,
-        jint compressedSizeInBytes, jint compressedFormat,
+        jint, jint, jint, jint, jint compressedSizeInBytes, jint compressedFormat,
         jobject handler, jobject runnable) {
     Texture *texture = (Texture *) nativeTexture;
     Engine *engine = (Engine *) nativeEngine;
@@ -208,7 +207,7 @@ Java_com_google_android_filament_Texture_nSetImageCompressed(JNIEnv *env, jclass
     size_t sizeInBytes = (size_t) compressedSizeInBytes;
 
     AutoBuffer nioBuffer(env, storage, 0);
-    if (sizeInBytes > (remaining << nioBuffer.getShift())) {
+    if (sizeInBytes > (size_t(remaining) << nioBuffer.getShift())) {
         // BufferOverflowException
         return -1;
     }
@@ -235,7 +234,7 @@ Java_com_google_android_filament_Texture_nSetImageCubemap(JNIEnv *env, jclass,
     Texture *texture = (Texture *) nativeTexture;
     Engine *engine = (Engine *) nativeEngine;
 
-    jint *faceOffsetsInBytes = env->GetIntArrayElements(faceOffsetsInBytes_, NULL);
+    jint *faceOffsetsInBytes = env->GetIntArrayElements(faceOffsetsInBytes_, nullptr);
     Texture::FaceOffsets faceOffsets;
     std::copy_n(faceOffsetsInBytes, 6, faceOffsets.offsets);
     env->ReleaseIntArrayElements(faceOffsetsInBytes_, faceOffsetsInBytes, JNI_ABORT);
@@ -244,7 +243,7 @@ Java_com_google_android_filament_Texture_nSetImageCubemap(JNIEnv *env, jclass,
             (Texture::Type) type, (size_t) stride, (size_t) alignment);
 
     AutoBuffer nioBuffer(env, storage, 0);
-    if (sizeInBytes > (remaining << nioBuffer.getShift())) {
+    if (sizeInBytes > (size_t(remaining) << nioBuffer.getShift())) {
         // BufferOverflowException
         return -1;
     }
@@ -271,7 +270,7 @@ Java_com_google_android_filament_Texture_nSetImageCubemapCompressed(JNIEnv *env,
     Texture *texture = (Texture *) nativeTexture;
     Engine *engine = (Engine *) nativeEngine;
 
-    jint *faceOffsetsInBytes = env->GetIntArrayElements(faceOffsetsInBytes_, NULL);
+    jint *faceOffsetsInBytes = env->GetIntArrayElements(faceOffsetsInBytes_, nullptr);
     Texture::FaceOffsets faceOffsets;
     std::copy_n(faceOffsetsInBytes, 6, faceOffsets.offsets);
     env->ReleaseIntArrayElements(faceOffsetsInBytes_, faceOffsetsInBytes, JNI_ABORT);
@@ -279,7 +278,7 @@ Java_com_google_android_filament_Texture_nSetImageCubemapCompressed(JNIEnv *env,
     size_t sizeInBytes = 6 * (size_t) compressedSizeInBytes;
 
     AutoBuffer nioBuffer(env, storage, 0);
-    if (sizeInBytes > (remaining << nioBuffer.getShift())) {
+    if (sizeInBytes > (size_t(remaining) << nioBuffer.getShift())) {
         // BufferOverflowException
         return -1;
     }
@@ -340,28 +339,29 @@ Java_com_google_android_filament_Texture_nGeneratePrefilterMipmap(JNIEnv *env, j
     Texture *texture = (Texture *) nativeTexture;
     Engine *engine = (Engine *) nativeEngine;
 
-    jint *faceOffsetsInBytes = env->GetIntArrayElements(faceOffsetsInBytes_, NULL);
+    jint *faceOffsetsInBytes = env->GetIntArrayElements(faceOffsetsInBytes_, nullptr);
     Texture::FaceOffsets faceOffsets;
     std::copy_n(faceOffsetsInBytes, 6, faceOffsets.offsets);
     env->ReleaseIntArrayElements(faceOffsetsInBytes_, faceOffsetsInBytes, JNI_ABORT);
 
     stride = stride ? stride : width;
     size_t sizeInBytes = 6 *
-                         Texture::computeTextureDataSize((Texture::Format) format, (Texture::Type) type,
-                                 (size_t) stride, (size_t) height, (size_t) alignment);
+            Texture::computeTextureDataSize((Texture::Format) format, (Texture::Type) type,
+                                            (size_t) stride, (size_t) height, (size_t) alignment);
 
     AutoBuffer nioBuffer(env, storage, 0);
-    if (sizeInBytes > (remaining << nioBuffer.getShift())) {
+    if (sizeInBytes > (size_t(remaining) << nioBuffer.getShift())) {
         // BufferOverflowException
         return -1;
     }
 
-    void *buffer = nioBuffer.getData();
-    auto *callback = JniBufferCallback::make(engine, env, handler, runnable, std::move(nioBuffer));
+    void* buffer = nioBuffer.getData();
+    auto* callback = JniBufferCallback::make(engine, env, handler, runnable, std::move(nioBuffer));
 
     Texture::PixelBufferDescriptor desc(buffer, sizeInBytes, (backend::PixelDataFormat) format,
-            (backend::PixelDataType) type, (uint8_t) alignment, (uint32_t)0, (uint32_t)0,
-            (uint32_t) stride, &JniBufferCallback::invoke, callback);
+            (backend::PixelDataType) type, (uint8_t) alignment,
+            (uint32_t) left, (uint32_t) top, (uint32_t) stride,
+            &JniBufferCallback::invoke, callback);
 
     Texture::PrefilterOptions options;
     options.sampleCount = sampleCount;

android/filament-android/src/main/java/com/google/android/filament/AndroidPlatform.java

@@ -19,8 +19,10 @@ package com.google.android.filament;
 import android.graphics.SurfaceTexture;
 import android.opengl.EGL14;
 import android.opengl.EGLContext;
+import android.os.Build;
 import android.util.Log;
 import android.view.Surface;
+import java.lang.reflect.Method;
 
 final class AndroidPlatform extends Platform {
     private static final String LOG_TAG = "Filament";
@@ -59,6 +61,20 @@ final class AndroidPlatform extends Platform {
 
     @Override
     long getSharedContextNativeHandle(Object sharedContext) {
-        return ((EGLContext) sharedContext).getNativeHandle();
+        if (Build.VERSION.SDK_INT >= 21) {
+            return AndroidPlatform21.getSharedContextNativeHandle(sharedContext);
+        } else {
+            try {
+                //noinspection JavaReflectionMemberAccess
+                Method method = EGLContext.class.getDeclaredMethod("getHandle");
+                Integer handle = (Integer) method.invoke(sharedContext);
+                //noinspection ConstantConditions
+                return handle.longValue();
+            } catch (Exception e) {
+                Log.d(LOG_TAG, "Could not access shared context's native handle", e);
+            }
+            // Should not happen
+            return 0;
+        }
     }
 }

android/filament-android/src/main/java/com/google/android/filament/AndroidPlatform21.java

@@ -0,0 +1,25 @@
+/*
+ * Copyright (C) 2019 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.
+ */
+
+package com.google.android.filament;
+
+import android.opengl.EGLContext;
+
+final class AndroidPlatform21 {
+    static long getSharedContextNativeHandle(Object sharedContext) {
+        return ((EGLContext) sharedContext).getNativeHandle();
+    }
+}

android/filament-android/src/main/java/com/google/android/filament/Asserts.java

@@ -16,7 +16,6 @@
 
 package com.google.android.filament;
 
-import android.support.annotation.IntRange;
 import android.support.annotation.NonNull;
 import android.support.annotation.Nullable;
 import android.support.annotation.Size;

android/filament-android/src/main/java/com/google/android/filament/Camera.java

@@ -157,26 +157,30 @@ public class Camera {
      * @param projection    type of projection to use
      *
      * @param left          distance in world units from the camera to the left plane,
-     *                      at the near plane. Precondition: left != right.
+     *                      at the near plane. Precondition: <code>left</code> != <code>right</code>
      *
      * @param right         distance in world units from the camera to the right plane,
-     *                      at the near plane. Precondition: left != right.
+     *                      at the near plane. Precondition: <code>left</code> != <code>right</code>
      *
      * @param bottom        distance in world units from the camera to the bottom plane,
-     *                      at the near plane. Precondition: bottom != top.
+     *                      at the near plane. Precondition: <code>bottom</code> != <code>top</code>
      *
      * @param top           distance in world units from the camera to the top plane,
-     *                      at the near plane. Precondition: left != right.
+     *                      at the near plane. Precondition: <code>bottom</code> != <code>top</code>
      *
      * @param near          distance in world units from the camera to the near plane.
-     *                      The near plane's position in view space is z = -near.
-     *                      Precondition: near > 0 for {@link Projection#PERSPECTIVE} or
-     *                                    near != far for {@link Projection#ORTHO}.
+     *                      The near plane's position in view space is z = -<code>near</code>.
+     *                      Precondition:
+     *                      <code>near</code> > 0 for {@link Projection#PERSPECTIVE} or
+     *                      <code>near</code> != <code>far</code> for {@link Projection#ORTHO}.
      *
      * @param far           distance in world units from the camera to the far plane.
-     *                      The far plane's position in view space is z = -far.
-     *                      Precondition: far > near for {@link Projection#PERSPECTIVE} or
-     *                                    far != near for {@link Projection#ORTHO}.
+     *                      The far plane's position in view space is z = -<code>far</code>.
+     *                      Precondition:
+     *                      <code>far</code> > <code>near</code>
+     *                              for {@link Projection#PERSPECTIVE} or
+     *                      <code>far</code> != <code>near</code>
+     *                              for {@link Projection#ORTHO}.
      *
      * <p>
      * These parameters are silently modified to meet the preconditions above.
@@ -189,12 +193,32 @@ public class Camera {
     }
 
     /**
+     * Sets the projection matrix from the field-of-view.
      *
-     * @param fovInDegrees
-     * @param aspect
-     * @param near
-     * @param far
-     * @param direction
+     * @param fovInDegrees  field-of-view in degrees from the camera center axis.
+     *                      0 < <code>fovInDegrees</code> < 180
+     *
+     * @param aspect        aspect ratio width/height. <code>aspect</code> > 0
+     *
+     * @param near          distance in world units from the camera to the near plane.
+     *                      The near plane's position in view space is z = -<code>near</code>.
+     *                      Precondition:
+     *                      <code>near</code> > 0 for {@link Projection#PERSPECTIVE} or
+     *                      <code>near</code> != <code>far</code> for {@link Projection#ORTHO}.
+     *
+     * @param far           distance in world units from the camera to the far plane.
+     *                      The far plane's position in view space is z = -<code>far</code>.
+     *                      Precondition:
+     *                      <code>far</code> > <code>near</code>
+     *                              for {@link Projection#PERSPECTIVE} or
+     *                      <code>far</code> != <code>near</code>
+     *                              for {@link Projection#ORTHO}.
+     *
+     * @param direction    direction of the field-of-view parameter.
+     * <p>
+     * These parameters are silently modified to meet the preconditions above.
+     *
+     * @see Fov
      */
     public void setProjection(double fovInDegrees, double aspect, double near, double far,
             @NonNull Fov direction) {
@@ -202,47 +226,86 @@ public class Camera {
     }
 
     /**
+     * Sets the projection matrix from the focal length
+     *
+     * @param focalLength   lense's focal length in millimeters. <code>focalLength</code> > 0
+     *
+     * @param near          distance in world units from the camera to the near plane.
+     *                      The near plane's position in view space is z = -<code>near</code>.
+     *                      Precondition:
+     *                      <code>near</code> > 0 for {@link Projection#PERSPECTIVE} or
+     *                      <code>near</code> != <code>far</code> for {@link Projection#ORTHO}.
+     *
+     * @param far           distance in world units from the camera to the far plane.
+     *                      The far plane's position in view space is z = -<code>far</code>.
+     *                      Precondition:
+     *                      <code>far</code> > <code>near</code>
+     *                              for {@link Projection#PERSPECTIVE} or
+     *                      <code>far</code> != <code>near</code>
+     *                              for {@link Projection#ORTHO}.
      *
-     * @param focalLength
-     * @param near
-     * @param far
      */
     public void setLensProjection(double focalLength, double near, double far) {
         nSetLensProjection(getNativeObject(), focalLength, near, far);
     }
 
     /**
+     * Sets the projection matrix.
      *
-     * @param inMatrix
-     * @param near
-     * @param far
+     * @param inMatrix      custom projection matrix.
+     *
+     * @param near          distance in world units from the camera to the near plane.
+     *                      The near plane's position in view space is z = -<code>near</code>.
+     *                      Precondition:
+     *                      <code>near</code> > 0 for {@link Projection#PERSPECTIVE} or
+     *                      <code>near</code> != <code>far</code> for {@link Projection#ORTHO}.
+     *
+     * @param far           distance in world units from the camera to the far plane.
+     *                      The far plane's position in view space is z = -<code>far</code>.
+     *                      Precondition:
+     *                      <code>far</code> > <code>near</code>
+     *                              for {@link Projection#PERSPECTIVE} or
+     *                      <code>far</code> != <code>near</code>
+     *                              for {@link Projection#ORTHO}.
      */
-    public void setCustomProjection(@NonNull @Size(min = 16) double inMatrix[],
+    public void setCustomProjection(@NonNull @Size(min = 16) double[] inMatrix,
             double near, double far) {
         Asserts.assertMat4dIn(inMatrix);
         nSetCustomProjection(getNativeObject(), inMatrix, near, far);
     }
 
     /**
+     * Sets the camera's view matrix.
+     * <p>
+     * Helper method to set the camera's entity transform component.
+     * Remember that the Camera "looks" towards its -z axis.
+     * <p>
+     * This has the same effect as calling:
      *
-     * @param in
+     * <pre>
+     *  engine.getTransformManager().setTransform(
+     *          engine.getTransformManager().getInstance(camera->getEntity()), viewMatrix);
+     * </pre>
+     *
+     * @param viewMatrix The camera position and orientation provided as a <b>rigid transform</b> matrix.
      */
-    public void setModelMatrix(@NonNull @Size(min = 16) float in[]) {
-        Asserts.assertMat4fIn(in);
-        nSetModelMatrix(getNativeObject(), in);
+    public void setModelMatrix(@NonNull @Size(min = 16) float[] viewMatrix) {
+        Asserts.assertMat4fIn(viewMatrix);
+        nSetModelMatrix(getNativeObject(), viewMatrix);
     }
 
     /**
+     * Sets the camera's view matrix.
      *
-     * @param eyeX
-     * @param eyeY
-     * @param eyeZ
-     * @param centerX
-     * @param centerY
-     * @param centerZ
-     * @param upX
-     * @param upY
-     * @param upZ
+     * @param eyeX      x-axis position of the camera in world space
+     * @param eyeY      y-axis position of the camera in world space
+     * @param eyeZ      z-axis position of the camera in world space
+     * @param centerX   x-axis position of the point in world space the camera is looking at
+     * @param centerY   y-axis position of the point in world space the camera is looking at
+     * @param centerZ   z-axis position of the point in world space the camera is looking at
+     * @param upX       x-axis coordinate of a unit vector denoting the camera's "up" direction
+     * @param upY       y-axis coordinate of a unit vector denoting the camera's "up" direction
+     * @param upZ       z-axis coordinate of a unit vector denoting the camera's "up" direction
      */
     public void lookAt(double eyeX, double eyeY, double eyeZ,
             double centerX, double centerY, double centerZ, double upX, double upY, double upZ) {
@@ -250,16 +313,14 @@ public class Camera {
     }
 
     /**
-     *
-     * @return Distance to the near plane.
+     * @return Distance to the near plane
      */
     public float getNear() {
         return nGetNear(getNativeObject());
     }
 
     /**
-     *
-     * @return Distance to the far plane.
+     * @return Distance to the far plane
      */
     public float getCullingFar() {
         return nGetCullingFar(getNativeObject());
@@ -267,12 +328,14 @@ public class Camera {
 
     /**
      * Retrieves the camera's projection matrix.
+     *
      * @param out A 16-float array where the projection matrix will be stored, or null in which
      *            case a new array is allocated.
+     *
      * @return A 16-float array containing the camera's projection as a column-major matrix.
      */
     @NonNull @Size(min = 16)
-    public double[] getProjectionMatrix(@Nullable @Size(min = 16) double out[]) {
+    public double[] getProjectionMatrix(@Nullable @Size(min = 16) double[] out) {
         out = Asserts.assertMat4d(out);
         nGetProjectionMatrix(getNativeObject(), out);
         return out;
@@ -281,12 +344,14 @@ public class Camera {
     /**
      * Retrieves the camera's model matrix. The model matrix encodes the camera position and
      * orientation, or pose.
+     *
      * @param out A 16-float array where the model matrix will be stored, or null in which
      *            case a new array is allocated.
+     *
      * @return A 16-float array containing the camera's pose as a column-major matrix.
      */
     @NonNull @Size(min = 16)
-    public float[] getModelMatrix(@Nullable @Size(min = 16) float out[]) {
+    public float[] getModelMatrix(@Nullable @Size(min = 16) float[] out) {
         out = Asserts.assertMat4f(out);
         nGetModelMatrix(getNativeObject(), out);
         return out;
@@ -297,10 +362,11 @@ public class Camera {
      *
      * @param out A 16-float array where the model view will be stored, or null in which
      *            case a new array is allocated.
+     *
      * @return A 16-float array containing the camera's view as a column-major matrix.
      */
     @NonNull @Size(min = 16)
-    public float[] getViewMatrix(@Nullable @Size(min = 16) float out[]) {
+    public float[] getViewMatrix(@Nullable @Size(min = 16) float[] out) {
         out = Asserts.assertMat4f(out);
         nGetViewMatrix(getNativeObject(), out);
         return out;
@@ -308,12 +374,14 @@ public class Camera {
 
     /**
      * Retrieves the camera position in world space.
+     *
      * @param out A 3-float array where the position will be stored, or null in which case a new
      *            array is allocated.
+     *
      * @return A 3-float array containing the camera's position in world units.
      */
     @NonNull @Size(min = 3)
-    public float[] getPosition(@Nullable @Size(min = 3) float out[]) {
+    public float[] getPosition(@Nullable @Size(min = 3) float[] out) {
         out = Asserts.assertFloat3(out);
         nGetPosition(getNativeObject(), out);
         return out;
@@ -322,12 +390,14 @@ public class Camera {
     /**
      * Retrieves the camera left unit vector in world space, that is a unit vector that points to
      * the left of the camera.
+     *
      * @param out A 3-float array where the left vector will be stored, or null in which case a new
      *            array is allocated.
+     *
      * @return A 3-float array containing the camera's left vector in world units.
      */
     @NonNull @Size(min = 3)
-    public float[] getLeftVector(@Nullable @Size(min = 3) float out[]) {
+    public float[] getLeftVector(@Nullable @Size(min = 3) float[] out) {
         out = Asserts.assertFloat3(out);
         nGetLeftVector(getNativeObject(), out);
         return out;
@@ -336,12 +406,14 @@ public class Camera {
     /**
      * Retrieves the camera up unit vector in world space, that is a unit vector that points up with
      * respect to the camera.
+     *
      * @param out A 3-float array where the up vector will be stored, or null in which case a new
      *            array is allocated.
+     *
      * @return A 3-float array containing the camera's up vector in world units.
      */
     @NonNull @Size(min = 3)
-    public float[] getUpVector(@Nullable @Size(min = 3) float out[]) {
+    public float[] getUpVector(@Nullable @Size(min = 3) float[] out) {
         out = Asserts.assertFloat3(out);
         nGetUpVector(getNativeObject(), out);
         return out;
@@ -350,52 +422,91 @@ public class Camera {
     /**
      * Retrieves the camera forward unit vector in world space, that is a unit vector that points
      * in the direction the camera is looking at.
+     *
      * @param out A 3-float array where the forward vector will be stored, or null in which case a
      *           new  array is allocated.
+     *
      * @return A 3-float array containing the camera's forward vector in world units.
      */
     @NonNull @Size(min = 3)
-    public float[] getForwardVector(@Nullable @Size(min = 3) float out[]) {
+    public float[] getForwardVector(@Nullable @Size(min = 3) float[] out) {
         out = Asserts.assertFloat3(out);
         nGetForwardVector(getNativeObject(), out);
         return out;
     }
 
     /**
+     * Sets this camera's exposure (default is f/16, 1/125s, 100 ISO)
      *
-     * @param aperture
-     * @param shutterSpeed
-     * @param sensitivity
+     * The exposure ultimately controls the scene's brightness, just like with a real camera.
+     * The default values provide adequate exposure for a camera placed outdoors on a sunny day
+     * with the sun at the zenith.
+     *
+     * With the default parameters, the scene must contain at least one Light of intensity
+     * similar to the sun (e.g.: a 100,000 lux directional light) and/or an indirect light
+     * of appropriate intensity (30,000).
+     *
+     * @param aperture      Aperture in f-stops, clamped between 0.5 and 64.
+     *                      A lower aperture value increases the exposure, leading to
+     *                      a brighter scene. Realistic values are between 0.95 and 32.
+     *
+     * @param shutterSpeed  Shutter speed in seconds, clamped between 1/25,000 and 60.
+     *                      A lower shutter speed increases the exposure. Realistic values are
+     *                      between 1/8000 and 30.
+     *
+     * @param sensitivity   Sensitivity in ISO, clamped between 10 and 204,800.
+     *                      A higher sensitivity increases the exposure. Realistic values are
+     *                      between 50 and 25600.
+     *
+     * @see LightManager
+     * @see Exposure
+     * @see #setExposure(float)
      */
     public void setExposure(float aperture, float shutterSpeed, float sensitivity) {
         nSetExposure(getNativeObject(), aperture, shutterSpeed, sensitivity);
     }
 
     /**
+     * Sets this camera's exposure directly. Calling this method will set the aperture
+     * to 1.0, the shutter speed to 1.2 and the sensitivity will be computed to match
+     * the requested exposure (for a desired exposure of 1.0, the sensitivity will be
+     * set to 100 ISO).
      *
-     * @return
+     * This method is useful when trying to match the lighting of other engines or tools.
+     * Many engines/tools use unit-less light intensities, which can be matched by setting
+     * the exposure manually. This can be typically achieved by setting the exposure to
+     * 1.0.
+     *
+     * @see Light
+     * @see Exposure
+     * @see #setExposure(float, float, float)
+     */
+    public void setExposure(float exposure) {
+        setExposure(1.0f, 1.2f, 100.0f * (1.0f / exposure));
+    }
+
+    /**
+     * @return Aperture in f-stops
      */
     public float getAperture() {
         return nGetAperture(getNativeObject());
     }
 
     /**
-     *
-     * @return
+     * @return Shutter speed in seconds
      */
     public float getShutterSpeed() {
         return nGetShutterSpeed(getNativeObject());
     }
 
     /**
-     *
-     * @return
+     * @return Sensitivity in ISO
      */
     public float getSensitivity() {
         return nGetSensitivity(getNativeObject());
     }
 
-    long getNativeObject() {
+    public long getNativeObject() {
         if (mNativeObject == 0) {
             throw new IllegalStateException("Calling method on destroyed Camera");
         }

android/filament-android/src/main/java/com/google/android/filament/Engine.java

@@ -16,21 +16,120 @@
 
 package com.google.android.filament;
 
-import com.google.android.filament.proguard.UsedByReflection;
-
 import android.support.annotation.NonNull;
 
+import com.google.android.filament.proguard.UsedByReflection;
+
+/**
+ * Engine is filament's main entry-point.
+ * <p>
+ * An Engine instance main function is to keep track of all resources created by the user and
+ * manage the rendering thread as well as the hardware renderer.
+ * <p>
+ * To use filament, an Engine instance must be created first:
+ *
+ * <pre>
+ * import com.google.android.filament.*
+ *
+ * Engine engine = Engine.create();
+ * </pre>
+ * <p>
+ * Engine essentially represents (or is associated to) a hardware context
+ * (e.g. an OpenGL ES context).
+ * <p>
+ * Rendering typically happens in an operating system's window (which can be full screen), such
+ * window is managed by a {@link Renderer}.
+ * <p>
+ * A typical filament render loop looks like this:
+ *
+ *
+ * <pre>
+ * import com.google.android.filament.*
+ *
+ * Engin engine         = Engine.create();
+ * SwapChain swapChain  = engine.createSwapChain(nativeWindow);
+ * Renderer renderer    = engine.createRenderer();
+ * Scene scene          = engine.createScene();
+ * View view            = engine.createView();
+ *
+ * view.setScene(scene);
+ *
+ * do {
+ *     // typically we wait for VSYNC and user input events
+ *     if (renderer.beginFrame(swapChain)) {
+ *         renderer.render(view);
+ *         renderer.endFrame();
+ *     }
+ * } while (!quit);
+ *
+ * engine.destroyView(view);
+ * engine.destroyScene(scene);
+ * engine.destroyRenderer(renderer);
+ * engine.destroySwapChain(swapChain);
+ * engine.destroy();
+ * </pre>
+ *
+ * <h1><u>Resource Tracking</u></h1>
+ * <p>
+ * Each <code>Engine</code> instance keeps track of all objects created by the user, such as vertex
+ * and index buffers, lights, cameras, etc...
+ * The user is expected to free those resources, however, leaked resources are freed when the
+ * engine instance is destroyed and a warning is emitted in the console.
+ *
+ * <h1><u>Thread safety</u></h1>
+ * <p>
+ * An <code>Engine</code> instance is not thread-safe. The implementation makes no attempt to
+ * synchronize calls to an <code>Engine</code> instance methods.
+ * If multi-threading is needed, synchronization must be external.
+ *
+ * <h1><u>Multi-threading</u></h1>
+ * <p>
+ * When created, the <code>Engine</code> instance starts a render thread as well as multiple worker
+ * threads, these threads have an elevated priority appropriate for rendering, based on the
+ * platform's best practices. The number of worker threads depends on the platform and is
+ * automatically chosen for best performance.
+ * <p>
+ * On platforms with asymmetric cores (e.g. ARM's Big.Little), <code>Engine</code> makes some
+ * educated guesses as to which cores to use for the render thread and worker threads. For example,
+ * it'll try to keep an OpenGL ES thread on a Big core.
+ *
+ * <h1><u>Swap Chains</u></h1>
+ * <p>
+ * A swap chain represents an Operating System's <b>native</b> renderable surface.
+ * Typically it's a window or a view. Because a {@link SwapChain} is initialized from a native
+ * object, it is given to filament as an <code>Object</code>, which must be of the proper type for
+ * each platform filament is running on.
+ * <p>
+ *
+ * @see SwapChain
+ * @see Renderer
+ */
 public class Engine {
     private long mNativeObject;
     @NonNull private final TransformManager mTransformManager;
     @NonNull private final LightManager mLightManager;
     @NonNull private final RenderableManager mRenderableManager;
 
+    /**
+     * Denotes a backend
+     */
     public enum Backend {
-        DEFAULT,  // Automatically selects an appropriate driver for the platform.
-        OPENGL,   // Selects the OpenGL ES driver.
-        VULKAN,   // Selects the experimental Vulkan driver.
-        NOOP,     // Selects the no-op driver for testing purposes.
+        /**
+         * Automatically selects an appropriate driver for the platform.
+         */
+        DEFAULT,
+        /**
+         * Selects the OpenGL ES driver.
+         */
+        OPENGL,
+        /**
+         * Selects the experimental Vulkan driver.
+         */
+        VULKAN,
+        /**
+         * Selects the no-op driver for testing purposes.
+         */
+        NOOP,
     }
 
     private Engine(long nativeEngine) {
@@ -40,6 +139,19 @@ public class Engine {
         mRenderableManager = new RenderableManager(nGetRenderableManager(nativeEngine));
     }
 
+    /**
+     * Creates an instance of Engine using the default {@link Backend}
+     * <p>
+     * This method is one of the few thread-safe methods.
+     *
+     * @return A newly created <code>Engine</code>, or <code>null</code> if the GPU driver couldn't
+     *         be initialized, for instance if it doesn't support the right version of OpenGL or
+     *         OpenGL ES.
+     *
+     * @exception IllegalStateException can be thrown if there isn't enough memory to
+     * allocate the command buffer.
+     *
+     */
     @NonNull
     public static Engine create() {
         long nativeEngine = nCreateEngine(0, 0);
@@ -47,6 +159,21 @@ public class Engine {
         return new Engine(nativeEngine);
     }
 
+    /**
+     * Creates an instance of Engine using the specified {@link Backend}
+     * <p>
+     * This method is one of the few thread-safe methods.
+     *
+     * @param backend           driver backend to use
+     *
+     * @return A newly created <code>Engine</code>, or <code>null</code> if the GPU driver couldn't
+     *         be initialized, for instance if it doesn't support the right version of OpenGL or
+     *         OpenGL ES.
+     *
+     * @exception IllegalStateException can be thrown if there isn't enough memory to
+     * allocate the command buffer.
+     *
+     */
     @NonNull
     public static Engine create(@NonNull Backend backend) {
         long nativeEngine = nCreateEngine(backend.ordinal(), 0);
@@ -55,9 +182,21 @@ public class Engine {
     }
 
     /**
-     * Valid shared context:
-     * - Android: EGLContext
-     * - Other: none
+     * Creates an instance of Engine using the {@link Backend#OPENGL} and a shared OpenGL context.
+     * <p>
+     * This method is one of the few thread-safe methods.
+     *
+     * @param sharedContext  A platform-dependant OpenGL context used as a shared context
+     *                       when creating filament's internal context. On Android this parameter
+     *                       <b>must be</b> an instance of {@link android.opengl.EGLContext}.
+     *
+     * @return A newly created <code>Engine</code>, or <code>null</code> if the GPU driver couldn't
+     *         be initialized, for instance if it doesn't support the right version of OpenGL or
+     *         OpenGL ES.
+     *
+     * @exception IllegalStateException can be thrown if there isn't enough memory to
+     * allocate the command buffer.
+     *
      */
     @NonNull
     public static Engine create(@NonNull Object sharedContext) {
@@ -70,15 +209,41 @@ public class Engine {
         throw new IllegalArgumentException("Invalid shared context " + sharedContext);
     }
 
+    /**
+     * @return <code>true</code> if this <code>Engine</code> is initialized properly.
+     */
     public boolean isValid() {
         return mNativeObject != 0;
     }
 
+    /**
+     * Destroy the <code>Engine</code> instance and all associated resources.
+     * <p>
+     * This method is one of the few thread-safe methods.
+     * <p>
+     * {@link Engine#destroy()} should be called last and after all other resources have been
+     * destroyed, it ensures all filament resources are freed.
+     * <p>
+     * <code>Destroy</code> performs the following tasks:
+     * <li>Destroy all internal software and hardware resources.</li>
+     * <li>Free all user allocated resources that are not already destroyed and logs a warning.
+     *     <p>This indicates a "leak" in the user's code.</li>
+     * <li>Terminate the rendering engine's thread.</li>
+     *
+     * <pre>
+     * Engine engine = Engine.create();
+     * engine.destroy();
+     * </pre>
+     */
     public void destroy() {
         nDestroyEngine(getNativeObject());
         clearNativeObject();
     }
 
+    /**
+     * @return the backend used by this <code>Engine</code>
+     */
+    @NonNull
     public Backend getBackend() {
         return Backend.values()[(int) nGetBackend(getNativeObject())];
     }
@@ -86,25 +251,36 @@ public class Engine {
     // SwapChain
 
     /**
-     * Valid surface types:
-     * - Android: Surface
-     * - Other: none
+     * Creates an opaque {@link SwapChain} from the given OS native window handle.
+     *
+     * @param surface on Android, <b>must be</b> an instance of {@link android.view.Surface}
+     *
+     * @return a newly created {@link SwapChain} object
+     *
+     * @exception IllegalStateException can be thrown if the SwapChain couldn't be created
      */
+    @NonNull
     public SwapChain createSwapChain(@NonNull Object surface) {
         return createSwapChain(surface, SwapChain.CONFIG_DEFAULT);
     }
 
     /**
-     * Valid surface types:
-     * - Android: Surface
-     * - Other: none
+     * Creates a {@link SwapChain} from the given OS native window handle.
      *
-     * Flags: see CONFIG flags in SwapChain.
+     * @param surface on Android, <b>must be</b> an instance of {@link android.view.Surface}
+     *
+     * @param flags configuration flags, see {@link SwapChain}
+     *
+     * @return a newly created {@link SwapChain} object
+     *
+     * @exception IllegalStateException can be thrown if the SwapChain couldn't be created
      *
      * @see SwapChain#CONFIG_DEFAULT
      * @see SwapChain#CONFIG_TRANSPARENT
      * @see SwapChain#CONFIG_READABLE
+     *
      */
+    @NonNull
     public SwapChain createSwapChain(@NonNull Object surface, long flags) {
         if (Platform.get().validateSurface(surface)) {
             long nativeSwapChain = nCreateSwapChain(getNativeObject(), surface, flags);
@@ -114,6 +290,18 @@ public class Engine {
         throw new IllegalArgumentException("Invalid surface " + surface);
     }
 
+    /**
+     * Creates a {@link SwapChain} from a {@link NativeSurface}.
+     *
+     * @param surface a properly initialized {@link NativeSurface}
+     *
+     * @param flags configuration flags, see {@link SwapChain}
+     *
+     * @return a newly created {@link SwapChain} object
+     *
+     * @exception IllegalStateException can be thrown if the {@link SwapChain} couldn't be created
+     */
+    @NonNull
     public SwapChain createSwapChainFromNativeSurface(@NonNull NativeSurface surface, long flags) {
         long nativeSwapChain =
                 nCreateSwapChainFromRawPointer(getNativeObject(), surface.getNativeObject(), flags);
@@ -121,6 +309,10 @@ public class Engine {
         return new SwapChain(nativeSwapChain, surface);
     }
 
+    /**
+     * Destroys a {@link SwapChain} and frees all its associated resources.
+     * @param swapChain the {@link SwapChain} to destroy
+     */
     public void destroySwapChain(@NonNull SwapChain swapChain) {
         nDestroySwapChain(getNativeObject(), swapChain.getNativeObject());
         swapChain.clearNativeObject();
@@ -128,6 +320,11 @@ public class Engine {
 
     // View
 
+    /**
+     * Creates a {@link View}.
+     * @return a newly created {@link View}
+     * @exception IllegalStateException can be thrown if the {@link View} couldn't be created
+     */
     @NonNull
     public View createView() {
         long nativeView = nCreateView(getNativeObject());
@@ -135,6 +332,10 @@ public class Engine {
         return new View(nativeView);
     }
 
+    /**
+     * Destroys a {@link View} and frees all its associated resources.
+     * @param view the {@link View} to destroy
+     */
     public void destroyView(@NonNull View view) {
         nDestroyView(getNativeObject(), view.getNativeObject());
         view.clearNativeObject();
@@ -142,6 +343,11 @@ public class Engine {
 
     // Renderer
 
+    /**
+     * Creates a {@link Renderer}.
+     * @return a newly created {@link Renderer}
+     * @exception IllegalStateException can be thrown if the {@link Renderer} couldn't be created
+     */
     @NonNull
     public Renderer createRenderer() {
         long nativeRenderer = nCreateRenderer(getNativeObject());
@@ -149,6 +355,10 @@ public class Engine {
         return new Renderer(this, nativeRenderer);
     }
 
+    /**
+     * Destroys a {@link Renderer} and frees all its associated resources.
+     * @param renderer the {@link Renderer} to destroy
+     */
     public void destroyRenderer(@NonNull Renderer renderer) {
         nDestroyRenderer(getNativeObject(), renderer.getNativeObject());
         renderer.clearNativeObject();
@@ -156,6 +366,12 @@ public class Engine {
 
     // Camera
 
+    /**
+     * Creates a new <code>entity</code> and adds a {@link Camera} component to it.
+     *
+     * @return A newly created {@link Camera}
+     * @exception IllegalStateException can be thrown if the {@link Camera} couldn't be created
+     */
     @NonNull
     public Camera createCamera() {
         long nativeCamera = nCreateCamera(getNativeObject());
@@ -163,6 +379,13 @@ public class Engine {
         return new Camera(nativeCamera);
     }
 
+    /**
+     * Creates and adds a {@link Camera} component to a given <code>entity</code>.
+     *
+     * @param entity <code>entity</code> to add the camera component to
+     * @return A newly created {@link Camera}
+     * @exception IllegalStateException can be thrown if the {@link Camera} couldn't be created
+     */
     @NonNull
     public Camera createCamera(@Entity int entity) {
         long nativeCamera = nCreateCameraWithEntity(getNativeObject(), entity);
@@ -170,6 +393,10 @@ public class Engine {
         return new Camera(nativeCamera);
     }
 
+    /**
+     * Destroys a {@link Camera} component and frees all its associated resources.
+     * @param camera the {@link Camera} to destroy
+     */
     public void destroyCamera(@NonNull Camera camera) {
         nDestroyCamera(getNativeObject(), camera.getNativeObject());
         camera.clearNativeObject();
@@ -177,6 +404,11 @@ public class Engine {
 
     // Scene
 
+    /**
+     * Creates a {@link Scene}.
+     * @return a newly created {@link Scene}
+     * @exception IllegalStateException can be thrown if the {@link Scene} couldn't be created
+     */
     @NonNull
     public Scene createScene() {
         long nativeScene = nCreateScene(getNativeObject());
@@ -184,6 +416,10 @@ public class Engine {
         return new Scene(nativeScene);
     }
 
+    /**
+     * Destroys a {@link Scene} and frees all its associated resources.
+     * @param scene the {@link Scene} to destroy
+     */
     public void destroyScene(@NonNull Scene scene) {
         nDestroyScene(getNativeObject(), scene.getNativeObject());
         scene.clearNativeObject();
@@ -191,6 +427,10 @@ public class Engine {
 
     // Stream
 
+    /**
+     * Destroys a {@link Stream} and frees all its associated resources.
+     * @param stream the {@link Stream} to destroy
+     */
     public void destroyStream(@NonNull Stream stream) {
         nDestroyStream(getNativeObject(), stream.getNativeObject());
         stream.clearNativeObject();
@@ -198,13 +438,22 @@ public class Engine {
 
     // Fence
 
+    /**
+     * Creates a {@link Fence}.
+     * @return a newly created {@link Fence}
+     * @exception IllegalStateException can be thrown if the {@link Fence} couldn't be created
+     */
     @NonNull
-    public Fence createFence(@NonNull Fence.Type type) {
-        long nativeFence = nCreateFence(getNativeObject(), type.ordinal());
+    public Fence createFence() {
+        long nativeFence = nCreateFence(getNativeObject());
         if (nativeFence == 0) throw new IllegalStateException("Couldn't create Fence");
         return new Fence(nativeFence);
     }
 
+    /**
+     * Destroys a {@link Fence} and frees all its associated resources.
+     * @param fence the {@link Fence} to destroy
+     */
     public void destroyFence(@NonNull Fence fence) {
         nDestroyFence(getNativeObject(), fence.getNativeObject());
         fence.clearNativeObject();
@@ -212,73 +461,134 @@ public class Engine {
 
     // others...
 
+    /**
+     * Destroys a {@link IndexBuffer} and frees all its associated resources.
+     * @param indexBuffer the {@link IndexBuffer} to destroy
+     */
     public void destroyIndexBuffer(@NonNull IndexBuffer indexBuffer) {
         nDestroyIndexBuffer(getNativeObject(), indexBuffer.getNativeObject());
         indexBuffer.clearNativeObject();
     }
 
+    /**
+     * Destroys a {@link VertexBuffer} and frees all its associated resources.
+     * @param vertexBuffer the {@link VertexBuffer} to destroy
+     */
     public void destroyVertexBuffer(@NonNull VertexBuffer vertexBuffer) {
         nDestroyVertexBuffer(getNativeObject(), vertexBuffer.getNativeObject());
         vertexBuffer.clearNativeObject();
     }
 
+    /**
+     * Destroys a {@link IndirectLight} and frees all its associated resources.
+     * @param ibl the {@link IndirectLight} to destroy
+     */
     public void destroyIndirectLight(@NonNull IndirectLight ibl) {
         nDestroyIndirectLight(getNativeObject(), ibl.getNativeObject());
         ibl.clearNativeObject();
     }
 
+    /**
+     * Destroys a {@link Material} and frees all its associated resources.
+     * <p>
+     * All {@link MaterialInstance} of the specified {@link Material} must be destroyed before
+     * destroying it; if some {@link MaterialInstance} remain, this method fails silently.
+     *
+     * @param material the {@link Material} to destroy
+     */
     public void destroyMaterial(@NonNull Material material) {
         nDestroyMaterial(getNativeObject(), material.getNativeObject());
         material.clearNativeObject();
     }
 
+    /**
+     * Destroys a {@link MaterialInstance} and frees all its associated resources.
+     * @param materialInstance the {@link MaterialInstance} to destroy
+     */
     public void destroyMaterialInstance(@NonNull MaterialInstance materialInstance) {
         nDestroyMaterialInstance(getNativeObject(), materialInstance.getNativeObject());
         materialInstance.clearNativeObject();
     }
 
+    /**
+     * Destroys a {@link Skybox} and frees all its associated resources.
+     * @param skybox the {@link Skybox} to destroy
+     */
     public void destroySkybox(@NonNull Skybox skybox) {
         nDestroySkybox(getNativeObject(), skybox.getNativeObject());
         skybox.clearNativeObject();
     }
 
+    /**
+     * Destroys a {@link Texture} and frees all its associated resources.
+     * @param texture the {@link Texture} to destroy
+     */
     public void destroyTexture(@NonNull Texture texture) {
         nDestroyTexture(getNativeObject(), texture.getNativeObject());
         texture.clearNativeObject();
     }
 
+    /**
+     * Destroys a {@link RenderTarget} and frees all its associated resources.
+     * @param target the {@link RenderTarget} to destroy
+     */
     public void destroyRenderTarget(@NonNull RenderTarget target) {
         nDestroyRenderTarget(getNativeObject(), target.getNativeObject());
         target.clearNativeObject();
     }
 
+    /**
+     * Destroys an <code>entity</code> and all its components.
+     * <p>
+     * It is recommended to destroy components individually before destroying their
+     * <code>entity</code>, this gives more control as to when the destruction really happens.
+     * Otherwise, orphaned components are garbage collected, which can happen at a later time.
+     * Even when component are garbage collected, the destruction of their <code>entity</code>
+     * terminates their participation immediately.
+     *
+     * @param entity the <code>entity</code> to destroy
+     */
     public void destroyEntity(@Entity int entity) {
         nDestroyEntity(getNativeObject(), entity);
     }
 
     // Managers
 
+    /**
+     * @return the {@link TransformManager} used by this {@link Engine}
+     */
     @NonNull
     public TransformManager getTransformManager() {
         return mTransformManager;
     }
 
+    /**
+     * @return the {@link LightManager} used by this {@link Engine}
+     */
     @NonNull
     public LightManager getLightManager() {
         return mLightManager;
     }
 
+    /**
+     * @return the {@link RenderableManager} used by this {@link Engine}
+     */
     @NonNull
     public RenderableManager getRenderableManager() {
         return mRenderableManager;
     }
 
+    /**
+     * Kicks the hardware thread (e.g.: the OpenGL, Vulkan or Metal thread) and blocks until
+     * all commands to this point are executed. Note that this doesn't guarantee that the
+     * hardware is actually finished.
+     */
     public void flushAndWait() {
-        Fence.waitAndDestroy(createFence(Fence.Type.HARD), Fence.Mode.FLUSH);
+        Fence.waitAndDestroy(createFence(), Fence.Mode.FLUSH);
     }
 
     @UsedByReflection("TextureHelper.java")
-    long getNativeObject() {
+    public long getNativeObject() {
         if (mNativeObject == 0) {
             throw new IllegalStateException("Calling method on destroyed Engine");
         }
@@ -304,7 +614,7 @@ public class Engine {
     private static native void nDestroyCamera(long nativeEngine, long nativeCamera);
     private static native long nCreateScene(long nativeEngine);
     private static native void nDestroyScene(long nativeEngine, long nativeScene);
-    private static native long nCreateFence(long nativeEngine, int fenceType);
+    private static native long nCreateFence(long nativeEngine);
     private static native void nDestroyFence(long nativeEngine, long nativeFence);
     private static native void nDestroyStream(long nativeEngine, long nativeStream);
     private static native void nDestroyIndexBuffer(long nativeEngine, long nativeIndexBuffer);

android/filament-android/src/main/java/com/google/android/filament/EntityManager.java

@@ -16,11 +16,11 @@
 
 package com.google.android.filament;
 
-import com.google.android.filament.proguard.UsedByReflection;
-
 import android.support.annotation.IntRange;
 import android.support.annotation.NonNull;
 
+import com.google.android.filament.proguard.UsedByReflection;
+
 public class EntityManager {
     private long mNativeObject = nGetEntityManager();
 
@@ -69,7 +69,7 @@ public class EntityManager {
     }
 
     @UsedByReflection("AssetLoader.java")
-    long getNativeObject() {
+    public long getNativeObject() {
         return mNativeObject;
     }
 

android/filament-android/src/main/java/com/google/android/filament/Fence.java

@@ -26,11 +26,6 @@ public class Fence {
 
     public static final long WAIT_FOR_EVER = -1;
 
-    public enum Type {
-        SOFT,
-        HARD
-    }
-
     public enum Mode {
         FLUSH,
         DONT_FLUSH
@@ -70,7 +65,7 @@ public class Fence {
         }
     }
 
-    long getNativeObject() {
+    public long getNativeObject() {
         if (mNativeObject == 0) {
             throw new IllegalStateException("Calling method on destroyed Fence");
         }

android/filament-android/src/main/java/com/google/android/filament/IndexBuffer.java

@@ -30,13 +30,6 @@ public class IndexBuffer {
         mNativeObject = nativeIndexBuffer;
     }
 
-    long getNativeObject() {
-        if (mNativeObject == 0) {
-            throw new IllegalStateException("Calling method on destroyed IndexBuffer");
-        }
-        return mNativeObject;
-    }
-
     public static class Builder {
         @SuppressWarnings({"FieldCanBeLocal", "UnusedDeclaration"})
         // Keep to finalize native resources
@@ -121,6 +114,13 @@ public class IndexBuffer {
         }
     }
 
+    public long getNativeObject() {
+        if (mNativeObject == 0) {
+            throw new IllegalStateException("Calling method on destroyed IndexBuffer");
+        }
+        return mNativeObject;
+    }
+
     void clearNativeObject() {
         mNativeObject = 0;
     }

android/filament-android/src/main/java/com/google/android/filament/IndirectLight.java

@@ -16,13 +16,13 @@
 
 package com.google.android.filament;
 
-import com.google.android.filament.proguard.UsedByReflection;
-
 import android.support.annotation.IntRange;
 import android.support.annotation.NonNull;
 import android.support.annotation.Nullable;
 import android.support.annotation.Size;
 
+import com.google.android.filament.proguard.UsedByReflection;
+
 public class IndirectLight {
     long mNativeObject;
 
@@ -165,7 +165,7 @@ public class IndirectLight {
         return colorIntensity;
     }
 
-    long getNativeObject() {
+    public long getNativeObject() {
         if (mNativeObject == 0) {
             throw new IllegalStateException("Calling method on destroyed IndirectLight");
         }

android/filament-android/src/main/java/com/google/android/filament/LightManager.java

@@ -270,6 +270,10 @@ public class LightManager {
         return nIsShadowCaster(mNativeObject, i);
     }
 
+    public long getNativeObject() {
+        return mNativeObject;
+    }
+
     private static native boolean nHasComponent(long nativeLightManager, int entity);
     private static native int nGetInstance(long nativeLightManager, int entity);
     private static native void nDestroy(long nativeLightManager, int entity);

android/filament-android/src/main/java/com/google/android/filament/Material.java

@@ -19,6 +19,7 @@ package com.google.android.filament;
 import android.support.annotation.IntRange;
 import android.support.annotation.NonNull;
 import android.support.annotation.Size;
+
 import com.google.android.filament.proguard.UsedByNative;
 
 import java.nio.Buffer;
@@ -338,7 +339,7 @@ public class Material {
         mDefaultInstance.setParameter(name, texture, sampler);
     }
 
-    long getNativeObject() {
+    public long getNativeObject() {
         if (mNativeObject == 0) {
             throw new IllegalStateException("Calling method on destroyed Material");
         }

android/filament-android/src/main/java/com/google/android/filament/MaterialInstance.java

@@ -178,7 +178,11 @@ public class MaterialInstance {
         nSetDoubleSided(getNativeObject(), doubleSided);
     }
 
-    long getNativeObject() {
+    public void setCullingMode(Material.CullingMode mode) {
+        nSetCullingMode(getNativeObject(), mode.ordinal());
+    }
+
+    public long getNativeObject() {
         if (mNativeObject == 0) {
             throw new IllegalStateException("Calling method on destroyed MaterialInstance");
         }
@@ -247,4 +251,6 @@ public class MaterialInstance {
             float threshold);
 
     private static native void nSetDoubleSided(long nativeMaterialInstance, boolean doubleSided);
+
+    private static native void nSetCullingMode(long nativeMaterialInstance, long mode);
 }

android/filament-android/src/main/java/com/google/android/filament/NioUtils.java

@@ -17,6 +17,7 @@
 package com.google.android.filament;
 
 import android.support.annotation.NonNull;
+
 import com.google.android.filament.proguard.UsedByNative;
 
 import java.nio.Buffer;

android/filament-android/src/main/java/com/google/android/filament/RenderTarget.java

@@ -20,9 +20,6 @@ import android.support.annotation.IntRange;
 import android.support.annotation.NonNull;
 import android.support.annotation.Nullable;
 
-import java.nio.Buffer;
-import java.nio.BufferOverflowException;
-
 public class RenderTarget {
     private long mNativeObject;
     private final Texture[] mTextures = new Texture[2];
@@ -33,7 +30,7 @@ public class RenderTarget {
         mTextures[1] = builder.mTextures[1];
     }
 
-    long getNativeObject() {
+    public long getNativeObject() {
         if (mNativeObject == 0) {
             throw new IllegalStateException("Calling method on destroyed RenderTarget");
         }

android/filament-android/src/main/java/com/google/android/filament/RenderableManager.java

@@ -340,6 +340,10 @@ public class RenderableManager {
         return requiredAttributes;
     }
 
+    public long getNativeObject() {
+        return mNativeObject;
+    }
+
     private static native boolean nHasComponent(long nativeRenderableManager, int entity);
     private static native int nGetInstance(long nativeRenderableManager, int entity);
     private static native void nDestroy(long nativeRenderableManager, int entity);

android/filament-android/src/main/java/com/google/android/filament/Renderer.java

@@ -104,7 +104,7 @@ public class Renderer {
         nResetUserTime(getNativeObject());
     }
 
-    long getNativeObject() {
+    public long getNativeObject() {
         if (mNativeObject == 0) {
             throw new IllegalStateException("Calling method on destroyed Renderer");
         }

android/filament-android/src/main/java/com/google/android/filament/Scene.java

@@ -75,7 +75,7 @@ public class Scene {
         return nGetLightCount(getNativeObject());
     }
 
-    long getNativeObject() {
+    public long getNativeObject() {
         if (mNativeObject == 0) {
             throw new IllegalStateException("Calling method on destroyed Scene");
         }

android/filament-android/src/main/java/com/google/android/filament/Skybox.java

@@ -16,11 +16,11 @@
 
 package com.google.android.filament;
 
-import com.google.android.filament.proguard.UsedByReflection;
-
 import android.support.annotation.IntRange;
 import android.support.annotation.NonNull;
 
+import com.google.android.filament.proguard.UsedByReflection;
+
 public class Skybox {
     private long mNativeObject;
 
@@ -83,7 +83,7 @@ public class Skybox {
         return nGetLayerMask(getNativeObject());
     }
 
-    long getNativeObject() {
+    public long getNativeObject() {
         if (mNativeObject == 0) {
             throw new IllegalStateException("Calling method on destroyed Skybox");
         }

android/filament-android/src/main/java/com/google/android/filament/Stream.java

@@ -132,7 +132,7 @@ public class Stream {
         return nGetTimestamp(getNativeObject());
     }
 
-    long getNativeObject() {
+    public long getNativeObject() {
         if (mNativeObject == 0) {
             throw new IllegalStateException("Calling method on destroyed Stream");
         }

android/filament-android/src/main/java/com/google/android/filament/SwapChain.java

@@ -36,7 +36,7 @@ public class SwapChain {
         return mSurface;
     }
 
-    long getNativeObject() {
+    public long getNativeObject() {
         if (mNativeObject == 0) {
             throw new IllegalStateException("Calling method on destroyed SwapChain");
         }

android/filament-android/src/main/java/com/google/android/filament/Texture.java

@@ -16,13 +16,13 @@
 
 package com.google.android.filament;
 
-import com.google.android.filament.proguard.UsedByReflection;
-
 import android.support.annotation.IntRange;
 import android.support.annotation.NonNull;
 import android.support.annotation.Nullable;
 import android.support.annotation.Size;
 
+import com.google.android.filament.proguard.UsedByReflection;
+
 import java.nio.Buffer;
 import java.nio.BufferOverflowException;
 import java.nio.ByteBuffer;
@@ -524,7 +524,7 @@ public class Texture {
 
 
     @UsedByReflection("TextureHelper.java")
-    long getNativeObject() {
+    public long getNativeObject() {
         if (mNativeObject == 0) {
             throw new IllegalStateException("Calling method on destroyed Texture");
         }

android/filament-android/src/main/java/com/google/android/filament/TransformManager.java

@@ -87,6 +87,10 @@ public class TransformManager {
         nCommitLocalTransformTransaction(mNativeObject);
     }
 
+    public long getNativeObject() {
+        return mNativeObject;
+    }
+
     private static native boolean nHasComponent(long nativeTransformManager, int entity);
     private static native int nGetInstance(long nativeTransformManager, int entity);
     private static native int nCreate(long nativeTransformManager, int entity);

android/filament-android/src/main/java/com/google/android/filament/VertexBuffer.java

@@ -31,13 +31,22 @@ public class VertexBuffer {
     }
 
     public enum VertexAttribute {
-        POSITION, // XYZ position (float3)
-        TANGENTS, // tangent, bitangent and normal, encoded as a quaternion (4 floats or half floats)
-        COLOR, // vertex color (float4)
-        UV0, // texture coordinates (float2)
-        UV1, // texture coordinates (float2)
+        POSITION,     // XYZ position (float3)
+        TANGENTS,     // tangent, bitangent and normal, encoded as a quaternion (4 floats or half floats)
+        COLOR,        // vertex color (float4)
+        UV0,          // texture coordinates (float2)
+        UV1,          // texture coordinates (float2)
         BONE_INDICES, // indices of 4 bones (uvec4)
-        BONE_WEIGHTS    // weights of the 4 bones (normalized float4)
+        BONE_WEIGHTS, // weights of the 4 bones (normalized float4)
+        UNUSED,       // reserved for future use
+        CUSTOM0,      // custom or MORPH_POSITION_0
+        CUSTOM1,      // custom or MORPH_POSITION_1
+        CUSTOM2,      // custom or MORPH_POSITION_2
+        CUSTOM3,      // custom or MORPH_POSITION_3
+        CUSTOM4,      // custom or MORPH_TANGENTS_0
+        CUSTOM5,      // custom or MORPH_TANGENTS_1
+        CUSTOM6,      // custom or MORPH_TANGENTS_2
+        CUSTOM7       // custom or MORPH_TANGENTS_3
     }
 
     public enum AttributeType {
@@ -197,7 +206,7 @@ public class VertexBuffer {
                 context.tangentsStride);
     }
 
-    long getNativeObject() {
+    public long getNativeObject() {
         if (mNativeObject == 0) {
             throw new IllegalStateException("Calling method on destroyed VertexBuffer");
         }

android/filament-android/src/main/java/com/google/android/filament/View.java

@@ -21,7 +21,7 @@ import android.support.annotation.NonNull;
 import android.support.annotation.Nullable;
 import android.support.annotation.Size;
 
-import static com.google.android.filament.Colors.*;
+import static com.google.android.filament.Colors.LinearColor;
 
 public class View {
     private long mNativeObject;
@@ -298,7 +298,7 @@ public class View {
         return mAmbientOcclusionOptions;
     }
 
-    long getNativeObject() {
+    public long getNativeObject() {
         if (mNativeObject == 0) {
             throw new IllegalStateException("Calling method on destroyed View");
         }

android/filament-android/src/main/java/com/google/android/filament/android/UiHelper.java

@@ -18,7 +18,6 @@ package com.google.android.filament.android;
 
 import android.graphics.PixelFormat;
 import android.graphics.SurfaceTexture;
-
 import android.os.Build;
 import android.support.annotation.NonNull;
 import android.support.annotation.Nullable;
@@ -27,6 +26,7 @@ import android.view.Surface;
 import android.view.SurfaceHolder;
 import android.view.SurfaceView;
 import android.view.TextureView;
+
 import com.google.android.filament.SwapChain;
 
 /**

android/gltfio-android/.gitignore

@@ -9,3 +9,4 @@
 /build
 /captures
 .externalNativeBuild
+/.cxx

android/gltfio-android/build.gradle

@@ -13,7 +13,7 @@ buildscript {
         jcenter()
     }
     dependencies {
-        classpath 'com.android.tools.build:gradle:3.4.1'
+        classpath 'com.android.tools.build:gradle:3.5.0'
     }
 }
 
@@ -25,7 +25,7 @@ allprojects {
 }
 
 group = "com.google.android.filament"
-version = "0.1"
+version = "1.3"
 
 apply plugin: 'com.android.library'
 
@@ -35,10 +35,10 @@ if (project.hasProperty("filament_dist_dir")) {
 }
 
 android {
-    compileSdkVersion 28
+    compileSdkVersion 29
     defaultConfig {
         minSdkVersion 14
-        targetSdkVersion 28
+        targetSdkVersion 29
         versionCode 1
         versionName "1.0"
 
@@ -47,7 +47,7 @@ android {
         externalNativeBuild {
             cmake {
                 arguments.add("-DANDROID_PIE=ON")
-                arguments.add("-DANDROID_PLATFORM=android-21")
+                arguments.add("-DANDROID_PLATFORM=android-19")
                 arguments.add("-DANDROID_STL=c++_static")
                 arguments.add("-DFILAMENT_DIST_DIR=${filament_path}".toString())
                 cppFlags.add("-std=c++14")

android/gltfio-android/gradle/wrapper/gradle-wrapper.properties

@@ -1,5 +1,5 @@
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-5.4-bin.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-5.4.1-all.zip
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists

android/gltfio-android/src/main/cpp/KtxLoader.cpp

@@ -34,7 +34,7 @@ Java_com_google_android_filament_gltfio_KtxLoader_nCreateTexture(JNIEnv* env, jc
     Engine* engine = (Engine*) nativeEngine;
     AutoBuffer buffer(env, javaBuffer, remaining);
     KtxBundle* bundle = new KtxBundle((const uint8_t*) buffer.getData(), buffer.getSize());
-    return (jlong) KtxUtility::createTexture(engine, *bundle, srgb, [](void* userdata) {
+    return (jlong) ktx::createTexture(engine, *bundle, srgb, [](void* userdata) {
         KtxBundle* bundle = (KtxBundle*) userdata;
         delete bundle;
     }, bundle);
@@ -46,7 +46,7 @@ Java_com_google_android_filament_gltfio_KtxLoader_nCreateIndirectLight(JNIEnv* e
     Engine* engine = (Engine*) nativeEngine;
     AutoBuffer buffer(env, javaBuffer, remaining);
     KtxBundle* bundle = new KtxBundle((const uint8_t*) buffer.getData(), buffer.getSize());
-    Texture* cubemap = KtxUtility::createTexture(engine, *bundle, srgb,  [](void* userdata) {
+    Texture* cubemap = ktx::createTexture(engine, *bundle, srgb,  [](void* userdata) {
         KtxBundle* bundle = (KtxBundle*) userdata;
         delete bundle;
     }, bundle);
@@ -69,7 +69,7 @@ Java_com_google_android_filament_gltfio_KtxLoader_nCreateSkybox(JNIEnv* env, jcl
     Engine* engine = (Engine*) nativeEngine;
     AutoBuffer buffer(env, javaBuffer, remaining);
     KtxBundle* bundle = new KtxBundle((const uint8_t*) buffer.getData(), buffer.getSize());
-    Texture* cubemap = KtxUtility::createTexture(engine, *bundle, srgb,  [](void* userdata) {
+    Texture* cubemap = ktx::createTexture(engine, *bundle, srgb,  [](void* userdata) {
         KtxBundle* bundle = (KtxBundle*) userdata;
         delete bundle;
     }, bundle);

android/gltfio-android/src/main/java/com/google/android/filament/gltfio/AssetLoader.java

@@ -29,6 +29,44 @@ import java.lang.reflect.Constructor;
 import java.lang.reflect.Method;
 import java.nio.Buffer;
 
+/**
+ * Consumes a blob of glTF 2.0 content (either JSON or GLB) and produces {@link FilamentAsset}
+ * objects, which are bundles of Filament entities, material instances, textures, vertex buffers,
+ * and index buffers.
+ *
+ * <p>AssetLoader does not fetch external buffer data or create textures on its own. Clients can use
+ * the provided {@link ResourceLoader} class for this, which obtains the URI list from the asset.
+ * This is demonstrated in the Kotlin snippet below.</p>
+ *
+ * <pre>
+ *
+ * companion object {
+ *     init {
+ *        Filament.init()
+ *        AssetLoader.init()
+ *    }
+ * }
+ *
+ * override fun onCreate(savedInstanceState: Bundle?) {
+ *
+ *     ...
+ *
+ *     assetLoader = AssetLoader(engine, MaterialProvider(engine), EntityManager.get())
+ *
+ *     filamentAsset = assets.open("models/lucy.glb").use { input ->
+ *         val bytes = ByteArray(input.available())
+ *         input.read(bytes)
+ *         assetLoader.createAssetFromBinary(ByteBuffer.wrap(bytes))!!
+ *     }
+ *
+ *     ResourceLoader(engine).loadResources(filamentAsset).destroy()
+ *     scene.addEntities(filamentAsset.entities)
+ * }
+ * </pre>
+ *
+ * @see FilamentAsset
+ * @see ResourceLoader
+ */
 public class AssetLoader {
     private long mNativeObject;
 
@@ -38,6 +76,9 @@ public class AssetLoader {
     static Constructor<IndirectLight> sIndirectLightConstructor;
     static Constructor<Skybox> sSkyboxConstructor;
 
+    /**
+     * Initializes the gltfio JNI layer. Must be called before using any gltfio functionality.
+     */
     public static void init() {
         System.loadLibrary("gltfio-jni");
         try {
@@ -60,6 +101,14 @@ public class AssetLoader {
         }
     }
 
+    /**
+     * Constructs an <code>AssetLoader </code>that can be used to create and destroy instances of
+     * {@link FilamentAsset}.
+     *
+     * @param engine the engine that the loader should pass to builder objects
+     * @param generator specifies if materials should be generated or loaded from a pre-built set
+     * @param entities the EntityManager that should be used to create entities
+     */
     public AssetLoader(@NonNull Engine engine, @NonNull MaterialProvider generator,
             @NonNull EntityManager entities) {
         try {
@@ -75,27 +124,40 @@ public class AssetLoader {
         }
     }
 
+    /**
+     * Frees all memory consumed by the native <code>AssetLoader</code> and its material cache.
+     */
     public void destroy() {
         nDestroyAssetLoader(mNativeObject);
         mNativeObject = 0;
     }
 
+    /**
+     * Creates a {@link FilamentAsset} from the contents of a GLB file.
+     */
     @Nullable
     public FilamentAsset createAssetFromBinary(@NonNull Buffer buffer) {
         long nativeAsset = nCreateAssetFromBinary(mNativeObject, buffer, buffer.remaining());
         return new FilamentAsset(nativeAsset);
     }
 
+    /**
+     * Allows clients to enable diagnostic shading on newly-loaded assets.
+     */
     public void enableDiagnostics(boolean enable) {
         nEnableDiagnostics(mNativeObject, enable);
     }
 
+    /**
+     * Frees all memory associated with the given {@link FilamentAsset}.
+     */
     public void destroyAsset(@Nullable FilamentAsset asset) {
         nDestroyAsset(mNativeObject, asset.getNativeObject());
         asset.clearNativeObject();
     }
 
-    private static native long nCreateAssetLoader(long nativeEngine, long nativeGenerator, long nativeEntities);
+    private static native long nCreateAssetLoader(long nativeEngine, long nativeGenerator,
+            long nativeEntities);
     private static native void nDestroyAssetLoader(long nativeLoader);
     private static native long nCreateAssetFromBinary(long nativeLoader, Buffer buffer, int remaining);
     private static native void nEnableDiagnostics(long nativeLoader, boolean enable);

android/gltfio-android/src/main/java/com/google/android/filament/gltfio/FilamentAsset.java

@@ -21,6 +21,27 @@ import android.support.annotation.NonNull;
 import com.google.android.filament.Box;
 import com.google.android.filament.Entity;
 
+/**
+ * Owns a bundle of Filament objects that have been created by <code>AssetLoader</code>.
+ *
+ * <p>For usage instructions, see the documentation for {@link AssetLoader}.</p>
+ *
+ * <p>This class owns a hierarchy of entities that have been loaded from a glTF asset. Every entity has
+ * a <code>TransformManager</code> component, and some entities also have
+ * <code>NameComponentManager</code> and/or <code>RenderableManager</code> components.</p>
+ *
+ * <p>In addition to the aforementioned entities, an asset has strong ownership over a list of
+ * <code>VertexBuffer</code>, <code>IndexBuffer</code>, <code>MaterialInstance</code>, and
+ * <code>Texture</code>.</p>
+ *
+ * <p>Clients can use {@link ResourceLoader} to create textures, compute tangent quaternions, and
+ * upload data into vertex buffers and index buffers.</p>
+ *
+ * <p>TODO: <code>Animator</code> is not yet exposed to Java / Kotlin clients.</p>
+ *
+ * @see ResourceLoader
+ * @see AssetLoader
+ */
 public class FilamentAsset {
     private long mNativeObject;
 
@@ -32,22 +53,37 @@ public class FilamentAsset {
         return mNativeObject;
     }
 
+    /**
+     * Gets the transform root for the asset, which has no matching glTF node.
+     */
     public @Entity int getRoot() {
         return nGetRoot(mNativeObject);
     }
 
+    /**
+     * Gets the list of entities, one for each glTF node.
+     *
+     * <p>All of these have a transform component. Some of the returned entities may also have a
+     * renderable component.</p>
+     */
     public @Entity int[] getEntities() {
         int[] result = new int[nGetEntityCount(mNativeObject)];
         nGetEntities(mNativeObject, result);
         return result;
     }
 
+    /**
+     * Gets the bounding box computed from the supplied min / max values in glTF accessors.
+     */
     public @NonNull Box getBoundingBox() {
         float[] box = new float[6];
         nGetBoundingBox(mNativeObject, box);
         return new Box(box[0], box[1], box[2], box[3], box[4], box[5]);
     }
 
+    /**
+     * Gets the <code>NameComponentManager<?code> label for the given entity, if it exists.
+     */
     public String getName(@Entity int entity) {
         return nGetName(getNativeObject(), entity);
     }

android/gltfio-android/src/main/java/com/google/android/filament/gltfio/KtxLoader.java

@@ -26,12 +26,26 @@ import com.google.android.filament.Texture;
 
 import java.nio.Buffer;
 
+/**
+ * Utilities for consuming KTX files and producing Filament textures, IBLs, and sky boxes.
+ *
+ * <p>KTX is a simple container format that makes it easy to bundle miplevels and cubemap faces
+ * into a single file.</p>
+ */
 public class KtxLoader {
 
     public static class Options {
         public boolean srgb;
     }
 
+    /**
+     * Consumes the content of a KTX file and produces a {@link Texture} object.
+     *
+     * @param engine Gets passed to the builder.
+     * @param buffer The content of the KTX File.
+     * @param options Loader options.
+     * @return The resulting Filament texture, or null on failure.
+     */
     @Nullable
     public static Texture createTexture(@NonNull Engine engine, @NonNull Buffer buffer, @NonNull Options options) {
         try {
@@ -43,6 +57,14 @@ public class KtxLoader {
         }
     }
 
+    /**
+     * Consumes the content of a KTX file and produces an {@link IndirectLight} object.
+     *
+     * @param engine Gets passed to the builder.
+     * @param buffer The content of the KTX File.
+     * @param options Loader options.
+     * @return The resulting Filament texture, or null on failure.
+     */
     @Nullable
     public static IndirectLight createIndirectLight(@NonNull Engine engine, @NonNull Buffer buffer, @NonNull Options options) {
         try {
@@ -54,6 +76,14 @@ public class KtxLoader {
         }
     }
 
+    /**
+     * Consumes the content of a KTX file and produces a {@link Skybox} object.
+     *
+     * @param engine Gets passed to the builder.
+     * @param buffer The content of the KTX File.
+     * @param options Loader options.
+     * @return The resulting Filament texture, or null on failure.
+     */
     @Nullable
     public static Skybox createSkybox(@NonNull Engine engine, @NonNull Buffer buffer, @NonNull Options options) {
         try {

android/gltfio-android/src/main/java/com/google/android/filament/gltfio/MaterialProvider.java

@@ -20,6 +20,12 @@ import com.google.android.filament.Engine;
 
 import java.lang.reflect.Method;
 
+/**
+ * Loads pre-generated ubershader materials that fulfill glTF requirements.
+ *
+ * <p>This class is used by {@link AssetLoader} to create Filament materials.
+ * Client applications do not need to call methods on it.</p>
+ */
 public class MaterialProvider {
     private long mNativeObject;
 
@@ -34,6 +40,11 @@ public class MaterialProvider {
         }
     }
 
+    /**
+     * Constructs an ubershader loader using the supplied {@link Engine}.
+     *
+     * @param engine the engine used to create materials
+     */
     public MaterialProvider(Engine engine) {
         try {
             long nativeEngine = (long) sEngineGetNativeObject.invoke(engine);
@@ -43,6 +54,9 @@ public class MaterialProvider {
         }
     }
 
+    /**
+     * Frees memory associated with the native material provider.
+     * */
     public void destroy() {
         nDestroyMaterialProvider(mNativeObject);
         mNativeObject = 0;

android/gltfio-android/src/main/java/com/google/android/filament/gltfio/ResourceLoader.java

@@ -25,6 +25,14 @@ import java.lang.reflect.InvocationTargetException;
 import java.lang.reflect.Method;
 import java.nio.Buffer;
 
+/**
+ * Uploads vertex buffers and textures to the GPU and computes tangents.
+ *
+ * <p>For a usage example, see the documentation for {@link AssetLoader}.</p>
+ *
+ * @see AssetLoader
+ * @see FilamentAsset
+ */
 public class ResourceLoader {
     private final long mNativeObject;
 
@@ -39,21 +47,55 @@ public class ResourceLoader {
         }
     }
 
+    /**
+     * Constructs a resource loader tied to the given Filament engine.
+     *
+     * @param engine the engine that gets passed to all builder methods
+     * @throws IllegalAccessException
+     * @throws InvocationTargetException
+     */
     public ResourceLoader(@NonNull Engine engine) throws IllegalAccessException, InvocationTargetException {
         long nativeEngine = (long) sEngineGetNativeObject.invoke(engine);
         mNativeObject = nCreateResourceLoader(nativeEngine);
     }
 
+    /**
+     * Frees all memory associated with the native resource loader.
+     */
     public void destroy() {
         nDestroyResourceLoader(mNativeObject);
     }
 
+    /**
+     * Feeds the binary content of an external resource into the loader's URI cache.
+     *
+     * <p><code>ResourceLoader</code> does not know how to download external resources on its own
+     * (for example, external resources might come from a filesystem, a database, or the internet)
+     * so this method allows clients to download external resources and push them to the loader.</p>
+     *
+     * <p>When loading GLB files (as opposed to JSON-based glTF files), clients typically do not
+     * need to call this method.</p>
+     *
+     * @param uri the string path that matches an image URI or buffer URI in the glTF
+     * @param buffer the binary blob corresponding to the given URI
+     * @return self (for daisy chaining)
+     */
     @NonNull
-    public ResourceLoader addResourceData(@NonNull String url, @NonNull Buffer buffer) {
-        nAddResourceData(mNativeObject, url, buffer, buffer.remaining());
+    public ResourceLoader addResourceData(@NonNull String uri, @NonNull Buffer buffer) {
+        nAddResourceData(mNativeObject, uri, buffer, buffer.remaining());
         return this;
     }
 
+    /**
+     * Iterates through all external buffers and images and creates corresponding Filament objects
+     * (vertex buffers, textures, etc), which become owned by the asset.
+     *
+     * <p>This is the main entry point for <code>ResourceLoader</code>, and only needs to be called
+     * once.</p>
+     *
+     * @param asset the Filament asset that contains URI-based resources
+     * @return self (for daisy chaining)
+     */
     @NonNull
     public ResourceLoader loadResources(@NonNull FilamentAsset asset) {
         nLoadResources(mNativeObject, asset.getNativeObject());

android/samples/gltf-bloom/app/build.gradle

@@ -17,31 +17,29 @@ task copyMesh(type: Copy) {
     into file("src/main/assets/models")
 }
 
-task copySky(type: Copy) {
-    from file("../../../../samples/envs/venetian_crossroads/venetian_crossroads_ibl.ktx")
-    into file("src/main/assets/envs")
-}
+generateIbl {
+    group 'Filament'
+    description 'Generate IBL'
 
-task copyIbl(type: Copy) {
-    from file("../../../../samples/envs/venetian_crossroads/venetian_crossroads_skybox.ktx")
-    into file("src/main/assets/envs")
+    cmgenArgs = "--format=ktx --size=256 --extract-blur=0.1 --deploy=src/main/assets/envs"
+    inputFile = file("../../../../third_party/environments/venetian_crossroads_2k.hdr")
+    outputDir = file("src/main/assets/envs")
 }
 
 preBuild.dependsOn compileMaterials
 preBuild.dependsOn copyMesh
-preBuild.dependsOn copySky
-preBuild.dependsOn copyIbl
+preBuild.dependsOn generateIbl
 
 clean.doFirst {
     delete "src/main/assets"
 }
 
 android {
-    compileSdkVersion 28
+    compileSdkVersion 29
     defaultConfig {
         applicationId "com.google.android.filament.gltf"
-        minSdkVersion 26
-        targetSdkVersion 28
+        minSdkVersion 19
+        targetSdkVersion 29
         versionCode 1
         versionName "1.0"
     }

android/samples/gltf-bloom/app/src/main/java/com/google/android/filament/gltf/MainActivity.kt

@@ -155,12 +155,14 @@ class MainActivity : Activity() {
         // IndirectLight and SkyBox
         // ------------------------
 
-        readUncompressedAsset("envs/venetian_crossroads_ibl.ktx").let {
+        val ibl = "venetian_crossroads_2k";
+
+        readUncompressedAsset("envs/$ibl/${ibl}_ibl.ktx").let {
             primary.scene.indirectLight = KtxLoader.createIndirectLight(engine, it, KtxLoader.Options())
             primary.scene.indirectLight!!.intensity = 50_000.0f
         }
 
-        readUncompressedAsset("envs/venetian_crossroads_skybox.ktx").let {
+        readUncompressedAsset("envs/$ibl/${ibl}_skybox.ktx").let {
             primary.scene.skybox = KtxLoader.createSkybox(engine, it, KtxLoader.Options())
         }
 
@@ -424,12 +426,17 @@ class MainActivity : Activity() {
 
     override fun onDestroy() {
         super.onDestroy()
+
+        // Stop the animation and any pending frame
+        choreographer.removeFrameCallback(frameScheduler)
+        animator.cancel();
+
         // Always detach the surface before destroying the engine
         uiHelper.detach()
 
         // This ensures that all the commands we've sent to Filament have
         // been processed before we attempt to destroy anything
-        Fence.waitAndDestroy(engine.createFence(Fence.Type.SOFT), Fence.Mode.FLUSH)
+        engine.flushAndWait()
 
         assetLoader.destroyAsset(filamentAsset)
         assetLoader.destroy()

android/samples/gltf-bloom/build.gradle

@@ -7,7 +7,7 @@ buildscript {
         jcenter()
     }
     dependencies {
-        classpath 'com.android.tools.build:gradle:3.4.1'
+        classpath 'com.android.tools.build:gradle:3.5.0'
         classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
 
         // NOTE: Do not place your application dependencies here; they belong

android/samples/gltf-bloom/gradle/wrapper/gradle-wrapper.properties

@@ -3,4 +3,4 @@ distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-5.1.1-all.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-5.4.1-all.zip

android/samples/hello-triangle/app/build.gradle

@@ -19,11 +19,11 @@ clean.doFirst {
 }
 
 android {
-    compileSdkVersion 28
+    compileSdkVersion 29
     defaultConfig {
         applicationId "com.google.android.filament.hellotriangle"
-        minSdkVersion 21
-        targetSdkVersion 28
+        minSdkVersion 19
+        targetSdkVersion 29
         versionCode 1
         versionName "1.0"
     }

android/samples/hello-triangle/app/src/main/java/com/google/android/filament/hellotriangle/MainActivity.kt

@@ -253,12 +253,17 @@ class MainActivity : Activity() {
 
     override fun onDestroy() {
         super.onDestroy()
+
+        // Stop the animation and any pending frame
+        choreographer.removeFrameCallback(frameScheduler)
+        animator.cancel();
+
         // Always detach the surface before destroying the engine
         uiHelper.detach()
 
         // This ensures that all the commands we've sent to Filament have
         // been processed before we attempt to destroy anything
-        Fence.waitAndDestroy(engine.createFence(Fence.Type.SOFT), Fence.Mode.FLUSH)
+        engine.flushAndWait()
 
         // Cleanup all resources
         engine.destroyEntity(renderable)

android/samples/hello-triangle/build.gradle

@@ -1,13 +1,13 @@
 // Top-level build file where you can add configuration options common to all sub-projects/modules.
 
 buildscript {
-    ext.kotlin_version = '1.3.31'
+    ext.kotlin_version = '1.3.50'
     repositories {
         google()
         jcenter()
     }
     dependencies {
-        classpath 'com.android.tools.build:gradle:3.4.1'
+        classpath 'com.android.tools.build:gradle:3.5.0'
         classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
 
         // NOTE: Do not place your application dependencies here; they belong

android/samples/hello-triangle/gradle/wrapper/gradle-wrapper.properties

@@ -3,4 +3,4 @@ distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-5.1.1-all.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-5.4.1-all.zip

android/samples/image-based-lighting/app/build.gradle

@@ -24,7 +24,7 @@ generateIbl {
     group 'Filament'
     description 'Generate IBL'
 
-    inputFile = file("../../../../third_party/environments/flower_road_2k.hdr")
+    inputFile = file("../../../../third_party/environments/flower_road_no_sun_2k.hdr")
     outputDir = file("src/main/assets/envs")
 }
 
@@ -37,11 +37,11 @@ clean.doFirst {
 }
 
 android {
-    compileSdkVersion 28
+    compileSdkVersion 29
     defaultConfig {
         applicationId "com.google.android.filament.ibl"
-        minSdkVersion 21
-        targetSdkVersion 28
+        minSdkVersion 19
+        targetSdkVersion 29
         versionCode 1
         versionName "1.0"
     }

android/samples/image-based-lighting/app/src/main/java/com/google/android/filament/ibl/MainActivity.kt

@@ -199,7 +199,7 @@ class MainActivity : Activity() {
     }
 
     private fun loadImageBasedLight() {
-        ibl = loadIbl(assets, "envs/flower_road_2k", engine)
+        ibl = loadIbl(assets, "envs/flower_road_no_sun_2k", engine)
         ibl.indirectLight.intensity = 40_000.0f
     }
 
@@ -230,12 +230,17 @@ class MainActivity : Activity() {
 
     override fun onDestroy() {
         super.onDestroy()
+
+        // Stop the animation and any pending frame
+        choreographer.removeFrameCallback(frameScheduler)
+        animator.cancel();
+
         // Always detach the surface before destroying the engine
         uiHelper.detach()
 
         // This ensures that all the commands we've sent to Filament have
         // been processed before we attempt to destroy anything
-        Fence.waitAndDestroy(engine.createFence(Fence.Type.SOFT), Fence.Mode.FLUSH)
+        engine.flushAndWait()
 
         // Cleanup all resources
         destroyMesh(engine, mesh)

android/samples/image-based-lighting/build.gradle

@@ -1,13 +1,13 @@
 // Top-level build file where you can add configuration options common to all sub-projects/modules.
 
 buildscript {
-    ext.kotlin_version = '1.3.31'
+    ext.kotlin_version = '1.3.50'
     repositories {
         google()
         jcenter()
     }
     dependencies {
-        classpath 'com.android.tools.build:gradle:3.4.1'
+        classpath 'com.android.tools.build:gradle:3.5.0'
         classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
 
         // NOTE: Do not place your application dependencies here; they belong

android/samples/image-based-lighting/gradle/wrapper/gradle-wrapper.properties

@@ -1,6 +1,6 @@
-#Mon Jan 14 11:08:47 PST 2019
+#Fri Aug 23 11:38:34 PDT 2019
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-5.1.1-all.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-5.4.1-all.zip

android/samples/lit-cube/app/build.gradle

@@ -19,11 +19,11 @@ clean.doFirst {
 }
 
 android {
-    compileSdkVersion 28
+    compileSdkVersion 29
     defaultConfig {
         applicationId "com.google.android.filament.litcube"
-        minSdkVersion 21
-        targetSdkVersion 28
+        minSdkVersion 19
+        targetSdkVersion 29
         versionCode 1
         versionName "1.0"
     }

android/samples/lit-cube/app/src/main/java/com/google/android/filament/litcube/MainActivity.kt

@@ -261,10 +261,10 @@ class MainActivity : Activity() {
                 .put(Vertex(-1.0f,  1.0f, -1.0f, tfNX))
                 .put(Vertex(-1.0f, -1.0f, -1.0f, tfNX))
                 // Face -Y
-                .put(Vertex(-1.0f, -1.0f, -1.0f, tfNY))
                 .put(Vertex(-1.0f, -1.0f,  1.0f, tfNY))
-                .put(Vertex( 1.0f, -1.0f,  1.0f, tfNY))
+                .put(Vertex(-1.0f, -1.0f, -1.0f, tfNY))
                 .put(Vertex( 1.0f, -1.0f, -1.0f, tfNY))
+                .put(Vertex( 1.0f, -1.0f,  1.0f, tfNY))
                 // Face +Y
                 .put(Vertex(-1.0f,  1.0f, -1.0f, tfPY))
                 .put(Vertex(-1.0f,  1.0f,  1.0f, tfPY))
@@ -338,12 +338,17 @@ class MainActivity : Activity() {
 
     override fun onDestroy() {
         super.onDestroy()
+
+        // Stop the animation and any pending frame
+        choreographer.removeFrameCallback(frameScheduler)
+        animator.cancel();
+
         // Always detach the surface before destroying the engine
         uiHelper.detach()
 
         // This ensures that all the commands we've sent to Filament have
         // been processed before we attempt to destroy anything
-        Fence.waitAndDestroy(engine.createFence(Fence.Type.SOFT), Fence.Mode.FLUSH)
+        engine.flushAndWait()
 
         // Cleanup all resources
         engine.destroyEntity(light)

android/samples/lit-cube/build.gradle

@@ -1,13 +1,13 @@
 // Top-level build file where you can add configuration options common to all sub-projects/modules.
 
 buildscript {
-    ext.kotlin_version = '1.3.31'
+    ext.kotlin_version = '1.3.50'
     repositories {
         google()
         jcenter()
     }
     dependencies {
-        classpath 'com.android.tools.build:gradle:3.4.1'
+        classpath 'com.android.tools.build:gradle:3.5.0'
         classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
 
         // NOTE: Do not place your application dependencies here; they belong

android/samples/lit-cube/gradle/wrapper/gradle-wrapper.properties

@@ -3,4 +3,4 @@ distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-5.1.1-all.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-5.4.1-all.zip

android/samples/material-builder/app/build.gradle

@@ -16,7 +16,7 @@ generateIbl {
     group 'Filament'
     description 'Generate IBL'
 
-    inputFile = file("../../../../third_party/environments/flower_road_2k.hdr")
+    inputFile = file("../../../../third_party/environments/flower_road_no_sun_2k.hdr")
     outputDir = file("src/main/assets/envs")
 }
 
@@ -24,11 +24,11 @@ preBuild.dependsOn compileMesh
 preBuild.dependsOn generateIbl
 
 android {
-    compileSdkVersion 28
+    compileSdkVersion 29
     defaultConfig {
         applicationId "com.google.android.filament.material_builder"
-        minSdkVersion 21
-        targetSdkVersion 28
+        minSdkVersion 19
+        targetSdkVersion 29
         versionCode 1
         versionName "1.0"
     }

android/samples/material-builder/app/src/main/java/com/google/android/filament/material_builder/MainActivity.kt

@@ -235,7 +235,7 @@ class MainActivity : Activity() {
     }
 
     private fun loadImageBasedLight() {
-        ibl = loadIbl(assets, "envs/flower_road_2k", engine)
+        ibl = loadIbl(assets, "envs/flower_road_no_sun_2k", engine)
         ibl.indirectLight.intensity = 40_000.0f
     }
 
@@ -266,12 +266,17 @@ class MainActivity : Activity() {
 
     override fun onDestroy() {
         super.onDestroy()
+
+        // Stop the animation and any pending frame
+        choreographer.removeFrameCallback(frameScheduler)
+        animator.cancel();
+
         // Always detach the surface before destroying the engine
         uiHelper.detach()
 
         // This ensures that all the commands we've sent to Filament have
         // been processed before we attempt to destroy anything
-        Fence.waitAndDestroy(engine.createFence(Fence.Type.SOFT), Fence.Mode.FLUSH)
+        engine.flushAndWait()
 
         // Cleanup all resources
         destroyMesh(engine, mesh)

android/samples/material-builder/build.gradle

@@ -1,13 +1,13 @@
 // Top-level build file where you can add configuration options common to all sub-projects/modules.
 
 buildscript {
-    ext.kotlin_version = '1.3.31'
+    ext.kotlin_version = '1.3.50'
     repositories {
         google()
         jcenter()
     }
     dependencies {
-        classpath 'com.android.tools.build:gradle:3.4.1'
+        classpath 'com.android.tools.build:gradle:3.5.0'
         classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
 
         // NOTE: Do not place your application dependencies here; they belong

android/samples/material-builder/gradle/wrapper/gradle-wrapper.properties

@@ -3,4 +3,4 @@ distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-5.1.1-all.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-5.4.1-all.zip

android/samples/texture-view/app/build.gradle

@@ -19,11 +19,11 @@ clean.doFirst {
 }
 
 android {
-    compileSdkVersion 28
+    compileSdkVersion 29
     defaultConfig {
         applicationId "com.google.android.filament.textureview"
-        minSdkVersion 21
-        targetSdkVersion 28
+        minSdkVersion 19
+        targetSdkVersion 29
         versionCode 1
         versionName "1.0"
     }

android/samples/texture-view/app/src/main/java/com/google/android/filament/textureview/MainActivity.kt

@@ -253,12 +253,17 @@ class MainActivity : Activity() {
 
     override fun onDestroy() {
         super.onDestroy()
+
+        // Stop the animation and any pending frame
+        choreographer.removeFrameCallback(frameScheduler)
+        animator.cancel();
+
         // Always detach the surface before destroying the engine
         uiHelper.detach()
 
         // This ensures that all the commands we've sent to Filament have
         // been processed before we attempt to destroy anything
-        Fence.waitAndDestroy(engine.createFence(Fence.Type.SOFT), Fence.Mode.FLUSH)
+        engine.flushAndWait()
 
         // Cleanup all resources
         engine.destroyEntity(renderable)

android/samples/texture-view/build.gradle

@@ -1,13 +1,13 @@
 // Top-level build file where you can add configuration options common to all sub-projects/modules.
 
 buildscript {
-    ext.kotlin_version = '1.3.31'
+    ext.kotlin_version = '1.3.50'
     repositories {
         google()
         jcenter()
     }
     dependencies {
-        classpath 'com.android.tools.build:gradle:3.4.1'
+        classpath 'com.android.tools.build:gradle:3.5.0'
         classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
 
         // NOTE: Do not place your application dependencies here; they belong

android/samples/texture-view/gradle/wrapper/gradle-wrapper.properties

@@ -3,4 +3,4 @@ distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-5.1.1-all.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-5.4.1-all.zip

android/samples/textured-object/app/build.gradle

@@ -37,11 +37,11 @@ clean.doFirst {
 }
 
 android {
-    compileSdkVersion 28
+    compileSdkVersion 29
     defaultConfig {
         applicationId "com.google.android.filament.textured"
-        minSdkVersion 26
-        targetSdkVersion 28
+        minSdkVersion 19
+        targetSdkVersion 29
         versionCode 1
         versionName "1.0"
     }

android/samples/textured-object/app/src/main/java/com/google/android/filament/textured/MainActivity.kt

@@ -249,12 +249,17 @@ class MainActivity : Activity() {
 
     override fun onDestroy() {
         super.onDestroy()
+
+        // Stop the animation and any pending frame
+        choreographer.removeFrameCallback(frameScheduler)
+        animator.cancel();
+
         // Always detach the surface before destroying the engine
         uiHelper.detach()
 
         // This ensures that all the commands we've sent to Filament have
         // been processed before we attempt to destroy anything
-        Fence.waitAndDestroy(engine.createFence(Fence.Type.SOFT), Fence.Mode.FLUSH)
+        engine.flushAndWait()
 
         // Cleanup all resources
         destroyMesh(engine, mesh)

android/samples/textured-object/app/src/main/java/com/google/android/filament/textured/TextureLoader.kt

@@ -79,19 +79,20 @@ private fun internalFormat(type: TextureType) = when (type) {
 }
 
 // Not required when SKIP_BITMAP_COPY is true
-private fun format(bitmap: Bitmap) = when (bitmap.config) {
-    Bitmap.Config.ALPHA_8   -> Texture.Format.ALPHA
-    Bitmap.Config.RGB_565   -> Texture.Format.RGB
-    Bitmap.Config.ARGB_8888 -> Texture.Format.RGBA
-    Bitmap.Config.RGBA_F16  -> Texture.Format.RGBA
+// Use String representation for compatibility across API levels
+private fun format(bitmap: Bitmap) = when (bitmap.config.name) {
+    "ALPHA_8"   -> Texture.Format.ALPHA
+    "RGB_565"   -> Texture.Format.RGB
+    "ARGB_8888" -> Texture.Format.RGBA
+    "RGBA_F16"  -> Texture.Format.RGBA
     else -> throw IllegalArgumentException("Unknown bitmap configuration")
 }
 
 // Not required when SKIP_BITMAP_COPY is true
-private fun type(bitmap: Bitmap) = when (bitmap.config) {
-    Bitmap.Config.ALPHA_8   -> Texture.Type.UBYTE
-    Bitmap.Config.RGB_565   -> Texture.Type.UBYTE
-    Bitmap.Config.ARGB_8888 -> Texture.Type.UBYTE
-    Bitmap.Config.RGBA_F16  -> Texture.Type.HALF
+private fun type(bitmap: Bitmap) = when (bitmap.config.name) {
+    "ALPHA_8"   -> Texture.Type.UBYTE
+    "RGB_565"   -> Texture.Type.UBYTE
+    "ARGB_8888" -> Texture.Type.UBYTE
+    "RGBA_F16"  -> Texture.Type.HALF
     else -> throw IllegalArgumentException("Unsupported bitmap configuration")
 }

android/samples/textured-object/build.gradle

@@ -1,13 +1,13 @@
 // Top-level build file where you can add configuration options common to all sub-projects/modules.
 
 buildscript {
-    ext.kotlin_version = '1.3.31'
+    ext.kotlin_version = '1.3.50'
     repositories {
         google()
         jcenter()
     }
     dependencies {
-        classpath 'com.android.tools.build:gradle:3.4.1'
+        classpath 'com.android.tools.build:gradle:3.5.0'
         classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
 
         // NOTE: Do not place your application dependencies here; they belong

android/samples/textured-object/gradle/wrapper/gradle-wrapper.properties

@@ -1,5 +1,5 @@
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-5.1.1-bin.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-5.4.1-bin.zip
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists

android/samples/transparent-view/app/build.gradle

@@ -19,11 +19,11 @@ clean.doFirst {
 }
 
 android {
-    compileSdkVersion 28
+    compileSdkVersion 29
     defaultConfig {
         applicationId "com.google.android.filament.hellotriangle"
-        minSdkVersion 21
-        targetSdkVersion 28
+        minSdkVersion 19
+        targetSdkVersion 29
         versionCode 1
         versionName "1.0"
     }

android/samples/transparent-view/app/src/main/java/com/google/android/filament/transparentrendering/MainActivity.kt

@@ -271,12 +271,17 @@ class MainActivity : Activity() {
 
     override fun onDestroy() {
         super.onDestroy()
+
+        // Stop the animation and any pending frame
+        choreographer.removeFrameCallback(frameScheduler)
+        animator.cancel();
+
         // Always detach the surface before destroying the engine
         uiHelper.detach()
 
         // This ensures that all the commands we've sent to Filament have
         // been processed before we attempt to destroy anything
-        Fence.waitAndDestroy(engine.createFence(Fence.Type.SOFT), Fence.Mode.FLUSH)
+        engine.flushAndWait()
 
         // Cleanup all resources
         engine.destroyEntity(renderable)

android/samples/transparent-view/build.gradle

@@ -1,13 +1,13 @@
 // Top-level build file where you can add configuration options common to all sub-projects/modules.
 
 buildscript {
-    ext.kotlin_version = '1.3.31'
+    ext.kotlin_version = '1.3.50'
     repositories {
         google()
         jcenter()
     }
     dependencies {
-        classpath 'com.android.tools.build:gradle:3.4.1'
+        classpath 'com.android.tools.build:gradle:3.5.0'
         classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
 
         // NOTE: Do not place your application dependencies here; they belong

android/samples/transparent-view/gradle/wrapper/gradle-wrapper.properties

@@ -3,4 +3,4 @@ distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-5.1.1-all.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-5.4.1-all.zip

build.sh

@@ -73,7 +73,7 @@ function print_help {
 # Requirements
 CMAKE_MAJOR=3
 CMAKE_MINOR=10
-ANDROID_NDK_VERSION=19
+ANDROID_NDK_VERSION=20
 
 # Internal variables
 TARGET=release
@@ -121,8 +121,11 @@ function build_clean {
     echo "Cleaning build directories..."
     rm -Rf out
     rm -Rf android/filament-android/build android/filament-android/.externalNativeBuild
+    rm -Rf android/filament-android/build android/filament-android/.cxx
     rm -Rf android/filamat-android/build android/filamat-android/.externalNativeBuild
+    rm -Rf android/filamat-android/build android/filamat-android/.cxx
     rm -Rf android/gltfio-android/build android/gltfio-android/.externalNativeBuild
+    rm -Rf android/gltfio-android/build android/gltfio-android/.cxx
 }
 
 function build_desktop_target {
@@ -313,17 +316,15 @@ function ensure_android_build {
         exit 1
     fi
 
-    local ndk_properties="$ANDROID_HOME/ndk-bundle/source.properties"
-
-    if [[ ! -f $ndk_properties ]]; then
-        echo "Error: The Android NDK must be properly installed, exiting"
-        exit 1
-    fi
-
-    local ndk_version=`sed -En -e "s/^Pkg.Revision *= *([0-9a-f]+).+/\1/p" ${ndk_properties}`
-
-    if [[ ${ndk_version} < ${ANDROID_NDK_VERSION} ]]; then
-        echo "Error: Android NDK version ${ANDROID_NDK_VERSION} or higher must be installed, exiting"
+    local ndk_side_by_side="${ANDROID_HOME}/ndk/"
+    if [[ -d $ndk_side_by_side ]]; then
+        local ndk_version=`ls ${ndk_side_by_side} | sort -V | tail -n 1 | cut -f 1 -d "."`
+        if [[ ${ndk_version} -lt ${ANDROID_NDK_VERSION} ]]; then
+            echo "Error: Android NDK side-by-side version ${ANDROID_NDK_VERSION} or higher must be installed, exiting"
+            exit 1
+        fi
+    else
+        echo "Error: Android NDK side-by-side version ${ANDROID_NDK_VERSION} or higher must be installed, exiting"
         exit 1
     fi
 
@@ -447,8 +448,13 @@ function ensure_ios_toolchain {
     echo
     echo "iOS toolchain file does not exist."
     echo "It will automatically be downloaded from http://opensource.apple.com."
-    read -p "Continue? (y/n) " -n 1 -r
-    echo
+
+    if [[ "$KOKORO_BUILD_ID" || "$GITHUB_WORKFLOW" ]]; then
+        REPLY=y
+    else
+        read -p "Continue? (y/n) " -n 1 -r
+        echo
+    fi
 
     if [[ ! "$REPLY" =~ ^[Yy]$ ]]; then
         echo "Toolchain file must be downloaded to continue."
@@ -495,7 +501,12 @@ function build_ios_target {
             ../..
     fi
 
-    ${BUILD_COMMAND} install
+    ${BUILD_COMMAND}
+
+    if [[ "$INSTALL_COMMAND" ]]; then
+        echo "Installing ${lc_target} in out/${lc_target}/filament..."
+        ${BUILD_COMMAND} ${INSTALL_COMMAND}
+    fi
 
     if [[ -d "../ios-${lc_target}/filament" ]]; then
         if [[ "$ISSUE_ARCHIVES" == "true" ]]; then

build/android/build.sh

@@ -11,6 +11,9 @@
 set -e
 set -x
 
+NDK_VERSION="ndk;20.0.5594570"
+ANDROID_NDK_VERSION=20
+
 UNAME=`echo $(uname)`
 LC_UNAME=`echo $UNAME | tr '[:upper:]' '[:lower:]'`
 
@@ -28,8 +31,16 @@ elif [[ "$LC_UNAME" == "darwin" ]]; then
 fi
 source `dirname $0`/../common/build-common.sh
 
-yes | ${ANDROID_HOME}/tools/bin/sdkmanager --update >/dev/null && \
-    yes | ${ANDROID_HOME}/tools/bin/sdkmanager --licenses >/dev/null
+# Only update and install the NDK if necessary, as this can be slow
+ndk_side_by_side="${ANDROID_HOME}/ndk/"
+if [[ -d $ndk_side_by_side ]]; then
+    ndk_version=`ls ${ndk_side_by_side} | sort -V | tail -n 1 | cut -f 1 -d "."`
+    if [[ ${ndk_version} -lt ${ANDROID_NDK_VERSION} ]]; then
+        ${ANDROID_HOME}/tools/bin/sdkmanager "${NDK_VERSION}" > /dev/null
+    fi
+else
+    ${ANDROID_HOME}/tools/bin/sdkmanager "${NDK_VERSION}" > /dev/null
+fi
 
 pushd `dirname $0`/../.. > /dev/null
 ./build.sh -p android -c $GENERATE_ARCHIVES $BUILD_DEBUG $BUILD_RELEASE

build/android/presubmit.cfg

@@ -1,3 +0,0 @@
-# Format: //devtools/kokoro/config/proto/build.proto
-
-build_file: "filament/build/android/build.sh"

build/common/ci-common.sh

@@ -3,4 +3,10 @@
 if [[ "$KOKORO_BUILD_ID" ]]; then
     echo "Running job $KOKORO_JOB_NAME"
     TARGET=`echo "$KOKORO_JOB_NAME" | awk -F "/" '{print $NF}'`
+    CONTINUOUS_INTEGRATION=true
+fi
+
+if [[ "$GITHUB_WORKFLOW" ]]; then
+    echo "Running workflow $GITHUB_WORKFLOW (event: $GITHUB_EVENT_NAME, action: $GITHUB_ACTION)"
+    CONTINUOUS_INTEGRATION=true
 fi

build/ios/build.sh

@@ -17,6 +17,5 @@ source `dirname $0`/../common/build-common.sh
 
 pushd `dirname $0`/../.. > /dev/null
 
-# build.sh prompts the user to download Apple's iOS toolchain
-yes | ./build.sh -p ios -c $GENERATE_ARCHIVES $BUILD_DEBUG $BUILD_RELEASE
+./build.sh -p ios -c $GENERATE_ARCHIVES $BUILD_DEBUG $BUILD_RELEASE
 

build/ios/presubmit.cfg

@@ -1,3 +0,0 @@
-# Format: //devtools/kokoro/config/proto/build.proto
-
-build_file: "filament/build/ios/build.sh"

build/licenses.inc.in

@@ -0,0 +1 @@
+${CONTENT}

build/linux/ci-common.sh

@@ -2,6 +2,7 @@
 
 # version of clang we want to use
 CLANG_VERSION=7
+GITHUB_CLANG_VERSION=8
 # version of libcxx and libcxxabi we want to use
 CXX_VERSION=7.0.0
 # version of CMake to use instead of the default one
@@ -9,6 +10,31 @@ CMAKE_VERSION=3.13.4
 # version of ninja to use
 NINJA_VERSION=1.8.2
 
+# Install ninja
+wget -q https://github.com/ninja-build/ninja/releases/download/v$NINJA_VERSION/ninja-linux.zip
+unzip -q ninja-linux.zip
+export PATH="$PWD:$PATH"
+
+# Install CMake
+mkdir -p cmake
+cd cmake
+
+sudo wget https://github.com/Kitware/CMake/releases/download/v$CMAKE_VERSION/cmake-$CMAKE_VERSION-Linux-x86_64.sh
+sudo chmod +x ./cmake-$CMAKE_VERSION-Linux-x86_64.sh
+sudo ./cmake-$CMAKE_VERSION-Linux-x86_64.sh --skip-license > /dev/null
+sudo update-alternatives --install /usr/bin/cmake cmake `pwd`/bin/cmake 1000 --force
+
+cd ..
+
+# Steps for GitHub Workflows
+if [[ "$GITHUB_WORKFLOW" ]]; then
+    sudo wget -O - https://apt.llvm.org/llvm-snapshot.gpg.key | sudo apt-key add -
+    sudo apt-get install clang-$GITHUB_CLANG_VERSION libc++-$GITHUB_CLANG_VERSION-dev libc++abi-$GITHUB_CLANG_VERSION-dev
+
+    sudo update-alternatives --install /usr/bin/cc cc /usr/bin/clang-${GITHUB_CLANG_VERSION} 100
+    sudo update-alternatives --install /usr/bin/c++ c++ /usr/bin/clang++-${GITHUB_CLANG_VERSION} 100
+fi
+
 # Steps specific to our CI environment
 # CI runs on Ubuntu 14.04, we need to install clang-7.0 and the
 # appropriate libc++ ourselves
@@ -17,24 +43,17 @@ if [[ "$KOKORO_BUILD_ID" ]]; then
 
     if [[ "$FILAMENT_ANDROID_CI_BUILD" ]]; then
         # Update NDK
-        yes | $ANDROID_HOME/tools/bin/sdkmanager "ndk-bundle" > /dev/null
+        yes | ${ANDROID_HOME}/tools/bin/sdkmanager --update >/dev/null
+        yes | ${ANDROID_HOME}/tools/bin/sdkmanager --licenses >/dev/null
     fi
 
-    # Install CMake
-    mkdir -p cmake
-    cd cmake
-
-    sudo wget https://github.com/Kitware/CMake/releases/download/v$CMAKE_VERSION/cmake-$CMAKE_VERSION-Linux-x86_64.sh
-    sudo chmod +x ./cmake-$CMAKE_VERSION-Linux-x86_64.sh
-    sudo ./cmake-$CMAKE_VERSION-Linux-x86_64.sh --skip-license > /dev/null
-    sudo update-alternatives --install /usr/bin/cmake cmake `pwd`/bin/cmake 1000 --force
-
-    cd ..
-
     # Install clang
     # This may or may not be needed...
     # sudo apt-key adv --keyserver apt.llvm.org --recv-keys 15CF4D18AF4F7421
     sudo apt-add-repository "deb http://apt.llvm.org/trusty/ llvm-toolchain-trusty-$CLANG_VERSION main"
+    wget -O - https://apt.llvm.org/llvm-snapshot.gpg.key | sudo apt-key add -
+    sudo rm -f /etc/apt/sources.list.d/cuda.list
+    sudo rm -f /etc/apt/sources.list.d/nvidia-ml.list
     sudo apt-get update -y
     sudo apt-get --assume-yes --force-yes install clang-$CLANG_VERSION
 
@@ -94,7 +113,3 @@ if [[ "$KOKORO_BUILD_ID" ]]; then
     export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH
     export LIBRARY_PATH=/usr/local/lib:$LIBRARY_PATH
 fi
-
-wget -q https://github.com/ninja-build/ninja/releases/download/v$NINJA_VERSION/ninja-linux.zip
-unzip -q ninja-linux.zip
-export PATH="$PWD:$PATH"

build/linux/presubmit.cfg

@@ -1,3 +0,0 @@
-# Format: //devtools/kokoro/config/proto/build.proto
-
-build_file: "filament/build/linux/build.sh"

build/mac/presubmit.cfg

@@ -1,3 +0,0 @@
-# Format: //devtools/kokoro/config/proto/build.proto
-
-build_file: "filament/build/mac/build.sh"

build/toolchain-aarch64-linux-android.cmake

@@ -30,7 +30,12 @@ set(DIST_ARCH arm64-v8a)
 # toolchain
 string(TOLOWER ${CMAKE_HOST_SYSTEM_NAME} HOST_NAME_L)
 file(TO_CMAKE_PATH $ENV{ANDROID_HOME} ANDROID_HOME_UNIX)
-set(TOOLCHAIN ${ANDROID_HOME_UNIX}/ndk-bundle/toolchains/llvm/prebuilt/${HOST_NAME_L}-x86_64)
+
+file(GLOB NDK_VERSIONS LIST_DIRECTORIES true ${ANDROID_HOME_UNIX}/ndk/*)
+list(SORT NDK_VERSIONS)
+list(GET NDK_VERSIONS -1 NDK_VERSION)
+get_filename_component(NDK_VERSION ${NDK_VERSION} NAME)
+set(TOOLCHAIN ${ANDROID_HOME_UNIX}/ndk/${NDK_VERSION}/toolchains/llvm/prebuilt/${HOST_NAME_L}-x86_64)
 
 # specify the cross compiler
 set(COMPILER_SUFFIX)

build/toolchain-arm7-linux-android.cmake

@@ -21,7 +21,7 @@ set(CMAKE_SYSTEM_NAME Linux)
 set(CMAKE_SYSTEM_VERSION 1)
 
 # android
-set(API_LEVEL 21)
+set(API_LEVEL 19)
 
 # architecture
 set(ARCH armv7a-linux-androideabi)
@@ -31,7 +31,12 @@ set(DIST_ARCH armeabi-v7a)
 # toolchain
 string(TOLOWER ${CMAKE_HOST_SYSTEM_NAME} HOST_NAME_L)
 file(TO_CMAKE_PATH $ENV{ANDROID_HOME} ANDROID_HOME_UNIX)
-set(TOOLCHAIN ${ANDROID_HOME_UNIX}/ndk-bundle/toolchains/llvm/prebuilt/${HOST_NAME_L}-x86_64/)
+
+file(GLOB NDK_VERSIONS LIST_DIRECTORIES true ${ANDROID_HOME_UNIX}/ndk/*)
+list(SORT NDK_VERSIONS)
+list(GET NDK_VERSIONS -1 NDK_VERSION)
+get_filename_component(NDK_VERSION ${NDK_VERSION} NAME)
+set(TOOLCHAIN ${ANDROID_HOME_UNIX}/ndk/${NDK_VERSION}/toolchains/llvm/prebuilt/${HOST_NAME_L}-x86_64)
 
 # specify the cross compiler
 set(COMPILER_SUFFIX)

build/toolchain-x86-linux-android.cmake

@@ -21,7 +21,7 @@ set(CMAKE_SYSTEM_NAME Linux)
 set(CMAKE_SYSTEM_VERSION 1)
 
 # android
-set(API_LEVEL 21)
+set(API_LEVEL 19)
 
 # architecture
 set(ARCH i686-linux-android)
@@ -30,7 +30,12 @@ set(DIST_ARCH x86)
 # toolchain
 string(TOLOWER ${CMAKE_HOST_SYSTEM_NAME} HOST_NAME_L)
 file(TO_CMAKE_PATH $ENV{ANDROID_HOME} ANDROID_HOME_UNIX)
-set(TOOLCHAIN ${ANDROID_HOME_UNIX}/ndk-bundle/toolchains/llvm/prebuilt/${HOST_NAME_L}-x86_64/)
+
+file(GLOB NDK_VERSIONS LIST_DIRECTORIES true ${ANDROID_HOME_UNIX}/ndk/*)
+list(SORT NDK_VERSIONS)
+list(GET NDK_VERSIONS -1 NDK_VERSION)
+get_filename_component(NDK_VERSION ${NDK_VERSION} NAME)
+set(TOOLCHAIN ${ANDROID_HOME_UNIX}/ndk/${NDK_VERSION}/toolchains/llvm/prebuilt/${HOST_NAME_L}-x86_64)
 
 # specify the cross compiler
 set(COMPILER_SUFFIX)

build/toolchain-x86_64-linux-android.cmake

@@ -30,7 +30,12 @@ set(DIST_ARCH x86_64)
 # toolchain
 string(TOLOWER ${CMAKE_HOST_SYSTEM_NAME} HOST_NAME_L)
 file(TO_CMAKE_PATH $ENV{ANDROID_HOME} ANDROID_HOME_UNIX)
-set(TOOLCHAIN ${ANDROID_HOME_UNIX}/ndk-bundle/toolchains/llvm/prebuilt/${HOST_NAME_L}-x86_64/)
+
+file(GLOB NDK_VERSIONS LIST_DIRECTORIES true ${ANDROID_HOME_UNIX}/ndk/*)
+list(SORT NDK_VERSIONS)
+list(GET NDK_VERSIONS -1 NDK_VERSION)
+get_filename_component(NDK_VERSION ${NDK_VERSION} NAME)
+set(TOOLCHAIN ${ANDROID_HOME_UNIX}/ndk/${NDK_VERSION}/toolchains/llvm/prebuilt/${HOST_NAME_L}-x86_64)
 
 # specify the cross compiler
 set(COMPILER_SUFFIX)

build/web/presubmit.cfg

@@ -1,3 +0,0 @@
-# Format: //devtools/kokoro/config/proto/build.proto
-
-build_file: "filament/build/web/build.sh"

docs/Filament.html

@@ -1415,12 +1415,12 @@ Because we must take into account the loss of energy caused by the addition of t
 </p><p>
 
 $$\begin{equation}
-f(v,l)=\fDiffuse(n,l) (1 - F_c) + \fSpecular(n,l) (1 - F_c)^2 + f_c(n,l)
+f(v,l)=\fDiffuse(n,l) (1 - F_c) + \fSpecular(n,l) (1 - F_c) + f_c(n,l)
 \end{equation}$$
 
 </p><p>
 
-Where \(F_c\) is the Fresnel term of the clear coat BRDF and \(f_c\) the clear coat BRDF. The multiplication by \((1 - F_c)^2\) of the specular component is to remain energy conservative as the light enters and exists the clear coat layer. The multiplication by \(1 - F_c\) of the diffuse component is an attempt at energy conservation.
+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">&#xA0;</a><a class="target" name="materialsystem/clearcoatmodel/clearcoatparameterization">&#xA0;</a><a class="target" name="toc4.9.3">&#xA0;</a><h3>Clear coat parameterization</h3>
@@ -1439,7 +1439,7 @@ The clear coat material model encompasses all the parameters previously defined
 
 <p></p><p>
 
-The clear coat roughness parameter is remapped and clamped in a similar way to the roughness parameter of the standard material. The main difference is that we want to lower the clear coat roughness range from [0..1] to the smaller [0..0.6] range. This remapping is arbitrary but matches the fact that clear coat layers are almost always glossy. The remapped value is squared to produce a perceptually linear roughness value.
+The clear coat roughness parameter is remapped and clamped in a similar way to the roughness parameter of the standard material.
 
 </p><p>
 
@@ -1461,7 +1461,7 @@ The clear coat roughness parameter is remapped and clamped in a similar way to t
 <span class="line">    <span class="hljs-comment">// compute Fd and Fr from standard model</span></span>
 <span class="line"></span>
 <span class="line">    <span class="hljs-comment">// remapping and linearization of clear coat roughness</span></span>
-<span class="line">    clearCoatPerceptualRoughness = mix(<span class="hljs-number">0.089</span>, <span class="hljs-number">0.6</span>, clearCoatPerceptualRoughness);</span>
+<span class="line">    clearCoatPerceptualRoughness = clamp(clearCoatPerceptualRoughness, <span class="hljs-number">0.089</span>, <span class="hljs-number">1.0</span>);</span>
 <span class="line">    clearCoatRoughness = clearCoatPerceptualRoughness * clearCoatPerceptualRoughness;</span>
 <span class="line"></span>
 <span class="line">    <span class="hljs-comment">// clear coat BRDF</span></span>
@@ -3376,10 +3376,12 @@ See an example below:
 
 <a href="#listing_iblevaluation">Listing&#xA0;27</a> presents a GLSL implementation to evaluate the IBL, using the various textures described in the previous sections. 
 
-</p><pre class="listing tilde"><code><span class="line"><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="hljs-type">float</span> perceptualRoughness) {</span>
+</p><pre class="listing tilde"><code><span class="line"><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>
+<span class="line">        <span class="hljs-type">float</span> perceptualRoughness) {</span>
 <span class="line">    <span class="hljs-type">vec3</span> r = <span class="hljs-built_in">reflect</span>(n);</span>
 <span class="line">    <span class="hljs-type">vec3</span> Ld = <span class="hljs-built_in">textureCube</span>(irradianceEnvMap, r) * diffuseColor;</span>
-<span class="line">    <span class="hljs-type">vec3</span> Lld = <span class="hljs-built_in">textureCube</span>(prefilteredEnvMap, r, computeLODFromRoughness(perceptualRoughness));</span>
+<span class="line">    <span class="hljs-type">float</span> lod = computeLODFromRoughness(perceptualRoughness);</span>
+<span class="line">    <span class="hljs-type">vec3</span> Lld = <span class="hljs-built_in">textureCube</span>(prefilteredEnvMap, r, lod);</span>
 <span class="line">    <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>
 <span class="line">    <span class="hljs-type">vec3</span> Lr =  (f0 * Ldfg.x + f90 * Ldfg.y) * Lld;</span>
 <span class="line">    <span class="hljs-keyword">return</span> Ld + Lr;</span>
@@ -3405,20 +3407,6 @@ irradiance cubemap and the analytical approximation of the \(DFG\) LUT, as shown
 <span class="line">        + sphericalHarmonics[<span class="hljs-number">8</span>] * (n.x * n.x - n.y * n.y);</span>
 <span class="line">}</span>
 <span class="line"></span>
-<span class="line"><span class="hljs-comment">// <span class="hljs-doctag">NOTE:</span> this approximation is not valid if the energy compensation term</span></span>
-<span class="line"><span class="hljs-comment">// for multiscattering is applied. We use the DFG LUT solution to implement</span></span>
-<span class="line"><span class="hljs-comment">// multiscattering</span></span>
-<span class="line"><span class="hljs-type">vec2</span> prefilteredDFG(<span class="hljs-type">float</span> NoV, <span class="hljs-type">float</span> perceptualRoughness) {</span>
-<span class="line">    <span class="hljs-comment">// Karis&apos; approximation based on Lazarov&apos;s</span></span>
-<span class="line">    <span class="hljs-keyword">const</span> <span class="hljs-type">vec4</span> c0 = <span class="hljs-type">vec4</span>(<span class="hljs-number">-1.0</span>, <span class="hljs-number">-0.0275</span>, <span class="hljs-number">-0.572</span>,  <span class="hljs-number">0.022</span>);</span>
-<span class="line">    <span class="hljs-keyword">const</span> <span class="hljs-type">vec4</span> c1 = <span class="hljs-type">vec4</span>( <span class="hljs-number">1.0</span>,  <span class="hljs-number">0.0425</span>,  <span class="hljs-number">1.040</span>, <span class="hljs-number">-0.040</span>);</span>
-<span class="line">    <span class="hljs-type">vec4</span> r = roughness * c0 + c1;</span>
-<span class="line">    <span class="hljs-type">float</span> a004 = <span class="hljs-built_in">min</span>(r.x * r.x, <span class="hljs-built_in">exp2</span>(<span class="hljs-number">-9.28</span> * NoV)) * r.x + r.y;</span>
-<span class="line">    <span class="hljs-keyword">return</span> <span class="hljs-type">vec2</span>(<span class="hljs-number">-1.04</span>, <span class="hljs-number">1.04</span>) * a004 + r.zw;</span>
-<span class="line">    <span class="hljs-comment">// Zioma&apos;s approximation based on Karis</span></span>
-<span class="line">    <span class="hljs-comment">// return vec2(1.0, pow(1.0 - max(perceptualRoughness, NoV), 3.0));</span></span>
-<span class="line">}</span>
-<span class="line"></span>
 <span class="line"><span class="hljs-comment">// <span class="hljs-doctag">NOTE:</span> this is the DFG LUT implementation of the function above</span></span>
 <span class="line"><span class="hljs-type">vec2</span> prefilteredDFG_LUT(<span class="hljs-type">float</span> coord, <span class="hljs-type">float</span> NoV) {</span>
 <span class="line">    <span class="hljs-comment">// coord = sqrt(roughness), which is the mapping used by the</span></span>