Added LoadBalancing class that monitors frame performance and memory metrics which will enable adjustment of scene graph loads to maintain performance/memory utilization within targets.

robertosfield · robertosfield · commit 97c4e637dffb · 2026-02-26T18:03:35.000Z
diff --git a/include/vsg/app/LoadBalancing.h b/include/vsg/app/LoadBalancing.h
@@ -0,0 +1,46 @@
+#pragma once
+
+/* <editor-fold desc="MIT License">
+
+Copyright(c) 2026 Robert Osfield
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+</editor-fold> */
+
+#include <vsg/core/Inherit.h>
+#include <vsg/ui/FrameStamp.h>
+
+namespace vsg
+{
+
+    // forward declare
+    class Viewer;
+
+    /// LoadBalancing is a base class for specifying the Camera view matrix and its inverse.
+    class VSG_DECLSPEC LoadBalancing : public Inherit<Object, LoadBalancing>
+    {
+    public:
+        LoadBalancing();
+        explicit LoadBalancing(const LoadBalancing& rhs, const CopyOp& copyop = {});
+
+        virtual void update(Viewer& viewer);
+
+        time_point previousFrameTime = std::numeric_limits<time_point>::max();
+
+        double targetFrameTime = 0.016; // seconds
+        double targetCPUTime = 0.008; // seconds
+        double targetGPUTime = 0.008; // seconds
+        double targetGPUMemoryUtilization = 0.9; // ratio
+
+    protected:
+        ~LoadBalancing();
+    };
+    VSG_type_name(vsg::LoadBalancing);
+
+
+} // namespace vsg
diff --git a/include/vsg/app/Viewer.h b/include/vsg/app/Viewer.h
@@ -18,6 +18,7 @@ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLI
 #include <vsg/app/RecordAndSubmitTask.h>
 #include <vsg/app/UpdateOperations.h>
 #include <vsg/app/Window.h>
+#include <vsg/app/LoadBalancing.h>
 #include <vsg/threading/Barrier.h>
 #include <vsg/threading/FrameBlock.h>
 #include <vsg/utils/Instrumentation.h>
@@ -129,6 +130,8 @@ namespace vsg
         ref_ptr<ActivityStatus> status;
         std::list<std::thread> threads;
 
+        ref_ptr<LoadBalancing> loadBalancing;
+
         void setupThreading();
         void stopThreading();
 
diff --git a/include/vsg/utils/Profiler.h b/include/vsg/utils/Profiler.h
@@ -42,6 +42,7 @@ namespace vsg
             const SourceLocation* sourceLocation = nullptr;
             const Object* object = nullptr;
             uint64_t reference = 0;
+            uint64_t frameCount = 0;
             std::thread::id thread_id = {};
         };
 
@@ -134,6 +135,7 @@ namespace vsg
         };
 
         mutable size_t frameIndex = 0;
+        mutable std::atomic_uint64_t frameCount = 0;
         mutable std::vector<FrameStatsCollection> perFrameGPUStats;
 
         VkResult getGpuResults(FrameStatsCollection& frameStats) const;
