onedrop_renderer/

border.rs

//! Outer + inner border pass.
//!
//! MD2 paints two rectangular rings around the frame between the wave /
//! shape overlays and the blur pyramid. Outer ring thickness comes from
//! `ob_size`, inner from `ib_size`; both are MD2-space fractions of the
//! **shorter** screen dimension, so a horizontal strip on a 16:9 display
//! is screen-symmetric (the thickness in x is divided by the aspect
//! ratio).
//!
//! Implementation: one alpha-blended `TriangleList` pipeline, no vertex
//! buffer. The vertex shader derives the 24-vertex frame from
//! `@builtin(vertex_index)` and a per-draw uniform carrying the outer
//! extent (e.g. `(1, 1)` for the outer ring), the inner extent (e.g.
//! `(1 - t_x, 1 - t_y)`), and the ring colour. Two draws per frame at
//! most; both are no-ops when the alpha is zero.
//!
//! Dispatch slot: after `CustomShapeRenderer`, before the blur pyramid —
//! so the rings feed back next frame (a high-decay preset trails them
//! inward, mirroring MD2's behaviour) and contribute to `GetBlur*`.

use bytemuck::{Pod, Zeroable};
use wgpu::util::DeviceExt;

use crate::config::BorderParams;

/// One ring's per-draw uniform: outer + inner clip-space extents and
/// the ring's RGBA colour. The vertex shader treats the extents as
/// `(±outer_x, ±outer_y)` for the outer quad corners and
/// `(±inner_x, ±inner_y)` for the inner quad corners; the four frame
/// strips (top/bottom/left/right) are built from those eight corners.
#[repr(C)]
#[derive(Debug, Clone, Copy, Pod, Zeroable, PartialEq)]
pub struct BorderUniform {
    /// `[outer_x, outer_y, inner_x, inner_y]` in clip space `[0, 1]`.
    /// We mirror to `(±outer_x, ±outer_y)` inside the shader.
    pub extents: [f32; 4],
    /// `[r, g, b, a]`. Pre-multiplied isn't needed — the pipeline uses
    /// standard alpha blending.
    pub color: [f32; 4],
}

impl Default for BorderUniform {
    fn default() -> Self {
        Self {
            extents: [1.0, 1.0, 1.0, 1.0],
            color: [0.0, 0.0, 0.0, 0.0],
        }
    }
}

/// GPU pass for the two MD2 border rings.
///
/// Holds one shader, one alpha-blended pipeline, and two uniform buffers
/// (outer + inner ring) wired through a shared bind-group layout. Each
/// frame's [`Self::update`] writes both buffers; [`Self::render`]
/// dispatches one draw per ring whose alpha is non-zero.
pub struct BorderRenderer {
    pipeline: wgpu::RenderPipeline,
    bind_group_layout: wgpu::BindGroupLayout,
    outer_uniform: wgpu::Buffer,
    inner_uniform: wgpu::Buffer,
    outer_bind_group: wgpu::BindGroup,
    inner_bind_group: wgpu::BindGroup,
    outer_visible: bool,
    inner_visible: bool,
}

/// Number of vertices the WGSL shader expands per ring. 4 strips × 2
/// triangles × 3 vertices = 24. Exposed for tests.
pub const BORDER_VERTICES_PER_RING: u32 = 24;

