Update all per-object/instance buffers all at once

pixelflinger · pixelflinger · commit 9f3c0ec8ef6e · 2025-08-29T14:45:36.000-07:00
FIXES=[433807402]
diff --git a/filament/src/components/RenderableManager.cpp b/filament/src/components/RenderableManager.cpp
@@ -434,6 +434,18 @@ void RenderableManager::BuilderDetails::processBoneIndicesAndWights(Engine& engi
     mBoneIndicesAndWeightsCount = pairsCount; // only part of mBoneIndicesAndWeights is used for real data
 }
 
+RenderableManager::Builder& RenderableManager::Builder::instances(size_t const instanceCount) noexcept {
+    mImpl->mInstanceCount = clamp((unsigned int)instanceCount, 1u, 32767u);
+    return *this;
+}
+
+RenderableManager::Builder& RenderableManager::Builder::instances(
+        size_t const instanceCount, InstanceBuffer* instanceBuffer) noexcept {
+    mImpl->mInstanceCount = clamp(instanceCount, (size_t)1, CONFIG_MAX_INSTANCES);
+    mImpl->mInstanceBuffer = downcast(instanceBuffer);
+    return *this;
+}
+
 RenderableManager::Builder::Result RenderableManager::Builder::build(Engine& engine, Entity const entity) {
     bool isEmpty = true;
 
@@ -519,18 +531,6 @@ RenderableManager::Builder::Result RenderableManager::Builder::build(Engine& eng
     return Success;
 }
 
-RenderableManager::Builder& RenderableManager::Builder::instances(size_t const instanceCount) noexcept {
-    mImpl->mInstanceCount = clamp((unsigned int)instanceCount, 1u, 32767u);
-    return *this;
-}
-
-RenderableManager::Builder& RenderableManager::Builder::instances(
-        size_t const instanceCount, InstanceBuffer* instanceBuffer) noexcept {
-    mImpl->mInstanceCount = clamp(instanceCount, (size_t)1, CONFIG_MAX_INSTANCES);
-    mImpl->mInstanceBuffer = downcast(instanceBuffer);
-    return *this;
-}
-
 // ------------------------------------------------------------------------------------------------
 
 FRenderableManager::FRenderableManager(FEngine& engine) noexcept : mEngine(engine) {
diff --git a/filament/src/details/InstanceBuffer.cpp b/filament/src/details/InstanceBuffer.cpp
@@ -29,6 +29,8 @@
 #include <backend/DriverEnums.h>
 #include <backend/Handle.h>
 
+#include <utils/compiler.h>
+#include <utils/debug.h>
 #include <utils/Panic.h>
 #include <utils/StaticString.h>
 
@@ -87,7 +89,7 @@ InstanceBuffer* InstanceBuffer::Builder::build(Engine& engine) const {
 
 // ------------------------------------------------------------------------------------------------
 
-FInstanceBuffer::FInstanceBuffer(FEngine& engine, const Builder& builder)
+FInstanceBuffer::FInstanceBuffer(FEngine&, const Builder& builder)
     : mName(builder.getName()) {
     mInstanceCount = builder->mInstanceCount;
 
@@ -98,22 +100,11 @@ FInstanceBuffer::FInstanceBuffer(FEngine& engine, const Builder& builder)
         memcpy(mLocalTransforms.data(), builder->mLocalTransforms,
                 sizeof(math::mat4f) * mInstanceCount);
     }
-
-    // Allocate our instance buffer. We always allocate a size to match
-    // PerRenderableUib, regardless of the number of instances. This is because the buffer
-    // will get bound to the PER_RENDERABLE UBO, and we can't bind a buffer smaller than the
-    // full size of the UBO.
-    DriverApi& driver = engine.getDriverApi();
-    mHandle = driver.createBufferObject(sizeof(PerRenderableUib),
-        BufferObjectBinding::UNIFORM, BufferUsage::DYNAMIC);
-    if (auto name = mName; !name.empty()) {
-        driver.setDebugTag(mHandle.getId(), std::move(name));
-    }
 }
 
-void FInstanceBuffer::terminate(FEngine& engine) {
-    DriverApi& driver = engine.getDriverApi();
-    driver.destroyBufferObject(std::move(mHandle));
+void FInstanceBuffer::terminate(FEngine&) {
+    mHandle.clear();
+    mOffset = 0;
 }
 
 FInstanceBuffer::~FInstanceBuffer() noexcept = default;
@@ -127,27 +118,23 @@ void FInstanceBuffer::setLocalTransforms(
     memcpy(mLocalTransforms.data() + offset, localTransforms, sizeof(math::mat4f) * count);
 }
 
-void FInstanceBuffer::prepare(DriverApi& driver, math::mat4f const& rootTransform,
-        const PerRenderableData& ubo) {
+void FInstanceBuffer::prepare(
+            BufferObjectHandle ubh,
+            PerRenderableData* const UTILS_RESTRICT buffer, uint32_t const offset, uint32_t const count,
+            math::mat4f const& rootTransform, PerRenderableData const& ubo) {
 
-    // TODO: allocate this staging buffer from a pool.
-    constexpr uint32_t stagingBufferSize = sizeof(PerRenderableUib);
-    PerRenderableData* stagingBuffer = static_cast<PerRenderableData*>(malloc(stagingBufferSize));
-    // TODO: consider using JobSystem to parallelize this.
-    for (size_t i = 0, c = mInstanceCount; i < c; i++) {
-        stagingBuffer[i] = ubo;
-        math::mat4f const model = rootTransform * mLocalTransforms[i];
-        stagingBuffer[i].worldFromModelMatrix = model;
+    // there is a precondition check for this, so this assert really should never trigger
+    assert_invariant(count <= mInstanceCount);
 
+    for (size_t i = 0, c = count; i < c; i++) {
+        math::mat4f const model = rootTransform * mLocalTransforms[i];
         math::mat3f const m = math::mat3f::getTransformForNormals(model.upperLeft());
-        stagingBuffer[i].worldFromModelNormalMatrix = math::prescaleForNormals(m);
+        buffer[offset + i] = ubo;
+        buffer[offset + i].worldFromModelMatrix = model;
+        buffer[offset + i].worldFromModelNormalMatrix = math::prescaleForNormals(m);
     }
-    driver.updateBufferObject(mHandle, {
-            stagingBuffer, stagingBufferSize,
-            +[](void* buffer, size_t, void*) {
-                free(buffer);
-            }
-    }, 0);
+    mHandle = ubh;
+    mOffset = offset * sizeof(PerRenderableData);
 }
 
 } // namespace filament
diff --git a/filament/src/details/InstanceBuffer.h b/filament/src/details/InstanceBuffer.h
@@ -21,7 +21,6 @@
 
 #include <filament/InstanceBuffer.h>
 
-#include <backend/DriverApiForward.h>
 #include <backend/Handle.h>
 
 #include <math/mat4.h>
@@ -50,7 +49,10 @@ class FInstanceBuffer : public InstanceBuffer {
 
     void setLocalTransforms(math::mat4f const* localTransforms, size_t count, size_t offset);
 
-    void prepare(backend::DriverApi& driver, math::mat4f const& rootTransform, const PerRenderableData& ubo);
+    void prepare(
+            backend::BufferObjectHandle ubh,
+            PerRenderableData* buffer, uint32_t offset, uint32_t count,
+            math::mat4f const& rootTransform, PerRenderableData const& ubo);
 
     utils::CString const& getName() const noexcept { return mName; }
 
diff --git a/filament/src/details/View.cpp b/filament/src/details/View.cpp
@@ -723,15 +723,15 @@ void FView::prepare(FEngine& engine, DriverApi& driver, RootArenaScope& rootAren
                 VISIBLE_RENDERABLE | VISIBLE_DIR_SHADOW_RENDERABLE,
                 VISIBLE_RENDERABLE);
 
-        auto beginDirCastersOnly = partition(beginDirCasters, renderableData.end(),
+        auto const beginDirCastersOnly = partition(beginDirCasters, renderableData.end(),
                 VISIBLE_RENDERABLE | VISIBLE_DIR_SHADOW_RENDERABLE,
                 VISIBLE_RENDERABLE | VISIBLE_DIR_SHADOW_RENDERABLE);
 
-        auto endDirCastersOnly = partition(beginDirCastersOnly, renderableData.end(),
+        auto const endDirCastersOnly = partition(beginDirCastersOnly, renderableData.end(),
                 VISIBLE_RENDERABLE | VISIBLE_DIR_SHADOW_RENDERABLE,
                 VISIBLE_DIR_SHADOW_RENDERABLE);
 
-        auto endPotentialSpotCastersOnly = partition(endDirCastersOnly, renderableData.end(),
+        auto const endPotentialSpotCastersOnly = partition(endDirCastersOnly, renderableData.end(),
                 VISIBLE_DYN_SHADOW_RENDERABLE,
                 VISIBLE_DYN_SHADOW_RENDERABLE);
 
@@ -759,21 +759,8 @@ void FView::prepare(FEngine& engine, DriverApi& driver, RootArenaScope& rootAren
         scene->prepareVisibleRenderables(merged);
 
         // update those UBOs
-        const size_t size = merged.size() * sizeof(PerRenderableData);
-        if (size) {
-            if (mRenderableUBOSize < size) {
-                // allocate 1/3 extra, with a minimum of 16 objects
-                const size_t count = std::max(size_t(16u), (4u * merged.size() + 2u) / 3u);
-                mRenderableUBOSize = uint32_t(count * sizeof(PerRenderableData));
-                driver.destroyBufferObject(mRenderableUbh);
-                mRenderableUbh = driver.createBufferObject(
-                        mRenderableUBOSize + sizeof(PerRenderableUib),
-                        BufferObjectBinding::UNIFORM, BufferUsage::DYNAMIC);
-            } else {
-                // TODO: should we shrink the underlying UBO at some point?
-            }
-            assert_invariant(mRenderableUbh);
-            updateUBOs(driver, renderableData, merged, mRenderableUbh);
+        if (!merged.empty()) {
+            updateUBOs(driver, renderableData, merged);
 
             mCommonRenderableDescriptorSet.setBuffer(
                 engine.getPerRenderableDescriptorSetLayout(),
@@ -893,65 +880,6 @@ void FView::prepare(FEngine& engine, DriverApi& driver, RootArenaScope& rootAren
     colorPassDescriptorSet.prepareMaterialGlobals(mMaterialGlobals);
 }
 
-void FView::updateUBOs(
-        FEngine::DriverApi& driver,
-        FScene::RenderableSoa& renderableData,
-        utils::Range<uint32_t> visibleRenderables,
-        Handle<HwBufferObject> renderableUbh) noexcept {
-    FILAMENT_TRACING_CALL(FILAMENT_TRACING_CATEGORY_FILAMENT);
-
-    // don't allocate more than 16 KiB directly into the render stream
-    static constexpr size_t MAX_STREAM_ALLOCATION_COUNT = 64;   // 16 KiB
-    const size_t count = visibleRenderables.size();
-    PerRenderableData* buffer = [&]{
-        if (count >= MAX_STREAM_ALLOCATION_COUNT) {
-            // use the heap allocator
-            auto& bufferPoolAllocator = mSharedState->mBufferPoolAllocator;
-            return static_cast<PerRenderableData*>(bufferPoolAllocator.get(count * sizeof(PerRenderableData)));
-        }
-        // allocate space into the command stream directly
-        return driver.allocatePod<PerRenderableData>(count);
-    }();
-
-    PerRenderableData const* const uboData = renderableData.data<FScene::UBO>();
-    mat4f const* const worldTransformData = renderableData.data<FScene::WORLD_TRANSFORM>();
-
-    // prepare each InstanceBuffer.
-    FRenderableManager::InstancesInfo const* instancesData = renderableData.data<FScene::INSTANCES>();
-    for (uint32_t const i : visibleRenderables) {
-        auto& instancesInfo = instancesData[i];
-        if (UTILS_UNLIKELY(instancesInfo.buffer)) {
-            instancesInfo.buffer->prepare(driver, worldTransformData[i], uboData[i]);
-        }
-    }
-
-    // copy our data into the UBO for each visible renderable
-    for (uint32_t const i : visibleRenderables) {
-        buffer[i] = uboData[i];
-    }
-
-    // We capture state shared between Scene and the update buffer callback, because the Scene could
-    // be destroyed before the callback executes.
-    std::weak_ptr<SharedState>* const weakShared =
-            new (std::nothrow) std::weak_ptr(mSharedState);
-
-    // update the UBO
-    driver.resetBufferObject(renderableUbh);
-    driver.updateBufferObjectUnsynchronized(renderableUbh, {
-            buffer, count * sizeof(PerRenderableData),
-            +[](void* p, size_t const s, void* user) {
-                std::weak_ptr<SharedState> const* const weakShared =
-                        static_cast<std::weak_ptr<SharedState>*>(user);
-                if (s >= MAX_STREAM_ALLOCATION_COUNT * sizeof(PerRenderableData)) {
-                    if (auto state = weakShared->lock()) {
-                        state->mBufferPoolAllocator.put(p);
-                    }
-                }
-                delete weakShared;
-            }, weakShared
-    }, 0);
-}
-
 void FView::computeVisibilityMasks(
         uint8_t const visibleLayers,
         uint8_t const* UTILS_RESTRICT layers,
@@ -983,6 +911,100 @@ void FView::computeVisibilityMasks(
     }
 }
 
+void FView::updateUBOs(
+        FEngine::DriverApi& driver,
+        FScene::RenderableSoa& renderableData,
+        utils::Range<uint32_t> visibleRenderables) noexcept {
+    FILAMENT_TRACING_CALL(FILAMENT_TRACING_CATEGORY_FILAMENT);
+
+    FRenderableManager::InstancesInfo const* instancesData = renderableData.data<FScene::INSTANCES>();
+    PerRenderableData const* const uboData = renderableData.data<FScene::UBO>();
+    mat4f const* const worldTransformData = renderableData.data<FScene::WORLD_TRANSFORM>();
+
+    // regular renderables count
+    size_t const rcount = visibleRenderables.size();
+
+    // instanced renderables count
+    size_t icount = 0;
+    for (uint32_t const i : visibleRenderables) {
+        auto& instancesInfo = instancesData[i];
+        if (instancesInfo.buffer) {
+            assert_invariant(instancesInfo.count == instancesInfo.buffer->getInstanceCount());
+            icount += instancesInfo.count;
+        }
+    }
+
+    // total count of PerRenderableData slots we need
+    size_t const tcount = rcount + icount;
+
+    // resize the UBO accordingly
+    if (mRenderableUBOElementCount < tcount) {
+        // allocate 1/3 extra, with a minimum of 16 objects
+        const size_t count = std::max(size_t(16u), (4u * tcount + 2u) / 3u);
+        mRenderableUBOElementCount = count;
+        driver.destroyBufferObject(mRenderableUbh);
+        mRenderableUbh = driver.createBufferObject(
+                count * sizeof(PerRenderableData) + sizeof(PerRenderableUib),
+                BufferObjectBinding::UNIFORM, BufferUsage::DYNAMIC);
+    } else {
+        // TODO: should we shrink the underlying UBO at some point?
+    }
+    assert_invariant(mRenderableUbh);
+
+
+    // Allocate a staging CPU buffer:
+    // Don't allocate more than 16 KiB directly into the render stream
+    static constexpr size_t MAX_STREAM_ALLOCATION_COUNT = 64;   // 16 KiB
+    PerRenderableData* buffer = [&]{
+        if (tcount >= MAX_STREAM_ALLOCATION_COUNT) {
+            // use the heap allocator
+            auto& bufferPoolAllocator = mSharedState->mBufferPoolAllocator;
+            return static_cast<PerRenderableData*>(bufferPoolAllocator.get(tcount * sizeof(PerRenderableData)));
+        }
+        // allocate space into the command stream directly
+        return driver.allocatePod<PerRenderableData>(tcount);
+    }();
+
+
+    // TODO: consider using JobSystem to parallelize this.
+    uint32_t j = rcount;
+    for (uint32_t const i: visibleRenderables) {
+        // even the instanced ones are copied here because we need to maintain the offsets
+        // into the buffer currently (we could skip then because it won't be used, but
+        // for now it's more trouble than it's worth)
+        buffer[i] = uboData[i];
+
+        auto& instancesInfo = instancesData[i];
+        if (instancesInfo.buffer) {
+            instancesInfo.buffer->prepare(
+                    mRenderableUbh,
+                    buffer,  j, instancesInfo.count,
+                    worldTransformData[i], uboData[i]);
+            j += instancesInfo.count;
+        }
+    }
+
+    // We capture state shared between Scene and the update buffer callback, because the Scene could
+    // be destroyed before the callback executes.
+    std::weak_ptr<SharedState>* const weakShared = new(std::nothrow) std::weak_ptr(mSharedState);
+
+    // update the UBO
+    driver.resetBufferObject(mRenderableUbh);
+    driver.updateBufferObjectUnsynchronized(mRenderableUbh, {
+        buffer, tcount * sizeof(PerRenderableData),
+        +[](void* p, size_t const s, void* user) {
+            std::weak_ptr<SharedState> const* const weakShared =
+                    static_cast<std::weak_ptr<SharedState>*>(user);
+            if (s >= MAX_STREAM_ALLOCATION_COUNT * sizeof(PerRenderableData)) {
+                if (auto state = weakShared->lock()) {
+                    state->mBufferPoolAllocator.put(p);
+                }
+            }
+            delete weakShared;
+        }, weakShared
+    }, 0);
+}
+
 UTILS_NOINLINE
 /* static */ FScene::RenderableSoa::iterator FView::partition(
         FScene::RenderableSoa::iterator const begin,
diff --git a/filament/src/details/View.h b/filament/src/details/View.h
@@ -519,9 +519,8 @@ class FView : public View {
             Frustum const& frustum, FScene::RenderableSoa& renderableData) const noexcept;
 
     void updateUBOs(backend::DriverApi& driver,
-        FScene::RenderableSoa& renderableData,
-        utils::Range<uint32_t> visibleRenderables,
-        backend::Handle<backend::HwBufferObject> renderableUbh) noexcept;
+            FScene::RenderableSoa& renderableData,
+            utils::Range<uint32_t> visibleRenderables) noexcept;
 
     static void prepareVisibleLights(FLightManager const& lcm,
             utils::Slice<float> scratch,
@@ -613,7 +612,7 @@ class FView : public View {
     Range mVisibleRenderables;
     Range mVisibleDirectionalShadowCasters;
     Range mSpotLightShadowCasters;
-    uint32_t mRenderableUBOSize = 0;
+    uint32_t mRenderableUBOElementCount = 0;
     mutable bool mHasDirectionalLighting = false;
     mutable bool mHasDynamicLighting = false;
     mutable bool mHasShadowing = false;
