isomesh_gpu/field_sampler.rs
1//! Evaluating the field on the GPU, so nothing is uploaded.
2//!
3//! # What this is worth, and what it costs
4//!
5//! After GPU-010a and GPU-012 the upload is **86% of the extraction path** —
6//! 7.04 ms of 8.15 at 129³ — and what is left of it is `field.sample()` on the
7//! CPU plus an irreducible memcpy. Producing the samples here removes both: they
8//! are written where they are read.
9//!
10//! **The cost is the sample-identity that made GPU-005's comparison mean
11//! something.** With [`FieldBuffer::sampled`](crate::FieldBuffer::sampled) both
12//! sides read *the same `f32`s*, because the CPU produced them — which is why
13//! M-142 could report vertex positions agreeing to one ULP and attribute the
14//! residue to a fused multiply-add. Evaluate independently on each side and the
15//! agreement becomes a property of each platform's arithmetic. See
16//! [`GpuField`] for the measured per-field deviation.
17//!
18//! The CPU path keeps its guarantee: `libm` is bit-reproducible across machines
19//! (M-31). **The GPU path acquires no such guarantee**, and that is a property
20//! of the approach rather than of this implementation.
21//!
22//! # The general mechanism is an interpreted edit log, and here is the argument
23//!
24//! GPU-011a proved the win with four fields hard-coded in WGSL, which is not
25//! shippable — a consumer's own field cannot be one of four. GPU-011b had two
26//! candidates and chose **interpreting an edit log**
27//! ([`sample_stack`](FieldSampler::sample_stack)) over **composing the
28//! consumer's WGSL** through [`Composer`](crate::Composer). Four reasons, in
29//! the order they mattered:
30//!
31//! 1. **It is what this crate's world already is.** A scene here is a base
32//! field plus an ordered op list — `BrushStack`, and `paint::Edit` after
33//! E-208. E-207's undo is a re-fold of that log. Consuming the same log puts
34//! the GPU path on the architecture that exists rather than beside it.
35//! 2. **It survives editing, and the alternative does not.** A carve pushes an
36//! op and the GPU re-reads a buffer. Composing WGSL would **recompile a
37//! shader per edit**, which is tolerable for a static CAD model and fatal
38//! for `game_dig` or `game_editor` — the demos where a GPU path would
39//! actually be used.
40//! 3. **It is exactly testable.** `brush::apply` and `brush::smooth_min` define
41//! the fold, so the interpreter is asserted against them sample-for-sample.
42//! Composed WGSL can only be checked against a *second* statement of the
43//! field, which is the drift rule 5 exists to prevent — testable, but only
44//! after the duplication is already there.
45//! 4. **M-154 says the drift is in the expression, not the GPU.** A field of
46//! `abs`/`max`/`min` crosses within 1 ULP; one of sums-of-products does not.
47//! An interpreter evaluating the same primitives has the same drift as
48//! compiled WGSL doing the same maths, so option (b) buys no accuracy.
49//!
50//! **What it costs, stated plainly:** the log is bounded by the primitives the
51//! shader knows — sphere, box, capsule, and the three brush ops. A consumer
52//! whose *base* is an arbitrary analytic SDF is served by
53//! [`fold_into`](FieldSampler::fold_into), which takes that base from a buffer
54//! the caller filled: one upload per grid instead of none, and none per edit.
55//! A consumer whose *brushes* are arbitrary is **not** served, and that is the
56//! CAD half of this crate's audience. Composing consumer WGSL remains the right
57//! answer for them and is additive rather than contradictory: a second
58//! *feature*, not a second path to this one.
59
60use crate::{Composer, FieldBuffer, GridParams, Result};
61
62/// Threads per workgroup, matching `@workgroup_size(64)` in `field.wgsl`.
63const WORKGROUP: u32 = 64;
64
65/// The `select.id` value meaning "the base is in the `base` binding".
66///
67/// Deliberately not a [`GpuField`] variant: that enum's contract is *a
68/// reference field this crate can evaluate*, and `name()` and `sample_on_cpu()`
69/// have no honest answer for a buffer the caller filled. One id past
70/// `GpuField::ALL`, matching `FIELD_SAMPLED` in `field.wgsl`.
71const SAMPLED_BASE_ID: u32 = 4;
72
73/// A reference field this crate can evaluate on the GPU.
74///
75/// # Measured deviation from `isomesh`'s CPU evaluation (M-154)
76///
77/// Same grid, same expressions in the same order, at `h = 0.125` from origin
78/// `-2.0` — both powers of two, so the sample *positions* are bit-identical and
79/// everything below is the field arithmetic alone.
80///
81/// | field | bit-exact | worst absolute |
82/// |---|---:|---:|
83/// | `sphere` | 26,009 / 35,937 | 2.38e-7 |
84/// | `torus` | 25,449 / 35,937 | 4.77e-7 |
85/// | `box_exact` | 30,637 / 35,937 | 1.19e-7 |
86/// | `gyroid` | 3,873 / 35,937 | 6.56e-7 |
87///
88/// **Nothing agrees bit-for-bit, including the fields with no transcendentals**
89/// — a GPU may contract `x*x + y*y + z*z` into fused multiply-adds, rounding
90/// once where `libm` rounds twice. `box_exact` comes closest because its
91/// expression is `abs`/`max`/`min`, exact in IEEE, over a `sqrt` whose argument
92/// is identically zero inside the box.
93///
94/// Every deviation is under `7e-7`, about `5e-6` of a cell at this spacing —
95/// four orders below anything that could move a crossing. **The shape of the
96/// result is what GPU-011b has to design around**: the drift is a property of
97/// the *expression*, not of the GPU, so a field built from exact operations
98/// crosses unchanged and one built from products does not.
99#[derive(Clone, Copy, Debug, PartialEq, Eq)]
100pub enum GpuField {
101 /// Centre origin, radius 1.
102 Sphere,
103 /// Centre origin, major 1, minor 0.3.
104 Torus,
105 /// Centre origin, half-extents `[1, 1, 1]`.
106 BoxExact,
107 /// Scale 1, iso 0. The only one with `sin`/`cos`.
108 Gyroid,
109}
110
111impl GpuField {
112 /// Every field, in shader-id order.
113 pub const ALL: [Self; 4] = [Self::Sphere, Self::Torus, Self::BoxExact, Self::Gyroid];
114
115 /// The name `isomesh`'s `ReferenceField` uses.
116 #[must_use]
117 pub const fn name(self) -> &'static str {
118 match self {
119 Self::Sphere => "sphere",
120 Self::Torus => "torus",
121 Self::BoxExact => "box_exact",
122 Self::Gyroid => "gyroid",
123 }
124 }
125
126 /// The `id` the shader switches on.
127 #[must_use]
128 pub const fn id(self) -> u32 {
129 match self {
130 Self::Sphere => 0,
131 Self::Torus => 1,
132 Self::BoxExact => 2,
133 Self::Gyroid => 3,
134 }
135 }
136
137 /// The same field, evaluated by `isomesh` on the CPU.
138 ///
139 /// The reference the GPU is compared against. It calls the crate's own
140 /// canonical constructors rather than re-stating the constants, so the two
141 /// cannot drift apart in the comparison that is supposed to detect drift.
142 #[must_use]
143 pub fn sample_on_cpu(self, p: [f32; 3]) -> f32 {
144 use isomesh::Sdf;
145 use isomesh::fields::{BoxExact, Gyroid, Sphere, Torus};
146 match self {
147 Self::Sphere => Sphere::<f32>::canonical().sample(p),
148 Self::Torus => Torus::<f32>::canonical().sample(p),
149 Self::BoxExact => BoxExact::<f32>::canonical().sample(p),
150 Self::Gyroid => Gyroid::<f32>::canonical().sample(p),
151 }
152 }
153}
154
155/// One brush shape, matching `isomesh`'s three.
156///
157/// Implements [`Sdf`](isomesh::Sdf) by delegating to `isomesh`'s own types, so
158/// the CPU side of every comparison is the real definition rather than a second
159/// copy of it.
160#[derive(Clone, Copy, Debug, PartialEq)]
161pub enum GpuShape {
162 /// A sphere.
163 Sphere {
164 /// Centre.
165 center: [f32; 3],
166 /// Radius.
167 radius: f32,
168 },
169 /// An axis-aligned box, exact distance.
170 BoxExact {
171 /// Centre.
172 center: [f32; 3],
173 /// Half-extents.
174 half_extents: [f32; 3],
175 },
176 /// The set of points within `radius` of a segment.
177 Capsule {
178 /// One end.
179 a: [f32; 3],
180 /// The other.
181 b: [f32; 3],
182 /// Distance from the segment that counts as inside.
183 radius: f32,
184 },
185}
186
187impl isomesh::Sdf for GpuShape {
188 type Scalar = f32;
189
190 fn sample(&self, p: [f32; 3]) -> f32 {
191 use isomesh::brush::Capsule;
192 use isomesh::fields::{BoxExact, Sphere};
193 match *self {
194 Self::Sphere { center, radius } => Sphere { center, radius }.sample(p),
195 Self::BoxExact {
196 center,
197 half_extents,
198 } => BoxExact {
199 center,
200 half_extents,
201 }
202 .sample(p),
203 Self::Capsule { a, b, radius } => Capsule { a, b, radius }.sample(p),
204 }
205 }
206}
207
208/// What a brush does to the field it is applied to, matching `isomesh`'s
209/// [`BrushOp`](isomesh::brush::BrushOp).
210#[derive(Clone, Copy, Debug, PartialEq)]
211pub enum GpuOp {
212 /// Union: `min(field, shape)`.
213 Add,
214 /// Difference: `max(field, -shape)`.
215 Subtract,
216 /// Union with a rounded join of width `k`.
217 SmoothAdd {
218 /// Join width, in world units.
219 k: f32,
220 },
221}
222
223/// One entry in the edit log.
224#[derive(Clone, Copy, Debug, PartialEq)]
225pub struct GpuBrush {
226 /// The shape being applied.
227 pub shape: GpuShape,
228 /// What to do with it.
229 pub op: GpuOp,
230}
231
232impl GpuBrush {
233 /// Bytes this occupies in the shader's brush array.
234 pub const STRIDE: u64 = 64;
235
236 /// The same brush as `isomesh` sees it.
237 #[must_use]
238 pub fn to_cpu(self) -> isomesh::brush::Brush<GpuShape> {
239 use isomesh::brush::{Brush, BrushOp};
240 Brush {
241 shape: self.shape,
242 op: match self.op {
243 GpuOp::Add => BrushOp::Add,
244 GpuOp::Subtract => BrushOp::Subtract,
245 GpuOp::SmoothAdd { k } => BrushOp::SmoothAdd { k: f64::from(k) },
246 },
247 }
248 }
249
250 /// The 64 bytes the shader reads.
251 ///
252 /// Four `vec4`s, so std140 and std430 agree. The slot meanings are written
253 /// out in `field.wgsl` next to the matching struct — a disagreement between
254 /// the two produces a brush of the right kind in the wrong place, which
255 /// looks like a meshing bug.
256 #[must_use]
257 pub fn to_std140(self) -> [u8; Self::STRIDE as usize] {
258 let (kind, a, a_w, b, b_w) = match self.shape {
259 GpuShape::Sphere { center, radius } => (0u32, center, radius, [0.0f32; 3], 0.0f32),
260 GpuShape::BoxExact {
261 center,
262 half_extents,
263 } => (1, center, 0.0, half_extents, 0.0),
264 GpuShape::Capsule { a, b, radius } => (2, a, radius, b, 0.0),
265 };
266 let (op, k) = match self.op {
267 GpuOp::Add => (0u32, 0.0f32),
268 GpuOp::Subtract => (1, 0.0),
269 GpuOp::SmoothAdd { k } => (2, k),
270 };
271
272 let mut out = [0u8; Self::STRIDE as usize];
273 let words: [[u8; 4]; 16] = [
274 kind.to_le_bytes(),
275 op.to_le_bytes(),
276 0u32.to_le_bytes(),
277 0u32.to_le_bytes(),
278 a[0].to_le_bytes(),
279 a[1].to_le_bytes(),
280 a[2].to_le_bytes(),
281 a_w.to_le_bytes(),
282 b[0].to_le_bytes(),
283 b[1].to_le_bytes(),
284 b[2].to_le_bytes(),
285 b_w.to_le_bytes(),
286 k.to_le_bytes(),
287 0f32.to_le_bytes(),
288 0f32.to_le_bytes(),
289 0f32.to_le_bytes(),
290 ];
291 for (slot, word) in out.as_chunks_mut::<4>().0.iter_mut().zip(words) {
292 slot.copy_from_slice(&word);
293 }
294 out
295 }
296}
297
298/// A compiled pipeline that fills a [`FieldBuffer`] on the GPU.
299#[derive(Debug)]
300pub struct FieldSampler {
301 pipeline: wgpu::ComputePipeline,
302 layout: wgpu::BindGroupLayout,
303 /// Four bytes, bound at binding 4 by every path that does not read it.
304 ///
305 /// One kernel has one bind-group layout, so binding 4 must be filled even
306 /// when `select.id` is a [`GpuField`] and the shader never touches it. The
307 /// obvious filler — the path's own output buffer — is a **validation
308 /// error**, not a free alias: `STORAGE_READ_WRITE` is in
309 /// `wgpu_types::BufferUses::EXCLUSIVE`, and wgpu-core's
310 /// `invalid_resource_state` rejects an exclusive state with more than one
311 /// bit set, so a buffer bound `read_write` at 2 and `read_only` at 4 in the
312 /// same bind group fails `merge_bind_group`. This is the alternative to
313 /// splitting the layout in two, which would mean two pipelines for one
314 /// shader.
315 unused_base: wgpu::Buffer,
316}
317
318impl FieldSampler {
319 /// Compile the kernel.
320 ///
321 /// # Errors
322 ///
323 /// Propagates composition failure, which would mean this crate's own
324 /// shaders are inconsistent.
325 pub fn new(device: &wgpu::Device) -> Result<Self> {
326 let source = Composer::with_builtins().compose("field", &[])?;
327 let module = device.create_shader_module(wgpu::ShaderModuleDescriptor {
328 label: Some("isomesh field sampler"),
329 source: wgpu::ShaderSource::Wgsl(source.into()),
330 });
331
332 let entry = |binding: u32, ty: wgpu::BufferBindingType| wgpu::BindGroupLayoutEntry {
333 binding,
334 visibility: wgpu::ShaderStages::COMPUTE,
335 ty: wgpu::BindingType::Buffer {
336 ty,
337 has_dynamic_offset: false,
338 min_binding_size: None,
339 },
340 count: None,
341 };
342 let layout = device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
343 label: Some("isomesh field sampler bindings"),
344 entries: &[
345 entry(0, wgpu::BufferBindingType::Uniform),
346 entry(1, wgpu::BufferBindingType::Uniform),
347 entry(2, wgpu::BufferBindingType::Storage { read_only: false }),
348 entry(3, wgpu::BufferBindingType::Storage { read_only: true }),
349 entry(4, wgpu::BufferBindingType::Storage { read_only: true }),
350 ],
351 });
352 let pipeline_layout = device.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
353 label: Some("isomesh field sampler layout"),
354 bind_group_layouts: &[Some(&layout)],
355 immediate_size: 0,
356 });
357
358 Ok(Self {
359 pipeline: device.create_compute_pipeline(&wgpu::ComputePipelineDescriptor {
360 label: Some("isomesh field sampler"),
361 layout: Some(&pipeline_layout),
362 module: &module,
363 entry_point: Some("sample_field"),
364 compilation_options: wgpu::PipelineCompilationOptions::default(),
365 cache: None,
366 }),
367 layout,
368 unused_base: device.create_buffer(&wgpu::BufferDescriptor {
369 label: Some("isomesh field sampler unused base"),
370 // One `f32`: the shader binds `array<f32>`, whose late-bound
371 // minimum is one stride, and nothing ever reads it.
372 size: 4,
373 usage: wgpu::BufferUsages::STORAGE,
374 mapped_at_creation: false,
375 }),
376 })
377 }
378
379 /// Allocate a [`FieldBuffer`] and fill it on the GPU.
380 ///
381 /// Nothing is uploaded but two uniforms — the grid and the field id, 48
382 /// bytes between them — where
383 /// [`FieldBuffer::sampled`](crate::FieldBuffer::sampled) copies four bytes
384 /// per sample.
385 ///
386 /// # Errors
387 ///
388 /// [`Error::GridTooLarge`](crate::Error::GridTooLarge) if the sample count
389 /// needs more workgroups than the adapter will dispatch.
390 pub fn sample(
391 &self,
392 device: &wgpu::Device,
393 queue: &wgpu::Queue,
394 params: GridParams,
395 field: GpuField,
396 ) -> Result<FieldBuffer> {
397 self.sample_stack(device, queue, params, field, &[])
398 }
399
400 /// Allocate a [`FieldBuffer`] and fill it from a base field **and an edit
401 /// log**, on the GPU.
402 ///
403 /// The general mechanism GPU-011b chose, and the argument for choosing it
404 /// over composing a consumer's WGSL is on [`FieldSampler`].
405 ///
406 /// `brushes` is folded first to last over the base, exactly as
407 /// [`BrushStack`](isomesh::brush::BrushStack) does. **That order is part of
408 /// the value**: a log mixing adds and subtracts does not commute, and one
409 /// containing a smooth add is not even associative (M-36..M-38), so a
410 /// shader that reordered for parallelism would compute a different solid.
411 ///
412 /// # Errors
413 ///
414 /// [`Error::GridTooLarge`](crate::Error::GridTooLarge) if the sample count
415 /// needs more workgroups than the adapter will dispatch.
416 pub fn sample_stack(
417 &self,
418 device: &wgpu::Device,
419 queue: &wgpu::Queue,
420 params: GridParams,
421 field: GpuField,
422 brushes: &[GpuBrush],
423 ) -> Result<FieldBuffer> {
424 let out = FieldBuffer::new(device, params);
425 self.run(device, queue, field.id(), brushes, &out, &self.unused_base)?;
426 Ok(out)
427 }
428
429 /// Fold an edit log over samples the caller already put in `base`, writing
430 /// `out`.
431 ///
432 /// [`sample_stack`](Self::sample_stack) with the base field taken out of the
433 /// shader's vocabulary: the log, the fold order and the arithmetic are the
434 /// same kernel, and what changes is only where the first value comes from.
435 /// This is the case this module's own doc calls out — a consumer whose base
436 /// is an arbitrary analytic SDF — and the cost of serving it is that the
437 /// base is uploaded once instead of never.
438 ///
439 /// The base and the output are two buffers rather than one folded in place,
440 /// because the caller re-derives the output from a pristine base on every
441 /// call — that is what makes a cached base impossible to leave stale — and
442 /// an in-place fold would consume it.
443 ///
444 /// `out` is taken by shared reference because nothing on this side mutates
445 /// it: the write is a queue submission, exactly as it is for the buffer
446 /// `sample_stack` allocates and returns.
447 ///
448 /// # Errors
449 ///
450 /// [`Error::SampleCountMismatch`](crate::Error::SampleCountMismatch) if
451 /// `base` and `out` do not describe the same number of samples — a fold
452 /// between two grids would read the wrong positions and produce a buffer
453 /// that still looks meshable.
454 /// [`Error::GridTooLarge`](crate::Error::GridTooLarge) if the sample count
455 /// needs more workgroups than the adapter will dispatch.
456 pub fn fold_into(
457 &self,
458 device: &wgpu::Device,
459 queue: &wgpu::Queue,
460 base: &FieldBuffer,
461 out: &FieldBuffer,
462 brushes: &[GpuBrush],
463 ) -> Result<()> {
464 let expected = base.params().sample_count();
465 let got = out.params().sample_count();
466 if expected != got {
467 return Err(crate::Error::SampleCountMismatch { expected, got });
468 }
469 self.run(device, queue, SAMPLED_BASE_ID, brushes, out, base.buffer())
470 }
471
472 /// One dispatch of `sample_field`, which is the whole of both public entry
473 /// points.
474 ///
475 /// Two public entry points over one private dispatch, because two
476 /// transcriptions of a bind group are two places for a binding index to
477 /// drift.
478 ///
479 /// The grid is `out.params()` rather than an argument: a caller that could
480 /// pass a grid disagreeing with the buffer it writes would get a buffer that
481 /// still looks meshable. `base` is bound at 4 on every path, and is
482 /// [`Self::unused_base`] when `field_id` names a [`GpuField`] the shader
483 /// evaluates itself.
484 fn run(
485 &self,
486 device: &wgpu::Device,
487 queue: &wgpu::Queue,
488 field_id: u32,
489 brushes: &[GpuBrush],
490 out: &FieldBuffer,
491 base: &wgpu::Buffer,
492 ) -> Result<()> {
493 let params = out.params();
494 let samples = params.sample_count();
495 let groups = samples.div_ceil(u64::from(WORKGROUP));
496 if groups > u64::from(device.limits().max_compute_workgroups_per_dimension) {
497 return Err(crate::Error::GridTooLarge {
498 samples: params.samples(),
499 });
500 }
501
502 let grid = device.create_buffer(&wgpu::BufferDescriptor {
503 label: Some("isomesh grid params"),
504 size: GridParams::UNIFORM_SIZE,
505 usage: wgpu::BufferUsages::UNIFORM | wgpu::BufferUsages::COPY_DST,
506 mapped_at_creation: false,
507 });
508 queue.write_buffer(&grid, 0, ¶ms.to_std140());
509
510 let select = device.create_buffer(&wgpu::BufferDescriptor {
511 label: Some("isomesh field select"),
512 size: 16,
513 usage: wgpu::BufferUsages::UNIFORM | wgpu::BufferUsages::COPY_DST,
514 mapped_at_creation: false,
515 });
516 let mut bytes = [0u8; 16];
517 bytes[..4].copy_from_slice(&field_id.to_le_bytes());
518 let count = u32::try_from(brushes.len()).map_err(|_| crate::Error::GridTooLarge {
519 samples: params.samples(),
520 })?;
521 bytes[4..8].copy_from_slice(&count.to_le_bytes());
522 queue.write_buffer(&select, 0, &bytes);
523
524 // At least one element: wgpu rejects a zero-sized binding, and an empty
525 // log is the ordinary case rather than an error.
526 let log = device.create_buffer(&wgpu::BufferDescriptor {
527 label: Some("isomesh brush log"),
528 size: GpuBrush::STRIDE * brushes.len().max(1) as u64,
529 usage: wgpu::BufferUsages::STORAGE | wgpu::BufferUsages::COPY_DST,
530 mapped_at_creation: false,
531 });
532 if !brushes.is_empty() {
533 let mut packed = Vec::with_capacity(brushes.len() * GpuBrush::STRIDE as usize);
534 for brush in brushes {
535 packed.extend_from_slice(&brush.to_std140());
536 }
537 queue.write_buffer(&log, 0, &packed);
538 }
539
540 fn entry(binding: u32, buffer: &wgpu::Buffer) -> wgpu::BindGroupEntry<'_> {
541 wgpu::BindGroupEntry {
542 binding,
543 resource: buffer.as_entire_binding(),
544 }
545 }
546 let bind_group = device.create_bind_group(&wgpu::BindGroupDescriptor {
547 label: Some("isomesh field sampler"),
548 layout: &self.layout,
549 entries: &[
550 entry(0, &grid),
551 entry(1, &select),
552 entry(2, out.buffer()),
553 entry(3, &log),
554 entry(4, base),
555 ],
556 });
557
558 let mut encoder = device.create_command_encoder(&wgpu::CommandEncoderDescriptor {
559 label: Some("isomesh field sampler"),
560 });
561 {
562 let mut pass = encoder.begin_compute_pass(&wgpu::ComputePassDescriptor {
563 label: Some("isomesh field sampler"),
564 timestamp_writes: None,
565 });
566 pass.set_pipeline(&self.pipeline);
567 pass.set_bind_group(0, &bind_group, &[]);
568 // Bounded against the adapter's limit above.
569 pass.dispatch_workgroups(groups as u32, 1, 1);
570 }
571 queue.submit(Some(encoder.finish()));
572
573 Ok(())
574 }
575}
576
577#[cfg(test)]
578mod tests;