entelechy-gpuGenerated

Generated from the source

Data comes from cargo +nightly doc --output-format json.

Layer: backends · Lines of code: 11,731 · Integration test files: 5

Brief

GPU backend: emits WGSL from Entelechy IR and runs it as compute dispatches through wgpu

Description

GPU backend.

Emits WGSL from validated IR at preparation and runs each execution through wgpu. The Host owns images and their pixels stay resident on the device: a resident input binds directly, a Host input uploads once and stays resident, and outputs are adopted as resident images. Pixels return only through Backend::download. Semantics match the CPU backend up to floating-point rounding; integer failures are reported as the CPU reports them.

Internal dependencies	entelechy-abi, entelechy-ir, entelechy-rules
External dependencies	pollster
Source	crates/backends/gpu

Modules

Name	Brief
present	Presenting a resident image to a window without reading it back.
wgsl	WGSL emission from validated Entelechy IR.

Structs

Name	Brief
present::Display	The GPU device as a window reaches it: taken from a backend before the backend goes to a runtime, sharing its device, so an interface draws what the backend left resident; the runtime knows only a Backend.
present::Overlay	Pixels drawn over the window’s top-left corner: 0x00RRGGBB, width per row.
present::Presenter	A window surface a Display draws resident images into.
GpuError	The GPU could not be opened.
GpuBackend	A wgpu device with a compute-only contract.

Enumerations

Name	Brief
wgsl::Longs	How a shader computes a Long: as the device’s own 64-bit integer, or, on a device without one (a page’s WebGPU), as a pair of 32-bit words with every operation a helper (pairs_take says which modules can).

Functions

Function	Brief
fn pairs_take(module: &Module) -> bool	Whether a module runs with its Longs in pairs of words: a map, a group, a reduction or a scatter of Longs under min or max (Half) whose Longs are all scalars (no Long vector or matrix), whose match never chooses by a Long, and whose intrinsics on Longs are the conversions, sign, abs, min, max, clamp and the wrapping arithmetic. Anything else still goes to the ordered backend.
fn brace_depth(module: &Module) -> usize	An upper bound on the module shader’s brace depth: a function body is one, an if or a loop one more, a match two. An if emitted as a select still counts.
fn bindings(module: &Module) -> (usize, usize)	(uniforms, storage) buffers the module’s widest pass binds unpacked: context and parameters, every input, every written output, the failure record where arithmetic can fail, an emitting scatter’s target.
fn packed_inputs(module: &Module, most: usize, most_storage: usize) -> Vec<usize>	The inputs packed into one buffer so the module binds at most most buffers and most_storage storage buffers: the fewest that fit, read- only inputs only (a memory keeps its own), rows before grids and volumes and the last declared first within each. A pack is copied whole before every run, and a grid or a volume is the kind as large as an image or a window; rows are most often a handful of words. Packing k inputs saves k - 1 bindings. Empty when the module fits, or when packing every read-only input is still too wide.
fn sums_whole(module: &Module) -> bool	Whether a scatter or prefix sums integers whole: each total is a word and a high word, checked once every value is in, and the first element whose total overflows is recorded.
fn highs_beside(module: &Module) -> bool	Whether a whole sum keeps its high words in a separate buffer: a prefix, and a parallel scatter. An ordered scatter keeps them as it folds.
fn can_fail(module: &Module) -> bool	Whether the module’s integer arithmetic can fail (+ - * overflow, / % udiv urem by zero, - of the least integer) or its work is accounted. Only such a module’s passes record failures.
fn written_outputs(module: &Module) -> usize	Outputs the main pass writes: every output of a map or a group, each in its own buffer; one for other modes.
fn output_binding(module: &Module, k: usize) -> u32	Binding index of output k: the first at OUTPUT_BINDING, the others after the inputs.
fn folded(groups: u32) -> (u32, u32)	(x, y) workgroups for a one-dimensional pass of groups: rows of at most MAX_GROUPS. The pass’s index is gid.x + gid.y * span, span being workgroup size times MAX_GROUPS; its bounds check drops the threads past the end.
fn dispatch(domain: Domain) -> (u32, u32, u32, u32)	A map’s dispatch over domain: workgroups in x, y, z, and the fold (elements per unit of gid.y) for rows. Rows fill whole workgroups: strips fold wide, a workgroup’s rows on consecutive strips.
fn group_dispatch(domain: Domain, size: u32) -> (u32, u32, u32, u32)	A group’s dispatch over domain: a workgroup a group of size lanes, rows of at most MAX_GROUPS workgroups (folded).

Constants

