materials: introduce MaterialCache (#9205)

* materials: introduce MaterialCache

Presently, Filament Materials are instantiated by first parsing a bunch of
read-only data from a material file, then applying a bunch of options from its
Builder before settling on a final, immutable Material object. If two different
Material instances need to be parameterized differently, e.g. setting their spec
constants independently, each has to do all of these steps independently for
each variation.

This change introduces two new concepts: MaterialDefinition, representing the
deserialized, read-only state of a material file, and MaterialCache, a
reference-counted system responsible for managing the lifetimes of
MaterialDefinitions. Now, each Material asks the cache if a MaterialDefinition
exists for the particular UUID of the data it's trying to read; if not,
MaterialCache creates a new entry transparently. If a hundred different
Materials all try to load the same material data, only one
MaterialDefinition (and its associated GPU resources) will be created.

This first PR is the least possible invasive implementation of this feature.
There are a lot of room for improvements (and more planned). For example, each
Material still manages its own compiled shader program cache, but we can easily
move this to the MaterialCache in future PRs, further enabling the planned
mutable spec constants feature.

Additionally, there's room here to add a Material::toBuilder() method, which
could take an extant material and create a Builder object from it already
parameterized with all of the same options, a la the prototype design pattern.

* material cache: key on crc32

* material cache: make materialParser private

* move RefCountedMap to utils and add unit tests

* material cache: make create functions private

* material cache: fix broken tests on iOS/web

* material cache: address more comments

Author: elizagamedev

filament/CMakeLists.txt

@@ -84,6 +84,8 @@ set(SRCS
         src/InstanceBuffer.cpp
         src/LightManager.cpp
         src/Material.cpp
+        src/MaterialCache.cpp
+        src/MaterialDefinition.cpp
         src/MaterialInstance.cpp
         src/MaterialInstanceManager.cpp
         src/MaterialParser.cpp
@@ -175,6 +177,8 @@ set(PRIVATE_HDRS
         src/HwRenderPrimitiveFactory.h
         src/HwVertexBufferInfoFactory.h
         src/Intersections.h
+        src/MaterialCache.h
+        src/MaterialDefinition.h
         src/MaterialParser.h
         src/MaterialInstanceManager.h
         src/PIDController.h

filament/backend/include/backend/DriverEnums.h

@@ -636,6 +636,15 @@ enum class ShaderModel : uint8_t {
 };
 static constexpr size_t SHADER_MODEL_COUNT = 2;
 
+constexpr std::string_view to_string(ShaderModel model) noexcept {
+    switch (model) {
+        case ShaderModel::MOBILE:
+            return "mobile";
+        case ShaderModel::DESKTOP:
+            return "desktop";
+    }
+}
+
 /**
  * Primitive types
  */

filament/src/MaterialCache.cpp

@@ -0,0 +1,65 @@
+/*
+ * 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 "MaterialCache.h"
+#include "MaterialParser.h"
+
+#include <backend/DriverEnums.h>
+
+#include <details/Engine.h>
+#include <details/Material.h>
+
+#include <utils/Logger.h>
+
+namespace filament {
+
+size_t MaterialCache::Key::Hash::operator()(
+        filament::MaterialCache::Key const& key) const noexcept {
+    uint32_t crc;
+    if (key.parser->getMaterialCrc32(&crc)) {
+        return size_t(crc);
+    }
+    return size_t(key.parser->computeCrc32());
+}
+
+bool MaterialCache::Key::operator==(Key const& rhs) const noexcept {
+    return parser == rhs.parser;
+}
+
+MaterialCache::~MaterialCache() {
+    if (!mDefinitions.empty()) {
+        LOG(WARNING) << "MaterialCache was destroyed but wasn't empty";
+    }
+}
+
+MaterialDefinition* UTILS_NULLABLE MaterialCache::acquire(FEngine& engine,
+        const void* UTILS_NONNULL data, size_t size) noexcept {
+    std::unique_ptr<MaterialParser> parser = MaterialDefinition::createParser(engine.getBackend(),
+            engine.getShaderLanguage(), data, size);
+    assert_invariant(parser);
+
+    return mDefinitions.acquire(Key{parser.get()}, [&engine, parser = std::move(parser)]() mutable {
+        return MaterialDefinition::create(engine, std::move(parser));
+    });
+}
+
+void MaterialCache::release(FEngine& engine, MaterialParser const& parser) noexcept {
+    mDefinitions.release(Key{&parser}, [&engine](MaterialDefinition& definition) {
+        definition.terminate(engine);
+    });
+}
+
+} // namespace filament

filament/src/MaterialCache.h

@@ -0,0 +1,65 @@
+/*
+ * 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_FILAMENT_MATERIALCACHE_H
+#define TNT_FILAMENT_MATERIALCACHE_H
+
+#include "MaterialDefinition.h"
+
+#include <private/filament/Variant.h>
+
+#include <backend/CallbackHandler.h>
+#include <backend/DriverEnums.h>
+#include <backend/Handle.h>
+#include <backend/Program.h>
+
+#include <utils/Invocable.h>
+#include <utils/RefCountedMap.h>
+
+namespace filament {
+
+class Material;
+
+class MaterialCache {
+    // A newtype around a material parser used as a key for the material cache. The material file's
+    // CRC32 is used as the hash function.
+    struct Key {
+        struct Hash {
+            size_t operator()(Key const& x) const noexcept;
+        };
+        bool operator==(Key const& rhs) const noexcept;
+
+        MaterialParser const* UTILS_NONNULL parser;
+    };
+
+public:
+    ~MaterialCache();
+
+    /** Acquire or create a new entry in the cache for the given material data. */
+    MaterialDefinition* UTILS_NULLABLE acquire(FEngine& engine, const void* UTILS_NONNULL data,
+            size_t size) noexcept;
+
+    /** Release an entry in the cache, potentially freeing its GPU resources. */
+    void release(FEngine& engine, MaterialParser const& parser) noexcept;
+
+private:
+    // We use unique_ptr here because we need these pointers to be stable.
+    // TODO: investigate using a custom allocator here?
+    utils::RefCountedMap<Key, std::unique_ptr<MaterialDefinition>, Key::Hash> mDefinitions;
+};
+
+} // namespace filament
+
+#endif  // TNT_FILAMENT_MATERIALCACHE_H