Add programmatic GPU frame capture via TestUtils.captureNextFrame. (#1675)

Introduces a one-shot, cross-backend API for requesting a GPU debugger
capture of the next submitted frame. Wraps bgfx's
`BGFX_FRAME_DEBUG_CAPTURE` flag, so the same call works with Xcode Metal
capture on macOS/iOS, PIX or RenderDoc on Windows, and RenderDoc on
Linux/Android.

Primary use case: producing a .gputrace for a failing validation test
without having to manually time a capture in the IDE. Add "capture":
true to a test entry in Apps/Playground/Scripts/config.json and the test
harness will request a capture on the screenshot frame; with the
platform GPU debugger attached, a capture document opens automatically.

Implementation:

- DeviceImpl owns an `std::atomic<bool> m_captureNextFrame`. `Frame()`
consumes it via exchange(false) and ORs `BGFX_FRAME_DEBUG_CAPTURE` into
the `bgfx::frame()` flags, guaranteeing the request is applied to
exactly one frame even under concurrent JS-thread calls.
- DeviceContext exposes `RequestCaptureNextFrame()`as a thin forwarder,
extending the existing public surface alongside RequestScreenShot.
- TestUtils plugin adds a cross-platform `captureNextFrame()` JS method
(no per-platform .mm/.cpp variants required).
validation_native.js honors an optional per-test "capture" flag and arms
a capture before the final `currentScene.render()` of the screenshot
frame.

When no GPU debugger is attached the bgfx flag is a no-op, so the API is
safe to leave in JS that ships in release builds.

Co-authored-by: Branimir Karadzic <branimirkaradzic@Bgmail.com>

Author: bkaradzic-microsoft

Apps/Playground/Scripts/validation_native.js

@@ -118,6 +118,9 @@
             }
             engine.runRenderLoop(function () {
                 try {
+                    if (test.capture && renderCount === 1 && TestUtils.captureNextFrame) {
+                        TestUtils.captureNextFrame();
+                    }
                     currentScene.render();
                     renderCount--;
 

Core/Graphics/InternalInclude/Babylon/Graphics/DeviceContext.h

@@ -96,6 +96,7 @@ namespace Babylon::Graphics
         Update GetUpdate(const char* updateName);
 
         void RequestScreenShot(std::function<void(std::vector<uint8_t>)> callback);
+        void RequestCaptureNextFrame();
         void SetRenderResetCallback(std::function<void()> callback);
 
         arcana::task<void, std::exception_ptr> ReadTextureAsync(bgfx::TextureHandle handle, gsl::span<uint8_t> data, uint8_t mipLevel = 0);

Core/Graphics/Source/DeviceContext.cpp

@@ -61,6 +61,11 @@ namespace Babylon::Graphics
         return m_graphicsImpl.RequestScreenShot(std::move(callback));
     }
 
+    void DeviceContext::RequestCaptureNextFrame()
+    {
+        m_graphicsImpl.RequestCaptureNextFrame();
+    }
+
     void DeviceContext::SetRenderResetCallback(std::function<void()> callback)
     {
         return m_graphicsImpl.SetRenderResetCallback(std::move(callback));

Core/Graphics/Source/DeviceImpl.cpp

@@ -373,6 +373,11 @@ namespace Babylon::Graphics
         m_screenShotCallbacks.push(std::move(callback));
     }
 
+    void DeviceImpl::RequestCaptureNextFrame()
+    {
+        m_captureNextFrame.store(true);
+    }
+
     arcana::task<void, std::exception_ptr> DeviceImpl::ReadTextureAsync(bgfx::TextureHandle handle, gsl::span<uint8_t> data, uint8_t mipLevel)
     {
         arcana::task_completion_source<void, std::exception_ptr> completionSource{};
@@ -462,7 +467,8 @@ namespace Babylon::Graphics
         RequestScreenShots();
 
         // Advance frame and render!
-        uint32_t frameNumber{bgfx::frame()};
+        const uint8_t frameFlags = m_captureNextFrame.exchange(false) ? BGFX_FRAME_DEBUG_CAPTURE : 0;
+        uint32_t frameNumber{bgfx::frame(frameFlags)};
 
         // Process read texture requests.
         while (!m_readTextureRequests.empty() && m_readTextureRequests.front().first <= frameNumber)

Core/Graphics/Source/DeviceImpl.h

@@ -87,6 +87,8 @@ namespace Babylon::Graphics
 
         void RequestScreenShot(std::function<void(std::vector<uint8_t>)> callback);
 
+        void RequestCaptureNextFrame();
+
         arcana::task<void, std::exception_ptr> ReadTextureAsync(bgfx::TextureHandle handle, gsl::span<uint8_t> data, uint8_t mipLevel);
 
         using CaptureCallbackTicketT = arcana::ticketed_collection<std::function<void(const BgfxCallback::CaptureData&)>>::ticket;
@@ -123,6 +125,8 @@ namespace Babylon::Graphics
 
         std::atomic<bgfx::ViewId> m_nextViewId{0};
 
+        std::atomic<bool> m_captureNextFrame{false};
+
         std::optional<arcana::cancellation_source> m_cancellationSource{};
 
         struct

Plugins/TestUtils/Source/TestUtils.cpp

@@ -91,6 +91,11 @@ namespace Babylon::Plugins::Internal
             });
         });
     }
+
+    void TestUtils::CaptureNextFrame(const Napi::CallbackInfo& /*info*/)
+    {
+        m_deviceContext.RequestCaptureNextFrame();
+    }
 }
 
 namespace Babylon::Plugins::TestUtils

Plugins/TestUtils/Source/TestUtils.h

@@ -37,6 +37,7 @@ namespace Babylon::Plugins::Internal
                     ParentT::InstanceMethod("getImageData", &TestUtils::GetImageData),
                     ParentT::InstanceMethod("getOutputDirectory", &TestUtils::GetOutputDirectory),
                     ParentT::InstanceMethod("getFrameBufferData", &TestUtils::GetFrameBufferData),
+                    ParentT::InstanceMethod("captureNextFrame", &TestUtils::CaptureNextFrame),
                 },
                 &window);
 
@@ -69,6 +70,7 @@ namespace Babylon::Plugins::Internal
         Napi::Value DecodeImage(const Napi::CallbackInfo& info);
         Napi::Value GetImageData(const Napi::CallbackInfo& info);
         void GetFrameBufferData(const Napi::CallbackInfo& info);
+        void CaptureNextFrame(const Napi::CallbackInfo& info);
 
         JsRuntime& m_runtime;
         Graphics::DeviceContext& m_deviceContext;