marsultor/learn-wgpu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add SurfaceStatus::Lost recovery strategy

Browse Source
This commit is contained in:
Krishna Ayyalasomayajula
2026-05-30 20:51:37 -05:00
parent 598708f111
commit 31adc35da7
1 changed files with 15 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
docs/01-rainbow-triangle.md
View File

@@ -1004,7 +1004,10 @@ fn render(&mut self) {
return; return;
} }
wgpu::CurrentSurfaceTexture::Lost => { wgpu::CurrentSurfaceTexture::Lost => {
log::error!("Surface lost — cannot recover without re-creating State"); log::error!("Surface lost — GPU resources invalidated; full re-init required");
// Production recovery: signal App to drop `self.state`,
// then recreate on the next RedrawRequested or in a
// dedicated recovery callback. See callout below.
return; return;
} }
wgpu::CurrentSurfaceTexture::Validation { source, description } => { wgpu::CurrentSurfaceTexture::Validation { source, description } => {
@@ -1067,6 +1070,17 @@ from the [swapchain](concepts/GLOSSARY.md#swapchain). The swapchain cycles throu
2–3 pre-allocated back buffers. This call returns immediately if a buffer is 2–3 pre-allocated back buffers. This call returns immediately if a buffer is
available; it does not block on the GPU. available; it does not block on the GPU.
> **Surface Lost recovery pattern:** `Lost` means the compositor destroyed the
> surface (display server restart, GPU reset, hotplug, etc.). Every GPU
> resource tied to that surface — the `Surface`, `Device`, `Queue`, pipeline,
> buffers — is irrecoverably invalidated. You cannot reuse any of them. The
> production pattern is to set `self.state = None` in `App`, then on the next
> `RedrawRequested` (or in a dedicated recovery callback), re-run the full
> `State::new()` initialization chain from S3. This recreates the adapter,
> device, surface, and all child resources. Without this, continued renders
> against a lost surface will either panic or silently produce corrupted
> output.
**`device.poll(wgpu::PollType::Wait { submission_index: None, timeout: None })`** — **Synchronous** call that drives **`device.poll(wgpu::PollType::Wait { submission_index: None, timeout: None })`** — **Synchronous** call that drives
in-flight GPU work to completion: shader compilation fences, memory allocation, in-flight GPU work to completion: shader compilation fences, memory allocation,
and queue signaling. Without this, resources accumulate because the device does and queue signaling. Without this, resources accumulate because the device does