From 6d72ecf45d54a49003a8e221672a907b65b1e491 Mon Sep 17 00:00:00 2001 From: Krishna Ayyalasomayajula Date: Sat, 30 May 2026 20:30:24 -0500 Subject: [PATCH] docs: fix all broken cross-reference links --- docs/01-rainbow-triangle.md | 19 +++++++++---------- docs/TROUBLESHOOTING.md | 4 ++-- docs/concepts/GLOSSARY.md | 4 ++-- docs/concepts/shader-basics.md | 2 +- 4 files changed, 14 insertions(+), 15 deletions(-) diff --git a/docs/01-rainbow-triangle.md b/docs/01-rainbow-triangle.md index 1796d4f..ed759cc 100644 --- a/docs/01-rainbow-triangle.md +++ b/docs/01-rainbow-triangle.md @@ -13,7 +13,7 @@ blending the three vertex colors proportionally to their distance. The result is a smooth rainbow gradient across a single primitive. We do not need a texture, a colormap, or a fragment shader with any branching — just three colored vertices and the default linear interpolation the [rasterizer](concepts/GLOSSARY.md#rasterizer) -applies to every [varying](concepts/GLOSSARY.md#varying). +applies to every [interpolated value](concepts/GLOSSARY.md#interpolation). If you haven't read the [concept overview](concepts/graphics-pipeline.md), do so now. [Coordinate systems](concepts/coordinate-systems.md) explains how the GPU @@ -242,10 +242,9 @@ struct State { (e.g., after a compositor restart or display hotplug), recovery requires reconfiguring the swapchain with the window's live size — and that requires holding a reference to the window itself. -- **`pipeline`** — the compiled [render pipeline](concepts/GLOSSARY.md#render-pipeline). +- **`pipeline`** — the compiled [render pipeline](concepts/GLOSSARY.md#pipeline). A render pipeline is an immutable configuration combining a shader, a vertex - buffer layout, a primitive topology, and a [color target](concepts/GLOSSARY.md#color-target) - setup. Switching pipelines mid-frame is expensive; most applications use a few + buffer layout, a primitive topology, and a color target setup. Switching pipelines mid-frame is expensive; most applications use a few pipelines and change them between draw calls. - **`vertex_buffer`** — GPU memory holding our vertex data. The GPU reads position and color data directly from this buffer during the vertex shader @@ -436,7 +435,7 @@ to a `VkQueue`. **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 -[sRGB](concepts/GLOSSARY.md#srgb) format for correct color display), pick the +[sRGB](concepts/GLOSSARY.md) format for correct color display), pick the window dimensions (clamped to at least 1x1 to allow minimize-and-restore on some platforms), and select the [present mode](concepts/GLOSSARY.md#present-mode). `PresentMode::Mailbox` is a triple-buffered present mode that provides @@ -684,8 +683,8 @@ const VERTICES: &[Vertex] = &[ - **CCW winding order:** The vertices are listed counter-clockwise: red → blue → green. In a standard right-handed coordinate system, connecting vertices in this sequence traces the triangle counter-clockwise. This - determines which face is "front" and which is "back" — critical for - [culling](concepts/GLOSSARY.md#rasterizer) and correct normal computation. + determines which face is "front" and which is "back" — critical for + [culling](concepts/GLOSSARY.md) and correct normal computation. ### Buffer Upload @@ -1103,7 +1102,7 @@ color_attachments: &[Some(wgpu::RenderPassColorAttachment { **`RenderPassColorAttachment` has exactly 4 fields:** - **`view: &texture_view`** — the framebuffer we draw into. Must match the - color target format in the [render pipeline](concepts/GLOSSARY.md#render-pipeline). + color target format in the [render pipeline](concepts/GLOSSARY.md#pipeline). - **`depth_slice: None`** — only used for 3D texture slices. Not applicable to 2D rendering. - **`resolve_target: None`** — only used for MSAA resolve. When multisampling @@ -1134,7 +1133,7 @@ that pass the depth test). Useful for visibility-based culling. ### Binding State and Drawing **`render_pass.set_pipeline(&self.pipeline)`** — Tells the GPU which -[render pipeline](concepts/GLOSSARY.md#render-pipeline) to use for subsequent +[render pipeline](concepts/GLOSSARY.md#pipeline) to use for subsequent draw calls. The pipeline encapsulates the shader programs, vertex format, primitive topology, and output configuration. Must be set before any draw call in a render pass. Switching pipelines mid-pass is expensive and should be @@ -1341,7 +1340,7 @@ each piece does: Each layer adds a capability: driver connection, window binding, GPU selection, resource management, and swapchain allocation. -- **The [render pipeline](concepts/GLOSSARY.md#pipeline-render):** Shaders, +- **The [render pipeline](concepts/GLOSSARY.md#pipeline):** Shaders, topology, and vertex layout compiled into a GPU configuration. Created once, reused every frame. Expensive to create, cheap to execute. diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md index b7a79bd..3bddece 100644 --- a/docs/TROUBLESHOOTING.md +++ b/docs/TROUBLESHOOTING.md @@ -57,7 +57,7 @@ vulkaninfo # verify installation **Symptom:** Program crashes with a surface lost error during rendering. -**Cause:** Display server restarted or GPU context was reset. The [Surface](concepts/GLOSSARY.md#Surface) is permanently invalidated. +**Cause:** Display server restarted or GPU context was reset. The [Surface](concepts/GLOSSARY.md#surface) is permanently invalidated. **Fix:** In the tutorial, this means the window needs to be reopened. In production code, handle the `Lost` variant of `CurrentSurfaceTexture` by recreating the surface via `Instance::create_surface()`. @@ -108,7 +108,7 @@ fn exiting(&mut self, event_loop_ctl: &ActiveEventLoop) { **Symptom:** Triangle renders but is a single uniform color instead of smoothly blending. -**Cause:** Fragment shader returns a constant color instead of passing through `input.vertex_color`. The [rasterizer](concepts/GLOSSARY.md#Rasterizer) interpolates vertex colors automatically, but only if the fragment shader uses them. +**Cause:** Fragment shader returns a constant color instead of passing through `input.vertex_color`. The [rasterizer](concepts/GLOSSARY.md#rasterizer) interpolates vertex colors automatically, but only if the fragment shader uses them. **Fix:** Ensure fragment shader returns the interpolated vertex color: ```wgsl diff --git a/docs/concepts/GLOSSARY.md b/docs/concepts/GLOSSARY.md index e3b8a27..a569f4c 100644 --- a/docs/concepts/GLOSSARY.md +++ b/docs/concepts/GLOSSARY.md @@ -32,7 +32,7 @@ The logical connection to the GPU. Created from an [[adapter]](#adapter), the de ## Fragment -A potential pixel produced by the [[rasterizer]](#rasterizer). One fragment is generated per screen pixel that a [[primitive]](#primitive) covers. A fragment carries interpolated [[vertex]](#vertex) shader outputs, a depth value, and a color. The fragment may be later discarded by depth testing, stencil testing, or alpha testing during the [[output merge]](#output-merge)(graphics-pipeline.md#stage-5-output-merge) stage. Not every fragment becomes a visible pixel. +A potential pixel produced by the [[rasterizer]](#rasterizer). One fragment is generated per screen pixel that a [[primitive]](#primitive) covers. A fragment carries interpolated [[vertex]](#vertex) shader outputs, a depth value, and a color. The fragment may be later discarded by depth testing, stencil testing, or alpha testing during the [[output merge]](#output-merge) ([Stage 5](graphics-pipeline.md#stage-5-output-merge)) stage. Not every fragment becomes a visible pixel. ## Fragment shader @@ -74,7 +74,7 @@ The strategy passed to `device.poll()`, which processes all completed GPU comman How the display compositor handles frame buffer presentation: `PresentMode::Mailbox` uses triple buffering for tear-free rendering, `PresentMode::Fifo` provides VSYNC-locked double buffering, `PresentMode::Immediate` renders without synchronization (may show tearing). -## Ndc +## NDC Normalized Device Coordinates. The GPU's native intermediate coordinate space. X and Y range from -1.0 (left/bottom) to +1.0 (right/top). Z ranges from 0.0 (near clipping plane) to 1.0 (far clipping plane). Geometry is mapped into NDC by the GPU after perspective division. Anything outside this cube is clipped. See [[coordinate-systems.md]](coordinate-systems.md). diff --git a/docs/concepts/shader-basics.md b/docs/concepts/shader-basics.md index 0802fe9..ad3efeb 100644 --- a/docs/concepts/shader-basics.md +++ b/docs/concepts/shader-basics.md @@ -79,7 +79,7 @@ Data flows between the vertex and fragment stages through a shared struct. The s The vertex shader produces a struct containing a `@builtin(position)` output plus any number of `@location` interpolants. The rasterizer takes these outputs, assembles [[primitives]](GLOSSARY.md#primitive), and for every pixel inside the triangle computes [[barycentric coordinates]](GLOSSARY.md#barycentric-coordinates) and blends all `@location` fields. The fragment shader receives the fully interpolated struct and outputs a `vec4` color at `@location(0)`, which maps to the [[pipeline]](GLOSSARY.md#pipeline)'s color attachment target. -For a complete line-by-line walkthrough of our rainbow triangle shader, see [Section 4](01-rainbow-triangle.md#section-4-writing-the-shaders). +For a complete line-by-line walkthrough of our rainbow triangle shader, see [Section 4](01-rainbow-triangle.md#s4-writing-the-shaders). ## WGSL Source Embedding