Expand description
GPU isosurface extraction for isomesh, on raw wgpu.
use isomesh_gpu::{MarchingCubesGpu, headless};
// Any wgpu device will do -- Bevy's via `RenderDevice::wgpu_device()`, a CAD
// tool's own, or this one. The API never names an engine type.
let gpu = headless::Gpu::new()?;
let mut mc = MarchingCubesGpu::new(gpu.device(), gpu.queue())?;§The one rule this crate exists to keep
Every public entry point takes &wgpu::Device, &wgpu::Queue or
&mut wgpu::CommandEncoder, and never an engine type. A Bevy consumer
reaches the raw device through RenderDevice::wgpu_device() and hands it in;
a CAD tool passes its own; a test passes one from headless. There is no
second entry point that takes a RenderDevice, because that would make the
engine a dependency of the algorithm rather than a caller of it.
That is also why headless exists in the library and not only in tests: a
CAD tool with no renderer at all still needs a device, and a GPU path that
can only be reached through a game engine has already leaked.
§The wgpu version is a hard pin, and getting it wrong does not fail loudly
wgpu 29.0.3 exactly, matching Bevy 0.19. Cargo resolves two wgpu majors
side by side with no resolution error — verified in
docs/research/2026-08-11-meshing-crate-architecture.md §6, where adding
wgpu 30 alongside bevy 0.19 locks 317 packages containing both. The
failure arrives much later and reads as a type error about TextureFormat
not matching itself.
isomesh-gpu | wgpu | bevy |
|---|---|---|
| 0.0.x | 29.0.3 | 0.19 |
§What is here
A whole extraction pipeline, not a substrate waiting for one.
| Extraction | MarchingCubesGpu — the case table is uploaded rather than transcribed, so there is one table in the repository and the GPU reads the same bytes the CPU does (case_table_bytes) |
| Fields on the GPU | GpuField, GpuShape, GpuOp, GpuBrush, FieldSampler — brushes folded device-side, so an edit does not cross the bus |
| The plumbing extraction needs | PrefixScan and DeferredScan for compaction, GridParams for std140 packing, FieldBuffer, read_buffer |
| Drawing without a readback | MeshShaderRenderer, IndirectGeometry, and probe_mesh_shaders to ask first |
| Distance transforms | JumpFlood |
| Shader sources | MARCHING_CUBES_WGSL, FIELD_WGSL, GRID_WGSL, SCAN_WGSL, JUMP_FLOOD_WGSL, MESH_RENDER_WGSL, composed by Composer |
| No device of your own | headless |
§Is it faster than the CPU? Above about 33³, yes — by 37× at 129³
Sphere, warmed, median of three, RTX 3090 over Vulkan, against a
single-threaded CPU extraction. docs/measurements/gpu_vs_cpu.csv.
| samples/axis | CPU | GPU, field evaluated on the GPU | |
|---|---|---|---|
| 17³ | 0.06 ms | 0.22 ms | CPU ahead 3.7× |
| 33³ | 0.34 ms | 0.23 ms | GPU ahead 1.5× |
| 65³ | 2.44 ms | 0.27 ms | GPU ahead 9× |
| 129³ | 20.14 ms | 0.54 ms | GPU ahead 37× |
The shape is the finding. That GPU column is nearly flat across a 420×
rise in cell count, because extraction was never the cost: count + emit is
0.045 ms at 129³ and does not move with resolution. Below ~33³ a fixed
~0.22 ms of setup is larger than the whole job, and the CPU wins.
§Where you evaluate the field decides the rest
Sample on the CPU and hand over a FieldBuffer and the upload is 87% of
the path — 8.37 ms at 129³, so 2.4× ahead instead of 37×. Worse, that
design does not take field evaluation off the CPU’s budget; it adds a copy to
it, and field evaluation is 65–74% of the whole job on a noise field.
Evaluate it in the shader instead — GpuField, GpuShape, GpuOp,
GpuBrush — and the upload stops existing, because the samples are
produced where they are read.
A base the shader has no name for — an arbitrary analytic SDF, which is half
this crate’s audience — takes the third option:
FieldSampler::fold_into reads that base from a buffer the caller filled
and folds the edit log over it on the device. One upload per grid instead
of none, and none per edit, which is what makes it the right shape for an
editor: bevy_isomesh’s game_dig samples its terrain once per chunk and
thereafter moves 64 bytes per surviving brush and no samples at all.
Three tickets took this path from 15.01 ms to 0.54 ms at 129³ and none of
them made the extractor faster. Every gain was data movement removed: a GPU
prefix scan so 8.4 MB of per-cell counts never come home (M-150), then
device-side field evaluation (M-155). What is left after that is the geometry
read-back, and MeshShaderRenderer removes even that by drawing straight
out of the compute output.
use isomesh::fields::Sphere;
use isomesh_gpu::{FieldBuffer, GridParams, headless};
let gpu = headless::Gpu::new()?;
let grid = GridParams::new([33; 3], [-2.0; 3], 0.125)?;
// Takes &Device and &Queue -- never an engine type.
let field = FieldBuffer::sampled(
gpu.device(),
gpu.queue(),
grid,
&Sphere::<f32>::canonical(),
)?;
assert_eq!(field.params().sample_count(), 33 * 33 * 33);Re-exports§
Modules§
- headless
- A device with no window, and a report of what it turned out to be.
- jump_
flood - Jump flooding: a distance field in
O(log n)passes, on the GPU.
Structs§
- Composer
- A registry of WGSL modules, and the preprocessor over them.
- Deferred
Geometry - Several
Readbacks in flight at once, keyed by what they are read-backs of, collected in submission order. - Deferred
Scan - A scan whose total is still on the GPU.
- Extract
Timings - Where the time went inside one
extract. - Field
Buffer - A grid of
f32field samples in GPU memory, with the grid that describes it. - Field
Sampler - A compiled pipeline that fills a
FieldBufferon the GPU. - GpuBrush
- One entry in the edit log.
- GpuGeometry
- Extraction output left in GPU memory.
- GpuMesh
- A triangle soup read back from the GPU.
- Grid
Params - A sampling grid: how many samples, where they start, how far apart.
- Indirect
Geometry - An extraction that never synchronised: the triangle count is still on the GPU, and the draw reads it from there.
- Marching
Cubes Gpu - A compiled Marching Cubes pipeline, and the table it dispatches against.
- Mesh
Shader Renderer - A compiled mesh-shader pipeline for isomesh’s triangle soup.
- Mesh
Shader Report - One adapter’s answer.
- Prefix
Scan - The compiled scan pipelines.
- Readback
- A read-back in flight, with no wait in it.
- Scan
Output - What a scan produced.
- Span
- One pass’s GPU-side span.
- Spans
- Every span resolved from one collector.
- Stage
Timestamps - A query set, its resolve chain, and the cursor into it.
Enums§
- Error
- Everything this crate can fail at.
- GpuField
- A reference field this crate can evaluate on the GPU.
- GpuOp
- What a brush does to the field it is applied to, matching
isomesh’sBrushOp. - GpuShape
- One brush shape, matching
isomesh’s three.
Constants§
- FEATURES
- Every compile-time flag any shader here reads.
- FIELD_
WGSL - Reference fields evaluated on the GPU. Includes
GRID_WGSL. - GRID_
WGSL - The shader-side counterpart of
GridParams. - JUMP_
FLOOD_ WGSL - Jump-flood distance transform, S-005. Includes
GRID_WGSL. - MARCHING_
CUBES_ WGSL - The Marching Cubes compute kernel. Includes
GRID_WGSL. - MAX_
PASSES - The most passes one extraction can time.
- MESH_
RENDER_ WGSL - The mesh-shader render pipeline. Standalone: it consumes the compute output’s buffers and needs no grid.
- SCAN_
WGSL - The hierarchical exclusive prefix scan over per-cell triangle counts.
Functions§
- case_
table_ bytes - The 256-case table, packed for the shader.
- cpu_
prefix_ sum - The exclusive prefix sum, on the CPU.
- probe_
mesh_ shaders - Probe every adapter on every backend this build supports.
- read_
buffer - Copy
bytesfromsourceback to the CPU asf32s. - read_
buffer_ u32 - The same, as
u32. - read_
bytes - Copy
bytesfromsourceback to the CPU, untyped. - read_
bytes_ many - Copy several buffers back to the CPU in one submission and one device wait.
- read_
bytes_ many_ deferred - Copy
requestsinto one staging buffer and start mapping it.
Type Aliases§
- Result
- The result of a fallible
isomesh-gpuoperation.