denise_render/

canvas.rs

//! The drawing target: a borrowed frame plus a clip rectangle.

pub use denise::PixelView;

use denise::{Color, Frame, PixelFormat, Rect, Size};

use crate::blend::{Paint, blend_pixel, blend_span};

/// A clipped, writable pixel target.
///
/// Every operation is clipped to [`Canvas::clip`], which starts as the whole frame
/// and only ever shrinks. Clipping is rectangular: that covers scrolling regions,
/// damage-restricted repaint and nested panels, which is all a UI actually needs.
/// Arbitrary clip shapes are not planned.
///
/// Coordinates are physical pixels relative to the frame origin, never relative to
/// the clip.
#[derive(Debug)]
pub struct Canvas<'a> {
    pixels: &'a mut [u32],
    size: Size,
    stride: usize,
    format: PixelFormat,
    clip: Rect,
}

impl<'a> Canvas<'a> {
    /// Borrows a frame for drawing, clipped to the whole frame.
    pub fn new(frame: &'a mut Frame<'_>) -> Self {
        let size = frame.size();
        let stride = frame.stride() as usize;
        let format = frame.format();
        Self {
            pixels: frame.pixels_mut(),
            size,
            stride,
            format,
            clip: Rect::from_size(size),
        }
    }

    /// Wraps a raw pixel slice. Returns `None` if it is too small for the geometry.
    ///
    /// Prefer [`Canvas::new`]; this exists for offscreen buffers and benchmarks that
    /// have no [`Frame`] to hand.
    pub fn from_pixels(
        pixels: &'a mut [u32],
        size: Size,
        stride: u32,
        format: PixelFormat,
    ) -> Option<Self> {
        if size.is_empty() || stride < size.width {
            return None;
        }
        let stride = stride as usize;
        let required = stride * (size.height as usize - 1) + size.width as usize;
        (pixels.len() >= required).then_some(Self {
            pixels,
            size,
            stride,
            format,
            clip: Rect::from_size(size),
        })
    }

