Skip to main content

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, &params.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;