impl BorderRenderer {
    pub fn new(device: &wgpu::Device, format: wgpu::TextureFormat) -> Self {
        let shader = crate::pipeline_helpers::load_wgsl(
            device,
            "Border Shader",
            include_str!("../shaders/border.wgsl"),
        );

        let bind_group_layout = device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
            label: Some("Border Bind Group Layout"),
            entries: &[wgpu::BindGroupLayoutEntry {
                binding: 0,
                visibility: wgpu::ShaderStages::VERTEX_FRAGMENT,
                ty: wgpu::BindingType::Buffer {
                    ty: wgpu::BufferBindingType::Uniform,
                    has_dynamic_offset: false,
                    min_binding_size: None,
                },
                count: None,
            }],
        });

        let pipeline_layout = device.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
            label: Some("Border Pipeline Layout"),
            bind_group_layouts: &[Some(&bind_group_layout)],
            immediate_size: 0,
        });

        let pipeline = device.create_render_pipeline(&wgpu::RenderPipelineDescriptor {
            label: Some("Border Pipeline"),
            layout: Some(&pipeline_layout),
            vertex: wgpu::VertexState {
                module: &shader,
                entry_point: Some("vs_main"),
                buffers: &[],
                compilation_options: Default::default(),
            },
            fragment: Some(wgpu::FragmentState {
                module: &shader,
                entry_point: Some("fs_main"),
                targets: &[Some(wgpu::ColorTargetState {
                    format,
                    blend: Some(wgpu::BlendState::ALPHA_BLENDING),
                    write_mask: wgpu::ColorWrites::ALL,
                })],
                compilation_options: Default::default(),
            }),
            primitive: wgpu::PrimitiveState {
                topology: wgpu::PrimitiveTopology::TriangleList,
                ..Default::default()
            },
            depth_stencil: None,
            multisample: wgpu::MultisampleState::default(),
            multiview_mask: None,
            cache: None,
        });

        let initial = BorderUniform::default();
        let make_uniform = |label: &str| {
            device.create_buffer_init(&wgpu::util::BufferInitDescriptor {
                label: Some(label),
                contents: bytemuck::bytes_of(&initial),
                usage: wgpu::BufferUsages::UNIFORM | wgpu::BufferUsages::COPY_DST,
            })
        };
        let outer_uniform = make_uniform("Border Outer Uniform");
        let inner_uniform = make_uniform("Border Inner Uniform");

        let make_bind = |label: &str, buffer: &wgpu::Buffer| {
            device.create_bind_group(&wgpu::BindGroupDescriptor {
                label: Some(label),
                layout: &bind_group_layout,
                entries: &[wgpu::BindGroupEntry {
                    binding: 0,
                    resource: buffer.as_entire_binding(),
                }],
            })
        };
        let outer_bind_group = make_bind("Border Outer Bind Group", &outer_uniform);
        let inner_bind_group = make_bind("Border Inner Bind Group", &inner_uniform);

        Self {
            pipeline,
            bind_group_layout,
            outer_uniform,
            inner_uniform,
            outer_bind_group,
            inner_bind_group,
            outer_visible: false,
            inner_visible: false,
        }
    }

    /// Recompute the per-ring uniforms from a [`BorderParams`] snapshot
    /// and the current output aspect ratio. Rings with alpha ≤ 0 are
    /// flagged as invisible so [`Self::render`] skips their draw call.
    pub fn update(&mut self, queue: &wgpu::Queue, params: BorderParams, aspect_ratio: f32) {
        let (outer, outer_visible) = ring_uniform(
            1.0,
            1.0,
            params.outer_size,
            params.outer_color,
            aspect_ratio,
        );
        // Inner ring sits just inboard of the outer one — its outer
        // extent starts where the outer ring's inner extent stops.
        let inner_outer_x = outer.extents[2];
        let inner_outer_y = outer.extents[3];
        let (inner, inner_visible) = ring_uniform(
            inner_outer_x,
            inner_outer_y,
            params.inner_size,
            params.inner_color,
            aspect_ratio,
        );

        queue.write_buffer(&self.outer_uniform, 0, bytemuck::bytes_of(&outer));
        queue.write_buffer(&self.inner_uniform, 0, bytemuck::bytes_of(&inner));
        self.outer_visible = outer_visible;
        self.inner_visible = inner_visible;
    }

    /// Render both visible rings into `view`. The pass loads existing
    /// contents (no clear) so it composites on top of the warp / wave /
    /// shape output.
    pub fn render(&self, encoder: &mut wgpu::CommandEncoder, view: &wgpu::TextureView) {
        if !self.outer_visible && !self.inner_visible {
            return;
        }
        let mut rp = encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
            label: Some("Border Pass"),
            color_attachments: &[Some(wgpu::RenderPassColorAttachment {
                view,
                depth_slice: None,
                resolve_target: None,
                ops: wgpu::Operations {
                    load: wgpu::LoadOp::Load,
                    store: wgpu::StoreOp::Store,
                },
            })],
            depth_stencil_attachment: None,
            timestamp_writes: None,
            occlusion_query_set: None,
            multiview_mask: None,
        });
        rp.set_pipeline(&self.pipeline);
        if self.outer_visible {
            rp.set_bind_group(0, &self.outer_bind_group, &[]);
            rp.draw(0..BORDER_VERTICES_PER_RING, 0..1);
        }
        if self.inner_visible {
            rp.set_bind_group(0, &self.inner_bind_group, &[]);
            rp.draw(0..BORDER_VERTICES_PER_RING, 0..1);
        }
    }

    /// Number of draw calls the next [`Self::render`] will issue.
    /// Exposed for tests asserting that the pass becomes a no-op when
    /// both rings are transparent.
    pub fn batch_count(&self) -> usize {
        usize::from(self.outer_visible) + usize::from(self.inner_visible)
    }

    /// Read-only access to the bind-group layout. Currently used only
    /// in unit tests that build their own pipelines.
    pub fn bind_group_layout(&self) -> &wgpu::BindGroupLayout {
        &self.bind_group_layout
    }
}

