Update Gitignore to ignore generated files.

- Re-enable renderdiff test.
- Cache the mesa directory so that we're not spending time pulling
  and compiling it.
- Move python prereqs into the script and use venv.

.github/workflows/presubmit.yml

@@ -108,9 +108,21 @@ jobs:
         uses: actions/setup-python@v5
         with:
           python-version: '3.x'
-      - name: Install python prereqs
-        run: pip install mako setuptools pyyaml
-      - name: Run script
+      - name: Cache Mesa and deps
+        id: mesa-cache
+        uses: actions/cache@v4 # Use a specific version
+        with:
+          path: |
+            $HOME/Library/Caches/Homebrew
+            mesa
+          key: ${{ runner.os }}-mesa-deps-${{ vars.MESA_VERSION }}
+      - name: Get Mesa
+        id: mesa-prereq
+        env:
+          MESA_VERSION: ${{ vars.MESA_VERSION }}
+        run: |
+          bash test/utils/get_mesa.sh
+      - name: Run Test
         run: |
           bash test/renderdiff/test.sh
       - uses: actions/upload-artifact@v4

.gitignore

@@ -18,3 +18,18 @@ test*.json
 results
 /compile_commands.json
 /.cache
+build/.cmake/
+build/CMakeCache.txt
+build/CMakeFiles/
+build/Makefile
+build/SPIRV-Tools*
+build/cmake_install.cmake
+build/compile_commands.json
+build/filament/
+build/include/
+build/libs/
+build/mac/ninja
+build/samples/
+build/shaders/
+build/third_party/
+build/tools/

CMakeLists.txt

@@ -801,6 +801,7 @@ add_subdirectory(${EXTERNAL}/draco/tnt)
 add_subdirectory(${EXTERNAL}/jsmn/tnt)
 add_subdirectory(${EXTERNAL}/stb/tnt)
 add_subdirectory(${EXTERNAL}/getopt)
+add_subdirectory(${EXTERNAL}/perfetto/tnt)
 
 # Note that this has to be placed after mikktspace in order for combine_static_libs to work.
 add_subdirectory(${LIBRARIES}/geometry)

README.md

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

RELEASE_NOTES.md

@@ -7,6 +7,12 @@ 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.59.4
+
+
+## v1.59.3
+
+
 ## v1.59.2
 
 - Fix build/compile errors when upgrading to MacOS 15.4

android/filamat-android/CMakeLists.txt

@@ -26,6 +26,10 @@ add_library(utils STATIC IMPORTED)
 set_target_properties(utils PROPERTIES IMPORTED_LOCATION
         ${FILAMENT_DIR}/lib/${ANDROID_ABI}/libutils.a)
 
+add_library(perfetto STATIC IMPORTED)
+set_target_properties(perfetto PROPERTIES IMPORTED_LOCATION
+        ${FILAMENT_DIR}/lib/${ANDROID_ABI}/libperfetto.a)
+
 add_library(filabridge STATIC IMPORTED)
 set_target_properties(filabridge PROPERTIES IMPORTED_LOCATION
         ${FILAMENT_DIR}/lib/${ANDROID_ABI}/libfilabridge.a)
@@ -40,6 +44,7 @@ set_target_properties(shaders PROPERTIES IMPORTED_LOCATION
 
 set(FILAMAT_INCLUDE_DIRS
         ../../libs/utils/include
+        ../../third_party/perfetto
         )
 
 include_directories(${FILAMENT_DIR}/include)
@@ -55,6 +60,7 @@ target_link_libraries(filamat-jni
         filabridge
         shaders
         utils
+        perfetto
         log
         smol-v
         $<$<STREQUAL:${FILAMENT_SUPPORTS_WEBGPU},ON>:tint>

android/filament-android/CMakeLists.txt

@@ -21,6 +21,10 @@ add_library(utils STATIC IMPORTED)
 set_target_properties(utils PROPERTIES IMPORTED_LOCATION
         ${FILAMENT_DIR}/lib/${ANDROID_ABI}/libutils.a)
 
+add_library(perfetto STATIC IMPORTED)
+set_target_properties(perfetto PROPERTIES IMPORTED_LOCATION
+        ${FILAMENT_DIR}/lib/${ANDROID_ABI}/libperfetto.a)
+
 add_library(ibl-lite STATIC IMPORTED)
 set_target_properties(ibl-lite PROPERTIES IMPORTED_LOCATION
         ${FILAMENT_DIR}/lib/${ANDROID_ABI}/libibl-lite.a)
@@ -123,6 +127,7 @@ target_link_libraries(filament-jni
     PRIVATE android
     PRIVATE jnigraphics
     PRIVATE utils
+    PRIVATE perfetto
 
     # libgeometry is PUBLIC because gltfio uses it.
     PUBLIC geometry
@@ -141,6 +146,7 @@ target_include_directories(filament-jni PRIVATE
         ${FILAMENT_DIR}/include
         ../../filament/backend/include
         ../../third_party/robin-map
+        ../../third_party/perfetto
         ../../libs/utils/include)
 
 # Force a relink when the version script is changed:

android/gltfio-android/CMakeLists.txt

@@ -35,6 +35,10 @@ add_library(utils STATIC IMPORTED)
 set_target_properties(utils PROPERTIES IMPORTED_LOCATION
         ${FILAMENT_DIR}/lib/${ANDROID_ABI}/libutils.a)
 
+add_library(perfetto STATIC IMPORTED)
+set_target_properties(perfetto PROPERTIES IMPORTED_LOCATION
+        ${FILAMENT_DIR}/lib/${ANDROID_ABI}/libperfetto.a)
+
 add_library(uberzlib STATIC IMPORTED)
 set_target_properties(uberzlib PROPERTIES IMPORTED_LOCATION
         ${FILAMENT_DIR}/lib/${ANDROID_ABI}/libuberzlib.a)
@@ -121,6 +125,7 @@ set(GLTFIO_INCLUDE_DIRS
         ../../third_party/meshoptimizer/src
         ../../third_party/robin-map
         ../../third_party/stb
+        ../../third_party/perfetto
         ../../libs/utils/include
         ../../libs/ktxreader/include
 )
@@ -129,7 +134,7 @@ add_library(gltfio-jni SHARED ${GLTFIO_SRCS})
 target_include_directories(gltfio-jni PRIVATE ${GLTFIO_INCLUDE_DIRS})
 set_target_properties(gltfio-jni PROPERTIES LINK_DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/libgltfio-jni.symbols)
 set_target_properties(gltfio-jni PROPERTIES LINK_DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/libgltfio-jni.map)
-target_link_libraries(gltfio-jni filament-jni utils uberzlib log stb ktxreader basis_transcoder zstd uberarchive)
+target_link_libraries(gltfio-jni filament-jni utils perfetto uberzlib log stb ktxreader basis_transcoder zstd uberarchive)
 target_link_libraries(gltfio-jni dracodec meshoptimizer)
 target_compile_definitions(gltfio-jni PUBLIC GLTFIO_DRACO_SUPPORTED=1)
 target_include_directories(gltfio-jni PRIVATE ${DRACO_DIR}/src)

android/gradle.properties

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

filament/backend/CMakeLists.txt

@@ -259,6 +259,7 @@ if (FILAMENT_SUPPORTS_WEBGPU)
             src/webgpu/WebGPUHandles.h
             src/webgpu/WebGPUSwapChain.cpp
             src/webgpu/WebGPUSwapChain.h
+            src/webgpu/WGPUProgram.cpp
     )
     if (WIN32)
         list(APPEND SRCS src/webgpu/platform/WebGPUPlatformWindows.cpp)
@@ -507,8 +508,10 @@ if (APPLE OR LINUX)
         test/Arguments.cpp
         test/ImageExpectations.cpp
         test/Lifetimes.cpp
+        test/PlatformRunner.cpp
         test/Shader.cpp
         test/SharedShaders.cpp
+        test/Skip.cpp
         test/test_FeedbackLoops.cpp
         test/test_Blit.cpp
         test/test_MissingRequiredAttributes.cpp
@@ -532,6 +535,9 @@ if (APPLE OR LINUX)
         filamat
         SPIRV
         spirv-cross-glsl)
+    # Create input/output directories for test result images.
+    file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/images/actual_images)
+    file(COPY test/expected_images DESTINATION ${CMAKE_CURRENT_BINARY_DIR}/images)
 endif()
 
 # TODO: Disabling IOS test due to breakage wrt glslang update

filament/backend/include/backend/BufferObjectStreamDescriptor.h

@@ -55,4 +55,9 @@ public:
 
 } // namespace filament::backend
 
+#if !defined(NDEBUG)
+utils::io::ostream& operator<<(utils::io::ostream& out,
+        const filament::backend::BufferObjectStreamDescriptor& b);
+#endif
+
 #endif // TNT_FILAMENT_BACKEND_BUFFEROBJECTSTREAMDESCRIPTOR_H

filament/backend/include/backend/Platform.h

@@ -149,13 +149,6 @@ public:
          *      - PlatformEGLAndroid
          */
         bool assertNativeWindowIsValid = false;
-
-        /**
-         * The action to take if a Drawable cannot be acquired. If true, the
-         * frame is aborted instead of panic. This is only supported for:
-         *      - PlatformMetal
-         */
-        bool metalDisablePanicOnDrawableFailure = false;
     };
 
     Platform() noexcept;

filament/backend/include/backend/platforms/WebGPUPlatform.h

@@ -38,6 +38,12 @@ public:
 
     [[nodiscard]] wgpu::Instance& getInstance() noexcept { return mInstance; }
 
+    // TODO consider that this functionality is not WebGPU-specific, and thus could be
+    //      placed in a generic place and even reused across backends. Alternatively,
+    //      a 3rd party library could be considered. However, this was a simple and
+    //      quick change and works for now.
+    // gets the size (height and width) of the surface/window
+    [[nodiscard]] wgpu::Extent2D getSurfaceExtent(void* nativeWindow) const;
     // either returns a valid surface or panics
     [[nodiscard]] wgpu::Surface createSurface(void* nativeWindow, uint64_t flags);
     // either returns a valid adapter or panics

filament/backend/src/CommandStream.cpp

