hub75_framebuffer/bitplane/

plain.rs

//! Bitplane framebuffer for a 16-bit plain HUB75 interface.
//!
//! This module provides a framebuffer that stores colour data as separate
//! bit-planes rather than the threshold-based frames used by
//! [`crate::plain::DmaFrameBuffer`]. Each plane holds one bit of every colour
//! channel, giving `PLANES` planes total (typically 8 for full 8-bit colour).
//! Row addressing, latch, OE, and colour data are all packed into each 16-bit
//! word -- no external latch circuit is required.
//!
//! # Hardware Requirements
//! Requires a parallel output peripheral capable of clocking 16 bits (though
//! only 15 are actually used) at a time. The data is structured to directly
//! match the HUB75 connector signals, so no external latch or address-decode
//! hardware is needed.
//!
//! # HUB75 Signal Bit Mapping
//! Each 16-bit `Entry` represents the logic levels driven onto the HUB75 bus
//! during a single pixel-clock cycle:
//!
//! ```text
//! 15 ─ (spare)
//! 14 ─ B2       Blue  – lower half of the panel
//! 13 ─ G2       Green – lower half of the panel
//! 12 ─ R2       Red   – lower half of the panel
//! 11 ─ B1       Blue  – upper half of the panel
//! 10 ─ G1       Green – upper half of the panel
//!  9 ─ R1       Red   – upper half of the panel
//!  8 ─ OE       Output-Enable / Blank
//!  7 ─ (spare)
//!  6 ─ (spare)
//!  5 ─ LAT      Latch / STB
//! 4-0 ─ A..E    Row address lines
//! ```
//!
//! The pixel clock is generated by the peripheral that owns the DMA stream and
//! is not part of the 16-bit word stored in the framebuffer.
//!
//! # Bitplane BCM Rendering
//! The framebuffer is organised into `PLANES` bit-planes. Plane 0 carries the
//! MSB (bit 7) of each colour channel, plane 1 carries bit 6, and so on down
//! to plane 7 which carries the LSB (bit 0).
//!
//! To produce correct brightness via Binary Code Modulation, configure the DMA
//! descriptor chain so that each plane's data is output (scanned) a number of
//! times equal to its bit-weight:
//!
//! ```text
//! plane 0 (bit 7) → output 2^7 = 128 times
//! plane 1 (bit 6) → output 2^6 =  64 times
//! plane 2 (bit 5) → output 2^5 =  32 times
//!   …
//! plane 7 (bit 0) → output 2^0 =   1 time
//! ```
//!
//! That is, each plane is scanned `2^(7 - plane_index)` times. The weighted
//! repetition counts sum to 255, reproducing the full 8-bit intensity range.
//! See <https://www.batsocks.co.uk/readme/art_bcm_1.htm> for background on
//! BCM.
//!
//! # Memory Usage
//! Memory scales linearly with `PLANES`: the buffer contains `PLANES` copies
//! of the row data (one per bit-plane). Unlike the threshold-based
//! [`crate::plain::DmaFrameBuffer`] whose frame count grows as
//! `2^BITS - 1`, this layout uses exactly `PLANES` planes regardless of
//! colour depth.
//!
//! Each row is `COLS` 16-bit entries, so total size is
//! `PLANES * NROWS * COLS * 2` bytes.

use core::convert::Infallible;

use bitfield::bitfield;
use embedded_graphics::pixelcolor::RgbColor;
use embedded_graphics::prelude::{DrawTarget, OriginDimensions, Point, Size};

use crate::Color;
use crate::FrameBuffer;
use crate::{FrameBufferOperations, MutableFrameBuffer};

#[cfg(feature = "lead-blank-1")]
const LEAD_BLANK_DELAY: usize = 1;
#[cfg(feature = "lead-blank-2")]
const LEAD_BLANK_DELAY: usize = 2;
#[cfg(feature = "lead-blank-4")]
const LEAD_BLANK_DELAY: usize = 4;
#[cfg(feature = "lead-blank-8")]
const LEAD_BLANK_DELAY: usize = 8;
#[cfg(feature = "lead-blank-16")]
const LEAD_BLANK_DELAY: usize = 16;

