isomesh-gpu
⚠️ Vibe Coded. Written by AI agents working from a human's direction, covered by tests rather than a line-by-line human review. Read the code before you rely on it for something you care about.
GPU isosurface extraction for isomesh, on raw wgpu. No engine
types anywhere in the public API.

E-303: field to pixels without the geometry ever crossing the bus — four bytes come home per frame. The timings table below is the compute half of the same story.
Status: experimental · no Bevy dependency · MSRV 1.89
The rule
Every entry point takes &wgpu::Device, &wgpu::Queue or &mut wgpu::CommandEncoder.
A Bevy consumer reaches the raw device through RenderDevice::wgpu_device() and hands it in. A CAD
tool passes its own. A test uses headless::Gpu. There is no second entry point that takes a
RenderDevice, because that would make the engine a dependency of the algorithm instead of a caller
of it.
The version pin is load-bearing
wgpu 29.0.3, matching Bevy 0.19 — and it has to be exact. Cargo resolves two wgpu majors side by
side with no resolution error; the failure arrives much later as expected TextureFormat, found a different TextureFormat. Verified: this workspace's lockfile and bevy_isomesh's independently
resolve wgpu 29.0.4 and wgpu-types 29.0.4, the same patch in both.
isomesh-gpu |
wgpu requirement |
resolves to, today | bevy |
|---|---|---|---|
| 0.0.x | 29.0.3 | 29.0.4 | 0.19 |
Cargo.toml declares 29.0.3 and both lockfiles resolve 29.0.4, because patch releases float by
design. The major and minor are what bevy_render 0.19 pins and what must not move independently.
No software fallback
headless::Gpu::new asks for a high-performance adapter with force_fallback_adapter: false, and a
missing adapter is an error rather than a CPU reference driver. The entire reason this crate exists is
to be compared against the CPU path — a benchmark that silently ran on lavapipe reports numbers orders
of magnitude off and looks merely slow.
So a machine with no GPU fails these tests. That is the intended behaviour.
What is here
use Sphere;
use ;
let gpu = new?;
let grid = new?;
let field = sampled?;
let back = read_buffer?;
# drop;
# Ok::
That block is compiled — never run — by every cargo test: the fence is rust,no_run, because a CI
runner has no adapter and headless::Gpu::new refuses to pretend otherwise.
-
GridParams— a validated sampling grid, with the 32-byte two-vec4layout a shader reads it as. Positions are the index multiplied, never accumulated;isomesh's M-70 and M-73 both record cracks caused by the other choice. -
FieldBuffer—f32samples in GPU memory, uploaded from a slice or sampled from anyisomesh::Sdf. -
read_buffer— results back to the CPU, blocking. -
headless::Gpu— a device with no window, and anAdapterReportof what it turned out to be. -
Composer— WGSL#includeand#ifdef, over modules compiled in withinclude_str!. Notnaga_oil; see the module docs for why. -
FEATURES— every compile-time flag any shader here reads. The validation sweep covers the cross product of modules with every subset of it, so a flag missing from this list is a branch nothing ever compiles. -
MarchingCubesGpu— the compute kernel. Two passes (count, prefix-sum, emit) so the output is dense and in cell order, which is what makes it comparable with the CPU and with itself. -
PrefixScan,DeferredScan,ScanOutput,cpu_prefix_sum— the compaction the emit pass needs, and a CPU reference for it that the tests check against. -
GpuField,GpuShape,GpuOp,GpuBrush,FieldSampler— the field evaluated device-side, brushes folded on the GPU, so an edit does not cross the bus to be applied. -
MeshShaderRenderer,IndirectGeometry,MeshShaderReport,probe_mesh_shaders— drawing straight out of the compute output, with no vertex buffer and no readback. Probe before you build: on an adapter withoutEXPERIMENTAL_MESH_SHADERthe pipeline is not created and the report says so. -
JumpFlood— a distance transform on the GPU. -
ExtractTimings,GpuGeometry,GpuMesh— what came back, and how long each stage took. -
The WGSL itself —
MARCHING_CUBES_WGSL,FIELD_WGSL,GRID_WGSL,SCAN_WGSL,JUMP_FLOOD_WGSL,MESH_RENDER_WGSL, all public so a consumer can compose against them.
The case table is uploaded, not transcribed
The usual way a GPU port breaks "never guess a case table" is by pasting a second copy into WGSL.
There isn't one. case_table_bytes() packs isomesh::marching_cubes::table::CASES — itself derived
by a const fn rather than copied from a paper — and a test unpacks the bytes and compares all 256
entries.
Is it faster? 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 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× |
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. 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. Upload CPU-sampled data and the upload is 87% of the path — 8.37 ms at 129³, so 2.4× rather than 37×, and it does not take field evaluation off the CPU's budget, it adds a copy to it. Evaluate it in the shader and that cost stops existing.
Three tickets took this path from 15.01 ms to 0.54 ms at 129³ and none made the extractor faster. Every gain was data movement removed (M-145, M-150, M-155).
Agreement with the CPU, vertex by vertex
Same grid, same samples, same table, 33³ sphere:
| triangle count vs CPU | equal, on sphere, torus and box_exact |
| vertices bit-identical to a CPU vertex | 6,507 of 6,936 |
| within one ULP per axis | 429 |
| further than one ULP | 0 |
The 1-ULP miss is float contraction, not the algorithm: WGSL permits a multiply-add to be fused, and this driver takes it, rounding once where the CPU rounds twice. The test asserts the bound, so two ULPs would fail it.
Normals are the one deliberate divergence — a shader cannot call Sdf::gradient, so it central-
differences the sample grid. isomesh's M-65 measures that at 0.460° worst against the analytic
gradient at 17³, converging at h².
Run it
Three examples, none of which needs a window — this crate's whole API takes &wgpu::Device, so a
demo that required an engine would be demonstrating the engine.
--release matters for the second one. A debug-build CPU extraction is 37–62× slower — measured
in this repo (FINDINGS M-152), not folklore — which would flatter the GPU by roughly the factor the
example exists to measure.
gpu_vs_cpu on an RTX 3090 / Vulkan, sphere, field evaluation included on both sides:
| n | triangles | cpu ms | gpu+read ms | gpu ms | vs cpu | no-read |
|---|---|---|---|---|---|---|
| 17 | 1,064 | 0.056 | 0.290 | 0.172 | 5.2× slower | 3.1× slower |
| 33 | 4,280 | 0.342 | 0.326 | 0.174 | 1.1× | 2.0× |
| 49 | 9,512 | 1.011 | 0.410 | 0.223 | 2.5× | 4.5× |
| 65 | 17,192 | 2.269 | 0.516 | 0.274 | 4.4× | 8.3× |
| 97 | 38,456 | 6.954 | 0.831 | 0.361 | 8.4× | 19.3× |
| 129 | 68,648 | 16.471 | 1.315 | 0.547 | 12.5× | 30.1× |
Two things there matter more than the ratio. The GPU loses below about 25³ — the top row is real and the example prints it rather than starting the table where the story improves. And the last column is nearly flat: 0.172 → 0.547 ms across a 420× increase in cells, because the samples are produced where they are read and the bus is never touched. The extractor is not remotely saturated at 129³.
Validation
Two layers, and they catch different things.
The naga sweep needs no adapter and catches "compiles on my Vulkan driver, explodes on DX12". A
companion test feeds the validator invalid WGSL and asserts it rejects it — a gate that has only
ever passed is indistinguishable from one that cannot fail.
Mesh shaders
Reports every adapter's EXPERIMENTAL_MESH_SHADER bits, then the three things the bits do not say.
Measured here (RTX 3090 / Vulkan): advertised, multiview, points.
Reaching them needs no unsafe from this repository. Enabling the feature does require a token
whose constructor is a const unsafe fn — but this crate never opens a device, only borrows one, and
Bevy writes that unsafe itself (bevy_render 0.19, renderer/mod.rs:335). Bevy's default
Functionality priority requests every advertised feature, so its device already reports
mesh_shader=true here. These crates stay 100% safe Rust.
wgpu's own source settles the Metal question: the feature reaches Vulkan, DX12 and Metal, but "naga is only supported on vulkan; on other platforms you will have to use passthrough shaders." So mesh shaders are a fork in the shader pipeline, not a flag on it. Metal is still unmeasured — run the probe there.
Part of the Coven
isomesh-gpu is one of the Bevy Coven crates, built in the isomesh repository. The Cauldron, the Coven's editor, uses it for caves, overhangs and carving: see use it in the Cauldron.
Who and licence
Maintained by @Ladvien. Issues go to github.com/bevy-coven/isomesh/issues; contributions follow the org's CONTRIBUTING.md.
MIT OR Apache-2.0, at your option.