@@ -84,7 +84,7 @@ void CommandStream::execute(void* buffer) {
 
     Profiler profiler;
 
-    if (SYSTRACE_TAG) {
+    if constexpr (SYSTRACE_TAG) {
         if (UTILS_UNLIKELY(mUsePerformanceCounter)) {
             // we want to remove all this when tracing is completely disabled
             profiler.resetEvents(Profiler::EV_CPU_CYCLES  | Profiler::EV_BPU_MISSES);
@@ -100,7 +100,7 @@ void CommandStream::execute(void* buffer) {
         }
     });
 
-    if (SYSTRACE_TAG) {
+    if constexpr (SYSTRACE_TAG) {
         if (UTILS_UNLIKELY(mUsePerformanceCounter)) {
             // we want to remove all this when tracing is completely disabled
             profiler.stop();

filament/backend/src/metal/PlatformMetal.mm

@@ -45,9 +45,6 @@ PlatformMetal::~PlatformMetal() noexcept {
 }
 
 Driver* PlatformMetal::createDriver(void* /*sharedContext*/, const Platform::DriverConfig& driverConfig) noexcept {
-    pImpl->mDrawableFailureBehavior = driverConfig.metalDisablePanicOnDrawableFailure
-            ? DrawableFailureBehavior::ABORT_FRAME
-            : DrawableFailureBehavior::PANIC;
     return MetalDriverFactory::create(this, driverConfig);
 }
 

filament/backend/src/opengl/OpenGLProgram.cpp

@@ -85,6 +85,7 @@ OpenGLProgram::~OpenGLProgram() noexcept {
         delete lazyInitializationData;
 
         ShaderCompilerService::terminate(mToken);
+        assert_invariant(!mToken);
     }
 
     delete [] mUniformsRecords;

filament/backend/src/opengl/ShaderCompilerService.h

@@ -24,23 +24,23 @@
 #include "OpenGLBlobCache.h"
 
 #include <backend/CallbackHandler.h>
+#include <backend/DriverEnums.h>
 #include <backend/Program.h>
 
 #include <utils/CString.h>
 #include <utils/FixedCapacityVector.h>
-#include <utils/Invocable.h>
 #include <utils/JobSystem.h>
 
-#include <atomic>
-#include <condition_variable>
-#include <deque>
+#include <array>
 #include <functional>
 #include <memory>
 #include <mutex>
-#include <thread>
+#include <tuple>
 #include <utility>
 #include <vector>
 
+#include <stdint.h>
+
 namespace filament::backend {
 
 class OpenGLDriver;
@@ -57,6 +57,8 @@ class ShaderCompilerService {
 
 public:
     using program_token_t = std::shared_ptr<OpenGLProgramToken>;
+    using shaders_t = std::array<GLuint, Program::SHADER_TYPE_COUNT>;
+    using shaders_source_t = std::array<utils::CString, Program::SHADER_TYPE_COUNT>;
 
     explicit ShaderCompilerService(OpenGLDriver& driver);
 
@@ -82,6 +84,7 @@ public:
     void tick();
 
     // Destroys a valid token and all associated resources. Used to "cancel" a program compilation.
+    // This function is not called if `initialize(token)` is already invoked.
     static void terminate(program_token_t& token);
 
     // stores a user data pointer in the token
@@ -90,6 +93,12 @@ public:
     // retrieves the user data pointer stored in the token
     static void* getUserData(const program_token_t& token) noexcept;
 
+    // Issue one callback handle.
+    CallbackManager::Handle issueCallbackHandle() const noexcept;
+
+    // Return a callback handle to the callback manager.
+    void submitCallbackHandle(CallbackManager::Handle handle) noexcept;
+
     // call the callback when all active programs are ready
     void notifyWhenAllProgramsAreReady(
             CallbackHandler* handler, CallbackHandler::Callback callback, void* user);
@@ -97,7 +106,7 @@ public:
 private:
     struct Job {
         template<typename FUNC>
-        Job(FUNC&& fn) : fn(std::forward<FUNC>(fn)) {}
+        Job(FUNC&& fn) : fn(std::forward<FUNC>(fn)) {} // NOLINT(*-explicit-constructor)
         Job(std::function<bool(Job const& job)> fn,
                 CallbackHandler* handler, void* user, CallbackHandler::Callback callback)
                 : fn(std::move(fn)), handler(handler), user(user), callback(callback) {
@@ -126,39 +135,49 @@ private:
     using ContainerType = std::tuple<CompilerPriorityQueue, program_token_t, Job>;
     std::vector<ContainerType> mRunAtNextTickOps;
 
-    GLuint initialize(ShaderCompilerService::program_token_t& token) noexcept;
+    GLuint initialize(program_token_t& token);
+    void ensureTokenIsReady(program_token_t const& token);
 
-    static void getProgramFromCompilerPool(program_token_t& token) noexcept;
-
-    static void compileShaders(
-            OpenGLContext& context,
-            Program::ShaderSource shadersSource,
-            utils::FixedCapacityVector<Program::SpecializationConstant> const& specializationConstants,
-            bool multiview,
-            std::array<GLuint, Program::SHADER_TYPE_COUNT>& outShaders,
-            std::array<utils::CString, Program::SHADER_TYPE_COUNT>& outShaderSourceCode) noexcept;
-
-    static void process_GOOGLE_cpp_style_line_directive(OpenGLContext& context,
-            char* source, size_t len) noexcept;
-
-    static void process_OVR_multiview2(OpenGLContext& context, int32_t eyeCount,
-            char* source, size_t len) noexcept;
-
-    static std::string_view process_ARB_shading_language_packing(OpenGLContext& context) noexcept;
-
-    static std::array<std::string_view, 3> splitShaderSource(std::string_view source) noexcept;
-
-    static GLuint linkProgram(OpenGLContext& context,
-            std::array<GLuint, Program::SHADER_TYPE_COUNT> shaders,
-            utils::FixedCapacityVector<std::pair<utils::CString, uint8_t>> const& attributes) noexcept;
-
-    static bool checkProgramStatus(program_token_t const& token) noexcept;
-
-    void runAtNextTick(CompilerPriorityQueue priority,
-            const program_token_t& token, Job job) noexcept;
+    void runAtNextTick(CompilerPriorityQueue priority, program_token_t const& token,
+            Job job) noexcept;
     void executeTickOps() noexcept;
-    bool cancelTickOp(program_token_t token) noexcept;
-    // order of insertion is important
+    bool cancelTickOp(program_token_t const& token) noexcept;
+
+    // Compile shaders with the given `shaderSource`. `gl.shaders` is always populated with valid
+    // shader IDs after this method. But this doesn't necessarily mean the shaders are successfully
+    // compiled. Errors can be checked by calling `checkCompileStatus` later.
+    static void compileShaders(OpenGLContext& context, Program::ShaderSource shadersSource,
+            utils::FixedCapacityVector<Program::SpecializationConstant> const&
+                    specializationConstants,
+            bool multiview, program_token_t const& token) noexcept;
+
+    // Check if the shader compilation is completed. You may want to call this when the extension
+    // `KHR_parallel_shader_compile` is enabled.
+    static bool isCompileCompleted(program_token_t const& token) noexcept;
+
+    // Check compilation status of the shaders and log errors on failure.
+    static void checkCompileStatus(program_token_t const& token) noexcept;
+
+    // Create a program by linking the compiled shaders. `gl.program` is always populated with a
+    // valid program ID after this method. But this doesn't necessarily mean the program is
+    // successfully linked. Errors can be checked by calling `checkLinkStatusAndCleanupShaders`
+    // later.
+    static void linkProgram(OpenGLContext const& context, program_token_t const& token) noexcept;
+
+    // Check if the program link is completed. You may want to call this when the extension
+    // `KHR_parallel_shader_compile` is enabled.
+    static bool isLinkCompleted(program_token_t const& token) noexcept;
+
+    // Check link status of the program and log errors on failure. Return the result of the link.
+    // Also cleanup shaders regardless of the result.
+    static bool checkLinkStatusAndCleanupShaders(program_token_t const& token) noexcept;
+
+    // Try caching the program if we haven't done it yet. Cache it only when the program is valid.
+    static void tryCachingProgram(OpenGLBlobCache& cache, OpenGLPlatform& platform,
+            program_token_t const& token) noexcept;
+
+    // Cleanup GL resources.
+    static void cleanupProgramAndShaders(program_token_t const& token) noexcept;
 };
 
 } // namespace filament::backend

filament/backend/src/ostream.cpp

@@ -15,6 +15,7 @@
  */
 
 #include <backend/BufferDescriptor.h>
+#include <backend/BufferObjectStreamDescriptor.h>
 #include <backend/DescriptorSetOffsetArray.h>
 #include <backend/DriverEnums.h>
 #include <backend/PipelineState.h>
@@ -437,6 +438,10 @@ io::ostream& operator<<(io::ostream& out, BufferDescriptor const& b) {
     << ", user=" << b.getUser() << " }";
 }
 
+io::ostream& operator<<(io::ostream& out, const BufferObjectStreamDescriptor& b) {
+    return out << "BufferObjectStreamDescriptor{ streams(" << b.mStreams.size() << ")=... }";
+}
+
 io::ostream& operator<<(io::ostream& out, PixelBufferDescriptor const& b) {
     BufferDescriptor const& base = static_cast<BufferDescriptor const&>(b);
     return out << "PixelBufferDescriptor{ " << base

filament/backend/src/vulkan/VulkanConstants.h

@@ -152,12 +152,12 @@ static_assert(FVK_ENABLED(FVK_DEBUG_VALIDATION));
 #elif FVK_ENABLED(FVK_DEBUG_SYSTRACE)
 
     #include <utils/Systrace.h>
-    
+
     #define FVK_SYSTRACE_CONTEXT()      SYSTRACE_CONTEXT()
     #define FVK_SYSTRACE_START(marker)  SYSTRACE_NAME_BEGIN(marker)
     #define FVK_SYSTRACE_END()          SYSTRACE_NAME_END()
-    #define FVK_SYSTRACE_SCOPE()        SYSTRACE_NAME(__func__)
-    #define FVK_PROFILE_MARKER(marker)  FVK_SYSTRACE_SCOPE()
+    #define FVK_SYSTRACE_SCOPE()        SYSTRACE_CALL()
+    #define FVK_PROFILE_MARKER(marker)  SYSTRACE_CALL()
 
 #else
     #define FVK_SYSTRACE_CONTEXT()

filament/backend/src/vulkan/VulkanDriver.cpp

@@ -327,7 +327,7 @@ void VulkanDriver::terminate() {
 
     mStagePool.terminate();
     mPipelineCache.terminate();
-    mFramebufferCache.reset();
+    mFramebufferCache.terminate();
     mSamplerCache.terminate();
     mDescriptorSetLayoutCache.terminate();
     mDescriptorSetCache.terminate();
@@ -1523,7 +1523,7 @@ void VulkanDriver::makeCurrent(Handle<HwSwapChain> drawSch, Handle<HwSwapChain>
     swapChain->acquire(resized);
 
     if (resized) {
-        mFramebufferCache.reset();
+        mFramebufferCache.resetFramebuffers();
     }
 
     if (UTILS_LIKELY(mDefaultRenderTarget)) {

filament/backend/src/vulkan/VulkanFboCache.cpp

@@ -340,15 +340,21 @@ VkRenderPass VulkanFboCache::getRenderPass(RenderPassKey const& config) noexcept
     return renderPass;
 }
 
-void VulkanFboCache::reset() noexcept {
-    for (auto pair : mFramebufferCache) {
+void VulkanFboCache::resetFramebuffers() noexcept {
+    for (const auto& pair: mFramebufferCache) {
         mRenderPassRefCount[pair.first.renderPass]--;
         vkDestroyFramebuffer(mDevice, pair.second.handle, VKALLOC);
     }
     mFramebufferCache.clear();
-    for (auto pair : mRenderPassCache) {
+}
+
+void VulkanFboCache::terminate() noexcept {
+    resetFramebuffers();
+
+    for (const auto& pair: mRenderPassCache) {
         vkDestroyRenderPass(mDevice, pair.second.handle, VKALLOC);
     }
+    mRenderPassRefCount.clear();
     mRenderPassCache.clear();
 }
 

filament/backend/src/vulkan/VulkanFboCache.h

@@ -106,8 +106,11 @@ public:
     // Evicts old unused Vulkan objects. Call this once per frame.
     void gc() noexcept;
 
+    // Frees all Framebuffer objects. Call this every time a the swapchain is resized
+    void resetFramebuffers() noexcept;
+
     // Frees all Vulkan objects. Call this during shutdown before the device is destroyed.
-    void reset() noexcept;
+    void terminate() noexcept;
 
 private:
     VkDevice mDevice;

filament/backend/src/vulkan/VulkanPipelineCache.cpp

@@ -35,7 +35,12 @@ using namespace bluevk;
 namespace filament::backend {
 
 VulkanPipelineCache::VulkanPipelineCache(VkDevice device)
-        : mDevice(device) {}
+    : mDevice(device) {
+    VkPipelineCacheCreateInfo createInfo = {
+        .sType = VK_STRUCTURE_TYPE_PIPELINE_CACHE_CREATE_INFO,
+    };
+    bluevk::vkCreatePipelineCache(mDevice, &createInfo, VKALLOC, &mPipelineCache);
+}
 
 void VulkanPipelineCache::bindLayout(VkPipelineLayout layout) noexcept {
     mPipelineRequirements.layout = layout;
@@ -215,7 +220,7 @@ VulkanPipelineCache::PipelineCacheEntry* VulkanPipelineCache::createPipeline() n
     PipelineCacheEntry cacheEntry = {
         .lastUsed = mCurrentTime,
     };
-    VkResult error = vkCreateGraphicsPipelines(mDevice, VK_NULL_HANDLE, 1, &pipelineCreateInfo,
+    VkResult error = vkCreateGraphicsPipelines(mDevice, mPipelineCache, 1, &pipelineCreateInfo,
             VKALLOC, &cacheEntry.handle);
     assert_invariant(error == VK_SUCCESS);
     if (error != VK_SUCCESS) {
@@ -271,6 +276,8 @@ void VulkanPipelineCache::terminate() noexcept {
     }
     mPipelines.clear();
     mBoundPipeline = {};
+
+    vkDestroyPipelineCache(mDevice, mPipelineCache, VKALLOC);
 }
 
 void VulkanPipelineCache::gc() noexcept {

filament/backend/src/vulkan/VulkanPipelineCache.h

@@ -198,6 +198,10 @@ private:
     // Immutable state.
     VkDevice mDevice = VK_NULL_HANDLE;
 
+    // Vuklan Driver pipeline cache handle. In the cases a pipeline has been  evicted by the `gc`,
+    // recreating the same pipeline is cheaper, helping with frame stalling.
+    VkPipelineCache mPipelineCache = VK_NULL_HANDLE;
+
     // Current requirements for the pipeline layout, pipeline, and descriptor sets.
     PipelineKey mPipelineRequirements = {};
 

filament/backend/src/vulkan/platform/VulkanPlatformApple.mm

@@ -24,28 +24,12 @@
 #include <bluevk/BlueVK.h>
 
 // Platform specific includes and defines
-#if defined(__APPLE__)
-    #include <Cocoa/Cocoa.h>
-    #import <Metal/Metal.h>
-    #import <QuartzCore/CAMetalLayer.h>
+#include <Cocoa/Cocoa.h>
+#import <Metal/Metal.h>
+#import <QuartzCore/CAMetalLayer.h>
 
-    #ifndef VK_MVK_macos_surface
-         #error VK_MVK_macos_surface is not defined
-    #endif
-#elif defined(FILAMENT_IOS)
-    // Metal is not available when building for the iOS simulator on Desktop.
-    #define METAL_AVAILABLE __has_include(<QuartzCore/CAMetalLayer.h>)
-    #if METAL_AVAILABLE
-        #import <Metal/Metal.h>
-        #import <QuartzCore/CAMetalLayer.h>
-    #endif
-
-    #ifndef VK_MVK_ios_surface
-        #error VK_MVK_ios_surface is not defined
-    #endif
-    #define METALVIEW_TAG 255
-#else
-    #error Not a supported Apple + Vulkan platform
+#ifndef VK_MVK_macos_surface
+    #error VK_MVK_macos_surface is not defined
 #endif
 
 using namespace bluevk;
@@ -54,11 +38,7 @@ namespace filament::backend {
 
 VulkanPlatform::ExtensionSet VulkanPlatform::getSwapchainInstanceExtensionsImpl() {
     ExtensionSet const ret = {
-    #if defined(__APPLE__)
         VK_MVK_MACOS_SURFACE_EXTENSION_NAME,  // TODO: replace with VK_EXT_metal_surface
-    #elif defined(FILAMENT_IOS) && defined(METAL_AVAILABLE)
-        VK_MVK_IOS_SURFACE_EXTENSION_NAME,
-    #endif
     };
     return ret;
 }
@@ -90,36 +70,20 @@ VkImageView VulkanPlatform::createExternalImageViewImpl(VkDevice device,
 VulkanPlatform::SurfaceBundle VulkanPlatform::createVkSurfaceKHRImpl(void* nativeWindow,
         VkInstance instance, uint64_t flags) noexcept {
     VkSurfaceKHR surface;
-    #if defined(__APPLE__)
-        NSView* nsview = (__bridge NSView*) nativeWindow;
-        FILAMENT_CHECK_POSTCONDITION(nsview) << "Unable to obtain Metal-backed NSView.";
+    NSView* nsview = (__bridge NSView*) nativeWindow;
+    FILAMENT_CHECK_POSTCONDITION(nsview) << "Unable to obtain Metal-backed NSView.";
 
-        // Create the VkSurface.
-        FILAMENT_CHECK_POSTCONDITION(vkCreateMacOSSurfaceMVK)
-                << "Unable to load vkCreateMacOSSurfaceMVK.";
-        VkMacOSSurfaceCreateInfoMVK createInfo = {};
-        createInfo.sType = VK_STRUCTURE_TYPE_MACOS_SURFACE_CREATE_INFO_MVK;
-        createInfo.pView = (__bridge void*) nsview;
-        VkResult result = vkCreateMacOSSurfaceMVK((VkInstance) instance, &createInfo, VKALLOC,
-                (VkSurfaceKHR*) &surface);
-        FILAMENT_CHECK_POSTCONDITION(result == VK_SUCCESS)
-                << "vkCreateMacOSSurfaceMVK. error=" << static_cast<int32_t>(result);
-#elif defined(FILAMENT_IOS) && defined(METAL_AVAILABLE)
-    CAMetalLayer* metalLayer = (CAMetalLayer*) nativeWindow;
     // Create the VkSurface.
-    FILAMENT_CHECK_POSTCONDITION(vkCreateIOSSurfaceMVK)
-            << "Unable to load vkCreateIOSSurfaceMVK function.";
-    VkIOSSurfaceCreateInfoMVK createInfo = {};
-    createInfo.sType = VK_STRUCTURE_TYPE_IOS_SURFACE_CREATE_INFO_MVK;
-    createInfo.pNext = NULL;
-    createInfo.flags = 0;
-    createInfo.pView = metalLayer;
-    VkResult result = vkCreateIOSSurfaceMVK((VkInstance) instance, &createInfo, VKALLOC,
+    FILAMENT_CHECK_POSTCONDITION(vkCreateMacOSSurfaceMVK)
+            << "Unable to load vkCreateMacOSSurfaceMVK.";
+    VkMacOSSurfaceCreateInfoMVK createInfo = {};
+    createInfo.sType = VK_STRUCTURE_TYPE_MACOS_SURFACE_CREATE_INFO_MVK;
+    createInfo.pView = (__bridge void*) nsview;
+    VkResult result = vkCreateMacOSSurfaceMVK((VkInstance) instance, &createInfo, VKALLOC,
             (VkSurfaceKHR*) &surface);
     FILAMENT_CHECK_POSTCONDITION(result == VK_SUCCESS)
-            << "vkCreateIOSSurfaceMVK failed. error=" << static_cast<int32_t>(result);
-#endif
-        return std::make_tuple(surface, VkExtent2D{});
+            << "vkCreateMacOSSurfaceMVK. error=" << static_cast<int32_t>(result);
+    return std::make_tuple(surface, VkExtent2D{});
 }
 
 } // namespace filament::backend

filament/backend/src/webgpu/WGPUProgram.cpp

@@ -0,0 +1,150 @@
+/*
+ * Copyright (C) 2025 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#include "WebGPUHandles.h"
+
+#include "WebGPUConstants.h"
+
+#include "DriverBase.h"
+#include <backend/DriverEnums.h>
+#include <backend/Program.h>
+
+#include <utils/Panic.h>
+#include <utils/ostream.h>
+
+#include <webgpu/webgpu_cpp.h>
+
+#include <sstream>
+#include <string_view>
+#include <vector>
+
+namespace filament::backend {
+
+namespace {
+
+[[nodiscard]] constexpr std::string_view toString(ShaderStage stage) {
+    switch (stage) {
+        case ShaderStage::VERTEX:
+            return "vertex";
+        case ShaderStage::FRAGMENT:
+            return "fragment";
+        case ShaderStage::COMPUTE:
+            return "compute";
+    }
+}
+
+[[nodiscard]] wgpu::ShaderModule createShaderModule(wgpu::Device& device, const char* programName,
+        std::array<utils::FixedCapacityVector<uint8_t>, Program::SHADER_TYPE_COUNT> const&
+                shaderSource,
+        ShaderStage stage) {
+    utils::FixedCapacityVector<uint8_t> const& sourceBytes =
+            shaderSource[static_cast<size_t>(stage)];
+    if (sourceBytes.empty()) {
+        return nullptr;// nothing to compile, the shader was not provided
+    }
+    wgpu::ShaderModuleWGSLDescriptor wgslDescriptor{};
+    wgslDescriptor.code = wgpu::StringView(reinterpret_cast<const char*>(sourceBytes.data()));
+    std::stringstream labelStream;
+    labelStream << programName << " " << toString(stage) << " shader";
+    auto label = labelStream.str();
+    wgpu::ShaderModuleDescriptor descriptor{
+        .nextInChain = &wgslDescriptor,
+        .label = label.data()
+    };
+    wgpu::ShaderModule module = device.CreateShaderModule(&descriptor);
+    FILAMENT_CHECK_POSTCONDITION(module != nullptr) << "Failed to create " << descriptor.label;
+    module.GetCompilationInfo(wgpu::CallbackMode::AllowSpontaneous,
+            [&descriptor](auto const& status, wgpu::CompilationInfo const* info) {
+                switch (status) {
+                    case wgpu::CompilationInfoRequestStatus::CallbackCancelled:
+                        FWGPU_LOGW << "Shader compilation info callback cancelled for "
+                                   << descriptor.label << "?" << utils::io::endl;
+                        return;
+                    case wgpu::CompilationInfoRequestStatus::Success:
+                        break;
+                }
+                if (info != nullptr) {
+                    std::stringstream errorStream;
+                    int errorCount = 0;
+                    for (size_t msgIndex = 0; msgIndex < info->messageCount; msgIndex++) {
+                        wgpu::CompilationMessage const& message = info->messages[msgIndex];
+                        switch (message.type) {
+                            case wgpu::CompilationMessageType::Info:
+                                FWGPU_LOGI << descriptor.label << ": " << message.message
+                                           << " line#:" << message.lineNum
+                                           << " linePos:" << message.linePos
+                                           << " offset:" << message.offset
+                                           << " length:" << message.length << utils::io::endl;
+                                break;
+                            case wgpu::CompilationMessageType::Warning:
+                                FWGPU_LOGW << "Warning compiling " << descriptor.label << ": "
+                                           << message.message << " line#:" << message.lineNum
+                                           << " linePos:" << message.linePos
+                                           << " offset:" << message.offset
+                                           << " length:" << message.length << utils::io::endl;
+                                break;
+                            case wgpu::CompilationMessageType::Error:
+                                errorCount++;
+                                errorStream << "Error " << errorCount << " : "
+                                            << std::string_view(message.message)
+                                            << " line#:" << message.lineNum
+                                            << " linePos:" << message.linePos
+                                            << " offset:" << message.offset
+                                            << " length:" << message.length << "\n";
+                                break;
+                        }
+                    }
+                    FILAMENT_CHECK_POSTCONDITION(errorCount < 1)
+                            << errorCount << " error(s) compiling " << descriptor.label << ":\n"
+                            << errorStream.str();
+                }
+                FWGPU_LOGD << descriptor.label << " compiled successfully" << utils::io::endl;
+            });
+    return module;
+}
+
+std::vector<wgpu::ConstantEntry> convertConstants(
+        utils::FixedCapacityVector<filament::backend::Program::SpecializationConstant> const&
+                constantsInfo) {
+    std::vector<wgpu::ConstantEntry> constants(constantsInfo.size());
+    for (size_t i = 0; i < constantsInfo.size(); i++) {
+        filament::backend::Program::SpecializationConstant const& specConstant = constantsInfo[i];
+        wgpu::ConstantEntry& constantEntry = constants[i];
+        constantEntry.key = wgpu::StringView(std::to_string(specConstant.id));
+        if (auto* v = std::get_if<int32_t>(&specConstant.value)) {
+            constantEntry.value = static_cast<double>(*v);
+        } else if (auto* f = std::get_if<float>(&specConstant.value)) {
+            constantEntry.value = static_cast<double>(*f);
+        } else if (auto* b = std::get_if<bool>(&specConstant.value)) {
+            constantEntry.value = *b ? 0.0 : 1.0;
+        }
+    }
+    return constants;
+}
+
+}// namespace
+
+WGPUProgram::WGPUProgram(wgpu::Device& device, Program& program)
+    : HwProgram(program.getName()),
+      vertexShaderModule(createShaderModule(device, name.c_str_safe(), program.getShadersSource(),
+              ShaderStage::VERTEX)),
+      fragmentShaderModule(createShaderModule(device, name.c_str_safe(), program.getShadersSource(),
+              ShaderStage::FRAGMENT)),
+      computeShaderModule(createShaderModule(device, name.c_str_safe(), program.getShadersSource(),
+              ShaderStage::COMPUTE)),
+      constants(convertConstants(program.getSpecializationConstants())) {}
+
+}// namespace filament::backend

filament/backend/src/webgpu/WebGPUDriver.cpp

@@ -16,6 +16,7 @@
 
 #include "webgpu/WebGPUDriver.h"
 
+#include "WebGPUSwapChain.h"
 #include "webgpu/WebGPUConstants.h"
 #include <backend/platforms/WebGPUPlatform.h>
 
@@ -227,6 +228,14 @@ WebGPUDriver::WebGPUDriver(WebGPUPlatform& platform, const Platform::DriverConfi
               driverConfig.disableHeapHandleTags) {
 #if FWGPU_ENABLED(FWGPU_PRINT_SYSTEM)
     printInstanceDetails(mPlatform.getInstance());
+#endif
+    mAdapter = mPlatform.requestAdapter(nullptr);
+#if FWGPU_ENABLED(FWGPU_PRINT_SYSTEM)
+    printAdapterDetails(mAdapter);
+#endif
+    mDevice = mPlatform.requestDevice(mAdapter);
+#if FWGPU_ENABLED(FWGPU_PRINT_SYSTEM)
+    printDeviceDetails(mDevice);
 #endif
 }
 
@@ -286,15 +295,27 @@ void WebGPUDriver::finish(int) {
 }
 
 void WebGPUDriver::destroyRenderPrimitive(Handle<HwRenderPrimitive> rph) {
+   if (rph) {
+        destructHandle<WGPURenderPrimitive>(rph);
+    }
 }
 
 void WebGPUDriver::destroyVertexBufferInfo(Handle<HwVertexBufferInfo> vbih) {
+   if (vbih) {
+        destructHandle<WGPUVertexBufferInfo>(vbih);
+    }
 }
 
 void WebGPUDriver::destroyVertexBuffer(Handle<HwVertexBuffer> vbh) {
+    if (vbh) {
+        destructHandle<WGPUVertexBuffer>(vbh);
+    }
 }
 
 void WebGPUDriver::destroyIndexBuffer(Handle<HwIndexBuffer> ibh) {
+    if (ibh) {
+        destructHandle<WGPUIndexBuffer>(ibh);
+    }
 }
 
 void WebGPUDriver::destroyBufferObject(Handle<HwBufferObject> boh) {
@@ -304,19 +325,19 @@ void WebGPUDriver::destroyTexture(Handle<HwTexture> th) {
 }
 
 void WebGPUDriver::destroyProgram(Handle<HwProgram> ph) {
+    if (ph) {
+        destructHandle<WGPUProgram>(ph);
+    }
 }
 
 void WebGPUDriver::destroyRenderTarget(Handle<HwRenderTarget> rth) {
 }
 
 void WebGPUDriver::destroySwapChain(Handle<HwSwapChain> sch) {
+    if (sch) {
+        destructHandle<WebGPUSwapChain>(sch);
+    }
     mSwapChain = nullptr;
-    // TODO:  use webgpu handle allocator from
-    //        https://github.com/google/filament/pull/8566
-//    if (sch) {
-//        HwSwapChain* hwSwapChain = handleCast<HwSwapChain*>(sch);
-//        destruct(sch, hwSwapChain);
-//    }
 }
 
 void WebGPUDriver::destroyStream(Handle<HwStream> sh) {
@@ -326,16 +347,16 @@ void WebGPUDriver::destroyTimerQuery(Handle<HwTimerQuery> tqh) {
 }
 
 void WebGPUDriver::destroyDescriptorSetLayout(Handle<HwDescriptorSetLayout> tqh) {
+    if (tqh) {
+        destructHandle<WebGPUDescriptorSetLayout>(tqh);
+    }
 }
 
 void WebGPUDriver::destroyDescriptorSet(Handle<HwDescriptorSet> tqh) {
 }
 
 Handle<HwSwapChain> WebGPUDriver::createSwapChainS() noexcept {
-    // TODO:  use webgpu handle allocator from.
-    //        https://github.com/google/filament/pull/8566
-    // return allocAndConstructHandle<HwSwapChain>();
-    return Handle<HwSwapChain>((Handle<HwSwapChain>::HandleId) mNextFakeHandle++);
+    return allocHandle<WebGPUSwapChain>();
 }
 
 Handle<HwSwapChain> WebGPUDriver::createSwapChainHeadlessS() noexcept {
@@ -351,7 +372,7 @@ Handle<HwTexture> WebGPUDriver::importTextureS() noexcept {
 }
 
 Handle<HwProgram> WebGPUDriver::createProgramS() noexcept {
-    return Handle<HwProgram>((Handle<HwProgram>::HandleId) mNextFakeHandle++);
+    return allocHandle<WGPUProgram>();
 }
 
 Handle<HwFence> WebGPUDriver::createFenceS() noexcept {
@@ -387,7 +408,7 @@ Handle<HwDescriptorSet> WebGPUDriver::createDescriptorSetS() noexcept {
 }
 
 Handle<HwRenderPrimitive> WebGPUDriver::createRenderPrimitiveS() noexcept {
-    return Handle<HwRenderPrimitive>((Handle<HwRenderPrimitive>::HandleId) mNextFakeHandle++);
+    return allocHandle<WGPURenderPrimitive>();
 }
 
 Handle<HwVertexBufferInfo> WebGPUDriver::createVertexBufferInfoS() noexcept {
@@ -403,8 +424,7 @@ Handle<HwRenderTarget> WebGPUDriver::createDefaultRenderTargetS() noexcept {
 }
 
 Handle<HwDescriptorSetLayout> WebGPUDriver::createDescriptorSetLayoutS() noexcept {
-    return Handle<HwDescriptorSetLayout>(
-            (Handle<HwDescriptorSetLayout>::HandleId) mNextFakeHandle++);
+    return allocHandle<WebGPUDescriptorSetLayout>();
 }
 
 Handle<HwTexture> WebGPUDriver::createTextureExternalImageS() noexcept {
@@ -420,21 +440,15 @@ Handle<HwTexture> WebGPUDriver::createTextureExternalImagePlaneS() noexcept {
 }
 
 void WebGPUDriver::createSwapChainR(Handle<HwSwapChain> sch, void* nativeWindow, uint64_t flags) {
-    // TODO:  use webgpu handle allocator from.
-    //        https://github.com/google/filament/pull/8566
-    // HwSwapChain* hwSwapChain = handleCast<HwSwapChain*>(sch);
+    mNativeWindow = nativeWindow;
     assert_invariant(!mSwapChain);
     wgpu::Surface surface = mPlatform.createSurface(nativeWindow, flags);
-    mAdapter = mPlatform.requestAdapter(surface);
-#if FWGPU_ENABLED(FWGPU_PRINT_SYSTEM)
-    printAdapterDetails(mAdapter);
-#endif
-    mDevice = mPlatform.requestDevice(mAdapter);
-#if FWGPU_ENABLED(FWGPU_PRINT_SYSTEM)
-    printDeviceDetails(mDevice);
-#endif
+
     mQueue = mDevice.GetQueue();
-    mSwapChain = std::make_unique<WebGPUSwapChain>(std::move(surface), mAdapter, mDevice, flags);
+    wgpu::Extent2D surfaceSize = mPlatform.getSurfaceExtent(mNativeWindow);
+    mSwapChain = constructHandle<WebGPUSwapChain>(sch, std::move(surface), surfaceSize, mAdapter,
+            mDevice, flags);
+    assert_invariant(mSwapChain);
     FWGPU_LOGW << "WebGPU support is still essentially a no-op at this point in development (only "
                   "background components have been instantiated/selected, such as surface/screen, "
                   "graphics device/GPU, etc.), thus nothing is being drawn to the screen."
@@ -447,9 +461,6 @@ void WebGPUDriver::createSwapChainR(Handle<HwSwapChain> sch, void* nativeWindow,
                   "rebuilding Filament with that flag, e.g. ./build.sh -x "
                << FWGPU_PRINT_SYSTEM << " ..." << utils::io::endl;
 #endif
-    // TODO:  use webgpu handle allocator from.
-    //        https://github.com/google/filament/pull/8566
-    // hwSwapChain->swapChain = mSwapChain.get();
 }
 
 void WebGPUDriver::createSwapChainHeadlessR(Handle<HwSwapChain> sch, uint32_t width,
@@ -497,7 +508,9 @@ void WebGPUDriver::importTextureR(Handle<HwTexture> th, intptr_t id, SamplerType
 void WebGPUDriver::createRenderPrimitiveR(Handle<HwRenderPrimitive> rph, Handle<HwVertexBuffer> vbh,
         Handle<HwIndexBuffer> ibh, PrimitiveType pt) {}
 
-void WebGPUDriver::createProgramR(Handle<HwProgram> ph, Program&& program) {}
+void WebGPUDriver::createProgramR(Handle<HwProgram> ph, Program&& program) {
+    constructHandle<WGPUProgram>(ph, mDevice, program);
+}
 
 void WebGPUDriver::createDefaultRenderTargetR(Handle<HwRenderTarget> rth, int) {
     assert_invariant(!mDefaultRenderTarget);
@@ -514,7 +527,9 @@ void WebGPUDriver::createFenceR(Handle<HwFence> fh, int) {}
 void WebGPUDriver::createTimerQueryR(Handle<HwTimerQuery> tqh, int) {}
 
 void WebGPUDriver::createDescriptorSetLayoutR(Handle<HwDescriptorSetLayout> dslh,
-        backend::DescriptorSetLayout&& info) {}
+        backend::DescriptorSetLayout&& info) {
+    constructHandle<WebGPUDescriptorSetLayout>(dslh, std::move(info), mDevice);
+}
 
 void WebGPUDriver::createDescriptorSetR(Handle<HwDescriptorSet> dsh,
         Handle<HwDescriptorSetLayout> dslh) {}
@@ -705,10 +720,6 @@ void WebGPUDriver::beginRenderPass(Handle<HwRenderTarget> rth, const RenderPassP
     };
     mCommandEncoder = mDevice.CreateCommandEncoder(&commandEncoderDescriptor);
     assert_invariant(mCommandEncoder);
-
-    mTextureView = mSwapChain->getNextSurfaceTextureView(params.viewport.width, params.viewport.height);
-    assert_invariant(mTextureView);
-
     // TODO: Remove this code once WebGPU pipeline is implemented
     static float red = 1.0f;
     if (red - 0.01 > 0) {
@@ -716,7 +727,7 @@ void WebGPUDriver::beginRenderPass(Handle<HwRenderTarget> rth, const RenderPassP
     } else {
         red = 1.0f;
     }
-
+    assert_invariant(mTextureView);
     wgpu::RenderPassColorAttachment renderPassColorAttachment = {
         .view = mTextureView,
         // TODO: remove this code once WebGPU Pipeline is implemented with render targets, pipeline and buffers.
@@ -752,6 +763,14 @@ void WebGPUDriver::nextSubpass(int) {
 }
 
 void WebGPUDriver::makeCurrent(Handle<HwSwapChain> drawSch, Handle<HwSwapChain> readSch) {
+    ASSERT_PRECONDITION_NON_FATAL(drawSch == readSch,
+            "WebGPU driver does not support distinct draw/read swap chains.");
+    auto* swapChain = handleCast<WebGPUSwapChain>(drawSch);
+    mSwapChain = swapChain;
+    assert_invariant(mSwapChain);
+    wgpu::Extent2D surfaceSize = mPlatform.getSurfaceExtent(mNativeWindow);
+    mTextureView = mSwapChain->getCurrentSurfaceTextureView(surfaceSize);
+    assert_invariant(mTextureView);
 }
 
 void WebGPUDriver::commit(Handle<HwSwapChain> sch) {
@@ -759,6 +778,7 @@ void WebGPUDriver::commit(Handle<HwSwapChain> sch) {
     mQueue.Submit(1, &mCommandBuffer);
     mCommandBuffer = nullptr;
     mTextureView = nullptr;
+    assert_invariant(mSwapChain);
     mSwapChain->present();
 }
 
@@ -787,7 +807,7 @@ void WebGPUDriver::readPixels(Handle<HwRenderTarget> src,
     scheduleDestroy(std::move(p));
 }
 
-void WebGPUDriver::readBufferSubData(backend::BufferObjectHandle boh,
+void WebGPUDriver::readBufferSubData(Handle<HwBufferObject> boh,
         uint32_t offset, uint32_t size, backend::BufferDescriptor&& p) {
     scheduleDestroy(std::move(p));
 }
@@ -839,22 +859,22 @@ void WebGPUDriver::resetState(int) {
 }
 
 void WebGPUDriver::updateDescriptorSetBuffer(
-        backend::DescriptorSetHandle dsh,
+        Handle<HwDescriptorSet> dsh,
         backend::descriptor_binding_t binding,
-        backend::BufferObjectHandle boh,
+        Handle<HwBufferObject> boh,
         uint32_t offset,
         uint32_t size) {
 }
 
 void WebGPUDriver::updateDescriptorSetTexture(
-        backend::DescriptorSetHandle dsh,
+        Handle<HwDescriptorSet> dsh,
         backend::descriptor_binding_t binding,
-        backend::TextureHandle th,
+        Handle<HwTexture> th,
         SamplerParams params) {
 }
 
 void WebGPUDriver::bindDescriptorSet(
-        backend::DescriptorSetHandle dsh,
+        Handle<HwDescriptorSet> dsh,
         backend::descriptor_set_t set,
         backend::DescriptorSetOffsetArray&& offsets) {
 }

filament/backend/src/webgpu/WebGPUDriver.h

@@ -18,7 +18,6 @@
 #define TNT_FILAMENT_BACKEND_WEBGPUDRIVER_H
 
 #include "WebGPUHandles.h"
-#include "webgpu/WebGPUSwapChain.h"
 #include <backend/platforms/WebGPUPlatform.h>
 
 #include "DriverBase.h"
@@ -40,6 +39,8 @@
 
 namespace filament::backend {
 
+class WebGPUSwapChain;
+
 /**
  * WebGPU backend (driver) implementation
  */
@@ -61,8 +62,8 @@ private:
     wgpu::Adapter mAdapter = nullptr;
     wgpu::Device mDevice = nullptr;
     wgpu::Queue mQueue = nullptr;
-    // TODO consider moving to handle allocator when ready
-    std::unique_ptr<WebGPUSwapChain> mSwapChain = nullptr;
+    void* mNativeWindow = nullptr;
+    WebGPUSwapChain* mSwapChain = nullptr;
     uint64_t mNextFakeHandle = 1;
     wgpu::CommandEncoder mCommandEncoder = nullptr;
     wgpu::TextureView mTextureView = nullptr;
@@ -102,11 +103,17 @@ private:
     D* constructHandle(Handle<B>& handle, ARGS&& ... args) noexcept {
         return mHandleAllocator.construct<D>(handle, std::forward<ARGS>(args)...);
     }
+
     template<typename D, typename B>
     D* handleCast(Handle<B> handle) noexcept {
         return mHandleAllocator.handle_cast<D*>(handle);
     }
 
+    template<typename D, typename B>
+    void destructHandle(Handle<B>& handle) noexcept {
+        auto* p = mHandleAllocator.handle_cast<D*>(handle);
+        return mHandleAllocator.deallocate(handle, p);
+    }
 };
 
 }// namespace filament::backend

filament/backend/src/webgpu/WebGPUHandles.cpp

@@ -16,13 +16,42 @@
 
 #include "WebGPUHandles.h"
 
+#include <utility>
+
+namespace {
+
+wgpu::Buffer createIndexBuffer(wgpu::Device const& device, uint8_t elementSize, uint32_t indexCount) {
+    wgpu::BufferDescriptor descriptor{ .label = "index_buffer",
+        .usage = wgpu::BufferUsage::CopyDst | wgpu::BufferUsage::Index,
+        .size = elementSize * indexCount,
+        .mappedAtCreation = false };
+    return device.CreateBuffer(&descriptor);
+}
+} // namespace
+
 namespace filament::backend {
 
-WGPUVertexBuffer::WGPUVertexBuffer(uint32_t vextexCount, uint32_t bufferCount,
-        Handle<WGPUVertexBufferInfo> vbih)
-    : HwVertexBuffer(vextexCount),
-      vbih(vbih),
-      buffers(MAX_VERTEX_BUFFER_COUNT) {}
+
+WGPUIndexBuffer::WGPUIndexBuffer(wgpu::Device const& device, uint8_t elementSize,
+        uint32_t indexCount)
+    : buffer(createIndexBuffer(device, elementSize, indexCount)) {}
+
+
+WGPUVertexBuffer::WGPUVertexBuffer(wgpu::Device const &device, uint32_t vextexCount, uint32_t bufferCount,
+                                   Handle<WGPUVertexBufferInfo> vbih)
+        : HwVertexBuffer(vextexCount),
+          vbih(vbih),
+          buffers(bufferCount) {
+    wgpu::BufferDescriptor descriptor {
+            .usage = wgpu::BufferUsage::CopyDst | wgpu::BufferUsage::Vertex,
+            .size = vextexCount * bufferCount,
+            .mappedAtCreation = false };
+
+    for (uint32_t i = 0; i < bufferCount; ++i) {
+        descriptor.label = ("vertex_buffer_" + std::to_string(i)).c_str();
+        buffers[i] = device.CreateBuffer(&descriptor);
+    }
+}
 
 // TODO: Empty function is a place holder for verxtex buffer updates and should be
 // updated for that purpose.
@@ -31,4 +60,93 @@ void WGPUVertexBuffer::setBuffer(WGPUBufferObject* bufferObject, uint32_t index)
 WGPUBufferObject::WGPUBufferObject(BufferObjectBinding bindingType, uint32_t byteCount)
     : HwBufferObject(byteCount),
       bufferObjectBinding(bindingType) {}
+
+wgpu::ShaderStage WebGPUDescriptorSetLayout::filamentStageToWGPUStage(ShaderStageFlags fFlags) {
+    wgpu::ShaderStage retStages = wgpu::ShaderStage::None;
+    if (any(ShaderStageFlags::VERTEX & fFlags)) {
+        retStages |= wgpu::ShaderStage::Vertex;
+    }
+    if (any(ShaderStageFlags::FRAGMENT & fFlags)) {
+        retStages |= wgpu::ShaderStage::Fragment;
+    }
+    if (any(ShaderStageFlags::COMPUTE & fFlags)) {
+        retStages |= wgpu::ShaderStage::Compute;
+    }
+    return retStages;
+}
+
+WebGPUDescriptorSetLayout::WebGPUDescriptorSetLayout(DescriptorSetLayout const& layout,
+        wgpu::Device const& device) {
+    assert_invariant(device);
+
+    // TODO: layoutDescriptor has a "Label". Ideally we can get info on what this layout is for
+    // debugging. For now, hack an incrementing value.
+    static int layoutNum = 0;
+
+    uint samplerCount =
+            std::count_if(layout.bindings.begin(), layout.bindings.end(), [](auto& fEntry) {
+                return fEntry.type == DescriptorType::SAMPLER ||
+                       fEntry.type == DescriptorType::SAMPLER_EXTERNAL;
+            });
+
+
+    std::vector<wgpu::BindGroupLayoutEntry> wEntries;
+    wEntries.reserve(layout.bindings.size() + samplerCount);
+
+    for (auto fEntry: layout.bindings) {
+        auto& wEntry = wEntries.emplace_back();
+        wEntry.visibility = filamentStageToWGPUStage(fEntry.stageFlags);
+        wEntry.binding = fEntry.binding * 2;
+
+        switch (fEntry.type) {
+            // TODO Metal treats these the same. Is this fine?
+            case DescriptorType::SAMPLER_EXTERNAL:
+            case DescriptorType::SAMPLER: {
+                // Sampler binding is 2n+1 due to split.
+                auto& samplerEntry = wEntries.emplace_back();
+                samplerEntry.binding = fEntry.binding * 2 + 1;
+                samplerEntry.visibility = wEntry.visibility;
+                // We are simply hoping that undefined and defaults suffices here.
+                samplerEntry.sampler.type = wgpu::SamplerBindingType::Undefined;
+                wEntry.texture.sampleType = wgpu::TextureSampleType::Undefined;
+                break;
+            }
+            case DescriptorType::UNIFORM_BUFFER: {
+                wEntry.buffer.hasDynamicOffset =
+                        any(fEntry.flags & DescriptorFlags::DYNAMIC_OFFSET);
+                wEntry.buffer.type = wgpu::BufferBindingType::Uniform;
+                // TODO: Ideally we fill minBindingSize
+                break;
+            }
+
+            case DescriptorType::INPUT_ATTACHMENT: {
+                // TODO: support INPUT_ATTACHMENT. Metal does not currently.
+                PANIC_POSTCONDITION("Input Attachment is not supported");
+                break;
+            }
+
+            case DescriptorType::SHADER_STORAGE_BUFFER: {
+                // TODO: Vulkan does not support this, can we?
+                PANIC_POSTCONDITION("Shader storage is not supported");
+                break;
+            }
+        }
+
+        // Currently flags are only used to specify dynamic offset.
+
+        // UNUSED
+        // fEntry.count
+    }
+
+    wgpu::BindGroupLayoutDescriptor layoutDescriptor{
+        // TODO: layoutDescriptor has a "Label". Ideally we can get info on what this layout is for
+        // debugging. For now, hack an incrementing value.
+        .label{ "layout_" + std::to_string(++layoutNum) },
+        .entryCount = wEntries.size(),
+        .entries = wEntries.data()
+    };
+    // TODO Do we need to defer this until we have more info on textures and samplers??
+    mLayout = device.CreateBindGroupLayout(&layoutDescriptor);
+}
+WebGPUDescriptorSetLayout::~WebGPUDescriptorSetLayout() {}
 }// namespace filament::backend

filament/backend/src/webgpu/WebGPUHandles.h

@@ -28,9 +28,20 @@
 #include <webgpu/webgpu_cpp.h>
 
 #include <cstdint>
+#include <vector>
 
 namespace filament::backend {
 
+class WGPUProgram final : public HwProgram {
+public:
+    WGPUProgram(wgpu::Device&, Program&);
+
+    wgpu::ShaderModule vertexShaderModule = nullptr;
+    wgpu::ShaderModule fragmentShaderModule = nullptr;
+    wgpu::ShaderModule computeShaderModule = nullptr;
+    std::vector<wgpu::ConstantEntry> constants;
+};
+
 struct WGPUBufferObject;
 // TODO: Currently WGPUVertexBufferInfo is not used by WebGPU for useful task.
 // Update the struct when used by WebGPU driver.
@@ -42,20 +53,19 @@ struct WGPUVertexBufferInfo : public HwVertexBufferInfo {
     AttributeArray attributes;
 };
 
-// TODO: Currently WGPUVertexBuffer is not used by WebGPU for useful task.
-// Update the struct when used by WebGPU driver.
 struct WGPUVertexBuffer : public HwVertexBuffer {
-    WGPUVertexBuffer(uint32_t vextexCount, uint32_t bufferCount, Handle<WGPUVertexBufferInfo> vbih);
-    void setBuffer(WGPUBufferObject* bufferObject, uint32_t index);
+    WGPUVertexBuffer(wgpu::Device const &device, uint32_t vextexCount, uint32_t bufferCount,
+                     Handle<WGPUVertexBufferInfo> vbih);
+
+    void setBuffer(WGPUBufferObject *bufferObject, uint32_t index);
 
     Handle<WGPUVertexBufferInfo> vbih;
     utils::FixedCapacityVector<wgpu::Buffer> buffers;
 };
 
-// TODO: Currently WGPUIndexBuffer is not used by WebGPU for useful task.
-// Update the struct when used by WebGPU driver.
 struct WGPUIndexBuffer : public HwIndexBuffer {
-    WGPUIndexBuffer(BufferUsage usage, uint8_t elementSize, uint32_t indexCount);
+    WGPUIndexBuffer(wgpu::Device const &device, uint8_t elementSize,
+                    uint32_t indexCount);
 
     wgpu::Buffer buffer;
 };
@@ -68,6 +78,18 @@ struct WGPUBufferObject : HwBufferObject {
     wgpu::Buffer buffer;
     const BufferObjectBinding bufferObjectBinding;
 };
+class WebGPUDescriptorSetLayout : public HwDescriptorSetLayout {
+public:
+    WebGPUDescriptorSetLayout(DescriptorSetLayout const& layout, wgpu::Device const& device);
+    ~WebGPUDescriptorSetLayout();
+
+private:
+    // TODO: If this is useful elsewhere, remove it from this class
+    // Convert Filament Shader Stage Flags bitmask to webgpu equivilant
+    static wgpu::ShaderStage filamentStageToWGPUStage(ShaderStageFlags fFlags);
+
+    wgpu::BindGroupLayout mLayout;
+};
 
 // TODO: Currently WGPUTexture is not used by WebGPU for useful task.
 // Update the struct when used by WebGPU driver.
@@ -81,6 +103,16 @@ struct WGPUTexture : public HwTexture {
     wgpu::Texture texture = nullptr;
 };
 
+struct WGPURenderPrimitive : public HwRenderPrimitive {
+    WGPURenderPrimitive();
+
+    void setBuffers(WGPUVertexBufferInfo const* const vbi,
+            WGPUVertexBuffer* vertexBuffer, WGPUIndexBuffer* indexBuffer);
+
+    WGPUVertexBuffer* vertexBuffer = nullptr;
+    WGPUIndexBuffer* indexBuffer = nullptr;
+};
+
 // TODO: Currently WGPURenderTarget is not used by WebGPU for useful task.
 // Update the struct when used by WebGPU driver.
 struct WGPURenderTarget : public HwRenderTarget {

filament/backend/src/webgpu/WebGPUSwapChain.cpp

@@ -191,9 +191,12 @@ wgpu::CompositeAlphaMode selectAlphaMode(size_t availableAlphaModesCount,
 }
 
 void initConfig(wgpu::SurfaceConfiguration& config, wgpu::Device const& device,
-        wgpu::SurfaceCapabilities const& capabilities, bool useSRGBColorSpace) {
+        wgpu::SurfaceCapabilities const& capabilities, wgpu::Extent2D const& surfaceSize,
+        bool useSRGBColorSpace) {
     config.device = device;
     config.usage = wgpu::TextureUsage::RenderAttachment;
+    config.width = surfaceSize.width;
+    config.height = surfaceSize.height;
     config.format =
             selectColorFormat(capabilities.formatCount, capabilities.formats, useSRGBColorSpace);
     config.presentMode =
@@ -205,8 +208,8 @@ void initConfig(wgpu::SurfaceConfiguration& config, wgpu::Device const& device,
 
 namespace filament::backend {
 
-WebGPUSwapChain::WebGPUSwapChain(wgpu::Surface&& surface, wgpu::Adapter& adapter,
-        wgpu::Device& device, uint64_t flags)
+WebGPUSwapChain::WebGPUSwapChain(wgpu::Surface&& surface, wgpu::Extent2D const& surfaceSize,
+        wgpu::Adapter& adapter, wgpu::Device& device, uint64_t flags)
     : mSurface(surface) {
     wgpu::SurfaceCapabilities capabilities = {};
     if (!mSurface.GetCapabilities(adapter, &capabilities)) {
@@ -217,43 +220,42 @@ WebGPUSwapChain::WebGPUSwapChain(wgpu::Surface&& surface, wgpu::Adapter& adapter
 #endif
     }
     const bool useSRGBColorSpace = (flags & SWAP_CHAIN_CONFIG_SRGB_COLORSPACE) != 0;
-    initConfig(mConfig, device, capabilities, useSRGBColorSpace);
+    initConfig(mConfig, device, capabilities, surfaceSize, useSRGBColorSpace);
+    mSurface.Configure(&mConfig);
 }
 
 WebGPUSwapChain::~WebGPUSwapChain() {
-    if (mConfigured) {
-        mSurface.Unconfigure();
-        mConfigured = false;
-    }
+    mSurface.Unconfigure();
 }
 
-void WebGPUSwapChain::getCurrentTexture(uint32_t width, uint32_t height, wgpu::SurfaceTexture* texture) {
-    if (width < 1 || height < 1) {
-        PANIC_LOG("WebGPUSwapChain::GetCurrentTexture: Invalid width and/or height requested.");
-        return;
-    }
-    if (mConfig.width != width || mConfig.height != height || !mConfigured) {
-        mConfig.width = width;
-        mConfig.height = height;
+void WebGPUSwapChain::setExtent(wgpu::Extent2D const& currentSurfaceSize) {
+    FILAMENT_CHECK_POSTCONDITION(currentSurfaceSize.width > 0 || currentSurfaceSize.height > 0)
+            << "WebGPUSwapChain::setExtent: Invalid width " << currentSurfaceSize.width
+            << " and/or height " << currentSurfaceSize.height << " requested.";
+    if (mConfig.width != currentSurfaceSize.width || mConfig.height != currentSurfaceSize.height) {
+        mConfig.width = currentSurfaceSize.width;
+        mConfig.height = currentSurfaceSize.height;
 #if FWGPU_ENABLED(FWGPU_PRINT_SYSTEM)
         printSurfaceConfiguration(mConfig);
 #endif
+        FWGPU_LOGD << "Resizing to width " << mConfig.width << " height " << mConfig.height
+                   << utils::io::endl;
+        // TODO we may need to ensure no surface texture is flight when we do this. some
+        //      synchronization may be necessary
         mSurface.Configure(&mConfig);
-        mConfigured = true;
     }
-
-    mSurface.GetCurrentTexture(texture);
 }
 
-wgpu::TextureView WebGPUSwapChain::getNextSurfaceTextureView(uint32_t width, uint32_t height) {
+wgpu::TextureView WebGPUSwapChain::getCurrentSurfaceTextureView(
+        wgpu::Extent2D const& currentSurfaceSize) {
+    setExtent(currentSurfaceSize);
     wgpu::SurfaceTexture surfaceTexture;
-    getCurrentTexture(width, height, &surfaceTexture);
+    mSurface.GetCurrentTexture(&surfaceTexture);
     if (surfaceTexture.status != wgpu::SurfaceGetCurrentTextureStatus::SuccessOptimal) {
         return nullptr;
     }
-
     // Create a view for this surface texture
-    //TODO: review these initiliazations as webgpu pipeline gets mature
+    // TODO: review these initiliazations as webgpu pipeline gets mature
     wgpu::TextureViewDescriptor textureViewDescriptor = {
         .label = "texture_view",
         .format = surfaceTexture.texture.GetFormat(),

filament/backend/src/webgpu/WebGPUSwapChain.h

@@ -19,26 +19,28 @@
 
 #include <webgpu/webgpu_cpp.h>
 
+#include "DriverBase.h"
 #include <backend/Platform.h>
 
 #include <cstdint>
 
 namespace filament::backend {
 
-class WebGPUSwapChain : public Platform::SwapChain {
+class WebGPUSwapChain final : public Platform::SwapChain, HwSwapChain {
 public:
-    WebGPUSwapChain(wgpu::Surface&& surface, wgpu::Adapter& adapter, wgpu::Device& device,
-            uint64_t flags);
+    WebGPUSwapChain(wgpu::Surface&& surface, wgpu::Extent2D const& surfaceSize,
+            wgpu::Adapter& adapter, wgpu::Device& device, uint64_t flags);
     ~WebGPUSwapChain();
 
-    wgpu::TextureView getNextSurfaceTextureView(uint32_t width, uint32_t height);
+    wgpu::TextureView getCurrentSurfaceTextureView(wgpu::Extent2D const&);
+
     void present();
 
 private:
-    void getCurrentTexture(uint32_t width, uint32_t height, wgpu::SurfaceTexture*);
+    void setExtent(wgpu::Extent2D const&);
+
     wgpu::Surface mSurface = {};
     wgpu::SurfaceConfiguration mConfig = {};
-    bool mConfigured = false;
 };
 
 } // namespace filament::backend

filament/backend/src/webgpu/platform/WebGPUPlatformAndroid.cpp

@@ -18,6 +18,7 @@
 
 #include <utils/Panic.h>
 
+#include <android/native_window.h>
 #include <webgpu/webgpu_cpp.h>
 
 #include <cstdint>
@@ -28,6 +29,14 @@
 
 namespace filament::backend {
 
+wgpu::Extent2D WebGPUPlatform::getSurfaceExtent(void* nativeWindow) const {
+    ANativeWindow* window = static_cast<ANativeWindow*>(nativeWindow);
+    return wgpu::Extent2D{
+        .width = static_cast<uint32_t>(ANativeWindow_getWidth(window)),
+        .height = static_cast<uint32_t>(ANativeWindow_getHeight(window))
+    };
+}
+
 wgpu::Surface WebGPUPlatform::createSurface(void* nativeWindow, uint64_t /*flags*/) {
     wgpu::SurfaceSourceAndroidNativeWindow surfaceSourceAndroidWindow{};
     surfaceSourceAndroidWindow.window = nativeWindow;

filament/backend/src/webgpu/platform/WebGPUPlatformApple.mm

@@ -33,6 +33,15 @@
 
 namespace filament::backend {
 
+wgpu::Extent2D WebGPUPlatform::getSurfaceExtent(void* nativeWindow) const {
+    // Both IOS and MacOS expects CAMetalLayer.
+    CAMetalLayer* metalLayer = (__bridge CAMetalLayer*) nativeWindow;
+    return wgpu::Extent2D{
+        .width = static_cast<uint32_t>(metalLayer.drawableSize.width),
+        .height = static_cast<uint32_t>(metalLayer.drawableSize.height)
+    };
+}
+
 wgpu::Surface WebGPUPlatform::createSurface(void* nativeWindow, uint64_t /*flags*/) {
     wgpu::Surface surface = nullptr;
     // Both IOS and MacOS expects CAMetalLayer.

filament/backend/src/webgpu/platform/WebGPUPlatformLinux.cpp

@@ -79,6 +79,74 @@
 
 namespace filament::backend {
 
+wgpu::Extent2D WebGPUPlatform::getSurfaceExtent(void* nativeWindow) const {
+    auto surfaceExtent = wgpu::Extent2D{};
+#if defined(__linux__) && defined(FILAMENT_SUPPORTS_WAYLAND)
+    wl* ptrval = reinterpret_cast<wl*>(nativeWindow);
+    surfaceExtent.width = ptrval->width;
+    surfaceExtent.height = ptrval->height;
+    FILAMENT_CHECK_POSTCONDITION(surfaceExtent.width != 0 && surfaceExtent.height != 0)
+            << "Unable to get window size for Linux Wayland-backed surface.";
+#elif defined(LINUX_OR_FREEBSD) && defined(FILAMENT_SUPPORTS_X11)
+    if (g_x11.library == nullptr) {
+        g_x11.library = dlopen(LIBRARY_X11, RTLD_LOCAL | RTLD_NOW);
+        FILAMENT_CHECK_PRECONDITION(g_x11.library) << "Unable to open X11 library.";
+        #if defined(FILAMENT_SUPPORTS_XCB)
+            g_x11.xcbConnect = (XCB_CONNECT) dlsym(g_x11.library, "xcb_connect");
+            int screen = 0;
+            g_x11.connection = g_x11.xcbConnect(nullptr, &screen);
+        #endif
+        #if defined(FILAMENT_SUPPORTS_XLIB)
+            g_x11.openDisplay = (X11_OPEN_DISPLAY) dlsym(g_x11.library, "XOpenDisplay");
+            g_x11.display = g_x11.openDisplay(NULL);
+            FILAMENT_CHECK_PRECONDITION(g_x11.display) << "Unable to open X11 display.";
+        #endif
+    }
+    #if defined(FILAMENT_SUPPORTS_XCB) || defined(FILAMENT_SUPPORTS_XLIB)
+        bool useXcb = false;
+    #endif
+    #if defined(FILAMENT_SUPPORTS_XCB)
+        #if defined(FILAMENT_SUPPORTS_XLIB)
+            useXcb = (SWAP_CHAIN_CONFIG_ENABLE_XCB) != 0;
+        #else
+            useXcb = true;
+        #endif
+        if (useXcb) {
+            const xcb_setup_t* setup = xcb_get_setup(g_x11.connection);
+            xcb_screen_iterator_t screen_iter = xcb_setup_roots_iterator(setup);
+            xcb_screen_t* screen = screen_iter.data;
+            surfaceExtent.width = static_cast<uint32_t>(screen->width_in_pixels);
+            surfaceExtent.height = static_cast<uint32_t>(screen->height_in_pixels);
+            FILAMENT_CHECK_POSTCONDITION(surfaceExtent.width != 0 && surfaceExtent.height != 0)
+                    << "Unable to get window surface size for Linux (or FreeBSD) "
+                       "XCB-backed surface.";
+        }
+    #endif
+    #if defined(FILAMENT_SUPPORTS_XLIB)
+        if (!useXcb) {
+            int screenNumber = DefaultScreen(g_x11.display);
+            Screen* screen = ScreenOfDisplay(g_x11.display, screenNumber);
+            surfaceExtent.width = static_cast<uint32_t>(WidthOfScreen(screen));
+            surfaceExtent.height = static_cast<uint32_t>(HeightOfScreen(screen));
+            FILAMENT_CHECK_POSTCONDITION(surfaceExtent.width != 0 && surfaceExtent.height != 0)
+                    << "Unable to get window surface size for Linux (or FreeBSD) "
+                       "XLib-backed surface.";
+        }
+    #endif
+    FILAMENT_CHECK_POSTCONDITION(surfaceExtent.width != 0 && surfaceExtent.height != 0)
+            << "Cannot get window surface size for X11 surface for Linux (or FreeBSD) OS "
+               "(not built with support for XCB or XLIB?)";
+#elif defined(__linux__)
+    FILAMENT_CHECK_POSTCONDITION(surfaceExtent.width != 0 && surfaceExtent.height != 0)
+            << "Cannot get window surface size for Linux (or FreeBSD) OS "
+               "(not built with support for Wayland or X11?)";
+#else
+    FILAMENT_CHECK_POSTCONDITION(surfaceExtent.width != 0 && surfaceExtent.height != 0)
+            << "Not a supported (Linux) OS + WebGPU platform";
+#endif
+    return surfaceExtent;
+}
+
 wgpu::Surface WebGPUPlatform::createSurface(void* nativeWindow, uint64_t flags) {
     wgpu::Surface surface = nullptr;
 #if defined(__linux__) && defined(FILAMENT_SUPPORTS_WAYLAND)

filament/backend/src/webgpu/platform/WebGPUPlatformWindows.cpp

@@ -30,6 +30,16 @@
 
 namespace filament::backend {
 
+wgpu::Extent2D WebGPUPlatform::getSurfaceExtent(void* nativeWindow) const {
+    HWND window = static_cast<HWND>(nativeWindow);
+    RECT windowRect;
+    GetWindowRect(window, &windowRect);
+    return wgpu::Extent2D{
+        .width = static_cast<uint32_t>(windowRect.right - windowRect.left),
+        .height = static_cast<uint32_t>(windowRect.bottom - windowRect.top)
+    };
+}
+
 wgpu::Surface WebGPUPlatform::createSurface(void* nativeWindow, uint64_t /*flags*/) {
     // TODO verify this is necessary for Dawn implementation as well:
     // On (at least) NVIDIA drivers, the Vulkan implementation (specifically the call to

filament/backend/test/BackendTest.cpp

@@ -43,24 +43,29 @@ using namespace image;
 namespace test {
 
 Backend BackendTest::sBackend = Backend::NOOP;
+OperatingSystem BackendTest::sOperatingSystem = OperatingSystem::OTHER;
 bool BackendTest::sIsMobilePlatform = false;
 
-void BackendTest::init(Backend backend, bool isMobilePlatform) {
+void BackendTest::init(Backend backend, OperatingSystem operatingSystem, bool isMobilePlatform) {
     sBackend = backend;
+    sOperatingSystem = operatingSystem;
     sIsMobilePlatform = isMobilePlatform;
 }
 
 BackendTest::BackendTest() : commandBufferQueue(CONFIG_MIN_COMMAND_BUFFERS_SIZE,
         CONFIG_COMMAND_BUFFERS_SIZE, /*mPaused=*/false) {
     initializeDriver();
+    mImageExpectations.emplace(getDriverApi());
 }
 
 BackendTest::~BackendTest() {
+    // Ensure all graphics commands and callbacks are finished.
+    flushAndWait();
+    mImageExpectations->evaluate();
     // Note: Don't terminate the driver for OpenGL, as it wipes away the context and removes the buffer from the screen.
     if (sBackend == Backend::OPENGL) {
         return;
     }
-    flushAndWait();
     driver->terminate();
     delete driver;
 }
@@ -154,49 +159,16 @@ void BackendTest::renderTriangle(
     api.endRenderPass();
 }
 
-void BackendTest::readPixelsAndAssertHash(const char* testName, size_t width, size_t height,
-        Handle<HwRenderTarget> rt, uint32_t expectedHash, bool exportScreenshot) {
-    void* buffer = calloc(1, width * height * 4);
+bool BackendTest::matchesEnvironment(Backend backend) {
+    return sBackend == backend;
+}
 
-    struct Capture {
-        uint32_t expectedHash;
-        char* name;
-        bool exportScreenshot;
-        size_t width, height;
-    };
-    auto* c = new Capture();
-    c->expectedHash = expectedHash;
-    c->name = strdup(testName);
-    c->exportScreenshot = exportScreenshot;
-    c->width = width;
-    c->height = height;
+bool BackendTest::matchesEnvironment(OperatingSystem operatingSystem) {
+    return sOperatingSystem == operatingSystem;
+}
 
-    PixelBufferDescriptor pbd(buffer, width * height * 4, PixelDataFormat::RGBA, PixelDataType::UBYTE,
-            1, 0, 0, width, [](void* buffer, size_t size, void* user) {
-                auto* c = (Capture*)user;
-
-                // Export a screenshot, if requested.
-                if (c->exportScreenshot) {
-#ifndef FILAMENT_IOS
-                    LinearImage image(c->width, c->height, 4);
-                    image = toLinearWithAlpha<uint8_t>(c->width, c->height, c->width * 4,
-                            (uint8_t*) buffer);
-                    const std::string png = std::string(c->name) + ".png";
-                    std::ofstream outputStream(png.c_str(), std::ios::binary | std::ios::trunc);
-                    ImageEncoder::encode(outputStream, ImageEncoder::Format::PNG, image, "",
-                            png);
-#endif
-                }
-
-                // Hash the contents of the buffer and check that they match.
-                uint32_t hash = utils::hash::murmur3((const uint32_t*) buffer, size / 4, 0);
-                ASSERT_EQ(hash, c->expectedHash) << c->name << " failed: hashes do not match." << std::endl;
-
-                free(buffer);
-                free(c->name);
-                free(c);
-            }, (void*)c);
-    getDriverApi().readPixels(rt, 0, 0, width, height, std::move(pbd));
+bool BackendTest::matchesEnvironment(OperatingSystem operatingSystem, Backend backend) {
+    return matchesEnvironment(operatingSystem) && matchesEnvironment(backend);
 }
 
 class Environment : public ::testing::Environment {
@@ -210,8 +182,8 @@ public:
     }
 };
 
-void initTests(Backend backend, bool isMobile, int& argc, char* argv[]) {
-    BackendTest::init(backend, isMobile);
+void initTests(Backend backend, OperatingSystem operatingSystem, bool isMobile, int& argc, char* argv[]) {
+    BackendTest::init(backend, operatingSystem, isMobile);
     ::testing::InitGoogleTest(&argc, argv);
     ::testing::AddGlobalTestEnvironment(new Environment);
 }

filament/backend/test/BackendTest.h

@@ -25,15 +25,17 @@
 #include "private/backend/DriverApi.h"
 
 #include "PlatformRunner.h"
+#include "ImageExpectations.h"
 
 namespace test {
 
 class BackendTest : public ::testing::Test {
 public:
 
-    static void init(Backend backend, bool isMobilePlatform);
+    static void init(Backend backend, OperatingSystem operatingSystem, bool isMobilePlatform);
 
     static Backend sBackend;
+    static OperatingSystem sOperatingSystem;
     static bool sIsMobilePlatform;
 
 protected:
@@ -64,13 +66,14 @@ protected:
             filament::backend::Handle<filament::backend::HwProgram> program,
             const filament::backend::RenderPassParams& params);
 
-    void readPixelsAndAssertHash(const char* testName, size_t width, size_t height,
-            filament::backend::Handle<filament::backend::HwRenderTarget> rt, uint32_t expectedHash,
-            bool exportScreenshot = false);
-
     filament::backend::DriverApi& getDriverApi() { return *commandStream; }
     filament::backend::Driver& getDriver() { return *driver; }
 
+    ImageExpectations& getExpectations() { return *mImageExpectations; }
+
+    static bool matchesEnvironment(Backend backend);
+    static bool matchesEnvironment(OperatingSystem operatingSystem);
+    static bool matchesEnvironment(OperatingSystem operatingSystem, Backend backend);
 private:
 
     filament::backend::Driver* driver = nullptr;
@@ -78,6 +81,10 @@ private:
     std::unique_ptr<filament::backend::DriverApi> commandStream;
 
     filament::backend::Handle<filament::backend::HwBufferObject> uniform;
+
+    // This isn't truly optional, it just needs to delay construction until after the driver has
+    // been initialized
+    std::optional<ImageExpectations> mImageExpectations;
 };
 
 } // namespace test

filament/backend/test/ImageExpectations.cpp

@@ -16,7 +16,6 @@
 
 #include "ImageExpectations.h"
 
-#include "gtest/gtest.h"
 #include "gmock/gmock.h"
 #include "absl/strings/str_format.h"
 #include "utils/Hash.h"
@@ -28,14 +27,17 @@
 #ifndef FILAMENT_IOS
 
 #include <imageio/ImageEncoder.h>
+#include <imageio/ImageDecoder.h>
 #include <image/ColorTransform.h>
 
 #endif
 
 ScreenshotParams::ScreenshotParams(int width, int height, std::string fileName,
-        uint32_t expectedPixelHash)
-        : mWidth(width), mHeight(height), mFileName(std::move(fileName)),
-          mExpectedPixelHash(expectedPixelHash) {}
+        uint32_t expectedHash)
+    : mWidth(width),
+      mHeight(height),
+      mExpectedPixelHash(expectedHash),
+      mFileName(std::move(fileName)) {}
 
 int ScreenshotParams::width() const {
     return mWidth;
@@ -49,24 +51,28 @@ uint32_t ScreenshotParams::expectedHash() const {
     return mExpectedPixelHash;
 }
 
-std::string ScreenshotParams::outputDirectoryPath() const {
-    return ".";
+std::string ScreenshotParams::actualDirectoryPath() {
+    return "images/actual_images";
 }
 
-std::string ScreenshotParams::generatedActualFileName() const {
+std::string ScreenshotParams::actualFileName() const {
     return absl::StrFormat("%s_actual.png", mFileName);
 }
 
-std::string ScreenshotParams::generatedActualFilePath() const {
-    return absl::StrFormat("%s/%s", outputDirectoryPath(), generatedActualFileName());
+std::string ScreenshotParams::actualFilePath() const {
+    return absl::StrFormat("%s/%s", actualDirectoryPath(), actualFileName());
 }
 
-std::string ScreenshotParams::goldenFileName() const {
-    return absl::StrFormat("%s_golden.png", mFileName);
+std::string ScreenshotParams::expectedDirectoryPath() {
+    return "images/expected_images";
 }
 
-std::string ScreenshotParams::goldenFilePath() const {
-    return absl::StrFormat("%s/%s", outputDirectoryPath(), goldenFileName());
+std::string ScreenshotParams::expectedFileName() const {
+    return absl::StrFormat("%s.png", mFileName);
+}
+
+std::string ScreenshotParams::expectedFilePath() const {
+    return absl::StrFormat("%s/%s", expectedDirectoryPath(), expectedFileName());
 }
 
 ImageExpectation::ImageExpectation(const char* fileName, int lineNumber,
@@ -91,11 +97,22 @@ void ImageExpectation::evaluate() {
 
 void ImageExpectation::compareImage() const {
     bool bytesFilled = mResult.bytesFilled();
+    // If this fails, it likely means that BackendTest::flushAndWait needs to be called before
+    // ImageExpectations is evaluated or destroyed.
     EXPECT_THAT(bytesFilled, testing::IsTrue())
                         << "Render target wasn't copied to the buffer for " << mFileName;
     if (bytesFilled) {
+        // Rather than directly compare the two images compare their hashes because comparing very
+        // large arrays generates way too much debug output to be useful.
         uint32_t actualHash = mResult.hash();
-        EXPECT_THAT(actualHash, testing::Eq(mParams.expectedHash()));
+#ifndef FILAMENT_IOS
+        LoadedPng loadedImage(mParams.expectedFilePath());
+        uint32_t loadedImageHash = loadedImage.hash();
+        EXPECT_THAT(actualHash, testing::Eq(loadedImageHash)) << mParams.expectedFileName();
+#endif
+        // For builds that can't load PNGs (currently iOS only) use the expected hash.
+        EXPECT_THAT(actualHash, testing::Eq(mParams.expectedHash())) << mParams.expectedFileName();
+        // TODO: Add better debug output, such as generating a diff image.
     }
 }
 
@@ -109,12 +126,13 @@ ImageExpectations::~ImageExpectations() {
 
 void ImageExpectations::addExpectation(const char* fileName, int lineNumber,
         filament::backend::RenderTargetHandle renderTarget, ScreenshotParams params) {
-    mExpectations.emplace_back(fileName, lineNumber, mApi, std::move(params), renderTarget);
+    mExpectations.emplace_back(std::make_unique<ImageExpectation>(fileName, lineNumber, mApi,
+            std::move(params), renderTarget));
 }
 
 void ImageExpectations::evaluate() {
     for (auto& expectation: mExpectations) {
-        expectation.evaluate();
+        expectation->evaluate();
     }
     mExpectations.clear();
 }
@@ -122,32 +140,28 @@ void ImageExpectations::evaluate() {
 RenderTargetDump::RenderTargetDump(filament::backend::DriverApi& api,
         filament::backend::RenderTargetHandle renderTarget, const ScreenshotParams& params)
         : mInternal(std::make_unique<RenderTargetDump::Internal>(params)) {
-#ifdef FILAMENT_IOS
-    bytesFilled_ = true;
-    bytes_.resize(size);
-    std::fill(bytes_.begin(), bytes_.end(), 0);
-#else
     const size_t size = mInternal->params.width() * mInternal->params.height() * 4;
     mInternal->bytes.resize(size);
 
     auto cb = [](void* buffer, size_t size, void* user) {
         auto* internal = static_cast<RenderTargetDump::Internal*>(user);
+        internal->bytesFilled = true;
+#ifndef FILAMENT_IOS
         image::LinearImage image(internal->params.width(), internal->params.width(), 4);
         image = image::toLinearWithAlpha<uint8_t>(internal->params.width(),
                 internal->params.height(),
                 internal->params.width() * 4, (uint8_t*)buffer);
-        std::string filePath = internal->params.generatedActualFilePath();
+        std::string filePath = internal->params.actualFilePath();
         std::ofstream pngStream(filePath, std::ios::binary | std::ios::trunc);
         image::ImageEncoder::encode(pngStream, image::ImageEncoder::Format::PNG, image, "",
                 filePath);
-        internal->bytesFilled = true;
+#endif
     };
     filament::backend::PixelBufferDescriptor pb(mInternal->bytes.data(), size,
             filament::backend::PixelDataFormat::RGBA, filament::backend::PixelDataType::UBYTE, cb,
             (void*)mInternal.get());
     api.readPixels(renderTarget, 0, 0, mInternal->params.width(), mInternal->params.height(),
             std::move(pb));
-#endif
 }
 
 RenderTargetDump::~RenderTargetDump() {
@@ -169,4 +183,30 @@ bool RenderTargetDump::bytesFilled() const {
     return mInternal->bytesFilled;
 }
 
-RenderTargetDump::Internal::Internal(const ScreenshotParams& params) : params(params) {}
+RenderTargetDump::Internal::Internal(const ScreenshotParams& params) : params(params) {}
+
+LoadedPng::LoadedPng(std::string filePath) : mFilePath(std::move(filePath)) {
+#ifndef FILAMENT_IOS
+    std::ifstream pngStream(mFilePath, std::ios::binary);
+    image::LinearImage loadedImage = image::ImageDecoder::decode(pngStream, filePath,
+            image::ImageDecoder::ColorSpace::LINEAR);
+    size_t valuesInImage = loadedImage.getWidth() * loadedImage.getHeight() *
+                          loadedImage.getChannels();
+    // The linear image is loaded with each component as [0.0, 1.0] but should be [0, 255], so
+    // convert them.
+    mBytes = std::vector<unsigned char>(valuesInImage);
+    for (int i = 0; i < valuesInImage; ++i) {
+        mBytes[i] = static_cast<uint8_t>(loadedImage.get<float>()[i] * 255.0f);
+    }
+#endif
+    // For platforms that don't support the image loading library, leave the loaded data blank.
+}
+
+uint32_t LoadedPng::hash() const {
+    EXPECT_THAT(mBytes, testing::Not(testing::IsEmpty()))
+            << "Failed to load expected test result: " << mFilePath;
+    if (mBytes.empty()) {
+        return 0;
+    }
+    return utils::hash::murmur3((uint32_t*)mBytes.data(), mBytes.size() / 4, 0);
+}

filament/backend/test/ImageExpectations.h

@@ -46,11 +46,12 @@ public:
     int height() const;
     uint32_t expectedHash() const;
 
-    std::string outputDirectoryPath() const;
-    std::string generatedActualFileName() const;
-    std::string generatedActualFilePath() const;
-    std::string goldenFileName() const;
-    std::string goldenFilePath() const;
+    static std::string actualDirectoryPath();
+    std::string actualFileName() const;
+    std::string actualFilePath() const;
+    static std::string expectedDirectoryPath();
+    std::string expectedFileName() const;
+    std::string expectedFilePath() const;
 
 private:
     int mWidth;
@@ -98,6 +99,17 @@ private:
     std::unique_ptr<Internal> mInternal;
 };
 
+class LoadedPng {
+public:
+    explicit LoadedPng(std::string filePath);
+
+    uint32_t hash() const;
+
+private:
+    std::string mFilePath;
+    std::vector<unsigned char> mBytes;
+};
+
 class ImageExpectation {
 public:
     ImageExpectation(const char* fileName, int lineNumber, filament::backend::DriverApi& api,
@@ -130,7 +142,8 @@ public:
 
 private:
     filament::backend::DriverApi& mApi;
-    std::vector<ImageExpectation> mExpectations;
+    // Store expectations in unique pointers because they are self referential.
+    std::vector<std::unique_ptr<ImageExpectation>> mExpectations;
 };
 
 #endif //TNT_IMAGE_EXPECTATIONS_H

filament/backend/test/PlatformRunner.cpp

@@ -0,0 +1,60 @@
+/*
+ * Copyright (C) 2019 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#include "PlatformRunner.h"
+
+namespace utils {
+
+template<>
+CString to_string<test::Backend>(test::Backend backend) noexcept {
+    switch (backend) {
+        case test::Backend::OPENGL: {
+            return "OpenGL";
+        }
+        case test::Backend::VULKAN: {
+            return "Vulkan";
+        }
+        case test::Backend::METAL: {
+            return "Metal";
+        }
+        case test::Backend::WEBGPU: {
+            return "WebGPU";
+        }
+        case test::Backend::NOOP:
+        default: {
+            return "No-op";
+        }
+    }
+}
+
+template<>
+CString to_string(test::OperatingSystem os) noexcept {
+    switch (os) {
+        case test::OperatingSystem::LINUX: {
+            return "Linux";
+        }
+        case test::OperatingSystem::APPLE: {
+            return "Apple";
+        }
+        case test::OperatingSystem::OTHER:
+        default: {
+            return "Other";
+        }
+    }
+}
+
+} // namespace utils
+

filament/backend/test/PlatformRunner.h

@@ -19,6 +19,7 @@
 
 #include <stdint.h>
 #include <stddef.h>
+#include "utils/CString.h"
 
 namespace test {
 
@@ -34,6 +35,15 @@ enum class Backend : uint8_t {
     NOOP = 5,
 };
 
+enum class OperatingSystem: uint8_t {
+    OTHER = 1,
+    // Also represents android phones.
+    LINUX = 2,
+    // Also represents iOS phones.
+    APPLE = 3,
+    // TODO: When tests support windows add it here.
+};
+
 struct NativeView {
     void* ptr = nullptr;
     size_t width = 0, height = 0;
@@ -51,9 +61,10 @@ NativeView getNativeView();
  * No tests will be run yet.
  *
  * @param backend The backend to run the tests on.
+ * @param operatingSystem The operating system the tests are being run on.
  * @param isMobile True if the platform is a mobile platform (iOS or Android).
  */
-void initTests(Backend backend, bool isMobile, int& argc, char* argv[]);
+void initTests(Backend backend, OperatingSystem operatingSystem, bool isMobile, int& argc, char* argv[]);
 
 /**
  * Test runners should call runTests when they are ready for tests to be run.
@@ -68,6 +79,6 @@ int runTests();
  */
 Backend parseArgumentsForBackend(int argc, char* argv[]);
 
-}
+} // namespace test
 
 #endif

filament/backend/test/Skip.cpp

@@ -0,0 +1,96 @@
+/*
+ * Copyright (C) 2025 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#include "Skip.h"
+
+#include <sstream>
+
+namespace test {
+
+SkipEnvironment::SkipEnvironment(test::Backend backend) : backend(backend) {}
+SkipEnvironment::SkipEnvironment(test::OperatingSystem os) : os(os) {}
+SkipEnvironment::SkipEnvironment(test::OperatingSystem os, test::Backend backend)
+    : backend(backend),
+      os(os) {}
+
+bool SkipEnvironment::matches() {
+    bool backendMatches = !backend.has_value() || *backend == BackendTest::sBackend;
+    bool osMatches = !os.has_value() || *os == BackendTest::sOperatingSystem;
+    bool isMobileMatches = !isMobile.has_value() || *isMobile == BackendTest::sIsMobilePlatform;
+    return backendMatches && osMatches && isMobileMatches;
+}
+
+std::string SkipEnvironment::describe() {
+    std::stringstream result;
+    if (matches()) {
+        result << "environment matches because " << describe_actual_environment() << ".";
+    } else {
+        result << "environment does not match because " << describe_requirements() << " but "
+               << describe_actual_environment() << ".";
+    }
+    return result.str();
+}
+
+std::string SkipEnvironment::describe_actual_environment() {
+    bool resultWritten = false;
+    std::stringstream reality;
+    if (backend.has_value()) {
+        reality << "backend was " << utils::to_string(BackendTest::sBackend).c_str();
+        resultWritten = true;
+    }
+    if (os.has_value()) {
+        if (resultWritten) {
+            reality << ", and ";
+        }
+        reality << "operating system was "
+                << utils::to_string(BackendTest::sOperatingSystem).c_str();
+        resultWritten = true;
+    }
+    if (isMobile.has_value()) {
+        if (resultWritten) {
+            reality << ", and ";
+        }
+        reality << "device " << (BackendTest::sIsMobilePlatform ? "was" : "was not") << " mobile";
+        resultWritten = true;
+    }
+    return reality.str();
+}
+
+std::string SkipEnvironment::describe_requirements() {
+    bool resultWritten = false;
+    std::stringstream requirement;
+    if (backend.has_value()) {
+        requirement << "backend needs to be " << utils::to_string(*backend).c_str();
+        resultWritten = true;
+    }
+    if (os.has_value()) {
+        if (resultWritten) {
+            requirement << ", and ";
+        }
+        requirement << "operating system needs to be " << utils::to_string(*os).c_str();
+        resultWritten = true;
+    }
+    if (isMobile.has_value() && BackendTest::sIsMobilePlatform != isMobile) {
+        if (resultWritten) {
+            requirement << ", and ";
+        }
+        requirement << "device needs to " << (*isMobile ? "be" : "not be") << " mobile";
+        resultWritten = true;
+    }
+    return requirement.str();
+}
+
+} // namespace test

filament/backend/test/Skip.h

@@ -0,0 +1,55 @@
+/*
+ * Copyright (C) 2025 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#ifndef TNT_SKIP_H
+#define TNT_SKIP_H
+
+#include <gtest/gtest.h>
+#include "BackendTest.h"
+
+// skipEnvironment must be a test::SkipEnvironment
+#define SKIP_IF(skipEnvironment)                                                                   \
+do {                                                                                               \
+    SkipEnvironment skip(skipEnvironment);                                                         \
+    if (skip.matches()) {                                                                          \
+        GTEST_SKIP() << "Skipping test as the " << skip.describe();                                \
+    }                                                                                              \
+} while (false)
+
+namespace test {
+
+struct SkipEnvironment {
+    SkipEnvironment(const SkipEnvironment&) = default;
+    explicit SkipEnvironment(test::Backend backend);
+    explicit SkipEnvironment(test::OperatingSystem os);
+    SkipEnvironment(test::OperatingSystem os, test::Backend backend);
+
+    std::optional<test::Backend> backend;
+    std::optional<test::OperatingSystem> os;
+    std::optional<bool> isMobile;
+
+    bool matches();
+    // Describes the current state of either matching or mismatching.
+    std::string describe();
+    // Describe all the non-null requirements.
+    std::string describe_requirements();
+    // Describes the environment's status for all the attributes that are non-null.
+    std::string describe_actual_environment();
+};
+
+} // namespace test
+
+#endif// TNT_SKIP_H

filament/backend/test/linux_runner.cpp

@@ -51,6 +51,6 @@ int main(int argc, char* argv[]) {
         return 1;
     }
 
-    test::initTests(backend, false, argc, argv);
+    test::initTests(backend, test::OperatingSystem::LINUX, false, argc, argv);
     return test::runTests();
 }

filament/backend/test/mac_runner.mm

@@ -98,7 +98,7 @@ test::NativeView getNativeView() {
 
 int main(int argc, char* argv[]) {
     auto backend = test::parseArgumentsForBackend(argc, argv);
-    test::initTests(backend, false, argc, argv);
+    test::initTests(backend, test::OperatingSystem::APPLE, false, argc, argv);
     AppDelegate* delegate = [AppDelegate new];
     delegate.backend = backend;
     NSApplication* app = [NSApplication sharedApplication];

filament/backend/test/test_Blit.cpp

@@ -197,16 +197,10 @@ TEST_F(BlitTest, ColorMagnify) {
     }
 
     {
-        ImageExpectations expectations(api);
-
-        {
-            RenderFrame frame(api);
-            EXPECT_IMAGE(dstRenderTargets[0], expectations,
-                    ScreenshotParams(kDstTexWidth, kDstTexHeight, "ColorMagnify", 0x410bdd31));
-            api.commit(swapChain);
-        }
-
-        flushAndWait();
+        RenderFrame frame(api);
+        EXPECT_IMAGE(dstRenderTargets[0], getExpectations(),
+                ScreenshotParams(kDstTexWidth, kDstTexHeight, "ColorMagnify", 0x410bdd31));
+        api.commit(swapChain);
     }
 }
 
@@ -260,14 +254,8 @@ TEST_F(BlitTest, ColorMinify) {
             { 0, 0, kSrcTexWidth >> srcLevel, kSrcTexHeight >> srcLevel },
             SamplerMagFilter::LINEAR);
 
-    {
-        ImageExpectations expectations(api);
-
-        EXPECT_IMAGE(dstRenderTargets[0], expectations,
-                ScreenshotParams(kDstTexWidth, kDstTexHeight, "ColorMinify", 0xf3d9c53f));
-
-        flushAndWait();
-    }
+    EXPECT_IMAGE(dstRenderTargets[0], getExpectations(),
+            ScreenshotParams(kDstTexWidth, kDstTexHeight, "ColorMinify", 0xf3d9c53f));
 }
 
 TEST_F(BlitTest, ColorResolve) {
@@ -351,14 +339,8 @@ TEST_F(BlitTest, ColorResolve) {
             srcRenderTarget, { 0, 0, kSrcTexWidth, kSrcTexHeight },
             SamplerMagFilter::NEAREST);
 
-    {
-        ImageExpectations expectations(api);
-
-        EXPECT_IMAGE(dstRenderTarget, expectations,
-                ScreenshotParams(kDstTexWidth, kDstTexHeight, "ColorResolve", 0xebfac2ef));
-
-        flushAndWait();
-    }
+    EXPECT_IMAGE(dstRenderTarget, getExpectations(),
+            ScreenshotParams(kDstTexWidth, kDstTexHeight, "ColorResolve", 0xebfac2ef));
 }
 
 TEST_F(BlitTest, Blit2DTextureArray) {
@@ -423,17 +405,11 @@ TEST_F(BlitTest, Blit2DTextureArray) {
     }
 
     {
-        ImageExpectations expectations(api);
-
-        {
-            RenderFrame frame(api);
-            EXPECT_IMAGE(dstRenderTarget, expectations,
-                    ScreenshotParams(kDstTexWidth, kDstTexHeight, "Blit2DTextureArray",
-                            0x8de7d55b));
-            api.commit(swapChain);
-        }
-
-        flushAndWait();
+        RenderFrame frame(api);
+        EXPECT_IMAGE(dstRenderTarget, getExpectations(),
+                ScreenshotParams(kDstTexWidth, kDstTexHeight, "Blit2DTextureArray",
+                        0x8de7d55b));
+        api.commit(swapChain);
     }
 }
 
@@ -503,18 +479,12 @@ TEST_F(BlitTest, BlitRegion) {
     }
 
     {
-        ImageExpectations expectations(api);
-
-        {
-            RenderFrame frame(api);
-            // TODO: for some reason, this test has very, very slight (as in one pixel) differences
-            // between OpenGL and Metal. So disable golden checking for now.
-            // EXPECT_IMAGE(dstRenderTarget, expectations, ScreenshotParams(kDstTexWidth,
-            //         kDstTexHeight, "BlitRegion", 0x74fa34ed));
-            api.commit(swapChain);
-        }
-
-        flushAndWait();
+        RenderFrame frame(api);
+        // TODO: for some reason, this test has very, very slight (as in one pixel) differences
+        // between OpenGL and Metal. So disable golden checking for now.
+        // EXPECT_IMAGE(dstRenderTarget, expectations, ScreenshotParams(kDstTexWidth,
+        //         kDstTexHeight, "BlitRegion", 0x74fa34ed));
+        api.commit(swapChain);
     }
 }
 
@@ -567,25 +537,19 @@ TEST_F(BlitTest, BlitRegionToSwapChain) {
     };
 
     {
-        ImageExpectations expectations(api);
-        {
-            {
-                RenderFrame frame(api);
+        RenderFrame frame(api);
 
-                api.blitDEPRECATED(TargetBufferFlags::COLOR0, dstRenderTarget,
-                        dstRect, srcRenderTargets[srcLevel],
-                        srcRect, SamplerMagFilter::LINEAR);
+        api.blitDEPRECATED(TargetBufferFlags::COLOR0, dstRenderTarget,
+                dstRect, srcRenderTargets[srcLevel],
+                srcRect, SamplerMagFilter::LINEAR);
 
-                api.commit(swapChain);
-            }
-
-            // TODO: for some reason, this test has been disabled. It needs to be tested on all
-            // machines.
-            // EXPECT_IMAGE(dstRenderTarget, expectations,
-            //         ScreenshotParams(kDstTexWidth, kDstTexHeight, "BlitRegionToSwapChain", 0x0));
-        }
-        flushAndWait();
+        api.commit(swapChain);
     }
+
+    // TODO: for some reason, this test has been disabled. It needs to be tested on all
+    // machines.
+    // EXPECT_IMAGE(dstRenderTarget, expectations,
+    //         ScreenshotParams(kDstTexWidth, kDstTexHeight, "BlitRegionToSwapChain", 0x0));
 }
 
 } // namespace test

filament/backend/test/test_BufferUpdates.cpp

@@ -16,6 +16,7 @@
 
 #include "BackendTest.h"
 
+#include "ImageExpectations.h"
 #include "Lifetimes.h"
 #include "Shader.h"
 #include "SharedShaders.h"
@@ -220,9 +221,9 @@ TEST_F(BufferUpdatesTest, BufferObjectUpdateWithOffset) {
     renderTriangle({{ DescriptorSetLayoutHandle{}, shader.getDescriptorSetLayout() }},
             renderTarget, swapChain, shader.getProgram(), params);
 
-    static const uint32_t expectedHash = 91322442;
-    readPixelsAndAssertHash(
-            "BufferObjectUpdateWithOffset", 512, 512, renderTarget, expectedHash, true);
+
+    EXPECT_IMAGE(renderTarget, getExpectations(),
+            ScreenshotParams(512, 512, "BufferObjectUpdateWithOffset", 91322442));
 
     api.flush();
     api.commit(swapChain);

filament/backend/test/test_Callbacks.cpp

@@ -17,6 +17,7 @@
 #include "BackendTest.h"
 
 #include "Lifetimes.h"
+#include "Skip.h"
 
 using namespace filament;
 using namespace filament::backend;
@@ -24,6 +25,8 @@ using namespace filament::backend;
 namespace test {
 
 TEST_F(BackendTest, FrameScheduledCallback) {
+    SKIP_IF(SkipEnvironment(OperatingSystem::APPLE, Backend::OPENGL));
+
     auto& api = getDriverApi();
     Cleanup cleanup(api);
 
@@ -81,6 +84,8 @@ TEST_F(BackendTest, FrameScheduledCallback) {
 }
 
 TEST_F(BackendTest, FrameCompletedCallback) {
+    SKIP_IF(SkipEnvironment(OperatingSystem::APPLE, Backend::OPENGL));
+
     auto& api = getDriverApi();
     Cleanup cleanup(api);
 

filament/backend/test/test_FeedbackLoops.cpp

@@ -71,8 +71,6 @@ void main() {
     fragColor = textureLod(test_tex, uv, params.sourceLevel);
 })";
 
-static uint32_t sPixelHashResult = 0;
-
 // Selecting a NPOT texture size seems to exacerbate the bug seen with Intel GPU's.
 // Note that Filament uses a higher precision format (R11F_G11F_B10F) but this does not seem
 // necessary to trigger the bug.
@@ -96,25 +94,6 @@ struct MaterialParams {
     float unused;
 };
 
-static void dumpScreenshot(DriverApi& dapi, Handle<HwRenderTarget> rt) {
-    const size_t size = kTexWidth * kTexHeight * 4;
-    void* buffer = calloc(1, size);
-    auto cb = [](void* buffer, size_t size, void* user) {
-        int w = kTexWidth, h = kTexHeight;
-        const uint32_t* texels = (uint32_t*) buffer;
-        sPixelHashResult = utils::hash::murmur3(texels, size / 4, 0);
-#ifndef FILAMENT_IOS
-        LinearImage image(w, h, 4);
-        image = toLinearWithAlpha<uint8_t>(w, h, w * 4, (uint8_t*) buffer);
-        std::ofstream pngstrm("feedback.png", std::ios::binary | std::ios::trunc);
-        ImageEncoder::encode(pngstrm, ImageEncoder::Format::PNG, image, "", "feedback.png");
-#endif
-        free(buffer);
-    };
-    PixelBufferDescriptor pb(buffer, size, PixelDataFormat::RGBA, PixelDataType::UBYTE, cb);
-    dapi.readPixels(rt, 0, 0, kTexWidth, kTexHeight, std::move(pb));
-}
-
 // TODO: This test needs work to get Metal and OpenGL to agree on results.
 // The problems are caused by both uploading and rendering into the same texture, since the OpenGL
 // backend's readPixels does not work correctly with textures that have image data uploaded.
@@ -259,7 +238,8 @@ TEST_F(BackendTest, FeedbackLoops) {
             // NOTE: Calling glReadPixels on any miplevel other than the base level
             // seems to be un-reliable on some GPU's.
             if (frame == kNumFrames - 1) {
-                dumpScreenshot(api, renderTargets[0]);
+                EXPECT_IMAGE(renderTargets[0], getExpectations(),
+                        ScreenshotParams(kTexWidth, kTexHeight, "FeedbackLoops", 0x70695aa1));
             }
 
             api.flush();
@@ -270,10 +250,6 @@ TEST_F(BackendTest, FeedbackLoops) {
             getDriver().purge();
         }
     }
-
-    const uint32_t expected = 0x70695aa1;
-    printf("Computed hash is 0x%8.8x, Expected 0x%8.8x\n", sPixelHashResult, expected);
-    EXPECT_TRUE(sPixelHashResult == expected);
 }
 
 } // namespace test

filament/backend/test/test_LoadImage.cpp

@@ -246,42 +246,42 @@ TEST_F(LoadImageTest, UpdateImage2D) {
     std::vector<TestCase> testCases;
 
     // Test basic upload.
-    testCases.emplace_back("RGBA, UBYTE -> RGBA8", PixelDataFormat::RGBA, PixelDataType::UBYTE, TextureFormat::RGBA8);
+    testCases.emplace_back("RGBA UBYTE to RGBA8", PixelDataFormat::RGBA, PixelDataType::UBYTE, TextureFormat::RGBA8);
 
     // Test format conversion.
     // TODO: Vulkan crashes with `Texture at colorAttachment[0] has usage (0x01) which doesn't specify MTLTextureUsageRenderTarget (0x04)'
-    testCases.emplace_back("RGBA, FLOAT -> RGBA16F", PixelDataFormat::RGBA, PixelDataType::FLOAT, TextureFormat::RGBA16F);
+    testCases.emplace_back("RGBA FLOAT to RGBA16F", PixelDataFormat::RGBA, PixelDataType::FLOAT, TextureFormat::RGBA16F);
 
     // Test texture formats not all backends support natively.
     // TODO: Vulkan crashes with "VK_FORMAT_R32G32B32_SFLOAT is not supported"
-    testCases.emplace_back("RGB, FLOAT -> RGB32F", PixelDataFormat::RGB, PixelDataType::FLOAT, TextureFormat::RGB32F);
-    testCases.emplace_back("RGB, FLOAT -> RGB16F", PixelDataFormat::RGB, PixelDataType::FLOAT, TextureFormat::RGB16F);
+    testCases.emplace_back("RGB FLOAT to RGB32F", PixelDataFormat::RGB, PixelDataType::FLOAT, TextureFormat::RGB32F);
+    testCases.emplace_back("RGB FLOAT to RGB16F", PixelDataFormat::RGB, PixelDataType::FLOAT, TextureFormat::RGB16F);
 
     // Test packed format uploads.
     // TODO: Vulkan crashes with "Texture at colorAttachment[0] has usage (0x01) which doesn't specify MTLTextureUsageRenderTarget (0x04)"
-    testCases.emplace_back("RGBA, UINT_2_10_10_10_REV -> RGB10_A2", PixelDataFormat::RGBA, PixelDataType::UINT_2_10_10_10_REV, TextureFormat::RGB10_A2);
-    testCases.emplace_back("RGB, UINT_10F_11F_11F_REV -> R11F_G11F_B10F", PixelDataFormat::RGB, PixelDataType::UINT_10F_11F_11F_REV, TextureFormat::R11F_G11F_B10F);
-    testCases.emplace_back("RGB, HALF -> R11F_G11F_B10F", PixelDataFormat::RGB, PixelDataType::HALF, TextureFormat::R11F_G11F_B10F);
+    testCases.emplace_back("RGBA UINT_2_10_10_10_REV to RGB10_A2", PixelDataFormat::RGBA, PixelDataType::UINT_2_10_10_10_REV, TextureFormat::RGB10_A2);
+    testCases.emplace_back("RGB UINT_10F_11F_11F_REV to R11F_G11F_B10F", PixelDataFormat::RGB, PixelDataType::UINT_10F_11F_11F_REV, TextureFormat::R11F_G11F_B10F);
+    testCases.emplace_back("RGB HALF to R11F_G11F_B10F", PixelDataFormat::RGB, PixelDataType::HALF, TextureFormat::R11F_G11F_B10F);
 
     // Test integer format uploads.
     // TODO: These cases fail on OpenGL and Vulkan.
     // TODO: These cases now also fail on Metal, but at some point previously worked.
-     testCases.emplace_back("RGB_INTEGER, UBYTE -> RGB8UI", PixelDataFormat::RGB_INTEGER, PixelDataType::UBYTE, TextureFormat::RGB8UI);
-     testCases.emplace_back("RGB_INTEGER, USHORT -> RGB16UI", PixelDataFormat::RGB_INTEGER, PixelDataType::USHORT, TextureFormat::RGB16UI);
-     testCases.emplace_back("RGB_INTEGER, INT -> RGB32I", PixelDataFormat::RGB_INTEGER, PixelDataType::INT, TextureFormat::RGB32I);
+     testCases.emplace_back("RGB_INTEGER UBYTE to RGB8UI", PixelDataFormat::RGB_INTEGER, PixelDataType::UBYTE, TextureFormat::RGB8UI);
+     testCases.emplace_back("RGB_INTEGER USHORT to RGB16UI", PixelDataFormat::RGB_INTEGER, PixelDataType::USHORT, TextureFormat::RGB16UI);
+     testCases.emplace_back("RGB_INTEGER INT to RGB32I", PixelDataFormat::RGB_INTEGER, PixelDataType::INT, TextureFormat::RGB32I);
 
     // Test uploads with buffer padding.
     // TODO: Vulkan crashes with "Assertion failed: (offset + size <= allocationSize)"
-    testCases.emplace_back("RGBA, UBYTE -> RGBA8 (with buffer padding)", PixelDataFormat::RGBA, PixelDataType::UBYTE, TextureFormat::RGBA8, 64u);
-    testCases.emplace_back("RGBA, FLOAT -> RGBA16F (with buffer padding)", PixelDataFormat::RGBA, PixelDataType::FLOAT, TextureFormat::RGBA16F, 64u);
-    testCases.emplace_back("RGB, FLOAT -> RGB32F (with buffer padding)", PixelDataFormat::RGB, PixelDataType::FLOAT, TextureFormat::RGB32F, 64u);
+    testCases.emplace_back("RGBA UBYTE to RGBA8 (with buffer padding)", PixelDataFormat::RGBA, PixelDataType::UBYTE, TextureFormat::RGBA8, 64u);
+    testCases.emplace_back("RGBA FLOAT to RGBA16F (with buffer padding)", PixelDataFormat::RGBA, PixelDataType::FLOAT, TextureFormat::RGBA16F, 64u);
+    testCases.emplace_back("RGB FLOAT to RGB32F (with buffer padding)", PixelDataFormat::RGB, PixelDataType::FLOAT, TextureFormat::RGB32F, 64u);
 
     // Upload subregions separately.
     // TODO: Vulkan crashes with "Offsets not yet supported"
-    testCases.emplace_back("RGBA, UBYTE -> RGBA8 (subregions)", PixelDataFormat::RGBA, PixelDataType::UBYTE, TextureFormat::RGBA8, 0u, true);
-    testCases.emplace_back("RGBA, FLOAT -> RGBA16F (subregions)", PixelDataFormat::RGBA, PixelDataType::FLOAT, TextureFormat::RGBA16F, 0u, true);
-    testCases.emplace_back("RGBA, UBYTE -> RGBA8 (subregions, buffer padding)", PixelDataFormat::RGBA, PixelDataType::UBYTE, TextureFormat::RGBA8, 64u, true);
-    testCases.emplace_back("RGB, FLOAT -> RGB32F (subregions, buffer padding)", PixelDataFormat::RGB, PixelDataType::FLOAT, TextureFormat::RGB32F, 64u, true);
+    testCases.emplace_back("RGBA UBYTE to RGBA8 (subregions)", PixelDataFormat::RGBA, PixelDataType::UBYTE, TextureFormat::RGBA8, 0u, true);
+    testCases.emplace_back("RGBA FLOAT to RGBA16F (subregions)", PixelDataFormat::RGBA, PixelDataType::FLOAT, TextureFormat::RGBA16F, 0u, true);
+    testCases.emplace_back("RGBA UBYTE to RGBA8 (subregions and buffer padding)", PixelDataFormat::RGBA, PixelDataType::UBYTE, TextureFormat::RGBA8, 64u, true);
+    testCases.emplace_back("RGB FLOAT to RGB32F (subregions and buffer padding)", PixelDataFormat::RGB, PixelDataType::FLOAT, TextureFormat::RGB32F, 64u, true);
 
     auto& api = getDriverApi();
 
@@ -339,16 +339,14 @@ TEST_F(LoadImageTest, UpdateImage2D) {
         renderTriangle({{ DescriptorSetLayoutHandle{}, shader.getDescriptorSetLayout() }},
                 defaultRenderTarget, swapChain, shader.getProgram());
 
-        readPixelsAndAssertHash(t.name, 512, 512, defaultRenderTarget, expectedHash);
+        EXPECT_IMAGE(defaultRenderTarget, getExpectations(),
+                ScreenshotParams(512, 512, t.name, expectedHash));
 
         api.commit(swapChain);
         api.endFrame(0);
     }
 
-    api.finish();
     api.stopCapture();
-
-    flushAndWait();
 }
 
 TEST_F(LoadImageTest, UpdateImageSRGB) {
@@ -372,7 +370,7 @@ TEST_F(LoadImageTest, UpdateImageSRGB) {
             getSamplerTypeName(textureFormat), fragmentTemplate);
     Shader shader(api, cleanup, ShaderConfig{
         .vertexShader = mVertexShader, .fragmentShader = fragment, .uniforms = {{
-            "text_tex", DescriptorType::SAMPLER, samplerInfo
+            "test_tex", DescriptorType::SAMPLER, samplerInfo
     }}});
 
     // Create a texture.
@@ -416,15 +414,12 @@ TEST_F(LoadImageTest, UpdateImageSRGB) {
     renderTriangle({{ DescriptorSetLayoutHandle{}, shader.getDescriptorSetLayout() }},
             defaultRenderTarget, swapChain, shader.getProgram());
 
-    static const uint32_t expectedHash = 359858623;
-    readPixelsAndAssertHash("UpdateImageSRGB", 512, 512, defaultRenderTarget, expectedHash);
+    EXPECT_IMAGE(defaultRenderTarget, getExpectations(),
+            ScreenshotParams(512, 512, "UpdateImageSRGB", 359858623));
 
-    api.flush();
     api.commit(swapChain);
     api.endFrame(0);
 
-    // This ensures all driver commands have finished before exiting the test.
-    api.finish();
     api.stopCapture();
 }
 
@@ -478,15 +473,12 @@ TEST_F(LoadImageTest, UpdateImageMipLevel) {
     renderTriangle({{ DescriptorSetLayoutHandle{}, shader.getDescriptorSetLayout() }},
             defaultRenderTarget, swapChain, shader.getProgram());
 
-    static const uint32_t expectedHash = 3644679986;
-    readPixelsAndAssertHash("UpdateImageMipLevel", 512, 512, defaultRenderTarget, expectedHash);
+    EXPECT_IMAGE(defaultRenderTarget, getExpectations(),
+            ScreenshotParams(512, 512, "UpdateImageMipLevel", 3644679986));
 
-    api.flush();
     api.commit(swapChain);
     api.endFrame(0);
 
-    // This ensures all driver commands have finished before exiting the test.
-    api.finish();
     api.stopCapture();
 }
 
@@ -538,29 +530,24 @@ TEST_F(LoadImageTest, UpdateImage3D) {
 
     api.update3DImage(texture, 0, 0, 0, 0, 512, 512, 4, std::move(descriptor));
 
-    api.beginFrame(0, 0, 0);
+    {
+        RenderFrame frame(api);
 
-    // Update samplers.
-    DescriptorSetHandle  descriptorSet = shader.createDescriptorSet(api);
-    api.updateDescriptorSetTexture(descriptorSet, 0, texture, {
-            .filterMag = SamplerMagFilter::LINEAR,
-            .filterMin = SamplerMinFilter::LINEAR_MIPMAP_NEAREST
-    });
+        // Update samplers.
+        DescriptorSetHandle descriptorSet = shader.createDescriptorSet(api);
+        api.updateDescriptorSetTexture(descriptorSet, 0, texture,
+                { .filterMag = SamplerMagFilter::LINEAR,
+                    .filterMin = SamplerMinFilter::LINEAR_MIPMAP_NEAREST });
 
-    api.bindDescriptorSet(descriptorSet, 1, {});
+        api.bindDescriptorSet(descriptorSet, 1, {});
 
-    renderTriangle({{ DescriptorSetLayoutHandle{}, shader.getDescriptorSetLayout() }},
-            defaultRenderTarget, swapChain, shader.getProgram());
+        renderTriangle({ { DescriptorSetLayoutHandle{}, shader.getDescriptorSetLayout() } },
+                defaultRenderTarget, swapChain, shader.getProgram());
 
-    static const uint32_t expectedHash = 3644679986;
-    readPixelsAndAssertHash("UpdateImage3D", 512, 512, defaultRenderTarget, expectedHash);
+        EXPECT_IMAGE(defaultRenderTarget, getExpectations(),
+                ScreenshotParams(512, 512, "UpdateImage3D", 3644679986));
+    }
 
-    api.flush();
-    api.commit(swapChain);
-    api.endFrame(0);
-
-    // This ensures all driver commands have finished before exiting the test.
-    api.finish();
     api.stopCapture();
 }
 

filament/backend/test/test_PushConstants.cpp

@@ -16,8 +16,10 @@
 
 #include "BackendTest.h"
 
+#include "ImageExpectations.h"
 #include "Lifetimes.h"
 #include "ShaderGenerator.h"
+#include "Skip.h"
 #include "TrianglePrimitive.h"
 
 #include <utils/Hash.h>
@@ -78,6 +80,8 @@ void main() {
 })";
 
 TEST_F(BackendTest, PushConstants) {
+    SKIP_IF(SkipEnvironment(OperatingSystem::APPLE, Backend::OPENGL));
+
     auto& api = getDriverApi();
 
     api.startCapture(0);
@@ -148,19 +152,14 @@ TEST_F(BackendTest, PushConstants) {
 
         api.endRenderPass();
 
-        readPixelsAndAssertHash("pushConstants", 512, 512, renderTarget, 1957275826, true);
+        EXPECT_IMAGE(renderTarget, getExpectations(),
+                ScreenshotParams(512, 512, "pushConstants", 1957275826));
 
         api.commit(swapChain);
         api.endFrame(0);
     }
 
     api.stopCapture(0);
-
-    // Wait for the ReadPixels result to come back.
-    api.finish();
-
-    executeCommands();
-    getDriver().purge();
 }
 
 } // namespace test

filament/backend/test/test_RenderExternalImage.cpp

@@ -16,6 +16,7 @@
 
 #include "BackendTest.h"
 
+#include "ImageExpectations.h"
 #include "Lifetimes.h"
 #include "Shader.h"
 #include "SharedShaders.h"
@@ -200,17 +201,16 @@ TEST_F(BackendTest, RenderExternalImage) {
     api.draw(state, triangle.getRenderPrimitive(), 0, 3, 1);
     api.endRenderPass();
 
-    readPixelsAndAssertHash("RenderExternalImage", 512, 512, defaultRenderTarget, 267229901, true);
-
     api.flush();
     api.commit(swapChain);
     api.endFrame(0);
+    EXPECT_IMAGE(defaultRenderTarget, getExpectations(),
+            ScreenshotParams(512, 512, "RenderExternalImage", 267229901));
 
     api.stopCapture(0);
-
     api.finish();
+    flushAndWait();
 
-    executeCommands();
 }
 
 } // namespace test

filament/backend/test/test_Scissor.cpp

@@ -16,6 +16,7 @@
 
 #include "BackendTest.h"
 
+#include "ImageExpectations.h"
 #include "Lifetimes.h"
 #include "Shader.h"
 #include "SharedShaders.h"
@@ -130,20 +131,14 @@ TEST_F(BackendTest, ScissorViewportRegion) {
         api.draw(ps, triangle.getRenderPrimitive(), 0, 3, 1);
         api.endRenderPass();
 
-        readPixelsAndAssertHash("scissor", kSrcTexWidth >> 1, kSrcTexHeight >> 1, fullRenderTarget,
-                0xAB3D1C53, true);
+        EXPECT_IMAGE(fullRenderTarget, getExpectations(),
+                ScreenshotParams(kSrcTexWidth >> 1, kSrcTexHeight >> 1, "scissor", 0xAB3D1C53));
 
         api.commit(swapChain);
         api.endFrame(0);
 
         api.stopCapture(0);
     }
-
-    // Wait for the ReadPixels result to come back.
-    api.finish();
-
-    executeCommands();
-    getDriver().purge();
 }
 
 // Verify that a negative Viewport origin works with scissor.
@@ -226,20 +221,14 @@ TEST_F(BackendTest, ScissorViewportEdgeCases) {
         api.draw(ps, triangle.getRenderPrimitive(), 0, 3, 1);
         api.endRenderPass();
 
-        readPixelsAndAssertHash(
-                "ScissorViewportEdgeCases", 512, 512, renderTarget, 0x6BF00F31, true);
+        EXPECT_IMAGE(renderTarget, getExpectations(),
+                ScreenshotParams(512, 512, "ScissorViewportEdgeCases", 0x6BF00F31));
 
         api.commit(swapChain);
         api.endFrame(0);
 
         api.stopCapture(0);
     }
-
-    // Wait for the ReadPixels result to come back.
-    api.finish();
-
-    executeCommands();
-    getDriver().purge();
 }
 
 } // namespace test

filament/backend/test/test_StencilBuffer.cpp

@@ -16,6 +16,7 @@
 
 #include "BackendTest.h"
 
+#include "ImageExpectations.h"
 #include "Lifetimes.h"
 #include "Shader.h"
 #include "SharedShaders.h"
@@ -129,7 +130,8 @@ TEST_F(BasicStencilBufferTest, StencilBuffer) {
 
     RunTest(renderTarget);
 
-    readPixelsAndAssertHash("StencilBuffer", 512, 512, renderTarget, 0x3B1AEF0F, true);
+    EXPECT_IMAGE(renderTarget, getExpectations(),
+            ScreenshotParams(512, 512, "StencilBuffer", 0x3B1AEF0F));
 
     flushAndWait();
     getDriver().purge();
@@ -151,7 +153,8 @@ TEST_F(BasicStencilBufferTest, DepthAndStencilBuffer) {
 
     RunTest(renderTarget);
 
-    readPixelsAndAssertHash("DepthAndStencilBuffer", 512, 512, renderTarget, 0x3B1AEF0F, true);
+    EXPECT_IMAGE(renderTarget, getExpectations(),
+            ScreenshotParams(512, 512, "DepthAndStencilBuffer", 0x3B1AEF0F));
 
     flushAndWait();
     getDriver().purge();
@@ -233,7 +236,8 @@ TEST_F(BasicStencilBufferTest, StencilBufferMSAA) {
     api.stopCapture(0);
     api.endFrame(0);
 
-    readPixelsAndAssertHash("StencilBufferAutoResolve", 512, 512, renderTarget1, 0x6CEFAC8F, true);
+    EXPECT_IMAGE(renderTarget1, getExpectations(),
+            ScreenshotParams(512, 512, "StencilBufferAutoResolve", 0x6CEFAC8F));
 
     flushAndWait();
     getDriver().purge();

filament/include/filament/Engine.h

@@ -317,15 +317,6 @@ public:
          */
         size_t metalUploadBufferSizeBytes = 512 * 1024;
 
-        /**
-         * The action to take if a Drawable cannot be acquired.
-         *
-         * Each frame rendered requires a CAMetalDrawable texture, which is
-         * presented on-screen at the completion of each frame. These are
-         * limited and provided round-robin style by the system.
-         */
-        bool metalDisablePanicOnDrawableFailure = false;
-
         /**
          * Set to `true` to forcibly disable parallel shader compilation in the backend.
          * Currently only honored by the GL and Metal backends.

filament/src/details/Engine.cpp

@@ -138,7 +138,6 @@ Engine* FEngine::create(Builder const& builder) {
                 .forceGLES2Context = instance->getConfig().forceGLES2Context,
                 .stereoscopicType = instance->getConfig().stereoscopicType,
                 .assertNativeWindowIsValid = instance->features.backend.opengl.assert_native_window_is_valid,
-                .metalDisablePanicOnDrawableFailure = instance->getConfig().metalDisablePanicOnDrawableFailure,
         };
         instance->mDriver = platform->createDriver(sharedContext, driverConfig);
 
@@ -734,7 +733,6 @@ int FEngine::loop() {
             .forceGLES2Context = mConfig.forceGLES2Context,
             .stereoscopicType =  mConfig.stereoscopicType,
             .assertNativeWindowIsValid = features.backend.opengl.assert_native_window_is_valid,
-            .metalDisablePanicOnDrawableFailure = mConfig.metalDisablePanicOnDrawableFailure,
     };
     mDriver = mPlatform->createDriver(mSharedGLContext, driverConfig);
 

filament/src/details/MaterialInstance.cpp

@@ -269,12 +269,14 @@ void FMaterialInstance::setParameterImpl(std::string_view const name,
     if (texture && texture->textureHandleCanMutate()) {
         mTextureParameters[binding] = { texture, sampler.getSamplerParams() };
     } else {
+        // Ensure to erase the binding from mTextureParameters since it will not
+        // be updated.
+        mTextureParameters.erase(binding);
+
         Handle<HwTexture> handle{};
         if (texture) {
             handle = texture->getHwHandleForSampling();
             assert_invariant(handle == texture->getHwHandle());
-        } else {
-            mTextureParameters.erase(binding);
         }
         mDescriptorSet.setSampler(binding, handle, sampler.getSamplerParams());
     }

ios/CocoaPods/Filament.podspec

@@ -1,12 +1,12 @@
 Pod::Spec.new do |spec|
   spec.name = "Filament"
-  spec.version = "1.59.2"
+  spec.version = "1.59.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.59.2/filament-v1.59.2-ios.tgz" }
+  spec.source = { :http => "https://github.com/google/filament/releases/download/v1.59.3/filament-v1.59.3-ios.tgz" }
 
   # Fix linking error with Xcode 12; we do not yet support the simulator on Apple silicon.
   spec.pod_target_xcconfig = {

libs/gltfio/src/AssetLoader.cpp

@@ -50,6 +50,8 @@
 #include <utils/Log.h>
 #include <utils/Panic.h>
 #include <utils/NameComponentManager.h>
+
+#define SYSTRACE_TAG SYSTRACE_TAG_GLTFIO
 #include <utils/Systrace.h>
 
 #include <tsl/robin_map.h>

libs/gltfio/src/ResourceLoader.cpp

@@ -37,7 +37,10 @@
 #include <utils/compiler.h>
 #include <utils/JobSystem.h>
 #include <utils/Log.h>
+
+#define SYSTRACE_TAG SYSTRACE_TAG_GLTFIO
 #include <utils/Systrace.h>
+
 #include <utils/Path.h>
 
 #include <cgltf.h>

libs/gltfio/src/Utility.cpp

@@ -21,6 +21,8 @@
 #include "GltfEnums.h"
 
 #include <utils/Log.h>
+
+#define SYSTRACE_TAG SYSTRACE_TAG_GLTFIO
 #include <utils/Systrace.h>
 
 #define CGLTF_IMPLEMENTATION

libs/utils/CMakeLists.txt

@@ -112,6 +112,7 @@ if (ANDROID)
     target_link_libraries(${TARGET} PUBLIC log)
     target_link_libraries(${TARGET} PRIVATE dl)
     target_link_libraries(${TARGET} PUBLIC android)
+    target_link_libraries(${TARGET} PUBLIC perfetto)
 endif()
 
 if (WIN32)

libs/utils/include/utils/Systrace.h

@@ -17,24 +17,23 @@
 #ifndef TNT_UTILS_SYSTRACE_H
 #define TNT_UTILS_SYSTRACE_H
 
-
-#define SYSTRACE_TAG_NEVER          (0)
-#define SYSTRACE_TAG_ALWAYS         (1<<0)
-#define SYSTRACE_TAG_FILAMENT       (1<<1)  // don't change, used in makefiles
-#define SYSTRACE_TAG_JOBSYSTEM      (1<<2)
+#define SYSTRACE_TAG_DISABLED       (0)
+#define SYSTRACE_TAG_FILAMENT       (2) // don't change used in makefiles
+#define SYSTRACE_TAG_JOBSYSTEM      (3)
+#define SYSTRACE_TAG_GLTFIO         (4)
 
 /*
- * The SYSTRACE_ macros use SYSTRACE_TAG as a the TAG, which should be defined
- * before this file is included. If not, the SYSTRACE_TAG_ALWAYS tag will be used.
+ * The SYSTRACE_ macros use SYSTRACE_TAG as a category, which must be defined
+ * before this file is included.
  */
 
 #ifndef SYSTRACE_TAG
-#define SYSTRACE_TAG (SYSTRACE_TAG_ALWAYS)
+#   error SYSTRACE_TAG must be set to SYSTRACE_TAG_{DISABLED|FILAMENT|JOBSYSTEM}
 #endif
 
 // Systrace on Apple platforms is fragile and adds overhead, should only be enabled in dev builds.
 #ifndef FILAMENT_APPLE_SYSTRACE
-#define FILAMENT_APPLE_SYSTRACE 0
+#   define FILAMENT_APPLE_SYSTRACE 0
 #endif
 
 #if defined(__ANDROID__)
@@ -44,7 +43,6 @@
 #else
 
 #define SYSTRACE_ENABLE()
-#define SYSTRACE_DISABLE()
 #define SYSTRACE_CONTEXT()
 #define SYSTRACE_NAME(name)
 #define SYSTRACE_FRAME_ID(frame)
@@ -56,6 +54,6 @@
 #define SYSTRACE_VALUE32(name, val)
 #define SYSTRACE_VALUE64(name, val)
 
-#endif // ANDROID
+#endif
 
 #endif // TNT_UTILS_SYSTRACE_H

libs/utils/include/utils/android/Systrace.h

@@ -17,226 +17,75 @@
 #ifndef TNT_UTILS_ANDROID_SYSTRACE_H
 #define TNT_UTILS_ANDROID_SYSTRACE_H
 
-#include <atomic>
+#include <perfetto/perfetto.h>
 
 #include <stdint.h>
-#include <stdio.h>
-#include <unistd.h>
 
-#include <utils/compiler.h>
+PERFETTO_DEFINE_CATEGORIES_IN_NAMESPACE(systrace,
+        perfetto::Category("filament"),
+        perfetto::Category("jobsystem"),
+        perfetto::Category("gltfio"));
 
-// enable tracing
-#define SYSTRACE_ENABLE() ::utils::details::Systrace::enable(SYSTRACE_TAG)
+PERFETTO_USE_CATEGORIES_FROM_NAMESPACE(systrace);
 
-// disable tracing
-#define SYSTRACE_DISABLE() ::utils::details::Systrace::disable(SYSTRACE_TAG)
+#if SYSTRACE_TAG == SYSTRACE_TAG_FILAMENT
+#   define UTILS_PERFETTO_CATEGORY "filament"
+#elif SYSTRACE_TAG == SYSTRACE_TAG_JOBSYSTEM
+#   define UTILS_PERFETTO_CATEGORY "jobsystem"
+#elif SYSTRACE_TAG == SYSTRACE_TAG_GLTFIO
+#   define UTILS_PERFETTO_CATEGORY "gltfio"
+#endif
 
+#if SYSTRACE_TAG == SYSTRACE_TAG_DISABLED
 
-/**
- * Creates a Systrace context in the current scope. needed for calling all other systrace
- * commands below.
- */
-#define SYSTRACE_CONTEXT() ::utils::details::Systrace ___trctx(SYSTRACE_TAG)
+#define SYSTRACE_ENABLE()
+#define SYSTRACE_CONTEXT()
+#define SYSTRACE_NAME(name)
+#define SYSTRACE_FRAME_ID(frame)
+#define SYSTRACE_NAME_BEGIN(name)
+#define SYSTRACE_NAME_END()
+#define SYSTRACE_CALL()
+#define SYSTRACE_ASYNC_BEGIN(name, cookie)
+#define SYSTRACE_ASYNC_END(name, cookie)
+#define SYSTRACE_VALUE32(name, val)
+#define SYSTRACE_VALUE64(name, val)
 
+#else
 
-// SYSTRACE_NAME traces the beginning and end of the current scope.  To trace
-// the correct start and end times this macro should be declared first in the
-// scope body.
-// It also automatically creates a Systrace context
-#define SYSTRACE_NAME(name) ::utils::details::ScopedTrace ___tracer(SYSTRACE_TAG, name)
+#define SYSTRACE_ENABLE()
+#define SYSTRACE_CONTEXT()
 
-// Denotes that a new frame has started processing.
-#define SYSTRACE_FRAME_ID(frame) \
-    { /* scope for frame id trace */ \
-        char buf[64]; \
-        snprintf(buf, 64, "frame %u", frame); \
-        SYSTRACE_NAME(buf); \
-    }
+#define SYSTRACE_CALL() \
+    auto constexpr FILAMENT_SYSTRACE_FUNCTION = perfetto::StaticString(__FUNCTION__); \
+    TRACE_EVENT(UTILS_PERFETTO_CATEGORY, FILAMENT_SYSTRACE_FUNCTION)
 
-// SYSTRACE_CALL is an SYSTRACE_NAME that uses the current function name.
-#define SYSTRACE_CALL() SYSTRACE_NAME(__FUNCTION__)
+#define SYSTRACE_NAME(name) TRACE_EVENT(UTILS_PERFETTO_CATEGORY, nullptr,   \
+        [&](perfetto::EventContext ctx) {                                   \
+            ctx.event()->set_name(name);                                    \
+        })
 
-#define SYSTRACE_NAME_BEGIN(name) \
-        ___trctx.traceBegin(SYSTRACE_TAG, name)
+#define SYSTRACE_NAME_BEGIN(name) TRACE_EVENT_BEGIN(UTILS_PERFETTO_CATEGORY, nullptr,   \
+        [&](perfetto::EventContext ctx) {                                               \
+            ctx.event()->set_name(name);                                                \
+        })
 
-#define SYSTRACE_NAME_END() \
-        ___trctx.traceEnd(SYSTRACE_TAG)
+#define SYSTRACE_NAME_END() TRACE_EVENT_END(UTILS_PERFETTO_CATEGORY)
 
-
-/**
- * Trace the beginning of an asynchronous event. Unlike ATRACE_BEGIN/ATRACE_END
- * contexts, asynchronous events do not need to be nested. The name describes
- * the event, and the cookie provides a unique identifier for distinguishing
- * simultaneous events. The name and cookie used to begin an event must be
- * used to end it.
- */
 #define SYSTRACE_ASYNC_BEGIN(name, cookie) \
-        ___trctx.asyncBegin(SYSTRACE_TAG, name, cookie)
+        TRACE_EVENT_BEGIN(UTILS_PERFETTO_CATEGORY, name, perfetto::Track(cookie))
 
-/**
- * Trace the end of an asynchronous event.
- * This should have a corresponding SYSTRACE_ASYNC_BEGIN.
- */
 #define SYSTRACE_ASYNC_END(name, cookie) \
-        ___trctx.asyncEnd(SYSTRACE_TAG, name, cookie)
+        TRACE_EVENT_END(UTILS_PERFETTO_CATEGORY, perfetto::Track(cookie))
+
+#define SYSTRACE_FRAME_ID(frame) \
+    TRACE_EVENT_INSTANT(UTILS_PERFETTO_CATEGORY, "frame", "id", frame)
 
-/**
- * Traces an integer counter value.  name is used to identify the counter.
- * This can be used to track how a value changes over time.
- */
 #define SYSTRACE_VALUE32(name, val) \
-        ___trctx.value(SYSTRACE_TAG, name, int32_t(val))
+    TRACE_COUNTER(UTILS_PERFETTO_CATEGORY, name, val)
 
 #define SYSTRACE_VALUE64(name, val) \
-        ___trctx.value(SYSTRACE_TAG, name, int64_t(val))
+    TRACE_COUNTER(UTILS_PERFETTO_CATEGORY, name, val)
 
-// ------------------------------------------------------------------------------------------------
-// No user serviceable code below...
-// ------------------------------------------------------------------------------------------------
-
-namespace utils {
-namespace details {
-
-class UTILS_PUBLIC Systrace {
-   public:
-
-    enum tags {
-        NEVER       = SYSTRACE_TAG_NEVER,
-        ALWAYS      = SYSTRACE_TAG_ALWAYS,
-        FILAMENT    = SYSTRACE_TAG_FILAMENT,
-        JOBSYSTEM   = SYSTRACE_TAG_JOBSYSTEM
-        // we could define more TAGS here, as we need them.
-    };
-
-    explicit Systrace(uint32_t tag) noexcept {
-        if (tag) init(tag);
-    }
-
-    static void enable(uint32_t tags) noexcept;
-    static void disable(uint32_t tags) noexcept;
-
-
-    inline void traceBegin(uint32_t tag, const char* name) noexcept {
-        if (tag && UTILS_UNLIKELY(mIsTracingEnabled)) {
-            beginSection(this, name);
-        }
-    }
-
-    inline void traceEnd(uint32_t tag) noexcept {
-        if (tag && UTILS_UNLIKELY(mIsTracingEnabled)) {
-            endSection(this);
-        }
-    }
-
-    inline void asyncBegin(uint32_t tag, const char* name, int32_t cookie) noexcept {
-        if (tag && UTILS_UNLIKELY(mIsTracingEnabled)) {
-            beginAsyncSection(this, name, cookie);
-        }
-    }
-
-    inline void asyncEnd(uint32_t tag, const char* name, int32_t cookie) noexcept {
-        if (tag && UTILS_UNLIKELY(mIsTracingEnabled)) {
-            endAsyncSection(this, name, cookie);
-        }
-    }
-
-    inline void value(uint32_t tag, const char* name, int32_t value) noexcept {
-        if (tag && UTILS_UNLIKELY(mIsTracingEnabled)) {
-            setCounter(this, name, value);
-        }
-    }
-
-    inline void value(uint32_t tag, const char* name, int64_t value) noexcept {
-        if (tag && UTILS_UNLIKELY(mIsTracingEnabled)) {
-            setCounter(this, name, value);
-        }
-    }
-
-   private:
-    friend class ScopedTrace;
-
-    // whether tracing is supported at all by the platform
-
-    using ATrace_isEnabled_t          = bool (*)();
-    using ATrace_beginSection_t       = void (*)(const char* sectionName);
-    using ATrace_endSection_t         = void (*)();
-    using ATrace_beginAsyncSection_t  = void (*)(const char* sectionName, int32_t cookie);
-    using ATrace_endAsyncSection_t    = void (*)(const char* sectionName, int32_t cookie);
-    using ATrace_setCounter_t         = void (*)(const char* counterName, int64_t counterValue);
-
-    struct GlobalState {
-        bool isTracingAvailable;
-        std::atomic<uint32_t> isTracingEnabled;
-        int markerFd;
-
-        ATrace_isEnabled_t ATrace_isEnabled;
-        ATrace_beginSection_t ATrace_beginSection;
-        ATrace_endSection_t ATrace_endSection;
-        ATrace_beginAsyncSection_t ATrace_beginAsyncSection;
-        ATrace_endAsyncSection_t ATrace_endAsyncSection;
-        ATrace_setCounter_t ATrace_setCounter;
-
-        void (*beginSection)(Systrace* that, const char* name);
-        void (*endSection)(Systrace* that);
-        void (*beginAsyncSection)(Systrace* that, const char* name, int32_t cookie);
-        void (*endAsyncSection)(Systrace* that, const char* name, int32_t cookie);
-        void (*setCounter)(Systrace* that, const char* name, int64_t value);
-    };
-
-    static GlobalState sGlobalState;
-
-
-    // per-instance versions for better performance
-    ATrace_isEnabled_t ATrace_isEnabled;
-    ATrace_beginSection_t ATrace_beginSection;
-    ATrace_endSection_t ATrace_endSection;
-    ATrace_beginAsyncSection_t ATrace_beginAsyncSection;
-    ATrace_endAsyncSection_t ATrace_endAsyncSection;
-    ATrace_setCounter_t ATrace_setCounter;
-
-    void (*beginSection)(Systrace* that, const char* name);
-    void (*endSection)(Systrace* that);
-    void (*beginAsyncSection)(Systrace* that, const char* name, int32_t cookie);
-    void (*endAsyncSection)(Systrace* that, const char* name, int32_t cookie);
-    void (*setCounter)(Systrace* that, const char* name, int64_t value);
-
-    void init(uint32_t tag) noexcept;
-
-    // cached values for faster access, no need to be initialized
-    bool mIsTracingEnabled;
-    int mMarkerFd = -1;
-    pid_t mPid;
-
-    static void setup() noexcept;
-    static void init_once() noexcept;
-    static bool isTracingEnabled(uint32_t tag) noexcept;
-
-    static void begin_body(int fd, int pid, const char* name) noexcept;
-    static void end_body(int fd, int pid) noexcept;
-    static void async_begin_body(int fd, int pid, const char* name, int32_t cookie) noexcept;
-    static void async_end_body(int fd, int pid, const char* name, int32_t cookie) noexcept;
-    static void int64_body(int fd, int pid, const char* name, int64_t value) noexcept;
-};
-
-// ------------------------------------------------------------------------------------------------
-
-class UTILS_PUBLIC ScopedTrace {
-public:
-    // we don't inline this because it's relatively heavy due to a global check
-    ScopedTrace(uint32_t tag, const char* name) noexcept: mTrace(tag), mTag(tag) {
-        mTrace.traceBegin(tag, name);
-    }
-
-    inline ~ScopedTrace() noexcept {
-        mTrace.traceEnd(mTag);
-    }
-
-private:
-    Systrace mTrace;
-    const uint32_t mTag;
-};
-
-} // namespace details
-} // namespace utils
+#endif // SYSTRACE_TAG == SYSTRACE_TAG_DISABLED
 
 #endif // TNT_UTILS_ANDROID_SYSTRACE_H

libs/utils/include/utils/darwin/Systrace.h

@@ -29,13 +29,25 @@
 #include <utils/compiler.h>
 #include <stack>
 
+#if SYSTRACE_TAG == SYSTRACE_TAG_DISABLED
+
+#define SYSTRACE_ENABLE()
+#define SYSTRACE_CONTEXT()
+#define SYSTRACE_NAME(name)
+#define SYSTRACE_FRAME_ID(frame)
+#define SYSTRACE_NAME_BEGIN(name)
+#define SYSTRACE_NAME_END()
+#define SYSTRACE_CALL()
+#define SYSTRACE_ASYNC_BEGIN(name, cookie)
+#define SYSTRACE_ASYNC_END(name, cookie)
+#define SYSTRACE_VALUE32(name, val)
+#define SYSTRACE_VALUE64(name, val)
+
+#else
+
 // enable tracing
 #define SYSTRACE_ENABLE() ::utils::details::Systrace::enable(SYSTRACE_TAG)
 
-// disable tracing
-#define SYSTRACE_DISABLE() ::utils::details::Systrace::disable(SYSTRACE_TAG)
-
-
 /**
  * Creates a Systrace context in the current scope. needed for calling all other systrace
  * commands below.
@@ -93,6 +105,8 @@ extern thread_local std::stack<const char*> ___tracerSections;
 #define SYSTRACE_VALUE64(name, val) \
         ___tracer.value(SYSTRACE_TAG, name, int64_t(val))
 
+#endif // SYSTRACE_TAG == SYSTRACE_TAG_DISABLED
+
 // ------------------------------------------------------------------------------------------------
 // No user serviceable code below...
 // ------------------------------------------------------------------------------------------------
@@ -118,50 +132,40 @@ namespace utils {
 namespace details {
 
 class Systrace {
-   public:
-
-    enum tags {
-        NEVER       = SYSTRACE_TAG_NEVER,
-        ALWAYS      = SYSTRACE_TAG_ALWAYS,
-        FILAMENT    = SYSTRACE_TAG_FILAMENT,
-        JOBSYSTEM   = SYSTRACE_TAG_JOBSYSTEM
-        // we could define more TAGS here, as we need them.
-    };
-
+public:
     explicit Systrace(uint32_t tag) noexcept {
         if (tag) init(tag);
     }
 
-    static void enable(uint32_t tags) noexcept;
-    static void disable(uint32_t tags) noexcept;
+    static void enable(uint32_t tag) noexcept;
 
-    inline void traceBegin(uint32_t tag, const char* name) noexcept {
+    void traceBegin(uint32_t tag, const char* name) noexcept {
         if (tag && UTILS_UNLIKELY(mIsTracingEnabled)) {
             APPLE_SIGNPOST_EMIT(sGlobalState.systraceLog, OS_SIGNPOST_INTERVAL_BEGIN,
                     OS_SIGNPOST_ID_EXCLUSIVE, name, name)
         }
     }
 
-    inline void traceEnd(uint32_t tag, const char* name) noexcept {
+    void traceEnd(uint32_t tag, const char* name) noexcept {
         if (tag && UTILS_UNLIKELY(mIsTracingEnabled)) {
             APPLE_SIGNPOST_EMIT(sGlobalState.systraceLog, OS_SIGNPOST_INTERVAL_END,
                     OS_SIGNPOST_ID_EXCLUSIVE, name, "")
         }
     }
 
-    inline void asyncBegin(uint32_t tag, const char* name, int32_t cookie) noexcept {
+    void asyncBegin(uint32_t tag, const char* name, int32_t cookie) noexcept {
         if (tag && UTILS_UNLIKELY(mIsTracingEnabled)) {
             // TODO
         }
     }
 
-    inline void asyncEnd(uint32_t tag, const char* name, int32_t cookie) noexcept {
+    void asyncEnd(uint32_t tag, const char* name, int32_t cookie) noexcept {
         if (tag && UTILS_UNLIKELY(mIsTracingEnabled)) {
             // TODO
         }
     }
 
-    inline void value(uint32_t tag, const char* name, int32_t value) noexcept {
+    void value(uint32_t tag, const char* name, int32_t value) noexcept {
         if (tag && UTILS_UNLIKELY(mIsTracingEnabled)) {
             char buf[64];
             snprintf(buf, 64, "%s - %d", name, value);
@@ -170,7 +174,7 @@ class Systrace {
         }
     }
 
-    inline void value(uint32_t tag, const char* name, int64_t value) noexcept {
+    void value(uint32_t tag, const char* name, int64_t value) noexcept {
         if (tag && UTILS_UNLIKELY(mIsTracingEnabled)) {
             char buf[64];
             snprintf(buf, 64, "%s - %lld", name, value);
@@ -179,16 +183,16 @@ class Systrace {
         }
     }
 
-    inline void frameId(uint32_t tag, uint32_t frame) noexcept {
+    void frameId(uint32_t tag, uint32_t frame) noexcept {
         if (tag && UTILS_UNLIKELY(mIsTracingEnabled)) {
-            char buf[64]; \
-            snprintf(buf, 64, "frame %u", frame); \
+            char buf[64];
+            snprintf(buf, 64, "frame %u", frame);
             APPLE_SIGNPOST_EMIT(sGlobalState.frameIdLog, OS_SIGNPOST_EVENT,
                     OS_SIGNPOST_ID_EXCLUSIVE, "frame", buf)
         }
     }
 
-   private:
+private:
     friend class ScopedTrace;
 
     struct GlobalState {
@@ -213,25 +217,25 @@ class Systrace {
 // ------------------------------------------------------------------------------------------------
 
 class ScopedTrace {
-   public:
+public:
     // we don't inline this because it's relatively heavy due to a global check
     ScopedTrace(uint32_t tag, const char* name) noexcept : mTrace(tag), mName(name), mTag(tag) {
         mTrace.traceBegin(tag, name);
     }
 
-    inline ~ScopedTrace() noexcept {
+    ~ScopedTrace() noexcept {
         mTrace.traceEnd(mTag, mName);
     }
 
-    inline void value(uint32_t tag, const char* name, int32_t v) noexcept {
+    void value(uint32_t tag, const char* name, int32_t v) noexcept {
         mTrace.value(tag, name, v);
     }
 
-    inline void value(uint32_t tag, const char* name, int64_t v) noexcept {
+    void value(uint32_t tag, const char* name, int64_t v) noexcept {
         mTrace.value(tag, name, v);
     }
 
-   private:
+private:
     Systrace mTrace;
     const char* mName;
     const uint32_t mTag;

libs/utils/src/JobSystem.cpp

@@ -15,10 +15,8 @@
  */
 
 // Note: The overhead of SYSTRACE_TAG_JOBSYSTEM is not negligible especially with parallel_for().
-#ifndef SYSTRACE_TAG
+#define SYSTRACE_TAG SYSTRACE_TAG_DISABLED
 //#define SYSTRACE_TAG SYSTRACE_TAG_JOBSYSTEM
-#define SYSTRACE_TAG SYSTRACE_TAG_NEVER
-#endif
 
 // when SYSTRACE_TAG_JOBSYSTEM is used, enables even heavier systraces
 #define HEAVY_SYSTRACE  0