bench: --frames + --no-vsync + BENCH stdout line (Win32)

Adds the BabylonNative-side of the cross-app perf comparison driven by
webgpu-cross-platform-app/tools/bench/run-bench.mjs. Same CLI contract,
same BENCH stdout format, so the runner can treat both apps uniformly.

CLI

- Apps/Playground/Shared/CommandLine.{h,cpp}: new fields
  PlaygroundOptions::Frames and PlaygroundOptions::NoVsync, parsed via
  the existing FlagSpec table. --frames N also implicitly sets
  NoVsync=true (matches DawnTest), --no-vsync standalone is supported
  for indefinite runs where vsync should still be off.

Graphics

- Core/Graphics/Include/Shared/Babylon/Graphics/Device.h: add
  Configuration::VSync (default true) so non-Playground consumers
  keep current behavior.
- Core/Graphics/Source/DeviceImpl.cpp: drop the BGFX_RESET_VSYNC bit
  from the reset mask when config.VSync is false. With vsync on the
  loop is pinned to the display refresh and dwarfs the per-frame
  measurement.
- Apps/Playground/Shared/AppContext.cpp: plumb options.NoVsync to
  graphicsConfig.VSync.

Bench

- Apps/Playground/Shared/BenchTimer.{h,cpp}: PascalCase mirror of
  DawnTest's framework/bench API (StartFrame/EndFrame/PrintBenchLine),
  same metric set (min/avg/max/p95 + wall), first frame is warmup.
- Apps/Playground/Win32/App.cpp: wrap each main-loop iteration in the
  timer (Finish -> FinishRender -> StartRender -> Start -> PeekMessage/
  Dispatch). When --frames is set, PostQuitMessage(0) on hitting the
  budget so the loop exits without depending on user input. Print the
  BENCH line before returning. Scene name is derived from the script
  stem so the runner can correlate cells across apps.
- Apps/Playground/CMakeLists.txt: register BenchTimer sources.

macOS/iOS/Android Playground entries are intentionally not wired here.
They route command-line args through MTKView delegates / JNI and need
larger refactors to feed --frames into the render loop. CI bench is
win32-only for now (no GPU on GH mac runners); local mac/Android bench
will follow.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: CedricGuillemet

Apps/Playground/CMakeLists.txt

@@ -21,6 +21,8 @@ set(SCRIPTS
 set(SOURCES
     "Shared/AppContext.cpp"
     "Shared/AppContext.h"
+    "Shared/BenchTimer.cpp"
+    "Shared/BenchTimer.h"
     "Shared/CommandLine.cpp"
     "Shared/CommandLine.h"
     "Shared/Diagnostics.cpp"

Apps/Playground/Shared/AppContext.cpp

@@ -78,6 +78,10 @@ AppContext::AppContext(
     graphicsConfig.Width = width;
     graphicsConfig.Height = height;
     graphicsConfig.MSAASamples = 4;
+    // Bench mode (--frames / --no-vsync) measures pure render throughput,
+    // not display refresh cap. Honor the CLI flag before the device is
+    // created so the BGFX_RESET_VSYNC bit is dropped on first init.
+    graphicsConfig.VSync = !playgroundOptions.NoVsync;
 
     m_device.emplace(graphicsConfig);
     m_deviceUpdate.emplace(m_device->GetUpdate("update"));

Apps/Playground/Shared/BenchTimer.cpp

@@ -0,0 +1,88 @@
+#include "BenchTimer.h"
+
+#include <algorithm>
+#include <chrono>
+#include <cstdio>
+
+namespace Bench
+{
+    double MonotonicMillis()
+    {
+        using namespace std::chrono;
+        static const auto kEpoch = steady_clock::now();
+        return duration<double, std::milli>(steady_clock::now() - kEpoch).count();
+    }
+
+    void FrameTimer::SetWarmupFrames(int n)
+    {
+        m_warmupFrames = n < 0 ? 0 : n;
+    }
+
+    void FrameTimer::Reserve(std::size_t n)
+    {
+        m_deltas.reserve(n);
+    }
+
+    void FrameTimer::StartFrame()
+    {
+        m_startMs = MonotonicMillis();
+        ++m_seenFrames;
+    }
+
+    void FrameTimer::EndFrame()
+    {
+        if (m_seenFrames <= m_warmupFrames)
+        {
+            return;
+        }
+        m_deltas.push_back(MonotonicMillis() - m_startMs);
+    }
+
+    FrameStats FrameTimer::Finish() const
+    {
+        FrameStats s{};
+        if (m_deltas.empty())
+        {
+            return s;
+        }
+
+        std::vector<double> sorted(m_deltas);
+        std::sort(sorted.begin(), sorted.end());
+
+        double sum = 0.0;
+        for (double d : sorted)
+        {
+            sum += d;
+        }
+
+        const std::size_t n = sorted.size();
+        std::size_t pIdx = static_cast<std::size_t>(0.95 * n);
+        if (pIdx >= n)
+        {
+            pIdx = n - 1;
+        }
+
+        s.frameCount = static_cast<int>(n);
+        s.wallMs     = sum;
+        s.minMs      = sorted.front();
+        s.avgMs      = sum / static_cast<double>(n);
+        s.maxMs      = sorted.back();
+        s.p95Ms      = sorted[pIdx];
+        return s;
+    }
+
+    void FrameTimer::PrintBenchLine(const std::string& sceneName) const
+    {
+        const FrameStats s = Finish();
+        std::fprintf(stdout,
+            "BENCH scene=%s frames=%d wall_ms=%.3f min_ms=%.3f avg_ms=%.3f max_ms=%.3f p95_ms=%.3f\n",
+            sceneName.c_str(),
+            s.frameCount,
+            s.wallMs,
+            s.minMs,
+            s.avgMs,
+            s.maxMs,
+            s.p95Ms);
+        std::fflush(stdout);
+    }
+}

Apps/Playground/Shared/BenchTimer.h

@@ -0,0 +1,51 @@
+// BenchTimer — per-frame wall-time collector used by Playground bench mode.
+//
+// Mirrors the DawnTest framework/bench.h API so the emitted "BENCH …" line
+// is identical across both apps and tools/bench/run-bench.mjs can parse a
+// single format.
+
+#pragma once
+
+#include <cstddef>
+#include <string>
+#include <vector>
+
+namespace Bench
+{
+    struct FrameStats
+    {
+        int    frameCount = 0;   // included frames (excludes warmup)
+        double wallMs     = 0;
+        double minMs      = 0;
+        double avgMs      = 0;
+        double maxMs      = 0;
+        double p95Ms      = 0;
+    };
+
+    class FrameTimer
+    {
+    public:
+        // Default warmup is 1 frame (shader compile + first-use upload is
+        // almost always an outlier).
+        void SetWarmupFrames(int n);
+        void Reserve(std::size_t n);
+
+        void StartFrame();
+        void EndFrame();
+
+        FrameStats Finish() const;
+
+        // Emits exactly:
+        //   BENCH scene=<sceneName> frames=N wall_ms=X min_ms=X avg_ms=X max_ms=X p95_ms=X\n
+        // on stdout, then flushes.
+        void PrintBenchLine(const std::string& sceneName) const;
+
+    private:
+        int                 m_warmupFrames = 1;
+        int                 m_seenFrames   = 0;
+        double              m_startMs      = 0;
+        std::vector<double> m_deltas;
+    };
+
+    double MonotonicMillis();
+}

Apps/Playground/Shared/CommandLine.cpp

@@ -232,6 +232,33 @@ namespace
                     err = "invalid --test-index value: " + ierr;
                 }
             }},
