Prevent circular buffer overflow during UboManager reallocation (#9714)

When UboManager::reallocate() is triggered, a large number of material instances may be invalidated simultaneously. This leads to a massive spike in descriptor set updates and command generation, which can overflow the circular buffer.

To prevent this, we now flush commands in batches, we trigger a flush whenever the command buffer usage exceeds half of its capacity. (Like what RenderPass::Executor::execute does)

BUGS = [474264976, 479079631]

CMakeLists.txt

@@ -49,6 +49,8 @@ option(FILAMENT_ENABLE_COVERAGE "Enable LLVM code coverage" OFF)
 
 option(FILAMENT_ENABLE_FEATURE_LEVEL_0 "Enable Feature Level 0" ON)
 
+option(FILAMENT_ENABLE_MULTIVIEW "Enable multiview for Filament" OFF)
+
 option(FILAMENT_SUPPORTS_OSMESA "Enable OSMesa (headless GL context) for Filament" OFF)
 
 option(FILAMENT_ENABLE_FGVIEWER "Enable the frame graph viewer" OFF)
@@ -605,6 +607,23 @@ else()
     option(FILAMENT_DISABLE_MATOPT "Disable material optimizations" ON)
 endif()
 
+# This only affects the prebuilt shader files in gltfio and samples, not filament library.
+# The value can be either "instanced", "multiview", or "none"
+set(FILAMENT_SAMPLES_STEREO_TYPE "none" CACHE STRING
+    "Stereoscopic type that shader files in gltfio and samples are built for."
+)
+string(TOLOWER "${FILAMENT_SAMPLES_STEREO_TYPE}" FILAMENT_SAMPLES_STEREO_TYPE)
+if (NOT FILAMENT_SAMPLES_STEREO_TYPE STREQUAL "instanced"
+    AND NOT FILAMENT_SAMPLES_STEREO_TYPE STREQUAL "multiview"
+    AND NOT FILAMENT_SAMPLES_STEREO_TYPE STREQUAL "none")
+    message(FATAL_ERROR "Invalid stereo type: \"${FILAMENT_SAMPLES_STEREO_TYPE}\" choose either \"instanced\",  \"multiview\", or \"none\" ")
+endif ()
+
+# Compiling samples for multiview implies enabling multiview feature as well.
+if (FILAMENT_SAMPLES_STEREO_TYPE STREQUAL "multiview")
+    set(FILAMENT_ENABLE_MULTIVIEW ON)
+endif ()
+
 # Define backend flag for debug only
 if (CMAKE_BUILD_TYPE STREQUAL "Debug" AND NOT FILAMENT_BACKEND_DEBUG_FLAG STREQUAL "")
     add_definitions(-DFILAMENT_BACKEND_DEBUG_FLAG=${FILAMENT_BACKEND_DEBUG_FLAG})

README.md

@@ -31,7 +31,7 @@ repositories {
 }
 
 dependencies {
-    implementation 'com.google.android.filament:filament-android:1.69.2'
+    implementation 'com.google.android.filament:filament-android:1.69.3'
 }
 ```
 
@@ -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.69.2'
+pod 'Filament', '~> 1.69.3'
 ```
 
 ## Documentation

android/gradle.properties

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

build.sh

@@ -214,6 +214,8 @@ ENABLE_PERFETTO=""
 
 BACKEND_DEBUG_FLAG_OPTION=""
 
+STEREOSCOPIC_OPTION=""
+
 OSMESA_OPTION=""
 
 IOS_BUILD_SIMULATOR=false
@@ -314,6 +316,7 @@ function build_desktop_target {
             ${ASAN_UBSAN_OPTION} \
             ${COVERAGE_OPTION} \
             ${BACKEND_DEBUG_FLAG_OPTION} \
+            ${STEREOSCOPIC_OPTION} \
             ${OSMESA_OPTION} \
             ${architectures} \
             ../..
@@ -452,6 +455,7 @@ function build_android_target {
             ${VULKAN_ANDROID_OPTION} \
             ${WEBGPU_OPTION} \
             ${BACKEND_DEBUG_FLAG_OPTION} \
+            ${STEREOSCOPIC_OPTION} \
             ${ENABLE_PERFETTO} \
             ../..
         ln -sf "out/cmake-android-${lc_target}-${arch}/compile_commands.json" \
@@ -693,6 +697,7 @@ function build_ios_target {
             ${WEBGPU_OPTION} \
             ${MATDBG_OPTION} \
             ${MATOPT_OPTION} \
+            ${STEREOSCOPIC_OPTION} \
             ../..
         ln -sf "out/cmake-ios-${lc_target}-${arch}/compile_commands.json" \
            ../../compile_commands.json
@@ -1006,6 +1011,20 @@ while getopts ":hacCfgimp:q:uvWslwedtk:bVx:S:X:Py:" opt; do
             ;;
         x)  BACKEND_DEBUG_FLAG_OPTION="-DFILAMENT_BACKEND_DEBUG_FLAG=${OPTARG}"
             ;;
+        S)  case $(echo "${OPTARG}" | tr '[:upper:]' '[:lower:]') in
+                instanced)
+                    STEREOSCOPIC_OPTION="-DFILAMENT_SAMPLES_STEREO_TYPE=instanced"
+                    ;;
+                multiview)
+                    STEREOSCOPIC_OPTION="-DFILAMENT_SAMPLES_STEREO_TYPE=multiview"
+                    ;;
+                *)
+                    echo "Unknown stereoscopic type ${OPTARG}"
+                    echo "Type must be one of [instanced|multiview]"
+                    echo ""
+                    exit 1
+            esac
+            ;;
         X)  OSMESA_OPTION="-DFILAMENT_OSMESA_PATH=${OPTARG}"
             ;;
         y)