// Default to 1 if no lead blank delay feature is enabled
#[cfg(not(any(
    feature = "lead-blank-1",
    feature = "lead-blank-2",
    feature = "lead-blank-4",
    feature = "lead-blank-8",
    feature = "lead-blank-16"
)))]
const LEAD_BLANK_DELAY: usize = 1;

#[cfg(feature = "trail-blank-1")]
const TRAIL_BLANK_DELAY: usize = 1;
#[cfg(feature = "trail-blank-2")]
const TRAIL_BLANK_DELAY: usize = 2;
#[cfg(feature = "trail-blank-4")]
const TRAIL_BLANK_DELAY: usize = 4;
#[cfg(feature = "trail-blank-8")]
const TRAIL_BLANK_DELAY: usize = 8;
#[cfg(feature = "trail-blank-16")]
const TRAIL_BLANK_DELAY: usize = 16;

// Default to 1 if no trail blank delay feature is enabled
#[cfg(not(any(
    feature = "trail-blank-1",
    feature = "trail-blank-2",
    feature = "trail-blank-4",
    feature = "trail-blank-8",
    feature = "trail-blank-16"
)))]
const TRAIL_BLANK_DELAY: usize = 1;

#[cfg(feature = "inter-row-blank-4")]
const INTER_ROW_BLANK: usize = 4;
#[cfg(feature = "inter-row-blank-8")]
const INTER_ROW_BLANK: usize = 8;
#[cfg(feature = "inter-row-blank-16")]
const INTER_ROW_BLANK: usize = 16;
#[cfg(feature = "inter-row-blank-32")]
const INTER_ROW_BLANK: usize = 32;
#[cfg(not(any(
    feature = "inter-row-blank-4",
    feature = "inter-row-blank-8",
    feature = "inter-row-blank-16",
    feature = "inter-row-blank-32"
)))]
const INTER_ROW_BLANK: usize = 0;

#[cfg(not(feature = "invert-oe"))]
const OE_ACTIVE: u16 = 0b1_0000_0000;
#[cfg(not(feature = "invert-oe"))]
const OE_BLANK: u16 = 0;

#[cfg(feature = "invert-oe")]
const OE_ACTIVE: u16 = 0;
#[cfg(feature = "invert-oe")]
const OE_BLANK: u16 = 0b1_0000_0000;

#[inline]
const fn map_index(i: usize) -> usize {
    #[cfg(feature = "esp32-ordering")]
    {
        i ^ 1
    }
    #[cfg(not(feature = "esp32-ordering"))]
    {
        i
    }
}

#[inline]
const fn make_data_template<const COLS: usize>(addr: u8) -> [Entry; COLS] {
    let mut data = [Entry::new(); COLS];
    let mut i = 0;

    while i < COLS {
        let mut entry = Entry::new();
        entry.0 = addr as u16 | OE_BLANK;

        if i == COLS - 1 {
            entry.0 |= 0b0010_0000; // latch
        } else if i >= TRAIL_BLANK_DELAY && i < COLS.saturating_sub(LEAD_BLANK_DELAY + 1) {
            entry.0 = (entry.0 & !0b1_0000_0000) | OE_ACTIVE;
        }

        data[map_index(i)] = entry;
        i += 1;
    }

    data
}

bitfield! {
    #[derive(Clone, Copy, Default, PartialEq)]
    #[repr(transparent)]
    pub(crate) struct Entry(u16);
    pub(crate) dummy2, set_dummy2: 15;
    pub(crate) blu2, set_blu2: 14;
    pub(crate) grn2, set_grn2: 13;
    pub(crate) red2, set_red2: 12;
    pub(crate) blu1, set_blu1: 11;
    pub(crate) grn1, set_grn1: 10;
    pub(crate) red1, set_red1: 9;
    pub(crate) output_enable, set_output_enable: 8;
    pub(crate) dummy1, set_dummy1: 7;
    pub(crate) dummy0, set_dummy0: 6;
    pub(crate) latch, set_latch: 5;
    pub(crate) addr, set_addr: 4, 0;
}

impl core::fmt::Debug for Entry {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        f.debug_tuple("Entry")
            .field(&format_args!("{:#x}", self.0))
            .finish()
    }
}

impl Entry {
    const fn new() -> Self {
        Self(OE_BLANK)
    }

