pointblitz-web 0.2.0

PointBlitz browser target (wasm)
Documentation
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
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
//! The browser viewer: a WebGPU surface on a canvas around the core `Scene` and `Renderer`.

use crate::json_str;
use crate::oneshot::Signal;
use pointblitz_core::renderer::DEPTH_FORMAT;
use pointblitz_core::{Camera, GpuTimer, Inserted, Renderer, Scene};
use std::cell::RefCell;
use std::rc::Rc;
use wasm_bindgen::prelude::*;

#[wasm_bindgen]
pub struct Viewer {
    surface: wgpu::Surface<'static>,
    device: wgpu::Device,
    queue: wgpu::Queue,
    config: wgpu::SurfaceConfiguration,
    depth: wgpu::TextureView,
    renderer: Renderer,
    scene: Scene,
    camera: Camera,
    adapter: String,
    /// Offscreen target of the canvas size and format for synchronised frames (orbit).
    offscreen: Option<(wgpu::Texture, wgpu::TextureView)>,
    /// One pixel of the last offscreen frame is copied here; mapping it waits for the GPU.
    readback: Option<wgpu::Buffer>,
    /// Where the last `render_offscreen` spent its time, ms (P4.2): record, copy, finish, submit.
    stages: [f64; 4],
    /// Copy the first pixel of each offscreen frame for `readback_done` (on by default). On WebGL2 the
    /// copy makes the GL work run inside submit; without it the same work runs at the page's
    /// readPixels and frames got slower (P4.2: p50 4.2 → 6.2 ms), so it stays on there too.
    readback_copy: bool,
    /// GPU timestamps of the offscreen frames (decision 0049), when the device has them.
    timer: Rc<RefCell<Option<GpuTimer>>>,
    /// The next offscreen frames are timed (between `gpu_timer_start` and `gpu_timer_read`).
    timing: bool,
}

fn err(what: &str, e: impl std::fmt::Display) -> JsValue {
    JsValue::from_str(&format!("{what}: {e}"))
}

fn depth_view(device: &wgpu::Device, w: u32, h: u32) -> wgpu::TextureView {
    device
        .create_texture(&wgpu::TextureDescriptor {
            label: Some("depth"),
            size: wgpu::Extent3d {
                width: w,
                height: h,
                depth_or_array_layers: 1,
            },
            mip_level_count: 1,
            sample_count: 1,
            dimension: wgpu::TextureDimension::D2,
            format: DEPTH_FORMAT,
            usage: wgpu::TextureUsages::RENDER_ATTACHMENT,
            view_formats: &[],
        })
        .create_view(&wgpu::TextureViewDescriptor::default())
}