    /// A [`Pen`](crate::Pen) drawing through this canvas.
    ///
    /// The bridge from a concrete rasteriser to the painter-agnostic API widgets
    /// and the text engine take.
    #[inline]
    pub fn pen(&mut self) -> crate::Pen<'_> {
        crate::Pen::new(self)
    }

    /// Full extent of the underlying frame.
    #[inline]
    pub const fn size(&self) -> Size {
        self.size
    }

    /// Word layout of the target.
    #[inline]
    pub const fn format(&self) -> PixelFormat {
        self.format
    }

    /// The region operations are currently restricted to.
    #[inline]
    pub const fn clip(&self) -> Rect {
        self.clip
    }

    /// Narrows the clip in place. Never widens it.
    pub fn clip_to(&mut self, rect: Rect) {
        self.clip = self.clip.intersect(&rect).unwrap_or(Rect::ZERO);
    }

    /// Puts back a clip that [`Painter::push_clip`](crate::Painter::push_clip)
    /// narrowed.
    ///
    /// The one operation that may widen, which is why it is not public: the only
    /// way to reach it is through a [`ClipToken`](crate::ClipToken), and the only
    /// way to hold one of those is to have narrowed the clip first.
    #[inline]
    pub(crate) fn restore_clip(&mut self, rect: Rect) {
        self.clip = rect;
    }

    /// A canvas over the same pixels with a tighter clip.
    ///
    /// The borrow ends when the returned canvas is dropped, so this is how a parent
    /// hands a child a region to draw in without either being able to escape it.
    pub fn with_clip(&mut self, rect: Rect) -> Canvas<'_> {
        let clip = self.clip.intersect(&rect).unwrap_or(Rect::ZERO);
        Canvas {
            pixels: self.pixels,
            size: self.size,
            stride: self.stride,
            format: self.format,
            clip,
        }
    }

    /// Returns `true` if the clip admits no pixels, so drawing can be skipped.
    #[inline]
    pub const fn is_clipped_out(&self) -> bool {
        self.clip.is_empty()
    }

    /// The clipped, visible part of `rect`.
    #[inline]
    pub fn visible(&self, rect: Rect) -> Option<Rect> {
        self.clip.intersect(&rect)
    }

    /// A writable span of row `y` from `x0` to `x1`, clipped. `None` if empty.
    #[inline]
    pub(crate) fn row_span(&mut self, y: i32, x0: i32, x1: i32) -> Option<&mut [u32]> {
        if y < self.clip.y || y >= self.clip.bottom() {
            return None;
        }
        let x0 = x0.max(self.clip.x);
        let x1 = x1.min(self.clip.right());
        if x0 >= x1 {
            return None;
        }
        let base = y as usize * self.stride;
        Some(&mut self.pixels[base + x0 as usize..base + x1 as usize])
    }

    /// Composites a paint over one pixel at `coverage` (`0..=255`), clipped.
    #[inline]
    pub(crate) fn blend_at(&mut self, x: i32, y: i32, paint: Paint, coverage: u32) {
        if coverage == 0 {
            return;
        }
        if let Some(span) = self.row_span(y, x, x + 1)
            && let Some(px) = span.first_mut()
        {
            blend_pixel(px, paint, coverage);
        }
    }

    /// Moves the pixels inside `rect` up by `dy` rows, or down by `-dy` rows
    /// when `dy` is negative, within the clip, leaving the rows that came into
    /// view as they were. [`Painter::scroll_rows`](denise::Painter::scroll_rows)
    /// for a buffer of words, which is the one kind of target that can: a
    /// `copy_within` per row, top to bottom when the content moves up and
    /// bottom to top when it moves down, so the destination always trails the
    /// source. Answers `false` only when there is nothing to copy — no rows
    /// inside the clip, or a move further than the rectangle is tall.
    pub fn scroll_rows(&mut self, rect: Rect, dy: i32) -> bool {
        let Some(rect) = rect
            .intersect(&self.clip)
            .and_then(|r| r.intersect(&Rect::from_size(self.size)))
        else {
            return false;
        };
        let shift = dy.unsigned_abs() as usize;
        let (width, height) = (rect.width as usize, rect.height as usize);
        if dy == 0 || shift >= height || width == 0 {
            return false;
        }
        let stride = self.stride;
        let (left, top) = (rect.x as usize, rect.y as usize);
        // The rectangle is inside the surface and the stride covers a row, so
        // this holds; it is checked because a panic here would be a panic in
        // the paint.
        if (top + height - 1) * stride + left + width > self.pixels.len() {
            return false;
        }
        if dy > 0 {
            // The content moved up, so row `y` takes what row `y + shift` had.
            for row in 0..height - shift {
                let from = (top + row + shift) * stride + left;
                self.pixels
                    .copy_within(from..from + width, (top + row) * stride + left);
            }
        } else {
            for row in (shift..height).rev() {
                let from = (top + row - shift) * stride + left;
                self.pixels
                    .copy_within(from..from + width, (top + row) * stride + left);
            }
        }
        true
    }

    /// Fills the entire clip with an opaque colour.
    ///
    /// This is the full-frame clear when the clip is untouched, and the
    /// damage-restricted clear when it is not.
    pub fn clear(&mut self, color: Color) {
        let paint = Paint::new(Color::rgb(color.r, color.g, color.b));
        let clip = self.clip;
        for y in clip.y..clip.bottom() {
            if let Some(span) = self.row_span(y, clip.x, clip.right()) {
                blend_span(span, paint);
            }
        }
    }

    /// Copies matching regions out of another buffer.
    ///
    /// Source and destination coordinates are the same, so this is the
    /// damage-driven "publish what changed" blit a double-buffered backend needs —
    /// not a general blitter. Regions are clipped to both buffers.
    pub fn copy_from(&mut self, src: &PixelView<'_>, regions: &[Rect]) {
        let bounds = Rect::from_size(Size::new(
            self.size.width.min(src.size().width),
            self.size.height.min(src.size().height),
        ));
        for region in regions {
            let Some(r) = region.intersect(&bounds) else {
                continue;
            };
            for y in r.y..r.bottom() {
                let Some(source) = src.row(y, r.x, r.right()) else {
                    continue;
                };
                // Re-clip through row_span so the canvas clip still applies, then
                // trim the source to whatever survived.
                if let Some(dst) = self.row_span(y, r.x, r.right()) {
                    let n = dst.len().min(source.len());
                    dst[..n].copy_from_slice(&source[..n]);
                }
            }
        }
    }
}

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

    /// Rows moved by a scroll land exactly where a repaint would put them, in
    /// both directions, and rows outside the rectangle and the clip stay.
    #[test]
    fn scrolled_rows_move_within_the_rectangle_and_the_clip() {
        let mut t = TestCanvas::with_stride(8, 8, 10);
        {
            let mut c = t.canvas();
            for y in 0..8 {
                c.fill_rect(Rect::new(0, y, 8, 1), Color::rgb(y as u8, 0, 0));
            }
            // Rows 1..7 of columns 2..6, moved up two: row 1 takes row 3.
            assert!(c.scroll_rows(Rect::new(2, 1, 4, 6), 2));
        }
        let row = |t: &TestCanvas, x: usize, y: usize| (t.pixels()[y * 10 + x] >> 16) & 0xFF;
        assert_eq!(row(&t, 3, 1), 3);
        assert_eq!(row(&t, 3, 4), 6);
        // The two rows that came into view are left as they were.
        assert_eq!(row(&t, 3, 5), 5);
        assert_eq!(row(&t, 3, 6), 6);
        // Outside the rectangle nothing moved.
        assert_eq!(row(&t, 0, 1), 1);
        assert_eq!(row(&t, 3, 0), 0);
        assert_eq!(row(&t, 3, 7), 7);

        // Down by one inside a clip narrower than the rectangle: only the
        // clipped columns move, and the row that came into view at the top
        // keeps what it had.
        {
            let mut c = t.canvas();
            c.clip_to(Rect::new(0, 0, 4, 8));
            assert!(c.scroll_rows(Rect::new(0, 0, 8, 8), -1));
        }
        assert_eq!(row(&t, 1, 2), 1);
        assert_eq!(row(&t, 1, 0), 0);
        assert_eq!(row(&t, 6, 2), 2);

        // Nothing to copy is not a move.
        let mut c = t.canvas();
        assert!(!c.scroll_rows(Rect::new(0, 0, 8, 8), 8));
        assert!(!c.scroll_rows(Rect::new(0, 0, 8, 8), 0));
        assert!(!c.scroll_rows(Rect::new(20, 0, 8, 8), 1));
    }

    #[test]
    fn clip_only_narrows() {
        let mut t = TestCanvas::new(16, 16);
        let mut c = t.canvas();
        c.clip_to(Rect::new(4, 4, 8, 8));
        c.clip_to(Rect::new(0, 0, 16, 16));
        assert_eq!(c.clip(), Rect::new(4, 4, 8, 8));
    }

    #[test]
    fn disjoint_clip_is_empty_not_negative() {
        let mut t = TestCanvas::new(16, 16);
        {
            let mut c = t.canvas();
            c.clip_to(Rect::new(0, 0, 4, 4));
            c.clip_to(Rect::new(8, 8, 4, 4));
            assert!(c.is_clipped_out());
            c.clear(Color::WHITE);
        }
        assert!(t.pixels().iter().all(|&p| p == 0));
    }

    #[test]
    fn nested_clip_borrow_restores_the_parent() {
        let mut t = TestCanvas::new(16, 16);
        let mut c = t.canvas();
        {
            let mut child = c.with_clip(Rect::new(0, 0, 4, 4));
            child.clear(Color::WHITE);
        }
        assert_eq!(c.clip(), Rect::new(0, 0, 16, 16));
    }

    #[test]
    fn clear_respects_the_clip_and_the_stride() {
        let mut t = TestCanvas::with_stride(10, 4, 16);
        {
            let mut c = t.canvas();
            c.clip_to(Rect::new(2, 1, 4, 2));
            c.clear(Color::WHITE);
        }
        for (y, row) in t.pixels().chunks(16).enumerate() {
            for (x, &px) in row.iter().enumerate() {
                let inside = (2..6).contains(&x) && (1..3).contains(&y);
                assert_eq!(px == 0xFFFF_FFFF, inside, "at {x},{y}");
            }
        }
    }

    #[test]
    fn copy_from_moves_only_the_listed_regions() {
        let mut source = TestCanvas::new(8, 8);
        source.canvas().clear(Color::from_argb8888(0xFFAA_BBCC));

        let mut t = TestCanvas::new(8, 8);
        t.canvas()
            .copy_from(&source.view(), &[Rect::new(2, 2, 3, 3)]);

        for y in 0..8 {
            for x in 0..8 {
                let inside = (2..5).contains(&x) && (2..5).contains(&y);
                let expected = if inside { 0xFFAA_BBCC } else { 0 };
                assert_eq!(t.pixels()[y * 8 + x], expected, "at {x},{y}");
            }
        }
    }

    #[test]
    fn copy_from_clips_to_the_smaller_buffer() {
        let mut source = TestCanvas::new(4, 4);
        source.canvas().clear(Color::from_argb8888(0xFFAA_BBCC));

        let mut t = TestCanvas::new(8, 8);
        t.canvas()
            .copy_from(&source.view(), &[Rect::new(0, 0, 8, 8)]);

        assert_eq!(t.pixels()[0], 0xFFAA_BBCC);
        assert_eq!(t.pixels()[3], 0xFFAA_BBCC);
        assert_eq!(t.pixels()[4], 0);
        assert_eq!(t.pixels()[4 * 8], 0);
    }

    #[test]
    fn pixel_view_rejects_undersized_slices() {
        let pixels = [0u32; 10];
        assert!(PixelView::new(&pixels, Size::new(4, 4), 4).is_none());
        assert!(PixelView::new(&pixels, Size::new(4, 2), 2).is_none());
    }
}