Merge branch 'rc/1.42.0' into release

README.md

@@ -31,7 +31,7 @@ repositories {
 }
 
 dependencies {
-    implementation 'com.google.android.filament:filament-android:1.41.0'
+    implementation 'com.google.android.filament:filament-android:1.42.0'
 }
 ```
 
@@ -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:
 
 ```
-pod 'Filament', '~> 1.41.0'
+pod 'Filament', '~> 1.42.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.42.0
+
+- engine: add preliminary support for instanced stereoscopic rendering [⚠️ **Recompile materials**]
+
 ## v1.41.0
 
 - backend: fix #6997 : picking can fail on Adreno [⚠️ **New Material Version**]

android/gradle.properties

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

docs/Materials.md.html

@@ -1139,7 +1139,8 @@
 :    array of `string`
 
 Value
-:     Each entry must be any of `dynamicLighting`, `directionalLighting`, `shadowReceiver`,`skinning` or `ssr`.
+:     Each entry must be any of `dynamicLighting`, `directionalLighting`, `shadowReceiver`,
+      `skinning`, `ssr`, or `stereo`.
 
 Description
 :     Used to specify a list of shader variants that the application guarantees will never be
@@ -1158,6 +1159,7 @@
 - `fog`, used when global fog is applied to the scene
 - `vsm`, used when VSM shadows are enabled and the object is a shadow receiver
 - `ssr`, used when screen-space reflections are enabled in the View
