Phones: sideways only; back from the background the Vulkan surface is made again (it was lost), the work saved on the way out and carried on with on the next start if the phone closed it

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

engine/engine.cpp

@@ -371,6 +371,11 @@ int runClient(Game& game) {
             if (!input::captured()) ImGui_ImplSDL3_ProcessEvent(&ev);
             if (ev.type == SDL_EVENT_QUIT && game.allowQuit()) g_quit = true;
             if (ev.type == SDL_EVENT_WINDOW_PIXEL_SIZE_CHANGED) renderer.onResize();
+            // (a phone: SDL waits once these are seen, until the app's back; the surface is new then)
+            if (ev.type == SDL_EVENT_WILL_ENTER_BACKGROUND || ev.type == SDL_EVENT_LOW_MEMORY || ev.type == SDL_EVENT_TERMINATING) game.onBackground();
+#if defined(__ANDROID__)
+            if (ev.type == SDL_EVENT_DID_ENTER_FOREGROUND) renderer.onSurfaceLost();
+#endif
         }
         const bool focused = SDL_GetWindowFlags(window.handle()) & SDL_WINDOW_INPUT_FOCUS;
         audio::setFocused(focused);

engine/engine.h

@@ -36,6 +36,9 @@ public:
     // A file dropped on the window, or opened with the program from the desktop (a Mac's Finder
     // hands it over this way, not on the command line).
     virtual void onFileDropped(const std::string& path) { (void)path; }
+    // Going into the background (a phone: another app, the home screen), or the system is short
+    // of memory: the work should be kept now, as the app may be closed while it's away.
+    virtual void onBackground() {}
     // Hot reload: called twice a second (hotreload 1) after the engine reloaded what changed
     // (`changed`: textures, models, sounds); the game reloads its own (scripts, the map).
     virtual void hotReload(const std::vector<std::string>& changed) { (void)changed; }

engine/render/backend.h

@@ -218,6 +218,8 @@ public:
     virtual void beginUi() = 0;
     virtual void setVsync(bool on) = 0;
     virtual void onResize() = 0;
+    // Back from the background (a phone): the window's surface may be a new one.
+    virtual void onSurfaceLost() { onResize(); }
     // A texture in table slot `slot`, mips largest first: RGBA8 pixels, or BC7 blocks (YAPF 2's
     // GPU payload) when blockCompression() says the GPU takes them.
     virtual void createTexture(TextureId slot, uint32_t width, uint32_t height, bool srgb, const std::vector<std::vector<uint8_t>>& mips,

engine/render/renderer.h

@@ -157,6 +157,9 @@ public:
     void onResize() {
         if (backend_) backend_->onResize();
     }
+    void onSurfaceLost() {
+        if (backend_) backend_->onSurfaceLost();
+    }
 
 private:
     struct Submesh {

engine/rhi/vulkan/vk_backend.cpp

@@ -404,6 +404,7 @@ public:
     }
     void setVsync(bool on) override { device_.setVsync(on); }
     void onResize() override { device_.markResized(); }
+    void onSurfaceLost() override { device_.markSurfaceLost(); }
 
     bool renderScale() const override { return true; }
     bool blockCompression() const override {

engine/rhi/vulkan/vk_device.cpp

@@ -263,6 +263,24 @@ bool Device::createSwapchain() {
     return true;
 }
 
+// A new surface on the window as it is now (Android makes a new one each time the app comes back).
+bool Device::recreateSurface() {
+    vkDeviceWaitIdle(device_);
+    destroySwapchainViews();
+    if (swapchain_) vkDestroySwapchainKHR(device_, swapchain_, nullptr), swapchain_ = VK_NULL_HANDLE;
+    if (surface_) vkDestroySurfaceKHR(instance_, surface_, nullptr), surface_ = VK_NULL_HANDLE;
+    if (!SDL_Vulkan_CreateSurface(window_->handle(), instance_, nullptr, &surface_)) {
+        log::warn("SDL_Vulkan_CreateSurface (again): {}", SDL_GetError());
+        surface_ = VK_NULL_HANDLE;
+        return false; // (tried again next frame)
+    }
+    VkBool32 present = VK_FALSE;
+    vkGetPhysicalDeviceSurfaceSupportKHR(physical_, queueFamily_, surface_, &present);
+    if (!present) log::warn("The new surface can't be presented to from this queue");
+    surfaceLost_ = false;
+    return createSwapchain();
+}
+
 void Device::destroySwapchainViews() {
     for (VkImageView v : views_) vkDestroyImageView(device_, v, nullptr);
     for (VkSemaphore s : renderDone_) vkDestroySemaphore(device_, s, nullptr);
@@ -271,6 +289,7 @@ void Device::destroySwapchainViews() {
 }
 
 VkCommandBuffer Device::beginFrame() {
+    if (surfaceLost_ && !recreateSurface()) return nullptr;
     if (swapchainDirty_ && !createSwapchain()) return nullptr;
 
     Frame& f = frames_[frameIndex_];
@@ -280,6 +299,10 @@ VkCommandBuffer Device::beginFrame() {
         swapchainDirty_ = true;
         return nullptr;
     }
+    if (r == VK_ERROR_SURFACE_LOST_KHR) {
+        surfaceLost_ = true;
+        return nullptr;
+    }
     if (r != VK_SUBOPTIMAL_KHR) VK_CHECK(r);
     VK_CHECK(vkResetFences(device_, 1, &f.inFlight));
 
@@ -328,6 +351,7 @@ void Device::endFrame() {
     }
 #endif
     if (r == VK_ERROR_OUT_OF_DATE_KHR || r == VK_SUBOPTIMAL_KHR) swapchainDirty_ = true;
+    else if (r == VK_ERROR_SURFACE_LOST_KHR) surfaceLost_ = true;
     else VK_CHECK(r);
 
     frameIndex_ = (frameIndex_ + 1) % kFramesInFlight;

engine/rhi/vulkan/vk_device.h

@@ -50,6 +50,8 @@ public:
 
     void setVsync(bool vsync) { vsync_ = vsync; swapchainDirty_ = true; }
     void markResized() { swapchainDirty_ = true; }
+    // The window's surface went away (a phone: the app was in the background): made again.
+    void markSurfaceLost() { surfaceLost_ = true; }
     void waitIdle() { vkDeviceWaitIdle(device_); }
 
     VkInstance instance() const { return instance_; }
@@ -81,6 +83,7 @@ private:
     };
 
     bool createSwapchain();
+    bool recreateSurface();
     void destroySwapchainViews();
 
     const Window* window_ = nullptr;
@@ -102,7 +105,7 @@ private:
     std::vector<VkImageView> views_;
     std::vector<VkSemaphore> renderDone_; // per swapchain image, so present never reuses one in flight
     bool vsync_ = true;
-    bool swapchainDirty_ = false;
+    bool swapchainDirty_ = false, surfaceLost_ = false;
 
     Frame frames_[kFramesInFlight];
     VkCommandPool immPool_ = VK_NULL_HANDLE;