15 KiB
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.
Clip space
The [homogeneous coordinates] coordinate space that the [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]. 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]. The GPU executes the recorded sequence asynchronously. One submission is one unit of GPU work.
Device
The logical connection to the GPU. Created from an [adapter], the device owns all GPU resources: buffers, textures, [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] Wait variant blocks the CPU thread until pending GPU tasks are done.
Fragment
A potential pixel produced by the [rasterizer]. One fragment is generated per screen pixel that a [primitive] covers. A fragment carries interpolated [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] (Stage 5) stage. Not every fragment becomes a visible pixel.
Fragment shader
GPU program running once per [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] 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] 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]. With w=1.0, division is the identity transform.
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] computes a linear blend using [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]s and manages [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] 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]. The blend state (configured in the [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] + [fragment shader] + [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].
Operations
Paired LoadOp + StoreOp controlling [framebuffer] behavior at [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]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] geometry into [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]. 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.
Render pass
A scoped section of a [command buffer] that groups draw operations sharing the same target [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].
Shader
GPU program written in [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] 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] 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] 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] memory for use inside a [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] with a defined size, format, and usage flags. You never read texture memory directly from the CPU — you access it through [texture view] bindings in shaders.
Topology
The rule for grouping vertices into [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] descriptor.
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]. 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] containing [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] mapping.
Vertex shader
GPU program running once per [vertex]. It reads vertex attributes from the [vertex buffer], transforms the position into [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] coordinates (-1..+1) to [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] 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.