+- `stereo`, used when stereoscopic rendering is enabled in the View
 
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ JSON
 material {

filament/backend/CMakeLists.txt

@@ -31,6 +31,7 @@ set(SRCS
         src/CircularBuffer.cpp
         src/CommandBufferQueue.cpp
         src/CommandStream.cpp
+        src/CompilerThreadPool.cpp
         src/Driver.cpp
         src/Handle.cpp
         src/HandleAllocator.cpp
@@ -55,6 +56,7 @@ set(PRIVATE_HDRS
         include/private/backend/PlatformFactory.h
         include/private/backend/SamplerGroup.h
         src/CommandStreamDispatcher.h
+        src/CompilerThreadPool.h
         src/DataReshaper.h
         src/DriverBase.h
 )

filament/backend/include/backend/DriverEnums.h

@@ -1141,6 +1141,11 @@ enum class Workaround : uint16_t {
     A8X_STATIC_TEXTURE_TARGET_ERROR,
     // Adreno drivers sometimes aren't able to blit into a layer of a texture array.
     DISABLE_BLIT_INTO_TEXTURE_ARRAY,
+    // Multiple workarounds needed for PowerVR GPUs
+    POWER_VR_SHADER_WORKAROUNDS,
+    // The driver has some threads pinned, and we can't easily know on which core, it can hurt
+    // performance more if we end-up pinned on the same one.
+    DISABLE_THREAD_AFFINITY
 };
 
 } // namespace filament::backend

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

@@ -287,7 +287,7 @@ DECL_DRIVER_API_SYNCHRONOUS_N(void, setStreamDimensions, backend::StreamHandle,
 DECL_DRIVER_API_SYNCHRONOUS_N(int64_t, getStreamTimestamp, backend::StreamHandle, stream)
 DECL_DRIVER_API_SYNCHRONOUS_N(void, updateStreams, backend::DriverApi*, driver)
 DECL_DRIVER_API_SYNCHRONOUS_N(void, destroyFence, backend::FenceHandle, fh)
-DECL_DRIVER_API_SYNCHRONOUS_N(backend::FenceStatus, wait, backend::FenceHandle, fh, uint64_t, timeout)
+DECL_DRIVER_API_SYNCHRONOUS_N(backend::FenceStatus, getFenceStatus, backend::FenceHandle, fh)
 DECL_DRIVER_API_SYNCHRONOUS_N(bool, isTextureFormatSupported, backend::TextureFormat, format)
 DECL_DRIVER_API_SYNCHRONOUS_0(bool, isTextureSwizzleSupported)
 DECL_DRIVER_API_SYNCHRONOUS_N(bool, isTextureFormatMipmappable, backend::TextureFormat, format)

filament/backend/src/CompilerThreadPool.cpp

@@ -0,0 +1,131 @@
+/*
+ * 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 "CompilerThreadPool.h"
+
+#include <memory>
+
+namespace filament::backend {
+
+using namespace utils;
+
+ProgramToken::~ProgramToken() = default;
+
+CompilerThreadPool::CompilerThreadPool() noexcept = default;
+
+CompilerThreadPool::~CompilerThreadPool() noexcept {
+    assert_invariant(mCompilerThreads.empty());
+    assert_invariant(mQueues[0].empty());
+    assert_invariant(mQueues[1].empty());
+}
+
+void CompilerThreadPool::init(uint32_t threadCount, JobSystem::Priority priority,
+        ThreadSetup&& threadSetup) noexcept {
+    auto setup = std::make_shared<ThreadSetup>(std::move(threadSetup));
+
+    for (size_t i = 0; i < threadCount; i++) {
+        mCompilerThreads.emplace_back([this, priority, setup]() {
+            // give the thread a name
+            JobSystem::setThreadName("CompilerThreadPool");
+            // run at a slightly lower priority than other filament threads
+            JobSystem::setThreadPriority(priority);
+
+            (*setup)();
+
+            // process jobs from the queue until we're asked to exit
+            while (!mExitRequested) {
+                std::unique_lock lock(mQueueLock);
+                mQueueCondition.wait(lock, [this]() {
+                    return  mExitRequested ||
+                            (!std::all_of( std::begin(mQueues), std::end(mQueues),
+                                    [](auto&& q) { return q.empty(); }));
+                });
+                if (!mExitRequested) {
+                    Job job;
+                    // use the first queue that's not empty
+                    auto& queue = [this]() -> auto& {
+                        for (auto& q: mQueues) {
+                            if (!q.empty()) {
+                                return q;
+                            }
+                        }
+                        return mQueues[0]; // we should never end-up here.
+                    }();
+                    assert_invariant(!queue.empty());
+                    std::swap(job, queue.front().second);
+                    queue.pop_front();
+
+                    // execute the job without holding any locks
+                    lock.unlock();
+                    job();
+                }
+            }
+        });
+
+    }
+}
+
+auto CompilerThreadPool::find(program_token_t const& token) -> std::pair<Queue&, Queue::iterator> {
+    for (auto&& q: mQueues) {
+        auto pos = std::find_if(q.begin(), q.end(), [&token](auto&& item) {
+            return item.first == token;
+        });
+        if (pos != q.end()) {
+            return { q, pos };
+        }
+    }
+    // this can happen if the program is being processed right now
+    return { mQueues[0], mQueues[0].end() };
+}
+
+auto CompilerThreadPool::dequeue(program_token_t const& token) -> Job {
+    std::unique_lock const lock(mQueueLock);
+    Job job;
+    auto&& [q, pos] = find(token);
+    if (pos != q.end()) {
+        std::swap(job, pos->second);
+        q.erase(pos);
+    }
+    return job;
+}
+
+void CompilerThreadPool::queue(CompilerPriorityQueue priorityQueue,
+        program_token_t const& token, Job&& job) {
+    std::unique_lock const lock(mQueueLock);
+    mQueues[size_t(priorityQueue)].emplace_back(token, std::move(job));
+    mQueueCondition.notify_one();
+}
+
+void CompilerThreadPool::terminate() noexcept {
+    std::unique_lock lock(mQueueLock);
+    mExitRequested = true;
+    mQueueCondition.notify_all();
+    lock.unlock();
+
+    for (auto& thread: mCompilerThreads) {
+        if (thread.joinable()) {
+            thread.join();
+        }
+    }
+    mCompilerThreads.clear();
+
+    // Clear all the queues, dropping the remaining jobs. This relies on the jobs being cancelable.
+    for (auto&& q : mQueues) {
+        q.clear();
+    }
+}
+
+} // namespace filament::backend

filament/backend/src/CompilerThreadPool.h

@@ -0,0 +1,68 @@
+/*
+ * 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.
+ */
+
+#ifndef TNT_FILAMENT_BACKEND_COMPILERTHREADPOOL_H
+#define TNT_FILAMENT_BACKEND_COMPILERTHREADPOOL_H
+
+#include <backend/DriverEnums.h>
+
+#include <utils/Invocable.h>
+#include <utils/JobSystem.h>
+
+#include <array>
+#include <atomic>
+#include <deque>
+#include <memory>
+#include <utility>
+#include <vector>
+
+namespace filament::backend {
+
+struct ProgramToken {
+    virtual ~ProgramToken();
+};
+
+using program_token_t = std::shared_ptr<ProgramToken>;
+
+class Platform;
+
+class CompilerThreadPool {
+public:
+    CompilerThreadPool() noexcept;
+    ~CompilerThreadPool() noexcept;
+    using Job = utils::Invocable<void()>;
+    using ThreadSetup = utils::Invocable<void()>;
+    void init(uint32_t threadCount, utils::JobSystem::Priority priority,
+            ThreadSetup&& threadSetup) noexcept;
+    void terminate() noexcept;
+    void queue(CompilerPriorityQueue priorityQueue, program_token_t const& token, Job&& job);
+    Job dequeue(program_token_t const& token);
+
+private:
+    using Queue = std::deque<std::pair<program_token_t, Job>>;
+    std::vector<std::thread> mCompilerThreads;
+    std::atomic_bool mExitRequested{false};
+    std::mutex mQueueLock;
+    std::condition_variable mQueueCondition;
+    std::array<Queue, 2> mQueues;
+    // lock must be held for methods below
+    std::pair<Queue&, Queue::iterator> find(program_token_t const& token);
+};
+
+} // namespace filament::backend
+
+#endif  // TNT_FILAMENT_BACKEND_COMPILERTHREADPOOL_H
+

filament/backend/src/metal/MetalDriver.mm

@@ -607,12 +607,12 @@
     }
 }
 