#[wasm_bindgen]
impl Viewer {
    /// Opens WebGPU on `canvas` (its `width`/`height` attributes set the drawing size).
    ///
    /// `backend`: `auto` (WebGPU when the browser has it, otherwise WebGL2), `webgpu` or `webgl`.
    /// A canvas keeps the first context type it was given, so the choice is made before the surface.
    /// `memory_hints`: `performance` (wgpu default) or `memory` (allocator favours memory).
    pub async fn create(
        canvas: web_sys::HtmlCanvasElement,
        backend: String,
        memory_hints: String,
    ) -> Result<Viewer, JsValue> {
        let (w, h) = (canvas.width().max(1), canvas.height().max(1));
        let webgpu = match backend.as_str() {
            "webgpu" => true,
            "webgl" => false,
            #[cfg(not(feature = "webgl"))]
            "auto" | "" if !wgpu::util::is_browser_webgpu_supported().await => {
                return Err(JsValue::from_str(
                    "no WebGPU, and this module was built without WebGL2",
                ));
            }
            "auto" | "" => wgpu::util::is_browser_webgpu_supported().await,
            other => return Err(JsValue::from_str(&format!("unknown backend {other}"))),
        };
        let mut desc = wgpu::InstanceDescriptor::new_without_display_handle();
        desc.backends = if webgpu {
            wgpu::Backends::BROWSER_WEBGPU
        } else {
            wgpu::Backends::GL
        };
        let instance = wgpu::Instance::new(desc);
        let surface = instance
            .create_surface(wgpu::SurfaceTarget::Canvas(canvas))
            .map_err(|e| err("surface", e))?;
        let adapter = instance
            .request_adapter(&wgpu::RequestAdapterOptions {
                power_preference: wgpu::PowerPreference::HighPerformance,
                compatible_surface: Some(&surface),
                ..Default::default()
            })
            .await
            .map_err(|e| err("adapter", e))?;
        let info = adapter.get_info();
        let (device, queue) = adapter
            .request_device(&wgpu::DeviceDescriptor {
                memory_hints: if memory_hints == "memory" {
                    wgpu::MemoryHints::MemoryUsage
                } else {
                    wgpu::MemoryHints::Performance
                },
                // WebGL2 cannot meet wgpu's default limits; ask only for what WebGL2 guarantees,
                // raised to the adapter's texture sizes.
                // GPU timestamps for the orbit frames when the adapter has them (decision 0049).
                required_features: if webgpu {
                    adapter.features() & wgpu::Features::TIMESTAMP_QUERY
                } else {
                    wgpu::Features::empty()
                },
                required_limits: if webgpu {
                    wgpu::Limits::default()
                } else {
                    wgpu::Limits::downlevel_webgl2_defaults().using_resolution(adapter.limits())
                },
                ..Default::default()
            })
            .await
            .map_err(|e| err("device", e))?;
        let mut config = surface
            .get_default_config(&adapter, w, h)
            .ok_or_else(|| JsValue::from_str("surface not supported"))?;
        // PLY colours are sRGB bytes: a non-sRGB format passes them through, like native and the
        // capture target (decision 0024). The browser's preferred format is bgra8unorm.
        let caps = surface.get_capabilities(&adapter);
        if let Some(f) = caps.formats.iter().find(|f| !f.is_srgb()) {
            config.format = *f;
        }
        config.alpha_mode = wgpu::CompositeAlphaMode::Opaque;
        surface.configure(&device, &config);
        let depth = depth_view(&device, w, h);
        let renderer = Renderer::new(&device, config.format);
        let adapter = format!(
            "{{\"backend\":\"{:?}\",\"format\":\"{:?}\",\"width\":{w},\"height\":{h},\"name\":{}}}",
            info.backend,
            config.format,
            json_str(&info.name)
        );
        Ok(Viewer {
            surface,
            device,
            queue,
            config,
            depth,
            renderer,
            scene: Scene::new(),
            camera: Camera::new([0.0, -10.0, 10.0], [0.0; 3], [0.0, 0.0, 1.0], 50.0),
            adapter,
            offscreen: None,
            readback: None,
            stages: [0.0; 4],
            readback_copy: true,
            timer: Rc::new(RefCell::new(None)),
            timing: false,
        })
    }

    /// Backend, surface format and size as JSON.
    pub fn info(&self) -> String {
        self.adapter.clone()
    }

    /// Adds one chunk (decision 0022). Returns what it did: `appended`, `pending`, `swapped`, `stale`.
    pub fn insert(&mut self, chunk: &[u8]) -> Result<String, JsValue> {
        let r = self
            .scene
            .insert(&self.device, chunk)
            .map_err(|e| err("chunk", e))?;
        Ok(match r {
            Inserted::Appended => "appended",
            Inserted::Pending => "pending",
            Inserted::Swapped { .. } => "swapped",
            Inserted::Stale => "stale",
        }
        .into())
    }

    pub fn set_camera(&mut self, eye: &[f64], target: &[f64], up: &[f64], fov_y_deg: f64) {
        let v = |a: &[f64]| [a[0], a[1], a[2]];
        self.camera = Camera::new(v(eye), v(target), v(up), fov_y_deg);
    }

