Merge branch 'rc/1.37.0' into release

NEW_RELEASE_NOTES.md

@@ -7,3 +7,4 @@ for next branch cut* header.
 appropriate header in [RELEASE_NOTES.md](./RELEASE_NOTES.md).
 
 ## Release notes for next branch cut
+

README.md

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

RELEASE_NOTES.md

@@ -7,6 +7,10 @@ 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.37.0
+
+- backend: added `Platform` blob cache APIs, typically used to cache programs [⚠️ **Recompile materials**]
+
 ## v1.36.0
 
 - engine: a local transform can now be supplied for each GPU instance [⚠️ **Recompile materials**]

android/gradle.properties

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

filament/CMakeLists.txt

@@ -237,14 +237,7 @@ set(MATERIAL_SRCS
         src/materials/skybox.mat
         src/materials/ssao/sao.mat
         src/materials/ssao/saoBentNormals.mat
-        src/materials/separableGaussianBlur1.mat
-        src/materials/separableGaussianBlur2.mat
-        src/materials/separableGaussianBlur3.mat
-        src/materials/separableGaussianBlur4.mat
-        src/materials/separableGaussianBlur1L.mat
-        src/materials/separableGaussianBlur2L.mat
-        src/materials/separableGaussianBlur3L.mat
-        src/materials/separableGaussianBlur4L.mat
+        src/materials/separableGaussianBlur.mat
         src/materials/antiAliasing/fxaa.mat
         src/materials/antiAliasing/taa.mat
         src/materials/vsmMipmap.mat
@@ -462,56 +455,7 @@ add_custom_command(
 )
 
 add_custom_command(
-        OUTPUT "${MATERIAL_DIR}/separableGaussianBlur1.filamat"
-        DEPENDS src/materials/separableGaussianBlur.vs
-        DEPENDS src/materials/separableGaussianBlur.fs
-        APPEND
-)
-
-add_custom_command(
-        OUTPUT "${MATERIAL_DIR}/separableGaussianBlur2.filamat"
-        DEPENDS src/materials/separableGaussianBlur.vs
-        DEPENDS src/materials/separableGaussianBlur.fs
-        APPEND
-)
-
-add_custom_command(
-        OUTPUT "${MATERIAL_DIR}/separableGaussianBlur3.filamat"
-        DEPENDS src/materials/separableGaussianBlur.vs
-        DEPENDS src/materials/separableGaussianBlur.fs
-        APPEND
-)
-
-add_custom_command(
-        OUTPUT "${MATERIAL_DIR}/separableGaussianBlur4.filamat"
-        DEPENDS src/materials/separableGaussianBlur.vs
-        DEPENDS src/materials/separableGaussianBlur.fs
-        APPEND
-)
-
-add_custom_command(
-        OUTPUT "${MATERIAL_DIR}/separableGaussianBlur1L.filamat"
-        DEPENDS src/materials/separableGaussianBlur.vs
-        DEPENDS src/materials/separableGaussianBlur.fs
-        APPEND
-)
-
-add_custom_command(
-        OUTPUT "${MATERIAL_DIR}/separableGaussianBlur2L.filamat"
-        DEPENDS src/materials/separableGaussianBlur.vs
-        DEPENDS src/materials/separableGaussianBlur.fs
-        APPEND
-)
-
-add_custom_command(
-        OUTPUT "${MATERIAL_DIR}/separableGaussianBlur3L.filamat"
-        DEPENDS src/materials/separableGaussianBlur.vs
-        DEPENDS src/materials/separableGaussianBlur.fs
-        APPEND
-)
-
-add_custom_command(
-        OUTPUT "${MATERIAL_DIR}/separableGaussianBlur4L.filamat"
+        OUTPUT "${MATERIAL_DIR}/separableGaussianBlur.filamat"
         DEPENDS src/materials/separableGaussianBlur.vs
         DEPENDS src/materials/separableGaussianBlur.fs
         APPEND

filament/backend/CMakeLists.txt

@@ -25,6 +25,7 @@ set(PUBLIC_HDRS
 
 set(SRCS
         src/BackendUtils.cpp
+        src/BlobCacheKey.cpp
         src/Callable.cpp
         src/CallbackHandler.cpp
         src/CircularBuffer.cpp
@@ -69,6 +70,8 @@ if (FILAMENT_SUPPORTS_OPENGL AND NOT FILAMENT_USE_EXTERNAL_GLES3 AND NOT FILAMEN
             src/opengl/gl_headers.h
             src/opengl/GLUtils.cpp
             src/opengl/GLUtils.h
+            src/opengl/OpenGLBlobCache.cpp
+            src/opengl/OpenGLBlobCache.h
             src/opengl/OpenGLContext.cpp
             src/opengl/OpenGLContext.h
             src/opengl/OpenGLDriver.cpp
@@ -193,20 +196,10 @@ if (FILAMENT_SUPPORTS_VULKAN)
             src/vulkan/VulkanUtility.cpp
             src/vulkan/VulkanUtility.h
     )
-    if (LINUX)
-        if (FILAMENT_SUPPORTS_WAYLAND)
-            list(APPEND SRCS src/vulkan/PlatformVkLinuxWayland.cpp)
-        elseif (FILAMENT_SUPPORTS_X11)
-            list(APPEND SRCS src/vulkan/PlatformVkLinuxX11.cpp)
-        endif()
-    elseif (APPLE AND NOT IOS)
-        list(APPEND SRCS src/vulkan/PlatformVkCocoa.mm)
-    elseif (IOS)
-        list(APPEND SRCS src/vulkan/PlatformVkCocoaTouch.mm)
-    elseif (ANDROID)
-        list(APPEND SRCS src/vulkan/PlatformVkAndroid.cpp)
-    elseif (WIN32)
-        list(APPEND SRCS src/vulkan/PlatformVkWindows.cpp)
+    if (ANDROID OR LINUX OR WIN32)
+        list(APPEND SRCS src/vulkan/platform/PlatformVulkanAndroidLinuxWindows.cpp)
+    elseif (APPLE OR IOS)
+        list(APPEND SRCS src/vulkan/platform/PlatformVulkanApple.mm)
     endif()
 endif()
 

filament/backend/include/backend/Platform.h

@@ -22,6 +22,7 @@
 #include <backend/DriverEnums.h>
 
 #include <utils/compiler.h>
+#include <utils/Invocable.h>
 
 namespace filament::backend {
 
@@ -47,6 +48,8 @@ class UTILS_PUBLIC Platform {
         size_t handleArenaSize = 0;
     };
 
+    Platform() noexcept;
+
     virtual ~Platform() noexcept;
 
     /**
@@ -79,6 +82,85 @@ class UTILS_PUBLIC Platform {
      * thread, or if the platform does not need to perform any special processing.
      */
     virtual bool pumpEvents() noexcept;
+
+    /**
+     * InsertBlobFunc is an Invocable to an application-provided function that a
+     * backend implementation may use to insert a key/value pair into the
+     * cache.
+     */
+    using InsertBlobFunc = utils::Invocable<
+            void(const void* key, size_t keySize, const void* value, size_t valueSize)>;
+
+    /*
+     * RetrieveBlobFunc is an Invocable to an application-provided function that a
+     * backend implementation may use to retrieve a cached value from the
+     * cache.
+     */
+    using RetrieveBlobFunc = utils::Invocable<
+            size_t(const void* key, size_t keySize, void* value, size_t valueSize)>;
+
+    /**
+     * Sets the callback functions that the backend can use to interact with caching functionality
+     * provided by the application.
+     *
+     * Cache functions may only be specified once during the lifetime of a
+     * Platform.  The <insert> and <retrieve> Invocables may be called at any time and
+     * from any thread from the time at which setBlobFunc is called until the time that Platform
+     * is destroyed. Concurrent calls to these functions from different threads is also allowed.
+     *
+     * @param insertBlob    an Invocable that inserts a new value into the cache and associates
+     *                      it with the given key
+     * @param retrieveBlob  an Invocable that retrieves from the cache the value associated with a
+     *                      given key
+     */
+    void setBlobFunc(InsertBlobFunc&& insertBlob, RetrieveBlobFunc&& retrieveBlob) noexcept;
+
+    /**
+     * @return true if setBlobFunc was called.
+     */
+    bool hasBlobFunc() const noexcept;
+
+    /**
+     * To insert a new binary value into the cache and associate it with a given
+     * key, the backend implementation can call the application-provided callback
+     * function insertBlob.
+     *
+     * No guarantees are made as to whether a given key/value pair is present in
+     * the cache after the set call.  If a different value has been associated
+     * with the given key in the past then it is undefined which value, if any, is
+     * associated with the key after the set call.  Note that while there are no
+     * guarantees, the cache implementation should attempt to cache the most
+     * recently set value for a given key.
+     *
+     * @param key           pointer to the beginning of the key data that is to be inserted
+     * @param keySize       specifies the size in byte of the data pointed to by <key>
+     * @param value         pointer to the beginning of the value data that is to be inserted
+     * @param valueSize     specifies the size in byte of the data pointed to by <value>
+     */
+    void insertBlob(const void* key, size_t keySize, const void* value, size_t valueSize);
+
+    /**
+     * To retrieve the binary value associated with a given key from the cache, a
+     * the backend implementation can call the application-provided callback
+     * function retrieveBlob.
+     *
+     * If the cache contains a value for the given key and its size in bytes is
+     * less than or equal to <valueSize> then the value is written to the memory
+     * pointed to by <value>.  Otherwise nothing is written to the memory pointed
+     * to by <value>.
+     *
+     * @param key          pointer to the beginning of the key
+     * @param keySize      specifies the size in bytes of the binary key pointed to by <key>
+     * @param value        pointer to a buffer to receive the cached binary data, if it exists
+     * @param valueSize    specifies the size in bytes of the memory pointed to by <value>
+     * @return             If the cache contains a value associated with the given key then the
+     *                     size of that binary value in bytes is returned. Otherwise 0 is returned.
+     */
+    size_t retrieveBlob(const void* key, size_t keySize, void* value, size_t valueSize);
+
+private:
+    InsertBlobFunc mInsertBlob;
+    RetrieveBlobFunc mRetrieveBlob;
 };
 
 } // namespace filament

filament/backend/include/backend/Program.h

@@ -109,6 +109,7 @@ class Program {
     Program& specializationConstants(
             utils::FixedCapacityVector<SpecializationConstant> specConstants) noexcept;
 
+    Program& cacheId(uint64_t cacheId) noexcept;
 
     ShaderSource const& getShadersSource() const noexcept { return mShadersSource; }
     ShaderSource& getShadersSource() noexcept { return mShadersSource; }
@@ -135,13 +136,16 @@ class Program {
         return mSpecializationConstants;
     }
 
+    uint64_t getCacheId() const noexcept { return mCacheId; }
+
 private:
     friend utils::io::ostream& operator<<(utils::io::ostream& out, const Program& builder);
 
     UniformBlockInfo mUniformBlocks = {};
     SamplerGroupInfo mSamplerGroups = {};
     ShaderSource mShadersSource;
     utils::CString mName;
+    uint64_t mCacheId{};
     utils::Invocable<utils::io::ostream&(utils::io::ostream& out)> mLogger;
     utils::FixedCapacityVector<SpecializationConstant> mSpecializationConstants;
     utils::FixedCapacityVector<std::pair<utils::CString, uint8_t>> mAttributes;

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

@@ -27,19 +27,10 @@ namespace filament::backend {
 
 class VulkanPlatform : public Platform {
 public:
-    struct SurfaceBundle {
-        void* surface;
-        // On certain platforms, the extent of the surface cannot be queried from Vulkan. In those
-        // situations, we allow the frontend to pass in the extent to use in creating the swap
-        // chains. Platform implementation should set extent to 0 if they do not expect to set the
-        // swap chain extent.
-        uint32_t width;
-        uint32_t height;
-    };
-
-    // Given a Vulkan instance and native window handle, creates the platform-specific surface.
-    virtual SurfaceBundle createVkSurfaceKHR(void* nativeWindow, void* instance,
-        uint64_t flags) noexcept = 0;
+    Driver* createDriver(void* const sharedContext,
+	Platform::DriverConfig const& driverConfig) noexcept override;
+
+    int getOSVersion() const noexcept override { return 0; }
 
    ~VulkanPlatform() override;
 };

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

@@ -22,6 +22,7 @@
 #include "private/backend/Driver.h"
 
 #include <backend/BufferDescriptor.h>
+#include <backend/CallbackHandler.h>
 #include <backend/DriverEnums.h>
 #include <backend/Handle.h>
 #include <backend/PipelineState.h>

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

@@ -17,6 +17,7 @@
 #ifndef TNT_FILAMENT_BACKEND_PRIVATE_DRIVER_H
 #define TNT_FILAMENT_BACKEND_PRIVATE_DRIVER_H
 
+#include <backend/CallbackHandler.h>
 #include <backend/DriverApiForward.h>
 #include <backend/DriverEnums.h>
 #include <backend/Handle.h>

filament/backend/include/private/backend/DriverAPI.inc

@@ -387,6 +387,10 @@ DECL_DRIVER_API_N(beginTimerQuery,
 DECL_DRIVER_API_N(endTimerQuery,
         backend::TimerQueryHandle, query)
 
+DECL_DRIVER_API_N(compilePrograms,
+        backend::CallbackHandler*, handler,
+        backend::CallbackHandler::Callback, callback,
+        void*, user)
 
 /*
  * Swap chain

filament/backend/src/BlobCacheKey.cpp

@@ -0,0 +1,58 @@
+/*
+ * Copyright (C) 2023 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 "BlobCacheKey.h"
+
+#include <memory>
+
+namespace filament::backend {
+
+struct BlobCacheKey::Key {
+    uint64_t id;
+    Program::SpecializationConstant constants[];
+};
+
+BlobCacheKey::BlobCacheKey() noexcept = default;
+
+BlobCacheKey::BlobCacheKey(uint64_t id,
+        BlobCacheKey::SpecializationConstants const& specConstants) {
+    mSize = sizeof(Key) + sizeof(Key::constants[0]) * specConstants.size();
+
+    Key* const pKey = (Key *)malloc(mSize);
+    memset(pKey, 0, mSize);
+    mData.reset(pKey, ::free);
+
+    mData->id = id;
+    for (size_t i = 0; i < specConstants.size(); i++) {
+        mData->constants[i] = specConstants[i];
+    }
+}
+
+BlobCacheKey::BlobCacheKey(BlobCacheKey&& rhs) noexcept
+        : mData(std::move(rhs.mData)), mSize(rhs.mSize) {
+    rhs.mSize = 0;
+}
+
+BlobCacheKey& BlobCacheKey::operator=(BlobCacheKey&& rhs) noexcept {
+    if (this != &rhs) {
+        using std::swap;
+        swap(mData, rhs.mData);
+        swap(mSize, rhs.mSize);
+    }
+    return *this;
+}
+
+} // namespace filament::backend