    const COLOR0_MASK: u16 = 0b0000_1110_0000_0000; // bits 9-11: R1, G1, B1
    const COLOR1_MASK: u16 = 0b0111_0000_0000_0000; // bits 12-14: R2, G2, B2

    #[inline]
    fn set_color0_bits(&mut self, bits: u8) {
        let bits16 = u16::from(bits) << 9;
        self.0 = (self.0 & !Self::COLOR0_MASK) | (bits16 & Self::COLOR0_MASK);
    }

    #[inline]
    fn set_color1_bits(&mut self, bits: u8) {
        let bits16 = u16::from(bits) << 12;
        self.0 = (self.0 & !Self::COLOR1_MASK) | (bits16 & Self::COLOR1_MASK);
    }
}

#[derive(Clone, Copy, PartialEq, Debug)]
#[repr(C)]
/// A single BCM row payload for 16-bit plain output.
///
/// Row addressing, latch, OE, and pixel colour data are all encoded into the
/// 16-bit `Entry` words -- no separate address bytes are needed.
pub struct Row<const COLS: usize> {
    pub(crate) data: [Entry; COLS],
    pub(crate) gap: [Entry; INTER_ROW_BLANK],
}

impl<const COLS: usize> Row<COLS> {
    /// Creates a zero-initialized row.
    ///
    /// Call [`Self::format`] before first use to populate row control metadata.
    #[must_use]
    pub const fn new() -> Self {
        Self {
            data: [Entry::new(); COLS],
            gap: [Entry::new(); INTER_ROW_BLANK],
        }
    }

    /// Formats this row for the provided multiplexed row address.
    ///
    /// Sets up blanking delay, output-enable, latch, and address bits in the
    /// pixel stream template.
    #[inline]
    pub const fn format(&mut self, prev_addr: u8) {
        let template = make_data_template::<COLS>(prev_addr);
        let mut i = 0;
        while i < COLS {
            self.data[i] = template[i];
            i += 1;
        }

        let gap_val = (prev_addr as u16) | OE_BLANK;
        let mut i = 0;
        // INTER_ROW_BLANK is 0 unless an inter-row-blank-* feature is enabled.
        #[allow(clippy::absurd_extreme_comparisons)]
        while i < INTER_ROW_BLANK {
            self.gap[i].0 = gap_val;
            i += 1;
        }
    }
}

impl<const COLS: usize> Default for Row<COLS> {
    fn default() -> Self {
        Self::new()
    }
}

/// A single bit-plane's DMA payload: all rows for the plane, optionally
/// followed by a tail word (see the `tail-closes-latch` feature).
#[derive(Clone, Copy, PartialEq, Debug)]
#[repr(C)]
pub struct PlaneData<const NROWS: usize, const COLS: usize> {
    pub(crate) rows: [Row<COLS>; NROWS],
    // Extra word that parks LATCH=0 and OE=BLANK on the GPIO pins after the
    // last clock edge, preventing the latch from staying asserted between
    // DMA descriptor loops.  On an esp32 the words are also re-ordered (swapped) so
    // we need a padding word.
    #[cfg(all(feature = "tail-closes-latch", feature = "esp32-ordering"))]
    pub(crate) padding: Entry,
    #[cfg(feature = "tail-closes-latch")]
    pub(crate) tail: Entry,
}

impl<const NROWS: usize, const COLS: usize> PlaneData<NROWS, COLS> {
    const fn new() -> Self {
        Self {
            rows: [Row::new(); NROWS],
            #[cfg(all(feature = "esp32-ordering", feature = "tail-closes-latch"))]
            padding: Entry::new(),
            #[cfg(feature = "tail-closes-latch")]
            tail: Entry::new(),
        }
    }
}

/// The entire BCM Frame Buffer (per-plane storage).
#[derive(Copy, Clone)]
#[repr(C)]
pub struct DmaFrameBuffer<const NROWS: usize, const COLS: usize, const PLANES: usize> {
    pub(crate) planes: [PlaneData<NROWS, COLS>; PLANES],
}