    /// Draws one frame into an offscreen texture of the canvas size and format, copies its first
    /// pixel to a small readback buffer, and submits (synchronised frames, decision 0033). Nothing
    /// is presented, so the canvas is not touched — drawing many frames to the canvas in one
    /// animation frame made Chrome allocate a new canvas texture each time (1.8–3.1 GB in the first
    /// P2.5 run). Wait for the GPU with [`Viewer::readback_done`].
    pub fn render_offscreen(&mut self) {
        let (w, h) = (self.config.width, self.config.height);
        let format = self.config.format;
        let device = &self.device;
        let (texture, view) = self.offscreen.get_or_insert_with(|| {
            let texture = device.create_texture(&wgpu::TextureDescriptor {
                label: Some("offscreen"),
                size: wgpu::Extent3d {
                    width: w,
                    height: h,
                    depth_or_array_layers: 1,
                },
                mip_level_count: 1,
                sample_count: 1,
                dimension: wgpu::TextureDimension::D2,
                format,
                usage: wgpu::TextureUsages::RENDER_ATTACHMENT | wgpu::TextureUsages::COPY_SRC,
                view_formats: &[],
            });
            let view = texture.create_view(&wgpu::TextureViewDescriptor::default());
            (texture, view)
        });
        let readback = self.readback.get_or_insert_with(|| {
            device.create_buffer(&wgpu::BufferDescriptor {
                label: Some("sync pixel"),
                size: 256,
                usage: wgpu::BufferUsages::COPY_DST | wgpu::BufferUsages::MAP_READ,
                mapped_at_creation: false,
            })
        });
        let now = || {
            web_sys::window()
                .and_then(|w| w.performance())
                .map_or(0.0, |p| p.now())
        };
        let t0 = now();
        let mut enc = self
            .device
            .create_command_encoder(&wgpu::CommandEncoderDescriptor::default());
        if self.timing
            && let Some(t) = self.timer.borrow_mut().as_mut()
        {
            t.next(&mut self.renderer);
        }
        self.renderer.render(
            &self.device,
            &self.queue,
            &mut enc,
            view,
            &self.depth,
            [w, h],
            &self.camera,
            &self.scene,
        );
        let t1 = now();
        if self.readback_copy {
            enc.copy_texture_to_buffer(
                texture.as_image_copy(),
                wgpu::TexelCopyBufferInfo {
                    buffer: readback,
                    layout: wgpu::TexelCopyBufferLayout {
                        offset: 0,
                        bytes_per_row: Some(256),
                        rows_per_image: Some(1),
                    },
                },
                wgpu::Extent3d {
                    width: 1,
                    height: 1,
                    depth_or_array_layers: 1,
                },
            );
        }
        let t2 = now();
        let commands = enc.finish();
        let t3 = now();
        self.queue.submit([commands]);
        let t4 = now();
        self.stages = [t1 - t0, t2 - t1, t3 - t2, t4 - t3];
    }

    /// Times the next `frames` offscreen frames with GPU timestamps (decision 0049). False when the
    /// device has no timestamp queries (WebGL2, or an adapter without them).
    pub fn gpu_timer_start(&mut self, frames: u32) -> bool {
        let mut timer = self.timer.borrow_mut();
        if timer.is_none() {
            *timer = GpuTimer::new(&self.device, &self.queue, frames);
        }
        self.timing = timer.is_some();
        self.timing
    }

    /// Resolves to the GPU time per timed frame, ms (sum of the pass times ÷ frames), and stops
    /// timing. Call after the frames were submitted (for example after `readback_done`).
    pub fn gpu_timer_read(&mut self) -> js_sys::Promise {
        self.timing = false;
        let timer = Rc::clone(&self.timer);
        let readback = {
            let mut t = timer.borrow_mut();
            let Some(t) = t.as_mut() else {
                return js_sys::Promise::reject(&JsValue::from_str("no GPU timer"));
            };
            let mut enc = self
                .device
                .create_command_encoder(&wgpu::CommandEncoderDescriptor::default());
            t.resolve(&mut self.renderer, &mut enc);
            self.queue.submit([enc.finish()]);
            t.readback().clone()
        };
        let signal = Signal::default();
        let fire = signal.clone();
        readback.map_async(wgpu::MapMode::Read, .., move |_| fire.fire());
        wasm_bindgen_futures::future_to_promise(async move {
            signal.await;
            let (total, n) = timer
                .borrow_mut()
                .as_mut()
                .map_or((0.0, 0), GpuTimer::take_ms);
            Ok(JsValue::from_f64(total / f64::from(n.max(1))))
        })
    }

