Skip to main content

webizen_runtime/
wgpu_backend.rs

1use crate::diffusion::DiffusionConfig;
2use crate::error::RuntimeError;
3use crate::kernel::ComputeBackend;
4use crate::snapshot::{
5    compute_state_hash, FrameHandle, SharedFrameBuffer, SimulationSnapshot, StateHash,
6};
7use bytemuck::{Pod, Zeroable};
8use std::sync::{mpsc, Arc};
9use etalon::util::DeviceExt;
10
11const WORKGROUP_SIZE: u32 = 8;
12
13// Render pipeline shader (basic vertex + fragment)
14const RENDER_SHADER: &str = r#"
15struct VertexInput {
16    @location(0) position: vec3<f32>,
17    @location(1) color: vec4<f32>,
18}
19
20struct VertexOutput {
21    @builtin(position) clip_position: vec4<f32>,
22    @location(0) color: vec4<f32>,
23}
24
25@vertex
26fn vertex_main(input: VertexInput) -> VertexOutput {
27    var output: VertexOutput;
28    output.clip_position = vec4<f32>(input.position, 1.0);
29    output.color = input.color;
30    return output;
31}
32
33@fragment
34fn fragment_main(input: VertexOutput) -> @location(0) vec4<f32> {
35    return input.color;
36}
37"#;
38
39const DIFFUSION_SHADER: &str = r#"
40struct DiffusionUniforms {
41    width: u32,
42    height: u32,
43    diffusion_rate: f32,
44    _pad: f32,
45};
46
47@group(0) @binding(0)
48var<storage, read> src: array<f32>;
49
50@group(0) @binding(1)
51var<storage, read_write> dst: array<f32>;
52
53@group(0) @binding(2)
54var<uniform> uniforms: DiffusionUniforms;
55
56fn idx(x: u32, y: u32) -> u32 {
57    return y * uniforms.width + x;
58}
59
60fn left_of(x: u32) -> u32 {
61    return select(x - 1u, uniforms.width - 1u, x == 0u);
62}
63
64fn right_of(x: u32) -> u32 {
65    return select(x + 1u, 0u, x + 1u >= uniforms.width);
66}
67
68fn up_of(y: u32) -> u32 {
69    return select(y - 1u, uniforms.height - 1u, y == 0u);
70}
71
72fn down_of(y: u32) -> u32 {
73    return select(y + 1u, 0u, y + 1u >= uniforms.height);
74}
75
76@compute @workgroup_size(8, 8, 1)
77fn main(@builtin(global_invocation_id) gid: vec3<u32>) {
78    if (gid.x >= uniforms.width || gid.y >= uniforms.height) {
79        return;
80    }
81
82    let x = gid.x;
83    let y = gid.y;
84    let center = src[idx(x, y)];
85    let left = src[idx(left_of(x), y)];
86    let right = src[idx(right_of(x), y)];
87    let up = src[idx(x, up_of(y))];
88    let down = src[idx(x, down_of(y))];
89    let average = (left + right + up + down) * 0.25;
90
91    dst[idx(x, y)] = center + (average - center) * uniforms.diffusion_rate;
92}
93"#;
94
95#[repr(C)]
96#[derive(Clone, Copy, Pod, Zeroable)]
97struct DiffusionUniforms {
98    width: u32,
99    height: u32,
100    diffusion_rate: f32,
101    pad: f32,
102}
103
104#[repr(C)]
105#[derive(Clone, Copy, Pod, Zeroable)]
106struct Vertex {
107    position: [f32; 3],
108    color: [f32; 4],
109}
110
111pub struct WgpuDiffusionBackend<'a> {
112    config: DiffusionConfig,
113    device: Arc<etalon::Device>,
114    queue: Arc<etalon::Queue>,
115    compute_pipeline: etalon::ComputePipeline,
116    bind_group_layout: etalon::BindGroupLayout,
117    uniform_buffer: etalon::Buffer,
118    state_buffers: [etalon::Buffer; 2],
119    bind_groups: [etalon::BindGroup; 2],
120    staging_buffer: etalon::Buffer,
121    frames: SharedFrameBuffer,
122    read_index: usize,
123    // Render pipeline fields (Phase 1.1) - planned for future use
124    #[allow(dead_code)]
125    surface: Option<etalon::Surface<'a>>,
126    #[allow(dead_code)]
127    render_pipeline: Option<etalon::RenderPipeline>,
128    #[allow(dead_code)]
129    vertex_buffer: Option<etalon::Buffer>,
130    #[allow(dead_code)]
131    index_buffer: Option<etalon::Buffer>,
132    #[allow(dead_code)]
133    depth_texture: Option<etalon::Texture>,
134    #[allow(dead_code)]
135    depth_texture_view: Option<etalon::TextureView>,
136}
137
138/// Build a wgpu instance with the same Windows-safe backend policy as
139/// `qualia_core_db::gpu_context`: **DX12 by default on Windows**.
140///
141/// `Instance::default()` enables Vulkan + DX12. On many Intel UHD systems the
142/// Vulkan ICD (`igvk64.dll`) access-violates during `request_device`, which
143/// kills the whole desktop process mid first-run setup. Prefer DX12 unless the
144/// operator pins `QUALIA_WGPU_BACKEND` / `WGPU_BACKEND`.
145fn create_instance() -> etalon::Instance {
146    let mut desc = etalon::InstanceDescriptor::new_without_display_handle();
147
148    if let Some(backends) = backend_override_from_env() {
149        log::info!("webizen-runtime|backend_override|{backends:?}");
150        desc.backends = backends;
151    } else if cfg!(target_os = "windows") {
152        desc.backends = etalon::Backends::DX12;
153        log::info!(
154            "webizen-runtime|backend_default|windows->dx12 (override with QUALIA_WGPU_BACKEND=vulkan)"
155        );
156    }
157
158    etalon::Instance::new(desc)
159}
160
161fn backend_override_from_env() -> Option<etalon::Backends> {
162    for key in ["QUALIA_WGPU_BACKEND", "WGPU_BACKEND"] {
163        if let Ok(raw) = std::env::var(key) {
164            let v = raw.trim().to_ascii_lowercase();
165            if v.is_empty() {
166                continue;
167            }
168            return Some(match v.as_str() {
169                "vulkan" | "vk" => etalon::Backends::VULKAN,
170                "dx12" | "d3d12" | "directx12" | "dx" => etalon::Backends::DX12,
171                "metal" | "mtl" => etalon::Backends::METAL,
172                "gl" | "opengl" | "gles" => etalon::Backends::GL,
173                "primary" => etalon::Backends::PRIMARY,
174                "all" => etalon::Backends::all(),
175                other => {
176                    log::warn!("{key}='{other}' unrecognized — using platform default");
177                    return None;
178                }
179            });
180        }
181    }
182    None
183}
184
185impl<'a> WgpuDiffusionBackend<'a> {
186    /// Creates a new instance.
187    pub async fn new(config: DiffusionConfig) -> Result<Self, RuntimeError> {
188        let instance = create_instance();
189
190        // CRITICAL FIX: Use HighPerformance on native desktop to capture NVIDIA GPU
191        // LowPower bypasses discrete NVIDIA GPU on Windows
192        #[cfg(not(target_arch = "wasm32"))]
193        let power_preference = etalon::PowerPreference::HighPerformance;
194        #[cfg(target_arch = "wasm32")]
195        let power_preference = etalon::PowerPreference::LowPower;
196
197        let adapter = instance
198            .request_adapter(&etalon::RequestAdapterOptions {
199                power_preference,
200                compatible_surface: None,
201                force_fallback_adapter: false,
202                // wgpu 30 added `apply_limit_buckets`; take the crate default.
203                ..Default::default()
204            })
205            .await
206            .map_err(|_| RuntimeError::AdapterUnavailable)?;
207
208        let adapter_info = adapter.get_info();
209        log::info!(
210            "wGPU adapter selected: {} (Backend: {:?})",
211            adapter_info.name,
212            adapter_info.backend
213        );
214
215        log::info!(
216            "webizen-runtime|request_device|adapter={} backend={:?}",
217            adapter_info.name,
218            adapter_info.backend
219        );
220        let (device, queue) = adapter
221            .request_device(&etalon::DeviceDescriptor {
222                label: Some("webizen-runtime-device"),
223                required_features: etalon::Features::empty(),
224                required_limits: etalon::Limits::downlevel_defaults(),
225                ..Default::default()
226            })
227            .await
228            .map_err(|err| RuntimeError::DeviceRequestFailed(err.to_string()))?;
229        log::info!("webizen-runtime|request_device|ok");
230
231        let device = Arc::new(device);
232        let queue = Arc::new(queue);
233        let shader = device.create_shader_module(etalon::ShaderModuleDescriptor {
234            label: Some("webizen-diffusion-shader"),
235            source: etalon::ShaderSource::Wgsl(DIFFUSION_SHADER.into()),
236        });
237
238        let bind_group_layout = device.create_bind_group_layout(&etalon::BindGroupLayoutDescriptor {
239            label: Some("webizen-diffusion-bind-group-layout"),
240            entries: &[
241                etalon::BindGroupLayoutEntry {
242                    binding: 0,
243                    visibility: etalon::ShaderStages::COMPUTE,
244                    ty: etalon::BindingType::Buffer {
245                        ty: etalon::BufferBindingType::Storage { read_only: true },
246                        has_dynamic_offset: false,
247                        min_binding_size: None,
248                    },
249                    count: None,
250                },
251                etalon::BindGroupLayoutEntry {
252                    binding: 1,
253                    visibility: etalon::ShaderStages::COMPUTE,
254                    ty: etalon::BindingType::Buffer {
255                        ty: etalon::BufferBindingType::Storage { read_only: false },
256                        has_dynamic_offset: false,
257                        min_binding_size: None,
258                    },
259                    count: None,
260                },
261                etalon::BindGroupLayoutEntry {
262                    binding: 2,
263                    visibility: etalon::ShaderStages::COMPUTE,
264                    ty: etalon::BindingType::Buffer {
265                        ty: etalon::BufferBindingType::Uniform,
266                        has_dynamic_offset: false,
267                        min_binding_size: None,
268                    },
269                    count: None,
270                },
271            ],
272        });
273
274        let pipeline_layout = device.create_pipeline_layout(&etalon::PipelineLayoutDescriptor {
275            label: Some("webizen-diffusion-pipeline-layout"),
276            bind_group_layouts: &[Some(&bind_group_layout)],
277            immediate_size: 0,
278        });
279
280        let compute_pipeline = device.create_compute_pipeline(&etalon::ComputePipelineDescriptor {
281            label: Some("webizen-diffusion-pipeline"),
282            layout: Some(&pipeline_layout),
283            module: &shader,
284            entry_point: Some("main"),
285            compilation_options: Default::default(),
286            cache: None,
287        });
288
289        let (uniform_buffer, state_buffers, bind_groups, staging_buffer, frames) =
290            Self::allocate_io_resources(&device, &bind_group_layout, config);
291
292        // Phase 1.1: Initialize render pipeline (without surface for now)
293        let render_pipeline = Self::create_render_pipeline(&device);
294        let vertex_buffer = None;
295        let index_buffer = None;
296        let depth_texture = None;
297        let depth_texture_view = None;
298        let surface = None;
299
300        Ok(Self {
301            config,
302            device,
303            queue,
304            compute_pipeline,
305            bind_group_layout,
306            uniform_buffer,
307            state_buffers,
308            bind_groups,
309            staging_buffer,
310            frames,
311            read_index: 0,
312            surface,
313            render_pipeline,
314            vertex_buffer,
315            index_buffer,
316            depth_texture,
317            depth_texture_view,
318        })
319    }
320
321    fn create_render_pipeline(device: &etalon::Device) -> Option<etalon::RenderPipeline> {
322        let shader = device.create_shader_module(etalon::ShaderModuleDescriptor {
323            label: Some("webizen-render-shader"),
324            source: etalon::ShaderSource::Wgsl(RENDER_SHADER.into()),
325        });
326
327        let pipeline_layout = device.create_pipeline_layout(&etalon::PipelineLayoutDescriptor {
328            label: Some("webizen-render-pipeline-layout"),
329            bind_group_layouts: &[],
330            immediate_size: 0,
331        });
332
333        Some(
334            device.create_render_pipeline(&etalon::RenderPipelineDescriptor {
335                label: Some("webizen-render-pipeline"),
336                layout: Some(&pipeline_layout),
337                vertex: etalon::VertexState {
338                    module: &shader,
339                    entry_point: Some("vertex_main"),
340                    compilation_options: Default::default(),
341                    // wgpu 30: VertexState::buffers is &[Option<VertexBufferLayout>].
342                    buffers: &[Some(etalon::VertexBufferLayout {
343                        array_stride: std::mem::size_of::<Vertex>() as etalon::BufferAddress,
344                        step_mode: etalon::VertexStepMode::Vertex,
345                        attributes: &[
346                            etalon::VertexAttribute {
347                                offset: 0,
348                                shader_location: 0,
349                                format: etalon::VertexFormat::Float32x3,
350                            },
351                            etalon::VertexAttribute {
352                                offset: std::mem::size_of::<[f32; 3]>() as etalon::BufferAddress,
353                                shader_location: 1,
354                                format: etalon::VertexFormat::Float32x4,
355                            },
356                        ],
357                    })],
358                },
359                fragment: Some(etalon::FragmentState {
360                    module: &shader,
361                    entry_point: Some("fragment_main"),
362                    compilation_options: Default::default(),
363                    targets: &[Some(etalon::ColorTargetState {
364                        format: etalon::TextureFormat::Bgra8UnormSrgb,
365                        blend: Some(etalon::BlendState::REPLACE),
366                        write_mask: etalon::ColorWrites::ALL,
367                    })],
368                }),
369                primitive: etalon::PrimitiveState {
370                    topology: etalon::PrimitiveTopology::TriangleList,
371                    strip_index_format: None,
372                    front_face: etalon::FrontFace::Ccw,
373                    cull_mode: Some(etalon::Face::Back),
374                    polygon_mode: etalon::PolygonMode::Fill,
375                    unclipped_depth: false,
376                    conservative: false,
377                },
378                depth_stencil: None,
379                multisample: etalon::MultisampleState {
380                    count: 1,
381                    mask: !0,
382                    alpha_to_coverage_enabled: false,
383                },
384                multiview_mask: None,
385                cache: None,
386            }),
387        )
388    }
389
390    fn allocate_io_resources(
391        device: &etalon::Device,
392        bind_group_layout: &etalon::BindGroupLayout,
393        config: DiffusionConfig,
394    ) -> (
395        etalon::Buffer,
396        [etalon::Buffer; 2],
397        [etalon::BindGroup; 2],
398        etalon::Buffer,
399        SharedFrameBuffer,
400    ) {
401        let uniforms = DiffusionUniforms {
402            width: config.width,
403            height: config.height,
404            diffusion_rate: config.diffusion_rate,
405            pad: 0.0,
406        };
407
408        let uniform_buffer = device.create_buffer_init(&etalon::util::BufferInitDescriptor {
409            label: Some("webizen-diffusion-uniform-buffer"),
410            contents: bytemuck::bytes_of(&uniforms),
411            usage: etalon::BufferUsages::UNIFORM | etalon::BufferUsages::COPY_DST,
412        });
413
414        let initial_state = seeded_field(&config);
415        let raw_bytes = bytemuck::cast_slice(&initial_state);
416
417        let state_buffer_a = device.create_buffer_init(&etalon::util::BufferInitDescriptor {
418            label: Some("webizen-diffusion-state-a"),
419            contents: raw_bytes,
420            usage: etalon::BufferUsages::STORAGE
421                | etalon::BufferUsages::COPY_SRC
422                | etalon::BufferUsages::COPY_DST,
423        });
424
425        let state_buffer_b = device.create_buffer_init(&etalon::util::BufferInitDescriptor {
426            label: Some("webizen-diffusion-state-b"),
427            contents: raw_bytes,
428            usage: etalon::BufferUsages::STORAGE
429                | etalon::BufferUsages::COPY_SRC
430                | etalon::BufferUsages::COPY_DST,
431        });
432
433        let staging_buffer = device.create_buffer(&etalon::BufferDescriptor {
434            label: Some("webizen-diffusion-staging"),
435            size: config.raw_byte_len(),
436            usage: etalon::BufferUsages::COPY_DST | etalon::BufferUsages::MAP_READ,
437            mapped_at_creation: false,
438        });
439
440        let bind_group_forward = device.create_bind_group(&etalon::BindGroupDescriptor {
441            label: Some("webizen-diffusion-bind-group-a-to-b"),
442            layout: bind_group_layout,
443            entries: &[
444                etalon::BindGroupEntry {
445                    binding: 0,
446                    resource: state_buffer_a.as_entire_binding(),
447                },
448                etalon::BindGroupEntry {
449                    binding: 1,
450                    resource: state_buffer_b.as_entire_binding(),
451                },
452                etalon::BindGroupEntry {
453                    binding: 2,
454                    resource: uniform_buffer.as_entire_binding(),
455                },
456            ],
457        });
458
459        let bind_group_reverse = device.create_bind_group(&etalon::BindGroupDescriptor {
460            label: Some("webizen-diffusion-bind-group-b-to-a"),
461            layout: bind_group_layout,
462            entries: &[
463                etalon::BindGroupEntry {
464                    binding: 0,
465                    resource: state_buffer_b.as_entire_binding(),
466                },
467                etalon::BindGroupEntry {
468                    binding: 1,
469                    resource: state_buffer_a.as_entire_binding(),
470                },
471                etalon::BindGroupEntry {
472                    binding: 2,
473                    resource: uniform_buffer.as_entire_binding(),
474                },
475            ],
476        });
477
478        let frames = SharedFrameBuffer::new(config.cell_count() * 4);
479
480        (
481            uniform_buffer,
482            [state_buffer_a, state_buffer_b],
483            [bind_group_forward, bind_group_reverse],
484            staging_buffer,
485            frames,
486        )
487    }
488
489    fn readback_snapshot_data(&self, slot: usize) -> Result<StateHash, RuntimeError> {
490        let slice = self.staging_buffer.slice(..);
491        let (tx, rx) = mpsc::channel();
492        slice.map_async(etalon::MapMode::Read, move |result| {
493            let _ = tx.send(result);
494        });
495
496        let _ = self.device.poll(etalon::PollType::wait_indefinitely());
497        let map_result = rx.recv().map_err(|_| RuntimeError::ChannelClosed)?;
498        map_result.map_err(|err| RuntimeError::BufferMapFailed(err.to_string()))?;
499
500        let mapped = slice
501            .get_mapped_range()
502            .expect("wgpu buffer map_range failed");
503        let hash = compute_state_hash(&mapped);
504        let field = bytemuck::cast_slice::<u8, f32>(&mapped);
505        let _ = self.frames.overwrite_slot(slot, |rgba| {
506            for (index, value) in field.iter().enumerate() {
507                let base = index * 4;
508                let channel = (value.clamp(0.0, 1.0) * 255.0) as u8;
509                rgba[base] = channel;
510                rgba[base + 1] = channel;
511                rgba[base + 2] = channel;
512                rgba[base + 3] = 255;
513            }
514        });
515        drop(mapped);
516        self.staging_buffer.unmap();
517
518        Ok(hash)
519    }
520}
521
522impl<'a> ComputeBackend for WgpuDiffusionBackend<'a> {
523    fn step(&mut self, epoch: u64) -> Result<SimulationSnapshot, RuntimeError> {
524        let write_index = (self.read_index + 1) % 2;
525        let mut encoder = self
526            .device
527            .create_command_encoder(&etalon::CommandEncoderDescriptor {
528                label: Some("webizen-diffusion-encoder"),
529            });
530
531        {
532            let mut compute = encoder.begin_compute_pass(&etalon::ComputePassDescriptor {
533                label: Some("webizen-diffusion-pass"),
534                timestamp_writes: None,
535            });
536            compute.set_pipeline(&self.compute_pipeline);
537            compute.set_bind_group(0, &self.bind_groups[self.read_index], &[]);
538            compute.dispatch_workgroups(
539                self.config.width.div_ceil(WORKGROUP_SIZE),
540                self.config.height.div_ceil(WORKGROUP_SIZE),
541                1,
542            );
543        }
544
545        encoder.copy_buffer_to_buffer(
546            &self.state_buffers[write_index],
547            0,
548            &self.staging_buffer,
549            0,
550            self.config.raw_byte_len(),
551        );
552        self.queue.submit(Some(encoder.finish()));
553        let _ = self.device.poll(etalon::PollType::wait_indefinitely());
554
555        let state_hash = self.readback_snapshot_data(write_index)?;
556        self.read_index = write_index;
557
558        Ok(SimulationSnapshot {
559            epoch,
560            dimensions: (self.config.width, self.config.height),
561            state_hash,
562            frame: FrameHandle::CpuRgbaSlot(write_index as u8),
563        })
564    }
565
566    fn reconfigure(&mut self, config: DiffusionConfig) -> Result<(), RuntimeError> {
567        let (uniform_buffer, state_buffers, bind_groups, staging_buffer, frames) =
568            Self::allocate_io_resources(&self.device, &self.bind_group_layout, config);
569
570        self.config = config;
571        self.uniform_buffer = uniform_buffer;
572        self.state_buffers = state_buffers;
573        self.bind_groups = bind_groups;
574        self.staging_buffer = staging_buffer;
575        self.frames = frames;
576        self.read_index = 0;
577        Ok(())
578    }
579
580    fn shared_frames(&self) -> Option<SharedFrameBuffer> {
581        Some(self.frames.clone())
582    }
583}
584
585fn seeded_field(config: &DiffusionConfig) -> Vec<f32> {
586    let mut state = vec![0.0; config.cell_count()];
587    let center_x = config.width / 2;
588    let center_y = config.height / 2;
589    let center = (center_y * config.width + center_x) as usize;
590    if let Some(cell) = state.get_mut(center) {
591        *cell = 1.0;
592    }
593    state
594}