196 lines
18 KiB
Markdown
196 lines
18 KiB
Markdown
# Glossary
|
|
|
|
Click any term to jump to its definition. These terms are referenced across all concept files.
|
|
|
|
## Adapter
|
|
|
|
The physical GPU or software renderer wgpu communicates with. A single system may expose multiple adapters: a dedicated NVIDIA GPU, an integrated Intel GPU, and a software fallback (llvmpipe / SwiftShader). You select one adapter and build all resources from it. In wgpu, adapters are discovered via `Instance::enumerate_adapters()`. Picking the wrong adapter means running on the integrated GPU when the discrete GPU is available.
|
|
|
|
## Barycentric coordinates
|
|
|
|
Three weights (w0, w1, w2) that sum to 1, computed by the rasterizer for every fragment inside a triangle. Each weight represents the fragment's proximity to one of the three vertices. These weights drive the hardware interpolation of vertex attributes: `value = w0*value0 + w1*value1 + w2*value2`. At vertex 0, the weights are (1,0,0). At the triangle centroid, they are (1/3, 1/3, 1/3).
|
|
|
|
## Buffer slice
|
|
|
|
A view into GPU buffer memory defined by an offset and a length. `buffer.slice(..)` returns the full buffer. Buffer slices are used when mapping buffers for CPU read/write access or when copying data between buffers. They do not own the underlying memory — they are a window into an existing buffer.
|
|
|
|
## Bind group
|
|
|
|
A collection of GPU resources (buffers, textures, samplers) grouped together and bound to a [shader](#shader) at once. Bind groups correspond to shader `@group` declarations in [WGSL](#wgsl) and are created via `device.create_bind_group()`. They provide efficient resource switching without rebuilding the entire [pipeline](#pipeline).
|
|
|
|
## Clip space
|
|
|
|
The [homogeneous coordinates](#homogeneous-coordinates) coordinate space that the [vertex shader](#vertex-shader) outputs into (`vec4<f32>`). The GPU clips geometry against the clip-space boundaries before performing perspective division (dividing x, y, z by w) to produce [ndc](#ndc). For perspective projection, clip space is a pyramid. For orthographic projection, it is a box. Geometry outside these boundaries is discarded by hardware.
|
|
|
|
## Command buffer
|
|
|
|
A recorded sequence of GPU commands — buffer copies, render passes, compute dispatches — analogous to a bash script listing operations to execute. You create a command buffer, encode operations into it via a `CommandEncoder`, then submit it to the [queue](#queue). The GPU executes the recorded sequence asynchronously. One submission is one unit of GPU work.
|
|
|
|
## Compute shader
|
|
|
|
A programmable GPU shader that operates on data in buffers without producing geometry or fragments. Compute shaders run in parallel workgroups and are used for general-purpose GPU computation (physics simulations, image processing, etc.). They use `@compute` entry points instead of `@vertex` or `@fragment`.
|
|
|
|
## Culling
|
|
|
|
A fixed-function optimization that discards primitives that won't appear in the final image. Back-face culling removes triangles whose winding order indicates they face away from the camera, saving [fragment shader](#fragment-shader) invocations. Culling is configured in the `Face` state of the [pipeline](#pipeline).
|
|
|
|
## Device
|
|
|
|
The logical connection to the GPU. Created from an [adapter](#adapter), the device owns all GPU resources: buffers, textures, [pipeline](#pipeline) objects, shader modules, and bind groups. It is analogous to a file descriptor — the handle through which you allocate and manage GPU memory. All resource creation and destruction flows through the device.
|
|
|
|
## Device poll
|
|
|
|
`device.poll(PollType::Wait)` — a synchronous call that tells wgpu to drive all in-flight GPU work toward completion. This includes shader compilation, memory allocation on the GPU side, fence signaling, and surface frame acquisition. Without polling, wgpu's internal work queues stall. The [polltype](#polltype) `Wait` variant blocks the CPU thread until pending GPU tasks are done.
|
|
|
|
## Depth buffer
|
|
|
|
A per-pixel buffer that stores the depth (Z) value of each rendered fragment, enabling the GPU to determine which surfaces are in front of others. Without a depth buffer, draw order determines visibility, which breaks 3D scenes with complex overlap. Configured via the `depth_stencil_attachment` in the [render pass](#render-pass).
|
|
|
|
## 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) ([Stage 5](graphics-pipeline.md#stage-5-output-merge)) stage. Not every fragment becomes a visible pixel.
|
|
|
|
## Fragment shader
|
|
|
|
GPU program running once per [fragment](#fragment). It receives pre-interpolated vertex shader outputs from the rasterizer and computes the final RGBA color for that fragment. This is where texture sampling, lighting calculations, and pixel-level effects happen. For the rainbow triangle, the fragment shader passes the interpolated vertex color through unchanged.
|
|
|
|
## Framebuffer
|
|
|
|
The color buffer that appears on screen. During [swapchain](#swapchain) double-buffering, the framebuffer being drawn to is the back buffer. Once the render pass completes and you submit the buffer, it becomes the front buffer and is displayed. The framebuffer is a [texture view](#texture-view) tied to a surface frame.
|
|
|
|
## Homogeneous coordinates
|
|
|
|
A four-component representation (x, y, z, w) that enables perspective projection via the divide-by-w step. When w=1, the coordinates represent a point in 3D space. When w=0, they represent a direction vector. Perspective division (x/w, y/w, z/w) transforms clip-space coordinates into [ndc](#ndc). With w=1.0, division is the identity transform.
|
|
|
|
## Index buffer
|
|
|
|
A GPU buffer containing vertex indices (integer offsets) that define the order in which vertices form [primitive](#primitive)s. Index buffers allow vertex reuse across multiple triangles, reducing memory usage and bandwidth. Used with `render_pass.draw_indexed()` instead of `draw()`.
|
|
|
|
## Interpolation
|
|
|
|
The rasterizer's automatic blending of vertex shader outputs across the surface of a triangle. For every `@location(n)` value output by the vertex shader, the [rasterizer](#rasterizer) computes a linear blend using [barycentric coordinates](#barycentric-coordinates): `value = w0*v0 + w1*v1 + w2*v2`. This is a free, hardware-accelerated feature. No shader code is required to perform interpolation.
|
|
|
|
## Instance
|
|
|
|
The root wgpu object representing the connection to the system's graphics drivers. Created via `Instance::default()`, the instance discovers available [adapter](#adapter)s and manages [surface](#surface) creation. It is the first object created in the wgpu initialization chain. (Note: `Instance::default()` calls `Instance::new(Default::default())` internally; both forms produce an equivalent instance.)
|
|
|
|
## Loadop
|
|
|
|
Controls what happens to the [framebuffer](#framebuffer) at the start of a render pass. `LoadOp::Clear(color)` fills the entire framebuffer with a solid color — this produces your scene background. `LoadOp::Load` keeps whatever pixels are already in the framebuffer — used for multi-pass rendering where the second pass draws on top of the first.
|
|
|
|
## Output merge
|
|
|
|
The final GPU pipeline stage. It applies per-fragment tests (depth, stencil, alpha) and blending operations before writing pixels to the [framebuffer](#framebuffer). The blend state (configured in the [pipeline](#pipeline)) determines whether new colors replace, add, or multiply with existing framebuffer colors. For the rainbow triangle, blending is REPLACE — new pixels overwrite old ones.
|
|
|
|
## Pipeline (render)
|
|
|
|
A compiled GPU configuration bundling: [vertex shader](#vertex-shader) + [fragment shader](#fragment-shader) + [topology](#topology) + blend state + depth/stencil state + vertex buffer layout. Created once via `device.create_render_pipeline()` and reused for every frame. Changing any of these parameters requires creating a new pipeline. Pipeline creation is expensive; do not create one per frame.
|
|
|
|
## Polltype
|
|
|
|
The strategy passed to `device.poll()`, which processes all completed GPU commands and optionally waits for new work. `PollType::Poll` is non-blocking: it checks for completed work once and returns immediately. `PollType::Wait { submission_index, timeout }` can optionally block until a specific command submission completes (via `submission_index: Option<T>`) or until a duration elapses (via `timeout: Option<Duration>`); passing `None` for both blocks indefinitely. For the rainbow triangle, `Wait` with a short timeout is correct: we need the GPU to finish the frame before requesting the next surface texture.
|
|
|
|
## Present Mode
|
|
|
|
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
|
|
|
|
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).
|
|
|
|
## Normal vector
|
|
|
|
A unit vector perpendicular to a surface at a given point, used for lighting calculations. Normals determine how light interacts with a surface (diffuse/specular reflection). In a [vertex buffer](#vertex-buffer), normals are stored per-[vertex](#vertex) and interpolated across triangles.
|
|
|
|
## Operations
|
|
|
|
Paired `LoadOp` + `StoreOp` controlling [framebuffer](#framebuffer) behavior at [render pass](#render-pass) boundaries. `LoadOp` defines the pre-draw state (clear or load). `StoreOp` defines the post-draw state (store or discard). Together they form `Operations { load, store }` passed to `RenderPassColorAttachment`.
|
|
|
|
## Primitive
|
|
|
|
A geometric shape the GPU can render: point list, line list, line strip, triangle list, or triangle strip. Triangles are the universal primitive — every 3D surface is built from triangles. In wgpu, the primitive type is set on the pipeline descriptor. The rainbow triangle uses `PrimitiveTopology::TriangleList`, meaning every group of 3 consecutive vertices forms one triangle.
|
|
|
|
## Queue
|
|
|
|
The submission channel to the GPU. You push [command buffer](#command-buffer)s into the queue via `queue.submit()`. The queue executes them asynchronously on the GPU. The queue also handles buffer uploads via `queue.write_buffer()` — these are synchronous copy operations that block until the data lands in GPU memory.
|
|
|
|
## Rasterizer
|
|
|
|
Hardware stage that converts [primitive](#primitive) geometry into [fragment](#fragment)s. For each triangle, determines which screen pixels it covers, generates one fragment per covered pixel, and computes interpolated vertex attributes using [barycentric coordinates](#barycentric-coordinates). The rasterizer is a fixed-function unit: no user code runs here. You configure its behavior (culling, fill mode, scissor test) via the pipeline descriptor.
|
|
|
|
## Perspective projection
|
|
|
|
A transformation matrix that maps 3D world coordinates into [clip space](#clip-space) with depth-based foreshortening, simulating how the human eye perceives distance. Objects farther from the camera appear smaller. The perspective projection matrix is typically combined with model and view matrices.
|
|
|
|
## Render pass
|
|
|
|
A scoped section of a [command buffer](#command-buffer) that groups draw operations sharing the same target [framebuffer](#framebuffer) attachments. Entered via `command_encoder.begin_render_pass()` and ended by dropping the `RenderPass` variable. Between begin and end, you set the pipeline, bind vertex buffers, and issue draw calls. Everything drawn in one render pass targets the same framebuffer with the same [operations](#operations).
|
|
|
|
## Sampler
|
|
|
|
A GPU resource that configures how a [texture](#texture) is read during shader execution, including filtering mode (nearest/linear), addressing mode (clamp/wrap/mirror), and comparison function. Samplers are bound via [bind groups](#bind-group) and referenced in WGSL with `textureSample()`.
|
|
|
|
## Shader
|
|
|
|
GPU program written in [wgsl](#wgsl). No heap allocation, no recursion, no I/O. The only output channel is the return value. A shader module may contain multiple entry points (`@vertex`, `@fragment`, `@compute`). The GPU runs thousands of shader invocations in parallel, each operating on different data but executing the identical program.
|
|
|
|
## Shader location
|
|
|
|
A numeric binding label (`@location(n)`) used to tie Rust vertex buffer attributes to WGSL shader parameters. On the Rust side: `VertexAttribute { shader_location: 0, ... }`. On the WGSL side: `@location(0) my_value: vec3<f32>`. These numbers must match exactly. Mismatched locations produce silent data corruption — the GPU reads from the wrong memory offset.
|
|
|
|
## Storeop
|
|
|
|
Controls what happens to the [framebuffer](#framebuffer) at the end of a render pass. `StoreOp::Store` keeps the written pixels — this is what you want for visible frames. `StoreOp::Discard` discards the framebuffer contents — used for offscreen renders where you do not need the result on screen, saving a memory barrier.
|
|
|
|
## Surface
|
|
|
|
wgpu's connection to a window's display buffer. Created via `instance.create_surface(window)`, the surface is like a bound socket — it is tied to a specific window and cannot be unlinked. The surface manages the [swapchain](#swapchain) and provides new framebuffers via `surface.get_current_texture()`. If the window is resized, the surface must be reconfigured with a new `SurfaceConfiguration`.
|
|
|
|
## Surface Configuration
|
|
|
|
The `SurfaceConfiguration` struct that allocates swapchain framebuffers: format, dimensions, present mode, and view formats. Reconfigured on window resize via `Surface::configure()`.
|
|
|
|
## Swapchain
|
|
|
|
A ring buffer of 2-3 [framebuffer](#framebuffer) textures managed by the GPU driver. The display hardware reads from the front buffer. The application renders to the back buffer. When the frame is complete, the buffers swap: the back buffer becomes the front (displayed), and the old front becomes the available back buffer for the next frame. This prevents screen tearing by ensuring the display never reads a frame mid-update.
|
|
|
|
## Texture view
|
|
|
|
A handle referencing a region of [texture](#texture) memory for use inside a [render pass](#render-pass) or bind group. Created via `texture.create_view()`, texture views define the mip level range, aspect, and dimensionality (2D, cube, array) of the binding. Surface framebuffers are accessed as texture views inside render passes.
|
|
|
|
## Texture
|
|
|
|
GPU memory region storing color data. Used for both render targets (framebuffers) and samplers (loaded images). In wgpu, a texture is created from the [device](#device) with a defined size, format, and usage flags. You never read texture memory directly from the CPU — you access it through [texture view](#texture-view) bindings in shaders.
|
|
|
|
## Topology
|
|
|
|
The rule for grouping vertices into [primitive](#primitive) shapes. `TriangleList` means every 3 consecutive vertices form one independent triangle. `TriangleStrip` means each new vertex combined with the previous two forms a triangle. `PointList` renders individual points. `LineList` renders pairs of connected vertices. Topology is set once on the [pipeline](#pipeline) descriptor.
|
|
|
|
## UV coordinate
|
|
|
|
A 2D texture coordinate (u, v) in the range [0, 1] that maps a [vertex](#vertex) to a location on a [texture](#texture). UVs are passed from the [vertex shader](#vertex-shader) to the [fragment shader](#fragment-shader) via `@location` attributes and used to sample texture colors. Also called "texture coordinates."
|
|
|
|
## Vertex
|
|
|
|
A data point containing one or more attributes: position, color, UV coordinates, normals, tangents. All attributes for one vertex are stored contiguously in a [vertex buffer](#vertex-buffer). The stride (total bytes per vertex) is determined by the sum of all attribute sizes. In the rainbow triangle, each vertex has three `f32` position components and three `f32` color components: 24 bytes per vertex.
|
|
|
|
## Vertex buffer
|
|
|
|
GPU [buffer slice](#buffer-slice) containing [vertex](#vertex) attribute data in a tightly packed layout. Created via `device.create_buffer()` and populated via `queue.write_buffer()`. The pipeline's vertex state describes how to interpret the buffer: stride, attribute count, and per-attribute format + [shader location](#shader-location) mapping.
|
|
|
|
## Vertex shader
|
|
|
|
GPU program running once per [vertex](#vertex). It reads vertex attributes from the [vertex buffer](#vertex-buffer), transforms the position into [clip space](#clip-space), and outputs any per-vertex data the downstream pipeline stages need. The mandatory output is `@builtin(position) vec4<f32>`. Optional outputs use `@location(n)` annotations and flow into the rasterizer for interpolation.
|
|
|
|
## Viewport transform
|
|
|
|
Automatic GPU step mapping [ndc](#ndc) coordinates (-1..+1) to [window](#window) pixel coordinates. Configured via `SurfaceConfiguration` `width` and `height` fields. The GPU performs: `screen_x = (ndc_x + 1) / 2 * width; screen_y = (ndc_y + 1) / 2 * height`. This step happens after perspective division, between NDC and the rasterizer. You never write this math in shader code.
|
|
|
|
## Window
|
|
|
|
The operating system window created by the windowing library. In wgpu, the window is passed to `instance.create_surface()` to bind the GPU to a display target. The window dimensions dictate the [viewport transform](#viewport-transform) and thus the size of the rendered image. Resizing the window requires creating a new `SurfaceConfiguration` with updated dimensions.
|
|
|
|
## WGSL
|
|
|
|
WebGPU Shading Language. The standardized shader language for WebGPU. Static typed, no heap, no recursion, no I/O. Compiles to platform-native intermediate formats: SPIR-V (Vulkan), MSL (Metal), DXIL (DirectX). You write one WGSL module; wgpu translates it for the target backend. Syntax is similar to GLSL but stricter — all variables must be declared, all branches must terminate, and all entry points must be annotated.
|