impl<const NROWS: usize, const COLS: usize, const PLANES: usize>
    DmaFrameBuffer<NROWS, COLS, PLANES>
{
    /// Creates a new frame buffer, pre-formatted and ready for use.
    #[must_use]
    pub const fn new() -> Self {
        let mut instance = Self {
            planes: [PlaneData::new(); PLANES],
        };
        instance.format();
        instance
    }

    /// Returns the number of BCM chunks (one per bit-plane).
    #[must_use]
    pub const fn bcm_chunk_count() -> usize {
        PLANES
    }

    /// Returns the byte size of one BCM chunk (a single bit-plane including tail word).
    #[must_use]
    pub const fn bcm_chunk_bytes() -> usize {
        core::mem::size_of::<PlaneData<NROWS, COLS>>()
    }

    /// Formats the frame buffer with row addresses and control bits.
    #[inline]
    pub const fn format(&mut self) {
        let mut p = 0;
        while p < PLANES {
            let mut row_idx = 0;
            while row_idx < NROWS {
                let prev_addr = if row_idx == 0 {
                    NROWS as u8 - 1
                } else {
                    row_idx as u8 - 1
                };
                self.planes[p].rows[row_idx].format(prev_addr);
                row_idx += 1;
            }
            #[cfg(feature = "tail-closes-latch")]
            {
                self.planes[p].tail.0 = 0x1f | OE_BLANK;
            }
            #[cfg(all(feature = "esp32-ordering", feature = "tail-closes-latch"))]
            {
                self.planes[p].padding.0 = 0x1f | OE_BLANK;
            }
            p += 1;
        }
    }

    /// Erase pixel colors while preserving row control data.
    #[inline]
    pub fn erase(&mut self) {
        const MASK: u16 = !0b0111_1110_0000_0000; // clear bits 9-14 (R1,G1,B1,R2,G2,B2)
        for plane in &mut self.planes {
            for row in &mut plane.rows {
                for entry in &mut row.data {
                    entry.0 &= MASK;
                }
            }
        }
    }

    /// Set a pixel in the framebuffer.
    #[inline]
    pub fn set_pixel(&mut self, p: Point, color: Color) {
        if p.x < 0 || p.y < 0 {
            return;
        }
        self.set_pixel_internal(p.x as usize, p.y as usize, color);
    }

    #[inline]
    fn set_pixel_internal(&mut self, x: usize, y: usize, color: Color) {
        if x >= COLS || y >= NROWS * 2 {
            return;
        }

        let row_idx = if y < NROWS { y } else { y - NROWS };
        let is_top = y < NROWS;
        let red = color.r();
        let green = color.g();
        let blue = color.b();

        for plane_idx in 0..PLANES {
            let bit = 7_u32.saturating_sub(plane_idx as u32);
            let bits = ((u8::from(((blue >> bit) & 1) != 0)) << 2)
                | ((u8::from(((green >> bit) & 1) != 0)) << 1)
                | u8::from(((red >> bit) & 1) != 0);
            let col_idx = map_index(x);
            let entry = &mut self.planes[plane_idx].rows[row_idx].data[col_idx];
            if is_top {
                entry.set_color0_bits(bits);
            } else {
                entry.set_color1_bits(bits);
            }
        }
    }
}

impl<const NROWS: usize, const COLS: usize, const PLANES: usize> Default
    for DmaFrameBuffer<NROWS, COLS, PLANES>
{
    fn default() -> Self {
        Self::new()
    }
}

impl<const NROWS: usize, const COLS: usize, const PLANES: usize> core::fmt::Debug
    for DmaFrameBuffer<NROWS, COLS, PLANES>
{
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        f.debug_struct("DmaFrameBuffer")
            .field("size", &core::mem::size_of_val(&self.planes))
            .field("plane_count", &self.planes.len())
            .field("plane_size", &core::mem::size_of_val(&self.planes[0]))
            .finish()
    }
}

#[cfg(feature = "defmt")]
impl<const NROWS: usize, const COLS: usize, const PLANES: usize> defmt::Format
    for DmaFrameBuffer<NROWS, COLS, PLANES>
{
    fn format(&self, f: defmt::Formatter) {
        defmt::write!(f, "DmaFrameBuffer<{}, {}, {}>", NROWS, COLS, PLANES);
        defmt::write!(f, " size: {}", core::mem::size_of_val(&self.planes));
        defmt::write!(
            f,
            " plane_size: {}",
            core::mem::size_of_val(&self.planes[0])
        );
    }
}

