Skip to main content

Crate isomesh_gpu

Crate isomesh_gpu 

Source
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-gpuwgpubevy
0.0.x29.0.30.19

§What is here

A whole extraction pipeline, not a substrate waiting for one.

ExtractionMarchingCubesGpu — 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 GPUGpuField, GpuShape, GpuOp, GpuBrush, FieldSampler — brushes folded device-side, so an edit does not cross the bus
The plumbing extraction needsPrefixScan and DeferredScan for compaction, GridParams for std140 packing, FieldBuffer, read_buffer
Drawing without a readbackMeshShaderRenderer, IndirectGeometry, and probe_mesh_shaders to ask first
Distance transformsJumpFlood
Shader sourcesMARCHING_CUBES_WGSL, FIELD_WGSL, GRID_WGSL, SCAN_WGSL, JUMP_FLOOD_WGSL, MESH_RENDER_WGSL, composed by Composer
No device of your ownheadless

§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/axisCPUGPU, field evaluated on the GPU
17³0.06 ms0.22 msCPU ahead 3.7×
33³0.34 ms0.23 msGPU ahead 1.5×
65³2.44 ms0.27 msGPU ahead 9×
129³20.14 ms0.54 msGPU 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§

pub use jump_flood::JumpFlood;
pub use wgpu;

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.
DeferredGeometry
Several Readbacks in flight at once, keyed by what they are read-backs of, collected in submission order.
DeferredScan
A scan whose total is still on the GPU.
ExtractTimings
Where the time went inside one extract.
FieldBuffer
A grid of f32 field samples in GPU memory, with the grid that describes it.
FieldSampler
A compiled pipeline that fills a FieldBuffer on 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.
GridParams
A sampling grid: how many samples, where they start, how far apart.
IndirectGeometry
An extraction that never synchronised: the triangle count is still on the GPU, and the draw reads it from there.
MarchingCubesGpu
A compiled Marching Cubes pipeline, and the table it dispatches against.
MeshShaderRenderer
A compiled mesh-shader pipeline for isomesh’s triangle soup.
MeshShaderReport
One adapter’s answer.
PrefixScan
The compiled scan pipelines.
Readback
A read-back in flight, with no wait in it.
ScanOutput
What a scan produced.
Span
One pass’s GPU-side span.
Spans
Every span resolved from one collector.
StageTimestamps
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’s BrushOp.
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 bytes from source back to the CPU as f32s.
read_buffer_u32
The same, as u32.
read_bytes
Copy bytes from source back 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 requests into one staging buffer and start mapping it.

Type Aliases§

Result
The result of a fallible isomesh-gpu operation.