diff --git a/docs/concepts/GLOSSARY.md b/docs/concepts/GLOSSARY.md index 2eedd0b..a3aabf4 100644 --- a/docs/concepts/GLOSSARY.md +++ b/docs/concepts/GLOSSARY.md @@ -14,6 +14,10 @@ Three weights (w0, w1, w2) that sum to 1, computed by the rasterizer for every f 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`). 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. @@ -22,6 +26,14 @@ The [homogeneous coordinates](#homogeneous-coordinates) coordinate space that th 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. @@ -30,6 +42,10 @@ The logical connection to the GPU. Created from an [adapter](#adapter), the devi `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. @@ -46,6 +62,10 @@ The color buffer that appears on screen. During [swapchain](#swapchain) double-b 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. @@ -78,6 +98,10 @@ How the display compositor handles frame buffer presentation: `PresentMode::Mail 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`. @@ -94,10 +118,18 @@ The submission channel to the GPU. You push [command buffer](#command-buffer)s i 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. @@ -134,6 +166,10 @@ GPU memory region storing color data. Used for both render targets (framebuffers 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.