impl<const NROWS: usize, const COLS: usize, const PLANES: usize> FrameBuffer
    for DmaFrameBuffer<NROWS, COLS, PLANES>
{
    type Word = u16;

    fn plane_count(&self) -> usize {
        PLANES
    }

    fn plane_ptr_len(&self, plane_idx: usize) -> (*const u8, usize) {
        assert!(
            plane_idx < PLANES,
            "plane_idx {plane_idx} out of range for {PLANES} planes"
        );
        let ptr = (&raw const self.planes[plane_idx]).cast::<u8>();
        let len = core::mem::size_of::<PlaneData<NROWS, COLS>>();
        (ptr, len)
    }
}

impl<const NROWS: usize, const COLS: usize, const PLANES: usize> FrameBufferOperations
    for DmaFrameBuffer<NROWS, COLS, PLANES>
{
    #[inline]
    fn erase(&mut self) {
        DmaFrameBuffer::<NROWS, COLS, PLANES>::erase(self);
    }

    #[inline]
    fn set_pixel(&mut self, p: Point, color: Color) {
        DmaFrameBuffer::<NROWS, COLS, PLANES>::set_pixel(self, p, color);
    }
}

impl<const NROWS: usize, const COLS: usize, const PLANES: usize> MutableFrameBuffer
    for DmaFrameBuffer<NROWS, COLS, PLANES>
{
}

impl<const NROWS: usize, const COLS: usize, const PLANES: usize> OriginDimensions
    for DmaFrameBuffer<NROWS, COLS, PLANES>
{
    fn size(&self) -> Size {
        Size::new(COLS as u32, (NROWS * 2) as u32)
    }
}

impl<const NROWS: usize, const COLS: usize, const PLANES: usize> DrawTarget
    for DmaFrameBuffer<NROWS, COLS, PLANES>
{
    type Color = Color;
    type Error = Infallible;

    fn draw_iter<I>(&mut self, pixels: I) -> Result<(), Self::Error>
    where
        I: IntoIterator<Item = embedded_graphics::Pixel<Self::Color>>,
    {
        for pixel in pixels {
            self.set_pixel_internal(pixel.0.x as usize, pixel.0.y as usize, pixel.1);
        }
        Ok(())
    }
}

#[cfg(test)]
mod tests {
    extern crate std;

    use super::*;
    use embedded_graphics::prelude::*;
    use std::format;

    const TEST_COLS: usize = 64;
    type TestBuffer = DmaFrameBuffer<16, 64, 8>;

    #[test]
    fn row_format_sets_address_and_control_bits() {
        let mut row = Row::<TEST_COLS>::new();
        row.format(4);

        let last_idx = map_index(TEST_COLS - 1);
        assert_eq!(row.data[last_idx].latch(), true);
        assert_eq!(row.data[last_idx].addr(), 4);

        let first_idx = map_index(0);
        assert_eq!(row.data[first_idx].addr(), 4);
        assert_eq!(row.data[first_idx].latch(), false);
    }

    #[test]
    fn format_sets_expected_row_addresses_for_all_rows() {
        let mut fb = TestBuffer::new();
        fb.format();

        for plane_idx in 0..8 {
            for row_idx in 0..16 {
                let prev_addr = if row_idx == 0 { 15 } else { row_idx - 1 };
                let last_col = map_index(63);
                assert_eq!(
                    fb.planes[plane_idx].rows[row_idx].data[last_col].addr(),
                    prev_addr as u16
                );
                assert_eq!(
                    fb.planes[plane_idx].rows[row_idx].data[last_col].latch(),
                    true
                );
            }
        }
    }

    #[test]
    fn set_pixel_maps_top_half_bits_per_plane() {
        let mut fb = TestBuffer::new();
        let color = Color::new(0b1010_0101, 0b0101_1010, 0b1111_0000);
        fb.set_pixel(Point::new(2, 3), color);

        for plane_idx in 0..8 {
            let bit = 7 - plane_idx;
            let entry = fb.planes[plane_idx].rows[3].data[map_index(2)];
            assert_eq!(entry.red1(), ((color.r() >> bit) & 1) != 0);
            assert_eq!(entry.grn1(), ((color.g() >> bit) & 1) != 0);
            assert_eq!(entry.blu1(), ((color.b() >> bit) & 1) != 0);
        }
    }