+
+        FlagSpec{"--frames", "", FlagKind::ValueRequired, "N",
+            "Render N frames then exit. Disables vsync.",
+            "                              Emits a single 'BENCH scene=... frames=... ...'\n"
+            "                              line on stdout, parsed by\n"
+            "                              tools/bench/run-bench.mjs to compute summary\n"
+            "                              statistics. When set, vsync is disabled\n"
+            "                              automatically so per-frame timings reflect\n"
+            "                              actual GPU/CPU work rather than the display\n"
+            "                              refresh cap.\n",
+            [](PlaygroundOptions& o, std::string_view value, std::string& err) {
+                int n = 0;
+                if (!ParseIntStrict(value, n) || n < 1 || n > 1000000)
+                {
+                    err = "invalid --frames value (expected positive integer): '" + std::string{value} + "'";
+                    return;
+                }
+                o.Frames = n;
+                o.NoVsync = true;
+            }},
+
+        FlagSpec{"--no-vsync", "", FlagKind::Boolean, "",
+            "Disable vsync on the swap chain.",
+            "                              Implied by --frames; can be set on its own for\n"
+            "                              interactive perf testing without a fixed frame\n"
+            "                              budget.\n",
+            [](PlaygroundOptions& o, std::string_view, std::string&) { o.NoVsync = true; }},
     };
 
     struct FlagMatch

Apps/Playground/Shared/CommandLine.h

@@ -21,6 +21,21 @@ struct PlaygroundOptions
     std::optional<bool> DebugTrace;
     std::optional<std::string> PerfTrace;
 
+    // Benchmark mode.
+    //
+    // When `Frames > 0`, the host's render loop exits after that many
+    // rendered frames (counted post-warmup by the BenchTimer) and emits a
+    // single line of the form:
+    //   BENCH scene=<name> frames=N wall_ms=X min_ms=X avg_ms=X max_ms=X p95_ms=X
+    // on stdout, parsed by tools/bench/run-bench.mjs. Setting `Frames`
+    // implicitly enables `NoVsync` so the timing reflects actual GPU/CPU
+    // throughput rather than the display refresh cap.
+    //
+    // `NoVsync` may also be set independently of `Frames` for interactive
+    // perf testing.
+    int Frames = 0;
+    bool NoVsync = false;
+
     // 1-based frame index at which to call TestUtils.captureNextFrame()
     // (RenderDoc capture trigger). When set, the runner extends each test's
     // render budget so the .rdc finalizes. Requires renderdoc.dll to be