-FenceStatus MetalDriver::wait(Handle<HwFence> fh, uint64_t timeout) {
+FenceStatus MetalDriver::getFenceStatus(Handle<HwFence> fh) {
     auto* fence = handle_cast<MetalFence>(fh);
     if (!fence) {
         return FenceStatus::ERROR;
     }
-    return fence->wait(timeout);
+    return fence->wait(0);
 }
 
 bool MetalDriver::isTextureFormatSupported(TextureFormat format) {
@@ -708,6 +708,8 @@
             return mContext->bugs.a8xStaticTextureTargetError;
         case Workaround::DISABLE_BLIT_INTO_TEXTURE_ARRAY:
             return false;
+        default:
+            return false;
     }
     return false;
 }

filament/backend/src/noop/NoopDriver.cpp

@@ -132,7 +132,7 @@ void NoopDriver::updateStreams(CommandStream* driver) {
 void NoopDriver::destroyFence(Handle<HwFence> fh) {
 }
 
-FenceStatus NoopDriver::wait(Handle<HwFence> fh, uint64_t timeout) {
+FenceStatus NoopDriver::getFenceStatus(Handle<HwFence> fh) {
     return FenceStatus::CONDITION_SATISFIED;
 }
 

filament/backend/src/opengl/OpenGLContext.cpp

@@ -283,6 +283,19 @@ OpenGLContext::OpenGLContext() noexcept {
             bugs.vao_doesnt_store_element_array_buffer_binding = true;
         } else if (strstr(state.renderer, "PowerVR")) {
             // PowerVR GPU
+            // On PowerVR (Rogue GE8320) glFlush doesn't seem to do anything, in particular,
+            // it doesn't kick the GPU earlier, so don't issue these calls as they seem to slow
+            // things down.
+            bugs.disable_glFlush = true;
+            // On PowerVR (Rogue GE8320) using gl_InstanceID too early in the shader doesn't work.
+            bugs.powervr_shader_workarounds = true;
+            // On PowerVR (Rogue GE8320) destroying a fbo after glBlitFramebuffer is effectively
+            // equivalent to glFinish.
+            bugs.delay_fbo_destruction = true;
+            // PowerVR seems to have no problem with this (which is good for us)
+            bugs.allow_read_only_ancillary_feedback_loop = true;
+            // PowerVR has a shader compiler thread pinned on the last core
+            bugs.disable_thread_affinity = true;
         } else if (strstr(state.renderer, "Apple")) {
             // Apple GPU
         } else if (strstr(state.renderer, "Tegra") ||

filament/backend/src/opengl/OpenGLContext.h

@@ -261,6 +261,20 @@ class OpenGLContext {
         // Some Adreno drivers crash in glDrawXXX() when there's an uninitialized uniform block,
         // even when the shader doesn't access it.
         bool enable_initialize_non_used_uniform_array;
+
+        // Workarounds specific to PowerVR GPUs affecting shaders (currently, we lump them all
+        // under one specialization constant).
+        // - gl_InstanceID is invalid when used first in the vertex shader
+        bool powervr_shader_workarounds;
+
+        // On PowerVR destroying the destination of a glBlitFramebuffer operation is equivalent to
+        // a glFinish. So we must delay the destruction until we know the GPU is finished.
+        bool delay_fbo_destruction;
+
+        // The driver has some threads pinned, and we can't easily know on which core, it can hurt
+        // performance more if we end-up pinned on the same one.
+        bool disable_thread_affinity;
+
     } bugs = {};
 
     // state getters -- as needed.
@@ -444,6 +458,15 @@ class OpenGLContext {
             {   bugs.enable_initialize_non_used_uniform_array,
                     "enable_initialize_non_used_uniform_array",
                     ""},
+            {   bugs.powervr_shader_workarounds,
+                    "powervr_shader_workarounds",
+                    ""},
+            {   bugs.delay_fbo_destruction,
+                    "delay_fbo_destruction",
+                    ""},
+            {   bugs.disable_thread_affinity,
+                    "disable_thread_affinity",
+                    ""},
     }};
 
     RenderPrimitive mDefaultVAO;