    #[test]
    fn set_pixel_maps_bottom_half_bits_per_plane() {
        let mut fb = TestBuffer::new();
        let color = Color::new(0b1100_0011, 0b0011_1100, 0b1001_0110);
        fb.set_pixel(Point::new(4, 20), color);

        for plane_idx in 0..8 {
            let bit = 7 - plane_idx;
            let entry = fb.planes[plane_idx].rows[4].data[map_index(4)];
            assert_eq!(entry.red2(), ((color.r() >> bit) & 1) != 0);
            assert_eq!(entry.grn2(), ((color.g() >> bit) & 1) != 0);
            assert_eq!(entry.blu2(), ((color.b() >> bit) & 1) != 0);
        }
    }

    #[test]
    fn erase_clears_only_color_bits() {
        let mut fb = TestBuffer::new();
        let oe_before = fb.planes[0].rows[0].data[map_index(1)].output_enable();
        fb.set_pixel(Point::new(0, 0), Color::WHITE);
        fb.erase();

        for plane in &fb.planes {
            for row in &plane.rows {
                for entry in &row.data {
                    assert!(!entry.red1());
                    assert!(!entry.grn1());
                    assert!(!entry.blu1());
                    assert!(!entry.red2());
                    assert!(!entry.grn2());
                    assert!(!entry.blu2());
                }
            }
        }

        assert_eq!(
            fb.planes[0].rows[0].data[map_index(1)].output_enable(),
            oe_before
        );
    }

    #[test]
    fn draw_target_iter_sets_pixels() {
        let mut fb = TestBuffer::new();
        let pixels = [Pixel(Point::new(1, 1), Color::RED)];
        let result = fb.draw_iter(pixels);
        assert!(result.is_ok());

        for plane_idx in 0..8 {
            let bit = 7 - plane_idx;
            let entry = fb.planes[plane_idx].rows[1].data[map_index(1)];
            assert_eq!(entry.red1(), ((Color::RED.r() >> bit) & 1) != 0);
            assert!(!entry.grn1());
            assert!(!entry.blu1());
        }
    }

    #[test]
    fn set_pixel_ignores_out_of_bounds_and_negative() {
        let mut fb = TestBuffer::new();
        let before = fb.planes;
        fb.set_pixel(Point::new(-1, 0), Color::WHITE);
        fb.set_pixel(Point::new(0, -1), Color::WHITE);
        fb.set_pixel(Point::new(64, 0), Color::WHITE);
        fb.set_pixel(Point::new(0, 32), Color::WHITE);
        assert_eq!(fb.planes, before);
    }

    #[test]
    fn bcm_chunk_info_for_common_panel() {
        assert_eq!(TestBuffer::bcm_chunk_count(), 8);
        assert_eq!(
            TestBuffer::bcm_chunk_bytes(),
            core::mem::size_of::<PlaneData<16, 64>>()
        );
    }

    #[test]
    fn frame_buffer_trait_accessors_report_expected_values() {
        let fb = TestBuffer::new();
        let as_trait: &dyn FrameBuffer<Word = u16> = &fb;
        assert_eq!(as_trait.get_word_size(), crate::WordSize::Sixteen);
        assert_eq!(as_trait.plane_count(), 8);

        let (ptr, len) = as_trait.plane_ptr_len(0);
        assert_eq!(len, core::mem::size_of::<PlaneData<16, 64>>());
        assert_eq!(ptr, (&raw const fb.planes[0]).cast::<u8>());
    }

    #[test]
    #[should_panic(expected = "out of range")]
    fn plane_ptr_len_panics_for_invalid_plane() {
        let fb = TestBuffer::new();
        let _ = fb.plane_ptr_len(8);
    }

    #[test]
    fn origin_dimensions_match_panel_geometry() {
        let fb = TestBuffer::new();
        assert_eq!(fb.size(), Size::new(64, 32));
    }

    #[test]
    fn debug_impl_includes_shape_information() {
        let fb = TestBuffer::new();
        let s = format!("{fb:?}");
        assert!(s.contains("DmaFrameBuffer"));
        assert!(s.contains("plane_count"));
        assert!(s.contains("plane_size"));
    }

