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