new LinearAllocatorWithFallback

LinearAllocatorWithFallback is a linear allocator that can fall back
to the heap allocator. We use it for the high level command buffer to
avoid crashing when running out of memory.

FIXES=[277115740]

.github/workflows/android-continuous.yml

@@ -10,7 +10,7 @@ on:
 jobs:
   build-android:
     name: build-android
-    runs-on: macos-latest
+    runs-on: macos-14
 
     steps:
       - uses: actions/checkout@v3.3.0

.github/workflows/cocopods-deploy.yml

@@ -13,7 +13,7 @@ on:
 jobs:
   cocoapods-deploy:
     name: cocoapods-deploy
-    runs-on: macos-latest
+    runs-on: macos-14
     steps:
       - name: Check out iOS/CocoaPods directory
         uses: Bhacaz/checkout-files@49fc3050859046bf4f4873678d46099985640e89

.github/workflows/ios-continuous.yml

@@ -10,7 +10,7 @@ on:
 jobs:
   build-ios:
     name: build-ios
-    runs-on: macos-latest
+    runs-on: macos-14
 
     steps:
       - uses: actions/checkout@v3.3.0

.github/workflows/mac-continuous.yml

@@ -10,7 +10,7 @@ on:
 jobs:
   build-mac:
     name: build-mac
-    runs-on: macos-latest
+    runs-on: macos-14
 
     steps:
       - uses: actions/checkout@v3.3.0

.github/workflows/npm-deploy.yml

@@ -11,7 +11,7 @@ on:
 jobs:
   npm-deploy:
     name: npm-deploy
-    runs-on: macos-latest
+    runs-on: macos-14
     steps:
       - uses: actions/checkout@v3.3.0
         with:

.github/workflows/presubmit.yml

@@ -15,7 +15,7 @@ jobs:
 
     strategy:
       matrix:
-        os: [macos-latest, ubuntu-22.04]
+        os: [macos-14, ubuntu-22.04]
 
     steps:
       - uses: actions/checkout@v3.3.0
@@ -40,7 +40,7 @@ jobs:
 
   build-android:
     name: build-android
-    runs-on: macos-latest
+    runs-on: macos-14
 
     steps:
       - uses: actions/checkout@v3.3.0
@@ -54,7 +54,7 @@ jobs:
 
   build-ios:
     name: build-iOS
-    runs-on: macos-latest
+    runs-on: macos-14
 
     steps:
       - uses: actions/checkout@v3.3.0
@@ -67,7 +67,7 @@ jobs:
 
   build-web:
     name: build-web
-    runs-on: macos-latest
+    runs-on: macos-14
 
     steps:
       - uses: actions/checkout@v3.3.0

.github/workflows/release.yml

@@ -31,7 +31,7 @@ jobs:
 
     strategy:
       matrix:
-        os: [macos-latest, ubuntu-22.04]
+        os: [macos-14, ubuntu-22.04]
 
     steps:
       - name: Decide Git ref
@@ -65,7 +65,7 @@ jobs:
 
   build-web:
     name: build-web
-    runs-on: macos-latest
+    runs-on: macos-14
     if: github.event_name == 'release' || github.event.inputs.platform == 'web'
 
     steps:
@@ -98,7 +98,7 @@ jobs:
 
   build-android:
     name: build-android
-    runs-on: macos-latest
+    runs-on: macos-14
     if: github.event_name == 'release' || github.event.inputs.platform == 'android'
 
     steps:
@@ -152,7 +152,7 @@ jobs:
 
   build-ios:
     name: build-ios
-    runs-on: macos-latest
+    runs-on: macos-14
     if: github.event_name == 'release' || github.event.inputs.platform == 'ios'
 
     steps:

.github/workflows/web-continuous.yml

@@ -10,7 +10,7 @@ on:
 jobs:
   build-web:
     name: build-web
-    runs-on: macos-latest
+    runs-on: macos-14
 
     steps:
       - uses: actions/checkout@v3.3.0

CMakeLists.txt

@@ -634,9 +634,9 @@ function(combine_static_libs TARGET OUTPUT DEPS)
     # Loop through the dependent libraries and query their location on disk.
     set(DEPS_FILES )
     foreach(DEPENDENCY ${DEPS})
-        if(TARGET ${DEPENDENCY})
+        if (TARGET ${DEPENDENCY})
             get_property(dep_type TARGET ${DEPENDENCY} PROPERTY TYPE)
-            if(dep_type STREQUAL "STATIC_LIBRARY")
+            if (dep_type STREQUAL "STATIC_LIBRARY")
                 list(APPEND DEPS_FILES "$<TARGET_FILE:${DEPENDENCY}>")
             endif()
         endif()
@@ -706,7 +706,7 @@ function(get_resgen_vars ARCHIVE_DIR ARCHIVE_NAME)
         set(RESGEN_OUTPUTS "${OUTPUTS}" PARENT_SCOPE)
         set(RESGEN_FLAGS -qx ${ARCHIVE_DIR} -p ${ARCHIVE_NAME} PARENT_SCOPE)
         set(RESGEN_SOURCE "${ARCHIVE_DIR}/${ARCHIVE_NAME}${ASM_SUFFIX}.S" PARENT_SCOPE)
-        set(RESGEN_SOURCE_FLAGS "-I${ARCHIVE_DIR} ${ASM_ARCH_FLAG}" PARENT_SCOPE)
+        set(RESGEN_SOURCE_FLAGS "-I'${ARCHIVE_DIR}' ${ASM_ARCH_FLAG}" PARENT_SCOPE)
     endif()
 endfunction()
 
@@ -721,7 +721,6 @@ add_subdirectory(${LIBRARIES}/filabridge)
 add_subdirectory(${LIBRARIES}/filaflat)
 add_subdirectory(${LIBRARIES}/filagui)
 add_subdirectory(${LIBRARIES}/filameshio)
-add_subdirectory(${LIBRARIES}/geometry)
 add_subdirectory(${LIBRARIES}/gltfio)
 add_subdirectory(${LIBRARIES}/ibl)
 add_subdirectory(${LIBRARIES}/iblprefilter)
@@ -749,6 +748,9 @@ add_subdirectory(${EXTERNAL}/jsmn/tnt)
 add_subdirectory(${EXTERNAL}/stb/tnt)
 add_subdirectory(${EXTERNAL}/getopt)
 
+# Note that this has to be placed after mikktspace in order for combine_static_libs to work.
+add_subdirectory(${LIBRARIES}/geometry)
+
 if (FILAMENT_BUILD_FILAMAT OR IS_HOST_PLATFORM)
     # spirv-tools must come before filamat, as filamat relies on the presence of the
     # spirv-tools_SOURCE_DIR variable.

NEW_RELEASE_NOTES.md

@@ -7,5 +7,3 @@ for next branch cut* header.
 appropriate header in [RELEASE_NOTES.md](./RELEASE_NOTES.md).
 
 ## Release notes for next branch cut
-
-- utils: remove usages of `SpinLock`. Fixes b/321101014.

README.md

@@ -31,7 +31,7 @@ repositories {
 }
 
 dependencies {
-    implementation 'com.google.android.filament:filament-android:1.50.0'
+    implementation 'com.google.android.filament:filament-android:1.50.2'
 }
 ```
 
@@ -51,7 +51,7 @@ Here are all the libraries available in the group `com.google.android.filament`:
 iOS projects can use CocoaPods to install the latest release:
 
 ```shell