Apps/Playground/Win32/App.cpp

@@ -3,6 +3,7 @@
 
 #include "App.h"
 #include <Shared/AppContext.h>
+#include <Shared/BenchTimer.h>
 #include <Shared/CommandLine.h>
 #include <Shared/Diagnostics.h>
 #include <Babylon/Plugins/TestUtils.h>
@@ -202,6 +203,27 @@ int APIENTRY wWinMain(_In_ HINSTANCE hInstance,
 
     MSG msg{};
 
+    // Bench mode: per-frame timing collector that emits the BENCH line on
+    // exit. Only armed when --frames was passed; default-constructed
+    // FrameTimer with zero work otherwise.
+    Bench::FrameTimer benchTimer;
+    int benchFrames = 0;  // count of rendered frames in this session
+    std::string benchSceneName;
+    if (options.Frames > 0)
+    {
+        benchTimer.Reserve(static_cast<std::size_t>(options.Frames));
+        // Scene name comes from the first positional script arg (stem); if
+        // none was passed, fall back to "experience" (the default script).
+        if (!options.Scripts.empty())
+        {
+            benchSceneName = std::filesystem::path{options.Scripts.front()}.stem().string();
+        }
+        else
+        {
+            benchSceneName = "experience";
+        }
+    }
+
     // Main message loop:
     while (msg.message != WM_QUIT)
     {
@@ -215,10 +237,28 @@ int APIENTRY wWinMain(_In_ HINSTANCE hInstance,
         {
             if (appContext)
             {
+                // Time the full frame: from the moment we ask the worker to
+                // finish the previous frame's JS render-loop pass, through
+                // FinishRenderingCurrentFrame (GPU present), the next
+                // StartRenderingCurrentFrame, the next DeviceUpdate.Start
+                // (which kicks the next JS render-loop pass), AND the
+                // PeekMessage / Translate / Dispatch that follows. This
+                // matches DawnTest's notion of "frame": the wall-clock
+                // interval between two consecutive present completions, so
+                // the BENCH line values are directly comparable.
+                benchTimer.StartFrame();
                 appContext->DeviceUpdate().Finish();
                 appContext->Device().FinishRenderingCurrentFrame();
                 appContext->Device().StartRenderingCurrentFrame();
                 appContext->DeviceUpdate().Start();
+                if (options.Frames > 0)
+                {
+                    ++benchFrames;
+                    if (benchFrames >= options.Frames)
+                    {
+                        PostQuitMessage(0);
+                    }
+                }
             }
 
             result = PeekMessage(&msg, nullptr, 0, 0, PM_REMOVE) && msg.message != WM_QUIT;
@@ -232,9 +272,24 @@ int APIENTRY wWinMain(_In_ HINSTANCE hInstance,
                 DispatchMessage(&msg);
             }
         }
+        // Close out the frame interval after we've drained pending window
+        // messages for this loop iteration. EndFrame is a no-op until past
+        // warmup, so it's safe to call every iteration including those
+        // where appContext is still being constructed.
+        if (!minimized && appContext)
+        {
+            benchTimer.EndFrame();
+        }
     }
 
     Diagnostics::SetExitCode(static_cast<int>(msg.wParam));
+    // Emit the BENCH line *before* return so it reaches stdout (which is
+    // unbuffered here) even when the host gets torn down by the runtime
+    // exit hook after we return.
+    if (options.Frames > 0)
+    {
+        benchTimer.PrintBenchLine(benchSceneName);
+    }
     return (int)msg.wParam;
 }
 

Core/Graphics/Include/Shared/Babylon/Graphics/Device.h

@@ -53,6 +53,12 @@ namespace Babylon::Graphics
         // When enabled, back buffer will be premultiplied with alpha value.
         bool AlphaPremultiplied{};
 
+        // When true (default), the swap chain waits for vertical sync. Set
+        // false for benchmark / latency-sensitive scenarios that want to
+        // measure render throughput without the display refresh cap.
+        // Mapped to BGFX_RESET_VSYNC in the bgfx backend.
+        bool VSync{true};
+
         // Format to use when creating the depth/stencil texture for the back buffer.
         // Specify DepthStencilFormat::None to not create a depth/stencil texture.
         DepthStencilFormat BackBufferDepthStencilFormat{DepthStencilFormat::Depth24Stencil8};

Core/Graphics/Source/DeviceImpl.cpp

@@ -53,7 +53,7 @@ namespace Babylon::Graphics
         // init.resolution
         //
 
-        init.resolution.reset = BGFX_RESET_VSYNC | BGFX_RESET_MAXANISOTROPY | BGFX_RESET_FLIP_AFTER_RENDER;
+        init.resolution.reset = (config.VSync ? BGFX_RESET_VSYNC : 0u) | BGFX_RESET_MAXANISOTROPY | BGFX_RESET_FLIP_AFTER_RENDER;
         init.resolution.maxFrameLatency = 1;
 
         UpdateSize(config.Width, config.Height);