unicorn_hat/

buffer.rs

//! Buffer abstraction for pixel operations.
//!
//! This module provides a trait-based abstraction for pixel buffers,
//! enabling unit testing of drawing operations without hardware.

use crate::color::RGB8;
use crate::Error;

/// Trait for types that can store and retrieve pixel data.
///
/// This abstraction allows drawing operations to work with both hardware
/// (via `UnicornHat`) and in-memory buffers (via `TestBuffer`).
pub trait PixelBuffer {
    /// Set a pixel at the given coordinates.
    ///
    /// # Arguments
    /// * `x` - X coordinate (0-7)
    /// * `y` - Y coordinate (0-7)
    /// * `color` - RGB color value
    ///
    /// # Errors
    /// Returns `Error::InvalidCoordinate` if coordinates are out of bounds.
    fn set_pixel(&mut self, x: usize, y: usize, color: RGB8) -> Result<(), Error>;

    /// Get the color of a pixel at the given coordinates.
    ///
    /// # Arguments
    /// * `x` - X coordinate (0-7)
    /// * `y` - Y coordinate (0-7)
    ///
    /// # Errors
    /// Returns `Error::InvalidCoordinate` if coordinates are out of bounds.
    fn get_pixel(&self, x: usize, y: usize) -> Result<RGB8, Error>;

    /// Get the width of the buffer (always 8 for Unicorn HAT).
    fn width(&self) -> usize {
        8
    }

    /// Get the height of the buffer (always 8 for Unicorn HAT).
    fn height(&self) -> usize {
        8
    }
}

/// In-memory buffer for unit testing drawing operations.
///
/// `TestBuffer` provides a simple 8×8 pixel array that implements
/// `PixelBuffer`, allowing drawing primitives to be tested without
/// hardware access.
///
/// # Example
/// ```
/// use unicorn_hat::{RGB8, buffer::{PixelBuffer, TestBuffer}};
///
/// let mut buf = TestBuffer::new();
/// buf.set_pixel(0, 0, RGB8::RED).unwrap();
/// assert_eq!(buf.get_pixel(0, 0).unwrap(), RGB8::RED);
/// ```
#[derive(Debug, Clone, PartialEq)]
pub struct TestBuffer {
    pixels: [[RGB8; 8]; 8],
}

impl TestBuffer {
    /// Create a new buffer filled with black pixels.
    pub fn new() -> Self {
        Self {
            pixels: [[RGB8::BLACK; 8]; 8],
        }
    }

    /// Create a buffer filled with a specific color.
    pub fn with_color(color: RGB8) -> Self {
        Self {
            pixels: [[color; 8]; 8],
        }
    }

    /// Fill the entire buffer with a color.
    pub fn fill(&mut self, color: RGB8) {
        self.pixels = [[color; 8]; 8];
    }

    /// Get all pixels as a 2D array reference.
    pub fn get_all(&self) -> &[[RGB8; 8]; 8] {
        &self.pixels
    }

    /// Set all pixels from a 2D array.
    pub fn set_all(&mut self, pixels: [[RGB8; 8]; 8]) {
        self.pixels = pixels;
    }
}

impl Default for TestBuffer {
    fn default() -> Self {
        Self::new()
    }
}

impl PixelBuffer for TestBuffer {
    fn set_pixel(&mut self, x: usize, y: usize, color: RGB8) -> Result<(), Error> {
        if x >= 8 || y >= 8 {
            return Err(Error::InvalidCoordinate(x, y));
        }
        self.pixels[y][x] = color;
        Ok(())
    }

    fn get_pixel(&self, x: usize, y: usize) -> Result<RGB8, Error> {
        if x >= 8 || y >= 8 {
            return Err(Error::InvalidCoordinate(x, y));
        }
        Ok(self.pixels[y][x])
    }
}

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

    #[test]
    fn test_new_buffer_is_black() {
        let buf = TestBuffer::new();
        for y in 0..8 {
            for x in 0..8 {
                assert_eq!(buf.get_pixel(x, y).unwrap(), RGB8::BLACK);
            }
        }
    }

    #[test]
    fn test_with_color() {
        let buf = TestBuffer::with_color(RGB8::RED);
        for y in 0..8 {
            for x in 0..8 {
                assert_eq!(buf.get_pixel(x, y).unwrap(), RGB8::RED);
            }
        }
    }

    #[test]
    fn test_set_get_pixel() {
        let mut buf = TestBuffer::new();
        buf.set_pixel(3, 4, RGB8::BLUE).unwrap();
        assert_eq!(buf.get_pixel(3, 4).unwrap(), RGB8::BLUE);
        assert_eq!(buf.get_pixel(0, 0).unwrap(), RGB8::BLACK);
    }

    #[test]
    fn test_fill() {
        let mut buf = TestBuffer::new();
        buf.fill(RGB8::GREEN);
        for y in 0..8 {
            for x in 0..8 {
                assert_eq!(buf.get_pixel(x, y).unwrap(), RGB8::GREEN);
            }
        }
    }

    #[test]
    fn test_invalid_coordinates() {
        let mut buf = TestBuffer::new();
        assert!(buf.set_pixel(8, 0, RGB8::RED).is_err());
        assert!(buf.set_pixel(0, 8, RGB8::RED).is_err());
        assert!(buf.set_pixel(8, 8, RGB8::RED).is_err());
        assert!(buf.get_pixel(8, 0).is_err());
        assert!(buf.get_pixel(0, 8).is_err());
    }

    #[test]
    fn test_all_corners() {
        let mut buf = TestBuffer::new();
        buf.set_pixel(0, 0, RGB8::RED).unwrap();
        buf.set_pixel(7, 0, RGB8::GREEN).unwrap();
        buf.set_pixel(0, 7, RGB8::BLUE).unwrap();
        buf.set_pixel(7, 7, RGB8::YELLOW).unwrap();

        assert_eq!(buf.get_pixel(0, 0).unwrap(), RGB8::RED);
        assert_eq!(buf.get_pixel(7, 0).unwrap(), RGB8::GREEN);
        assert_eq!(buf.get_pixel(0, 7).unwrap(), RGB8::BLUE);
        assert_eq!(buf.get_pixel(7, 7).unwrap(), RGB8::YELLOW);
    }

    #[test]
    fn test_dimensions() {
        let buf = TestBuffer::new();
        assert_eq!(buf.width(), 8);
        assert_eq!(buf.height(), 8);
    }

    #[test]
    fn test_get_set_all() {
        let mut buf = TestBuffer::new();
        let mut pixels = [[RGB8::BLACK; 8]; 8];
        pixels[0][0] = RGB8::RED;
        pixels[7][7] = RGB8::BLUE;

        buf.set_all(pixels);
        let result = buf.get_all();

        assert_eq!(result[0][0], RGB8::RED);
        assert_eq!(result[7][7], RGB8::BLUE);
        assert_eq!(result[0][1], RGB8::BLACK);
    }
}