    #[test]
    fn row_format_sets_expected_blank_and_latch_positions() {
        let mut row = Row::<TEST_COLS>::new();
        row.format(4);

        let oe_active = !cfg!(feature = "invert-oe");

        // DMA index TRAIL_BLANK_DELAY: first active pixel (right edge = DMA start)
        let idx_active = map_index(TRAIL_BLANK_DELAY);
        assert_eq!(row.data[idx_active].output_enable(), oe_active);
        assert_eq!(row.data[idx_active].addr(), 4);

        // i == COLS - LEAD_BLANK_DELAY - 1: lead blanking before latch (left edge)
        let idx_blank = map_index(TEST_COLS - LEAD_BLANK_DELAY - 1);
        assert_eq!(row.data[idx_blank].output_enable(), !oe_active);

        // i == COLS - 1 latches, address stays at prev_addr
        let idx_last = map_index(TEST_COLS - 1);
        assert!(row.data[idx_last].latch());
        assert_eq!(row.data[idx_last].addr(), 4);
    }

    #[test]
    fn default_constructors_match_new() {
        let row_default = Row::<TEST_COLS>::default();
        let row_new = Row::<TEST_COLS>::new();
        assert_eq!(row_default, row_new);

        let fb_default = TestBuffer::default();
        let fb_new = TestBuffer::new();
        assert_eq!(fb_default.planes, fb_new.planes);
    }

    #[test]
    fn framebuffer_operations_trait_delegates_correctly() {
        let mut fb = TestBuffer::new();
        FrameBufferOperations::set_pixel(&mut fb, Point::new(3, 5), Color::GREEN);

        assert!(fb.planes[0].rows[5].data[map_index(3)].grn1());

        FrameBufferOperations::erase(&mut fb);
        for plane in &fb.planes {
            for row in &plane.rows {
                for entry in &row.data {
                    assert!(!entry.red1());
                    assert!(!entry.grn1());
                    assert!(!entry.blu1());
                    assert!(!entry.red2());
                    assert!(!entry.grn2());
                    assert!(!entry.blu2());
                }
            }
        }
    }

    #[test]
    fn entry_debug_shows_hex_value() {
        let mut entry = Entry::new();
        entry.set_red1(true);
        let s = format!("{entry:?}");
        assert!(s.contains("Entry"));
        assert!(s.contains("0x"));
    }

    #[test]
    fn entry_new_oe_matches_feature() {
        let entry = Entry::new();
        if cfg!(feature = "invert-oe") {
            assert!(entry.output_enable());
        } else {
            assert!(!entry.output_enable());
        }
    }

    #[test]
    fn make_data_template_oe_polarity() {
        let mut row = Row::<TEST_COLS>::new();
        row.format(4);

        let active_idx = map_index(TRAIL_BLANK_DELAY);
        let blank_idx = map_index(TEST_COLS - LEAD_BLANK_DELAY - 1);
        let latch_idx = map_index(TEST_COLS - 1);

        if cfg!(feature = "invert-oe") {
            assert!(!row.data[active_idx].output_enable());
            assert!(row.data[blank_idx].output_enable());
            assert!(row.data[latch_idx].output_enable());
        } else {
            assert!(row.data[active_idx].output_enable());
            assert!(!row.data[blank_idx].output_enable());
            assert!(!row.data[latch_idx].output_enable());
        }
    }

    static STATIC_FB: TestBuffer = TestBuffer::new();

    #[test]
    fn test_static_construction_is_formatted() {
        let runtime_fb = TestBuffer::new();

        for (pi, plane) in STATIC_FB.planes.iter().enumerate() {
            for (ri, row) in plane.rows.iter().enumerate() {
                assert_eq!(
                    row.data, runtime_fb.planes[pi].rows[ri].data,
                    "static vs runtime mismatch at plane {pi}, row {ri}"
                );
                assert_eq!(
                    row.gap, runtime_fb.planes[pi].rows[ri].gap,
                    "static vs runtime gap mismatch at plane {pi}, row {ri}"
                );
            }
        }
    }

    #[test]
    fn test_format_reinitializes_at_runtime() {
        let mut fb = TestBuffer::new();
        fb.erase();
        fb.format();

        for (pi, plane) in fb.planes.iter().enumerate() {
            for (ri, row) in plane.rows.iter().enumerate() {
                assert_eq!(
                    row.data, STATIC_FB.planes[pi].rows[ri].data,
                    "re-formatted vs static mismatch at plane {pi}, row {ri}"
                );
            }
        }
    }
}