Skip to main content

kova_native_render/
renderer.rs

1//! wgpu device management and scene rendering.
2
3use crate::atlas::{Atlas, AtlasTextures};
4use crate::scene::{Effect, Instance, Op, Scene};
5use crate::shaders::ShaderId;
6use kova_native_core::{Color, KovaError, KovaResult};
7use rustc_hash::FxHashMap;
8use std::borrow::Cow;
9
10pub(crate) const SHADER: &str = include_str!("shader.wgsl");
11const POST_SHADER: &str = include_str!("post.wgsl");
12/// Format of offscreen targets (intermediate scene texture, blur buffers).
13const OFFSCREEN_FORMAT: wgpu::TextureFormat = wgpu::TextureFormat::Rgba8Unorm;
14
15/// The GPU instance, adapter, device and queue shared by all windows.
16pub struct GpuContext {
17    pub instance: wgpu::Instance,
18    pub adapter: wgpu::Adapter,
19    pub device: wgpu::Device,
20    pub queue: wgpu::Queue,
21}
22
23impl GpuContext {
24    /// Creates a wgpu instance with Kova Native's native backends (DX12/Vulkan on
25    /// Windows, Metal on macOS, Vulkan elsewhere). `WGPU_BACKEND` overrides.
26    pub fn create_instance() -> wgpu::Instance {
27        let mut desc = wgpu::InstanceDescriptor::new_without_display_handle();
28        desc.backends = wgpu::Backends::from_env().unwrap_or(if cfg!(target_os = "windows") {
29            wgpu::Backends::DX12 | wgpu::Backends::VULKAN
30        } else {
31            wgpu::Backends::PRIMARY
32        });
33        wgpu::Instance::new(desc)
34    }
35
36    /// Picks an adapter (compatible with `surface` if given) and opens a device.
37    pub fn new(
38        instance: wgpu::Instance,
39        surface: Option<&wgpu::Surface<'_>>,
40    ) -> KovaResult<GpuContext> {
41        let adapter =
42            pollster::block_on(
43                instance.request_adapter(&wgpu::RequestAdapterOptions {
44                    power_preference: wgpu::PowerPreference::from_env()
45                        .unwrap_or(wgpu::PowerPreference::HighPerformance),
46                    force_fallback_adapter: false,
47                    compatible_surface: surface,
48                    ..Default::default()
49                }),
50            )
51            .map_err(|e| KovaError::Gpu(format!("no suitable GPU adapter: {e}")))?;
52        let info = adapter.get_info();
53        log::info!(
54            "kova-native: using {} ({:?}, {:?})",
55            info.name,
56            info.backend,
57            info.device_type
58        );
59        let (device, queue) = pollster::block_on(adapter.request_device(&wgpu::DeviceDescriptor {
60            label: Some("kova-native device"),
61            required_limits: wgpu::Limits::default().using_resolution(adapter.limits()),
62            ..Default::default()
63        }))
64        .map_err(|e| KovaError::Gpu(format!("failed to open GPU device: {e}")))?;
65        device.on_uncaptured_error(std::sync::Arc::new(|e| {
66            log::error!("kova-native gpu error: {e}")
67        }));
68        Ok(GpuContext {
69            instance,
70            adapter,
71            device,
72            queue,
73        })
74    }
75
76    /// Opens a device without any surface (headless rendering, tests).
77    pub fn new_headless() -> KovaResult<GpuContext> {
78        Self::new(Self::create_instance(), None)
79    }
80}
81
82/// Presentation configuration of a window surface.
83#[derive(Clone, Copy, Debug, PartialEq, Eq)]
84pub struct SurfaceOptions {
85    /// Synchronize with the display refresh (60/120/144 Hz...).
86    pub vsync: bool,
87    /// Frames the CPU may queue ahead of the GPU. 1 = lowest input latency.
88    pub max_frame_latency: u32,
89}
90
91impl Default for SurfaceOptions {
92    fn default() -> Self {
93        SurfaceOptions {
94            vsync: true,
95            max_frame_latency: 1,
96        }
97    }
98}
99
100/// A window's swapchain.
101pub struct WindowSurface {
102    surface: wgpu::Surface<'static>,
103    config: wgpu::SurfaceConfiguration,
104}
105
106impl WindowSurface {
107    /// Creates a raw surface for a window handle.
108    pub fn create_surface(
109        instance: &wgpu::Instance,
110        window: impl wgpu::DisplayAndWindowHandle + 'static,
111    ) -> KovaResult<wgpu::Surface<'static>> {
112        instance
113            .create_surface(window)
114            .map_err(|e| KovaError::Gpu(format!("failed to create surface: {e}")))
115    }
116
117    pub fn new(
118        gpu: &GpuContext,
119        surface: wgpu::Surface<'static>,
120        width: u32,
121        height: u32,
122        options: SurfaceOptions,
123    ) -> KovaResult<WindowSurface> {
124        let caps = surface.get_capabilities(&gpu.adapter);
125        if caps.formats.is_empty() {
126            return Err(KovaError::Gpu(
127                "surface is not supported by the adapter".into(),
128            ));
129        }
130        // Prefer a non-sRGB format: Kova Native blends in sRGB space like browsers.
131        let format = caps
132            .formats
133            .iter()
134            .copied()
135            .find(|f| {
136                matches!(
137                    f,
138                    wgpu::TextureFormat::Bgra8Unorm | wgpu::TextureFormat::Rgba8Unorm
139                )
140            })
141            .unwrap_or(caps.formats[0]);
142        let present_mode = if options.vsync {
143            wgpu::PresentMode::Fifo
144        } else {
145            [wgpu::PresentMode::Mailbox, wgpu::PresentMode::Immediate]
146                .into_iter()
147                .find(|m| caps.present_modes.contains(m))
148                .unwrap_or(wgpu::PresentMode::Fifo)
149        };
150        let alpha_mode = if caps.alpha_modes.contains(&wgpu::CompositeAlphaMode::Opaque) {
151            wgpu::CompositeAlphaMode::Opaque
152        } else {
153            caps.alpha_modes[0]
154        };
155        let config = wgpu::SurfaceConfiguration {
156            usage: wgpu::TextureUsages::RENDER_ATTACHMENT,
157            format,
158            color_space: wgpu::SurfaceColorSpace::Auto,
159            width: width.max(1),
160            height: height.max(1),
161            desired_maximum_frame_latency: options.max_frame_latency.max(1),
162            present_mode,
163            alpha_mode,
164            view_formats: vec![],
165        };
166        surface.configure(&gpu.device, &config);
167        Ok(WindowSurface { surface, config })
168    }
169
170    pub fn resize(&mut self, gpu: &GpuContext, width: u32, height: u32) {
171        if width == 0 || height == 0 || (width == self.config.width && height == self.config.height)
172        {
173            return;
174        }
175        self.config.width = width;
176        self.config.height = height;
177        self.surface.configure(&gpu.device, &self.config);
178    }
179
180    pub fn size(&self) -> (u32, u32) {
181        (self.config.width, self.config.height)
182    }
183
184    pub fn format(&self) -> wgpu::TextureFormat {
185        self.config.format
186    }
187
188    /// Acquires the next frame, reconfiguring the swapchain if needed.
189    /// Returns `None` when the frame should be skipped (minimized, timeout).
190    pub fn acquire(&mut self, gpu: &GpuContext) -> Option<wgpu::SurfaceTexture> {
191        for _ in 0..2 {
192            match self.surface.get_current_texture() {
193                wgpu::CurrentSurfaceTexture::Success(t)
194                | wgpu::CurrentSurfaceTexture::Suboptimal(t) => return Some(t),
195                wgpu::CurrentSurfaceTexture::Outdated | wgpu::CurrentSurfaceTexture::Lost => {
196                    self.surface.configure(&gpu.device, &self.config);
197                }
198                _ => return None,
199            }
200        }
201        None
202    }
203}
204
205struct Target {
206    texture: wgpu::Texture,
207    view: wgpu::TextureView,
208}
209
210impl Target {
211    fn new(
212        device: &wgpu::Device,
213        width: u32,
214        height: u32,
215        usage: wgpu::TextureUsages,
216        label: &str,
217    ) -> Target {
218        let texture = device.create_texture(&wgpu::TextureDescriptor {
219            label: Some(label),
220            size: wgpu::Extent3d {
221                width: width.max(1),
222                height: height.max(1),
223                depth_or_array_layers: 1,
224            },
225            mip_level_count: 1,
226            sample_count: 1,
227            dimension: wgpu::TextureDimension::D2,
228            format: OFFSCREEN_FORMAT,
229            usage,
230            view_formats: &[],
231        });
232        let view = texture.create_view(&wgpu::TextureViewDescriptor::default());
233        Target { texture, view }
234    }
235}
236
237/// An offscreen layer target with bind groups to draw from it.
238struct LayerTarget {
239    target: Target,
240    /// Scene bind group sampling this layer as `backdrop_texture`.
241    composite_group: wgpu::BindGroup,
242    /// Post bind group sampling this layer (backdrop blur inside layers).
243    post_group: wgpu::BindGroup,
244}
245
246/// Offscreen textures used when a frame contains effects (backdrop blur).
247struct EffectTargets {
248    size: (u32, u32),
249    scene: Target,
250    blur_a: Target,
251    blur_b: Target,
252    /// Post bind groups sampling from `scene`, `blur_a`, `blur_b`.
253    from_scene: wgpu::BindGroup,
254    from_a: wgpu::BindGroup,
255    from_b: wgpu::BindGroup,
256}
257
258#[repr(C)]
259#[derive(Clone, Copy, bytemuck::Pod, bytemuck::Zeroable)]
260struct Globals {
261    viewport: [f32; 2],
262    linear_output: f32,
263    _pad: f32,
264}
265
266#[repr(C)]
267#[derive(Clone, Copy, bytemuck::Pod, bytemuck::Zeroable)]
268struct PostParams {
269    texel: [f32; 2],
270    direction: [f32; 2],
271    sigma: f32,
272    radius: f32,
273    linear_output: f32,
274    _pad: f32,
275}
276
277/// Renders [`Scene`]s. One renderer (and one set of atlases) is shared by
278/// all windows of an application.
279pub struct Renderer {
280    shader: wgpu::ShaderModule,
281    post_shader: wgpu::ShaderModule,
282    bind_group_layout: wgpu::BindGroupLayout,
283    pipeline_layout: wgpu::PipelineLayout,
284    pipelines: FxHashMap<wgpu::TextureFormat, wgpu::RenderPipeline>,
285    post_bind_group_layout: wgpu::BindGroupLayout,
286    post_pipeline_layout: wgpu::PipelineLayout,
287    blit_pipelines: FxHashMap<wgpu::TextureFormat, wgpu::RenderPipeline>,
288    downsample_pipeline: wgpu::RenderPipeline,
289    blur_pipeline: wgpu::RenderPipeline,
290    globals: wgpu::Buffer,
291    post_params: wgpu::Buffer,
292    post_stride: u64,
293    post_capacity: u64,
294    instances: wgpu::Buffer,
295    instance_capacity: u64,
296    sampler: wgpu::Sampler,
297    atlas: Atlas,
298    atlas_textures: AtlasTextures,
299    dummy_backdrop: Target,
300    effects: Option<EffectTargets>,
301    bind_group: Option<wgpu::BindGroup>,
302    /// Layer targets by nesting depth (all viewport sized).
303    layers: Vec<LayerTarget>,
304    custom_modules: FxHashMap<ShaderId, wgpu::ShaderModule>,
305    custom_pipelines: FxHashMap<(ShaderId, wgpu::TextureFormat), wgpu::RenderPipeline>,
306}
307
308fn is_srgb(format: wgpu::TextureFormat) -> bool {
309    format.is_srgb()
310}
311
312impl Renderer {
313    pub fn new(gpu: &GpuContext) -> Renderer {
314        let device = &gpu.device;
315        let shader = device.create_shader_module(wgpu::ShaderModuleDescriptor {
316            label: Some("kova-native shader"),
317            source: wgpu::ShaderSource::Wgsl(Cow::Borrowed(SHADER)),
318        });
319        let post_shader = device.create_shader_module(wgpu::ShaderModuleDescriptor {
320            label: Some("kova-native post shader"),
321            source: wgpu::ShaderSource::Wgsl(Cow::Borrowed(POST_SHADER)),
322        });
323        let texture_entry =
324            |binding: u32, dim: wgpu::TextureViewDimension| wgpu::BindGroupLayoutEntry {
325                binding,
326                visibility: wgpu::ShaderStages::FRAGMENT,
327                ty: wgpu::BindingType::Texture {
328                    sample_type: wgpu::TextureSampleType::Float { filterable: true },
329                    view_dimension: dim,
330                    multisampled: false,
331                },
332                count: None,
333            };
334        let bind_group_layout = device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
335            label: Some("kova-native bind group layout"),
336            entries: &[
337                wgpu::BindGroupLayoutEntry {
338                    binding: 0,
339                    visibility: wgpu::ShaderStages::VERTEX_FRAGMENT,
340                    ty: wgpu::BindingType::Buffer {
341                        ty: wgpu::BufferBindingType::Uniform,
342                        has_dynamic_offset: false,
343                        min_binding_size: None,
344                    },
345                    count: None,
346                },
347                texture_entry(1, wgpu::TextureViewDimension::D2Array),
348                texture_entry(2, wgpu::TextureViewDimension::D2Array),
349                wgpu::BindGroupLayoutEntry {
350                    binding: 3,
351                    visibility: wgpu::ShaderStages::FRAGMENT,
352                    ty: wgpu::BindingType::Sampler(wgpu::SamplerBindingType::Filtering),
353                    count: None,
354                },
355                texture_entry(4, wgpu::TextureViewDimension::D2),
356            ],
357        });
358        let pipeline_layout = device.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
359            label: Some("kova-native pipeline layout"),
360            bind_group_layouts: &[Some(&bind_group_layout)],
361            immediate_size: 0,
362        });
363        let post_bind_group_layout =
364            device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
365                label: Some("kova-native post bind group layout"),
366                entries: &[
367                    wgpu::BindGroupLayoutEntry {
368                        binding: 0,
369                        visibility: wgpu::ShaderStages::FRAGMENT,
370                        ty: wgpu::BindingType::Buffer {
371                            ty: wgpu::BufferBindingType::Uniform,
372                            has_dynamic_offset: true,
373                            min_binding_size: wgpu::BufferSize::new(
374                                std::mem::size_of::<PostParams>() as u64,
375                            ),
376                        },
377                        count: None,
378                    },
379                    texture_entry(1, wgpu::TextureViewDimension::D2),
380                    wgpu::BindGroupLayoutEntry {
381                        binding: 2,
382                        visibility: wgpu::ShaderStages::FRAGMENT,
383                        ty: wgpu::BindingType::Sampler(wgpu::SamplerBindingType::Filtering),
384                        count: None,
385                    },
386                ],
387            });
388        let post_pipeline_layout = device.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
389            label: Some("kova-native post pipeline layout"),
390            bind_group_layouts: &[Some(&post_bind_group_layout)],
391            immediate_size: 0,
392        });
393        let post_stride = (std::mem::size_of::<PostParams>() as u64)
394            .next_multiple_of(device.limits().min_uniform_buffer_offset_alignment as u64);
395        let post_capacity = 16;
396        let post_params = device.create_buffer(&wgpu::BufferDescriptor {
397            label: Some("kova-native post params"),
398            size: post_stride * post_capacity,
399            usage: wgpu::BufferUsages::UNIFORM | wgpu::BufferUsages::COPY_DST,
400            mapped_at_creation: false,
401        });
402        let globals = device.create_buffer(&wgpu::BufferDescriptor {
403            label: Some("kova-native globals"),
404            size: std::mem::size_of::<Globals>() as u64,
405            usage: wgpu::BufferUsages::UNIFORM | wgpu::BufferUsages::COPY_DST,
406            mapped_at_creation: false,
407        });
408        let instance_capacity = 1024;
409        let instances = Self::create_instance_buffer(device, instance_capacity);
410        let sampler = device.create_sampler(&wgpu::SamplerDescriptor {
411            label: Some("kova-native sampler"),
412            address_mode_u: wgpu::AddressMode::ClampToEdge,
413            address_mode_v: wgpu::AddressMode::ClampToEdge,
414            address_mode_w: wgpu::AddressMode::ClampToEdge,
415            mag_filter: wgpu::FilterMode::Linear,
416            min_filter: wgpu::FilterMode::Linear,
417            ..Default::default()
418        });
419        let downsample_pipeline = Self::create_post_pipeline(
420            device,
421            &post_pipeline_layout,
422            &post_shader,
423            "fs_downsample",
424            OFFSCREEN_FORMAT,
425        );
426        let blur_pipeline = Self::create_post_pipeline(
427            device,
428            &post_pipeline_layout,
429            &post_shader,
430            "fs_blur",
431            OFFSCREEN_FORMAT,
432        );
433        let dummy_backdrop = Target::new(
434            device,
435            1,
436            1,
437            wgpu::TextureUsages::TEXTURE_BINDING,
438            "kova-native dummy backdrop",
439        );
440        Renderer {
441            shader,
442            post_shader,
443            bind_group_layout,
444            pipeline_layout,
445            pipelines: FxHashMap::default(),
446            post_bind_group_layout,
447            post_pipeline_layout,
448            blit_pipelines: FxHashMap::default(),
449            downsample_pipeline,
450            blur_pipeline,
451            globals,
452            post_params,
453            post_stride,
454            post_capacity,
455            instances,
456            instance_capacity,
457            sampler,
458            atlas: Atlas::new(),
459            atlas_textures: AtlasTextures::new(device),
460            dummy_backdrop,
461            effects: None,
462            bind_group: None,
463            layers: Vec::new(),
464            custom_modules: FxHashMap::default(),
465            custom_pipelines: FxHashMap::default(),
466        }
467    }
468
469    /// The glyph/image atlas. Painting code inserts tiles here; they are
470    /// uploaded to the GPU on the next [`Renderer::render`].
471    pub fn atlas(&mut self) -> &mut Atlas {
472        &mut self.atlas
473    }
474
475    fn create_instance_buffer(device: &wgpu::Device, capacity: u64) -> wgpu::Buffer {
476        device.create_buffer(&wgpu::BufferDescriptor {
477            label: Some("kova-native instances"),
478            size: capacity * std::mem::size_of::<Instance>() as u64,
479            usage: wgpu::BufferUsages::VERTEX | wgpu::BufferUsages::COPY_DST,
480            mapped_at_creation: false,
481        })
482    }
483
484    fn create_post_pipeline(
485        device: &wgpu::Device,
486        layout: &wgpu::PipelineLayout,
487        module: &wgpu::ShaderModule,
488        entry: &str,
489        format: wgpu::TextureFormat,
490    ) -> wgpu::RenderPipeline {
491        device.create_render_pipeline(&wgpu::RenderPipelineDescriptor {
492            label: Some(entry),
493            layout: Some(layout),
494            vertex: wgpu::VertexState {
495                module,
496                entry_point: Some("vs_fullscreen"),
497                compilation_options: Default::default(),
498                buffers: &[],
499            },
500            primitive: wgpu::PrimitiveState::default(),
501            depth_stencil: None,
502            multisample: wgpu::MultisampleState::default(),
503            fragment: Some(wgpu::FragmentState {
504                module,
505                entry_point: Some(entry),
506                compilation_options: Default::default(),
507                targets: &[Some(wgpu::ColorTargetState {
508                    format,
509                    blend: None,
510                    write_mask: wgpu::ColorWrites::ALL,
511                })],
512            }),
513            multiview_mask: None,
514            cache: None,
515        })
516    }
517
518    /// Creates an instanced quad pipeline (built-in or custom fragment entry).
519    fn create_scene_pipeline(
520        device: &wgpu::Device,
521        layout: &wgpu::PipelineLayout,
522        module: &wgpu::ShaderModule,
523        fragment: &str,
524        format: wgpu::TextureFormat,
525    ) -> wgpu::RenderPipeline {
526        const ATTRIBUTES: [wgpu::VertexAttribute; 13] = wgpu::vertex_attr_array![
527            0 => Float32x4, 1 => Float32x4, 2 => Float32x4, 3 => Float32x4,
528            4 => Float32x4, 5 => Float32x4, 6 => Float32x4, 7 => Float32x4,
529            8 => Float32x4, 9 => Unorm8x4, 10 => Unorm8x4, 11 => Unorm8x4,
530            12 => Uint32
531        ];
532        device.create_render_pipeline(&wgpu::RenderPipelineDescriptor {
533            label: Some("kova-native pipeline"),
534            layout: Some(layout),
535            vertex: wgpu::VertexState {
536                module,
537                entry_point: Some("vs_main"),
538                compilation_options: Default::default(),
539                buffers: &[Some(wgpu::VertexBufferLayout {
540                    array_stride: std::mem::size_of::<Instance>() as u64,
541                    step_mode: wgpu::VertexStepMode::Instance,
542                    attributes: &ATTRIBUTES,
543                })],
544            },
545            primitive: wgpu::PrimitiveState {
546                topology: wgpu::PrimitiveTopology::TriangleStrip,
547                ..Default::default()
548            },
549            depth_stencil: None,
550            multisample: wgpu::MultisampleState::default(),
551            fragment: Some(wgpu::FragmentState {
552                module,
553                entry_point: Some(fragment),
554                compilation_options: Default::default(),
555                targets: &[Some(wgpu::ColorTargetState {
556                    format,
557                    blend: Some(wgpu::BlendState::PREMULTIPLIED_ALPHA_BLENDING),
558                    write_mask: wgpu::ColorWrites::ALL,
559                })],
560            }),
561            multiview_mask: None,
562            cache: None,
563        })
564    }
565
566    fn pipeline(&mut self, device: &wgpu::Device, format: wgpu::TextureFormat) {
567        let (shader, layout) = (&self.shader, &self.pipeline_layout);
568        self.pipelines.entry(format).or_insert_with(|| {
569            Self::create_scene_pipeline(device, layout, shader, "fs_main", format)
570        });
571    }
572
573    /// Compiles the pipeline of a registered custom shader for `format`.
574    fn custom_pipeline(
575        &mut self,
576        device: &wgpu::Device,
577        id: ShaderId,
578        format: wgpu::TextureFormat,
579    ) {
580        if self.custom_pipelines.contains_key(&(id, format)) {
581            return;
582        }
583        let Some((label, source)) = crate::shaders::shader_module_source(id) else {
584            log::error!("kova-native: unknown custom shader {id:?}");
585            return;
586        };
587        let module = self.custom_modules.entry(id).or_insert_with(|| {
588            device.create_shader_module(wgpu::ShaderModuleDescriptor {
589                label: Some(&label),
590                source: wgpu::ShaderSource::Wgsl(Cow::Owned(source.to_string())),
591            })
592        });
593        let pipeline =
594            Self::create_scene_pipeline(device, &self.pipeline_layout, module, "fs_custom", format);
595        self.custom_pipelines.insert((id, format), pipeline);
596    }
597
598    /// Makes sure `depth` layer targets of `size` exist with current bind groups.
599    fn ensure_layers(&mut self, device: &wgpu::Device, depth: usize, size: (u32, u32)) {
600        if self.layers.first().is_some_and(|l| {
601            (l.target.texture.width(), l.target.texture.height()) != (size.0.max(1), size.1.max(1))
602        }) {
603            self.layers.clear();
604        }
605        while self.layers.len() < depth {
606            let usage =
607                wgpu::TextureUsages::RENDER_ATTACHMENT | wgpu::TextureUsages::TEXTURE_BINDING;
608            let target = Target::new(device, size.0, size.1, usage, "kova-native layer");
609            let composite_group = device.create_bind_group(&wgpu::BindGroupDescriptor {
610                label: Some("kova-native layer composite bind group"),
611                layout: &self.bind_group_layout,
612                entries: &[
613                    wgpu::BindGroupEntry {
614                        binding: 0,
615                        resource: self.globals.as_entire_binding(),
616                    },
617                    wgpu::BindGroupEntry {
618                        binding: 1,
619                        resource: wgpu::BindingResource::TextureView(
620                            &self.atlas_textures.mono.view,
621                        ),
622                    },
623                    wgpu::BindGroupEntry {
624                        binding: 2,
625                        resource: wgpu::BindingResource::TextureView(
626                            &self.atlas_textures.color.view,
627                        ),
628                    },
629                    wgpu::BindGroupEntry {
630                        binding: 3,
631                        resource: wgpu::BindingResource::Sampler(&self.sampler),
632                    },
633                    wgpu::BindGroupEntry {
634                        binding: 4,
635                        resource: wgpu::BindingResource::TextureView(&target.view),
636                    },
637                ],
638            });
639            let post_group = device.create_bind_group(&wgpu::BindGroupDescriptor {
640                label: Some("kova-native layer post bind group"),
641                layout: &self.post_bind_group_layout,
642                entries: &[
643                    wgpu::BindGroupEntry {
644                        binding: 0,
645                        resource: wgpu::BindingResource::Buffer(wgpu::BufferBinding {
646                            buffer: &self.post_params,
647                            offset: 0,
648                            size: wgpu::BufferSize::new(std::mem::size_of::<PostParams>() as u64),
649                        }),
650                    },
651                    wgpu::BindGroupEntry {
652                        binding: 1,
653                        resource: wgpu::BindingResource::TextureView(&target.view),
654                    },
655                    wgpu::BindGroupEntry {
656                        binding: 2,
657                        resource: wgpu::BindingResource::Sampler(&self.sampler),
658                    },
659                ],
660            });
661            self.layers.push(LayerTarget {
662                target,
663                composite_group,
664                post_group,
665            });
666        }
667    }
668
669    fn ensure_effect_targets(&mut self, device: &wgpu::Device, size: (u32, u32)) -> bool {
670        if self.effects.as_ref().is_some_and(|e| e.size == size) {
671            return false;
672        }
673        let usage = wgpu::TextureUsages::RENDER_ATTACHMENT | wgpu::TextureUsages::TEXTURE_BINDING;
674        let scene = Target::new(device, size.0, size.1, usage, "kova-native scene target");
675        let (bw, bh) = (size.0.div_ceil(2), size.1.div_ceil(2));
676        let blur_a = Target::new(device, bw, bh, usage, "kova-native blur a");
677        let blur_b = Target::new(device, bw, bh, usage, "kova-native blur b");
678        let post_group = |view: &wgpu::TextureView| {
679            device.create_bind_group(&wgpu::BindGroupDescriptor {
680                label: Some("kova-native post bind group"),
681                layout: &self.post_bind_group_layout,
682                entries: &[
683                    wgpu::BindGroupEntry {
684                        binding: 0,
685                        resource: wgpu::BindingResource::Buffer(wgpu::BufferBinding {
686                            buffer: &self.post_params,
687                            offset: 0,
688                            size: wgpu::BufferSize::new(std::mem::size_of::<PostParams>() as u64),
689                        }),
690                    },
691                    wgpu::BindGroupEntry {
692                        binding: 1,
693                        resource: wgpu::BindingResource::TextureView(view),
694                    },
695                    wgpu::BindGroupEntry {
696                        binding: 2,
697                        resource: wgpu::BindingResource::Sampler(&self.sampler),
698                    },
699                ],
700            })
701        };
702        let from_scene = post_group(&scene.view);
703        let from_a = post_group(&blur_a.view);
704        let from_b = post_group(&blur_b.view);
705        self.effects = Some(EffectTargets {
706            size,
707            scene,
708            blur_a,
709            blur_b,
710            from_scene,
711            from_a,
712            from_b,
713        });
714        true
715    }
716
717    fn rebuild_bind_group(&mut self, device: &wgpu::Device) {
718        let backdrop = self
719            .effects
720            .as_ref()
721            .map_or(&self.dummy_backdrop.view, |e| &e.blur_a.view);
722        self.bind_group = Some(device.create_bind_group(&wgpu::BindGroupDescriptor {
723            label: Some("kova-native bind group"),
724            layout: &self.bind_group_layout,
725            entries: &[
726                wgpu::BindGroupEntry {
727                    binding: 0,
728                    resource: self.globals.as_entire_binding(),
729                },
730                wgpu::BindGroupEntry {
731                    binding: 1,
732                    resource: wgpu::BindingResource::TextureView(&self.atlas_textures.mono.view),
733                },
734                wgpu::BindGroupEntry {
735                    binding: 2,
736                    resource: wgpu::BindingResource::TextureView(&self.atlas_textures.color.view),
737                },
738                wgpu::BindGroupEntry {
739                    binding: 3,
740                    resource: wgpu::BindingResource::Sampler(&self.sampler),
741                },
742                wgpu::BindGroupEntry {
743                    binding: 4,
744                    resource: wgpu::BindingResource::TextureView(backdrop),
745                },
746            ],
747        }));
748    }
749
750    fn ensure_post_capacity(&mut self, device: &wgpu::Device, slots: u64) {
751        if slots <= self.post_capacity {
752            return;
753        }
754        self.post_capacity = slots.next_power_of_two();
755        self.post_params = device.create_buffer(&wgpu::BufferDescriptor {
756            label: Some("kova-native post params"),
757            size: self.post_stride * self.post_capacity,
758            usage: wgpu::BufferUsages::UNIFORM | wgpu::BufferUsages::COPY_DST,
759            mapped_at_creation: false,
760        });
761        // Post bind groups reference the buffer; force their recreation.
762        let size = self.effects.take().map(|e| e.size);
763        if let Some(size) = size {
764            self.ensure_effect_targets(device, size);
765            // The scene bind group also samples an effect texture. Replacing
766            // those targets must refresh it along with the post bind groups.
767            self.bind_group = None;
768        }
769    }
770
771    /// Renders `scene` into `target` (a view of a `format` texture of `size`
772    /// pixels), clearing it to `clear` first. Submits its own command buffer.
773    pub fn render(
774        &mut self,
775        gpu: &GpuContext,
776        scene: &Scene,
777        target: &wgpu::TextureView,
778        format: wgpu::TextureFormat,
779        size: (u32, u32),
780        clear: Color,
781    ) {
782        let device = &gpu.device;
783        let queue = &gpu.queue;
784        let mut rebuild =
785            self.atlas_textures.sync(device, queue, &mut self.atlas) || self.bind_group.is_none();
786
787        let ops = scene.ops();
788        let captures = ops.iter().filter(|op| matches!(op, Op::Effect(_))).count() as u64;
789        let mut depth = 0usize;
790        let mut max_depth = 0usize;
791        for op in &ops {
792            match op {
793                Op::PushLayer => {
794                    depth += 1;
795                    max_depth = max_depth.max(depth);
796                }
797                Op::PopLayer { .. } => depth = depth.saturating_sub(1),
798                _ => {}
799            }
800        }
801        let use_effects = captures > 0 || max_depth > 0;
802        if use_effects {
803            self.ensure_post_capacity(device, captures * 3 + 1);
804            rebuild |= self.ensure_effect_targets(device, size);
805            rebuild |= self.bind_group.is_none();
806        }
807        if rebuild {
808            self.rebuild_bind_group(device);
809            // Layer bind groups reference the atlas and parameter buffers too.
810            self.layers.clear();
811        }
812        if max_depth > 0 {
813            self.ensure_layers(device, max_depth, size);
814        }
815
816        // Upload instances.
817        let count = scene.instances.len() as u64;
818        if count > self.instance_capacity {
819            self.instance_capacity = count.next_power_of_two();
820            self.instances = Self::create_instance_buffer(device, self.instance_capacity);
821        }
822        if count > 0 {
823            queue.write_buffer(&self.instances, 0, bytemuck::cast_slice(&scene.instances));
824        }
825        let draw_format = if use_effects {
826            OFFSCREEN_FORMAT
827        } else {
828            format
829        };
830        let globals = Globals {
831            viewport: [size.0 as f32, size.1 as f32],
832            linear_output: if !use_effects && is_srgb(format) {
833                1.0
834            } else {
835                0.0
836            },
837            _pad: 0.0,
838        };
839        queue.write_buffer(&self.globals, 0, bytemuck::bytes_of(&globals));
840
841        // sRGB targets expect linear clear values.
842        let clear_color = if !use_effects && is_srgb(format) {
843            let lin = |c: f32| {
844                if c <= 0.04045 {
845                    c / 12.92
846                } else {
847                    ((c + 0.055) / 1.055).powf(2.4)
848                }
849            };
850            wgpu::Color {
851                r: lin(clear.r) as f64,
852                g: lin(clear.g) as f64,
853                b: lin(clear.b) as f64,
854                a: clear.a as f64,
855            }
856        } else {
857            wgpu::Color {
858                r: clear.r as f64,
859                g: clear.g as f64,
860                b: clear.b as f64,
861                a: clear.a as f64,
862            }
863        };
864
865        self.pipeline(device, draw_format);
866        for op in &ops {
867            if let Op::Draw {
868                shader: Some(id), ..
869            } = op
870            {
871                self.custom_pipeline(device, *id, draw_format);
872            }
873        }
874        let pipeline = &self.pipelines[&draw_format];
875        let bind_group = self.bind_group.as_ref().expect("bind group");
876        let mut encoder = device.create_command_encoder(&wgpu::CommandEncoderDescriptor {
877            label: Some("kova-native frame"),
878        });
879        let root = match (&self.effects, use_effects) {
880            (Some(e), true) => &e.scene.view,
881            _ => target,
882        };
883        let layers = &self.layers;
884        let view_at = |depth: usize| {
885            if depth == 0 {
886                root
887            } else {
888                &layers[depth - 1].target.view
889            }
890        };
891        let clear_at = |depth: usize| {
892            if depth == 0 {
893                clear_color
894            } else {
895                wgpu::Color::TRANSPARENT
896            }
897        };
898        let begin = begin_pass;
899
900        let mut post_slot = 0u64;
901        let mut post_writes: Vec<(u64, PostParams)> = Vec::new();
902        // `fresh[d]`: target at depth `d` has not been cleared this frame.
903        let mut fresh = vec![true];
904        for op in &ops {
905            let depth = fresh.len() - 1;
906            match op {
907                Op::Draw { instances, shader } => {
908                    let load = if fresh[depth] {
909                        wgpu::LoadOp::Clear(clear_at(depth))
910                    } else {
911                        wgpu::LoadOp::Load
912                    };
913                    fresh[depth] = false;
914                    let pipeline = match shader {
915                        None => Some(pipeline),
916                        Some(id) => self.custom_pipelines.get(&(*id, draw_format)),
917                    };
918                    let mut pass = begin(&mut encoder, view_at(depth), load);
919                    if let Some(pipeline) = pipeline
920                        && !instances.is_empty()
921                    {
922                        pass.set_pipeline(pipeline);
923                        pass.set_bind_group(0, bind_group, &[]);
924                        pass.set_vertex_buffer(0, self.instances.slice(..));
925                        pass.draw(0..4, instances.clone());
926                    }
927                }
928                Op::Effect(Effect::CaptureBackdrop { blur }) => {
929                    if fresh[depth] {
930                        fresh[depth] = false;
931                        drop(begin(
932                            &mut encoder,
933                            view_at(depth),
934                            wgpu::LoadOp::Clear(clear_at(depth)),
935                        ));
936                    }
937                    if let Some(effects) = &self.effects {
938                        let source = if depth == 0 {
939                            &effects.from_scene
940                        } else {
941                            &layers[depth - 1].post_group
942                        };
943                        Self::encode_blur(
944                            &mut encoder,
945                            effects,
946                            source,
947                            &self.downsample_pipeline,
948                            &self.blur_pipeline,
949                            *blur,
950                            self.post_stride,
951                            &mut post_slot,
952                            &mut post_writes,
953                        );
954                    }
955                }
956                Op::PushLayer => fresh.push(true),
957                Op::PopLayer { composite } => {
958                    if depth == 0 {
959                        continue;
960                    }
961                    let empty = fresh.pop().unwrap_or(true);
962                    let parent = depth - 1;
963                    if let Some(index) = composite
964                        && !empty
965                    {
966                        let load = if fresh[parent] {
967                            wgpu::LoadOp::Clear(clear_at(parent))
968                        } else {
969                            wgpu::LoadOp::Load
970                        };
971                        fresh[parent] = false;
972                        let mut pass = begin(&mut encoder, view_at(parent), load);
973                        pass.set_pipeline(pipeline);
974                        pass.set_bind_group(0, &layers[depth - 1].composite_group, &[]);
975                        pass.set_vertex_buffer(0, self.instances.slice(..));
976                        pass.draw(0..4, *index..*index + 1);
977                    }
978                }
979            }
980        }
981        if fresh[0] {
982            drop(begin(&mut encoder, root, wgpu::LoadOp::Clear(clear_color)));
983        }
984
985        if use_effects && let Some(effects) = &self.effects {
986            let linear = if is_srgb(format) { 1.0 } else { 0.0 };
987            let slot = post_slot;
988            post_writes.push((
989                slot,
990                PostParams {
991                    texel: [1.0 / size.0 as f32, 1.0 / size.1 as f32],
992                    direction: [0.0; 2],
993                    sigma: 0.0,
994                    radius: 0.0,
995                    linear_output: linear,
996                    _pad: 0.0,
997                },
998            ));
999            let post_shader = &self.post_shader;
1000            let post_layout = &self.post_pipeline_layout;
1001            let blit = self.blit_pipelines.entry(format).or_insert_with(|| {
1002                Self::create_post_pipeline(device, post_layout, post_shader, "fs_blit", format)
1003            });
1004            let mut pass = encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
1005                label: Some("kova-native blit"),
1006                color_attachments: &[Some(wgpu::RenderPassColorAttachment {
1007                    view: target,
1008                    depth_slice: None,
1009                    resolve_target: None,
1010                    ops: wgpu::Operations {
1011                        load: wgpu::LoadOp::Clear(wgpu::Color::BLACK),
1012                        store: wgpu::StoreOp::Store,
1013                    },
1014                })],
1015                depth_stencil_attachment: None,
1016                timestamp_writes: None,
1017                occlusion_query_set: None,
1018                multiview_mask: None,
1019            });
1020            pass.set_pipeline(blit);
1021            pass.set_bind_group(0, &effects.from_scene, &[(slot * self.post_stride) as u32]);
1022            pass.draw(0..3, 0..1);
1023        }
1024
1025        for (slot, params) in post_writes {
1026            queue.write_buffer(
1027                &self.post_params,
1028                slot * self.post_stride,
1029                bytemuck::bytes_of(&params),
1030            );
1031        }
1032        queue.submit(Some(encoder.finish()));
1033    }
1034
1035    #[allow(clippy::too_many_arguments)]
1036    fn encode_blur(
1037        encoder: &mut wgpu::CommandEncoder,
1038        effects: &EffectTargets,
1039        source: &wgpu::BindGroup,
1040        downsample: &wgpu::RenderPipeline,
1041        blur: &wgpu::RenderPipeline,
1042        blur_radius: f32,
1043        stride: u64,
1044        slot: &mut u64,
1045        writes: &mut Vec<(u64, PostParams)>,
1046    ) {
1047        let (w, h) = effects.size;
1048        let (bw, bh) = (w.div_ceil(2) as f32, h.div_ceil(2) as f32);
1049        // CSS blur radius = standard deviation; halved at half resolution.
1050        let sigma = (blur_radius * 0.5).max(0.5);
1051        let radius = (sigma * 2.5).ceil().min(64.0);
1052        let steps: [(
1053            &wgpu::RenderPipeline,
1054            &wgpu::BindGroup,
1055            &wgpu::TextureView,
1056            PostParams,
1057        ); 3] = [
1058            (
1059                downsample,
1060                source,
1061                &effects.blur_a.view,
1062                PostParams {
1063                    texel: [1.0 / w as f32, 1.0 / h as f32],
1064                    direction: [0.0; 2],
1065                    sigma: 0.0,
1066                    radius: 0.0,
1067                    linear_output: 0.0,
1068                    _pad: 0.0,
1069                },
1070            ),
1071            (
1072                blur,
1073                &effects.from_a,
1074                &effects.blur_b.view,
1075                PostParams {
1076                    texel: [1.0 / bw, 1.0 / bh],
1077                    direction: [1.0, 0.0],
1078                    sigma,
1079                    radius,
1080                    linear_output: 0.0,
1081                    _pad: 0.0,
1082                },
1083            ),
1084            (
1085                blur,
1086                &effects.from_b,
1087                &effects.blur_a.view,
1088                PostParams {
1089                    texel: [1.0 / bw, 1.0 / bh],
1090                    direction: [0.0, 1.0],
1091                    sigma,
1092                    radius,
1093                    linear_output: 0.0,
1094                    _pad: 0.0,
1095                },
1096            ),
1097        ];
1098        for (pipeline, bind_group, target, params) in steps {
1099            writes.push((*slot, params));
1100            let mut pass = encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
1101                label: Some("kova-native blur"),
1102                color_attachments: &[Some(wgpu::RenderPassColorAttachment {
1103                    view: target,
1104                    depth_slice: None,
1105                    resolve_target: None,
1106                    ops: wgpu::Operations {
1107                        load: wgpu::LoadOp::Clear(wgpu::Color::TRANSPARENT),
1108                        store: wgpu::StoreOp::Store,
1109                    },
1110                })],
1111                depth_stencil_attachment: None,
1112                timestamp_writes: None,
1113                occlusion_query_set: None,
1114                multiview_mask: None,
1115            });
1116            pass.set_pipeline(pipeline);
1117            pass.set_bind_group(0, bind_group, &[(*slot * stride) as u32]);
1118            pass.draw(0..3, 0..1);
1119            *slot += 1;
1120        }
1121    }
1122
1123    /// Renders `scene` offscreen and returns tightly packed RGBA8 pixels
1124    /// (premultiplied alpha). Used for screenshots and visual tests.
1125    pub fn render_to_rgba(
1126        &mut self,
1127        gpu: &GpuContext,
1128        scene: &Scene,
1129        width: u32,
1130        height: u32,
1131        clear: Color,
1132    ) -> Vec<u8> {
1133        let device = &gpu.device;
1134        let target = Target::new(
1135            device,
1136            width,
1137            height,
1138            wgpu::TextureUsages::RENDER_ATTACHMENT | wgpu::TextureUsages::COPY_SRC,
1139            "kova-native screenshot",
1140        );
1141        self.render(
1142            gpu,
1143            scene,
1144            &target.view,
1145            OFFSCREEN_FORMAT,
1146            (width, height),
1147            clear,
1148        );
1149        read_texture(gpu, &target.texture, width, height)
1150    }
1151
1152    /// Copies a texture's contents back to the CPU as RGBA8.
1153    pub fn read_texture_rgba(
1154        &self,
1155        gpu: &GpuContext,
1156        texture: &wgpu::Texture,
1157        width: u32,
1158        height: u32,
1159    ) -> Vec<u8> {
1160        read_texture(gpu, texture, width, height)
1161    }
1162}
1163
1164fn begin_pass<'e>(
1165    encoder: &'e mut wgpu::CommandEncoder,
1166    view: &wgpu::TextureView,
1167    load: wgpu::LoadOp<wgpu::Color>,
1168) -> wgpu::RenderPass<'e> {
1169    encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
1170        label: Some("kova-native scene pass"),
1171        color_attachments: &[Some(wgpu::RenderPassColorAttachment {
1172            view,
1173            depth_slice: None,
1174            resolve_target: None,
1175            ops: wgpu::Operations {
1176                load,
1177                store: wgpu::StoreOp::Store,
1178            },
1179        })],
1180        depth_stencil_attachment: None,
1181        timestamp_writes: None,
1182        occlusion_query_set: None,
1183        multiview_mask: None,
1184    })
1185}
1186
1187fn read_texture(gpu: &GpuContext, texture: &wgpu::Texture, width: u32, height: u32) -> Vec<u8> {
1188    let device = &gpu.device;
1189    let padded_row = (width * 4).next_multiple_of(wgpu::COPY_BYTES_PER_ROW_ALIGNMENT);
1190    let buffer = device.create_buffer(&wgpu::BufferDescriptor {
1191        label: Some("kova-native readback"),
1192        size: (padded_row * height) as u64,
1193        usage: wgpu::BufferUsages::COPY_DST | wgpu::BufferUsages::MAP_READ,
1194        mapped_at_creation: false,
1195    });
1196    let mut encoder = device.create_command_encoder(&wgpu::CommandEncoderDescriptor {
1197        label: Some("kova-native readback"),
1198    });
1199    encoder.copy_texture_to_buffer(
1200        wgpu::TexelCopyTextureInfo {
1201            texture,
1202            mip_level: 0,
1203            origin: wgpu::Origin3d::ZERO,
1204            aspect: wgpu::TextureAspect::All,
1205        },
1206        wgpu::TexelCopyBufferInfo {
1207            buffer: &buffer,
1208            layout: wgpu::TexelCopyBufferLayout {
1209                offset: 0,
1210                bytes_per_row: Some(padded_row),
1211                rows_per_image: Some(height),
1212            },
1213        },
1214        wgpu::Extent3d {
1215            width,
1216            height,
1217            depth_or_array_layers: 1,
1218        },
1219    );
1220    gpu.queue.submit(Some(encoder.finish()));
1221    let slice = buffer.slice(..);
1222    slice.map_async(wgpu::MapMode::Read, |_| {});
1223    let _ = device.poll(wgpu::PollType::Wait {
1224        submission_index: None,
1225        timeout: None,
1226    });
1227    let mut pixels = Vec::with_capacity((width * height * 4) as usize);
1228    if let Ok(view) = slice.get_mapped_range() {
1229        for row in 0..height {
1230            let start = (row * padded_row) as usize;
1231            pixels.extend_from_slice(&view[start..start + (width * 4) as usize]);
1232        }
1233    }
1234    buffer.unmap();
1235    pixels
1236}