filament/CMakeLists.txt

@@ -314,6 +314,12 @@ set(MATERIAL_FL0_SRCS
         src/materials/skybox.mat
 )
 
+set(MATERIAL_MULTIVIEW_SRCS
+        src/materials/clearDepth.mat
+        src/materials/defaultMaterial.mat
+        src/materials/skybox.mat
+)
+
 # ==================================================================================================
 # Configuration
 # ==================================================================================================
@@ -338,6 +344,11 @@ if (FILAMENT_ENABLE_FEATURE_LEVEL_0)
     add_definitions(-DFILAMENT_ENABLE_FEATURE_LEVEL_0)
 endif()
 
+# Whether to include MULTIVIEW materials.
+if (FILAMENT_ENABLE_MULTIVIEW)
+    add_definitions(-DFILAMENT_ENABLE_MULTIVIEW)
+endif()
+
 # Whether to force the profiling mode.
 if (FILAMENT_FORCE_PROFILING_MODE)
     add_definitions(-DFILAMENT_FORCE_PROFILING_MODE)
@@ -428,6 +439,21 @@ foreach(mat_dir ${MATERIAL_DIRS})
             list(APPEND FILAMAT_FILES_FOR_GROUP ${output_path_fl0})
             list(APPEND FILAMAT_TARGETS_FOR_GROUP ${output_path_fl0})
         endif()
+
+        # --- Multiview variant ---
+        list(FIND MATERIAL_MULTIVIEW_SRCS ${mat_src} index)
+        if (${index} GREATER -1 AND FILAMENT_ENABLE_MULTIVIEW)
+            string(REGEX REPLACE "[.]filamat$" "_multiview.filamat" output_path_multiview ${output_path})
+            add_custom_command(
+                    OUTPUT ${output_path_multiview}
+                    COMMAND matc ${MATC_BASE_FLAGS} -PstereoscopicType=multiview -o ${output_path_multiview} ${fullname}
+                    MAIN_DEPENDENCY ${fullname}
+                    DEPENDS matc
+                    COMMENT "Compiling material ${fullname} (Multiview)"
+            )
+            list(APPEND FILAMAT_FILES_FOR_GROUP ${output_path_multiview})
+            list(APPEND FILAMAT_TARGETS_FOR_GROUP ${output_path_multiview})
+        endif()
     endforeach()
 
     # Generate a single resource file for the whole group

