Throw from Device::UpdateDevice when called while rendering is enabled

Before this change, UpdateDevice's effect on a Device whose bgfx is already
initialized was silently buffered: the new device pointer was stored in
Bgfx.InitState.platformData, but bgfx::init does not run again until the
caller does a DisableRendering / EnableRendering cycle, and EnableRendering
early-outs while already initialized. The result was a swap that appeared to
succeed but in which the device never actually changed -- a footgun that's
hard to diagnose.

This commit:

  - Throws std::runtime_error from DeviceImpl::UpdateDevice when called with
    Bgfx.Initialized == true. The throw message names the required call
    sequence (DisableRendering first).
  - Documents the contract on the public Device::UpdateDevice declaration in
    Device.h, including the canonical D3D11/D3D12 device-removed recovery
    sequence.
  - Adds TEST(Device, UpdateDeviceThrowsWhenRenderingEnabled) that exercises
    the contract: pre-init UpdateDevice is permitted, post-init throws,
    and the swap completes successfully after DisableRendering.

UpdateWindow has the same surface-level contract but is left unchanged in
this PR -- the Android Playground's surfaceChanged JNI callback calls
UpdateWindow followed by UpdateSize while bgfx is initialized, and on the
OpenGL backend bgfx::reset (triggered by UpdateSize) re-creates the EGL
surface from the new ANativeWindow*. So the "init-only vs. reset-applicable"
classification is more nuanced for UpdateWindow than for UpdateDevice, and
narrowing the change to UpdateDevice avoids breaking the Android flow.

UpdateBackBuffer, UpdateSize, UpdateMSAA, and UpdateAlphaPremultiplied are
left unchanged because they are reset-applicable: bgfx::reset (called from
UpdateSize) reads g_platformData.backBuffer and init.resolution.reset, so
those updates take effect mid-frame as expected. The existing
TEST(Device, BackBuffer) exercises that flow and continues to pass.

Local verification: full UnitTests suite on Win32 D3D11 PASSED including
the new test; Win32 D3D12 builds and runs (UniformPadding sample passes).

[Created by Copilot on behalf of @bghgary]

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

Author: bghgary

Apps/UnitTests/Source/Tests.Device.D3D11.cpp

@@ -101,3 +101,49 @@ TEST(Device, BackBuffer)
         device.FinishRenderingCurrentFrame();
     }
 }
+
+// Verifies that UpdateDevice throws when called while bgfx is initialized.
+//
+// Without the throw, UpdateDevice would silently store the new device pointer in the bgfx init
+// state without applying it (bgfx::init only runs on the next EnableRendering, and EnableRendering
+// early-outs while already initialized). This is a footgun: the caller's swap appears to succeed
+// but the device never actually changes.
+TEST(Device, UpdateDeviceThrowsWhenRenderingEnabled)
+{
+    winrt::com_ptr<ID3D11Device> deviceA = CreateDevice();
+    winrt::com_ptr<ID3D11Device> deviceB = CreateDevice();
+
+    constexpr SIZE dimensions{1280, 720};
+    RenderTargetTexture rttA{CreateTestRenderTargetTexture(deviceA.get(), dimensions.cx, dimensions.cy)};
+
+    Babylon::Graphics::Configuration config{};
+    config.Device = deviceA.get();
+    config.BackBufferColor = rttA.View.get();
+    config.Width = dimensions.cx;
+    config.Height = dimensions.cy;
+
+    Babylon::Graphics::Device device{config};
+
+    // Before EnableRendering: UpdateDevice should be permitted (init state has not been consumed
+    // yet). This pattern is used by callers who deferred their device choice.
+    EXPECT_NO_THROW(device.UpdateDevice(deviceA.get()));
+
+    // After EnableRendering (driven by StartRenderingCurrentFrame): UpdateDevice must throw.
+    device.StartRenderingCurrentFrame();
+    EXPECT_THROW(device.UpdateDevice(deviceB.get()), std::runtime_error);
+    device.FinishRenderingCurrentFrame();
+
+    // Still initialized after the frame -- still throws.
+    EXPECT_THROW(device.UpdateDevice(deviceB.get()), std::runtime_error);
+
+    // After DisableRendering, UpdateDevice is permitted again. The next frame picks up the new device.
+    device.DisableRendering();
+    EXPECT_NO_THROW(device.UpdateDevice(deviceB.get()));
+
+    RenderTargetTexture rttB{CreateTestRenderTargetTexture(deviceB.get(), dimensions.cx, dimensions.cy)};
+    device.UpdateBackBuffer(rttB.View.get());
+    device.StartRenderingCurrentFrame();
+    device.FinishRenderingCurrentFrame();
+
+    EXPECT_EQ(device.GetPlatformInfo().Device, deviceB.get());
+}

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

@@ -112,7 +112,23 @@ namespace Babylon::Graphics
         // method and structure might change.
 
         void UpdateWindow(WindowT window);
+
+        // Sets the underlying graphics device that bgfx is initialized with on the next
+        // EnableRendering call.
+        //
+        // This API is only valid when rendering is disabled. Calling it while rendering is
+        // enabled throws std::runtime_error: bgfx is already initialized with the previous device
+        // and the swap would otherwise be silently buffered until the caller happens to do a
+        // DisableRendering / EnableRendering cycle, leading to bugs that are hard to diagnose.
+        //
+        // The typical call sequence to swap to a new device (e.g. on D3D11 / D3D12 device-removed
+        // recovery) is:
+        //   device.DisableRendering();
+        //   device.UpdateDevice(newDevice);
+        //   // Optional: device.UpdateBackBuffer(newBackBuffer); on D3D11 if a caller-owned RTV is in use
+        //   device.StartRenderingCurrentFrame();   // implicitly calls EnableRendering with the new device
         void UpdateDevice(DeviceT device);
+
         void UpdateSize(size_t width, size_t height);
         void UpdateMSAA(uint8_t value);
         void UpdateAlphaPremultiplied(bool enabled);

Core/Graphics/Source/DeviceImpl.cpp

@@ -108,6 +108,10 @@ namespace Babylon::Graphics
     void DeviceImpl::UpdateDevice(DeviceT device)
     {
         std::scoped_lock lock{m_state.Mutex};
+        if (m_state.Bgfx.Initialized)
+        {
+            throw std::runtime_error{"UpdateDevice called while rendering is enabled. Call DisableRendering first; the new device will take effect on the next EnableRendering / StartRenderingCurrentFrame."};
+        }
         m_state.Bgfx.InitState.platformData.context = device;
         m_state.Bgfx.Dirty = true;
     }