Merge branch 'rc/1.54.2' into release

NEW_RELEASE_NOTES.md

@@ -7,5 +7,3 @@ for next branch cut* header.
 appropriate header in [RELEASE_NOTES.md](./RELEASE_NOTES.md).
 
 ## Release notes for next branch cut
-
-- Add a `name` API to Filament objects for debugging handle use-after-free assertions

README.md

@@ -31,7 +31,7 @@ repositories {
 }
 
 dependencies {
-    implementation 'com.google.android.filament:filament-android:1.54.1'
+    implementation 'com.google.android.filament:filament-android:1.54.2'
 }
 ```
 
@@ -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.54.1'
+pod 'Filament', '~> 1.54.2'
 ```
 
 ### 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.54.2
+
+- Add a `name` API to Filament objects for debugging handle use-after-free assertions
+
 ## v1.54.1
 
 

android/gradle.properties

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

docs/Materials.md.html

@@ -1308,7 +1308,12 @@
       declare a variable called `eyeDirection` you can access it in the fragment shader using
       `variable_eyeDirection`. In the vertex shader, the interpolant name is simply a member of
       the `MaterialVertexInputs` structure (`material.eyeDirection` in your example). Each
-      interpolant is of type `float4` (`vec4`) in the shaders.
+      interpolant is of type `float4` (`vec4`) in the shaders. By default the precision of the
+      interpolant is `highp` in *both* the vertex and fragment shaders.
+      An alternate syntax can be used to specify both the name and precision of the interpolant.
+      In this case the specified precision is used as-is in both fragment and vertex stages, in
+      particular if `default` is specified the default precision is used is the fragment shader
+      (`mediump`) and in the vertex shader (`highp`).
 
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ JSON
 material {
@@ -1320,7 +1325,11 @@
         }
     ],
     variables : [
-         eyeDirection
+         eyeDirection,
+         {
+            name : eyeColor,
+            precision : medium
+         }
     ],
     vertexDomain : device,
     depthWrite : false,

filament/backend/include/private/backend/HandleAllocator.h