diff --git a/src/vsg/CMakeLists.txt b/src/vsg/CMakeLists.txt
@@ -187,6 +187,7 @@ set(SOURCES
     app/UpdateOperations.cpp
     app/RecordTraversal.cpp
     app/CompileTraversal.cpp
+    app/LoadBalancing.cpp
 
     raytracing/AccelerationGeometry.cpp
     raytracing/AccelerationStructure.cpp
diff --git a/src/vsg/app/LoadBalancing.cpp b/src/vsg/app/LoadBalancing.cpp
@@ -0,0 +1,132 @@
+/* <editor-fold desc="MIT License">
+
+Copyright(c) 2026 Robert Osfield
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+</editor-fold> */
+
+#include <vsg/app/LoadBalancing.h>
+#include <vsg/app/Viewer.h>
+#include <vsg/io/Logger.h>
+#include <vsg/utils/Profiler.h>
+
+using namespace vsg;
+
+LoadBalancing::LoadBalancing()
+{
+}
+
+LoadBalancing::LoadBalancing(const LoadBalancing& rhs, const CopyOp& copyop) :
+    Inherit(rhs, copyop)
+{
+}
+
+LoadBalancing::~LoadBalancing()
+{
+}
+
+void LoadBalancing::update(Viewer& viewer)
+{
+    if (previousFrameTime == std::numeric_limits<time_point>::max())
+    {
+        previousFrameTime = viewer.getFrameStamp()->time;
+        return;
+    }
+
+    double frameDelta = (previousFrameTime == std::numeric_limits<time_point>::max()) ? 0.0 : std::chrono::duration<double, std::chrono::seconds::period>(viewer.getFrameStamp()->time - previousFrameTime).count();
+    uint64_t previousFrameCount = viewer.getFrameStamp()->frameCount - 1;
+
+    // vsg::info("LoadBalancing::update( ", &viewer, " ) ", viewer.getFrameStamp()->frameCount, ", ", frameDelta);
+
+    double frameTargetRatio = frameDelta/targetFrameTime;
+    double cpuTargetRatio = 0.0;
+    double gpuTargetRatio = 0.0;
+
+    if (auto profiler = viewer.instrumentation.cast<Profiler>())
+    {
+        auto& log = profiler->log;
+
+        size_t targetFrameCount = 16;
+
+        double max_cpu_durection = 0.0;
+        double max_gpu_durection = 0.0;
+
+        auto& frameIndices = log->frameIndices;
+        auto last_frame = frameIndices.end();
+        auto first_frame = (frameIndices.size() > targetFrameCount) ? (frameIndices.end() - targetFrameCount) : frameIndices.begin();
+        for(auto itr = first_frame; itr != last_frame; ++itr)
+        {
+            auto first_index = *itr;
+            const auto& first = log->entry(first_index);
+            auto last_index = first.reference;
+
+            auto cpu_duration = 0.0;
+            auto gpu_duration = 0.0;
+
+            for(auto i = first_index; i <= last_index;)
+            {
+                if (log->entry(i).type == ProfileLog::COMMAND_BUFFER)
+                {
+                    const auto& start = log->entry(i);
+                    const auto& end = log->entry(start.reference);
+                    if (start.gpuTime != 0 && end.gpuTime != 0)
+                    {
+                        gpu_duration = static_cast<double>(end.gpuTime - start.gpuTime) * log->timestampScaleToMilliseconds * 0.001;
+                        if (gpu_duration > max_gpu_durection)
+                        {
+                            max_gpu_durection = gpu_duration;
+                        }
+                    }
+
+                    cpu_duration = std::abs(std::chrono::duration<double, std::chrono::seconds::period>(end.cpuTime - start.cpuTime).count());
+
+                    if (cpu_duration > max_cpu_durection)
+                    {
+                        max_cpu_durection = cpu_duration;
+                    }
+
+                    i = start.reference+1;
+                }
+                else
+                {
+                    ++i;
+                }
+            }
+
+
+
+#if 0
+            if (first.sourceLocation) vsg::info("    entry(", first_index,") { ", int(first.type), ", ", first.reference, ", func=", first.sourceLocation->function, ", cpu_duration = ", cpu_duration, ", gpu_duration = ",  gpu_duration, "} ");
+            else vsg::info("    entry(", first_index,") { ", int(first.type), ", ", first.reference, " }");
+
+            if (max_gpu_durection > targetGPUTime)
+            {
+                vsg::info("   GPU time too high ", max_gpu_durection, "ms is greated than target ", targetGPUTime, "ms");
+            }
+#endif
+        }
+
+        cpuTargetRatio = max_cpu_durection/targetCPUTime;
+        gpuTargetRatio = max_gpu_durection/targetGPUTime;
+    }
+
+    double maxTargetRatio = std::max({frameTargetRatio, cpuTargetRatio, gpuTargetRatio});
+
+    if (maxTargetRatio > 2.0)
+    {
+        vsg::info("Frame break on frameCount = ", previousFrameCount, " : maxTargetRatio = ", maxTargetRatio, " { frame = ", frameTargetRatio, ", cpu = ", cpuTargetRatio, ", gpu = ", gpuTargetRatio, " }");
+    }
+    else if (maxTargetRatio > 1.2)
+    {
+        vsg::info("Frame targets exceeded on frameCount = ", previousFrameCount,  " : maxTargetRatio = ", maxTargetRatio, " { frame = ", frameTargetRatio, ", cpu = ", cpuTargetRatio, ", gpu = ", gpuTargetRatio, " }");
+    }
+
+    previousFrameTime = viewer.getFrameStamp()->time;
+}
+
+
diff --git a/src/vsg/app/Viewer.cpp b/src/vsg/app/Viewer.cpp
@@ -31,6 +31,7 @@ Viewer::Viewer() :
     updateOperations(UpdateOperations::create()),
     animationManager(AnimationManager::create()),
     status(vsg::ActivityStatus::create()),
+    loadBalancing(vsg::LoadBalancing::create()),
     _firstFrame(true),
     _start_point(clock::now()),
     _frameStamp(FrameStamp::create(_start_point, 0, 0.0))
@@ -793,6 +794,8 @@ void Viewer::update()
 {
     CPU_INSTRUMENTATION_L1_NC(instrumentation, "Viewer update", COLOR_UPDATE);
 
+    if (loadBalancing) loadBalancing->update(*this);
+
     // merge any updates from the DatabasePager
     for (const auto& task : recordAndSubmitTasks)
     {
diff --git a/src/vsg/utils/Profiler.cpp b/src/vsg/utils/Profiler.cpp
@@ -87,7 +87,9 @@ uint64_t ProfileLog::report(std::ostream& out, uint64_t reference)
         {
             ++i;
 
-            out << indent << "{ " << typeNames[first.type] << ", cpu_duration = " << cpu_duration << "ms, ";
+            out << indent << "{ " << typeNames[first.type];
+            if (first.type==ProfileLog::FRAME) out << ", frameCount = "<<first.frameCount;
+            out << ", cpu_duration = " << cpu_duration << "ms, ";
             if (gpu_duration != 0.0) out << ", gpu_duration = " << gpu_duration << "ms, ";
 
             auto itr = threadNames.find(first.thread_id);
@@ -107,7 +109,9 @@ uint64_t ProfileLog::report(std::ostream& out, uint64_t reference)
                 out << indent << "} ";
             }
 
-            out << typeNames[first.type] << ", cpu_duration = " << cpu_duration << "ms, ";
+            out << typeNames[first.type];
+            if (first.type==ProfileLog::FRAME) out << ", frameCount = "<<first.frameCount;
+            out << ", cpu_duration = " << cpu_duration << "ms, ";
             if (gpu_duration != 0.0) out << ", gpu_duration = " << gpu_duration << "ms, ";
 
             auto itr = threadNames.find(first.thread_id);
@@ -173,6 +177,10 @@ VkResult Profiler::getGpuResults(FrameStatsCollection& frameStats) const
                 }
                 gpuStats->queryIndex = 0;
             }
+            else if (result == VK_NOT_READY)
+            {
+                debug("Profiler::getGpuResults() ", gpuStats, ", query failed with result = ", result);
+            }
             else
             {
                 info("Profiler::getGpuResults() ", gpuStats, ", query failed with result = ", result);
@@ -190,9 +198,12 @@ void Profiler::setThreadName(const std::string& name) const
 
 void Profiler::enterFrame(const SourceLocation* sl, uint64_t& reference, FrameStamp& frameStamp) const
 {
+    frameCount = frameStamp.frameCount;
+
     auto& entry = log->enter(reference, ProfileLog::FRAME);
     entry.sourceLocation = sl;
     entry.object = &frameStamp;
+    entry.frameCount = frameCount;
 
     getGpuResults(perFrameGPUStats[frameIndex]);
 }
@@ -203,6 +214,8 @@ void Profiler::leaveFrame(const SourceLocation* sl, uint64_t& reference, FrameSt
     auto& entry = log->leave(reference, ProfileLog::FRAME);
     entry.sourceLocation = sl;
     entry.object = &frameStamp;
+    entry.frameCount = frameCount;
+
     uint64_t endReference = reference;
 
     if (endReference >= static_cast<uint64_t>(log->entries.size()))
@@ -236,6 +249,7 @@ void Profiler::enter(const SourceLocation* sl, uint64_t& reference, const Object
         auto& entry = log->enter(reference, ProfileLog::CPU);
         entry.sourceLocation = sl;
         entry.object = object;
+        entry.frameCount = frameCount;
     }
 }
 
@@ -246,6 +260,7 @@ void Profiler::leave(const SourceLocation* sl, uint64_t& reference, const Object
         auto& entry = log->leave(reference, ProfileLog::CPU);
         entry.sourceLocation = sl;
         entry.object = object;
+        entry.frameCount = frameCount;
     }
 }
 
@@ -285,6 +300,7 @@ void Profiler::enterCommandBuffer(const SourceLocation* sl, uint64_t& reference,
         auto& entry = log->enter(reference, ProfileLog::COMMAND_BUFFER);
         entry.sourceLocation = sl;
         entry.object = &commandBuffer;
+        entry.frameCount = frameCount;
 
         if (gpuStats)
         {
@@ -303,6 +319,7 @@ void Profiler::leaveCommandBuffer(const SourceLocation* sl, uint64_t& reference,
         auto& entry = log->leave(reference, ProfileLog::COMMAND_BUFFER);
         entry.sourceLocation = sl;
         entry.object = &commandBuffer;
+        entry.frameCount = frameCount;
 
         if (commandBuffer.gpuStats) commandBuffer.gpuStats->writeGpuTimestamp(commandBuffer, reference, VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT);
     }
@@ -315,6 +332,7 @@ void Profiler::enter(const SourceLocation* sl, uint64_t& reference, CommandBuffe
         auto& entry = log->enter(reference, ProfileLog::GPU);
         entry.sourceLocation = sl;
         entry.object = object;
+        entry.frameCount = frameCount;
 
         if (commandBuffer.gpuStats) commandBuffer.gpuStats->writeGpuTimestamp(commandBuffer, reference, VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT);
     }
@@ -327,6 +345,7 @@ void Profiler::leave(const SourceLocation* sl, uint64_t& reference, CommandBuffe
         auto& entry = log->leave(reference, ProfileLog::GPU);
         entry.sourceLocation = sl;
         entry.object = object;
+        entry.frameCount = frameCount;
 
         if (commandBuffer.gpuStats) commandBuffer.gpuStats->writeGpuTimestamp(commandBuffer, reference, VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT);
     }
