1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
//! GPU isosurface extraction for [`isomesh`], on raw `wgpu`.
//!
//! ```no_run
//! 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())?;
//! # let _ = &mut mc;
//! # Ok::<(), isomesh_gpu::Error>(())
//! ```
//!
//! # 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.
//!
//! 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.
//!
//! ```no_run
//! use isomesh::fields::Sphere;
//! use isomesh_gpu::{FieldBuffer, GridParams, headless};
//!
//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
//! 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);
//! # Ok(())
//! # }
//! ```
pub use ;
pub use ;
pub use ;
pub use GridParams;
pub use JumpFlood;
pub use ;
pub use MeshShaderRenderer;
pub use ;
pub use ;
pub use ;
/// Compiles the README's example as a doctest, without putting the README into
/// these docs — the same pattern `isomesh` uses. The README's fence is
/// `rust,no_run`: it must compile everywhere, including a CI runner with no
/// adapter, and execute nowhere, because [`headless::Gpu::new`] refuses to fall
/// back to a software device.
;