-pod 'Filament', '~> 1.50.0'
+pod 'Filament', '~> 1.50.2'
 ```
 
 ### Snapshots

RELEASE_NOTES.md

@@ -7,6 +7,18 @@ A new header is inserted each time a *tag* is created.
 Instead, if you are authoring a PR for the main branch, add your release note to
 [NEW_RELEASE_NOTES.md](./NEW_RELEASE_NOTES.md).
 
+## v1.50.3
+
+
+## v1.50.2
+
+
+## v1.50.1
+
+- Metal: fix some shader artifacts by disabling fast math optimizations.
+- backend: remove `atan2` overload which had a typo and wasn't useful. Fixes b/320856413.
+- utils: remove usages of `SpinLock`. Fixes b/321101014.
+
 ## v1.50.0
 - engine: TAA now supports 4x upscaling [BETA] [⚠️ **New Material Version**]
 

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

@@ -484,7 +484,8 @@ extern "C" JNIEXPORT void JNICALL Java_com_google_android_filament_Engine_nSetBu
 extern "C" JNIEXPORT void JNICALL Java_com_google_android_filament_Engine_nSetBuilderConfig(JNIEnv*,
         jclass, jlong nativeBuilder, jlong commandBufferSizeMB, jlong perRenderPassArenaSizeMB,
         jlong driverHandleArenaSizeMB, jlong minCommandBufferSizeMB, jlong perFrameCommandsSizeMB,
-        jlong jobSystemThreadCount, jlong stereoscopicEyeCount) {
+        jlong jobSystemThreadCount, jlong stereoscopicEyeCount,
+        jlong resourceAllocatorCacheSizeMB, jlong resourceAllocatorCacheMaxAge) {
     Engine::Builder* builder = (Engine::Builder*) nativeBuilder;
     Engine::Config config = {
             .commandBufferSizeMB = (uint32_t) commandBufferSizeMB,
@@ -494,6 +495,8 @@ extern "C" JNIEXPORT void JNICALL Java_com_google_android_filament_Engine_nSetBu
             .perFrameCommandsSizeMB = (uint32_t) perFrameCommandsSizeMB,
             .jobSystemThreadCount = (uint32_t) jobSystemThreadCount,
             .stereoscopicEyeCount = (uint8_t) stereoscopicEyeCount,
+            .resourceAllocatorCacheSizeMB = (uint32_t) resourceAllocatorCacheSizeMB,
+            .resourceAllocatorCacheMaxAge = (uint8_t) resourceAllocatorCacheMaxAge,
     };
     builder->config(&config);
 }

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

@@ -211,7 +211,8 @@ public class Engine {
             nSetBuilderConfig(mNativeBuilder, config.commandBufferSizeMB,
                     config.perRenderPassArenaSizeMB, config.driverHandleArenaSizeMB,
                     config.minCommandBufferSizeMB, config.perFrameCommandsSizeMB,
-                    config.jobSystemThreadCount, config.stereoscopicEyeCount);
+                    config.jobSystemThreadCount, config.stereoscopicEyeCount,
+                    config.resourceAllocatorCacheSizeMB, config.resourceAllocatorCacheMaxAge);
             return this;
         }
 
@@ -356,6 +357,18 @@ public class Engine {
          * @see Engine#getMaxStereoscopicEyes
          */
         public long stereoscopicEyeCount = 2;
+
+        /*
+         * Size in MiB of the frame graph texture cache. This should be adjusted based on the
+         * size of used render targets (typically the screen).
+         */
+        public long resourceAllocatorCacheSizeMB = 64;
+
+        /*
+         * This value determines for how many frames are texture entries kept in the cache.
+         * The default value of 30 corresponds to about half a second at 60 fps.
+         */
+        public long resourceAllocatorCacheMaxAge = 30;
     }
 
     private Engine(long nativeEngine, Config config) {
@@ -1227,7 +1240,8 @@ public class Engine {
     private static native void nSetBuilderConfig(long nativeBuilder, long commandBufferSizeMB,
             long perRenderPassArenaSizeMB, long driverHandleArenaSizeMB,
             long minCommandBufferSizeMB, long perFrameCommandsSizeMB, long jobSystemThreadCount,
-            long stereoscopicEyeCount);
+            long stereoscopicEyeCount,
+            long resourceAllocatorCacheSizeMB, long resourceAllocatorCacheMaxAge);
     private static native void nSetBuilderFeatureLevel(long nativeBuilder, int ordinal);
     private static native void nSetBuilderSharedContext(long nativeBuilder, long sharedContext);
     private static native long nBuilderBuild(long nativeBuilder);

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

@@ -1637,6 +1637,10 @@ public class View {
          * circle of confusion scale factor (amount of blur)
          */
         public float cocScale = 1.0f;
+        /**
+         * width/height aspect ratio of the circle of confusion (simulate anamorphic lenses)
+         */
+        public float cocAspectRatio = 1.0f;
         /**
          * maximum aperture diameter in meters (zero to disable rotation)
          */
@@ -1921,6 +1925,7 @@ public class View {
             UNIFORM_HELIX_X4,
             HALTON_23_X8,
             HALTON_23_X16,
+            HALTON_23_X32,
         }
 
         /**
@@ -1935,6 +1940,10 @@ public class View {
          * texturing lod bias (typically -1 or -2)
          */
         public float lodBias = -1.0f;
+        /**
+         * post-TAA sharpen, especially useful when upscaling is true.
+         */
+        public float sharpness = 0.0f;
         /**
          * enables or disables temporal anti-aliasing
          */

android/gradle.properties

@@ -1,5 +1,5 @@
 GROUP=com.google.android.filament
-VERSION_NAME=1.50.0
+VERSION_NAME=1.50.2
 
 POM_DESCRIPTION=Real-time physically based rendering engine for Android.
 

build/linux/combine-static-libs.sh

@@ -125,7 +125,13 @@ if [[ "${has_universal}" == "true" ]]; then
 
         arch_output="${OUTPUT_PATH%.a}_${arch}.a"
         arch_outputs+=("$arch_output")
-        combine_static_libs "$arch_output" $(find "$(pwd)/${archs_temp_dir}/${arch}" -iname '*.a')
+
+        archives=()
+        while IFS=  read -r -d $'\0'; do
+            archives+=("$REPLY")
+        done < <(find "$(pwd)/${archs_temp_dir}/${arch}" -iname '*.a' -print0)
+
+        combine_static_libs "$arch_output" "$archives"
     done
 
     # Finally, combine the single-architecture archives into a universal binary.

filament/CMakeLists.txt

@@ -238,6 +238,7 @@ set(MATERIAL_SRCS
         src/materials/resolveDepth.mat
         src/materials/separableGaussianBlur.mat
         src/materials/skybox.mat
+        src/materials/shadowmap.mat
         src/materials/ssao/bilateralBlur.mat
         src/materials/ssao/bilateralBlurBentNormals.mat
         src/materials/ssao/mipmapDepth.mat

filament/backend/include/backend/BufferDescriptor.h

@@ -23,7 +23,6 @@
 #include <utils/ostream.h>
 
 #include <stddef.h>
-#include <stdint.h>
 
 namespace filament::backend {
 

filament/backend/include/backend/CallbackHandler.h

@@ -17,8 +17,6 @@
 #ifndef TNT_FILAMENT_BACKEND_CALLBACKHANDLER_H
 #define TNT_FILAMENT_BACKEND_CALLBACKHANDLER_H
 
-#include <utils/compiler.h>
-
 namespace filament::backend {
 
 /**

filament/backend/include/backend/DriverEnums.h

@@ -28,7 +28,8 @@
 
 #include <math/vec4.h>
 
-#include <array>    // FIXME: STL headers are not allowed in public headers
+#include <array>        // FIXME: STL headers are not allowed in public headers
+#include <type_traits>  // FIXME: STL headers are not allowed in public headers
 
 #include <stddef.h>
 #include <stdint.h>

filament/backend/include/backend/Handle.h

@@ -17,16 +17,14 @@
 #ifndef TNT_FILAMENT_BACKEND_HANDLE_H
 #define TNT_FILAMENT_BACKEND_HANDLE_H
 
-#include <utils/compiler.h>
 #if !defined(NDEBUG)
-#include <utils/Log.h>
+#include <utils/ostream.h>
 #endif
 #include <utils/debug.h>
 
-#include <stdint.h>
+#include <type_traits> // FIXME: STL headers are not allowed in public headers
 
-#include <limits>
-#include <type_traits>
+#include <stdint.h>
 
 namespace filament::backend {
 
@@ -54,7 +52,7 @@ struct HwVertexBuffer;
 class HandleBase {
 public:
     using HandleId = uint32_t;
-    static constexpr const HandleId nullid = HandleId{ std::numeric_limits<HandleId>::max() };
+    static constexpr const HandleId nullid = HandleId{ UINT32_MAX };
 
     constexpr HandleBase() noexcept: object(nullid) {}
 

filament/backend/include/backend/PipelineState.h

@@ -20,7 +20,7 @@
 #include <backend/DriverEnums.h>
 #include <backend/Handle.h>
 
-#include <limits>
+#include <utils/ostream.h>
 
 #include <stdint.h>
 
@@ -33,10 +33,7 @@ struct PipelineState {
     RasterState rasterState;
     StencilState stencilState;
     PolygonOffset polygonOffset;
-    Viewport scissor{ 0, 0,
-                      (uint32_t)std::numeric_limits<int32_t>::max(),
-                      (uint32_t)std::numeric_limits<int32_t>::max()
-    };
+    Viewport scissor{ 0, 0, (uint32_t)INT32_MAX, (uint32_t)INT32_MAX };
 };
 
 } // namespace filament::backend

filament/backend/include/backend/PixelBufferDescriptor.h

@@ -24,6 +24,7 @@
 
 #include <utils/compiler.h>
 #include <utils/debug.h>
+#include <utils/ostream.h>
 
 #include <stddef.h>
 #include <stdint.h>

filament/backend/include/backend/Platform.h

@@ -19,11 +19,11 @@
 #ifndef TNT_FILAMENT_BACKEND_PLATFORM_H
 #define TNT_FILAMENT_BACKEND_PLATFORM_H
 
-#include <backend/DriverEnums.h>
-
 #include <utils/compiler.h>
 #include <utils/Invocable.h>
 
+#include <stddef.h>
+
 namespace filament::backend {
 
 class Driver;
@@ -41,18 +41,24 @@ public:
     struct Stream {};
 
     struct DriverConfig {
-        /*
-         * size of handle arena in bytes. Setting to 0 indicates default value is to be used.
+        /**
+         * Size of handle arena in bytes. Setting to 0 indicates default value is to be used.
          * Driver clamps to valid values.
          */
         size_t handleArenaSize = 0;
 
-        /*
-         * this number of most-recently destroyed textures will be tracked for use-after-free.
+        /**
+         * This number of most-recently destroyed textures will be tracked for use-after-free.
          * Throws an exception when a texture is freed but still bound to a SamplerGroup and used in
          * a draw call. 0 disables completely. Currently only respected by the Metal backend.
          */
         size_t textureUseAfterFreePoolSize = 0;
+
+        /**
+         * Set to `true` to forcibly disable parallel shader compilation in the backend.
+         * Currently only honored by the GL backend.
+         */
+        bool disableParallelShaderCompile = false;
     };
 
     Platform() noexcept;
@@ -78,7 +84,7 @@ public:
      *
      * @return nullptr on failure, or a pointer to the newly created driver.
      */
-    virtual backend::Driver* createDriver(void* sharedContext,
+    virtual backend::Driver* UTILS_NULLABLE createDriver(void* UTILS_NULLABLE sharedContext,
             const DriverConfig& driverConfig) noexcept = 0;
 
     /**
@@ -96,7 +102,8 @@ public:
      * cache.
      */
     using InsertBlobFunc = utils::Invocable<
-            void(const void* key, size_t keySize, const void* value, size_t valueSize)>;
+            void(const void* UTILS_NONNULL key, size_t keySize,
+                    const void* UTILS_NONNULL value, size_t valueSize)>;
 
     /*
      * RetrieveBlobFunc is an Invocable to an application-provided function that a
@@ -104,7 +111,8 @@ public:
      * cache.
      */
     using RetrieveBlobFunc = utils::Invocable<
-            size_t(const void* key, size_t keySize, void* value, size_t valueSize)>;
+            size_t(const void* UTILS_NONNULL key, size_t keySize,
+                    void* UTILS_NONNULL value, size_t valueSize)>;
 
     /**
      * Sets the callback functions that the backend can use to interact with caching functionality
@@ -157,7 +165,8 @@ public:
      * @param value         pointer to the beginning of the value data that is to be inserted
      * @param valueSize     specifies the size in byte of the data pointed to by <value>
      */
-    void insertBlob(const void* key, size_t keySize, const void* value, size_t valueSize);
+    void insertBlob(const void* UTILS_NONNULL key, size_t keySize,
+            const void* UTILS_NONNULL value, size_t valueSize);
 
     /**
      * To retrieve the binary value associated with a given key from the cache, a
@@ -176,7 +185,8 @@ public:
      * @return             If the cache contains a value associated with the given key then the
      *                     size of that binary value in bytes is returned. Otherwise 0 is returned.
      */
-    size_t retrieveBlob(const void* key, size_t keySize, void* value, size_t valueSize);
+    size_t retrieveBlob(const void* UTILS_NONNULL key, size_t keySize,
+            void* UTILS_NONNULL value, size_t valueSize);
 
 private:
     InsertBlobFunc mInsertBlob;

filament/backend/include/backend/PresentCallable.h

@@ -21,8 +21,7 @@
 
 #include <utils/compiler.h>
 
-namespace filament {
-namespace backend {
+namespace filament::backend {
 
 /**
  * A PresentCallable is a callable object that, when called, schedules a frame for presentation on
@@ -98,7 +97,6 @@ private:
  */
 using FrameFinishedCallback UTILS_DEPRECATED = void(*)(PresentCallable callable, void* user);
 
-} // namespace backend
-} // namespace filament
+} // namespace filament::backend
 
 #endif // TNT_FILAMENT_BACKEND_PRESENTCALLABLE

filament/backend/include/backend/Program.h

@@ -17,17 +17,19 @@
 #ifndef TNT_FILAMENT_BACKEND_PRIVATE_PROGRAM_H
 #define TNT_FILAMENT_BACKEND_PRIVATE_PROGRAM_H
 
-#include <utils/compiler.h>
 #include <utils/CString.h>
 #include <utils/FixedCapacityVector.h>
 #include <utils/Invocable.h>
-#include <utils/Log.h>
 #include <utils/ostream.h>
 
 #include <backend/DriverEnums.h>
 
-#include <array>
-#include <variant>
+#include <array>    // FIXME: STL headers are not allowed in public headers
+#include <utility>  // FIXME: STL headers are not allowed in public headers
+#include <variant>  // FIXME: STL headers are not allowed in public headers
+
+#include <stddef.h>
+#include <stdint.h>
 
 namespace filament::backend {
 

filament/backend/include/backend/SamplerDescriptor.h

@@ -24,9 +24,6 @@
 
 #include <utils/compiler.h>
 
-#include <stddef.h>
-#include <stdint.h>
-
 namespace filament::backend {
 
 struct UTILS_PUBLIC SamplerDescriptor {

filament/backend/include/backend/TargetBufferInfo.h

@@ -17,9 +17,11 @@
 #ifndef TNT_FILAMENT_BACKEND_TARGETBUFFERINFO_H
 #define TNT_FILAMENT_BACKEND_TARGETBUFFERINFO_H
 
-#include <backend/DriverEnums.h>
 #include <backend/Handle.h>
 
+#include <utils/ostream.h>
+
+#include <stddef.h>
 #include <stdint.h>
 
 namespace filament::backend {

filament/backend/include/backend/platforms/OpenGLPlatform.h

@@ -18,8 +18,13 @@
 #define TNT_FILAMENT_BACKEND_PRIVATE_OPENGLPLATFORM_H
 
 #include <backend/AcquiredImage.h>
+#include <backend/DriverEnums.h>
 #include <backend/Platform.h>
 
+#include <utils/compiler.h>
+
+#include <stdint.h>
+
 namespace filament::backend {
 
 class Driver;
@@ -38,8 +43,8 @@ protected:
      * Derived classes can use this to instantiate the default OpenGLDriver backend.
      * This is typically called from your implementation of createDriver()
      */
-    static Driver* createDefaultDriver(OpenGLPlatform* platform,
-            void* sharedContext, const DriverConfig& driverConfig);
+    static Driver* UTILS_NULLABLE createDefaultDriver(OpenGLPlatform* UTILS_NONNULL platform,
+            void* UTILS_NULLABLE sharedContext, const DriverConfig& driverConfig);
 
     ~OpenGLPlatform() noexcept override;
 
@@ -66,7 +71,8 @@ public:
      * @return              The driver's SwapChain object.
      *
      */
-    virtual SwapChain* createSwapChain(void* nativeWindow, uint64_t flags) noexcept = 0;
+    virtual SwapChain* UTILS_NONNULL createSwapChain(
+            void* UTILS_NULLABLE nativeWindow, uint64_t flags) noexcept = 0;
 
     /**
      * Return whether createSwapChain supports the SWAP_CHAIN_CONFIG_SRGB_COLORSPACE flag.
@@ -87,13 +93,14 @@ public:
      * TODO: we need a more generic way of passing construction parameters
      *       A void* might be enough.
      */
-    virtual SwapChain* createSwapChain(uint32_t width, uint32_t height, uint64_t flags) noexcept = 0;
+    virtual SwapChain* UTILS_NULLABLE createSwapChain(
+            uint32_t width, uint32_t height, uint64_t flags) noexcept = 0;
 
     /**
      * Called by the driver to destroys the SwapChain
      * @param swapChain SwapChain to be destroyed.
      */
-    virtual void destroySwapChain(SwapChain* swapChain) noexcept = 0;
+    virtual void destroySwapChain(SwapChain* UTILS_NONNULL swapChain) noexcept = 0;
 
     /**
      * Returns the set of buffers that must be preserved up to the call to commit().
@@ -106,7 +113,7 @@ public:
      * @return buffer that must be preserved
      * @see commit()
      */
-    virtual TargetBufferFlags getPreservedFlags(SwapChain* swapChain) noexcept;
+    virtual TargetBufferFlags getPreservedFlags(SwapChain* UTILS_NONNULL swapChain) noexcept;
 
     /**
      * Called by the driver to establish the default FBO. The default implementation returns 0.
@@ -120,14 +127,16 @@ public:
      * @param drawSwapChain SwapChain to draw to. It must be bound to the default FBO.
      * @param readSwapChain SwapChain to read from (for operation like `glBlitFramebuffer`)
      */
-    virtual void makeCurrent(SwapChain* drawSwapChain, SwapChain* readSwapChain) noexcept = 0;
+    virtual void makeCurrent(
+            SwapChain* UTILS_NONNULL drawSwapChain,
+            SwapChain* UTILS_NONNULL readSwapChain) noexcept = 0;
 
     /**
      * Called by the driver once the current frame finishes drawing. Typically, this should present
      * the drawSwapChain. This is for example where `eglMakeCurrent()` would be called.
      * @param swapChain the SwapChain to present.
      */
-    virtual void commit(SwapChain* swapChain) noexcept = 0;
+    virtual void commit(SwapChain* UTILS_NONNULL swapChain) noexcept = 0;
 
     /**
      * Set the time the next committed buffer should be presented to the user at.
@@ -152,14 +161,14 @@ public:
      *
      * @return A Fence object. The default implementation returns nullptr.
      */
-    virtual Fence* createFence() noexcept;
+    virtual Fence* UTILS_NULLABLE createFence() noexcept;
 
     /**
      * Destroys a Fence object. The default implementation does nothing.
      *
      * @param fence Fence to destroy.
      */
-    virtual void destroyFence(Fence* fence) noexcept;
+    virtual void destroyFence(Fence* UTILS_NONNULL fence) noexcept;
 
     /**
      * Waits on a Fence.
@@ -169,7 +178,7 @@ public:
      * @return Whether the fence signaled or timed out. See backend::FenceStatus.
      *         The default implementation always return backend::FenceStatus::ERROR.
      */
-    virtual backend::FenceStatus waitFence(Fence* fence, uint64_t timeout) noexcept;
+    virtual backend::FenceStatus waitFence(Fence* UTILS_NONNULL fence, uint64_t timeout) noexcept;
 
 
     // --------------------------------------------------------------------------------------------
@@ -183,13 +192,13 @@ public:
      * @param nativeStream The native stream, this parameter depends on the concrete implementation.
      * @return A new Stream object.
      */
-    virtual Stream* createStream(void* nativeStream) noexcept;
+    virtual Stream* UTILS_NULLABLE createStream(void* UTILS_NULLABLE nativeStream) noexcept;
 
     /**
      * Destroys a Stream.
      * @param stream Stream to destroy.
      */
-    virtual void destroyStream(Stream* stream) noexcept;
+    virtual void destroyStream(Stream* UTILS_NONNULL stream) noexcept;
 
     /**
      * The specified stream takes ownership of the texture (tname) object
@@ -199,20 +208,21 @@ public:
      * @param stream Stream to take ownership of the texture
      * @param tname  GL texture id to "bind" to the Stream.
      */
-    virtual void attach(Stream* stream, intptr_t tname) noexcept;
+    virtual void attach(Stream* UTILS_NONNULL stream, intptr_t tname) noexcept;
 
     /**
      * Destroys the texture associated to the stream
      * @param stream Stream to detach from its texture
      */
-    virtual void detach(Stream* stream) noexcept;
+    virtual void detach(Stream* UTILS_NONNULL stream) noexcept;
 
     /**
      * Updates the content of the texture attached to the stream.
      * @param stream Stream to update
      * @param timestamp Output parameter: Timestamp of the image bound to the texture.
      */
-    virtual void updateTexImage(Stream* stream, int64_t* timestamp) noexcept;
+    virtual void updateTexImage(Stream* UTILS_NONNULL stream,
+            int64_t* UTILS_NONNULL timestamp) noexcept;
 
 
     // --------------------------------------------------------------------------------------------
@@ -225,13 +235,13 @@ public:
      *         implementation could just return { 0, GL_TEXTURE_2D } at this point. The actual
      *         values can be delayed until setExternalImage.
      */
-    virtual ExternalTexture *createExternalImageTexture() noexcept;
+    virtual ExternalTexture* UTILS_NULLABLE createExternalImageTexture() noexcept;
 
     /**
      * Destroys an external texture handle and associated data.
      * @param texture a pointer to the handle to destroy.
      */
-    virtual void destroyExternalImage(ExternalTexture* texture) noexcept;
+    virtual void destroyExternalImage(ExternalTexture* UTILS_NONNULL texture) noexcept;
 
     // called on the application thread to allow Filament to take ownership of the image
 
@@ -244,7 +254,7 @@ public:
      * @param externalImage A token representing the platform's external image.
      * @see destroyExternalImage
      */
-    virtual void retainExternalImage(void* externalImage) noexcept;
+    virtual void retainExternalImage(void* UTILS_NONNULL externalImage) noexcept;
 
     /**
      * Called to bind the platform-specific externalImage to an ExternalTexture.
@@ -258,7 +268,8 @@ public:
      * @param texture an in/out pointer to ExternalTexture, id and target can be updated if necessary.
      * @return true on success, false on error.
      */
-    virtual bool setExternalImage(void* externalImage, ExternalTexture* texture) noexcept;
+    virtual bool setExternalImage(void* UTILS_NONNULL externalImage,
+            ExternalTexture* UTILS_NONNULL texture) noexcept;
 
     /**
      * The method allows platforms to convert a user-supplied external image object into a new type

filament/backend/include/backend/platforms/PlatformCocoaGL.h

@@ -17,11 +17,10 @@
 #ifndef TNT_FILAMENT_BACKEND_OPENGL_OPENGL_PLATFORM_COCOA_GL_H
 #define TNT_FILAMENT_BACKEND_OPENGL_OPENGL_PLATFORM_COCOA_GL_H
 
-#include <stdint.h>
-
+#include <backend/DriverEnums.h>
 #include <backend/platforms/OpenGLPlatform.h>
 
-#include <backend/DriverEnums.h>
+#include <stdint.h>
 
 namespace filament::backend {
 

filament/backend/include/backend/platforms/PlatformCocoaTouchGL.h

@@ -30,7 +30,7 @@ struct PlatformCocoaTouchGLImpl;
 class PlatformCocoaTouchGL : public OpenGLPlatform {
 public:
     PlatformCocoaTouchGL();
-    ~PlatformCocoaTouchGL() noexcept;
+    ~PlatformCocoaTouchGL() noexcept override;
 
     // --------------------------------------------------------------------------------------------
     // Platform Interface

filament/backend/include/backend/platforms/PlatformEGL.h

@@ -17,18 +17,21 @@
 #ifndef TNT_FILAMENT_BACKEND_OPENGL_OPENGL_PLATFORM_EGL_H
 #define TNT_FILAMENT_BACKEND_OPENGL_OPENGL_PLATFORM_EGL_H
 
-#include <stdint.h>
+#include <backend/DriverEnums.h>
+#include <backend/Platform.h>
+#include <backend/platforms/OpenGLPlatform.h>
 
 #include <EGL/egl.h>
 #include <EGL/eglext.h>
+#include <EGL/eglplatform.h>
 
-#include <backend/platforms/OpenGLPlatform.h>
-
-#include <backend/DriverEnums.h>
-
+#include <initializer_list>
 #include <utility>
 #include <vector>
 
+#include <stddef.h>
+#include <stdint.h>
+
 namespace filament::backend {
 
 /**

filament/backend/include/backend/platforms/PlatformEGLAndroid.h

@@ -17,8 +17,14 @@
 #ifndef TNT_FILAMENT_BACKEND_OPENGL_OPENGL_PLATFORM_EGL_ANDROID_H
 #define TNT_FILAMENT_BACKEND_OPENGL_OPENGL_PLATFORM_EGL_ANDROID_H
 
+#include <backend/AcquiredImage.h>
+#include <backend/Platform.h>
+#include <backend/platforms/OpenGLPlatform.h>
 #include <backend/platforms/PlatformEGL.h>
 
+#include <stddef.h>
+#include <stdint.h>
+
 namespace filament::backend {
 
 class ExternalStreamManagerAndroid;

filament/backend/include/backend/platforms/VulkanPlatform.h

@@ -20,13 +20,18 @@
 #include <backend/Platform.h>
 
 #include <bluevk/BlueVK.h>
+
 #include <utils/CString.h>
 #include <utils/FixedCapacityVector.h>
 #include <utils/PrivateImplementation.h>
 
+#include <string_view>
 #include <tuple>
 #include <unordered_set>
 
+#include <stddef.h>
+#include <stdint.h>
+
 namespace filament::backend {
 
 using SwapChain = Platform::SwapChain;

filament/backend/include/private/backend/CircularBuffer.h

@@ -17,7 +17,7 @@
 #ifndef TNT_FILAMENT_BACKEND_PRIVATE_CIRCULARBUFFER_H
 #define TNT_FILAMENT_BACKEND_PRIVATE_CIRCULARBUFFER_H
 
-#include <utils/compiler.h>
+#include <utils/debug.h>
 
 #include <stddef.h>
 #include <stdint.h>
@@ -40,28 +40,36 @@ public:
 
     ~CircularBuffer() noexcept;
 
-    // allocates 'size' bytes in the circular buffer and returns a pointer to the memory
-    // return the current head and moves it forward by size bytes
-    inline void* allocate(size_t size) noexcept {
+    static size_t getBlockSize() noexcept { return sPageSize; }
+
+    // Total size of circular buffer. This is a constant.
+    size_t size() const noexcept { return mSize; }
+
+    // Allocates `s` bytes in the circular buffer and returns a pointer to the memory. All
+    // allocations must not exceed size() bytes.
+    inline void* allocate(size_t s) noexcept {
+        // We can never allocate more that size().
+        assert_invariant(getUsed() + s <= size());
         char* const cur = static_cast<char*>(mHead);
-        mHead = cur + size;
+        mHead = cur + s;
         return cur;
     }
 
-    // Total size of circular buffer
-    size_t size() const noexcept { return mSize; }
-
-    // returns true if the buffer is empty (e.g. after calling flush)
+    // Returns true if the buffer is empty, i.e.: no allocations were made since
+    // calling getBuffer();
     bool empty() const noexcept { return mTail == mHead; }
 
-    void* getHead() const noexcept { return mHead; }
+    // Returns the size used since the last call to getBuffer()
+    size_t getUsed() const noexcept { return intptr_t(mHead) - intptr_t(mTail); }
 
-    void* getTail() const noexcept { return mTail; }
-
-    // call at least once every getRequiredSize() bytes allocated from the buffer
-    void circularize() noexcept;
-
-    static size_t getBlockSize() noexcept { return sPageSize; }
+    // Retrieves the current allocated range and frees it. It is the responsibility of the caller
+    // to make sure the returned range is no longer in use by the time allocate() allocates
+    // (size() - getUsed()) bytes.
+    struct Range {
+        void* tail;
+        void* head;
+    };
+    Range getBuffer() noexcept;
 
 private:
     void* alloc(size_t size) noexcept;
@@ -69,10 +77,10 @@ private:
 
     // pointer to the beginning of the circular buffer (constant)
     void* mData = nullptr;
-    int mUsesAshmem = -1;
+    int mAshmemFd = -1;
 
     // size of the circular buffer (constant)
-    size_t mSize = 0;
+    size_t const mSize;
 
     // pointer to the beginning of recorded data
     void* mTail = nullptr;

filament/backend/include/private/backend/CommandBufferQueue.h

@@ -19,19 +19,21 @@
 
 #include "private/backend/CircularBuffer.h"
 
-#include <utils/compiler.h>
 #include <utils/Condition.h>
 #include <utils/Mutex.h>
 
 #include <vector>
 
+#include <stddef.h>
+#include <stdint.h>
+
 namespace filament::backend {
 
 /*
  * A producer-consumer command queue that uses a CircularBuffer as main storage
  */
 class CommandBufferQueue {
-    struct Slice {
+    struct Range {
         void* begin;
         void* end;
     };
@@ -44,7 +46,7 @@ class CommandBufferQueue {
 
     mutable utils::Mutex mLock;
     mutable utils::Condition mCondition;
-    mutable std::vector<Slice> mCommandBuffersToExecute;
+    mutable std::vector<Range> mCommandBuffersToExecute;
     size_t mFreeSpace = 0;
     size_t mHighWatermark = 0;
     uint32_t mExitRequested = 0;
@@ -56,17 +58,20 @@ public:
     CommandBufferQueue(size_t requiredSize, size_t bufferSize);
     ~CommandBufferQueue();
 
-    CircularBuffer& getCircularBuffer() { return mCircularBuffer; }
+    CircularBuffer& getCircularBuffer() noexcept { return mCircularBuffer; }
+    CircularBuffer const& getCircularBuffer() const noexcept { return mCircularBuffer; }
+
+    size_t getCapacity() const noexcept { return mRequiredSize; }
 
     size_t getHighWatermark() const noexcept { return mHighWatermark; }
 
     // wait for commands to be available and returns an array containing these commands
-    std::vector<Slice> waitForCommands() const;
+    std::vector<Range> waitForCommands() const;
 
     // return the memory used by this command buffer to the circular buffer
     // WARNING: releaseBuffer() must be called in sequence of the Slices returned by
     // waitForCommands()
-    void releaseBuffer(Slice const& buffer);
+    void releaseBuffer(Range const& buffer);
 
     // all commands buffers (Slices) written to this point are returned by waitForCommand(). This
     // call blocks until the CircularBuffer has at least mRequiredSize bytes available.

filament/backend/include/private/backend/CommandStream.h

@@ -32,11 +32,13 @@
 #include <backend/TargetBufferInfo.h>
 
 #include <utils/compiler.h>
+#include <utils/debug.h>
 #include <utils/ThreadUtils.h>
 
 #include <cstddef>
 #include <functional>
 #include <tuple>
+#include <type_traits>
 #include <utility>
 
 #ifndef NDEBUG
@@ -152,14 +154,14 @@ struct CommandType<void (Driver::*)(ARGS...)> {
         }
 
         // placement new declared as "throw" to avoid the compiler's null-check
-        inline void* operator new(std::size_t size, void* ptr) {
+        inline void* operator new(std::size_t, void* ptr) {
             assert_invariant(ptr);
             return ptr;
         }
     };
 };
 
-// convert an method of "class Driver" into a Command<> type
+// convert a method of "class Driver" into a Command<> type
 #define COMMAND_TYPE(method) CommandType<decltype(&Driver::method)>::Command<&Driver::method>
 
 // ------------------------------------------------------------------------------------------------
@@ -211,6 +213,8 @@ public:
     CommandStream(CommandStream const& rhs) noexcept = delete;
     CommandStream& operator=(CommandStream const& rhs) noexcept = delete;
 
+    CircularBuffer const& getCircularBuffer() const noexcept { return mCurrentBuffer; }
+
 public:
 #define DECL_DRIVER_API(methodName, paramsDecl, params)                                         \
     inline void methodName(paramsDecl) {                                                        \

filament/backend/include/private/backend/Driver.h

@@ -29,6 +29,7 @@
 
 #include <functional>
 
+#include <stddef.h>
 #include <stdint.h>
 
 // Command debugging off. debugging virtuals are not called.

filament/backend/include/private/backend/HandleAllocator.h

@@ -22,9 +22,18 @@
 #include <utils/Allocator.h>
 #include <utils/Log.h>
 #include <utils/compiler.h>
+#include <utils/debug.h>
+#include <utils/ostream.h>
+
 #include <tsl/robin_map.h>
+
+#include <exception>
+#include <type_traits>
 #include <unordered_map>
 
+#include <stddef.h>
+#include <stdint.h>
+
 #if !defined(NDEBUG) && UTILS_HAS_RTTI
 #   define HANDLE_TYPE_SAFETY 1
 #else
@@ -222,7 +231,7 @@ private:
         explicit Allocator(const utils::AreaPolicy::HeapArea& area);
 
         // this is in fact always called with a constexpr size argument
-        [[nodiscard]] inline void* alloc(size_t size, size_t alignment, size_t extra) noexcept {
+        [[nodiscard]] inline void* alloc(size_t size, size_t, size_t extra = 0) noexcept {
             void* p = nullptr;
                  if (size <= mPool0.getSize()) p = mPool0.alloc(size, 16, extra);
             else if (size <= mPool1.getSize()) p = mPool1.alloc(size, 16, extra);

filament/backend/include/private/backend/PlatformFactory.h

@@ -19,9 +19,9 @@
 #ifndef TNT_FILAMENT_BACKEND_PLATFORM_FACTORY_H
 #define TNT_FILAMENT_BACKEND_PLATFORM_FACTORY_H
 
-#include "backend/DriverEnums.h"
+#include <backend/DriverEnums.h>
 
-#include "utils/compiler.h"
+#include <utils/compiler.h>
 
 namespace filament::backend {
 

filament/backend/include/private/backend/SamplerGroup.h

@@ -17,15 +17,13 @@
 #ifndef TNT_FILAMENT_BACKEND_PRIVATE_SAMPLERGROUP_H
 #define TNT_FILAMENT_BACKEND_PRIVATE_SAMPLERGROUP_H
 
-#include "backend/DriverApiForward.h"
-
-#include <utils/compiler.h>
-#include <utils/FixedCapacityVector.h>
-
+#include <backend/DriverApiForward.h>
 #include <backend/DriverEnums.h>
-#include <backend/Handle.h>
 #include <backend/SamplerDescriptor.h>
 
+#include <utils/FixedCapacityVector.h>
+#include <utils/ostream.h>
+
 #include <stddef.h>
 
 namespace filament::backend {

filament/backend/src/CircularBuffer.cpp

@@ -16,6 +16,14 @@
 
 #include "private/backend/CircularBuffer.h"
 
+#include <utils/Log.h>
+#include <utils/Panic.h>
+#include <utils/architecture.h>
+#include <utils/ashmem.h>
+#include <utils/compiler.h>
+#include <utils/debug.h>
+#include <utils/ostream.h>
+
 #if !defined(WIN32) && !defined(__EMSCRIPTEN__) && !defined(IOS)
 #    include <sys/mman.h>
 #    include <unistd.h>
@@ -24,23 +32,20 @@
 #    define HAS_MMAP 0
 #endif
 
+#include <stdint.h>
+#include <stddef.h>
+#include <stdlib.h>
 #include <stdio.h>
 
-#include <utils/architecture.h>
-#include <utils/ashmem.h>
-#include <utils/debug.h>
-#include <utils/Log.h>
-#include <utils/Panic.h>
-
 using namespace utils;
 
 namespace filament::backend {
 
 size_t CircularBuffer::sPageSize = arch::getPageSize();
 
-CircularBuffer::CircularBuffer(size_t size) {
+CircularBuffer::CircularBuffer(size_t size)
+    : mSize(size) {
     mData = alloc(size);
-    mSize = size;
     mTail = mData;
     mHead = mData;
 }
@@ -85,7 +90,7 @@ void* CircularBuffer::alloc(size_t size) noexcept {
                             MAP_PRIVATE, fd, (off_t)size);
                     if (vaddr_guard != MAP_FAILED && (vaddr_guard == (char*)vaddr_shadow + size)) {
                         // woo-hoo success!
-                        mUsesAshmem = fd;
+                        mAshmemFd = fd;
                         data = vaddr;
                     }
                 }
@@ -93,7 +98,7 @@ void* CircularBuffer::alloc(size_t size) noexcept {
         }
     }
 
-    if (UTILS_UNLIKELY(mUsesAshmem < 0)) {
+    if (UTILS_UNLIKELY(mAshmemFd < 0)) {
         // ashmem failed
         if (vaddr_guard != MAP_FAILED) {
             munmap(vaddr_guard, size);
@@ -137,9 +142,9 @@ void CircularBuffer::dealloc() noexcept {
     if (mData) {
         size_t const BLOCK_SIZE = getBlockSize();
         munmap(mData, mSize * 2 + BLOCK_SIZE);
-        if (mUsesAshmem >= 0) {
-            close(mUsesAshmem);
-            mUsesAshmem = -1;
+        if (mAshmemFd >= 0) {
+            close(mAshmemFd);
+            mAshmemFd = -1;
         }
     }
 #else
@@ -149,23 +154,37 @@ void CircularBuffer::dealloc() noexcept {
 }
 
 
-void CircularBuffer::circularize() noexcept {
-    if (mUsesAshmem > 0) {
-        intptr_t const overflow = intptr_t(mHead) - (intptr_t(mData) + ssize_t(mSize));
-        if (overflow >= 0) {
-            assert_invariant(size_t(overflow) <= mSize);
-            mHead = (void *) (intptr_t(mData) + overflow);
-            #ifndef NDEBUG
-            memset(mData, 0xA5, size_t(overflow));
-            #endif
-        }
-    } else {
-        // Only circularize if mHead if in the second buffer.
-        if (intptr_t(mHead) - intptr_t(mData) > ssize_t(mSize)) {
+CircularBuffer::Range CircularBuffer::getBuffer() noexcept {
+    Range const range{ .tail = mTail, .head = mHead };
+
+    char* const pData = static_cast<char*>(mData);
+    char const* const pEnd = pData + mSize;
+    char const* const pHead = static_cast<char const*>(mHead);
+    if (UTILS_UNLIKELY(pHead >= pEnd)) {
+        size_t const overflow = pHead - pEnd;
+        if (UTILS_LIKELY(mAshmemFd > 0)) {
+            assert_invariant(overflow <= mSize);
+            mHead = static_cast<void*>(pData + overflow);
+            // Data         Tail  End   Head              [virtual]
+            //  v             v    v     v
+            //  +-------------:----+-----:--------------+
+            //  |             :    |     :              |
+            //  +-----:------------+--------------------+
+            //       Head          |<------ copy ------>| [physical]
+        } else {
+            // Data         Tail  End   Head
+            //  v             v    v     v
+            //  +-------------:----+-----:--------------+
+            //  |             :    |     :              |
+            //  +-----|------------+-----|--------------+
+            //        |<---------------->|
+            //           sliding window
             mHead = mData;
         }
     }
     mTail = mHead;
+
+    return range;
 }
 
 } // namespace filament::backend

filament/backend/src/CommandBufferQueue.cpp

@@ -15,14 +15,25 @@
  */
 
 #include "private/backend/CommandBufferQueue.h"
+#include "private/backend/CircularBuffer.h"
+#include "private/backend/CommandStream.h"
 
+#include <utils/compiler.h>
 #include <utils/Log.h>
-#include <utils/Systrace.h>
+#include <utils/Mutex.h>
+#include <utils/ostream.h>
 #include <utils/Panic.h>
+#include <utils/Systrace.h>
 #include <utils/debug.h>
 
-#include "private/backend/BackendUtils.h"
-#include "private/backend/CommandStream.h"
+#include <algorithm>
+#include <mutex>
+#include <iterator>
+#include <utility>
+#include <vector>
+
+#include <stddef.h>
+#include <stdint.h>
 
 using namespace utils;
 
@@ -65,50 +76,53 @@ void CommandBufferQueue::flush() noexcept {
     // always guaranteed to have enough space for the NoopCommand
     new(circularBuffer.allocate(sizeof(NoopCommand))) NoopCommand(nullptr);
 
-    // end of this slice
-    void* const head = circularBuffer.getHead();
+    const size_t requiredSize = mRequiredSize;
 
-    // beginning of this slice
-    void* const tail = circularBuffer.getTail();
+    // get the current buffer
+    auto const [begin, end] = circularBuffer.getBuffer();
 
-    // size of this slice
-    uint32_t const used = uint32_t(intptr_t(head) - intptr_t(tail));
+    assert_invariant(circularBuffer.empty());
 
-    circularBuffer.circularize();
+    // size of the current buffer
+    size_t const used = std::distance(
+            static_cast<char const*>(begin), static_cast<char const*>(end));
 
     std::unique_lock<utils::Mutex> lock(mLock);
-    mCommandBuffersToExecute.push_back({ tail, head });
+    mCommandBuffersToExecute.push_back({ begin, end });
+    mCondition.notify_one();
 
     // circular buffer is too small, we corrupted the stream
     ASSERT_POSTCONDITION(used <= mFreeSpace,
             "Backend CommandStream overflow. Commands are corrupted and unrecoverable.\n"
             "Please increase minCommandBufferSizeMB inside the Config passed to Engine::create.\n"
-            "Space used at this time: %u bytes",
-            (unsigned)used);
+            "Space used at this time: %u bytes, overflow: %u bytes",
+            (unsigned)used, unsigned(used - mFreeSpace));
 
     // wait until there is enough space in the buffer
     mFreeSpace -= used;
-    const size_t requiredSize = mRequiredSize;
+    if (UTILS_UNLIKELY(mFreeSpace < requiredSize)) {
+
 
 #ifndef NDEBUG
-    size_t totalUsed = circularBuffer.size() - mFreeSpace;
-    mHighWatermark = std::max(mHighWatermark, totalUsed);
-    if (UTILS_UNLIKELY(totalUsed > requiredSize)) {
-        slog.d << "CommandStream used too much space: " << totalUsed
-            << ", out of " << requiredSize << " (will block)" << io::endl;
-    }
+        size_t const totalUsed = circularBuffer.size() - mFreeSpace;
+        slog.d << "CommandStream used too much space (will block): "
+                << "needed space " << requiredSize << " out of " << mFreeSpace
+                << ", totalUsed=" << totalUsed << ", current=" << used
+                << ", queue size=" << mCommandBuffersToExecute.size() << " buffers"
+                << io::endl;
+
+        mHighWatermark = std::max(mHighWatermark, totalUsed);
 #endif
 
-    mCondition.notify_one();
-    if (UTILS_LIKELY(mFreeSpace < requiredSize)) {
         SYSTRACE_NAME("waiting: CircularBuffer::flush()");
         mCondition.wait(lock, [this, requiredSize]() -> bool {
+            // TODO: on macOS, we need to call pumpEvents from time to time
             return mFreeSpace >= requiredSize;
         });
     }
 }
 
-std::vector<CommandBufferQueue::Slice> CommandBufferQueue::waitForCommands() const {
+std::vector<CommandBufferQueue::Range> CommandBufferQueue::waitForCommands() const {
     if (!UTILS_HAS_THREADING) {
         return std::move(mCommandBuffersToExecute);
     }
@@ -123,7 +137,7 @@ std::vector<CommandBufferQueue::Slice> CommandBufferQueue::waitForCommands() con
     return std::move(mCommandBuffersToExecute);
 }
 
-void CommandBufferQueue::releaseBuffer(CommandBufferQueue::Slice const& buffer) {
+void CommandBufferQueue::releaseBuffer(CommandBufferQueue::Range const& buffer) {
     std::lock_guard<utils::Mutex> const lock(mLock);
     mFreeSpace += uintptr_t(buffer.end) - uintptr_t(buffer.begin);
     mCondition.notify_one();

filament/backend/src/Driver.cpp

@@ -21,7 +21,12 @@
 
 #include <backend/AcquiredImage.h>
 #include <backend/BufferDescriptor.h>
+#include <backend/DriverEnums.h>
 
+#include <utils/compiler.h>
+#include <utils/debug.h>
+#include <utils/Log.h>
+#include <utils/ostream.h>
 #include <utils/Systrace.h>
 
 #include <math/half.h>
@@ -29,6 +34,13 @@
 #include <math/vec3.h>
 #include <math/vec4.h>
 
+#include <functional>
+#include <mutex>
+#include <utility>
+
+#include <stddef.h>
+#include <stdint.h>
+
 using namespace utils;
 using namespace filament::math;
 
@@ -119,7 +131,8 @@ void DriverBase::purge() noexcept {
 // ------------------------------------------------------------------------------------------------
 
 void DriverBase::scheduleDestroySlow(BufferDescriptor&& buffer) noexcept {
-    scheduleCallback(buffer.getHandler(), [buffer = std::move(buffer)]() {
+    auto const handler = buffer.getHandler();
+    scheduleCallback(handler, [buffer = std::move(buffer)]() {
         // user callback is called when BufferDescriptor gets destroyed
     });
 }

filament/backend/src/metal/MetalBlitter.mm

@@ -20,6 +20,7 @@
 #include "MetalUtils.h"
 
 #include <utils/Panic.h>
+#include <utils/Log.h>
 
 namespace filament::backend {
 

filament/backend/src/metal/MetalBufferPool.mm

@@ -19,6 +19,7 @@
 #include "MetalContext.h"
 
 #include <utils/Panic.h>
+#include <utils/Log.h>
 #include <utils/trap.h>
 
 #include <thread>

filament/backend/src/metal/MetalExternalImage.mm

@@ -21,6 +21,7 @@
 #include "MetalUtils.h"
 
 #include <utils/Panic.h>
+#include <utils/Log.h>
 #include <utils/trap.h>
 
 #define NSERROR_CHECK(message)                                                                     \

filament/backend/src/metal/MetalHandles.mm

@@ -245,30 +245,53 @@ void MetalSwapChain::present() {
     }
 }
 
-struct PresentDrawableData {
-    void* drawable = nullptr;
-    MetalDriver* driver = nullptr;
+#ifndef FILAMENT_RELEASE_PRESENT_DRAWABLE_MAIN_THREAD
+#define FILAMENT_RELEASE_PRESENT_DRAWABLE_MAIN_THREAD 1
+#endif
+
+class PresentDrawableData {
+public:
+    PresentDrawableData() = delete;
+    PresentDrawableData(const PresentDrawableData&) = delete;
+    PresentDrawableData& operator=(const PresentDrawableData&) = delete;
+
+    static PresentDrawableData* create(id<CAMetalDrawable> drawable, MetalDriver* driver) {
+        assert_invariant(driver);
+        return new PresentDrawableData(drawable, driver);
+    }
+
+    static void maybePresentAndDestroyAsync(PresentDrawableData* that, bool shouldPresent) {
+        if (shouldPresent) {
+           [that->mDrawable present];
+        }
+
+#if FILAMENT_RELEASE_PRESENT_DRAWABLE_MAIN_THREAD == 1
+        // mDrawable is acquired on the driver thread. Typically, we would release this object on
+        // the same thread, but after receiving consistent crash reports from within
+        // [CAMetalDrawable dealloc], we suspect this object requires releasing on the main thread.
+        dispatch_async(dispatch_get_main_queue(), ^{ cleanupAndDestroy(that); });
+#else
+        that->mDriver->runAtNextTick([that]() { cleanupAndDestroy(that); });
+#endif
+    }
+
+private:
+    PresentDrawableData(id<CAMetalDrawable> drawable, MetalDriver* driver)
+        : mDrawable(drawable), mDriver(driver) {}
+
+    static void cleanupAndDestroy(PresentDrawableData *that) {
+        that->mDrawable = nil;
+        that->mDriver = nullptr;
+        delete that;
+    }
+
+    id<CAMetalDrawable> mDrawable;
+    MetalDriver* mDriver = nullptr;
 };
 
 void presentDrawable(bool presentFrame, void* user) {
     auto* presentDrawableData = static_cast<PresentDrawableData*>(user);
-
-    // CFBridgingRelease here is used to balance the CFBridgingRetain inside acquireDrawable.
-    id<CAMetalDrawable> drawable =
-            (id<CAMetalDrawable>)CFBridgingRelease(presentDrawableData->drawable);
-    if (presentFrame) {
-        [drawable present];
-    }
-
-    // Schedule the drawable destruction on the driver thread.
-    void* voidDrawable = (void*) CFBridgingRetain(drawable);
-    MetalDriver* driver = presentDrawableData->driver;
-    driver->runAtNextTick([voidDrawable]() {
-        // The drawable is released here.
-        CFBridgingRelease(voidDrawable);
-    });
-
-    delete presentDrawableData;
+    PresentDrawableData::maybePresentAndDestroyAsync(presentDrawableData, presentFrame);
 }
 
 void MetalSwapChain::scheduleFrameScheduledCallback() {
@@ -277,21 +300,16 @@ void MetalSwapChain::scheduleFrameScheduledCallback() {
     }
 
     assert_invariant(drawable);
-    FrameScheduledCallback callback = frameScheduledCallback;
-    // This block strongly captures drawable to keep it alive until the handler executes.
-    // We cannot simply reference this->drawable inside the block because the block would then only
-    // capture the _this_ pointer (MetalSwapChain*) instead of the drawable.
-    id<CAMetalDrawable> d = drawable;
+
+    // Destroy this by calling maybePresentAndDestroyAsync() later.
+    auto* presentData = PresentDrawableData::create(drawable, context.driver);
+
+    FrameScheduledCallback userCallback = frameScheduledCallback;
     void* userData = frameScheduledUserData;
-    MetalDriver* driver = context.driver;
+
     [getPendingCommandBuffer(&context) addScheduledHandler:^(id<MTLCommandBuffer> cb) {
-        // CFBridgingRetain is used here to give the drawable a +1 retain count before
-        // casting it to a void*.
-        auto* presentDrawableData = new PresentDrawableData;
-        presentDrawableData->drawable = (void*) CFBridgingRetain(d);
-        presentDrawableData->driver = driver;
-        PresentCallable callable(presentDrawable, (void*) presentDrawableData);
-        callback(callable, userData);
+        PresentCallable callable(presentDrawable, static_cast<void*>(presentData));
+        userCallback(callable, userData);
     }];
 }
 

filament/backend/src/metal/MetalShaderCompiler.mm

@@ -103,10 +103,19 @@ void MetalShaderCompiler::terminate() noexcept {
         NSString* objcSource = [[NSString alloc] initWithBytes:source.data()
                                                         length:source.size() - 1
                                                       encoding:NSUTF8StringEncoding];
+
+        // By default, Metal uses the most recent language version.
+        MTLCompileOptions* options = [MTLCompileOptions new];
+
+        // Disable Fast Math optimizations.
+        // This ensures that operations adhere to IEEE standards for floating-point arithmetic,
+        // which is crucial for half precision floats in scenarios where fast math optimizations
+        // lead to inaccuracies, such as in handling special values like NaN or Infinity.
+        options.fastMathEnabled = NO;
+
         NSError* error = nil;
-        // When options is nil, Metal uses the most recent language version available.
         id<MTLLibrary> library = [device newLibraryWithSource:objcSource
-                                                      options:nil
+                                                      options:options
                                                         error:&error];
         if (library == nil) {
             if (error) {

filament/backend/src/metal/MetalState.mm

@@ -18,6 +18,8 @@
 
 #include "MetalEnums.h"
 
+#include <utils/Log.h>
+
 namespace filament {
 namespace backend {
 

filament/backend/src/opengl/OpenGLContext.cpp

@@ -427,7 +427,6 @@ void OpenGLContext::initBugs(Bugs* bugs, Extensions const& exts,
             if (strstr(renderer, "Mali-T")) {
                 bugs->disable_glFlush = true;
                 bugs->disable_shared_context_draws = true;
-                bugs->texture_external_needs_rebind = true;
                 // We have not verified that timer queries work on Mali-T, so we disable to be safe.
                 bugs->dont_use_timer_query = true;
             }

filament/backend/src/opengl/OpenGLContext.h

@@ -222,10 +222,6 @@ public:
         // Some drivers have gl state issues when drawing from shared contexts
         bool disable_shared_context_draws;
 
-        // Some drivers require the GL_TEXTURE_EXTERNAL_OES target to be bound when
-        // the texture image changes, even if it's already bound to that texture
-        bool texture_external_needs_rebind;
-
         // Some web browsers seem to immediately clear the default framebuffer when calling
         // glInvalidateFramebuffer with WebGL 2.0
         bool disable_invalidate_framebuffer;
@@ -433,9 +429,6 @@ private:
             {   bugs.disable_shared_context_draws,
                     "disable_shared_context_draws",
                     ""},
-            {   bugs.texture_external_needs_rebind,
-                    "texture_external_needs_rebind",
-                    ""},
             {   bugs.disable_invalidate_framebuffer,
                     "disable_invalidate_framebuffer",
                     ""},
@@ -711,7 +704,7 @@ void OpenGLContext::bindTexture(GLuint unit, GLuint target, GLuint texId, size_t
     update_state(state.textures.units[unit].targets[targetIndex].texture_id, texId, [&]() {
         activeTexture(unit);
         glBindTexture(target, texId);
-    }, (target == GL_TEXTURE_EXTERNAL_OES) && bugs.texture_external_needs_rebind);
+    }, target == GL_TEXTURE_EXTERNAL_OES);
 }
 
 void OpenGLContext::bindTexture(GLuint unit, GLuint target, GLuint texId) noexcept {

filament/backend/src/opengl/OpenGLDriver.cpp

@@ -147,9 +147,9 @@ Driver* OpenGLDriver::create(OpenGLPlatform* const platform,
 #endif
 
     size_t const defaultSize = FILAMENT_OPENGL_HANDLE_ARENA_SIZE_IN_MB * 1024U * 1024U;
-    Platform::DriverConfig validConfig {driverConfig};
+    Platform::DriverConfig validConfig{ driverConfig };
     validConfig.handleArenaSize = std::max(driverConfig.handleArenaSize, defaultSize);
-    OpenGLDriver* const driver = new OpenGLDriver(ec, validConfig);
+    OpenGLDriver* const driver = new(std::nothrow) OpenGLDriver(ec, validConfig);
     return driver;
 }
 
@@ -171,7 +171,8 @@ OpenGLDriver::OpenGLDriver(OpenGLPlatform* platform, const Platform::DriverConfi
           mContext(),
           mShaderCompilerService(*this),
           mHandleAllocator("Handles", driverConfig.handleArenaSize),
-          mSamplerMap(32) {
+          mSamplerMap(32),
+          mDriverConfig(driverConfig) {
 
     std::fill(mSamplerBindings.begin(), mSamplerBindings.end(), nullptr);
 

filament/backend/src/opengl/OpenGLDriver.h

@@ -400,6 +400,9 @@ private:
     // timer query implementation
     OpenGLTimerQueryInterface* mTimerQueryImpl = nullptr;
 
+    const Platform::DriverConfig mDriverConfig;
+    Platform::DriverConfig const& getDriverConfig() const noexcept { return mDriverConfig; }
+
     // for ES2 sRGB support
     GLSwapChain* mCurrentDrawSwapChain = nullptr;
     bool mRec709OutputColorspace = false;

filament/backend/src/opengl/ShaderCompilerService.cpp

@@ -151,6 +151,12 @@ bool ShaderCompilerService::isParallelShaderCompileSupported() const noexcept {
 }
 
 void ShaderCompilerService::init() noexcept {
+    if (UTILS_UNLIKELY(mDriver.getDriverConfig().disableParallelShaderCompile)) {
+        // user disabled parallel shader compile
+        mMode = Mode::SYNCHRONOUS;
+        return;
+    }
+
     // Here we decide which mode we'll be using. We always prefer our own thread-pool if
     // that mode is available because, we have no control on how the compilation queues are
     // handled if done by the driver (so at the very least we'd need to decode this per-driver).

filament/backend/src/opengl/ShaderCompilerService.h

@@ -109,7 +109,7 @@ private:
     };
 
     enum class Mode {
-        UNDEFINED,      // init() has not beed called yet.
+        UNDEFINED,      // init() has not been called yet.
         SYNCHRONOUS,    // synchronous shader compilation
         THREAD_POOL,    // asynchronous shader compilation using a thread-pool (most common)
         ASYNCHRONOUS    // asynchronous shader compilation using KHR_parallel_shader_compile

filament/backend/src/vulkan/platform/VulkanPlatformAndroidLinuxWindows.cpp

@@ -15,6 +15,7 @@
  */
 
 #include <backend/platforms/VulkanPlatform.h>
+#include <backend/DriverEnums.h>
 
 #include "vulkan/VulkanConstants.h"
 #include "vulkan/VulkanDriverFactory.h"
@@ -23,6 +24,11 @@
 
 #include <bluevk/BlueVK.h>
 
+#include <tuple>
+
+#include <stdint.h>
+#include <stddef.h>
+
 #if defined(__linux__) || defined(__FreeBSD__)
 #define LINUX_OR_FREEBSD 1
 #endif

filament/include/filament/Box.h

@@ -21,10 +21,14 @@
 
 #include <utils/compiler.h>
 
-#include <limits>
-
+#include <math/mat3.h>
 #include <math/mat4.h>
 #include <math/vec3.h>
+#include <math/vec4.h>
+
+#include <float.h>
+
+#include <stddef.h>
 
 namespace filament {
 
@@ -70,7 +74,7 @@ public:
      * @return This bounding box
      */
     Box& set(const math::float3& min, const math::float3& max) noexcept {
-        // float3 ctor needed for visual studio
+        // float3 ctor needed for Visual Studio
         center     = (max + min) * math::float3(0.5f);
         halfExtent = (max - min) * math::float3(0.5f);
         return *this;
@@ -130,17 +134,17 @@ public:
 struct UTILS_PUBLIC Aabb {
 
     /** min coordinates */
-    math::float3 min = std::numeric_limits<float>::max();
+    math::float3 min = FLT_MAX;
 
     /** max coordinates */
-    math::float3 max = std::numeric_limits<float>::lowest();
+    math::float3 max = -FLT_MAX;
 
     /**
      * Computes the center of the box.
      * @return (max + min)/2
      */
     math::float3 center() const noexcept {
-        // float3 ctor needed for visual studio
+        // float3 ctor needed for Visual Studio
         return (max + min) * math::float3(0.5f);
     }
 
@@ -149,7 +153,7 @@ struct UTILS_PUBLIC Aabb {
      * @return (max - min)/2
      */
     math::float3 extent() const noexcept {
-        // float3 ctor needed for visual studio
+        // float3 ctor needed for Visual Studio
         return (max - min) * math::float3(0.5f);
     }
 
@@ -198,12 +202,14 @@ struct UTILS_PUBLIC Aabb {
      * @return the maximum signed distance to the box. Negative if p is in the box
      */
     float contains(math::float3 p) const noexcept {
+        // we don't use std::max to avoid a dependency on <algorithm>
+        auto const maximum = [](auto a, auto b) { return a > b ? a : b; };
         float d = min.x - p.x;
-        d = std::max(d, min.y - p.y);
-        d = std::max(d, min.z - p.z);
-        d = std::max(d, p.x - max.x);
-        d = std::max(d, p.y - max.y);
-        d = std::max(d, p.z - max.z);
+        d = maximum(d, min.y - p.y);
+        d = maximum(d, min.z - p.z);
+        d = maximum(d, p.x - max.x);
+        d = maximum(d, p.y - max.y);
+        d = maximum(d, p.z - max.z);
         return d;
     }
 

filament/include/filament/BufferObject.h

@@ -22,11 +22,13 @@
 #include <filament/FilamentAPI.h>
 
 #include <backend/DriverEnums.h>
-
 #include <backend/BufferDescriptor.h>
 
 #include <utils/compiler.h>
 
+#include <stdint.h>
+#include <stddef.h>
+
 namespace filament {
 
 class FBufferObject;
@@ -82,8 +84,7 @@ public:
          *
          * @param engine Reference to the filament::Engine to associate this BufferObject with.
          *
-         * @return pointer to the newly created object or nullptr if exceptions are disabled and
-         *         an error occurred.
+         * @return pointer to the newly created object
          *
          * @exception utils::PostConditionPanic if a runtime error occurred, such as running out of
          *            memory or other resources.
@@ -91,7 +92,7 @@ public:
          *
          * @see IndexBuffer::setBuffer
          */
-        BufferObject* build(Engine& engine);
+        BufferObject* UTILS_NONNULL build(Engine& engine);
     private:
         friend class FBufferObject;
     };

filament/include/filament/Camera.h

@@ -28,6 +28,11 @@
 #include <math/vec4.h>
 #include <math/mat4.h>
 
+#include <math.h>
+
+#include <stdint.h>
+#include <stddef.h>
+
 namespace utils {
 class Entity;
 } // namespace utils
@@ -184,7 +189,7 @@ public:
      * @see Fov.
      */
     static math::mat4 projection(Fov direction, double fovInDegrees,
-            double aspect, double near, double far = std::numeric_limits<double>::infinity());
+            double aspect, double near, double far = INFINITY);
 
     /** Returns the projection matrix from the focal length.
      *
@@ -194,7 +199,7 @@ public:
      * @param far         distance in world units from the camera to the far plane. \p far > \p near.
      */
     static math::mat4 projection(double focalLengthInMillimeters,
-            double aspect, double near, double far = std::numeric_limits<double>::infinity());
+            double aspect, double near, double far = INFINITY);
 
 
     /** Sets the projection matrix from a frustum defined by six planes.
@@ -301,7 +306,7 @@ public:
      * @see setCustomProjection
      * @see Engine::Config::stereoscopicEyeCount
      */
-    void setCustomEyeProjection(math::mat4 const* projection, size_t count,
+    void setCustomEyeProjection(math::mat4 const* UTILS_NONNULL projection, size_t count,
             math::mat4 const& projectionForCulling, double near, double far);
 
     /** Sets an additional matrix that scales the projection matrix.

filament/include/filament/Color.h

@@ -24,6 +24,9 @@
 #include <math/vec3.h>
 #include <math/vec4.h>
 
+#include <stdint.h>
+#include <stddef.h>
+
 namespace filament {
 
 //! RGB color in linear space

filament/include/filament/ColorGrading.h

@@ -26,6 +26,9 @@
 
 #include <math/mathfwd.h>
 
+#include <stdint.h>
+#include <stddef.h>
+
 namespace filament {
 
 class Engine;
@@ -200,7 +203,7 @@ public:
          *
          * @return This Builder, for chaining calls
          */
-        Builder& toneMapper(const ToneMapper* toneMapper) noexcept;
+        Builder& toneMapper(ToneMapper const* UTILS_NULLABLE toneMapper) noexcept;
 
         /**
          * Selects the tone mapping operator to apply to the HDR color buffer as the last
@@ -470,10 +473,9 @@ public:
          *
          * @param engine Reference to the filament::Engine to associate this ColorGrading with.
          *
-         * @return pointer to the newly created object or nullptr if exceptions are disabled and
-         *         an error occurred.
+         * @return pointer to the newly created object.
          */
-        ColorGrading* build(Engine& engine);
+        ColorGrading* UTILS_NONNULL build(Engine& engine);
 
     private:
         friend class FColorGrading;

filament/include/filament/ColorSpace.h

@@ -18,7 +18,6 @@
 #define TNT_FILAMENT_COLOR_SPACE_H
 
 #include <math/vec2.h>
-#include <math/vec3.h>
 
 namespace filament::color {
 

filament/include/filament/DebugRegistry.h

@@ -25,7 +25,7 @@
 
 #include <math/mathfwd.h>
 
-#include <stdint.h>
+#include <stddef.h>
 
 namespace filament {
 
@@ -39,27 +39,12 @@ namespace filament {
 class UTILS_PUBLIC DebugRegistry : public FilamentAPI {
 public:
 
-    /**
-     * Type of a property
-     */
-    enum Type {
-        BOOL, INT, FLOAT, FLOAT2, FLOAT3, FLOAT4
-    };
-
-    /**
-     * Information about a property
-     */
-    struct Property {
-        const char* name;   //!< property name
-        Type type;          //!< property type
-    };
-
     /**
      * Queries whether a property exists
      * @param name The name of the property to query
      * @return true if the property exists, false otherwise
      */
-    bool hasProperty(const char* name) const noexcept;
+    bool hasProperty(const char* UTILS_NONNULL name) const noexcept;
 
     /**
      * Queries the address of a property's data from its name
@@ -67,28 +52,30 @@ public:
      * @return Address of the data of the \p name property
      * @{
      */
-    void* getPropertyAddress(const char* name);
+    void* UTILS_NULLABLE getPropertyAddress(const char* UTILS_NONNULL name);
 
-    void const* getPropertyAddress(const char* name) const noexcept;
+    void const* UTILS_NULLABLE getPropertyAddress(const char* UTILS_NONNULL name) const noexcept;
 
     template<typename T>
-    inline T* getPropertyAddress(const char* name) {
+    inline T* UTILS_NULLABLE getPropertyAddress(const char* UTILS_NONNULL name) {
         return static_cast<T*>(getPropertyAddress(name));
     }
 
     template<typename T>
-    inline T const* getPropertyAddress(const char* name) const noexcept {
+    inline T const* UTILS_NULLABLE getPropertyAddress(const char* UTILS_NONNULL name) const noexcept {
         return static_cast<T*>(getPropertyAddress(name));
     }
 
     template<typename T>
-    inline bool getPropertyAddress(const char* name, T** p) {
+    inline bool getPropertyAddress(const char* UTILS_NONNULL name,
+            T* UTILS_NULLABLE* UTILS_NONNULL p) {
         *p = getPropertyAddress<T>(name);
         return *p != nullptr;
     }
 
     template<typename T>
-    inline bool getPropertyAddress(const char* name, T* const* p) const noexcept {
+    inline bool getPropertyAddress(const char* UTILS_NONNULL name,
+            T* const UTILS_NULLABLE* UTILS_NONNULL p) const noexcept {
         *p = getPropertyAddress<T>(name);
         return *p != nullptr;
     }
@@ -101,12 +88,12 @@ public:
      * @return true if the operation was successful, false otherwise.
      * @{
      */
-    bool setProperty(const char* name, bool v) noexcept;
-    bool setProperty(const char* name, int v) noexcept;
-    bool setProperty(const char* name, float v) noexcept;
-    bool setProperty(const char* name, math::float2 v) noexcept;
-    bool setProperty(const char* name, math::float3 v) noexcept;
-    bool setProperty(const char* name, math::float4 v) noexcept;
+    bool setProperty(const char* UTILS_NONNULL name, bool v) noexcept;
+    bool setProperty(const char* UTILS_NONNULL name, int v) noexcept;
+    bool setProperty(const char* UTILS_NONNULL name, float v) noexcept;
+    bool setProperty(const char* UTILS_NONNULL name, math::float2 v) noexcept;
+    bool setProperty(const char* UTILS_NONNULL name, math::float3 v) noexcept;
+    bool setProperty(const char* UTILS_NONNULL name, math::float4 v) noexcept;
     /** @}*/
 
     /**
@@ -116,20 +103,20 @@ public:
      * @return true if the call was successful and \p v was updated
      * @{
      */
-    bool getProperty(const char* name, bool* v) const noexcept;
-    bool getProperty(const char* name, int* v) const noexcept;
-    bool getProperty(const char* name, float* v) const noexcept;
-    bool getProperty(const char* name, math::float2* v) const noexcept;
-    bool getProperty(const char* name, math::float3* v) const noexcept;
-    bool getProperty(const char* name, math::float4* v) const noexcept;
+    bool getProperty(const char* UTILS_NONNULL name, bool* UTILS_NONNULL v) const noexcept;
+    bool getProperty(const char* UTILS_NONNULL name, int* UTILS_NONNULL v) const noexcept;
+    bool getProperty(const char* UTILS_NONNULL name, float* UTILS_NONNULL v) const noexcept;
+    bool getProperty(const char* UTILS_NONNULL name, math::float2* UTILS_NONNULL v) const noexcept;
+    bool getProperty(const char* UTILS_NONNULL name, math::float3* UTILS_NONNULL v) const noexcept;
+    bool getProperty(const char* UTILS_NONNULL name, math::float4* UTILS_NONNULL v) const noexcept;
     /** @}*/
 
     struct DataSource {
-        void const* data;
+        void const* UTILS_NULLABLE data;
         size_t count;
     };
 
-    DataSource getDataSource(const char* name) const noexcept;
+    DataSource getDataSource(const char* UTILS_NONNULL name) const noexcept;
 
     struct FrameHistory {
         using duration_ms = float;

filament/include/filament/Engine.h

@@ -19,9 +19,14 @@
 
 #include <filament/FilamentAPI.h>
 
+#include <backend/DriverEnums.h>
 #include <backend/Platform.h>
 
 #include <utils/compiler.h>
+#include <utils/Invocable.h>
+
+#include <stdint.h>
+#include <stddef.h>
 
 namespace utils {
 class Entity;
@@ -300,11 +305,23 @@ public:
          * @see Engine::getMaxStereoscopicEyes
          */
         uint8_t stereoscopicEyeCount = 2;
+
+        /*
+         * Size in MiB of the frame graph texture cache. This should be adjusted based on the
+         * size of used render targets (typically the screen).
+         */
+        uint32_t resourceAllocatorCacheSizeMB = 64;
+
+        /*
+         * This value determines for how many frames are texture entries kept in the cache.
+         * The default value of 30 corresponds to about half a second at 60 fps.
+         */
+        uint32_t resourceAllocatorCacheMaxAge = 30;
     };
 
 
 #if UTILS_HAS_THREADING
-    using CreateCallback = void(void* user, void* token);
+    using CreateCallback = void(void* UTILS_NULLABLE user, void* UTILS_NONNULL token);
 #endif
 
     /**
@@ -343,7 +360,7 @@ public:
          *
          * @return A reference to this Builder for chaining calls.
          */
-        Builder& platform(Platform* platform) noexcept;
+        Builder& platform(Platform* UTILS_NULLABLE platform) noexcept;
 
         /**
          * @param config    A pointer to optional parameters to specify memory size
@@ -351,7 +368,7 @@ public:
          *
          * @return A reference to this Builder for chaining calls.
          */
-        Builder& config(const Config* config) noexcept;
+        Builder& config(const Config* UTILS_NULLABLE config) noexcept;
 
         /**
          * @param sharedContext A platform-dependant context used as a shared context
@@ -359,7 +376,7 @@ public:
          *
          * @return A reference to this Builder for chaining calls.
          */
-        Builder& sharedContext(void* sharedContext) noexcept;
+        Builder& sharedContext(void* UTILS_NULLABLE sharedContext) noexcept;
 
         /**
          * @param featureLevel The feature level at which initialize Filament.
@@ -374,7 +391,7 @@ public:
          * @param callback  Callback called once the engine is initialized and it is safe to
          *                  call Engine::getEngine().
          */
-        void build(utils::Invocable<void(void* token)>&& callback) const;
+        void build(utils::Invocable<void(void* UTILS_NONNULL token)>&& callback) const;
 #endif
 
         /**
@@ -389,16 +406,17 @@ public:
          *              allocate the command buffer. If exceptions are disabled, this condition if
          *              fatal and this function will abort.
          */
-        Engine* build() const;
+        Engine* UTILS_NULLABLE build() const;
     };
 
     /**
      * Backward compatibility helper to create an Engine.
      * @see Builder
      */
-    static inline Engine* create(Backend backend = Backend::DEFAULT,
-            Platform* platform = nullptr, void* sharedContext = nullptr,
-            const Config* config = nullptr) {
+    static inline Engine* UTILS_NULLABLE create(Backend backend = Backend::DEFAULT,
+            Platform* UTILS_NULLABLE platform = nullptr,
+            void* UTILS_NULLABLE sharedContext = nullptr,
+            const Config* UTILS_NULLABLE config = nullptr) {
         return Engine::Builder()
                 .backend(backend)
                 .platform(platform)
@@ -413,16 +431,18 @@ public:
      * Backward compatibility helper to create an Engine asynchronously.
      * @see Builder
      */
-    static inline void createAsync(CreateCallback callback, void* user,
+    static inline void createAsync(CreateCallback callback,
+            void* UTILS_NULLABLE user,
             Backend backend = Backend::DEFAULT,
-            Platform* platform = nullptr, void* sharedContext = nullptr,
-            const Config* config = nullptr) {
+            Platform* UTILS_NULLABLE platform = nullptr,
+            void* UTILS_NULLABLE sharedContext = nullptr,
+            const Config* UTILS_NULLABLE config = nullptr) {
         Engine::Builder()
                 .backend(backend)
                 .platform(platform)
                 .sharedContext(sharedContext)
                 .config(config)
-                .build([callback, user](void* token) {
+                .build([callback, user](void* UTILS_NONNULL token) {
                     callback(user, token);
                 });
     }
@@ -439,7 +459,7 @@ public:
      * allocate the command buffer. If exceptions are disabled, this condition if fatal and
      * this function will abort.
      */
-    static Engine* getEngine(void* token);
+    static Engine* UTILS_NULLABLE getEngine(void* UTILS_NONNULL token);
 #endif
 
 
@@ -469,7 +489,7 @@ public:
      * \remark
      * This method is thread-safe.
      */
-    static void destroy(Engine** engine);
+    static void destroy(Engine* UTILS_NULLABLE* UTILS_NULLABLE engine);
 
     /**
      * Destroy the Engine instance and all associated resources.
@@ -496,7 +516,7 @@ public:
      * \remark
      * This method is thread-safe.
      */
-    static void destroy(Engine* engine);
+    static void destroy(Engine* UTILS_NULLABLE engine);
 
     /**
      * Query the feature level supported by the selected backend.
@@ -644,11 +664,11 @@ public:
      *                     `ANativeWindow*`.
      * @param flags One or more configuration flags as defined in `SwapChain`.
      *
-     * @return A pointer to the newly created SwapChain or nullptr if it couldn't be created.
+     * @return A pointer to the newly created SwapChain.
      *
      * @see Renderer.beginFrame()
      */
-    SwapChain* createSwapChain(void* nativeWindow, uint64_t flags = 0) noexcept;
+    SwapChain* UTILS_NONNULL createSwapChain(void* UTILS_NULLABLE nativeWindow, uint64_t flags = 0) noexcept;
 
 
     /**
@@ -658,42 +678,42 @@ public:
       * @param height   Height of the drawing buffer in pixels.
      * @param flags     One or more configuration flags as defined in `SwapChain`.
      *
-     * @return A pointer to the newly created SwapChain or nullptr if it couldn't be created.
+     * @return A pointer to the newly created SwapChain.
      *
      * @see Renderer.beginFrame()
      */
-    SwapChain* createSwapChain(uint32_t width, uint32_t height, uint64_t flags = 0) noexcept;
+    SwapChain* UTILS_NONNULL createSwapChain(uint32_t width, uint32_t height, uint64_t flags = 0) noexcept;
 
     /**
      * Creates a renderer associated to this engine.
      *
      * A Renderer is intended to map to a *window* on screen.
      *
-     * @return A pointer to the newly created Renderer or nullptr if it couldn't be created.
+     * @return A pointer to the newly created Renderer.
      */
-    Renderer* createRenderer() noexcept;
+    Renderer* UTILS_NONNULL createRenderer() noexcept;
 
     /**
      * Creates a View.
      *
-     * @return A pointer to the newly created View or nullptr if it couldn't be created.
+     * @return A pointer to the newly created View.
      */
-    View* createView() noexcept;
+    View* UTILS_NONNULL createView() noexcept;
 
     /**
      * Creates a Scene.
      *
-     * @return A pointer to the newly created Scene or nullptr if it couldn't be created.
+     * @return A pointer to the newly created Scene.
      */
-    Scene* createScene() noexcept;
+    Scene* UTILS_NONNULL createScene() noexcept;
 
     /**
      * Creates a Camera component.
      *
      * @param entity Entity to add the camera component to.
-     * @return A pointer to the newly created Camera or nullptr if it couldn't be created.
+     * @return A pointer to the newly created Camera.
      */
-    Camera* createCamera(utils::Entity entity) noexcept;
+    Camera* UTILS_NONNULL createCamera(utils::Entity entity) noexcept;
 
     /**
      * Returns the Camera component of the given entity.
@@ -703,7 +723,7 @@ public:
      *         have a Camera component. The pointer is valid until destroyCameraComponent()
      *         is called or the entity itself is destroyed.
      */
-    Camera* getCameraComponent(utils::Entity entity) noexcept;
+    Camera* UTILS_NULLABLE getCameraComponent(utils::Entity entity) noexcept;
 
     /**
      * Destroys the Camera component associated with the given entity.
@@ -715,17 +735,17 @@ public:
     /**
      * Creates a Fence.
      *
-     * @return A pointer to the newly created Fence or nullptr if it couldn't be created.
+     * @return A pointer to the newly created Fence.
      */
-    Fence* createFence() noexcept;
+    Fence* UTILS_NONNULL createFence() noexcept;
 
-    bool destroy(const BufferObject* p);        //!< Destroys a BufferObject object.
-    bool destroy(const VertexBuffer* p);        //!< Destroys an VertexBuffer object.
-    bool destroy(const Fence* p);               //!< Destroys a Fence object.
-    bool destroy(const IndexBuffer* p);         //!< Destroys an IndexBuffer object.
-    bool destroy(const SkinningBuffer* p);      //!< Destroys a SkinningBuffer object.
-    bool destroy(const MorphTargetBuffer* p);   //!< Destroys a MorphTargetBuffer object.
-    bool destroy(const IndirectLight* p);       //!< Destroys an IndirectLight object.
+    bool destroy(const BufferObject* UTILS_NULLABLE p);         //!< Destroys a BufferObject object.
+    bool destroy(const VertexBuffer* UTILS_NULLABLE p);         //!< Destroys an VertexBuffer object.
+    bool destroy(const Fence* UTILS_NULLABLE p);                //!< Destroys a Fence object.
+    bool destroy(const IndexBuffer* UTILS_NULLABLE p);          //!< Destroys an IndexBuffer object.
+    bool destroy(const SkinningBuffer* UTILS_NULLABLE p);       //!< Destroys a SkinningBuffer object.
+    bool destroy(const MorphTargetBuffer* UTILS_NULLABLE p);    //!< Destroys a MorphTargetBuffer object.
+    bool destroy(const IndirectLight* UTILS_NULLABLE p);        //!< Destroys an IndirectLight object.
 
     /**
      * Destroys a Material object
@@ -735,38 +755,38 @@ public:
      * @exception utils::PreConditionPanic is thrown if some MaterialInstances remain.
      * no-op if exceptions are disabled and some MaterialInstances remain.
      */
-    bool destroy(const Material* p);
-    bool destroy(const MaterialInstance* p);    //!< Destroys a MaterialInstance object.
-    bool destroy(const Renderer* p);            //!< Destroys a Renderer object.
-    bool destroy(const Scene* p);               //!< Destroys a Scene object.
-    bool destroy(const Skybox* p);              //!< Destroys a SkyBox object.
-    bool destroy(const ColorGrading* p);        //!< Destroys a ColorGrading object.
-    bool destroy(const SwapChain* p);           //!< Destroys a SwapChain object.
-    bool destroy(const Stream* p);              //!< Destroys a Stream object.
-    bool destroy(const Texture* p);             //!< Destroys a Texture object.
-    bool destroy(const RenderTarget* p);        //!< Destroys a RenderTarget object.
-    bool destroy(const View* p);                //!< Destroys a View object.
-    bool destroy(const InstanceBuffer* p);      //!< Destroys an InstanceBuffer object.
-    void destroy(utils::Entity e);              //!< Destroys all filament-known components from this entity
+    bool destroy(const Material* UTILS_NULLABLE p);
+    bool destroy(const MaterialInstance* UTILS_NULLABLE p); //!< Destroys a MaterialInstance object.
+    bool destroy(const Renderer* UTILS_NULLABLE p);         //!< Destroys a Renderer object.
+    bool destroy(const Scene* UTILS_NULLABLE p);            //!< Destroys a Scene object.
+    bool destroy(const Skybox* UTILS_NULLABLE p);           //!< Destroys a SkyBox object.
+    bool destroy(const ColorGrading* UTILS_NULLABLE p);     //!< Destroys a ColorGrading object.
+    bool destroy(const SwapChain* UTILS_NULLABLE p);        //!< Destroys a SwapChain object.
+    bool destroy(const Stream* UTILS_NULLABLE p);           //!< Destroys a Stream object.
+    bool destroy(const Texture* UTILS_NULLABLE p);          //!< Destroys a Texture object.
+    bool destroy(const RenderTarget* UTILS_NULLABLE p);     //!< Destroys a RenderTarget object.
+    bool destroy(const View* UTILS_NULLABLE p);             //!< Destroys a View object.
+    bool destroy(const InstanceBuffer* UTILS_NULLABLE p);   //!< Destroys an InstanceBuffer object.
+    void destroy(utils::Entity e);    //!< Destroys all filament-known components from this entity
 
-    bool isValid(const BufferObject* p);        //!< Tells whether a BufferObject object is valid
-    bool isValid(const VertexBuffer* p);        //!< Tells whether an VertexBuffer object is valid
-    bool isValid(const Fence* p);               //!< Tells whether a Fence object is valid
-    bool isValid(const IndexBuffer* p);         //!< Tells whether an IndexBuffer object is valid
-    bool isValid(const SkinningBuffer* p);      //!< Tells whether a SkinningBuffer object is valid
-    bool isValid(const MorphTargetBuffer* p);   //!< Tells whether a MorphTargetBuffer object is valid
-    bool isValid(const IndirectLight* p);       //!< Tells whether an IndirectLight object is valid
-    bool isValid(const Material* p);            //!< Tells whether an IndirectLight object is valid
-    bool isValid(const Renderer* p);            //!< Tells whether a Renderer object is valid
-    bool isValid(const Scene* p);               //!< Tells whether a Scene object is valid
-    bool isValid(const Skybox* p);              //!< Tells whether a SkyBox object is valid
-    bool isValid(const ColorGrading* p);        //!< Tells whether a ColorGrading object is valid
-    bool isValid(const SwapChain* p);           //!< Tells whether a SwapChain object is valid
-    bool isValid(const Stream* p);              //!< Tells whether a Stream object is valid
-    bool isValid(const Texture* p);             //!< Tells whether a Texture object is valid
-    bool isValid(const RenderTarget* p);        //!< Tells whether a RenderTarget object is valid
-    bool isValid(const View* p);                //!< Tells whether a View object is valid
-    bool isValid(const InstanceBuffer* p);      //!< Tells whether an InstanceBuffer object is valid
+    bool isValid(const BufferObject* UTILS_NULLABLE p);        //!< Tells whether a BufferObject object is valid
+    bool isValid(const VertexBuffer* UTILS_NULLABLE p);        //!< Tells whether an VertexBuffer object is valid
+    bool isValid(const Fence* UTILS_NULLABLE p);               //!< Tells whether a Fence object is valid
+    bool isValid(const IndexBuffer* UTILS_NULLABLE p);         //!< Tells whether an IndexBuffer object is valid
+    bool isValid(const SkinningBuffer* UTILS_NULLABLE p);      //!< Tells whether a SkinningBuffer object is valid
+    bool isValid(const MorphTargetBuffer* UTILS_NULLABLE p);   //!< Tells whether a MorphTargetBuffer object is valid
+    bool isValid(const IndirectLight* UTILS_NULLABLE p);       //!< Tells whether an IndirectLight object is valid
+    bool isValid(const Material* UTILS_NULLABLE p);            //!< Tells whether an IndirectLight object is valid
+    bool isValid(const Renderer* UTILS_NULLABLE p);            //!< Tells whether a Renderer object is valid
+    bool isValid(const Scene* UTILS_NULLABLE p);               //!< Tells whether a Scene object is valid
+    bool isValid(const Skybox* UTILS_NULLABLE p);              //!< Tells whether a SkyBox object is valid
+    bool isValid(const ColorGrading* UTILS_NULLABLE p);        //!< Tells whether a ColorGrading object is valid
+    bool isValid(const SwapChain* UTILS_NULLABLE p);           //!< Tells whether a SwapChain object is valid
+    bool isValid(const Stream* UTILS_NULLABLE p);              //!< Tells whether a Stream object is valid
+    bool isValid(const Texture* UTILS_NULLABLE p);             //!< Tells whether a Texture object is valid
+    bool isValid(const RenderTarget* UTILS_NULLABLE p);        //!< Tells whether a RenderTarget object is valid
+    bool isValid(const View* UTILS_NULLABLE p);                //!< Tells whether a View object is valid
+    bool isValid(const InstanceBuffer* UTILS_NULLABLE p);      //!< Tells whether an InstanceBuffer object is valid
 
     /**
      * Kicks the hardware thread (e.g. the OpenGL, Vulkan or Metal thread) and blocks until
@@ -806,7 +826,7 @@ public:
      *
      * @return A pointer to the default Material instance (a singleton).
      */
-    const Material* getDefaultMaterial() const noexcept;
+    Material const* UTILS_NONNULL getDefaultMaterial() const noexcept;
 
     /**
      * Returns the resolved backend.
@@ -837,7 +857,7 @@ public:
      * @return A pointer to the Platform object that was provided to Engine::create, or the
      * Filament-created one.
      */
-    Platform* getPlatform() const noexcept;
+    Platform* UTILS_NULLABLE getPlatform() const noexcept;
 
     /**
      * Allocate a small amount of memory directly in the command stream. The allocated memory is
@@ -850,7 +870,7 @@ public:
      * @note there is no need to destroy this buffer, it will be freed automatically when
      *       the current command buffer is executed.
      */
-    void* streamAlloc(size_t size, size_t alignment = alignof(double)) noexcept;
+    void* UTILS_NULLABLE streamAlloc(size_t size, size_t alignment = alignof(double)) noexcept;
 
     /**
       * Invokes one iteration of the render loop, used only on single-threaded platforms.

filament/include/filament/Fence.h

@@ -25,6 +25,8 @@
 
 #include <utils/compiler.h>
 
+#include <stdint.h>
+
 namespace filament {
 
 /**
@@ -74,7 +76,7 @@ public:
      * @return  FenceStatus::CONDITION_SATISFIED on success,
      *          FenceStatus::ERROR otherwise.
      */
-    static FenceStatus waitAndDestroy(Fence* fence, Mode mode = Mode::FLUSH);
+    static FenceStatus waitAndDestroy(Fence* UTILS_NONNULL fence, Mode mode = Mode::FLUSH);
 
 protected:
     // prevent heap allocation

filament/include/filament/Frustum.h

@@ -23,9 +23,12 @@
 
 #include <math/mat4.h>
 #include <math/vec3.h>
+#include <math/vec4.h>
 
 #include <utils/unwindows.h> // Because we define NEAR and FAR in the Plane enum.
 
+#include <stdint.h>
+
 namespace filament {
 
 class Box;
@@ -76,14 +79,14 @@ public:
      * @param planes six plane equations encoded as in getNormalizedPlane() in
      *              left, right, bottom, top, far, near order
      */
-    void getNormalizedPlanes(math::float4 planes[6]) const noexcept;
+    void getNormalizedPlanes(math::float4 planes[UTILS_NONNULL 6]) const noexcept;
 
     /**
      * Returns all six frustum planes in left, right, bottom, top, far, near order
      * @return six plane equations encoded as in getNormalizedPlane() in
      *              left, right, bottom, top, far, near order
      */
-    math::float4 const* getNormalizedPlanes() const noexcept { return mPlanes; }
+    math::float4 const* UTILS_NONNULL getNormalizedPlanes() const noexcept { return mPlanes; }
 
     /**
      * Returns whether a box intersects the frustum (i.e. is visible)

filament/include/filament/IndexBuffer.h

@@ -27,6 +27,7 @@
 
 #include <utils/compiler.h>
 
+#include <stdint.h>
 #include <stddef.h>
 
 namespace filament {
@@ -88,8 +89,7 @@ public:
          *
          * @param engine Reference to the filament::Engine to associate this IndexBuffer with.
          *
-         * @return pointer to the newly created object or nullptr if exceptions are disabled and
-         *         an error occurred.
+         * @return pointer to the newly created object.
          *
          * @exception utils::PostConditionPanic if a runtime error occurred, such as running out of
          *            memory or other resources.
@@ -97,7 +97,7 @@ public:
          *
          * @see IndexBuffer::setBuffer
          */
-        IndexBuffer* build(Engine& engine);
+        IndexBuffer* UTILS_NONNULL build(Engine& engine);
     private:
         friend class FIndexBuffer;
     };

filament/include/filament/IndirectLight.h

@@ -25,6 +25,8 @@
 
 #include <math/mathfwd.h>
 
+#include <stdint.h>
+
 namespace filament {
 
 class Engine;
@@ -114,7 +116,7 @@ public:
          * @return This Builder, for chaining calls.
          *
          */
-        Builder& reflections(Texture const* cubemap) noexcept;
+        Builder& reflections(Texture const* UTILS_NULLABLE cubemap) noexcept;
 
         /**
          * Sets the irradiance as Spherical Harmonics.
@@ -160,7 +162,7 @@ public:
          * Because the coefficients are pre-scaled, `sh[0]` is the environment's
          * average irradiance.
          */
-        Builder& irradiance(uint8_t bands, math::float3 const* sh) noexcept;
+        Builder& irradiance(uint8_t bands, math::float3 const* UTILS_NONNULL sh) noexcept;
 
         /**
          * Sets the irradiance from the radiance expressed as Spherical Harmonics.
@@ -192,7 +194,7 @@ public:
          *
          * @return This Builder, for chaining calls.
          */
-        Builder& radiance(uint8_t bands, math::float3 const* sh) noexcept;
+        Builder& radiance(uint8_t bands, math::float3 const* UTILS_NONNULL sh) noexcept;
 
         /**
          * Sets the irradiance as a cubemap.
@@ -211,7 +213,7 @@ public:
          *
          * @see irradiance(uint8_t bands, math::float3 const* sh)
          */
-        Builder& irradiance(Texture const* cubemap) noexcept;
+        Builder& irradiance(Texture const* UTILS_NULLABLE cubemap) noexcept;
 
         /**
          * (optional) Environment intensity.
@@ -247,7 +249,7 @@ public:
          *            memory or other resources.
          * @exception utils::PreConditionPanic if a parameter to a builder function was invalid.
          */
-        IndirectLight* build(Engine& engine);
+        IndirectLight* UTILS_NONNULL build(Engine& engine);
 
     private:
         friend class FIndirectLight;
@@ -284,12 +286,12 @@ public:
     /**
      * Returns the associated reflection map, or null if it does not exist.
      */
-    Texture const* getReflectionsTexture() const noexcept;
+    Texture const* UTILS_NULLABLE getReflectionsTexture() const noexcept;
 
     /**
      * Returns the associated irradiance map, or null if it does not exist.
      */
-    Texture const* getIrradianceTexture() const noexcept;
+    Texture const* UTILS_NULLABLE getIrradianceTexture() const noexcept;
 
     /**
      * Helper to estimate the direction of the dominant light in the environment represented by
@@ -312,7 +314,7 @@ public:
      * @see LightManager::Builder::direction()
      * @see getColorEstimate()
      */
-    static math::float3 getDirectionEstimate(const math::float3 sh[9]) noexcept;
+    static math::float3 getDirectionEstimate(const math::float3 sh[UTILS_NONNULL 9]) noexcept;
 
     /**
      * Helper to estimate the color and relative intensity of the environment represented by
@@ -332,7 +334,8 @@ public:
      * @see LightManager::Builder::intensity()
      * @see getDirectionEstimate, getIntensity, setIntensity
      */
-    static math::float4 getColorEstimate(const math::float3 sh[9], math::float3 direction) noexcept;
+    static math::float4 getColorEstimate(const math::float3 sh[UTILS_NONNULL 9],
+            math::float3 direction) noexcept;
 
 
     /** @deprecated use static versions instead */

filament/include/filament/InstanceBuffer.h

@@ -18,11 +18,14 @@
 #define TNT_FILAMENT_INSTANCEBUFFER_H
 
 #include <filament/FilamentAPI.h>
-
 #include <filament/Engine.h>
 
+#include <utils/compiler.h>
+
 #include <math/mathfwd.h>
 
+#include <stddef.h>
+
 namespace filament {
 
 /**
@@ -45,7 +48,7 @@ public:
          *                      >= 1 and <= \c Engine::getMaxAutomaticInstances()
          * @see Engine::getMaxAutomaticInstances
          */
-        Builder(size_t instanceCount) noexcept;
+        explicit Builder(size_t instanceCount) noexcept;
 
         Builder(Builder const& rhs) noexcept;
         Builder(Builder&& rhs) noexcept;
@@ -65,12 +68,12 @@ public:
          * @param localTransforms an array of math::mat4f with length instanceCount, must remain
          *                        valid until after build() is called
          */
-        Builder& localTransforms(math::mat4f const* localTransforms) noexcept;
+        Builder& localTransforms(math::mat4f const* UTILS_NULLABLE localTransforms) noexcept;
 
         /**
          * Creates the InstanceBuffer object and returns a pointer to it.
          */
-        InstanceBuffer* build(Engine& engine);
+        InstanceBuffer* UTILS_NONNULL build(Engine& engine);
 
     private:
         friend class FInstanceBuffer;
@@ -90,7 +93,8 @@ public:
      * @param count the number of local transforms
      * @param offset index of the first instance to set local transforms
      */
-    void setLocalTransforms(math::mat4f const* localTransforms, size_t count, size_t offset = 0);
+    void setLocalTransforms(math::mat4f const* UTILS_NONNULL localTransforms,
+            size_t count, size_t offset = 0);
 
 protected:
     // prevent heap allocation

filament/include/filament/LightManager.h

@@ -27,6 +27,9 @@
 #include <math/mathfwd.h>
 #include <math/quat.h>
 
+#include <stdint.h>
+#include <stddef.h>
+
 namespace utils {
     class Entity;
 } // namespace utils
@@ -173,7 +176,7 @@ public:
      * Retrieve the Entities of all the components of this manager.
      * @return A list, in no particular order, of all the entities managed by this manager.
      */
-    utils::Entity const* getEntities() const noexcept;
+    utils::Entity const* UTILS_NONNULL getEntities() const noexcept;
 
     /**
      * Gets an Instance representing the Light component associated with the given Entity.
@@ -391,7 +394,7 @@ public:
          *                          positions into
          * @param cascades          the number of shadow cascades, at most 4
          */
-        static void computeUniformSplits(float* splitPositions, uint8_t cascades);
+        static void computeUniformSplits(float* UTILS_NONNULL splitPositions, uint8_t cascades);
 
         /**
          * Utility method to compute ShadowOptions::cascadeSplitPositions according to a logarithmic
@@ -403,7 +406,7 @@ public:
          * @param near              the camera near plane
          * @param far               the camera far plane
          */
-        static void computeLogSplits(float* splitPositions, uint8_t cascades,
+        static void computeLogSplits(float* UTILS_NONNULL splitPositions, uint8_t cascades,
                 float near, float far);
 
         /**
@@ -423,7 +426,7 @@ public:
          * @param lambda            a float in the range [0, 1] that interpolates between log and
          *                          uniform split schemes
          */
-        static void computePracticalSplits(float* splitPositions, uint8_t cascades,
+        static void computePracticalSplits(float* UTILS_NONNULL splitPositions, uint8_t cascades,
                 float near, float far, float lambda);
     };
 

filament/include/filament/Material.h

@@ -30,7 +30,12 @@
 
 #include <math/mathfwd.h>
 
+#include <type_traits>
+#include <utility>
+
+#include <stddef.h>
 #include <stdint.h>
+#include <string.h>
 
 namespace utils {
     class CString;
@@ -69,7 +74,7 @@ public:
      */
     struct ParameterInfo {
         //! Name of the parameter.
-        const char* name;
+        const char* UTILS_NONNULL name;
         //! Whether the parameter is a sampler (texture).
         bool isSampler;
         //! Whether the parameter is a subpass type.
@@ -105,7 +110,7 @@ public:
          * @param payload Pointer to the material data, must stay valid until build() is called.
          * @param size Size of the material data pointed to by "payload" in bytes.
          */
-        Builder& package(const void* payload, size_t size);
+        Builder& package(const void* UTILS_NONNULL payload, size_t size);
 
         template<typename T>
         using is_supported_constant_parameter_t = typename std::enable_if<
@@ -127,11 +132,11 @@ public:
          *              in the material definition.
          */
         template<typename T, typename = is_supported_constant_parameter_t<T>>
-        Builder& constant(const char* name, size_t nameLength, T value);
+        Builder& constant(const char* UTILS_NONNULL name, size_t nameLength, T value);
 
         /** inline helper to provide the constant name as a null-terminated C string */
         template<typename T, typename = is_supported_constant_parameter_t<T>>
-        inline Builder& constant(const char* name, T value) {
+        inline Builder& constant(const char* UTILS_NONNULL name, T value) {
             return constant(name, strlen(name), value);
         }
 
@@ -147,7 +152,7 @@ public:
          *            memory or other resources.
          * @exception utils::PreConditionPanic if a parameter to a builder function was invalid.
          */
-        Material* build(Engine& engine);
+        Material* UTILS_NULLABLE build(Engine& engine);
     private:
         friend class FMaterial;
     };
@@ -193,22 +198,22 @@ public:
      */
     void compile(CompilerPriorityQueue priority,
             UserVariantFilterMask variants,
-            backend::CallbackHandler* handler = nullptr,
-            utils::Invocable<void(Material*)>&& callback = {}) noexcept;
+            backend::CallbackHandler* UTILS_NULLABLE handler = nullptr,
+            utils::Invocable<void(Material* UTILS_NONNULL)>&& callback = {}) noexcept;
 
     inline void compile(CompilerPriorityQueue priority,
             UserVariantFilterBit variants,
-            backend::CallbackHandler* handler = nullptr,
-            utils::Invocable<void(Material*)>&& callback = {}) noexcept {
+            backend::CallbackHandler* UTILS_NULLABLE handler = nullptr,
+            utils::Invocable<void(Material* UTILS_NONNULL)>&& callback = {}) noexcept {
         compile(priority, UserVariantFilterMask(variants), handler,
-                std::forward<utils::Invocable<void(Material*)>>(callback));
+                std::forward<utils::Invocable<void(Material* UTILS_NONNULL)>>(callback));
     }
 
     inline void compile(CompilerPriorityQueue priority,
-            backend::CallbackHandler* handler = nullptr,
-            utils::Invocable<void(Material*)>&& callback = {}) noexcept {
+            backend::CallbackHandler* UTILS_NULLABLE handler = nullptr,
+            utils::Invocable<void(Material* UTILS_NONNULL)>&& callback = {}) noexcept {
         compile(priority, UserVariantFilterBit::ALL, handler,
-                std::forward<utils::Invocable<void(Material*)>>(callback));
+                std::forward<utils::Invocable<void(Material* UTILS_NONNULL)>>(callback));
     }
 
     /**
@@ -220,13 +225,13 @@ public:
      *
      * @return A pointer to the new instance.
      */
-    MaterialInstance* createInstance(const char* name = nullptr) const noexcept;
+    MaterialInstance* UTILS_NONNULL createInstance(const char* UTILS_NULLABLE name = nullptr) const noexcept;
 
     //! Returns the name of this material as a null-terminated string.
-    const char* getName() const noexcept;
+    const char* UTILS_NONNULL getName() const noexcept;
 
     //! Returns the shading model of this material.
-    Shading getShading()  const noexcept;
+    Shading getShading() const noexcept;
 
     //! Returns the interpolation mode of this material. This affects how variables are interpolated.
     Interpolation getInterpolation() const noexcept;
@@ -312,13 +317,13 @@ public:
      *
      * @return The number of parameters written to the parameters pointer.
      */
-    size_t getParameters(ParameterInfo* parameters, size_t count) const noexcept;
+    size_t getParameters(ParameterInfo* UTILS_NONNULL parameters, size_t count) const noexcept;
 
     //! Indicates whether a parameter of the given name exists on this material.
-    bool hasParameter(const char* name) const noexcept;
+    bool hasParameter(const char* UTILS_NONNULL name) const noexcept;
 
     //! Indicates whether an existing parameter is a sampler or not.
-    bool isSampler(const char* name) const noexcept;
+    bool isSampler(const char* UTILS_NONNULL name) const noexcept;
 
     /**
      * Sets the value of the given parameter on this material's default instance.
@@ -329,7 +334,7 @@ public:
      * @see getDefaultInstance()
      */
     template <typename T>
-    void setDefaultParameter(const char* name, T value) noexcept {
+    void setDefaultParameter(const char* UTILS_NONNULL name, T value) noexcept {
         getDefaultInstance()->setParameter(name, value);
     }
 
@@ -342,8 +347,8 @@ public:
      *
      * @see getDefaultInstance()
      */
-    void setDefaultParameter(const char* name, Texture const* texture,
-            TextureSampler const& sampler) noexcept {
+    void setDefaultParameter(const char* UTILS_NONNULL name,
+            Texture const* UTILS_NULLABLE texture, TextureSampler const& sampler) noexcept {
         getDefaultInstance()->setParameter(name, texture, sampler);
     }
 
@@ -356,7 +361,7 @@ public:
      *
      * @see getDefaultInstance()
      */
-    void setDefaultParameter(const char* name, RgbType type, math::float3 color) noexcept {
+    void setDefaultParameter(const char* UTILS_NONNULL name, RgbType type, math::float3 color) noexcept {
         getDefaultInstance()->setParameter(name, type, color);
     }
 
@@ -369,15 +374,15 @@ public:
      *
      * @see getDefaultInstance()
      */
-    void setDefaultParameter(const char* name, RgbaType type, math::float4 color) noexcept {
+    void setDefaultParameter(const char* UTILS_NONNULL name, RgbaType type, math::float4 color) noexcept {
         getDefaultInstance()->setParameter(name, type, color);
     }
 
     //! Returns this material's default instance.
-    MaterialInstance* getDefaultInstance() noexcept;
+    MaterialInstance* UTILS_NONNULL getDefaultInstance() noexcept;
 
     //! Returns this material's default instance.
-    MaterialInstance const* getDefaultInstance() const noexcept;
+    MaterialInstance const* UTILS_NONNULL getDefaultInstance() const noexcept;
 
 protected:
     // prevent heap allocation

filament/include/filament/MaterialInstance.h

@@ -28,6 +28,12 @@
 
 #include <math/mathfwd.h>
 
+#include <type_traits>
+
+#include <stddef.h>
+#include <stdint.h>
+#include <string.h>
+
 namespace filament {
 
 class Material;
@@ -41,7 +47,7 @@ class UTILS_PUBLIC MaterialInstance : public FilamentAPI {
     using StringLiteralHelper = const char[N];
 
     struct StringLiteral {
-        const char* data;
+        const char* UTILS_NONNULL data;
         size_t size;
         template<size_t N>
         StringLiteral(StringLiteralHelper<N> const& s) noexcept // NOLINT(google-explicit-constructor)
@@ -89,17 +95,18 @@ public:
      * @param name  A name for the new MaterialInstance or nullptr to use the template's name
      * @return      A new MaterialInstance
      */
-    static MaterialInstance* duplicate(MaterialInstance const* other, const char* name = nullptr) noexcept;
+    static MaterialInstance* UTILS_NONNULL duplicate(MaterialInstance const* UTILS_NONNULL other,
+            const char* UTILS_NULLABLE name = nullptr) noexcept;
 
     /**
      * @return the Material associated with this instance
      */
-    Material const* getMaterial() const noexcept;
+    Material const* UTILS_NONNULL getMaterial() const noexcept;
 
     /**
      * @return the name associated with this instance
      */
-    const char* getName() const noexcept;
+    const char* UTILS_NONNULL getName() const noexcept;
 
     /**
      * Set a uniform by name
@@ -110,7 +117,7 @@ public:
      * @throws utils::PreConditionPanic if name doesn't exist or no-op if exceptions are disabled.
      */
     template<typename T, typename = is_supported_parameter_t<T>>
-    void setParameter(const char* name, size_t nameLength, T const& value);
+    void setParameter(const char* UTILS_NONNULL name, size_t nameLength, T const& value);
 
     /** inline helper to provide the name as a null-terminated string literal */
     template<typename T, typename = is_supported_parameter_t<T>>
@@ -120,7 +127,7 @@ public:
 
     /** inline helper to provide the name as a null-terminated C string */
     template<typename T, typename = is_supported_parameter_t<T>>
-    inline void setParameter(const char* name, T const& value) {
+    inline void setParameter(const char* UTILS_NONNULL name, T const& value) {
         setParameter<T>(name, strlen(name), value);
     }
 
@@ -135,17 +142,19 @@ public:
      * @throws utils::PreConditionPanic if name doesn't exist or no-op if exceptions are disabled.
      */
     template<typename T, typename = is_supported_parameter_t<T>>
-    void setParameter(const char* name, size_t nameLength, const T* values, size_t count);
+    void setParameter(const char* UTILS_NONNULL name, size_t nameLength,
+            const T* UTILS_NONNULL values, size_t count);
 
     /** inline helper to provide the name as a null-terminated string literal */
     template<typename T, typename = is_supported_parameter_t<T>>
-    inline void setParameter(StringLiteral name, const T* values, size_t count) {
+    inline void setParameter(StringLiteral name, const T* UTILS_NONNULL values, size_t count) {
         setParameter<T>(name.data, name.size, values, count);
     }
 
     /** inline helper to provide the name as a null-terminated C string */
     template<typename T, typename = is_supported_parameter_t<T>>
-    inline void setParameter(const char* name, const T* values, size_t count) {
+    inline void setParameter(const char* UTILS_NONNULL name,
+            const T* UTILS_NONNULL values, size_t count) {
         setParameter<T>(name, strlen(name), values, count);
     }
 
@@ -162,18 +171,18 @@ public:
      * @param sampler       Sampler parameters.
      * @throws utils::PreConditionPanic if name doesn't exist or no-op if exceptions are disabled.
      */
-    void setParameter(const char* name, size_t nameLength,
-            Texture const* texture, TextureSampler const& sampler);
+    void setParameter(const char* UTILS_NONNULL name, size_t nameLength,
+            Texture const* UTILS_NULLABLE texture, TextureSampler const& sampler);
 
     /** inline helper to provide the name as a null-terminated string literal */
     inline void setParameter(StringLiteral name,
-            Texture const* texture, TextureSampler const& sampler) {
+            Texture const* UTILS_NULLABLE texture, TextureSampler const& sampler) {
         setParameter(name.data, name.size, texture, sampler);
     }
 
     /** inline helper to provide the name as a null-terminated C string */
-    inline void setParameter(const char* name,
-            Texture const* texture, TextureSampler const& sampler) {
+    inline void setParameter(const char* UTILS_NONNULL name,
+            Texture const* UTILS_NULLABLE texture, TextureSampler const& sampler) {
         setParameter(name, strlen(name), texture, sampler);
     }
 
@@ -188,7 +197,8 @@ public:
      * @param color         Array of read, green, blue channels values.
      * @throws utils::PreConditionPanic if name doesn't exist or no-op if exceptions are disabled.
      */
-    void setParameter(const char* name, size_t nameLength, RgbType type, math::float3 color);
+    void setParameter(const char* UTILS_NONNULL name, size_t nameLength,
+            RgbType type, math::float3 color);
 
     /** inline helper to provide the name as a null-terminated string literal */
     inline void setParameter(StringLiteral name, RgbType type, math::float3 color) {
@@ -196,7 +206,7 @@ public:
     }
 
     /** inline helper to provide the name as a null-terminated C string */
-    inline void setParameter(const char* name, RgbType type, math::float3 color) {
+    inline void setParameter(const char* UTILS_NONNULL name, RgbType type, math::float3 color) {
         setParameter(name, strlen(name), type, color);
     }
 
@@ -211,7 +221,8 @@ public:
      * @param color         Array of read, green, blue and alpha channels values.
      * @throws utils::PreConditionPanic if name doesn't exist or no-op if exceptions are disabled.
      */
-    void setParameter(const char* name, size_t nameLength, RgbaType type, math::float4 color);
+    void setParameter(const char* UTILS_NONNULL name, size_t nameLength,
+            RgbaType type, math::float4 color);
 
     /** inline helper to provide the name as a null-terminated string literal */
     inline void setParameter(StringLiteral name, RgbaType type, math::float4 color) {
@@ -219,7 +230,7 @@ public:
     }
 
     /** inline helper to provide the name as a null-terminated C string */
-    inline void setParameter(const char* name, RgbaType type, math::float4 color) {
+    inline void setParameter(const char* UTILS_NONNULL name, RgbaType type, math::float4 color) {
         setParameter(name, strlen(name), type, color);
     }
 

filament/include/filament/MorphTargetBuffer.h

@@ -21,8 +21,11 @@
 
 #include <filament/Engine.h>
 
+#include <utils/compiler.h>
+
 #include <math/mathfwd.h>
 
+#include <stddef.h>
 
 namespace filament {
 
@@ -65,14 +68,13 @@ public:
          *
          * @param engine Reference to the filament::Engine to associate this MorphTargetBuffer with.
          *
-         * @return pointer to the newly created object or nullptr if exceptions are disabled and
-         *         an error occurred.
+         * @return pointer to the newly created object.
          *
          * @exception utils::PostConditionPanic if a runtime error occurred, such as running out of
          *            memory or other resources.
          * @exception utils::PreConditionPanic if a parameter to a builder function was invalid.
          */
-        MorphTargetBuffer* build(Engine& engine);
+        MorphTargetBuffer* UTILS_NONNULL build(Engine& engine);
     private:
         friend class FMorphTargetBuffer;
     };
@@ -92,7 +94,7 @@ public:
      * @see setTangentsAt
      */
     void setPositionsAt(Engine& engine, size_t targetIndex,
-            math::float3 const* positions, size_t count, size_t offset = 0);
+            math::float3 const* UTILS_NONNULL positions, size_t count, size_t offset = 0);
 
     /**
      * Updates positions for the given morph target.
@@ -107,7 +109,7 @@ public:
      * @see setTangentsAt
      */
     void setPositionsAt(Engine& engine, size_t targetIndex,
-            math::float4 const* positions, size_t count, size_t offset = 0);
+            math::float4 const* UTILS_NONNULL positions, size_t count, size_t offset = 0);
 
     /**
      * Updates tangents for the given morph target.
@@ -123,7 +125,7 @@ public:
      * @see setPositionsAt
      */
     void setTangentsAt(Engine& engine, size_t targetIndex,
-            math::short4 const* tangents, size_t count, size_t offset = 0);
+            math::short4 const* UTILS_NONNULL tangents, size_t count, size_t offset = 0);
 
     /**
      * Returns the vertex count of this MorphTargetBuffer.

filament/include/filament/Options.h

@@ -19,10 +19,13 @@
 
 #include <filament/Color.h>
 
-#include <stdint.h>
+#include <math/vec2.h>
+#include <math/vec3.h>
 
 #include <math.h>
 
+#include <stdint.h>
+
 namespace filament {
 
 class Texture;
@@ -293,6 +296,7 @@ struct DepthOfFieldOptions {
         MEDIAN
     };
     float cocScale = 1.0f;              //!< circle of confusion scale factor (amount of blur)
+    float cocAspectRatio = 1.0f;        //!< width/height aspect ratio of the circle of confusion (simulate anamorphic lenses)
     float maxApertureDiameter = 0.01f;  //!< maximum aperture diameter in meters (zero to disable rotation)
     bool enabled = false;               //!< enable or disable depth of field effect
     Filter filter = Filter::MEDIAN;     //!< filter to use for filling gaps in the kernel
@@ -437,6 +441,7 @@ struct TemporalAntiAliasingOptions {
     float filterWidth = 1.0f;   //!< reconstruction filter width typically between 0.2 (sharper, aliased) and 1.5 (smoother)
     float feedback = 0.12f;     //!< history feedback, between 0 (maximum temporal AA) and 1 (no temporal AA).
     float lodBias = -1.0f;      //!< texturing lod bias (typically -1 or -2)
+    float sharpness = 0.0f;     //!< post-TAA sharpen, especially useful when upscaling is true.
     bool enabled = false;       //!< enables or disables temporal anti-aliasing
     bool upscaling = false;     //!< 4x TAA upscaling. Disables Dynamic Resolution. [BETA]
 
@@ -456,7 +461,8 @@ struct TemporalAntiAliasingOptions {
         RGSS_X4,             //!  4-samples, rotated grid sampling
         UNIFORM_HELIX_X4,    //!  4-samples, uniform grid in helix sequence
         HALTON_23_X8,        //!  8-samples of halton 2,3
-        HALTON_23_X16        //! 16-samples of halton 2,3
+        HALTON_23_X16,       //! 16-samples of halton 2,3
+        HALTON_23_X32        //! 32-samples of halton 2,3
     };
 
     bool filterHistory = true;      //!< whether to filter the history buffer

filament/include/filament/RenderTarget.h

@@ -24,7 +24,10 @@
 #include <backend/DriverEnums.h>
 #include <backend/TargetBufferInfo.h>
 
+#include <utils/compiler.h>
+
 #include <stddef.h>
+#include <stdint.h>
 
 namespace filament {
 
@@ -103,7 +106,7 @@ public:
          * @param texture The associated texture object.
          * @return A reference to this Builder for chaining calls.
          */
-        Builder& texture(AttachmentPoint attachment, Texture* texture) noexcept;
+        Builder& texture(AttachmentPoint attachment, Texture* UTILS_NULLABLE texture) noexcept;
 
         /**
          * Sets the mipmap level for a given attachment point.
@@ -135,10 +138,9 @@ public:
         /**
          * Creates the RenderTarget object and returns a pointer to it.
          *
-         * @return pointer to the newly created object or nullptr if exceptions are disabled and
-         *         an error occurred.
+         * @return pointer to the newly created object.
          */
-        RenderTarget* build(Engine& engine);
+        RenderTarget* UTILS_NONNULL build(Engine& engine);
 
     private:
         friend class FRenderTarget;
@@ -149,7 +151,7 @@ public:
      * @param attachment Attachment point
      * @return A Texture object or nullptr if no texture is set for this attachment point
      */
-    Texture* getTexture(AttachmentPoint attachment) const noexcept;
+    Texture* UTILS_NULLABLE getTexture(AttachmentPoint attachment) const noexcept;
 
     /**
      * Returns the mipmap level set on the given attachment point

filament/include/filament/RenderableManager.h

@@ -29,9 +29,15 @@
 #include <utils/FixedCapacityVector.h>
 
 #include <math/mathfwd.h>
+#include <math/vec3.h>
+#include <math/vec4.h>
 
 #include <type_traits>
 
+#include <float.h>
+#include <stddef.h>
+#include <stdint.h>
+
 namespace utils {
     class Entity;
 } // namespace utils
@@ -123,7 +129,7 @@ public:
      * Retrieve the Entities of all the components of this manager.
      * @return A list, in no particular order, of all the entities managed by this manager.
      */
-    utils::Entity const* getEntities() const noexcept;
+    utils::Entity const* UTILS_NONNULL getEntities() const noexcept;
 
     /**
      * The transformation associated with a skinning joint.
@@ -184,9 +190,19 @@ public:
          * @param maxIndex specifies the maximum index contained in the index buffer
          * @param count number of indices to read (for triangles, this should be a multiple of 3)
          */
-        Builder& geometry(size_t index, PrimitiveType type, VertexBuffer* vertices, IndexBuffer* indices, size_t offset, size_t minIndex, size_t maxIndex, size_t count) noexcept;
-        Builder& geometry(size_t index, PrimitiveType type, VertexBuffer* vertices, IndexBuffer* indices, size_t offset, size_t count) noexcept; //!< \overload
-        Builder& geometry(size_t index, PrimitiveType type, VertexBuffer* vertices, IndexBuffer* indices) noexcept; //!< \overload
+        Builder& geometry(size_t index, PrimitiveType type,
+                VertexBuffer* UTILS_NONNULL vertices,
+                IndexBuffer* UTILS_NONNULL indices,
+                size_t offset, size_t minIndex, size_t maxIndex, size_t count) noexcept;
+
+        Builder& geometry(size_t index, PrimitiveType type,
+                VertexBuffer* UTILS_NONNULL vertices,
+                IndexBuffer* UTILS_NONNULL indices,
+                size_t offset, size_t count) noexcept; //!< \overload
+
+        Builder& geometry(size_t index, PrimitiveType type,
+                VertexBuffer* UTILS_NONNULL vertices,
+                IndexBuffer* UTILS_NONNULL indices) noexcept; //!< \overload
 
         /**
          * Binds a material instance to the specified primitive.
@@ -203,7 +219,8 @@ public:
          *
          * @see Engine::setActiveFeatureLevel
          */
-        Builder& material(size_t index, MaterialInstance const* materialInstance) noexcept;
+        Builder& material(size_t index,
+                MaterialInstance const* UTILS_NONNULL materialInstance) noexcept;
 
         /**
          * The axis-aligned bounding box of the renderable.
@@ -351,7 +368,8 @@ public:
          * @param count 0 to disable, otherwise the number of bone transforms (up to 255)
          * @param offset offset in the SkinningBuffer
          */
-        Builder& skinning(SkinningBuffer* skinningBuffer, size_t count, size_t offset) noexcept;
+        Builder& skinning(SkinningBuffer* UTILS_NONNULL skinningBuffer,
+                size_t count, size_t offset) noexcept;
 
 
         /**
@@ -369,8 +387,8 @@ public:
          * @param boneCount 0 to disable, otherwise the number of bone transforms (up to 255)
          * @param transforms the initial set of transforms (one for each bone)
          */
-        Builder& skinning(size_t boneCount, math::mat4f const* transforms) noexcept;
-        Builder& skinning(size_t boneCount, Bone const* bones) noexcept; //!< \overload
+        Builder& skinning(size_t boneCount, math::mat4f const* UTILS_NONNULL transforms) noexcept;
+        Builder& skinning(size_t boneCount, Bone const* UTILS_NONNULL bones) noexcept; //!< \overload
         Builder& skinning(size_t boneCount) noexcept; //!< \overload
 
         /**
@@ -399,7 +417,8 @@ public:
          * @see VertexBuffer:Builder:advancedSkinning
          */
         Builder& boneIndicesAndWeights(size_t primitiveIndex,
-                math::float2 const* indicesAndWeights, size_t count, size_t bonesPerVertex) noexcept;
+                math::float2 const* UTILS_NONNULL indicesAndWeights,
+                size_t count, size_t bonesPerVertex) noexcept;
 
         /**
          * Define bone indices and weights "pairs" for vertex skinning as a float2.
@@ -462,10 +481,11 @@ public:
          * @param count number of vertices in the morph target buffer to read, must equal the geometry's count (for triangles, this should be a multiple of 3)
          */
         Builder& morphing(uint8_t level, size_t primitiveIndex,
-                MorphTargetBuffer* morphTargetBuffer, size_t offset, size_t count) noexcept;
+                MorphTargetBuffer* UTILS_NONNULL morphTargetBuffer,
+                size_t offset, size_t count) noexcept;
 
         inline Builder& morphing(uint8_t level, size_t primitiveIndex,
-                MorphTargetBuffer* morphTargetBuffer) noexcept;
+                MorphTargetBuffer* UTILS_NONNULL morphTargetBuffer) noexcept;
 
         /**
          * Sets the drawing order for blended primitives. The drawing order is either global or
@@ -532,7 +552,8 @@ public:
          *                      the result of Engine::getMaxAutomaticInstances().
          * @param instanceBuffer an InstanceBuffer containing at least instanceCount transforms
          */
-        Builder& instances(size_t instanceCount, InstanceBuffer* instanceBuffer) noexcept;
+        Builder& instances(size_t instanceCount,
+                InstanceBuffer* UTILS_NONNULL instanceBuffer) noexcept;
 
         /**
          * Adds the Renderable component to an entity.
@@ -559,18 +580,18 @@ public:
         friend class FRenderPrimitive;
         friend class FRenderableManager;
         struct Entry {
-            VertexBuffer* vertices = nullptr;
-            IndexBuffer* indices = nullptr;
+            VertexBuffer* UTILS_NULLABLE vertices = nullptr;
+            IndexBuffer* UTILS_NULLABLE indices = nullptr;
             size_t offset = 0;
             size_t minIndex = 0;
             size_t maxIndex = 0;
             size_t count = 0;
-            MaterialInstance const* materialInstance = nullptr;
+            MaterialInstance const* UTILS_NULLABLE materialInstance = nullptr;
             PrimitiveType type = PrimitiveType::TRIANGLES;
             uint16_t blendOrder = 0;
             bool globalBlendOrderEnabled = false;
             struct {
-                MorphTargetBuffer* buffer = nullptr;
+                MorphTargetBuffer* UTILS_NULLABLE buffer = nullptr;
                 size_t offset = 0;
                 size_t count = 0;
             } morphing;
@@ -688,8 +709,11 @@ public:
      * Updates the bone transforms in the range [offset, offset + boneCount).
      * The bones must be pre-allocated using Builder::skinning().
      */
-    void setBones(Instance instance, Bone const* transforms, size_t boneCount = 1, size_t offset = 0);
-    void setBones(Instance instance, math::mat4f const* transforms, size_t boneCount = 1, size_t offset = 0); //!< \overload
+    void setBones(Instance instance, Bone const* UTILS_NONNULL transforms,
+            size_t boneCount = 1, size_t offset = 0);
+
+    void setBones(Instance instance, math::mat4f const* UTILS_NONNULL transforms,
+            size_t boneCount = 1, size_t offset = 0); //!< \overload
 
     /**
      * Associates a region of a SkinningBuffer to a renderable instance
@@ -702,7 +726,7 @@ public:
      * @param count             Size of the region in bones, must be smaller or equal to 256.
      * @param offset            Start offset of the region in bones
      */
-    void setSkinningBuffer(Instance instance, SkinningBuffer* skinningBuffer,
+    void setSkinningBuffer(Instance instance, SkinningBuffer* UTILS_NONNULL skinningBuffer,
             size_t count, size_t offset);
 
     /**
@@ -717,24 +741,25 @@ public:
      * @param offset Index of the first morph target weight to set at instance.
      */
     void setMorphWeights(Instance instance,
-            float const* weights, size_t count, size_t offset = 0);
+            float const* UTILS_NONNULL weights, size_t count, size_t offset = 0);
 
     /**
      * Associates a MorphTargetBuffer to the given primitive.
      */
     void setMorphTargetBufferAt(Instance instance, uint8_t level, size_t primitiveIndex,
-            MorphTargetBuffer* morphTargetBuffer, size_t offset, size_t count);
+            MorphTargetBuffer* UTILS_NONNULL morphTargetBuffer, size_t offset, size_t count);
 
     /**
      * Utility method to change a MorphTargetBuffer to the given primitive
      */
     inline void setMorphTargetBufferAt(Instance instance, uint8_t level, size_t primitiveIndex,
-            MorphTargetBuffer* morphTargetBuffer);
+            MorphTargetBuffer* UTILS_NONNULL morphTargetBuffer);
 
     /**
      * Get a MorphTargetBuffer to the given primitive or null if it doesn't exist.
      */
-    MorphTargetBuffer* getMorphTargetBufferAt(Instance instance, uint8_t level, size_t primitiveIndex) const noexcept;
+    MorphTargetBuffer* UTILS_NULLABLE getMorphTargetBufferAt(Instance instance,
+            uint8_t level, size_t primitiveIndex) const noexcept;
 
     /**
      * Gets the number of morphing in the given entity.
@@ -776,20 +801,22 @@ public:
      * @see Engine::setActiveFeatureLevel
      */
     void setMaterialInstanceAt(Instance instance,
-            size_t primitiveIndex, MaterialInstance const* materialInstance);
+            size_t primitiveIndex, MaterialInstance const* UTILS_NONNULL materialInstance);
 
     /**
      * Retrieves the material instance that is bound to the given primitive.
      */
-    MaterialInstance* getMaterialInstanceAt(Instance instance, size_t primitiveIndex) const noexcept;
+    MaterialInstance* UTILS_NULLABLE getMaterialInstanceAt(
+            Instance instance, size_t primitiveIndex) const noexcept;
 
     /**
      * Changes the geometry for the given primitive.
      *
      * \see Builder::geometry()
      */
-    void setGeometryAt(Instance instance, size_t primitiveIndex,
-            PrimitiveType type, VertexBuffer* vertices, IndexBuffer* indices,
+    void setGeometryAt(Instance instance, size_t primitiveIndex, PrimitiveType type,
+            VertexBuffer* UTILS_NONNULL vertices,
+            IndexBuffer* UTILS_NONNULL indices,
             size_t offset, size_t count) noexcept;
 
     /**
@@ -850,7 +877,9 @@ public:
     template<typename VECTOR, typename INDEX,
             typename = typename is_supported_vector_type<VECTOR>::type,
             typename = typename is_supported_index_type<INDEX>::type>
-    static Box computeAABB(VECTOR const* vertices, INDEX const* indices, size_t count,
+    static Box computeAABB(
+            VECTOR const* UTILS_NONNULL vertices,
+            INDEX const* UTILS_NONNULL indices, size_t count,
             size_t stride = sizeof(VECTOR)) noexcept;
 
 protected:
@@ -858,23 +887,27 @@ protected:
     ~RenderableManager() = default;
 };
 
-RenderableManager::Builder& RenderableManager::Builder::morphing(uint8_t level, size_t primitiveIndex,
-        MorphTargetBuffer* morphTargetBuffer) noexcept {
+RenderableManager::Builder& RenderableManager::Builder::morphing(
+        uint8_t level, size_t primitiveIndex,
+        MorphTargetBuffer* UTILS_NONNULL morphTargetBuffer) noexcept {
     return morphing(level, primitiveIndex, morphTargetBuffer, 0,
             morphTargetBuffer->getVertexCount());
 }
 
-void RenderableManager::setMorphTargetBufferAt(Instance instance, uint8_t level, size_t primitiveIndex,
-        MorphTargetBuffer* morphTargetBuffer) {
+void RenderableManager::setMorphTargetBufferAt(
+        Instance instance, uint8_t level, size_t primitiveIndex,
+        MorphTargetBuffer* UTILS_NONNULL morphTargetBuffer) {
     setMorphTargetBufferAt(instance, level, primitiveIndex, morphTargetBuffer, 0,
             morphTargetBuffer->getVertexCount());
 }
 
 template<typename VECTOR, typename INDEX, typename, typename>
-Box RenderableManager::computeAABB(VECTOR const* vertices, INDEX const* indices, size_t count,
-        size_t stride) noexcept {
-    math::float3 bmin(std::numeric_limits<float>::max());
-    math::float3 bmax(std::numeric_limits<float>::lowest());
+Box RenderableManager::computeAABB(
+        VECTOR const* UTILS_NONNULL vertices,
+        INDEX const* UTILS_NONNULL indices,
+        size_t count, size_t stride) noexcept {
+    math::float3 bmin(FLT_MAX);
+    math::float3 bmax(-FLT_MAX);
     for (size_t i = 0; i < count; ++i) {
         VECTOR const* p = reinterpret_cast<VECTOR const*>(
                 (char const*)vertices + indices[i] * stride);

filament/include/filament/Renderer.h

@@ -23,9 +23,6 @@
 
 #include <utils/compiler.h>
 
-#include <backend/PresentCallable.h>
-#include <backend/DriverEnums.h>
-
 #include <math/vec4.h>
 
 #include <stdint.h>
@@ -184,14 +181,14 @@ public:
      *
      * @return A pointer to the Engine instance this Renderer is associated to.
      */
-    Engine* getEngine() noexcept;
+    Engine* UTILS_NONNULL getEngine() noexcept;
 
     /**
      * Get the Engine that created this Renderer.
      *
      * @return A constant pointer to the Engine instance this Renderer is associated to.
      */
-    inline Engine const* getEngine() const noexcept {
+    inline Engine const* UTILS_NONNULL getEngine() const noexcept {
         return const_cast<Renderer *>(this)->getEngine();
     }
 
@@ -267,7 +264,7 @@ public:
      * @see
      * endFrame()
      */
-    bool beginFrame(SwapChain* swapChain,
+    bool beginFrame(SwapChain* UTILS_NONNULL swapChain,
             uint64_t vsyncSteadyClockTimeNano = 0u);
 
     /**
@@ -338,7 +335,7 @@ public:
      * beginFrame(), endFrame(), View
      *
      */
-    void render(View const* view);
+    void render(View const* UTILS_NONNULL view);
 
     /**
      * Copy the currently rendered view to the indicated swap chain, using the
@@ -353,7 +350,7 @@ public:
      * copyFrame() should be called after a frame is rendered using render()
      * but before endFrame() is called.
      */
-    void copyFrame(SwapChain* dstSwapChain, Viewport const& dstViewport,
+    void copyFrame(SwapChain* UTILS_NONNULL dstSwapChain, Viewport const& dstViewport,
             Viewport const& srcViewport, uint32_t flags = 0);
 
     /**
@@ -493,7 +490,7 @@ public:
      * readPixels() is intended for debugging and testing. It will impact performance significantly.
      *
      */
-    void readPixels(RenderTarget* renderTarget,
+    void readPixels(RenderTarget* UTILS_NONNULL renderTarget,
             uint32_t xoffset, uint32_t yoffset, uint32_t width, uint32_t height,
             backend::PixelBufferDescriptor&& buffer);
 
@@ -520,7 +517,7 @@ public:
      * However, internally, renderStandaloneView() is highly multi-threaded to both improve
      * performance in mitigate the call's latency.
      */
-    void renderStandaloneView(View const* view);
+    void renderStandaloneView(View const* UTILS_NONNULL view);
 
 
     /**

filament/include/filament/Scene.h

@@ -24,6 +24,8 @@
 #include <utils/compiler.h>
 #include <utils/Invocable.h>
 
+#include <stddef.h>
+
 namespace utils {
     class Entity;
 } // namespace utils
@@ -73,14 +75,14 @@ public:
      *
      * @param skybox The Skybox to use to fill untouched pixels, or nullptr to unset the Skybox.
      */
-    void setSkybox(Skybox* skybox) noexcept;
+    void setSkybox(Skybox* UTILS_NULLABLE skybox) noexcept;
 
     /**
      * Returns the Skybox associated with the Scene.
      *
      * @return The associated Skybox, or nullptr if there is none.
      */
-    Skybox* getSkybox() const noexcept;
+    Skybox* UTILS_NULLABLE getSkybox() const noexcept;
 
     /**
      * Set the IndirectLight to use when rendering the Scene.
@@ -91,7 +93,7 @@ public:
      * @param ibl The IndirectLight to use when rendering the Scene or nullptr to unset.
      * @see getIndirectLight
      */
-    void setIndirectLight(IndirectLight* ibl) noexcept;
+    void setIndirectLight(IndirectLight* UTILS_NULLABLE ibl) noexcept;
 
     /**
      * Get the IndirectLight or nullptr if none is set.
@@ -99,7 +101,7 @@ public:
      * @return the the IndirectLight or nullptr if none is set
      * @see setIndirectLight
      */
-    IndirectLight* getIndirectLight() const noexcept;
+    IndirectLight* UTILS_NULLABLE getIndirectLight() const noexcept;
 
     /**
      * Adds an Entity to the Scene.
@@ -118,7 +120,7 @@ public:
      * @param entities Array containing entities to add to the scene.
      * @param count Size of the entity array.
      */
-    void addEntities(const utils::Entity* entities, size_t count);
+    void addEntities(const utils::Entity* UTILS_NONNULL entities, size_t count);
 
     /**
      * Removes the Renderable from the Scene.
@@ -137,7 +139,7 @@ public:
      * @param entities Array containing entities to remove from the scene.
      * @param count Size of the entity array.
      */
-    void removeEntities(const utils::Entity* entities, size_t count);
+    void removeEntities(const utils::Entity* UTILS_NONNULL entities, size_t count);
 
     /**
      * Returns the total number of Entities in the Scene, whether alive or not.

filament/include/filament/SkinningBuffer.h

@@ -26,7 +26,7 @@
 #include <math/mathfwd.h>
 
 #include <stddef.h>
-
+#include <stdint.h>
 
 namespace filament {
 
@@ -74,8 +74,7 @@ public:
          *
          * @param engine Reference to the filament::Engine to associate this SkinningBuffer with.
          *
-         * @return pointer to the newly created object or nullptr if exceptions are disabled and
-         *         an error occurred.
+         * @return pointer to the newly created object.
          *
          * @exception utils::PostConditionPanic if a runtime error occurred, such as running out of
          *            memory or other resources.
@@ -83,7 +82,7 @@ public:
          *
          * @see SkinningBuffer::setBones
          */
-        SkinningBuffer* build(Engine& engine);
+        SkinningBuffer* UTILS_NONNULL build(Engine& engine);
     private:
         friend class FSkinningBuffer;
     };
@@ -96,7 +95,7 @@ public:
      * @param offset offset in elements (not bytes) in the SkinningBuffer (not in transforms)
      * @see RenderableManager::setSkinningBuffer
      */
-    void setBones(Engine& engine, RenderableManager::Bone const* transforms,
+    void setBones(Engine& engine, RenderableManager::Bone const* UTILS_NONNULL transforms,
             size_t count, size_t offset = 0);
 
     /**
@@ -107,7 +106,7 @@ public:
      * @param offset offset in elements (not bytes) in the SkinningBuffer (not in transforms)
      * @see RenderableManager::setSkinningBuffer
      */
-    void setBones(Engine& engine, math::mat4f const* transforms,
+    void setBones(Engine& engine, math::mat4f const* UTILS_NONNULL transforms,
             size_t count, size_t offset = 0);
 
     /**

filament/include/filament/Skybox.h

@@ -23,9 +23,10 @@
 
 #include <utils/compiler.h>
 
-#include <stdint.h>
 #include <math/mathfwd.h>
 
+#include <stdint.h>
+
 namespace filament {
 
 class FSkybox;
@@ -91,7 +92,7 @@ public:
          *
          * @see Texture
          */
-        Builder& environment(Texture* cubemap) noexcept;
+        Builder& environment(Texture* UTILS_NONNULL cubemap) noexcept;
 
         /**
          * Indicates whether the sun should be rendered. The sun can only be
@@ -135,9 +136,9 @@ public:
          *
          * @param engine Reference to the filament::Engine to associate this Skybox with.
          *
-         * @return pointer to the newly created object, or nullptr if the light couldn't be created.
+         * @return pointer to the newly created object.
          */
-        Skybox* build(Engine& engine);
+        Skybox* UTILS_NONNULL build(Engine& engine);
 
     private:
         friend class FSkybox;
@@ -171,9 +172,9 @@ public:
     float getIntensity() const noexcept;
 
     /**
-     * @return the associated texture, or null if it does not exist
+     * @return the associated texture
      */
-    Texture const* getTexture() const noexcept;
+    Texture const* UTILS_NONNULL getTexture() const noexcept;
 
 protected:
     // prevent heap allocation

filament/include/filament/Stream.h

@@ -20,12 +20,12 @@
 #include <filament/FilamentAPI.h>
 
 #include <backend/DriverEnums.h>
-
-#include <backend/PixelBufferDescriptor.h>
 #include <backend/CallbackHandler.h>
 
 #include <utils/compiler.h>
 
+#include <stdint.h>
+
 namespace filament {
 
 class FStream;
@@ -114,7 +114,7 @@ public:
          *
          * @return This Builder, for chaining calls.
          */
-        Builder& stream(void* stream) noexcept;
+        Builder& stream(void* UTILS_NULLABLE stream) noexcept;
 
         /**
          *
@@ -141,9 +141,9 @@ public:
          *
          * @param engine Reference to the filament::Engine to associate this Stream with.
          *
-         * @return pointer to the newly created object, or nullptr if the stream couldn't be created.
+         * @return pointer to the newly created object.
          */
-        Stream* build(Engine& engine);
+        Stream* UTILS_NONNULL build(Engine& engine);
 
     private:
         friend class FStream;
@@ -171,11 +171,12 @@ public:
      *
      * @param image      Pointer to AHardwareBuffer, casted to void* since this is a public header.
      * @param callback   This is triggered by Filament when it wishes to release the image.
-     *                   It callback tales two arguments: the AHardwareBuffer and the userdata.
+     *                   The callback tales two arguments: the AHardwareBuffer and the userdata.
      * @param userdata   Optional closure data. Filament will pass this into the callback when it
      *                   releases the image.
      */
-    void setAcquiredImage(void* image, Callback callback, void* userdata) noexcept;
+    void setAcquiredImage(void* UTILS_NONNULL image,
+            Callback UTILS_NONNULL callback, void* UTILS_NULLABLE userdata) noexcept;
 
     /**
      * @see setAcquiredImage(void*, Callback, void*)
@@ -187,7 +188,9 @@ public:
      * @param userdata   Optional closure data. Filament will pass this into the callback when it
      *                   releases the image.
      */
-    void setAcquiredImage(void* image, backend::CallbackHandler* handler, Callback callback, void* userdata) noexcept;
+    void setAcquiredImage(void* UTILS_NONNULL image,
+            backend::CallbackHandler* UTILS_NULLABLE handler,
+            Callback UTILS_NONNULL callback, void* UTILS_NULLABLE userdata) noexcept;
 
     /**
      * Updates the size of the incoming stream. Whether this value is used is

filament/include/filament/SwapChain.h

@@ -21,11 +21,12 @@
 
 #include <backend/CallbackHandler.h>
 #include <backend/DriverEnums.h>
-#include <backend/PresentCallable.h>
 
 #include <utils/compiler.h>
 #include <utils/Invocable.h>
 
+#include <stdint.h>
+
 namespace filament {
 
 class Engine;
@@ -151,7 +152,7 @@ class Engine;
 class UTILS_PUBLIC SwapChain : public FilamentAPI {
 public:
     using FrameScheduledCallback = backend::FrameScheduledCallback;
-    using FrameCompletedCallback = utils::Invocable<void(SwapChain*)>;
+    using FrameCompletedCallback = utils::Invocable<void(SwapChain* UTILS_NONNULL)>;
 
     /**
      * Requests a SwapChain with an alpha channel.
@@ -235,7 +236,7 @@ public:
      */
     static bool isSRGBSwapChainSupported(Engine& engine) noexcept;
 
-    void* getNativeWindow() const noexcept;
+    void* UTILS_NULLABLE getNativeWindow() const noexcept;
 
     /**
      * FrameScheduledCallback is a callback function that notifies an application when Filament has
@@ -268,7 +269,8 @@ public:
      *
      * @see PresentCallable
      */
-    void setFrameScheduledCallback(FrameScheduledCallback callback, void* user = nullptr);
+    void setFrameScheduledCallback(FrameScheduledCallback UTILS_NULLABLE callback,
+            void* UTILS_NULLABLE user = nullptr);
 
     /**
      * FrameCompletedCallback is a callback function that notifies an application when a frame's
@@ -289,7 +291,7 @@ public:
      *
      * @see CallbackHandler
      */
-    void setFrameCompletedCallback(backend::CallbackHandler* handler = nullptr,
+    void setFrameCompletedCallback(backend::CallbackHandler* UTILS_NULLABLE handler = nullptr,
             FrameCompletedCallback&& callback = {}) noexcept;
 
 

filament/include/filament/Texture.h

@@ -20,12 +20,16 @@
 #define TNT_FILAMENT_TEXTURE_H
 
 #include <filament/FilamentAPI.h>
+
 #include <backend/DriverEnums.h>
 #include <backend/PixelBufferDescriptor.h>
 
 #include <utils/compiler.h>
 
+#include <utility>
+
 #include <stddef.h>
+#include <stdint.h>
 
 namespace filament {
 
@@ -200,14 +204,13 @@ public:
          *
          * @param engine Reference to the filament::Engine to associate this Texture with.
          *
-         * @return pointer to the newly created object or nullptr if exceptions are disabled and
-         *         an error occurred.
+         * @return pointer to the newly created object.
          *
          * @exception utils::PostConditionPanic if a runtime error occurred, such as running out of
          *            memory or other resources.
          * @exception utils::PreConditionPanic if a parameter to a builder function was invalid.
          */
-        Texture* build(Engine& engine);
+        Texture* UTILS_NONNULL build(Engine& engine);
 
         /* no user serviceable parts below */
 
@@ -396,7 +399,7 @@ public:
      * @see Builder::sampler()
      *
      */
-    void setExternalImage(Engine& engine, void* image) noexcept;
+    void setExternalImage(Engine& engine, void* UTILS_NONNULL image) noexcept;
 
     /**
      * Specify the external image and plane to associate with this Texture. Typically the external
@@ -427,7 +430,7 @@ public:
      *                      kCVPixelFormatType_420YpCbCr8BiPlanarFullRange images. On platforms
      *                      other than iOS, this method is a no-op.
      */
-    void setExternalImage(Engine& engine, void* image, size_t plane) noexcept;
+    void setExternalImage(Engine& engine, void* UTILS_NONNULL image, size_t plane) noexcept;
 
     /**
      * Specify the external stream to associate with this Texture. Typically the external
@@ -446,7 +449,7 @@ public:
      * @see Builder::sampler(), Stream
      *
      */
-    void setExternalStream(Engine& engine, Stream* stream) noexcept;
+    void setExternalStream(Engine& engine, Stream* UTILS_NULLABLE stream) noexcept;
 
     /**
      * Generates all the mipmap levels automatically. This requires the texture to have a
@@ -496,7 +499,7 @@ public:
      */
     void generatePrefilterMipmap(Engine& engine,
             PixelBufferDescriptor&& buffer, const FaceOffsets& faceOffsets,
-            PrefilterOptions const* options = nullptr);
+            PrefilterOptions const* UTILS_NULLABLE options = nullptr);
 
 
     /** @deprecated */

filament/include/filament/TextureSampler.h

@@ -25,6 +25,8 @@
 
 #include <math.h>
 
+#include <stdint.h>
+
 namespace filament {
 
 /**

filament/include/filament/ToneMapper.h

@@ -21,6 +21,8 @@
 
 #include <math/mathfwd.h>
 
+#include <stdint.h>
+
 namespace filament {
 
 /**

filament/include/filament/TransformManager.h

@@ -26,6 +26,7 @@
 
 #include <iterator>
 
+#include <stddef.h>
 
 namespace utils {
 class Entity;
@@ -139,7 +140,7 @@ public:
      * Retrieve the Entities of all the components of this manager.
      * @return A list, in no particular order, of all the entities managed by this manager.
      */
-    utils::Entity const* getEntities() const noexcept;
+    utils::Entity const* UTILS_NONNULL getEntities() const noexcept;
 
     /**
      * Enables or disable the accurate translation mode. Disabled by default.
@@ -223,7 +224,7 @@ public:
      * @param count The maximum number of children to retrieve.
      * @return The number of children written to the pointer.
      */
-    size_t getChildren(Instance i, utils::Entity* children, size_t count) const noexcept;
+    size_t getChildren(Instance i, utils::Entity* UTILS_NONNULL children, size_t count) const noexcept;
 
     /**
      * Returns an iterator to the Instance of the first child of the given parent.

filament/include/filament/VertexBuffer.h

@@ -27,6 +27,9 @@
 
 #include <utils/compiler.h>
 
+#include <stddef.h>
+#include <stdint.h>
+
 namespace filament {
 
 class FVertexBuffer;
@@ -160,14 +163,13 @@ public:
          *
          * @param engine Reference to the filament::Engine to associate this VertexBuffer with.
          *
-         * @return pointer to the newly created object or nullptr if exceptions are disabled and
-         *         an error occurred.
+         * @return pointer to the newly created object.
          *
          * @exception utils::PostConditionPanic if a runtime error occurred, such as running out of
          *            memory or other resources.
          * @exception utils::PreConditionPanic if a parameter to a builder function was invalid.
          */
-        VertexBuffer* build(Engine& engine);
+        VertexBuffer* UTILS_NONNULL build(Engine& engine);
 
     private:
         friend class FVertexBuffer;
@@ -206,7 +208,8 @@ public:
      *                    and Builder::bufferCount() - 1.
      * @param bufferObject The handle to the GPU data that will be used in this buffer slot.
      */
-    void setBufferObjectAt(Engine& engine, uint8_t bufferIndex, BufferObject const* bufferObject);
+    void setBufferObjectAt(Engine& engine, uint8_t bufferIndex,
+            BufferObject const*  UTILS_NONNULL bufferObject);
 
 protected:
     // prevent heap allocation

filament/include/filament/View.h

@@ -19,17 +19,19 @@
 #ifndef TNT_FILAMENT_VIEW_H
 #define TNT_FILAMENT_VIEW_H
 
-#include <filament/Color.h>
 #include <filament/FilamentAPI.h>
 #include <filament/Options.h>
 
-#include <backend/DriverEnums.h>
-
 #include <utils/compiler.h>
 #include <utils/Entity.h>
 
 #include <math/mathfwd.h>
 
+#include <utility>
+
+#include <stddef.h>
+#include <stdint.h>
+
 namespace filament {
 
 namespace backend {
@@ -91,7 +93,7 @@ public:
      * Sets the View's name. Only useful for debugging.
      * @param name Pointer to the View's name. The string is copied.
      */
-    void setName(const char* name) noexcept;
+    void setName(const char* UTILS_NONNULL name) noexcept;
 
     /**
      * Returns the View's name
@@ -100,7 +102,7 @@ public:
      *
      * @attention Do *not* free the pointer or modify its content.
      */
-    const char* getName() const noexcept;
+    const char* UTILS_NULLABLE getName() const noexcept;
 
     /**
      * Set this View instance's Scene.
@@ -116,19 +118,19 @@ public:
      *  There is no reference-counting.
      *  Make sure to dissociate a Scene from all Views before destroying it.
      */
-    void setScene(Scene* scene);
+    void setScene(Scene* UTILS_NULLABLE scene);
 
     /**
      * Returns the Scene currently associated with this View.
      * @return A pointer to the Scene associated to this View. nullptr if no Scene is set.
      */
-    Scene* getScene() noexcept;
+    Scene* UTILS_NULLABLE getScene() noexcept;
 
     /**
      * Returns the Scene currently associated with this View.
      * @return A pointer to the Scene associated to this View. nullptr if no Scene is set.
      */
-    Scene const* getScene() const noexcept {
+    Scene const* UTILS_NULLABLE getScene() const noexcept {
         return const_cast<View*>(this)->getScene();
     }
 
@@ -143,7 +145,7 @@ public:
      *
      * @param renderTarget Render target associated with view, or nullptr for the swap chain.
      */
-    void setRenderTarget(RenderTarget* renderTarget) noexcept;
+    void setRenderTarget(RenderTarget* UTILS_NULLABLE renderTarget) noexcept;
 
     /**
      * Gets the offscreen render target associated with this view.
@@ -152,7 +154,7 @@ public:
      *
      * @see setRenderTarget
      */
-    RenderTarget* getRenderTarget() const noexcept;
+    RenderTarget* UTILS_NULLABLE getRenderTarget() const noexcept;
 
     /**
      * Sets the rectangular region to render to.
@@ -185,7 +187,7 @@ public:
      *  There is no reference-counting.
      *  Make sure to dissociate a Camera from all Views before destroying it.
      */
-    void setCamera(Camera* camera) noexcept;
+    void setCamera(Camera* UTILS_NONNULL camera) noexcept;
 
     /**
      * Returns the Camera currently associated with this View.
@@ -402,13 +404,13 @@ public:
      *  There is no reference-counting.
      *  Make sure to dissociate a ColorGrading from all Views before destroying it.
      */
-    void setColorGrading(ColorGrading* colorGrading) noexcept;
+    void setColorGrading(ColorGrading* UTILS_NULLABLE colorGrading) noexcept;
 
     /**
      * Returns the color grading transforms currently associated to this view.
      * @return A pointer to the ColorGrading associated to this View.
      */
-    const ColorGrading* getColorGrading() const noexcept;
+    const ColorGrading* UTILS_NULLABLE getColorGrading() const noexcept;
 
     /**
      * Sets ambient occlusion options.
@@ -714,10 +716,10 @@ public:
     bool isFrustumCullingEnabled() const noexcept;
 
     //! debugging: sets the Camera used for rendering. It may be different from the culling camera.
-    void setDebugCamera(Camera* camera) noexcept;
+    void setDebugCamera(Camera* UTILS_NULLABLE camera) noexcept;
 
     //! debugging: returns a Camera from the point of view of *the* dominant directional light used for shadowing.
-    Camera const* getDirectionalLightCamera() const noexcept;
+    Camera const* UTILS_NULLABLE getDirectionalLightCamera() const noexcept;
 
 
     /** Result of a picking query */
@@ -746,11 +748,12 @@ public:
     /** User data for PickingQueryResultCallback */
     struct PickingQuery {
         // note: this is enough to store a std::function<> -- just saying...
-        void* storage[4];
+        void* UTILS_NULLABLE storage[4];
     };
 
     /** callback type used for picking queries. */
-    using PickingQueryResultCallback = void(*)(PickingQueryResult const& result, PickingQuery* pq);
+    using PickingQueryResultCallback =
+            void(*)(PickingQueryResult const& result, PickingQuery* UTILS_NONNULL pq);
 
     /**
      * Helper for creating a picking query from Foo::method, by pointer.
@@ -764,8 +767,8 @@ public:
      * @param handler   Handler to dispatch the callback or nullptr for the default handler.
      */
     template<typename T, void(T::*method)(PickingQueryResult const&)>
-    void pick(uint32_t x, uint32_t y, T* instance,
-            backend::CallbackHandler* handler = nullptr) noexcept {
+    void pick(uint32_t x, uint32_t y, T* UTILS_NONNULL instance,
+            backend::CallbackHandler* UTILS_NULLABLE handler = nullptr) noexcept {
         PickingQuery& query = pick(x, y, [](PickingQueryResult const& result, PickingQuery* pq) {
             (static_cast<T*>(pq->storage[0])->*method)(result);
         }, handler);
@@ -785,7 +788,7 @@ public:
      */
     template<typename T, void(T::*method)(PickingQueryResult const&)>
     void pick(uint32_t x, uint32_t y, T instance,
-            backend::CallbackHandler* handler = nullptr) noexcept {
+            backend::CallbackHandler* UTILS_NULLABLE handler = nullptr) noexcept {
         static_assert(sizeof(instance) <= sizeof(PickingQuery::storage), "user data too large");
         PickingQuery& query = pick(x, y, [](PickingQueryResult const& result, PickingQuery* pq) {
             T* const that = static_cast<T*>(reinterpret_cast<void*>(pq->storage));
@@ -806,7 +809,7 @@ public:
      */
     template<typename T>
     void pick(uint32_t x, uint32_t y, T functor,
-            backend::CallbackHandler* handler = nullptr) noexcept {
+            backend::CallbackHandler* UTILS_NULLABLE handler = nullptr) noexcept {
         static_assert(sizeof(functor) <= sizeof(PickingQuery::storage), "functor too large");
         PickingQuery& query = pick(x, y, handler,
                 (PickingQueryResultCallback)[](PickingQueryResult const& result, PickingQuery* pq) {
@@ -832,8 +835,9 @@ public:
      *                  8*sizeof(void*) bytes of user data. This user data is later accessible
      *                  in the PickingQueryResultCallback callback 3rd parameter.
      */
-    PickingQuery& pick(uint32_t x, uint32_t y, backend::CallbackHandler* handler,
-            PickingQueryResultCallback callback) noexcept;
+    PickingQuery& pick(uint32_t x, uint32_t y,
+            backend::CallbackHandler* UTILS_NULLABLE handler,
+            PickingQueryResultCallback UTILS_NONNULL callback) noexcept;
 
     /**
      * Set the value of material global variables. There are up-to four such variable each of

filament/include/filament/Viewport.h

@@ -23,9 +23,6 @@
 
 #include <utils/compiler.h>
 
-#include <math/scalar.h>
-#include <math/mathfwd.h>
-
 #include <stddef.h>
 #include <stdint.h>
 

filament/src/Allocators.h

@@ -54,7 +54,7 @@ using LinearAllocatorArena = utils::Arena<
 
 #endif
 
-using ArenaScope = utils::ArenaScope<LinearAllocatorArena>;
+using RootArenaScope = utils::ArenaScope<LinearAllocatorArena>;
 
 } // namespace filament
 

filament/src/Froxelizer.cpp

@@ -168,7 +168,8 @@ void Froxelizer::setProjection(const mat4f& projection,
 }
 
 bool Froxelizer::prepare(
-        FEngine::DriverApi& driverApi, ArenaScope& arena, filament::Viewport const& viewport,
+        FEngine::DriverApi& driverApi, RootArenaScope& rootArenaScope,
+        filament::Viewport const& viewport,
         const mat4f& projection, float projectionNear, float projectionFar) noexcept {
     setViewport(viewport);
     setProjection(projection, projectionNear, projectionFar);
@@ -199,12 +200,12 @@ bool Froxelizer::prepare(
 
     // light records per froxel (~256 KiB)
     mLightRecords = {
-            arena.allocate<LightRecord>(getFroxelBufferEntryCount(), CACHELINE_SIZE),
+            rootArenaScope.allocate<LightRecord>(getFroxelBufferEntryCount(), CACHELINE_SIZE),
             getFroxelBufferEntryCount() };
 
     // froxel thread data (~256 KiB)
     mFroxelShardedData = {
-            arena.allocate<FroxelThreadData>(GROUP_COUNT, CACHELINE_SIZE),
+            rootArenaScope.allocate<FroxelThreadData>(GROUP_COUNT, CACHELINE_SIZE),
             uint32_t(GROUP_COUNT)
     };
 

filament/src/Froxelizer.h

@@ -110,7 +110,7 @@ public:
      *
      * return true if updateUniforms() needs to be called
      */
-    bool prepare(backend::DriverApi& driverApi, ArenaScope& arena, Viewport const& viewport,
+    bool prepare(backend::DriverApi& driverApi, RootArenaScope& rootArenaScope, Viewport const& viewport,
             const math::mat4f& projection, float projectionNear, float projectionFar) noexcept;
 
     Froxel getFroxelAt(size_t x, size_t y, size_t z) const noexcept;

filament/src/Material.cpp

@@ -25,7 +25,7 @@ MaterialInstance* Material::createInstance(const char* name) const noexcept {
 }
 
 const char* Material::getName() const noexcept {
-    return downcast(this)->getName().c_str();
+    return downcast(this)->getName().c_str_safe();
 }
 
 Shading Material::getShading()  const noexcept {

filament/src/PostProcessManager.cpp

@@ -64,6 +64,7 @@
 #include <math/mat3.h>
 #include <math/mat4.h>
 #include <math/scalar.h>
+#include <math/vec2.h>
 #include <math/vec3.h>
 #include <math/vec4.h>
 
@@ -74,6 +75,7 @@
 #include <utils/FixedCapacityVector.h>
 
 #include <algorithm>
+#include <array>
 #include <cmath>
 #include <limits>
 #include <string_view>
@@ -113,7 +115,7 @@ PostProcessManager::PostProcessMaterial::PostProcessMaterial() noexcept {
 }
 
 PostProcessManager::PostProcessMaterial::PostProcessMaterial(MaterialInfo const& info) noexcept
-    : PostProcessMaterial() {
+        : PostProcessMaterial() {
     mData = info.data; // aliased to mMaterial
     mSize = info.size;
     mConstants = info.constants;
@@ -165,7 +167,7 @@ void PostProcessManager::PostProcessMaterial::loadMaterial(FEngine& engine) cons
     mHasMaterial = true;
     auto builder = Material::Builder();
     builder.package(mData, mSize);
-    for (auto const& constant : mConstants) {
+    for (auto const& constant: mConstants) {
         std::visit([&](auto&& arg) {
             builder.constant(constant.name.data(), constant.name.size(), arg);
         }, constant.value);
@@ -187,63 +189,60 @@ PipelineState PostProcessManager::PostProcessMaterial::getPipelineState(
     FMaterial* const material = getMaterial(engine);
     material->prepareProgram(Variant{ variantKey });
     return {
-            .program = material->getProgram(Variant{variantKey}),
+            .program = material->getProgram(Variant{ variantKey }),
             .rasterState = material->getRasterState(),
             .scissor = material->getDefaultInstance()->getScissor()
     };
 }
 
 UTILS_NOINLINE
-FMaterialInstance* PostProcessManager::PostProcessMaterial::getMaterialInstance(FEngine& engine) const noexcept {
+FMaterialInstance* PostProcessManager::PostProcessMaterial::getMaterialInstance(
+        FEngine& engine) const noexcept {
     FMaterial* const material = getMaterial(engine);
     return material->getDefaultInstance();
 }
 
 // ------------------------------------------------------------------------------------------------
 
-const PostProcessManager::JitterSequence<4> PostProcessManager::sRGSS4 = {{
+const PostProcessManager::JitterSequence<4> PostProcessManager::sRGSS4 = {{{
         { 0.625f, 0.125f },
         { 0.125f, 0.375f },
         { 0.875f, 0.625f },
         { 0.375f, 0.875f }
-}};
+}}};
 
-const PostProcessManager::JitterSequence<4> PostProcessManager::sUniformHelix4 = {{
+const PostProcessManager::JitterSequence<4> PostProcessManager::sUniformHelix4 = {{{
         { 0.25f, 0.25f },
         { 0.75f, 0.75f },
         { 0.25f, 0.75f },
         { 0.75f, 0.25f },
-}};
+}}};
 
-const PostProcessManager::JitterSequence<16> PostProcessManager::sHaltonSamples = {{
-        { filament::halton( 0, 2), filament::halton( 0, 3) },
-        { filament::halton( 1, 2), filament::halton( 1, 3) },
-        { filament::halton( 2, 2), filament::halton( 2, 3) },
-        { filament::halton( 3, 2), filament::halton( 3, 3) },
-        { filament::halton( 4, 2), filament::halton( 4, 3) },
-        { filament::halton( 5, 2), filament::halton( 5, 3) },
-        { filament::halton( 6, 2), filament::halton( 6, 3) },
-        { filament::halton( 7, 2), filament::halton( 7, 3) },
-        { filament::halton( 8, 2), filament::halton( 8, 3) },
-        { filament::halton( 9, 2), filament::halton( 9, 3) },
-        { filament::halton(10, 2), filament::halton(10, 3) },
-        { filament::halton(11, 2), filament::halton(11, 3) },
-        { filament::halton(12, 2), filament::halton(12, 3) },
-        { filament::halton(13, 2), filament::halton(13, 3) },
-        { filament::halton(14, 2), filament::halton(14, 3) },
-        { filament::halton(15, 2), filament::halton(15, 3) }
-}};
+template<size_t COUNT>
+constexpr auto halton() {
+    std::array<float2, COUNT> h;
+    for (size_t i = 0; i < COUNT; i++) {
+        h[i] = {
+                filament::halton(i, 2),
+                filament::halton(i, 3) };
+    }
+    return h;
+}
+
+const PostProcessManager::JitterSequence<32>
+        PostProcessManager::sHaltonSamples = { halton<32>() };
 
 PostProcessManager::PostProcessManager(FEngine& engine) noexcept
         : mEngine(engine),
-         mWorkaroundSplitEasu(false),
-         mWorkaroundAllowReadOnlyAncillaryFeedbackLoop(false) {
+          mWorkaroundSplitEasu(false),
+          mWorkaroundAllowReadOnlyAncillaryFeedbackLoop(false) {
 }
 
 PostProcessManager::~PostProcessManager() noexcept = default;
 
 UTILS_NOINLINE
-void PostProcessManager::registerPostProcessMaterial(std::string_view name, MaterialInfo const& info) {
+void PostProcessManager::registerPostProcessMaterial(std::string_view name,
+        MaterialInfo const& info) {
     mMaterialRegistry.try_emplace(name, info);
 }
 
@@ -308,6 +307,7 @@ static const PostProcessManager::MaterialInfo sMaterialList[] = {
         { "fsr_rcas",                   MATERIAL(FSR_RCAS) },
         { "debugShadowCascades",        MATERIAL(DEBUGSHADOWCASCADES) },
         { "resolveDepth",               MATERIAL(RESOLVEDEPTH) },
+        { "shadowmap",                  MATERIAL(SHADOWMAP) },
 };
 
 void PostProcessManager::init() noexcept {
@@ -326,13 +326,13 @@ void PostProcessManager::init() noexcept {
             driver.isWorkaroundNeeded(Workaround::ALLOW_READ_ONLY_ANCILLARY_FEEDBACK_LOOP);
 
     #pragma nounroll
-    for (auto const& info : sMaterialListFeatureLevel0) {
+    for (auto const& info: sMaterialListFeatureLevel0) {
         registerPostProcessMaterial(info.name, info);
     }
 
     if (mEngine.getActiveFeatureLevel() >= FeatureLevel::FEATURE_LEVEL_1) {
         #pragma nounroll
-        for (auto const& info : sMaterialList) {
+        for (auto const& info: sMaterialList) {
             registerPostProcessMaterial(info.name, info);
         }
     }
@@ -414,7 +414,7 @@ void PostProcessManager::commitAndRender(FrameGraphResources::RenderPassInfo con
 // ------------------------------------------------------------------------------------------------
 
 PostProcessManager::StructurePassOutput PostProcessManager::structure(FrameGraph& fg,
-        RenderPass const& pass, uint8_t structureRenderFlags,
+        RenderPassBuilder const& passBuilder, uint8_t structureRenderFlags,
         uint32_t width, uint32_t height,
         StructurePassConfig const& config) noexcept {
 
@@ -466,17 +466,19 @@ PostProcessManager::StructurePassOutput PostProcessManager::structure(FrameGraph
                         .clearFlags = TargetBufferFlags::COLOR0 | TargetBufferFlags::DEPTH
                 });
             },
-            [=, renderPass = pass](FrameGraphResources const& resources,
+            [=, passBuilder = passBuilder](FrameGraphResources const& resources,
                     auto const&, DriverApi&) mutable {
                 Variant structureVariant(Variant::DEPTH_VARIANT);
                 structureVariant.setPicking(config.picking);
 
                 auto out = resources.getRenderPassInfo();
-                renderPass.setRenderFlags(structureRenderFlags);
-                renderPass.setVariant(structureVariant);
-                renderPass.appendCommands(mEngine, RenderPass::CommandTypeFlags::SSAO);
-                renderPass.sortCommands(mEngine);
-                renderPass.execute(mEngine, resources.getPassName(), out.target, out.params);
+
+                passBuilder.renderFlags(structureRenderFlags);
+                passBuilder.variant(structureVariant);
+                passBuilder.commandTypeFlags(RenderPass::CommandTypeFlags::SSAO);
+
+                RenderPass const pass{ passBuilder.build(mEngine) };
+                RenderPass::execute(pass, mEngine, resources.getPassName(), out.target, out.params);
             });
 
     auto depth = structurePass->depth;
@@ -523,7 +525,7 @@ PostProcessManager::StructurePassOutput PostProcessManager::structure(FrameGraph
 // ------------------------------------------------------------------------------------------------
 
 FrameGraphId<FrameGraphTexture> PostProcessManager::ssr(FrameGraph& fg,
-        RenderPass const& pass,
+        RenderPassBuilder const& passBuilder,
         FrameHistory const& frameHistory,
         CameraInfo const& cameraInfo,
         PerViewUniforms& uniforms,
@@ -586,7 +588,7 @@ FrameGraphId<FrameGraphTexture> PostProcessManager::ssr(FrameGraph& fg,
             },
             [this, projection = cameraInfo.projection,
                     userViewMatrix = cameraInfo.getUserViewMatrix(), uvFromClipMatrix, historyProjection,
-                    options, &uniforms, renderPass = pass]
+                    options, &uniforms, passBuilder = passBuilder]
             (FrameGraphResources const& resources, auto const& data, DriverApi& driver) mutable {
                 // set structure sampler
                 uniforms.prepareStructure(data.structure ?
@@ -607,17 +609,17 @@ FrameGraphId<FrameGraphTexture> PostProcessManager::ssr(FrameGraph& fg,
                 auto out = resources.getRenderPassInfo();
 
                 // Remove the HAS_SHADOWING RenderFlags, since it's irrelevant when rendering reflections
-                RenderPass::RenderFlags flags = renderPass.getRenderFlags();
-                flags &= ~RenderPass::HAS_SHADOWING;
-                renderPass.setRenderFlags(flags);
+                passBuilder.renderFlags(~RenderPass::HAS_SHADOWING, 0);
 
                 // use our special SSR variant, it can only be applied to object that have
                 // the SCREEN_SPACE ReflectionMode.
-                renderPass.setVariant(Variant{Variant::SPECIAL_SSR});
+                passBuilder.variant(Variant{ Variant::SPECIAL_SSR });
+
                 // generate all our drawing commands, except blended objects.
-                renderPass.appendCommands(mEngine, RenderPass::CommandTypeFlags::SCREEN_SPACE_REFLECTIONS);
-                renderPass.sortCommands(mEngine);
-                renderPass.execute(mEngine, resources.getPassName(), out.target, out.params);
+                passBuilder.commandTypeFlags(RenderPass::CommandTypeFlags::SCREEN_SPACE_REFLECTIONS);
+
+                RenderPass const pass{ passBuilder.build(mEngine) };
+                RenderPass::execute(pass, mEngine, resources.getPassName(), out.target, out.params);
             });
 
     return ssrPass->reflections;
@@ -1428,7 +1430,7 @@ FrameGraphId<FrameGraphTexture> PostProcessManager::dof(FrameGraph& fg,
         FrameGraphId<FrameGraphTexture> depth,
         const CameraInfo& cameraInfo,
         bool translucent,
-        float bokehAspectRatio,
+        float2 bokehScale,
         const DepthOfFieldOptions& dofOptions) noexcept {
 
     assert_invariant(depth);
@@ -1683,8 +1685,8 @@ FrameGraphId<FrameGraphTexture> PostProcessManager::dof(FrameGraph& fg,
 
     // we assume the width/height is already multiple of 16
     assert_invariant(!(colorDesc.width  & 0xF) && !(colorDesc.height & 0xF));
-    const uint32_t tileBufferWidth  = colorDesc.width  / dofResolution;
-    const uint32_t tileBufferHeight = colorDesc.height / dofResolution;
+    const uint32_t tileBufferWidth  = width;
+    const uint32_t tileBufferHeight = height;
     const size_t tileReductionCount = ctz(tileSize / dofResolution);
 
     struct PostProcessDofTiling1 {
@@ -1818,8 +1820,8 @@ FrameGraphId<FrameGraphTexture> PostProcessManager::dof(FrameGraph& fg,
                 mi->setParameter("tiles", tilesCocMinMax,
                         { .filterMin = SamplerMinFilter::NEAREST });
                 mi->setParameter("cocToTexelScale", float2{
-                        bokehAspectRatio / (inputDesc.width  * dofResolution),
-                                     1.0 / (inputDesc.height * dofResolution)
+                        bokehScale.x / (inputDesc.width * dofResolution),
+                        bokehScale.y / (inputDesc.height * dofResolution)
                 });
                 mi->setParameter("cocToPixelScale", (1.0f / float(dofResolution)));
                 mi->setParameter("ringCounts", float4{
@@ -2569,6 +2571,8 @@ void PostProcessManager::prepareTaa(FrameGraph& fg,
             case JitterPattern::HALTON_23_X8:
                 return sHaltonSamples(frameIndex % 8);
             case JitterPattern::HALTON_23_X16:
+                return sHaltonSamples(frameIndex % 16);
+            case JitterPattern::HALTON_23_X32:
                 return sHaltonSamples(frameIndex);
         }
     };
@@ -2618,6 +2622,7 @@ void PostProcessManager::configureTemporalAntiAliasingMaterial(
         }
     };
 
+    setConstantParameter(ma, "upscaling", taaOptions.upscaling);
     setConstantParameter(ma, "historyReprojection", taaOptions.historyReprojection);
     setConstantParameter(ma, "filterHistory", taaOptions.filterHistory);
     setConstantParameter(ma, "filterInput", taaOptions.filterInput);
@@ -2767,24 +2772,77 @@ FrameGraphId<FrameGraphTexture> PostProcessManager::taa(FrameGraph& fg,
             });
 
     input = colorGradingConfig.asSubpass ? taaPass->tonemappedOutput : taaPass->output;
+    auto history = input;
+
+    // optional sharpen pass from FSR1
+    if (taaOptions.sharpness > 0.0f) {
+        input = rcas(fg, taaOptions.sharpness,
+                input, fg.getDescriptor(input), colorGradingConfig.translucent);
+    }
 
     struct ExportColorHistoryData {
         FrameGraphId<FrameGraphTexture> color;
     };
-    auto& exportHistoryPass = fg.addPass<ExportColorHistoryData>("Export TAA history",
+    fg.addPass<ExportColorHistoryData>("Export TAA history",
             [&](FrameGraph::Builder& builder, auto& data) {
                 // We need to use sideEffect here to ensure this pass won't be culled.
                 // The "output" of this pass is going to be used during the next frame as
                 // an "import".
                 builder.sideEffect();
-                data.color = builder.sample(input); // FIXME: an access must be declared for detach(), why?
-            }, [&current](FrameGraphResources const& resources, auto const& data,
-                    backend::DriverApi&) {
-                resources.detach(data.color,
-                        &current.color, &current.desc);
+                data.color = builder.sample(history); // FIXME: an access must be declared for detach(), why?
+            }, [&current](FrameGraphResources const& resources, auto const& data, auto&) {
+                resources.detach(data.color, &current.color, &current.desc);
             });
 
-    return exportHistoryPass->color;
+    return input;
+}
+
+FrameGraphId<FrameGraphTexture> PostProcessManager::rcas(
+        FrameGraph& fg,
+        float sharpness,
+        FrameGraphId<FrameGraphTexture> input,
+        FrameGraphTexture::Descriptor const& outDesc,
+        bool translucent) {
+
+    struct QuadBlitData {
+        FrameGraphId<FrameGraphTexture> input;
+        FrameGraphId<FrameGraphTexture> output;
+    };
+
+    auto& ppFsrRcas = fg.addPass<QuadBlitData>("FidelityFX FSR1 Rcas",
+            [&](FrameGraph::Builder& builder, auto& data) {
+                data.input = builder.sample(input);
+                data.output = builder.createTexture("FFX FSR1 Rcas output", outDesc);
+                data.output = builder.declareRenderPass(data.output);
+            },
+            [=](FrameGraphResources const& resources,
+                    auto const& data, DriverApi& driver) {
+
+                auto input = resources.getTexture(data.input);
+                auto out = resources.getRenderPassInfo();
+                auto const& outputDesc = resources.getDescriptor(data.input);
+
+                auto& material = getPostProcessMaterial("fsr_rcas");
+                FMaterialInstance* const mi = material.getMaterialInstance(mEngine);
+
+                FSRUniforms uniforms;
+                FSR_SharpeningSetup(&uniforms, { .sharpness = 2.0f - 2.0f * sharpness });
+                mi->setParameter("RcasCon", uniforms.RcasCon);
+                mi->setParameter("color", input, {}); // uses texelFetch
+                mi->setParameter("resolution", float4{
+                        outputDesc.width, outputDesc.height,
+                        1.0f / outputDesc.width, 1.0f / outputDesc.height });
+                mi->commit(driver);
+                mi->use(driver);
+
+                const uint8_t variant = uint8_t(
+                        translucent ? PostProcessVariant::TRANSLUCENT : PostProcessVariant::OPAQUE);
+
+                PipelineState const pipeline(material.getPipelineState(mEngine, variant));
+                render(out, pipeline, driver);
+            });
+
+    return ppFsrRcas->output;
 }
 
 FrameGraphId<FrameGraphTexture> PostProcessManager::upscale(FrameGraph& fg, bool translucent,
@@ -2947,41 +3005,9 @@ FrameGraphId<FrameGraphTexture> PostProcessManager::upscale(FrameGraph& fg, bool
     auto output = ppQuadBlit->output;
 
     // if we had to take the low quality fallback, we still do the "sharpen pass"
-    if (dsrOptions.sharpness > 0.0f && (dsrOptions.quality != QualityLevel::LOW || lowQualityFallback)) {
-        auto& ppFsrRcas = fg.addPass<QuadBlitData>("FidelityFX FSR1 Rcas",
-                [&](FrameGraph::Builder& builder, auto& data) {
-                    data.input = builder.sample(output);
-                    data.output = builder.createTexture("FFX FSR1 Rcas output", outDesc);
-                    data.output = builder.declareRenderPass(data.output);
-                },
-                [=](FrameGraphResources const& resources,
-                        auto const& data, DriverApi& driver) {
-
-                    auto color = resources.getTexture(data.input);
-                    auto out = resources.getRenderPassInfo();
-                    auto const& outputDesc = resources.getDescriptor(data.output);
-
-                    auto& material = getPostProcessMaterial("fsr_rcas");
-                    FMaterialInstance* const mi = material.getMaterialInstance(mEngine);
-
-                    FSRUniforms uniforms;
-                    FSR_SharpeningSetup(&uniforms, { .sharpness = 2.0f - 2.0f * dsrOptions.sharpness });
-                    mi->setParameter("RcasCon", uniforms.RcasCon);
-                    mi->setParameter("color", color, { }); // uses texelFetch
-                    mi->setParameter("resolution", float4{
-                            outputDesc.width, outputDesc.height,
-                            1.0f / outputDesc.width, 1.0f / outputDesc.height });
-                    mi->commit(driver);
-                    mi->use(driver);
-
-                    const uint8_t variant = uint8_t(translucent ?
-                            PostProcessVariant::TRANSLUCENT : PostProcessVariant::OPAQUE);
-
-                    PipelineState const pipeline(material.getPipelineState(mEngine, variant));
-                    render(out, pipeline, driver);
-                });
-
-        output = ppFsrRcas->output;
+    if (dsrOptions.sharpness > 0.0f &&
+            (dsrOptions.quality != QualityLevel::LOW || lowQualityFallback)) {
+        output = rcas(fg, dsrOptions.sharpness, output, outDesc, translucent);
     }
 
     // we rely on automatic culling of unused render passes
@@ -3250,4 +3276,51 @@ FrameGraphId<FrameGraphTexture> PostProcessManager::debugShadowCascades(FrameGra
     return debugShadowCascadePass->output;
 }
 
+FrameGraphId<FrameGraphTexture> PostProcessManager::debugDisplayShadowTexture(
+        FrameGraph& fg,
+        FrameGraphId<FrameGraphTexture> input,
+        FrameGraphId<FrameGraphTexture> shadowmap, float scale,
+        uint8_t layer, uint8_t level, uint8_t channel, float power) noexcept {
+    if (shadowmap) {
+        struct ShadowMapData {
+            FrameGraphId<FrameGraphTexture> color;
+            FrameGraphId<FrameGraphTexture> depth;
+        };
+
+        auto const& desc = fg.getDescriptor(input);
+        float const ratio = float(desc.height) / float(desc.width);
+        float const screenScale = float(fg.getDescriptor(shadowmap).height) / float(desc.height);
+        float2 const s = { screenScale * scale * ratio, screenScale * scale };
+
+        auto& shadomapDebugPass = fg.addPass<ShadowMapData>("shadowmap debug pass",
+                [&](FrameGraph::Builder& builder, auto& data) {
+                    data.color = builder.read(input,
+                            FrameGraphTexture::Usage::COLOR_ATTACHMENT);
+                    data.color = builder.write(data.color,
+                            FrameGraphTexture::Usage::COLOR_ATTACHMENT);
+                    data.depth = builder.sample(shadowmap);
+                    builder.declareRenderPass("color target", {
+                            .attachments = { .color = { data.color }}
+                    });
+                },
+                [=](FrameGraphResources const& resources, auto const& data, DriverApi& driver) {
+                    auto out = resources.getRenderPassInfo();
+                    auto in = resources.getTexture(data.depth);
+                    auto const& material = getPostProcessMaterial("shadowmap");
+                    FMaterialInstance* const mi = material.getMaterialInstance(mEngine);
+                    mi->setParameter("shadowmap", in, {
+                        .filterMin = SamplerMinFilter::NEAREST_MIPMAP_NEAREST });
+                    mi->setParameter("scale", s);
+                    mi->setParameter("layer", (uint32_t)layer);
+                    mi->setParameter("level", (uint32_t)level);
+                    mi->setParameter("channel", (uint32_t)channel);
+                    mi->setParameter("power", power);
+                    commitAndRender(out, material, driver);
+                });
+        input = shadomapDebugPass->color;
+    }
+    return input;
+}
+
+
 } // namespace filament

filament/src/PostProcessManager.h

@@ -36,6 +36,7 @@
 
 #include <tsl/robin_map.h>
 
+#include <array>
 #include <random>
 #include <string_view>
 #include <variant>
@@ -49,6 +50,7 @@ class FMaterialInstance;
 class FrameGraph;
 class PerViewUniforms;
 class RenderPass;
+class RenderPassBuilder;
 struct CameraInfo;
 
 class PostProcessManager {
@@ -98,12 +100,12 @@ public:
         FrameGraphId<FrameGraphTexture> picking;
     };
     StructurePassOutput structure(FrameGraph& fg,
-            RenderPass const& pass, uint8_t structureRenderFlags,
+            RenderPassBuilder const& passBuilder, uint8_t structureRenderFlags,
             uint32_t width, uint32_t height, StructurePassConfig const& config) noexcept;
 
     // reflections pass
     FrameGraphId<FrameGraphTexture> ssr(FrameGraph& fg,
-            RenderPass const& pass,
+            RenderPassBuilder const& passBuilder,
             FrameHistory const& frameHistory,
             CameraInfo const& cameraInfo,
             PerViewUniforms& uniforms,
@@ -162,7 +164,7 @@ public:
             FrameGraphId<FrameGraphTexture> depth,
             const CameraInfo& cameraInfo,
             bool translucent,
-            float bokehAspectRatio,
+            math::float2 bokehScale,
             const DepthOfFieldOptions& dofOptions) noexcept;
 
     // Bloom
@@ -241,6 +243,13 @@ public:
             filament::Viewport const& vp, FrameGraphTexture::Descriptor const& outDesc,
             backend::SamplerMagFilter filter) noexcept;
 
+    FrameGraphId<FrameGraphTexture> rcas(
+            FrameGraph& fg,
+            float sharpness,
+            FrameGraphId<FrameGraphTexture> input,
+            FrameGraphTexture::Descriptor const& outDesc,
+            bool translucent);
+
     // upscale/downscale blitter using shaders
     FrameGraphId<FrameGraphTexture> blit(FrameGraph& fg, bool translucent,
             FrameGraphId<FrameGraphTexture> input,
@@ -274,6 +283,11 @@ public:
             FrameGraphId<FrameGraphTexture> input,
             FrameGraphId<FrameGraphTexture> depth) noexcept;
 
+    FrameGraphId<FrameGraphTexture> debugDisplayShadowTexture(FrameGraph& fg,
+            FrameGraphId<FrameGraphTexture> input,
+            FrameGraphId<FrameGraphTexture> shadowmap, float scale,
+            uint8_t layer, uint8_t level, uint8_t channel, float power) noexcept;
+
     backend::Handle<backend::HwTexture> getOneTexture() const;
     backend::Handle<backend::HwTexture> getZeroTexture() const;
     backend::Handle<backend::HwTexture> getOneTextureArray() const;
@@ -362,12 +376,12 @@ private:
     template<size_t SIZE>
     struct JitterSequence {
         auto operator()(size_t i) const noexcept { return positions[i % SIZE] - 0.5f; }
-        const math::float2 positions[SIZE];
+        const std::array<math::float2, SIZE> positions;
     };
 
     static const JitterSequence<4> sRGSS4;
     static const JitterSequence<4> sUniformHelix4;
-    static const JitterSequence<16> sHaltonSamples;
+    static const JitterSequence<32> sHaltonSamples;
 
     bool mWorkaroundSplitEasu : 1;
     bool mWorkaroundAllowReadOnlyAncillaryFeedbackLoop : 1;

filament/src/RenderPass.cpp

@@ -19,17 +19,43 @@
 #include "RenderPrimitive.h"
 #include "ShadowMap.h"
 
+#include "details/Camera.h"
 #include "details/Material.h"
 #include "details/MaterialInstance.h"
 #include "details/View.h"
 
+#include "components/RenderableManager.h"
+
+#include <private/filament/EngineEnums.h>
 #include <private/filament/UibStructs.h>
+#include <private/filament/Variant.h>
 
+#include <filament/MaterialEnums.h>
+
+#include <backend/DriverApiForward.h>
+#include <backend/DriverEnums.h>
+#include <backend/Handle.h>
+#include <backend/PipelineState.h>
+
+#include "private/backend/CircularBuffer.h"
+
+#include <utils/compiler.h>
+#include <utils/debug.h>
 #include <utils/JobSystem.h>
+#include <utils/Panic.h>
+#include <utils/Slice.h>
 #include <utils/Systrace.h>
+#include <utils/Range.h>
 
+#include <algorithm>
+#include <functional>
+#include <limits>
 #include <utility>
 
+#include <stddef.h>
+#include <stdint.h>
+#include <stdlib.h>
+
 using namespace utils;
 using namespace filament::math;
 
@@ -37,60 +63,103 @@ namespace filament {
 
 using namespace backend;
 
-RenderPass::RenderPass(FEngine& engine,
-        RenderPass::Arena& arena) noexcept
-        : mCommandArena(arena),
-          mCustomCommands(engine.getPerRenderPassAllocator()) {
+RenderPassBuilder& RenderPassBuilder::customCommand(
+        FEngine& engine,
+        uint8_t channel,
+        RenderPass::Pass pass,
+        RenderPass::CustomCommand custom,
+        uint32_t order,
+        RenderPass::Executor::CustomCommandFn const& command) {
+    if (!mCustomCommands.has_value()) {
+        // construct the vector the first time
+        mCustomCommands.emplace(engine.getPerRenderPassArena());
+    }
+    mCustomCommands->emplace_back(channel, pass, custom, order, command);
+    return *this;
 }
 
-RenderPass::RenderPass(RenderPass const& rhs) = default;
+RenderPass RenderPassBuilder::build(FEngine& engine) {
+    ASSERT_POSTCONDITION(mRenderableSoa, "RenderPassBuilder::geometry() hasn't been called");
+    assert_invariant(mScissorViewport.width  <= std::numeric_limits<int32_t>::max());
+    assert_invariant(mScissorViewport.height <= std::numeric_limits<int32_t>::max());
+    return RenderPass{ engine, *this };
+}
+
+// ------------------------------------------------------------------------------------------------
+
+RenderPass::RenderPass(FEngine& engine, RenderPassBuilder const& builder) noexcept
+        : mRenderableSoa(*builder.mRenderableSoa),
+          mVisibleRenderables(builder.mVisibleRenderables),
+          mUboHandle(builder.mUboHandle),
+          mCameraPosition(builder.mCameraPosition),
+          mCameraForwardVector(builder.mCameraForwardVector),
+          mFlags(builder.mFlags),
+          mVariant(builder.mVariant),
+          mVisibilityMask(builder.mVisibilityMask),
+          mScissorViewport(builder.mScissorViewport),
+          mCustomCommands(engine.getPerRenderPassArena()) {
+
+    // compute the number of commands we need
+    updateSummedPrimitiveCounts(
+            const_cast<FScene::RenderableSoa&>(mRenderableSoa), mVisibleRenderables);
+
+    uint32_t commandCount =
+            FScene::getPrimitiveCount(mRenderableSoa, mVisibleRenderables.last);
+    const bool colorPass  = bool(builder.mCommandTypeFlags & CommandTypeFlags::COLOR);
+    const bool depthPass  = bool(builder.mCommandTypeFlags & CommandTypeFlags::DEPTH);
+    commandCount *= uint32_t(colorPass * 2 + depthPass);
+    commandCount += 1; // for the sentinel
+
+    uint32_t const customCommandCount =
+            builder.mCustomCommands.has_value() ? builder.mCustomCommands->size() : 0;
+
+    Command* const curr = builder.mArena.alloc<Command>(commandCount + customCommandCount);
+    assert_invariant(curr);
+
+    if (UTILS_UNLIKELY(builder.mArena.getAllocator().isHeapAllocation(curr))) {
+        static bool sLogOnce = true;
+        if (UTILS_UNLIKELY(sLogOnce)) {
+            sLogOnce = false;
+            PANIC_LOG("RenderPass arena is full, using slower system heap. Please increase "
+                      "the appropriate constant (e.g. FILAMENT_PER_RENDER_PASS_ARENA_SIZE_IN_MB).");
+        }
+    }
+
+    mCommandBegin = curr;
+    mCommandEnd = curr + commandCount + customCommandCount;
+
+    appendCommands(engine, { curr, commandCount }, builder.mCommandTypeFlags);
+
+    if (builder.mCustomCommands.has_value()) {
+        Command* p = curr + commandCount;
+        for (auto [channel, passId, command, order, fn]: builder.mCustomCommands.value()) {
+            appendCustomCommand(p++, channel, passId, command, order, fn);
+        }
+    }
+
+    // sort commands once we're done adding commands
+    sortCommands(builder.mArena);
+
+    if (engine.isAutomaticInstancingEnabled()) {
+        instanceify(engine, builder.mArena);
+    }
+}
 
 // this destructor is actually heavy because it inlines ~vector<>
 RenderPass::~RenderPass() noexcept = default;
 
-RenderPass::Command* RenderPass::append(size_t count) noexcept {
-    // this is like an "in-place" realloc(). Works only with LinearAllocator.
-    Command* const curr = mCommandArena.alloc<Command>(count);
-    assert_invariant(curr);
-    assert_invariant(mCommandBegin == nullptr || curr == mCommandEnd);
-    if (mCommandBegin == nullptr) {
-        mCommandBegin = mCommandEnd = curr;
-    }
-    mCommandEnd += count;
-    return curr;
-}
-
-void RenderPass::resize(size_t count) noexcept {
+void RenderPass::resize(Arena& arena, size_t count) noexcept {
     if (mCommandBegin) {
         mCommandEnd = mCommandBegin + count;
-        mCommandArena.rewind(mCommandEnd);
+        arena.rewind(mCommandEnd);
     }
 }
 
-void RenderPass::setGeometry(FScene::RenderableSoa const& soa, Range<uint32_t> vr,
-        backend::Handle<backend::HwBufferObject> uboHandle) noexcept {
-    mRenderableSoa = &soa;
-    mVisibleRenderables = vr;
-    mUboHandle = uboHandle;
-}
-
-void RenderPass::setCamera(const CameraInfo& camera) noexcept {
-    mCameraPosition = camera.getPosition();
-    mCameraForwardVector = camera.getForwardVector();
-}
-
-void RenderPass::setScissorViewport(backend::Viewport viewport) noexcept {
-    assert_invariant(viewport.width  <= std::numeric_limits<int32_t>::max());
-    assert_invariant(viewport.height <= std::numeric_limits<int32_t>::max());
-    mScissorViewport = viewport;
-}
-
-void RenderPass::appendCommands(FEngine& engine, CommandTypeFlags const commandTypeFlags) noexcept {
+void RenderPass::appendCommands(FEngine& engine,
+        Slice<Command> commands, CommandTypeFlags const commandTypeFlags) noexcept {
     SYSTRACE_CALL();
     SYSTRACE_CONTEXT();
 
-    assert_invariant(mRenderableSoa);
-
     utils::Range<uint32_t> const vr = mVisibleRenderables;
     // trace the number of visible renderables
     SYSTRACE_VALUE32("visibleRenderables", vr.size());
@@ -104,17 +173,10 @@ void RenderPass::appendCommands(FEngine& engine, CommandTypeFlags const commandT
     const FScene::VisibleMaskType visibilityMask = mVisibilityMask;
 
     // up-to-date summed primitive counts needed for generateCommands()
-    FScene::RenderableSoa const& soa = *mRenderableSoa;
-    updateSummedPrimitiveCounts(const_cast<FScene::RenderableSoa&>(soa), vr);
+    FScene::RenderableSoa const& soa = mRenderableSoa;
 
-    // compute how much maximum storage we need for this pass
-    uint32_t commandCount = FScene::getPrimitiveCount(soa, vr.last);
-    // double the color pass for transparent objects that need to render twice
-    const bool colorPass  = bool(commandTypeFlags & CommandTypeFlags::COLOR);
-    const bool depthPass  = bool(commandTypeFlags & CommandTypeFlags::DEPTH);
-    commandCount *= uint32_t(colorPass * 2 + depthPass);
-    commandCount += 1; // for the sentinel
-    Command* const curr = append(commandCount);
+    Command* curr = commands.data();
+    size_t const commandCount = commands.size();
 
     auto stereoscopicEyeCount =
             renderFlags & IS_STEREOSCOPIC ? engine.getConfig().stereoscopicEyeCount : 1;
@@ -152,7 +214,8 @@ void RenderPass::appendCommands(FEngine& engine, CommandTypeFlags const commandT
     }
 }
 
-void RenderPass::appendCustomCommand(uint8_t channel, Pass pass, CustomCommand custom, uint32_t order,
+void RenderPass::appendCustomCommand(Command* commands,
+        uint8_t channel, Pass pass, CustomCommand custom, uint32_t order,
         Executor::CustomCommandFn command) {
 
     assert_invariant((uint64_t(order) << CUSTOM_ORDER_SHIFT) <=  CUSTOM_ORDER_MASK);
@@ -168,11 +231,10 @@ void RenderPass::appendCustomCommand(uint8_t channel, Pass pass, CustomCommand c
     cmd |= uint64_t(order) << CUSTOM_ORDER_SHIFT;
     cmd |= uint64_t(index);
 
-    Command* const curr = append(1);
-    curr->key = cmd;
+    commands->key = cmd;
 }
 
-void RenderPass::sortCommands(FEngine& engine) noexcept {
+void RenderPass::sortCommands(Arena& arena) noexcept {
     SYSTRACE_NAME("sort and trim commands");
 
     std::sort(mCommandBegin, mCommandEnd);
@@ -183,30 +245,20 @@ void RenderPass::sortCommands(FEngine& engine) noexcept {
                 return c.key != uint64_t(Pass::SENTINEL);
             });
 
-    resize(uint32_t(last - mCommandBegin));
-
-    if (engine.isAutomaticInstancingEnabled()) {
-        instanceify(engine);
-    }
+    resize(arena, uint32_t(last - mCommandBegin));
 }
 
-void RenderPass::execute(FEngine& engine, const char* name,
+void RenderPass::execute(RenderPass const& pass,
+        FEngine& engine, const char* name,
         backend::Handle<backend::HwRenderTarget> renderTarget,
-        backend::RenderPassParams params) const noexcept {
-
+        backend::RenderPassParams params) noexcept {
     DriverApi& driver = engine.getDriverApi();
-
-    // this is a good time to flush the CommandStream, because we're about to potentially
-    // output a lot of commands. This guarantees here that we have at least
-    // FILAMENT_MIN_COMMAND_BUFFERS_SIZE_IN_MB bytes (1MiB by default).
-    engine.flush();
-
     driver.beginRenderPass(renderTarget, params);
-    getExecutor().execute(engine, name);
+    pass.getExecutor().execute(engine, name);
     driver.endRenderPass();
 }
 
-void RenderPass::instanceify(FEngine& engine) noexcept {
+void RenderPass::instanceify(FEngine& engine, Arena& arena) noexcept {
     SYSTRACE_NAME("instanceify");
 
     // instanceify works by scanning the **sorted** command stream, looking for repeat draw
@@ -262,7 +314,8 @@ void RenderPass::instanceify(FEngine& engine) noexcept {
                 // buffer large enough for all instances data
                 stagingBufferSize = sizeof(PerRenderableData) * (last - curr);
                 stagingBuffer = (PerRenderableData*)::malloc(stagingBufferSize);
-                uboData = mRenderableSoa->data<FScene::UBO>();
+                uboData = mRenderableSoa.data<FScene::UBO>();
+                assert_invariant(uboData);
             }
 
             // copy the ubo data to a staging buffer
@@ -315,7 +368,7 @@ void RenderPass::instanceify(FEngine& engine) noexcept {
             return command.key == uint64_t(Pass::SENTINEL);
         });
 
-        resize(uint32_t(lastCommand - mCommandBegin));
+        resize(arena, uint32_t(lastCommand - mCommandBegin));
     }
 
     assert_invariant(stagingBuffer == nullptr);
@@ -323,7 +376,7 @@ void RenderPass::instanceify(FEngine& engine) noexcept {
 
 
 /* static */
-UTILS_ALWAYS_INLINE // this function exists only to make the code more readable. we want it inlined.
+UTILS_ALWAYS_INLINE // This function exists only to make the code more readable. we want it inlined.
 inline              // and we don't need it in the compilation unit
 void RenderPass::setupColorCommand(Command& cmdDraw, Variant variant,
         FMaterialInstance const* const UTILS_RESTRICT mi, bool inverseFrontFaces) noexcept {
@@ -374,7 +427,7 @@ void RenderPass::setupColorCommand(Command& cmdDraw, Variant variant,
 
 /* static */
 UTILS_NOINLINE
-void RenderPass::generateCommands(uint32_t commandTypeFlags, Command* const commands,
+void RenderPass::generateCommands(CommandTypeFlags commandTypeFlags, Command* const commands,
         FScene::RenderableSoa const& soa, Range<uint32_t> range,
         Variant variant, RenderFlags renderFlags,
         FScene::VisibleMaskType visibilityMask, float3 cameraPosition, float3 cameraForward,
@@ -432,9 +485,9 @@ void RenderPass::generateCommands(uint32_t commandTypeFlags, Command* const comm
 }
 
 /* static */
-template<uint32_t commandTypeFlags>
+template<RenderPass::CommandTypeFlags commandTypeFlags>
 UTILS_NOINLINE
-RenderPass::Command* RenderPass::generateCommandsImpl(uint32_t extraFlags,
+RenderPass::Command* RenderPass::generateCommandsImpl(RenderPass::CommandTypeFlags extraFlags,
         Command* UTILS_RESTRICT curr,
         FScene::RenderableSoa const& UTILS_RESTRICT soa, Range<uint32_t> range,
         Variant const variant, RenderFlags renderFlags, FScene::VisibleMaskType visibilityMask,
@@ -737,13 +790,13 @@ void RenderPass::updateSummedPrimitiveCounts(
 // ------------------------------------------------------------------------------------------------
 
 void RenderPass::Executor::overridePolygonOffset(backend::PolygonOffset const* polygonOffset) noexcept {
-    if ((mPolygonOffsetOverride = (polygonOffset != nullptr))) {
+    if ((mPolygonOffsetOverride = (polygonOffset != nullptr))) { // NOLINT(*-assignment-in-if-condition)
         mPolygonOffset = *polygonOffset;
     }
 }
 
 void RenderPass::Executor::overrideScissor(backend::Viewport const* scissor) noexcept {
-    if ((mScissorOverride = (scissor != nullptr))) {
+    if ((mScissorOverride = (scissor != nullptr))) { // NOLINT(*-assignment-in-if-condition)
         mScissor = *scissor;
     }
 }
@@ -754,15 +807,20 @@ void RenderPass::Executor::overrideScissor(backend::Viewport const& scissor) noe
 }
 
 void RenderPass::Executor::execute(FEngine& engine, const char*) const noexcept {
-    execute(engine.getDriverApi(), mCommands.begin(), mCommands.end());
+    execute(engine, mCommands.begin(), mCommands.end());
 }
 
 UTILS_NOINLINE // no need to be inlined
-void RenderPass::Executor::execute(backend::DriverApi& driver,
+void RenderPass::Executor::execute(FEngine& engine,
         const Command* first, const Command* last) const noexcept {
+
     SYSTRACE_CALL();
     SYSTRACE_CONTEXT();
 
+    DriverApi& driver = engine.getDriverApi();
+    size_t const capacity = engine.getMinCommandBufferSize();
+    CircularBuffer const& circularBuffer = driver.getCircularBuffer();
+
     if (first != last) {
         SYSTRACE_VALUE32("commandCount", last - first);
 
@@ -781,126 +839,163 @@ void RenderPass::Executor::execute(backend::DriverApi& driver,
         FMaterial const* UTILS_RESTRICT ma = nullptr;
         auto const* UTILS_RESTRICT pCustomCommands = mCustomCommands.data();
 
-        first--;
-        while (++first != last) {
-            assert_invariant(first->key != uint64_t(Pass::SENTINEL));
+        // Maximum space occupied in the CircularBuffer by a single `Command`. This must be
+        // reevaluated when the inner loop below adds DriverApi commands or when we change the
+        // CommandStream protocol. Currently, the maximum is 240 bytes, and we use 256 to be on
+        // the safer side.
+        size_t const maxCommandSizeInBytes = 256;
 
-            /*
-             * Be careful when changing code below, this is the hot inner-loop
-             */
+        // Number of Commands that can be issued and guaranteed to fit in the current
+        // CircularBuffer allocation. In practice, we'll have tons of headroom especially if
+        // skinning and morphing aren't used. With a 2 MiB buffer (the default) a batch is
+        // 8192 commands (i.e. draw calls).
+        size_t const batchCommandCount = capacity / maxCommandSizeInBytes;
+        while(first != last) {
+            Command const* const batchLast = std::min(first + batchCommandCount, last);
 
-            if (UTILS_UNLIKELY((first->key & CUSTOM_MASK) != uint64_t(CustomCommand::PASS))) {
-                mi = nullptr; // custom command could change the currently bound MaterialInstance
-                uint32_t const index = (first->key & CUSTOM_INDEX_MASK) >> CUSTOM_INDEX_SHIFT;
-                assert_invariant(index < mCustomCommands.size());
-                pCustomCommands[index]();
-                continue;
+            // actual number of commands we need to write (can be smaller than batchCommandCount)
+            size_t const commandCount = batchLast - first;
+            size_t const commandSizeInBytes = commandCount * maxCommandSizeInBytes;
+
+            // check we have enough capacity to write these commandCount commands, if not,
+            // request a new CircularBuffer allocation of `capacity` bytes.
+            if (UTILS_UNLIKELY(circularBuffer.getUsed() > capacity - commandSizeInBytes)) {
+                engine.flush(); // TODO: we should use a "fast" flush if possible
             }
 
-            // primitiveHandle may be invalid if no geometry was set on the renderable.
-            if (UTILS_UNLIKELY(!first->primitive.primitiveHandle)) {
-                continue;
-            }
+            first--;
+            while (++first != batchLast) {
+                assert_invariant(first->key != uint64_t(Pass::SENTINEL));
 
-            // per-renderable uniform
-            const PrimitiveInfo info = first->primitive;
-            pipeline.rasterState = info.rasterState;
+                /*
+                 * Be careful when changing code below, this is the hot inner-loop
+                 */
 
-            if (UTILS_UNLIKELY(mi != info.mi)) {
-                // this is always taken the first time
-                mi = info.mi;
-                ma = mi->getMaterial();
-
-                auto const& scissor = mi->getScissor();
-                if (UTILS_UNLIKELY(mi->hasScissor())) {
-                    // scissor is set, we need to apply the offset/clip
-                    // clang vectorizes this!
-                    constexpr int32_t maxvali = std::numeric_limits<int32_t>::max();
-                    const backend::Viewport scissorViewport = mScissorViewport;
-                    // compute new left/bottom, assume no overflow
-                    int32_t l = scissor.left + scissorViewport.left;
-                    int32_t b = scissor.bottom + scissorViewport.bottom;
-                    // compute right/top without overflowing, scissor.width/height guaranteed
-                    // to convert to int32
-                    int32_t r = (l > maxvali - int32_t(scissor.width)) ?
-                            maxvali : l + int32_t(scissor.width);
-                    int32_t t = (b > maxvali - int32_t(scissor.height)) ?
-                            maxvali : b + int32_t(scissor.height);
-                    // clip to the viewport
-                    l = std::max(l, scissorViewport.left);
-                    b = std::max(b, scissorViewport.bottom);
-                    r = std::min(r, scissorViewport.left + int32_t(scissorViewport.width));
-                    t = std::min(t, scissorViewport.bottom + int32_t(scissorViewport.height));
-                    assert_invariant(r >= l && t >= b);
-                    *pScissor = { l, b, uint32_t(r - l), uint32_t(t - b) };
-                } else {
-                    // no scissor set (common case), 'scissor' has its default value, use that.
-                    *pScissor = scissor;
+                if (UTILS_UNLIKELY((first->key & CUSTOM_MASK) != uint64_t(CustomCommand::PASS))) {
+                    mi = nullptr; // custom command could change the currently bound MaterialInstance
+                    uint32_t const index = (first->key & CUSTOM_INDEX_MASK) >> CUSTOM_INDEX_SHIFT;
+                    assert_invariant(index < mCustomCommands.size());
+                    pCustomCommands[index]();
+                    continue;
                 }
 
-                *pPipelinePolygonOffset = mi->getPolygonOffset();
-                pipeline.stencilState = mi->getStencilState();
-                mi->use(driver);
-            }
-
-            pipeline.program = ma->getProgram(info.materialVariant);
-
-            uint16_t const instanceCount = info.instanceCount & PrimitiveInfo::INSTANCE_COUNT_MASK;
-            auto getPerObjectUboHandle =
-                    [this, &info, &instanceCount]() -> std::pair<Handle<backend::HwBufferObject>, uint32_t> {
-                if (info.instanceBufferHandle) {
-                    // "hybrid" instancing -- instanceBufferHandle takes the place of the UBO
-                    return { info.instanceBufferHandle, 0 };
+                // primitiveHandle may be invalid if no geometry was set on the renderable.
+                if (UTILS_UNLIKELY(!first->primitive.primitiveHandle)) {
+                    continue;
                 }
-                bool const userInstancing =
-                        (info.instanceCount & PrimitiveInfo::USER_INSTANCE_MASK) != 0u;
-                if (!userInstancing && instanceCount > 1) {
-                    // automatic instancing
-                    return { mInstancedUboHandle, info.index * sizeof(PerRenderableData) };
-                } else {
-                    // manual instancing
-                    return { mUboHandle, info.index * sizeof(PerRenderableData) };
+
+                // per-renderable uniform
+                const PrimitiveInfo info = first->primitive;
+                pipeline.rasterState = info.rasterState;
+
+                if (UTILS_UNLIKELY(mi != info.mi)) {
+                    // this is always taken the first time
+                    mi = info.mi;
+                    assert_invariant(mi);
+
+                    ma = mi->getMaterial();
+
+                    auto const& scissor = mi->getScissor();
+                    if (UTILS_UNLIKELY(mi->hasScissor())) {
+                        // scissor is set, we need to apply the offset/clip
+                        // clang vectorizes this!
+                        constexpr int32_t maxvali = std::numeric_limits<int32_t>::max();
+                        const backend::Viewport scissorViewport = mScissorViewport;
+                        // compute new left/bottom, assume no overflow
+                        int32_t l = scissor.left + scissorViewport.left;
+                        int32_t b = scissor.bottom + scissorViewport.bottom;
+                        // compute right/top without overflowing, scissor.width/height guaranteed
+                        // to convert to int32
+                        int32_t r = (l > maxvali - int32_t(scissor.width)) ?
+                                    maxvali : l + int32_t(scissor.width);
+                        int32_t t = (b > maxvali - int32_t(scissor.height)) ?
+                                    maxvali : b + int32_t(scissor.height);
+                        // clip to the viewport
+                        l = std::max(l, scissorViewport.left);
+                        b = std::max(b, scissorViewport.bottom);
+                        r = std::min(r, scissorViewport.left + int32_t(scissorViewport.width));
+                        t = std::min(t, scissorViewport.bottom + int32_t(scissorViewport.height));
+                        assert_invariant(r >= l && t >= b);
+                        *pScissor = { l, b, uint32_t(r - l), uint32_t(t - b) };
+                    } else {
+                        // no scissor set (common case), 'scissor' has its default value, use that.
+                        *pScissor = scissor;
+                    }
+
+                    *pPipelinePolygonOffset = mi->getPolygonOffset();
+                    pipeline.stencilState = mi->getStencilState();
+                    mi->use(driver);
                 }
-            };
 
-            // bind per-renderable uniform block. there is no need to attempt to skip this command
-            // because the backends already do this.
-            auto const [perObjectUboHandle, offset] = getPerObjectUboHandle();
-            assert_invariant(perObjectUboHandle);
-            driver.bindBufferRange(BufferObjectBinding::UNIFORM,
-                    +UniformBindingPoints::PER_RENDERABLE,
-                    perObjectUboHandle,
-                    offset,
-                    sizeof(PerRenderableUib));
+                assert_invariant(ma);
+                pipeline.program = ma->getProgram(info.materialVariant);
 
-            if (UTILS_UNLIKELY(info.skinningHandle)) {
-                // note: we can't bind less than sizeof(PerRenderableBoneUib) due to glsl limitations
+                uint16_t const instanceCount =
+                        info.instanceCount & PrimitiveInfo::INSTANCE_COUNT_MASK;
+                auto getPerObjectUboHandle =
+                        [this, &info, &instanceCount]() -> std::pair<Handle<backend::HwBufferObject>, uint32_t> {
+                            if (info.instanceBufferHandle) {
+                                // "hybrid" instancing -- instanceBufferHandle takes the place of the UBO
+                                return { info.instanceBufferHandle, 0 };
+                            }
+                            bool const userInstancing =
+                                    (info.instanceCount & PrimitiveInfo::USER_INSTANCE_MASK) != 0u;
+                            if (!userInstancing && instanceCount > 1) {
+                                // automatic instancing
+                                return {
+                                        mInstancedUboHandle,
+                                        info.index * sizeof(PerRenderableData) };
+                            } else {
+                                // manual instancing
+                                return { mUboHandle, info.index * sizeof(PerRenderableData) };
+                            }
+                        };
+
+                // Bind per-renderable uniform block. There is no need to attempt to skip this command
+                // because the backends already do this.
+                auto const [perObjectUboHandle, offset] = getPerObjectUboHandle();
+                assert_invariant(perObjectUboHandle);
                 driver.bindBufferRange(BufferObjectBinding::UNIFORM,
-                        +UniformBindingPoints::PER_RENDERABLE_BONES,
-                        info.skinningHandle,
-                        info.skinningOffset * sizeof(PerRenderableBoneUib::BoneData),
-                        sizeof(PerRenderableBoneUib));
-                // note: always bind the skinningTexture because the shader needs it.
-                driver.bindSamplers(+SamplerBindingPoints::PER_RENDERABLE_SKINNING,
-                        info.skinningTexture);
-                // note: even if only skinning is enabled, binding morphTargetBuffer is needed.
-                driver.bindSamplers(+SamplerBindingPoints::PER_RENDERABLE_MORPHING,
-                        info.morphTargetBuffer);
-           }
+                        +UniformBindingPoints::PER_RENDERABLE,
+                        perObjectUboHandle,
+                        offset,
+                        sizeof(PerRenderableUib));
 
-            if (UTILS_UNLIKELY(info.morphWeightBuffer)) {
-                // Instead of using a UBO per primitive, we could also have a single UBO for all
-                // primitives and use bindUniformBufferRange which might be more efficient.
-                driver.bindUniformBuffer(+UniformBindingPoints::PER_RENDERABLE_MORPHING,
-                        info.morphWeightBuffer);
-                driver.bindSamplers(+SamplerBindingPoints::PER_RENDERABLE_MORPHING,
-                        info.morphTargetBuffer);
-                // note: even if only morphing is enabled, binding skinningTexture is needed.
-                driver.bindSamplers(+SamplerBindingPoints::PER_RENDERABLE_SKINNING,
-                        info.skinningTexture);
+                if (UTILS_UNLIKELY(info.skinningHandle)) {
+                    // note: we can't bind less than sizeof(PerRenderableBoneUib) due to glsl limitations
+                    driver.bindBufferRange(BufferObjectBinding::UNIFORM,
+                            +UniformBindingPoints::PER_RENDERABLE_BONES,
+                            info.skinningHandle,
+                            info.skinningOffset * sizeof(PerRenderableBoneUib::BoneData),
+                            sizeof(PerRenderableBoneUib));
+                    // note: always bind the skinningTexture because the shader needs it.
+                    driver.bindSamplers(+SamplerBindingPoints::PER_RENDERABLE_SKINNING,
+                            info.skinningTexture);
+                    // note: even if only skinning is enabled, binding morphTargetBuffer is needed.
+                    driver.bindSamplers(+SamplerBindingPoints::PER_RENDERABLE_MORPHING,
+                            info.morphTargetBuffer);
+                }
+
+                if (UTILS_UNLIKELY(info.morphWeightBuffer)) {
+                    // Instead of using a UBO per primitive, we could also have a single UBO for all
+                    // primitives and use bindUniformBufferRange which might be more efficient.
+                    driver.bindUniformBuffer(+UniformBindingPoints::PER_RENDERABLE_MORPHING,
+                            info.morphWeightBuffer);
+                    driver.bindSamplers(+SamplerBindingPoints::PER_RENDERABLE_MORPHING,
+                            info.morphTargetBuffer);
+                    // note: even if only morphing is enabled, binding skinningTexture is needed.
+                    driver.bindSamplers(+SamplerBindingPoints::PER_RENDERABLE_SKINNING,
+                            info.skinningTexture);
+                }
+
+                driver.draw(pipeline, info.primitiveHandle, instanceCount);
             }
+        }
 
-            driver.draw(pipeline, info.primitiveHandle, instanceCount);
+        // If the remaining space is less than half the capacity, we flush right away to
+        // allow some headroom for commands that might come later.
+        if (UTILS_UNLIKELY(circularBuffer.getUsed() > capacity / 2)) {
+            engine.flush();
         }
     }