    /// A/B switch for the readback copy (P4.2).
    pub fn set_readback_copy(&mut self, on: bool) {
        self.readback_copy = on;
    }

    /// Stage times of the last `render_offscreen`, ms: record (pass + buffer writes), copy, finish,
    /// submit (P4.2 diagnosis). On WebGL2 the GL calls happen at submit.
    pub fn last_stages(&self) -> Vec<f64> {
        self.stages.to_vec()
    }

    /// Resolves when the last offscreen frame is finished: maps the one-pixel readback, which the
    /// GPU can only hand over after the frame — the WebGPU counterpart of the baseline's 1-pixel
    /// readPixels (decision 0033). Used instead of `gpu_done` for many frames in a row: Chrome kept
    /// about 1.9 MB per `onSubmittedWorkDone` after a frame (2 GB over 960 frames).
    pub fn readback_done(&self) -> js_sys::Promise {
        let Some(buffer) = self.readback.clone() else {
            return js_sys::Promise::reject(&JsValue::from_str("no offscreen frame yet"));
        };
        let signal = Signal::default();
        let fire = signal.clone();
        buffer.map_async(wgpu::MapMode::Read, .., move |_| fire.fire());
        wasm_bindgen_futures::future_to_promise(async move {
            signal.await;
            buffer.unmap();
            Ok(JsValue::UNDEFINED)
        })
    }

    /// Draws one frame to the canvas.
    pub fn render(&mut self) -> Result<(), JsValue> {
        let frame = match self.surface.get_current_texture() {
            wgpu::CurrentSurfaceTexture::Success(t)
            | wgpu::CurrentSurfaceTexture::Suboptimal(t) => t,
            wgpu::CurrentSurfaceTexture::Outdated | wgpu::CurrentSurfaceTexture::Lost => {
                self.surface.configure(&self.device, &self.config);
                return Ok(());
            }
            other => return Err(JsValue::from_str(&format!("surface texture: {other:?}"))),
        };
        let view = frame
            .texture
            .create_view(&wgpu::TextureViewDescriptor::default());
        let mut enc = self
            .device
            .create_command_encoder(&wgpu::CommandEncoderDescriptor::default());
        self.renderer.render(
            &self.device,
            &self.queue,
            &mut enc,
            &view,
            &self.depth,
            [self.config.width, self.config.height],
            &self.camera,
            &self.scene,
        );
        self.queue.submit([enc.finish()]);
        self.queue.present(frame);
        Ok(())
    }

    /// Resolves when the GPU has finished everything submitted so far.
    pub fn gpu_done(&self) -> js_sys::Promise {
        let signal = Signal::default();
        let fire = signal.clone();
        self.queue.on_submitted_work_done(move || fire.fire());
        wasm_bindgen_futures::future_to_promise(async move {
            signal.await;
            Ok(JsValue::UNDEFINED)
        })
    }

    /// Lets wgpu run completion callbacks without blocking. WebGPU calls them by itself; on WebGL2
    /// they only run when the device is polled, so `gpu_done` would never resolve (P2.4). Call it
    /// once per animation frame.
    pub fn poll(&self) {
        let _ = self.device.poll(wgpu::PollType::Poll);
    }

    /// Points on screen.
    pub fn points(&self) -> f64 {
        self.scene.points() as f64
    }

    /// Vertex buffer bytes on the GPU (shown + pending generations).
    pub fn gpu_bytes(&self) -> f64 {
        self.scene.gpu_bytes() as f64
    }
}