/// Build a `BorderUniform` for one ring given its outer extent
/// `(out_x, out_y)` in clip space, the MD2 `size` (a fraction of the
/// shorter screen axis), the RGBA colour, and the framebuffer aspect
/// ratio `width / height`.
///
/// Returned `(uniform, visible)` — `visible` is `false` when alpha is
/// ≤ 0 or when the requested thickness is so small it would render zero
/// pixels.
fn ring_uniform(
    out_x: f32,
    out_y: f32,
    size: f32,
    color: [f32; 4],
    aspect_ratio: f32,
) -> (BorderUniform, bool) {
    let alpha = color[3];
    let s = size.clamp(0.0, 0.5);
    if alpha <= 0.0 || s <= 0.0 {
        return (
            BorderUniform {
                extents: [out_x, out_y, out_x, out_y],
                color,
            },
            false,
        );
    }

    // MD2 sizes are fractions of the shorter screen dimension. Apply
    // them in clip space (range 2.0): `t_y = 2.0 * size`. To keep the
    // ring screen-symmetric on non-square aspect ratios we divide the
    // x thickness by the aspect ratio (width / height ≥ 1 for typical
    // landscape outputs; the same formula works for portrait — the
    // ring just gets thicker in y).
    let aspect_safe = aspect_ratio.max(1e-3);
    let t_y = 2.0 * s;
    let t_x = if aspect_safe >= 1.0 {
        t_y / aspect_safe
    } else {
        t_y
    };
    let t_y = if aspect_safe < 1.0 {
        t_y * aspect_safe
    } else {
        t_y
    };
    let in_x = (out_x - t_x).max(0.0);
    let in_y = (out_y - t_y).max(0.0);

    (
        BorderUniform {
            extents: [out_x, out_y, in_x, in_y],
            color,
        },
        true,
    )
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn zero_alpha_is_invisible() {
        let (_, visible) = ring_uniform(1.0, 1.0, 0.05, [1.0, 0.0, 0.0, 0.0], 1.0);
        assert!(!visible);
    }

    #[test]
    fn zero_size_is_invisible() {
        let (_, visible) = ring_uniform(1.0, 1.0, 0.0, [1.0, 0.0, 0.0, 1.0], 1.0);
        assert!(!visible);
    }

    #[test]
    fn aspect_correction_keeps_ring_symmetric() {
        // Square aspect: x and y thickness equal.
        let (sq, vis_sq) = ring_uniform(1.0, 1.0, 0.05, [1.0; 4], 1.0);
        assert!(vis_sq);
        let dx_sq = 1.0 - sq.extents[2];
        let dy_sq = 1.0 - sq.extents[3];
        assert!((dx_sq - dy_sq).abs() < 1e-5);

        // 16:9: shorter dim is y, so x gets thinner in clip space.
        let aspect = 16.0_f32 / 9.0;
        let (wide, vis_w) = ring_uniform(1.0, 1.0, 0.05, [1.0; 4], aspect);
        assert!(vis_w);
        let dx = 1.0 - wide.extents[2];
        let dy = 1.0 - wide.extents[3];
        // dy should be the same as the square case (anchored on shorter
        // dim), dx should be scaled down by aspect.
        assert!((dy - dy_sq).abs() < 1e-5);
        assert!((dx - dy / aspect).abs() < 1e-5);
    }

    #[test]
    fn portrait_aspect_swaps_axis() {
        // 9:16 portrait: shorter dim is x, so y gets the divisor.
        let aspect = 9.0_f32 / 16.0;
        let (port, vis) = ring_uniform(1.0, 1.0, 0.05, [1.0; 4], aspect);
        assert!(vis);
        let dx = 1.0 - port.extents[2];
        let dy = 1.0 - port.extents[3];
        // x thickness should match the square case; y should scale down.
        assert!((dx - 2.0 * 0.05).abs() < 1e-5);
        assert!((dy - dx * aspect).abs() < 1e-5);
    }

    #[test]
    fn inner_extent_clamps_at_zero() {
        // Asking for a thickness larger than the half-extent should
        // clamp to 0 instead of producing a negative inner edge.
        let (uni, _vis) = ring_uniform(1.0, 1.0, 0.5, [1.0; 4], 1.0);
        assert!(uni.extents[2] >= 0.0);
        assert!(uni.extents[3] >= 0.0);
    }
}