filament/src/details/Engine.cpp

@@ -462,8 +462,22 @@ void FEngine::init() {
 #endif
     {
         FMaterial::DefaultMaterialBuilder defaultMaterialBuilder;
-        defaultMaterialBuilder.package(
-                MATERIALS_DEFAULTMATERIAL_DATA, MATERIALS_DEFAULTMATERIAL_SIZE);
+        switch (mConfig.stereoscopicType) {
+            case StereoscopicType::NONE:
+            case StereoscopicType::INSTANCED:
+                defaultMaterialBuilder.package(
+                        MATERIALS_DEFAULTMATERIAL_DATA, MATERIALS_DEFAULTMATERIAL_SIZE);
+                break;
+            case StereoscopicType::MULTIVIEW:
+#ifdef FILAMENT_ENABLE_MULTIVIEW
+                defaultMaterialBuilder.package(
+                        MATERIALS_DEFAULTMATERIAL_MULTIVIEW_DATA,
+                        MATERIALS_DEFAULTMATERIAL_MULTIVIEW_SIZE);
+#else
+                assert_invariant(false);
+#endif
+                break;
+        }
         mDefaultMaterial = downcast(defaultMaterialBuilder.build(*this));
     }
 
@@ -721,14 +735,21 @@ void FEngine::prepare(DriverApi& driver) {
     }
 
     UboManager* uboManager = mUboManager;
+    size_t const capacity = getMinCommandBufferSize();
     for (auto& materialInstanceList: mMaterialInstances) {
-        materialInstanceList.second.forEach([&driver, uboManager](FMaterialInstance const* item) {
-            // post-process materials instances must be commited explicitly because their
-            // parameters are typically not set at this point in time.
-            if (item->getMaterial()->getMaterialDomain() == MaterialDomain::SURFACE) {
-                item->commit(driver, uboManager);
-            }
-        });
+        materialInstanceList.second.forEach(
+                [this, &driver, uboManager, capacity](FMaterialInstance const* item) {
+                    // post-process materials instances must be commited explicitly because their
+                    // parameters are typically not set at this point in time.
+                    if (item->getMaterial()->getMaterialDomain() == MaterialDomain::SURFACE) {
+                        // 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(driver.getCircularBuffer().getUsed() > capacity / 2)) {
+                            flush();
+                        }
+                        item->commit(driver, uboManager);
+                    }
+                });
     }
 
     if (useUboBatching) {

filament/src/details/Skybox.cpp

@@ -138,7 +138,20 @@ FMaterial const* FSkybox::createMaterial(FEngine& engine) {
     } else
 #endif
     {
-        builder.package(MATERIALS_SKYBOX_DATA, MATERIALS_SKYBOX_SIZE);
+        switch (engine.getConfig().stereoscopicType) {
+            case Engine::StereoscopicType::NONE:
+            case Engine::StereoscopicType::INSTANCED:
+                builder.package(MATERIALS_SKYBOX_DATA, MATERIALS_SKYBOX_SIZE);
+                break;
+            case Engine::StereoscopicType::MULTIVIEW:
+#ifdef FILAMENT_ENABLE_MULTIVIEW
+                builder.package(MATERIALS_SKYBOX_MULTIVIEW_DATA, MATERIALS_SKYBOX_MULTIVIEW_SIZE);
+#else
+                PANIC_POSTCONDITION("Multiview is enabled in the Engine, but this build has not "
+                                    "been compiled for multiview.");
+#endif
+                break;
+        }
     }
     auto material = builder.build(engine);
     return downcast(material);

ios/CocoaPods/Filament.podspec

@@ -1,12 +1,12 @@
 Pod::Spec.new do |spec|
   spec.name = "Filament"
-  spec.version = "1.69.2"
+  spec.version = "1.69.3"
   spec.license = { :type => "Apache 2.0", :file => "LICENSE" }
   spec.homepage = "https://google.github.io/filament"
   spec.authors = "Google LLC."
   spec.summary = "Filament is a real-time physically based rendering engine for Android, iOS, Windows, Linux, macOS, and WASM/WebGL."
   spec.platform = :ios, "11.0"
-  spec.source = { :http => "https://github.com/google/filament/releases/download/v1.69.2/filament-v1.69.2-ios.tgz" }
+  spec.source = { :http => "https://github.com/google/filament/releases/download/v1.69.3/filament-v1.69.3-ios.tgz" }
 
   spec.libraries = 'c++'
 

libs/filagui/CMakeLists.txt

@@ -40,13 +40,20 @@ endif()
 
 file(MAKE_DIRECTORY ${MATERIAL_DIR})
 
+set (MATC_FLAGS ${MATC_BASE_FLAGS})
+if (FILAMENT_SAMPLES_STEREO_TYPE STREQUAL "instanced")
+    set (MATC_FLAGS ${MATC_FLAGS} -PstereoscopicType=instanced)
+elseif (FILAMENT_SAMPLES_STEREO_TYPE STREQUAL "multiview")
+    set (MATC_FLAGS ${MATC_FLAGS} -PstereoscopicType=multiview)
+endif ()
+
 foreach (mat_src ${MATERIAL_SRCS})
     get_filename_component(localname "${mat_src}" NAME_WE)
     get_filename_component(fullname "${mat_src}" ABSOLUTE)
     set(output_path "${MATERIAL_DIR}/${localname}.filamat")
     add_custom_command(
             OUTPUT ${output_path}
-            COMMAND matc ${MATC_BASE_FLAGS} -o ${output_path} ${fullname}
+            COMMAND matc ${MATC_FLAGS} -o ${output_path} ${fullname}
             DEPENDS ${mat_src} matc
             COMMENT "Compiling material ${mat_src} to ${output_path}"
     )

libs/filamat/include/filamat/MaterialBuilder.h

@@ -939,7 +939,7 @@ private:
     Interpolation mInterpolation = Interpolation::SMOOTH;
     VertexDomain mVertexDomain = VertexDomain::OBJECT;
     TransparencyMode mTransparencyMode = TransparencyMode::DEFAULT;
-    StereoscopicType mStereoscopicType = StereoscopicType::MULTIVIEW;
+    StereoscopicType mStereoscopicType = StereoscopicType::INSTANCED;
     uint8_t mStereoscopicEyeCount = 2;
 
     filament::AttributeBitset mRequiredAttributes;

libs/filamentapp/CMakeLists.txt

@@ -114,13 +114,22 @@ file(MAKE_DIRECTORY ${RESOURCE_DIR})
 
 set(RESOURCE_BINS)
 
+set (MATC_FLAGS ${MATC_BASE_FLAGS})
+if (FILAMENT_SAMPLES_STEREO_TYPE STREQUAL "instanced")
+    set (MATC_FLAGS ${MATC_FLAGS} -PstereoscopicType=instanced)
+    add_definitions(-DFILAMENT_SAMPLES_STEREO_TYPE_INSTANCED)
+elseif (FILAMENT_SAMPLES_STEREO_TYPE STREQUAL "multiview")
+    set (MATC_FLAGS ${MATC_FLAGS} -PstereoscopicType=multiview)
+    add_definitions(-DFILAMENT_SAMPLES_STEREO_TYPE_MULTIVIEW)
+endif ()
+
 foreach (mat_src ${MATERIAL_SRCS})
     get_filename_component(localname "${mat_src}" NAME_WE)
     get_filename_component(fullname "${mat_src}" ABSOLUTE)
     set(output_path "${MATERIAL_DIR}/${localname}.filamat")
     add_custom_command(
             OUTPUT ${output_path}
-            COMMAND matc ${MATC_BASE_FLAGS} -o ${output_path} ${fullname}
+            COMMAND matc ${MATC_FLAGS} -o ${output_path} ${fullname}
             MAIN_DEPENDENCY ${mat_src}
             DEPENDS matc
             COMMENT "Compiling material ${mat_src} to ${output_path}"

libs/filamentapp/src/FilamentApp.cpp

@@ -741,7 +741,13 @@ FilamentApp::Window::Window(FilamentApp* filamentApp,
 
         Engine::Config engineConfig = {};
         engineConfig.stereoscopicEyeCount = config.stereoscopicEyeCount;
+#if defined(FILAMENT_SAMPLES_STEREO_TYPE_INSTANCED)
+        engineConfig.stereoscopicType = Engine::StereoscopicType::INSTANCED;
+#elif defined (FILAMENT_SAMPLES_STEREO_TYPE_MULTIVIEW)
         engineConfig.stereoscopicType = Engine::StereoscopicType::MULTIVIEW;
+#else
+        engineConfig.stereoscopicType = Engine::StereoscopicType::NONE;
+#endif
 
         backend::Platform* platform = nullptr;
 #if defined(FILAMENT_DRIVER_SUPPORTS_VULKAN)

libs/gltfio/CMakeLists.txt

@@ -79,6 +79,13 @@ set(TRANSPARENCY default)
 
 set(UBERZ_OUTPUT_PATH "${RESOURCE_DIR}/default.uberz")
 
+set (MATC_FLAGS ${MATC_BASE_FLAGS})
+if (FILAMENT_SAMPLES_STEREO_TYPE STREQUAL "instanced")
+    set (MATC_FLAGS ${MATC_FLAGS} -PstereoscopicType=instanced)
+elseif (FILAMENT_SAMPLES_STEREO_TYPE STREQUAL "multiview")
+    set (MATC_FLAGS ${MATC_FLAGS} -PstereoscopicType=multiview)
+endif ()
+
 function(build_ubershader NAME SRC SHADINGMODEL BLENDING)
     set(DEST "${RESOURCE_DIR}/${NAME}")
     configure_file(materials/${SRC}.mat.in "${DEST}.mat" COPYONLY)
@@ -95,7 +102,7 @@ function(build_ubershader NAME SRC SHADINGMODEL BLENDING)
 
     add_custom_command(
         OUTPUT "${NAME}.filamat"
-        COMMAND matc ${MATC_BASE_FLAGS} ${TEMPLATE_ARGS} -o "${NAME}.filamat" "${NAME}.mat"
+        COMMAND matc ${MATC_FLAGS} ${TEMPLATE_ARGS} -o "${NAME}.filamat" "${NAME}.mat"
         DEPENDS matc "${DEST}.mat"
         WORKING_DIRECTORY ${RESOURCE_DIR}
         COMMENT "Compiling material ${NAME}")

libs/viewer/CMakeLists.txt

@@ -34,6 +34,12 @@ target_link_libraries(${TARGET} PUBLIC imgui filament gltfio_core filagui jsmn c
 target_include_directories(${TARGET} PUBLIC ${PUBLIC_HDR_DIR})
 set_target_properties(${TARGET} PROPERTIES FOLDER Libs)
 
+if (FILAMENT_SAMPLES_STEREO_TYPE STREQUAL "instanced")
+    add_definitions(-DFILAMENT_SAMPLES_STEREO_TYPE_INSTANCED)
+elseif (FILAMENT_SAMPLES_STEREO_TYPE STREQUAL "multiview")
+    add_definitions(-DFILAMENT_SAMPLES_STEREO_TYPE_MULTIVIEW)
+endif ()
+
 # ==================================================================================================
 # Compiler flags
 # ==================================================================================================

libs/viewer/src/ViewerGui.cpp

@@ -1153,13 +1153,15 @@ void ViewerGui::updateUserInterface() {
             ImGui::ListBox("Cameras", &mCurrentCamera, cstrings.data(), cstrings.size());
         }
 
+#if defined(FILAMENT_SAMPLES_STEREO_TYPE_INSTANCED)                                                \
+        || defined(FILAMENT_SAMPLES_STEREO_TYPE_MULTIVIEW)
         ImGui::Checkbox("Stereo mode", &mSettings.view.stereoscopicOptions.enabled);
-
+#if defined(FILAMENT_SAMPLES_STEREO_TYPE_MULTIVIEW)
         ImGui::Indent();
         ImGui::Checkbox("Combine Multiview Images",
                 debug.getPropertyAddress<bool>("d.stereo.combine_multiview_images"));
         ImGui::Unindent();
-
+#endif
         ImGui::SliderFloat("Ocular distance", &mSettings.camera.eyeOcularDistance, 0.0f, 1.0f);
 
         float toeInDegrees = mSettings.camera.eyeToeIn / f::PI * 180.0f;
@@ -1167,6 +1169,7 @@ void ViewerGui::updateUserInterface() {
         mSettings.camera.eyeToeIn = toeInDegrees / 180.0f * f::PI;
 
         ImGui::Unindent();
+#endif
     }
 
     if (ImGui::CollapsingHeader("Debug Options")) {

samples/CMakeLists.txt

@@ -54,13 +54,22 @@ endif()
 
 file(MAKE_DIRECTORY ${MATERIAL_DIR})
 
+set (MATC_FLAGS ${MATC_BASE_FLAGS})
+if (FILAMENT_SAMPLES_STEREO_TYPE STREQUAL "instanced")
+    set (MATC_FLAGS ${MATC_FLAGS} -PstereoscopicType=instanced)
+    add_definitions(-DFILAMENT_SAMPLES_STEREO_TYPE_INSTANCED)
+elseif (FILAMENT_SAMPLES_STEREO_TYPE STREQUAL "multiview")
+    set (MATC_FLAGS ${MATC_FLAGS} -PstereoscopicType=multiview)
+    add_definitions(-DFILAMENT_SAMPLES_STEREO_TYPE_MULTIVIEW)
+endif ()
+
 foreach (mat_src ${MATERIAL_SRCS})
     get_filename_component(localname "${mat_src}" NAME_WE)
     get_filename_component(fullname "${mat_src}" ABSOLUTE)
     set(output_path "${MATERIAL_DIR}/${localname}.filamat")
     add_custom_command(
             OUTPUT ${output_path}
-            COMMAND matc ${MATC_BASE_FLAGS} -o ${output_path} ${fullname}
+            COMMAND matc ${MATC_FLAGS} -o ${output_path} ${fullname}
             MAIN_DEPENDENCY ${mat_src}
             DEPENDS matc
             COMMENT "Compiling material ${mat_src} to ${output_path}"

samples/hellostereo.cpp

@@ -160,6 +160,12 @@ static int handleCommandLineArguments(int argc, char* argv[], App* app) {
 }
 
 int main(int argc, char** argv) {
+
+#if !defined(FILAMENT_SAMPLES_STEREO_TYPE_MULTIVIEW)
+    std::cerr << "This sample only works with multiview enabled.\n";
+    exit(1);
+#endif
+
     App app{};
     app.config.title = "stereoscopic rendering";
     handleCommandLineArguments(argc, argv, &app);

web/filament-js/package.json

@@ -1,6 +1,6 @@
 {
   "name": "filament",
-  "version": "1.69.2",
+  "version": "1.69.3",
   "description": "Real-time physically based rendering engine",
   "main": "filament.js",
   "module": "filament.js",