Name	Type	Value	Brief
present::BLIT	&str	" struct Frame { // window width, window height, image widt	The WGSL that blits a vec4<f32> storage buffer onto the surface.
wgsl::CONTEXT_BINDING	u32	0	Binding index of the context uniform.
wgsl::PARAMS_BINDING	u32	1	Binding index of the parameter uniform.
wgsl::OUTPUT_BINDING	u32	2	Binding index of the output storage buffer.
wgsl::INPUT_BINDING	u32	3	Binding index of the first input storage buffer; input i is at INPUT_BINDING + i.
wgsl::FAILURE_BINDING	u32	90	Binding index of a failing pass’s record. Word 0 is the first failure: all ones less element * 4 + code, the greatest kept, so it names the first element in row-major order; zero is none. Word 1 counts blocks of work taken, word 2 is the most allowed (entelechy_rules::Run).
wgsl::BRACE_LIMIT	usize	127	The deepest brace nesting WGSL compiles.
wgsl::PACKED_BINDING	u32	91	Binding index of the buffer that packs inputs; see packed_inputs.
wgsl::FAILURE_BYTES	u64	32	Bytes of the failure record, rounded to sixteen: the first failure, blocks taken, their limit, the remainder short of a block, and the first element whose whole sum overflows (sums_whole).
wgsl::EMIT_HIGHS_BINDING	u32	92	Binding index of an emitting scatter’s high words, beside its target.
wgsl::FAILED_OVERFLOW	u32	1	A failure’s code in the word: an overflow.
wgsl::FAILED_DIVISION	u32	2	A failure’s code in the word: a division by zero.
wgsl::FAILED_BUDGET	u32	3	A failure’s code in the word: more loop iterations than the budget.
wgsl::WORKGROUP	u32	8	Workgroup edge length in the first two dimensions.
wgsl::CONTEXT_HEAD	usize	16	Context slots before the per-input extents: [width, height, time, button bits], [pointer.x, pointer.y, depth, rate], two slots of key bits, [wheel.x, wheel.y, window.x, window.y], [scale, fold, 1, 0], where fold is the elements per unit of gid.y for a Rows domain, which is dispatched as a grid (else zero), the pad’s two slots ([left.x, left.y, right.x, right.y], [triggers.x, triggers.y, pads, queued]), and eight slots of the characters typed, four a slot. Each input then has [width, height, depth, 0]. Extents, the fold, the key bits, the samples queued and the characters are the bits of u32s, read with bitcast, so every one is exact.
wgsl::OPAQUE_ONE	&str	"ctx[5].z"	The context word holding 1, which the shader compiler cannot fold. Multiplied into an integer dividend, it makes a narrowed value (such as x >>> 16) a whole i32 for division, which Metal miscompiles.
wgsl::MAX_GROUPS	u32	65535	The most workgroups in one dispatch dimension.

Re-exports

Placement, placement, pruned, map, prefix, reduce, scatter, storage, Wait

present::Display

crates/backends/gpu/src/present.rs#L17

The GPU device as a window reaches it: taken from a backend before the backend goes to a runtime, sharing its device, so an interface draws what the backend left resident; the runtime knows only a Backend.

Methods

Function	Description
fn presenter(&self, target: impl Into<SurfaceTarget<'static>>, width: u32, height: u32) -> Result<Presenter, String>	Configures a surface on target (a window handle the backend may keep) of the given size.
fn present(&self, presenter: &mut Presenter, device: &dyn Any + Send + Sync, width: u32, height: u32, window_width: u32, window_height: u32, overlay: Option<Overlay<'_>>) -> Result<Option<Placement>, String>	Draws a resident image (device, the Host’s resident object) into the surface, with overlay over its top-left corner. Returns where the image was placed, or None when the window takes no frame now (occluded, or the surface timed out). Nothing is read back.

Implemented traits: Clone

---

present::Overlay

crates/backends/gpu/src/present.rs#L96

Pixels drawn over the window’s top-left corner: 0x00RRGGBB, width per row.

Properties

Name	Type	Description
pixels	&'a [u32]	The pixels, row by row.
width	u32	Width in window pixels.
height	u32	Height in window pixels.

Implemented traits: Clone, Copy, Debug

---

present::Presenter

crates/backends/gpu/src/present.rs#L106

A window surface a Display draws resident images into.

---

GpuError

crates/backends/gpu/src/lib.rs#L54

The GPU could not be opened.

Properties

Name	Type	Description
0	String

Implemented traits: Debug, Display, Error

---

GpuBackend

crates/backends/gpu/src/lib.rs#L65

A wgpu device with a compute-only contract.

Methods

Function	Description
fn display(&self) -> Display	A display on this backend’s device, for presenting what it leaves resident.
fn measured(&self) -> bool	Whether executions wait for the device; see Backend::set_measured.
fn last_device_time(&self) -> Option<Duration>	The device time of the last measured execution, by its own clock; None when nothing was measured or the adapter has no timestamps. Taken once.
fn wait_floor(&self) -> Duration	The cost of a measured execution’s wait with nothing to wait for: one empty submission polled to completion, the least of sixteen. Every node a profile times carries it before its own work.
fn device_clock_answered(&self) -> bool	Whether the device’s own clock has answered a measured execution: set the first time a resolve returns two different numbers, since a driver may take the queries and resolve zeros. Until then a measured run’s numbers are the call and its wait, and whatever prints them says so.
fn workgroup_memory(&self) -> u32	The bytes a workgroup of this device holds at once: what a group’s exchanges may take.
fn new() -> Result<Self, GpuError>	Opens the default adapter, blocking to wait for the device. Where Entelechy is WebAssembly nothing blocks: a page opens it with GpuBackend::with_wait.
fn with_wait(wait: Wait) -> Result<Self, GpuError>	Opens the fastest adapter, waiting for the device as wait says.
fn with_long_pairs(self) -> Self	This backend computing every Long as a pair of 32-bit words, as on a device without 64-bit integers (a page’s WebGPU): what a test runs that path by on a device that has them.
fn with_pulled_vertices(self) -> Self	This backend drawing triangles a vertex pulled at a time, as on a device whose fragments do not know their primitive: what a test runs that path by on a device that has it.
fn adapter_name(&self) -> &str	The adapter’s name, for diagnostics.
fn device(&self) -> &Device	The wgpu device, for interfaces and tests that speak wgpu directly.

Implemented traits: Backend, Debug

---

wgsl::Longs

crates/backends/gpu/src/wgsl/mod.rs#L54

How a shader computes a Long: as the device’s own 64-bit integer, or, on a device without one (a page’s WebGPU), as a pair of 32-bit words with every operation a helper (pairs_take says which modules can).

Variants

Name	Description
Native	The device’s own 64-bit integer, i64.
Pairs	Two 32-bit words, low first, every operation a helper.

Implemented traits: Clone, Copy, Debug, Eq, PartialEq, StructuralPartialEq

---