From 689b43da984088540c42f9cd24e0d6ceaf18231c Mon Sep 17 00:00:00 2001 From: Krishna Ayyalasomayajula Date: Sat, 30 May 2026 20:49:40 -0500 Subject: [PATCH] docs: add validation layer discussion to GPU init section --- docs/01-rainbow-triangle.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/01-rainbow-triangle.md b/docs/01-rainbow-triangle.md index 2b5fbcf..e837ce1 100644 --- a/docs/01-rainbow-triangle.md +++ b/docs/01-rainbow-triangle.md @@ -432,6 +432,16 @@ becomes a [command buffer](concepts/GLOSSARY.md#command-buffer) that is submitte to this queue. On Vulkan, the device corresponds to `VkDevice` and the queue to a `VkQueue`. +> **Key insight — Validation layers catch GPU errors at runtime:** wgpu ships +> with built-in validation layers that inspect your API calls for common +> mistakes: incorrect buffer bindings, mismatched pipeline state, out-of-bounds +> buffer slices, and resource lifecycle violations. These layers run +> automatically during development and surface errors as log messages or +> panics, saving hours of debugging silent GPU corruption. The tradeoff: +> validation adds measurable overhead to every frame. In release builds, +> disable validation by setting `DeviceDescriptor::device_type` or using +> the `WGPU_BACKEND` environment variable to skip the validation path. + **Step 5 — SurfaceConfiguration:** This allocates the [swapchain](concepts/GLOSSARY.md#swapchain) [framebuffers](concepts/GLOSSARY.md#framebuffer). We negotiate the pixel format with the driver (preferring an