materials: introduce MaterialCache

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