@@ -208,14 +208,8 @@ class HandleAllocator {
         // TODO: for now, only pool handles check for use-after-free, so we only keep tags for
         // those
         if (isPoolHandle(id)) {
-            // Truncate the tag's age to N bits.
-            constexpr uint8_t N = 2; // support a history of 4 tags
-            constexpr uint8_t mask = (1 << N) - 1;
-
-            uint8_t const age = (id & HANDLE_AGE_MASK) >> HANDLE_AGE_SHIFT;
-            uint8_t const newAge = age & mask;
-            uint32_t const key = (id & ~HANDLE_AGE_MASK) | (newAge << HANDLE_AGE_SHIFT);
-
+            // Truncate the age to get the debug tag
+            uint32_t const key = id & ~(HANDLE_DEBUG_TAG_MASK ^ HANDLE_AGE_MASK);
             // This line is the costly part. In the future, we could potentially use a custom
             // allocator.
             mDebugTags[key] = std::move(tag);
@@ -226,7 +220,8 @@ class HandleAllocator {
         if (!isPoolHandle(id)) {
             return "(no tag)";
         }
-        if (auto pos = mDebugTags.find(id); pos != mDebugTags.end()) {
+        uint32_t const key = id & ~(HANDLE_DEBUG_TAG_MASK ^ HANDLE_AGE_MASK);
+        if (auto pos = mDebugTags.find(key); pos != mDebugTags.end()) {
             return pos->second;
         }
         return "(no tag)";
@@ -349,12 +344,24 @@ class HandleAllocator {
         }
     }
 
-    // we handle a 4 bits age per address
-    static constexpr uint32_t HANDLE_HEAP_FLAG      = 0x80000000u;      // pool vs heap handle
-    static constexpr uint32_t HANDLE_AGE_MASK       = 0x78000000u;      // handle's age
-    static constexpr uint32_t HANDLE_INDEX_MASK     = 0x07FFFFFFu;      // handle index
-    static constexpr uint32_t HANDLE_TAG_MASK       = HANDLE_AGE_MASK;
-    static constexpr uint32_t HANDLE_AGE_SHIFT      = 27;
+    // number if bits allotted to the handle's age (currently 4 max)
+    static constexpr uint32_t HANDLE_AGE_BIT_COUNT = 4;
+    // number if bits allotted to the handle's debug tag (HANDLE_AGE_BIT_COUNT max)
+    static constexpr uint32_t HANDLE_DEBUG_TAG_BIT_COUNT = 2;
+    // bit shift for both the age and debug tag
+    static constexpr uint32_t HANDLE_AGE_SHIFT = 27;
+    // mask for the heap (vs pool) flag
+    static constexpr uint32_t HANDLE_HEAP_FLAG = 0x80000000u;
+    // mask for the age
+    static constexpr uint32_t HANDLE_AGE_MASK =
+            ((1 << HANDLE_AGE_BIT_COUNT) - 1) << HANDLE_AGE_SHIFT;
+    // mask for the debug tag
+    static constexpr uint32_t HANDLE_DEBUG_TAG_MASK =
+            ((1 << HANDLE_DEBUG_TAG_BIT_COUNT) - 1) << HANDLE_AGE_SHIFT;
+    // mask for the index
+    static constexpr uint32_t HANDLE_INDEX_MASK = 0x07FFFFFFu;
+
+    static_assert(HANDLE_DEBUG_TAG_BIT_COUNT <= HANDLE_AGE_BIT_COUNT);
 
     static bool isPoolHandle(HandleBase::HandleId id) noexcept {
         return (id & HANDLE_HEAP_FLAG) == 0u;
@@ -369,7 +376,7 @@ class HandleAllocator {
         // a non-pool handle.
         if (UTILS_LIKELY(isPoolHandle(id))) {
             char* const base = (char*)mHandleArena.getArea().begin();
-            uint32_t const tag = id & HANDLE_TAG_MASK;
+            uint32_t const tag = id & HANDLE_AGE_MASK;
             size_t const offset = (id & HANDLE_INDEX_MASK) * Allocator::getAlignment();
             return { static_cast<void*>(base + offset), tag };
         }
@@ -384,7 +391,7 @@ class HandleAllocator {
         size_t const offset = (char*)p - base;
         assert_invariant((offset % Allocator::getAlignment()) == 0);
         auto id = HandleBase::HandleId(offset / Allocator::getAlignment());
-        id |= tag & HANDLE_TAG_MASK;
+        id |= tag & HANDLE_AGE_MASK;
         assert_invariant((id & HANDLE_HEAP_FLAG) == 0);
         return id;
     }

filament/backend/src/metal/MetalBuffer.h

@@ -160,6 +160,8 @@ class MetalBuffer {
          size_t size, bool forceGpuBuffer = false);
     ~MetalBuffer();
 
+    [[nodiscard]] bool wasAllocationSuccessful() const noexcept { return mBuffer || mCpuBuffer; }
+
     MetalBuffer(const MetalBuffer& rhs) = delete;
     MetalBuffer& operator=(const MetalBuffer& rhs) = delete;
 

filament/backend/src/metal/MetalBuffer.mm

@@ -53,8 +53,8 @@
         mBuffer = { [context.device newBufferWithLength:size options:MTLResourceStorageModePrivate],
             TrackedMetalBuffer::Type::GENERIC };
     }
-    FILAMENT_CHECK_POSTCONDITION(mBuffer)
-            << "Could not allocate Metal buffer of size " << size << ".";
+    // mBuffer might fail to be allocated. Clients can check for this by calling
+    // wasAllocationSuccessful().
 }
 
 MetalBuffer::~MetalBuffer() {

filament/backend/src/metal/MetalDriver.h

@@ -57,7 +57,6 @@ class MetalDriver final : public DriverBase {
 
 public:
     static Driver* create(MetalPlatform* platform, const Platform::DriverConfig& driverConfig);
-    void runAtNextTick(const std::function<void()>& fn) noexcept;
 
 private:
 
@@ -73,10 +72,12 @@ class MetalDriver final : public DriverBase {
 
     /*
      * Tasks run regularly on the driver thread.
+     * Not thread-safe; tasks are run from the driver thead and must be enqueued from the driver
+     * thread.
      */
+    void runAtNextTick(const std::function<void()>& fn) noexcept;
     void executeTickOps() noexcept;
     std::vector<std::function<void()>> mTickOps;
-    std::mutex mTickOpsLock;
 
     /*
      * Driver interface

filament/backend/src/metal/MetalDriver.mm

@@ -320,17 +320,40 @@
         uint32_t vertexCount, Handle<HwVertexBufferInfo> vbih) {
     MetalVertexBufferInfo const* const vbi = handle_cast<const MetalVertexBufferInfo>(vbih);
     construct_handle<MetalVertexBuffer>(vbh, *mContext, vertexCount, vbi->bufferCount, vbih);
+    // No actual GPU memory is allocated here, so no need to check for allocation success.
 }
 
 void MetalDriver::createIndexBufferR(Handle<HwIndexBuffer> ibh, ElementType elementType,
         uint32_t indexCount, BufferUsage usage) {
-    auto elementSize = (uint8_t) getElementTypeSize(elementType);
-    construct_handle<MetalIndexBuffer>(ibh, *mContext, usage, elementSize, indexCount);
+    auto elementSize = (uint8_t)getElementTypeSize(elementType);
+    auto* indexBuffer =
+            construct_handle<MetalIndexBuffer>(ibh, *mContext, usage, elementSize, indexCount);
+    auto& buffer = indexBuffer->buffer;
+    // If the allocation was not successful, postpone the error message until the next tick, to give
+    // Filament a chance to call setDebugTag on the handle; this way we get a nicer error message.
+    if (UTILS_UNLIKELY(!buffer.wasAllocationSuccessful())) {
+        const size_t byteCount = buffer.getSize();
+        runAtNextTick([byteCount, this, ibh]() {
+            FILAMENT_CHECK_POSTCONDITION(false)
+                    << "Could not allocate Metal index buffer of size " << byteCount
+                    << ", tag=" << mHandleAllocator.getHandleTag(ibh.getId()).c_str_safe();
+        });
+    }
 }
 
 void MetalDriver::createBufferObjectR(Handle<HwBufferObject> boh, uint32_t byteCount,
         BufferObjectBinding bindingType, BufferUsage usage) {
-    construct_handle<MetalBufferObject>(boh, *mContext, bindingType, usage, byteCount);
+    auto* bufferObject =
+            construct_handle<MetalBufferObject>(boh, *mContext, bindingType, usage, byteCount);
+    // If the allocation was not successful, postpone the error message until the next tick, to give
+    // Filament a chance to call setDebugTag on the handle; this way we get a nicer error message.
+    if (UTILS_UNLIKELY(!bufferObject->getBuffer()->wasAllocationSuccessful())) {
+        runAtNextTick([byteCount, this, boh]() {
+            FILAMENT_CHECK_POSTCONDITION(false)
+                    << "Could not allocate Metal buffer of size " << byteCount
+                    << ", tag=" << mHandleAllocator.getHandleTag(boh.getId()).c_str_safe();
+        });
+    }
 }
 
 void MetalDriver::createTextureR(Handle<HwTexture> th, SamplerType target, uint8_t levels,
@@ -2066,15 +2089,12 @@
 }
 
 void MetalDriver::runAtNextTick(const std::function<void()>& fn) noexcept {
-    std::lock_guard<std::mutex> const lock(mTickOpsLock);
     mTickOps.push_back(fn);
 }
 
 void MetalDriver::executeTickOps() noexcept {
     std::vector<std::function<void()>> ops;
-    mTickOpsLock.lock();
     std::swap(ops, mTickOps);
-    mTickOpsLock.unlock();
     for (const auto& f : ops) {
         f();
     }

filament/backend/src/metal/MetalHandles.mm

@@ -257,10 +257,6 @@ static inline MTLTextureUsage getMetalTextureUsage(TextureUsage usage) {
     }
 }
 
-#ifndef FILAMENT_RELEASE_PRESENT_DRAWABLE_MAIN_THREAD
-#define FILAMENT_RELEASE_PRESENT_DRAWABLE_MAIN_THREAD 1
-#endif
-
 class PresentDrawableData {
 public:
     PresentDrawableData() = delete;
@@ -279,14 +275,10 @@ static void maybePresentAndDestroyAsync(PresentDrawableData* that, bool shouldPr
            [that->mDrawable present];
         }
 
-#if FILAMENT_RELEASE_PRESENT_DRAWABLE_MAIN_THREAD == 1
         // mDrawable is acquired on the driver thread. Typically, we would release this object on
         // the same thread, but after receiving consistent crash reports from within
         // [CAMetalDrawable dealloc], we suspect this object requires releasing on the main thread.
         dispatch_async(dispatch_get_main_queue(), ^{ cleanupAndDestroy(that); });
-#else
-        that->mDriver->runAtNextTick([that]() { cleanupAndDestroy(that); });
-#endif
     }
 
 private:

filament/backend/src/opengl/OpenGLContext.cpp

@@ -541,9 +541,6 @@ void OpenGLContext::initBugs(Bugs* bugs, Extensions const& exts,
             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 doesn't respect lengths passed to glShaderSource, so concatenate them into a
-            // single string.
-            bugs->concatenate_shader_strings = true;
         } else if (strstr(renderer, "Apple")) {
             // Apple GPU
         } else if (strstr(renderer, "Tegra") ||

filament/backend/src/opengl/OpenGLContext.h

@@ -315,12 +315,6 @@ class OpenGLContext final : public TimerQueryFactoryInterface {
         // bugs or performance issues.
         bool force_feature_level0;
 
-        // Some drivers don't respect the length argument of glShaderSource() and (apparently)
-        // require each shader source string to be null-terminated. This works around the issue by
-        // concatenating the strings into a single null-terminated string before passing it to
-        // glShaderSource().
-        bool concatenate_shader_strings;
-
     } bugs = {};
 
     // state getters -- as needed.
@@ -567,9 +561,6 @@ class OpenGLContext final : public TimerQueryFactoryInterface {
             {   bugs.force_feature_level0,
                     "force_feature_level0",
                     ""},
-            {   bugs.concatenate_shader_strings,
-                    "concatenate_shader_strings",
-                    ""},
     }};
 
     // this is chosen to minimize code size

filament/backend/src/opengl/ShaderCompilerService.cpp

@@ -597,40 +597,30 @@ void ShaderCompilerService::compileShaders(OpenGLContext& context,
                 version = "#version 310 es\n";
             }
 
-            const std::array<const char*, 5> sources = {
-                    version.data(),
-                    prolog.data(),
-                    specializationConstantString.c_str(),
-                    packingFunctions.data(),
-                    body.data()
+            std::array<std::string_view, 5> sources = {
+                version,
+                prolog,
+                specializationConstantString,
+                packingFunctions,
+                { body.data(), body.size() - 1 }  // null-terminated
             };
 
-            const std::array<GLint, 5> lengths = {
-                    (GLint)version.length(),
-                    (GLint)prolog.length(),
-                    (GLint)specializationConstantString.length(),
-                    (GLint)packingFunctions.length(),
-                    (GLint)body.length() - 1 // null terminated
-            };
+            // Some of the sources may be zero-length. Remove them as to avoid passing lengths of
+            // zero to glShaderSource(). glShaderSource should work with lengths of zero, but some
+            // drivers instead interpret zero as a sentinel for a null-terminated string.
+            auto partitionPoint = std::stable_partition(
+                    sources.begin(), sources.end(), [](std::string_view s) { return !s.empty(); });
+            size_t count = std::distance(sources.begin(), partitionPoint);
+
+            std::array<const char*, 5> shaderStrings;
+            std::array<GLint, 5> lengths;
+            for (size_t i = 0; i < count; i++) {
+                shaderStrings[i] = sources[i].data();
+                lengths[i] = sources[i].size();
+            }
 
             GLuint const shaderId = glCreateShader(glShaderType);
-
-            if (UTILS_UNLIKELY(context.bugs.concatenate_shader_strings)) {
-                size_t totalSize = 0;
-                for (size_t i = 0; i < sources.size(); i++) {
-                    totalSize += lengths[i];
-                }
-                std::string concatenatedShaderSource;
-                concatenatedShaderSource.reserve(totalSize);
-                for (size_t i = 0; i < sources.size(); i++) {
-                    concatenatedShaderSource.append(sources[i], lengths[i]);
-                }
-                const GLchar* ptr = concatenatedShaderSource.c_str();
-                GLint length = concatenatedShaderSource.length();
-                glShaderSource(shaderId, 1, &ptr, &length);
-            } else {
-                glShaderSource(shaderId, sources.size(), sources.data(), lengths.data());
-            }
+            glShaderSource(shaderId, count, shaderStrings.data(), lengths.data());
 
             glCompileShader(shaderId);
 

filament/include/filament/FilamentAPI.h

@@ -55,7 +55,8 @@ class UTILS_PUBLIC FilamentAPI {
 template<typename T>
 using BuilderBase = utils::PrivateImplementation<T>;
 
-void builderMakeName(utils::CString& outName, const char* name, size_t len) noexcept;
+// This needs to be public because it is used in the following template.
+UTILS_PUBLIC void builderMakeName(utils::CString& outName, const char* name, size_t len) noexcept;
 
 template <typename Builder>
 class UTILS_PUBLIC BuilderNameMixin {