hub75_framebuffer/

plain.rs

//! DMA-friendly framebuffer implementation for HUB75 LED panels.
//!
//! This module provides a framebuffer implementation with memory
//! layout optimized for efficient transfer to HUB75 LED panels. The data is
//! structured for direct signal mapping, making it ideal for DMA transfers but
//! also suitable for programmatic transfer. It supports RGB color and brightness
//! control through multiple frames using Binary Code Modulation (BCM).
//!
//! # Hardware Requirements
//! This implementation can be used by any microcontroller that has a peripheral
//! capable of outputting a clock signal and 16 bits (though only 14 bits are
//! actually needed) in parallel. The data is structured to directly match the
//! HUB75 connector signals, making it suitable for various parallel output
//! peripherals.
//!
//! # Features
//! - Memory layout optimized for efficient data transfer
//! - Direct signal mapping to HUB75 connector signals
//! - Support for RGB color with brightness control
//! - Multiple frame buffers for Binary Code Modulation (BCM)
//! - Integration with embedded-graphics for easy drawing
//!
//! # Brightness Control
//! Brightness is controlled through Binary Code Modulation (BCM):
//! - The number of brightness levels is determined by the `BITS` parameter
//! - Each additional bit doubles the number of brightness levels
//! - More bits provide better brightness resolution but require more memory
//! - Memory usage grows exponentially with the number of bits: `(2^BITS)-1`
//!   frames
//! - Example: 8 bits = 256 levels, 4 bits = 16 levels
//!
//! # Memory Usage
//! The framebuffer's memory usage is determined by:
//! - Panel size (ROWS × COLS)
//! - Number of brightness bits (BITS)
//! - Memory grows exponentially with bits: `(2^BITS)-1` frames
//! - 16-bit entries provide direct signal mapping but use more memory
//!
//! # Example
//! ```rust,no_run
//! use embedded_graphics::pixelcolor::RgbColor;
//! use embedded_graphics::prelude::*;
//! use embedded_graphics::primitives::Circle;
//! use embedded_graphics::primitives::Rectangle;
//! use hub75_framebuffer::compute_frame_count;
//! use hub75_framebuffer::compute_rows;
//! use hub75_framebuffer::Color;
//! use hub75_framebuffer::plain::DmaFrameBuffer;
//! use embedded_graphics::primitives::PrimitiveStyle;
//!
//! // Create a framebuffer for a 64x32 panel with 3-bit color depth
//! const ROWS: usize = 32;
//! const COLS: usize = 64;
//! const BITS: u8 = 3; // Color depth (8 brightness levels, 7 frames)
//! const NROWS: usize = compute_rows(ROWS); // Number of rows per scan
//! const FRAME_COUNT: usize = compute_frame_count(BITS); // Number of frames for BCM
//!
//! let mut framebuffer = DmaFrameBuffer::<ROWS, COLS, NROWS, BITS, FRAME_COUNT>::new();
//!
//! // Draw a red rectangle
//! Rectangle::new(Point::new(10, 10), Size::new(20, 20))
//!     .into_styled(PrimitiveStyle::with_fill(Color::RED))
//!     .draw(&mut framebuffer)
//!     .unwrap();
//!
//! // Draw a blue circle
//! Circle::new(Point::new(40, 20), 10)
//!     .into_styled(PrimitiveStyle::with_fill(Color::BLUE))
//!     .draw(&mut framebuffer)
//!     .unwrap();
//! ```
//!
//! # Implementation Details
//! The framebuffer is organized to directly match the HUB75 connector signals:
//! - Each 16-bit word maps directly to the HUB75 control signals
//! - Color data (R, G, B) for two sub-pixels is stored in dedicated bits
//! - Control signals (output enable, latch, address) are mapped to specific
//!   bits
//! - Multiple frames are used to achieve Binary Code Modulation (BCM)
//! - DMA transfers the data directly to the panel without any transformation
//!
//! # HUB75 Signal Bit Mapping
//! Each 16-bit `Entry` represents the logic levels that will be driven onto the HUB75
//! bus during a single pixel-clock cycle. Every panel signal—apart from the clock
//! (`CLK`) itself—occupies a dedicated bit, allowing the word to be streamed via DMA
//! with zero run-time manipulation.
//!
//! ```text
//! 15 ─ Dummy2   (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 ─ Dummy1   (spare)
//!  6 ─ Dummy0   (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 therefore **not** part of the 16-bit word stored in the framebuffer.
//!
//! # Binary Code Modulation (BCM) Frames
//! Brightness is achieved with Binary-Code-Modulation as outlined in
//! <https://www.batsocks.co.uk/readme/art_bcm_1.htm>. For a colour depth of
//! `BITS`, the driver allocates `FRAME_COUNT = 2^BITS - 1` frames. Frame *n*
//! (0-based) is displayed for a duration proportional to `2^n`, mirroring the
//! weight of that bit in a binary number.
//!
//! When a pixel is written its 8-bit RGB components are compared against a
//! per-frame threshold:
//!
//! ```text
//! brightness_step = 256 / 2^BITS
//! threshold_n     = (n + 1) * brightness_step
//! ```
//!
//! If a channel's value is greater than or equal to `threshold_n` the
//! corresponding colour bit is set in frame *n*. Streaming the frames from the
//! least-significant (shortest) to the most-significant (longest) time-slot
//! produces the correct 8-bit brightness while keeping the refresh routine
//! trivial.
//!
//! # Safety
//! This implementation uses unsafe code for DMA operations. The framebuffer
//! must be properly aligned in memory and the DMA configuration must match the
//! buffer layout.

use core::convert::Infallible;

use crate::{FrameBufferOperations, MutableFrameBuffer};
use bitfield::bitfield;
use embedded_dma::ReadBuffer;
use embedded_graphics::pixelcolor::RgbColor;
use embedded_graphics::prelude::Point;

use super::Color;
use super::FrameBuffer;

#[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;

#[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;

#[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;

/// Creates a pre-computed data template for a row with the specified address.
/// This template contains all the timing and control signals but no pixel data.
/// The address remains constant across all entries (including the latch pixel)
/// so that the address change is deferred to the first pixel of the next row.
#[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! {
    /// A 16-bit word representing the HUB75 control signals for a single pixel.
    ///
    /// This structure directly maps to the HUB75 connector signals:
    /// - RGB color data for two sub-pixels (color0 and color1)
    /// - Panel control signals (output enable, latch, address)
    /// - Dummy bits for timing alignment
    ///
    /// The bit layout matches the HUB75 connector signals:
    /// - Bit 15: Dummy bit 2
    /// - Bit 14: Blue channel for color1
    /// - Bit 13: Green channel for color1
    /// - Bit 12: Red channel for color1
    /// - Bit 11: Blue channel for color0
    /// - Bit 10: Green channel for color0
    /// - Bit 9: Red channel for color0
    /// - Bit 8: Output enable
    /// - Bit 7: Dummy bit 1
    /// - Bit 6: Dummy bit 0
    /// - Bit 5: Latch signal
    /// - Bits 4-0: Row address
    #[derive(Clone, Copy, Default, PartialEq)]
    #[repr(transparent)]
    struct Entry(u16);
    dummy2, set_dummy2: 15;
    blu2, set_blu2: 14;
    grn2, set_grn2: 13;
    red2, set_red2: 12;
    blu1, set_blu1: 11;
    grn1, set_grn1: 10;
    red1, set_red1: 9;
    output_enable, set_output_enable: 8;
    dummy1, set_dummy1: 7;
    dummy0, set_dummy0: 6;
    latch, set_latch: 5;
    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()
    }
}

#[cfg(feature = "defmt")]
impl defmt::Format for Entry {
    fn format(&self, f: defmt::Formatter) {
        defmt::write!(f, "Entry({=u16:#x})", self.0);
    }
}

impl Entry {
    const fn new() -> Self {
        #[cfg(feature = "invert-oe")]
        {
            Self(0b1_0000_0000)
        }
        #[cfg(not(feature = "invert-oe"))]
        {
            Self(0)
        }
    }

    // Optimized color bit manipulation constants and methods
    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);
    }
}

/// Represents a single row of pixels in the framebuffer.
///
/// Each row contains a fixed number of columns (`COLS`) and manages the timing
/// and control signals for the HUB75 panel. The row handles:
/// - Output enable timing to prevent ghosting
/// - Latch signal generation for row updates
/// - Row address management
/// - Color data for both sub-pixels
#[derive(Clone, Copy, PartialEq, Debug)]
#[repr(C)]
struct Row<const COLS: usize> {
    data: [Entry; COLS],
    gap: [Entry; INTER_ROW_BLANK],
}

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

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

impl<const COLS: usize> Row<COLS> {
    pub const fn new() -> Self {
        Self {
            data: [Entry::new(); COLS],
            gap: [Entry::new(); INTER_ROW_BLANK],
        }
    }

    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;
        }
    }

    /// Fast clear method that preserves timing/control bits while clearing pixel data.
    /// Uses bulk memory operations for maximum performance.
    #[inline]
    pub fn clear_colors(&mut self) {
        // Clear color bits while preserving timing and control bits
        const COLOR_CLEAR_MASK: u16 = !0b0111_1110_0000_0000; // Clear bits 9-14 (R1,G1,B1,R2,G2,B2)

        for entry in &mut self.data {
            entry.0 &= COLOR_CLEAR_MASK;
        }
    }

    #[inline]
    pub fn set_color0(&mut self, col: usize, r: bool, g: bool, b: bool) {
        let bits = (u8::from(b) << 2) | (u8::from(g) << 1) | u8::from(r);
        let col = map_index(col);
        self.data[col].set_color0_bits(bits);
    }

    #[inline]
    pub fn set_color1(&mut self, col: usize, r: bool, g: bool, b: bool) {
        let bits = (u8::from(b) << 2) | (u8::from(g) << 1) | u8::from(r);
        let col = map_index(col);
        self.data[col].set_color1_bits(bits);
    }
}

#[derive(Copy, Clone, Debug)]
#[repr(C)]
struct Frame<const ROWS: usize, const COLS: usize, const NROWS: usize> {
    rows: [Row<COLS>; NROWS],
}

impl<const ROWS: usize, const COLS: usize, const NROWS: usize> Frame<ROWS, COLS, NROWS> {
    pub const fn new() -> Self {
        Self {
            rows: [Row::new(); NROWS],
        }
    }

    pub const fn format(&mut self) {
        let mut addr = 0;
        while addr < NROWS {
            let prev_addr = if addr == 0 {
                NROWS as u8 - 1
            } else {
                addr as u8 - 1
            };
            self.rows[addr].format(prev_addr);
            addr += 1;
        }
    }

    /// Fast clear method that preserves timing/control bits while clearing pixel data.
    #[inline]
    pub fn clear_colors(&mut self) {
        for row in &mut self.rows {
            row.clear_colors();
        }
    }

    #[inline]
    pub fn set_pixel(&mut self, y: usize, x: usize, red: bool, green: bool, blue: bool) {
        let row = &mut self.rows[if y < NROWS { y } else { y - NROWS }];
        if y < NROWS {
            row.set_color0(x, red, green, blue);
        } else {
            row.set_color1(x, red, green, blue);
        }
    }
}

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

/// All BCM frames for this framebuffer, optionally followed by a tail word
/// (see the `tail-closes-latch` feature).
#[derive(Copy, Clone, Debug)]
#[repr(C)]
struct FrameData<const ROWS: usize, const COLS: usize, const NROWS: usize, const FRAME_COUNT: usize>
{
    frames: [Frame<ROWS, COLS, NROWS>; FRAME_COUNT],
    #[cfg(all(feature = "tail-closes-latch", feature = "esp32-ordering"))]
    padding: Entry,
    #[cfg(feature = "tail-closes-latch")]
    tail: Entry,
}

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

/// DMA-compatible framebuffer for HUB75 LED panels.
///
/// This is a framebuffer implementation that:
/// - Manages multiple frames for Binary Code Modulation (BCM)
/// - Provides DMA-compatible memory layout
/// - Implements the embedded-graphics `DrawTarget` trait
///
/// # Type Parameters
/// - `ROWS`: Total number of rows in the panel
/// - `COLS`: Number of columns in the panel
/// - `NROWS`: Number of rows per scan (typically half of ROWS)
/// - `BITS`: Color depth (1-8 bits)
/// - `FRAME_COUNT`: Number of frames used for Binary Code Modulation
///
/// # Helper Functions
/// Use these functions to compute the correct values:
/// - `esp_hub75::compute_frame_count(BITS)`: Computes the required number of
///   frames
/// - `esp_hub75::compute_rows(ROWS)`: Computes the number of rows per scan
///
/// # Memory Layout
/// The buffer is aligned to ensure efficient DMA transfers and contains:
/// - A 64-bit alignment field
/// - An array of frames, each containing the full panel data
#[derive(Copy, Clone)]
#[repr(C)]
pub struct DmaFrameBuffer<
    const ROWS: usize,
    const COLS: usize,
    const NROWS: usize,
    const BITS: u8,
    const FRAME_COUNT: usize,
> {
    _align: u64,
    data: FrameData<ROWS, COLS, NROWS, FRAME_COUNT>,
}

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

impl<
        const ROWS: usize,
        const COLS: usize,
        const NROWS: usize,
        const BITS: u8,
        const FRAME_COUNT: usize,
    > DmaFrameBuffer<ROWS, COLS, NROWS, BITS, FRAME_COUNT>
{
    /// Create a new, ready-to-use framebuffer.
    ///
    /// This creates a new framebuffer and automatically formats it with proper timing signals.
    /// The framebuffer is immediately ready for pixel operations and DMA transfers.
    ///
    /// # Panics
    ///
    /// Panics if `BITS` is greater than 8, as only 1-8 bit color depths are supported.
    ///
    /// # Example
    /// ```rust,no_run
    /// use hub75_framebuffer::{Color,plain::DmaFrameBuffer,compute_rows,compute_frame_count};
    ///
    /// const ROWS: usize = 32;
    /// const COLS: usize = 64;
    /// const BITS: u8 = 3; // Color depth (8 brightness levels, 7 frames)
    /// const NROWS: usize = compute_rows(ROWS); // Number of rows per scan
    /// const FRAME_COUNT: usize = compute_frame_count(BITS); // Number of frames for BCM
    ///
    /// let mut framebuffer = DmaFrameBuffer::<ROWS, COLS, NROWS, BITS, FRAME_COUNT>::new();
    /// // No need to call format() - framebuffer is ready to use!
    /// ```
    #[must_use]
    pub const fn new() -> Self {
        assert!(BITS <= 8);

        let mut instance = Self {
            _align: 0,
            data: FrameData::new(),
        };

        instance.format();
        instance
    }

    /// Returns the number of BCM chunks in this framebuffer (always 1 for
    /// single-plane framebuffers — the entire buffer is one contiguous chunk).
    #[must_use]
    pub const fn bcm_chunk_count() -> usize {
        1
    }

    /// Returns the byte size of one BCM chunk (for single-plane framebuffers
    /// this equals the total DMA buffer size including the tail word, since BCM
    /// weighting is baked in).
    #[must_use]
    pub const fn bcm_chunk_bytes() -> usize {
        core::mem::size_of::<FrameData<ROWS, COLS, NROWS, FRAME_COUNT>>()
    }

    /// Perform full formatting of the framebuffer with timing and control signals.
    ///
    /// This sets up all the timing and control signals needed for proper HUB75 operation.
    /// This is automatically called by `new()`, so you typically don't need to call this
    /// unless you want to completely reinitialize the framebuffer.
    ///
    /// # Example
    /// ```rust,no_run
    /// use hub75_framebuffer::{Color,plain::DmaFrameBuffer,compute_rows,compute_frame_count};
    ///
    /// const ROWS: usize = 32;
    /// const COLS: usize = 64;
    /// const BITS: u8 = 3; // Color depth (8 brightness levels, 7 frames)
    /// const NROWS: usize = compute_rows(ROWS); // Number of rows per scan
    /// const FRAME_COUNT: usize = compute_frame_count(BITS); // Number of frames for BCM
    ///
    /// let mut framebuffer = DmaFrameBuffer::<ROWS, COLS, NROWS, BITS, FRAME_COUNT>::new();
    /// framebuffer.format(); // Reinitialize if needed
    /// ```
    #[inline]
    pub const fn format(&mut self) {
        let mut i = 0;
        while i < FRAME_COUNT {
            self.data.frames[i].format();
            i += 1;
        }
        #[cfg(feature = "tail-closes-latch")]
        {
            self.data.tail.0 = 0x1f | OE_BLANK;
        }
        #[cfg(all(feature = "esp32-ordering", feature = "tail-closes-latch"))]
        {
            self.data.padding.0 = 0x1f | OE_BLANK;
        }
    }

    /// Fast erase operation that clears all pixel data while preserving timing signals.
    ///
    /// This is much faster than `format()` when you just want to clear the display
    /// since it preserves all the timing and control signals that are already set up.
    /// Use this for clearing between frames or when you want to start drawing fresh content.
    ///
    /// # Example
    /// ```rust,no_run
    /// use hub75_framebuffer::{Color,plain::DmaFrameBuffer,compute_rows,compute_frame_count};
    ///
    /// const ROWS: usize = 32;
    /// const COLS: usize = 64;
    /// const BITS: u8 = 3; // Color depth (8 brightness levels, 7 frames)
    /// const NROWS: usize = compute_rows(ROWS); // Number of rows per scan
    /// const FRAME_COUNT: usize = compute_frame_count(BITS); // Number of frames for BCM
    ///
    /// let mut framebuffer = DmaFrameBuffer::<ROWS, COLS, NROWS, BITS, FRAME_COUNT>::new();
    /// framebuffer.erase();
    /// ```
    #[inline]
    pub fn erase(&mut self) {
        for frame in &mut self.data.frames {
            frame.clear_colors();
        }
    }

    /// Set a pixel in the framebuffer.
    /// # Example
    /// ```rust,no_run
    /// use hub75_framebuffer::{Color,plain::DmaFrameBuffer,compute_rows,compute_frame_count};
    /// use embedded_graphics::prelude::*;
    ///
    /// const ROWS: usize = 32;
    /// const COLS: usize = 64;
    /// const BITS: u8 = 3; // Color depth (8 brightness levels, 7 frames)
    /// const NROWS: usize = compute_rows(ROWS); // Number of rows per scan
    /// const FRAME_COUNT: usize = compute_frame_count(BITS); // Number of frames for BCM
    ///
    /// let mut framebuffer = DmaFrameBuffer::<ROWS, COLS, NROWS, BITS, FRAME_COUNT>::new();
    /// framebuffer.set_pixel(Point::new(10, 10), Color::RED);
    /// ```
    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 frames_on(v: u8) -> usize {
        // v / brightness_step but the compiler resolves the shift at build-time
        (v as usize) >> (8 - BITS)
    }

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

        // Early exit for black pixels - common in UI backgrounds
        // Only enabled when skip-black-pixels feature is active
        #[cfg(feature = "skip-black-pixels")]
        if color == Color::BLACK {
            return;
        }

        // Pre-compute how many frames each channel should be on
        let red_frames = Self::frames_on(color.r());
        let green_frames = Self::frames_on(color.g());
        let blue_frames = Self::frames_on(color.b());

        // Set the pixel in all frames based on pre-computed frame counts
        for (frame_idx, frame) in self.data.frames.iter_mut().enumerate() {
            frame.set_pixel(
                y,
                x,
                frame_idx < red_frames,
                frame_idx < green_frames,
                frame_idx < blue_frames,
            );
        }
    }
}

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

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

impl<
        const ROWS: usize,
        const COLS: usize,
        const NROWS: usize,
        const BITS: u8,
        const FRAME_COUNT: usize,
    > embedded_graphics::prelude::OriginDimensions
    for DmaFrameBuffer<ROWS, COLS, NROWS, BITS, FRAME_COUNT>
{
    fn size(&self) -> embedded_graphics::prelude::Size {
        embedded_graphics::prelude::Size::new(COLS as u32, ROWS as u32)
    }
}

impl<
        const ROWS: usize,
        const COLS: usize,
        const NROWS: usize,
        const BITS: u8,
        const FRAME_COUNT: usize,
    > embedded_graphics::prelude::OriginDimensions
    for &mut DmaFrameBuffer<ROWS, COLS, NROWS, BITS, FRAME_COUNT>
{
    fn size(&self) -> embedded_graphics::prelude::Size {
        embedded_graphics::prelude::Size::new(COLS as u32, ROWS as u32)
    }
}

impl<
        const ROWS: usize,
        const COLS: usize,
        const NROWS: usize,
        const BITS: u8,
        const FRAME_COUNT: usize,
    > embedded_graphics::draw_target::DrawTarget
    for DmaFrameBuffer<ROWS, COLS, NROWS, BITS, FRAME_COUNT>
{
    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(())
    }
}

unsafe impl<
        const ROWS: usize,
        const COLS: usize,
        const NROWS: usize,
        const BITS: u8,
        const FRAME_COUNT: usize,
    > ReadBuffer for DmaFrameBuffer<ROWS, COLS, NROWS, BITS, FRAME_COUNT>
{
    type Word = u8;

    unsafe fn read_buffer(&self) -> (*const u8, usize) {
        let ptr = (&raw const self.data).cast::<u8>();
        let len = core::mem::size_of::<FrameData<ROWS, COLS, NROWS, FRAME_COUNT>>();
        (ptr, len)
    }
}

unsafe impl<
        const ROWS: usize,
        const COLS: usize,
        const NROWS: usize,
        const BITS: u8,
        const FRAME_COUNT: usize,
    > ReadBuffer for &mut DmaFrameBuffer<ROWS, COLS, NROWS, BITS, FRAME_COUNT>
{
    type Word = u8;

    unsafe fn read_buffer(&self) -> (*const u8, usize) {
        let ptr = (&raw const self.data).cast::<u8>();
        let len = core::mem::size_of::<FrameData<ROWS, COLS, NROWS, FRAME_COUNT>>();
        (ptr, len)
    }
}

impl<
        const ROWS: usize,
        const COLS: usize,
        const NROWS: usize,
        const BITS: u8,
        const FRAME_COUNT: usize,
    > core::fmt::Debug for DmaFrameBuffer<ROWS, COLS, NROWS, BITS, FRAME_COUNT>
{
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        let brightness_step = 1 << (8 - BITS);
        let size = core::mem::size_of::<FrameData<ROWS, COLS, NROWS, FRAME_COUNT>>();
        f.debug_struct("DmaFrameBuffer")
            .field("size", &size)
            .field("frame_count", &self.data.frames.len())
            .field("frame_size", &core::mem::size_of_val(&self.data.frames[0]))
            .field("brightness_step", &&brightness_step)
            .finish_non_exhaustive()
    }
}

#[cfg(feature = "defmt")]
impl<
        const ROWS: usize,
        const COLS: usize,
        const NROWS: usize,
        const BITS: u8,
        const FRAME_COUNT: usize,
    > defmt::Format for DmaFrameBuffer<ROWS, COLS, NROWS, BITS, FRAME_COUNT>
{
    fn format(&self, f: defmt::Formatter) {
        let brightness_step = 1 << (8 - BITS);
        defmt::write!(
            f,
            "DmaFrameBuffer<{}, {}, {}, {}, {}>",
            ROWS,
            COLS,
            NROWS,
            BITS,
            FRAME_COUNT
        );
        defmt::write!(
            f,
            " size: {}",
            core::mem::size_of::<FrameData<ROWS, COLS, NROWS, FRAME_COUNT>>()
        );
        defmt::write!(
            f,
            " frame_size: {}",
            core::mem::size_of_val(&self.data.frames[0])
        );
        defmt::write!(f, " brightness_step: {}", brightness_step);
    }
}

impl<
        const ROWS: usize,
        const COLS: usize,
        const NROWS: usize,
        const BITS: u8,
        const FRAME_COUNT: usize,
    > FrameBuffer for DmaFrameBuffer<ROWS, COLS, NROWS, BITS, FRAME_COUNT>
{
    type Word = u16;

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

    fn plane_ptr_len(&self, plane_idx: usize) -> (*const u8, usize) {
        assert!(plane_idx == 0, "plain DmaFrameBuffer has only 1 plane");
        let ptr = (&raw const self.data).cast::<u8>();
        let len = core::mem::size_of::<FrameData<ROWS, COLS, NROWS, FRAME_COUNT>>();
        (ptr, len)
    }
}

impl<
        const ROWS: usize,
        const COLS: usize,
        const NROWS: usize,
        const BITS: u8,
        const FRAME_COUNT: usize,
    > MutableFrameBuffer for DmaFrameBuffer<ROWS, COLS, NROWS, BITS, FRAME_COUNT>
{
}

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

    use std::format;
    use std::vec;

    use super::*;
    use crate::{FrameBuffer, WordSize};
    use embedded_graphics::pixelcolor::RgbColor;
    use embedded_graphics::prelude::*;
    use embedded_graphics::primitives::{Circle, PrimitiveStyle, Rectangle};

    const TEST_ROWS: usize = 32;
    const TEST_COLS: usize = 64;
    const TEST_NROWS: usize = TEST_ROWS / 2;
    const TEST_BITS: u8 = 3;
    const TEST_FRAME_COUNT: usize = (1 << TEST_BITS) - 1; // 7 frames for 3-bit depth

    type TestFrameBuffer =
        DmaFrameBuffer<TEST_ROWS, TEST_COLS, TEST_NROWS, TEST_BITS, TEST_FRAME_COUNT>;

    // Helper function to get mapped index for ESP32
    fn get_mapped_index(index: usize) -> usize {
        map_index(index)
    }

    #[test]
    fn test_entry_construction() {
        let entry = Entry::new();
        let expect_oe = cfg!(feature = "invert-oe");
        assert_eq!(entry.dummy2(), false);
        assert_eq!(entry.blu2(), false);
        assert_eq!(entry.grn2(), false);
        assert_eq!(entry.red2(), false);
        assert_eq!(entry.blu1(), false);
        assert_eq!(entry.grn1(), false);
        assert_eq!(entry.red1(), false);
        assert_eq!(entry.output_enable(), expect_oe);
        assert_eq!(entry.dummy1(), false);
        assert_eq!(entry.dummy0(), false);
        assert_eq!(entry.latch(), false);
        assert_eq!(entry.addr(), 0);
    }

    #[test]
    fn test_entry_setters() {
        let mut entry = Entry::new();

        entry.set_dummy2(true);
        assert_eq!(entry.dummy2(), true);
        assert_eq!(entry.0 & 0b1000000000000000, 0b1000000000000000);

        entry.set_blu2(true);
        assert_eq!(entry.blu2(), true);
        assert_eq!(entry.0 & 0b0100000000000000, 0b0100000000000000);

        entry.set_grn2(true);
        assert_eq!(entry.grn2(), true);
        assert_eq!(entry.0 & 0b0010000000000000, 0b0010000000000000);

        entry.set_red2(true);
        assert_eq!(entry.red2(), true);
        assert_eq!(entry.0 & 0b0001000000000000, 0b0001000000000000);

        entry.set_blu1(true);
        assert_eq!(entry.blu1(), true);
        assert_eq!(entry.0 & 0b0000100000000000, 0b0000100000000000);

        entry.set_grn1(true);
        assert_eq!(entry.grn1(), true);
        assert_eq!(entry.0 & 0b0000010000000000, 0b0000010000000000);

        entry.set_red1(true);
        assert_eq!(entry.red1(), true);
        assert_eq!(entry.0 & 0b0000001000000000, 0b0000001000000000);

        entry.set_output_enable(true);
        assert_eq!(entry.output_enable(), true);
        assert_eq!(entry.0 & 0b0000000100000000, 0b0000000100000000);

        entry.set_dummy1(true);
        assert_eq!(entry.dummy1(), true);
        assert_eq!(entry.0 & 0b0000000010000000, 0b0000000010000000);

        entry.set_dummy0(true);
        assert_eq!(entry.dummy0(), true);
        assert_eq!(entry.0 & 0b0000000001000000, 0b0000000001000000);

        entry.set_latch(true);
        assert_eq!(entry.latch(), true);
        assert_eq!(entry.0 & 0b0000000000100000, 0b0000000000100000);

        entry.set_addr(0b11111);
        assert_eq!(entry.addr(), 0b11111);
        assert_eq!(entry.0 & 0b0000000000011111, 0b0000000000011111);
    }

    #[test]
    fn test_entry_bit_isolation() {
        let mut entry = Entry::new();
        let expect_oe = cfg!(feature = "invert-oe");

        // Test that setting one field doesn't affect others
        entry.set_addr(0b11111);
        entry.set_latch(true);
        assert_eq!(entry.addr(), 0b11111);
        assert_eq!(entry.latch(), true);
        assert_eq!(entry.output_enable(), expect_oe);
        assert_eq!(entry.red1(), false);

        entry.set_red1(true);
        entry.set_grn2(true);
        assert_eq!(entry.addr(), 0b11111);
        assert_eq!(entry.latch(), true);
        assert_eq!(entry.red1(), true);
        assert_eq!(entry.grn2(), true);
        assert_eq!(entry.blu1(), false);
        assert_eq!(entry.red2(), false);
    }

    #[test]
    fn test_entry_set_color0() {
        let mut entry = Entry::new();

        let bits = (u8::from(true) << 2) | (u8::from(false) << 1) | u8::from(true); // b=1, g=0, r=1 = 0b101
        entry.set_color0_bits(bits);
        assert_eq!(entry.red1(), true);
        assert_eq!(entry.grn1(), false);
        assert_eq!(entry.blu1(), true);
        // Check that only the expected bits are set
        assert_eq!(entry.0 & 0b0000101000000000, 0b0000101000000000); // Red1 and Blue1 bits
    }

    #[test]
    fn test_entry_set_color1() {
        let mut entry = Entry::new();

        let bits = (u8::from(true) << 2) | (u8::from(true) << 1) | u8::from(false); // b=1, g=1, r=0 = 0b110
        entry.set_color1_bits(bits);
        assert_eq!(entry.red2(), false);
        assert_eq!(entry.grn2(), true);
        assert_eq!(entry.blu2(), true);
        // Check that only the expected bits are set
        assert_eq!(entry.0 & 0b0110000000000000, 0b0110000000000000); // Green2 and Blue2 bits
    }

    #[test]
    fn test_entry_debug_formatting() {
        let entry = Entry(0x1234);
        let debug_str = format!("{:?}", entry);
        assert_eq!(debug_str, "Entry(0x1234)");

        let entry = Entry(0xabcd);
        let debug_str = format!("{:?}", entry);
        assert_eq!(debug_str, "Entry(0xabcd)");
    }

    #[test]
    fn test_row_construction() {
        let row: Row<TEST_COLS> = Row::new();
        assert_eq!(row.data.len(), TEST_COLS);

        let expected = Entry::new().0;
        for entry in &row.data {
            assert_eq!(entry.0, expected);
        }
    }

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

        row.format(prev_addr);

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

        for (physical_i, entry) in row.data.iter().enumerate() {
            let logical_i = get_mapped_index(physical_i);

            assert_eq!(entry.addr(), prev_addr as u16);

            if logical_i == TEST_COLS - 1 {
                assert_eq!(entry.latch(), true);
                assert_eq!(entry.output_enable(), !oe_active);
            } else {
                assert_eq!(entry.latch(), false);
                if logical_i >= TRAIL_BLANK_DELAY && logical_i < TEST_COLS - LEAD_BLANK_DELAY - 1 {
                    assert_eq!(entry.output_enable(), oe_active);
                } else {
                    assert_eq!(entry.output_enable(), !oe_active);
                }
            }
        }
    }

    #[test]
    fn test_row_set_color0() {
        let mut row: Row<TEST_COLS> = Row::new();

        row.set_color0(0, true, false, true);

        let mapped_col_0 = get_mapped_index(0);
        assert_eq!(row.data[mapped_col_0].red1(), true);
        assert_eq!(row.data[mapped_col_0].grn1(), false);
        assert_eq!(row.data[mapped_col_0].blu1(), true);

        // Test another column
        row.set_color0(1, false, true, false);

        let mapped_col_1 = get_mapped_index(1);
        assert_eq!(row.data[mapped_col_1].red1(), false);
        assert_eq!(row.data[mapped_col_1].grn1(), true);
        assert_eq!(row.data[mapped_col_1].blu1(), false);
    }

    #[test]
    fn test_row_set_color1() {
        let mut row: Row<TEST_COLS> = Row::new();

        row.set_color1(0, true, true, false);

        let mapped_col_0 = get_mapped_index(0);
        assert_eq!(row.data[mapped_col_0].red2(), true);
        assert_eq!(row.data[mapped_col_0].grn2(), true);
        assert_eq!(row.data[mapped_col_0].blu2(), false);
    }

    #[test]
    fn test_row_default() {
        let row1: Row<TEST_COLS> = Row::new();
        let row2: Row<TEST_COLS> = Row::default();

        // Both should be equivalent
        assert_eq!(row1, row2);
        assert_eq!(row1.data.len(), row2.data.len());

        let expected = Entry::new().0;
        for (entry1, entry2) in row1.data.iter().zip(row2.data.iter()) {
            assert_eq!(entry1.0, entry2.0);
            assert_eq!(entry1.0, expected);
        }
    }

    #[test]
    fn test_frame_construction() {
        let frame: Frame<TEST_ROWS, TEST_COLS, TEST_NROWS> = Frame::new();
        assert_eq!(frame.rows.len(), TEST_NROWS);
    }

    #[test]
    fn test_frame_format() {
        let mut frame: Frame<TEST_ROWS, TEST_COLS, TEST_NROWS> = Frame::new();

        frame.format();

        for addr in 0..TEST_NROWS {
            let prev_addr = if addr == 0 { TEST_NROWS - 1 } else { addr - 1 };
            let row = &frame.rows[addr];

            let last_pixel_idx = get_mapped_index(TEST_COLS - 1);
            assert_eq!(row.data[last_pixel_idx].addr(), prev_addr as u16);
            assert_eq!(row.data[last_pixel_idx].latch(), true);

            let first_pixel_idx = get_mapped_index(0);
            assert_eq!(row.data[first_pixel_idx].addr(), prev_addr as u16);
            assert_eq!(row.data[first_pixel_idx].latch(), false);
        }
    }

    #[test]
    fn test_frame_set_pixel() {
        let mut frame: Frame<TEST_ROWS, TEST_COLS, TEST_NROWS> = Frame::new();

        // Test setting pixel in upper half (y < NROWS)
        frame.set_pixel(5, 10, true, false, true);

        let mapped_col_10 = get_mapped_index(10);
        assert_eq!(frame.rows[5].data[mapped_col_10].red1(), true);
        assert_eq!(frame.rows[5].data[mapped_col_10].grn1(), false);
        assert_eq!(frame.rows[5].data[mapped_col_10].blu1(), true);

        // Test setting pixel in lower half (y >= NROWS)
        frame.set_pixel(TEST_NROWS + 5, 15, false, true, false);

        let mapped_col_15 = get_mapped_index(15);
        assert_eq!(frame.rows[5].data[mapped_col_15].red2(), false);
        assert_eq!(frame.rows[5].data[mapped_col_15].grn2(), true);
        assert_eq!(frame.rows[5].data[mapped_col_15].blu2(), false);
    }

    #[test]
    fn test_frame_default() {
        let frame1: Frame<TEST_ROWS, TEST_COLS, TEST_NROWS> = Frame::new();
        let frame2: Frame<TEST_ROWS, TEST_COLS, TEST_NROWS> = Frame::default();

        // Both should be equivalent
        assert_eq!(frame1.rows.len(), frame2.rows.len());

        let expected = Entry::new().0;
        for (row1, row2) in frame1.rows.iter().zip(frame2.rows.iter()) {
            assert_eq!(row1, row2);

            for (entry1, entry2) in row1.data.iter().zip(row2.data.iter()) {
                assert_eq!(entry1.0, entry2.0);
                assert_eq!(entry1.0, expected);
            }
        }
    }

    #[test]
    fn test_dma_framebuffer_construction() {
        let fb = TestFrameBuffer::new();
        assert_eq!(fb.data.frames.len(), TEST_FRAME_COUNT);
        assert_eq!(fb._align, 0);
    }

    #[test]
    fn test_bcm_chunk_info() {
        let expected_size =
            core::mem::size_of::<FrameData<TEST_ROWS, TEST_COLS, TEST_NROWS, TEST_FRAME_COUNT>>();
        assert_eq!(TestFrameBuffer::bcm_chunk_bytes(), expected_size);
        assert_eq!(TestFrameBuffer::bcm_chunk_count(), 1);
    }

    #[test]
    fn test_dma_framebuffer_erase() {
        let fb = TestFrameBuffer::new();

        for frame in &fb.data.frames {
            for addr in 0..TEST_NROWS {
                let prev_addr = if addr == 0 { TEST_NROWS - 1 } else { addr - 1 };
                let row = &frame.rows[addr];

                let last_pixel_idx = get_mapped_index(TEST_COLS - 1);
                assert_eq!(row.data[last_pixel_idx].addr(), prev_addr as u16);
                assert_eq!(row.data[last_pixel_idx].latch(), true);

                let first_pixel_idx = get_mapped_index(0);
                assert_eq!(row.data[first_pixel_idx].addr(), prev_addr as u16);
                assert_eq!(row.data[first_pixel_idx].latch(), false);
            }
        }
    }

    #[test]
    fn test_dma_framebuffer_set_pixel_bounds() {
        let mut fb = TestFrameBuffer::new();

        // Test negative coordinates
        fb.set_pixel(Point::new(-1, 5), Color::RED);
        fb.set_pixel(Point::new(5, -1), Color::RED);

        // Test coordinates out of bounds (should not panic)
        fb.set_pixel(Point::new(TEST_COLS as i32, 5), Color::RED);
        fb.set_pixel(Point::new(5, TEST_ROWS as i32), Color::RED);
    }

    #[test]
    fn test_dma_framebuffer_set_pixel_internal() {
        let mut fb = TestFrameBuffer::new();

        let red_color = Color::RED;
        fb.set_pixel_internal(10, 5, red_color);

        // With 3-bit depth, brightness steps are 32 (256/8)
        // Frames represent thresholds: 32, 64, 96, 128, 160, 192, 224
        // Red value 255 should activate all frames
        for frame in &fb.data.frames {
            // Check upper half pixel
            let mapped_col_10 = get_mapped_index(10);
            assert_eq!(frame.rows[5].data[mapped_col_10].red1(), true);
            assert_eq!(frame.rows[5].data[mapped_col_10].grn1(), false);
            assert_eq!(frame.rows[5].data[mapped_col_10].blu1(), false);
        }
    }

    #[test]
    fn test_dma_framebuffer_brightness_modulation() {
        let mut fb = TestFrameBuffer::new();

        // Test with a medium brightness value
        let brightness_step = 1 << (8 - TEST_BITS); // 32 for 3-bit
        let test_brightness = brightness_step * 3; // 96
        let color = Color::from(embedded_graphics::pixelcolor::Rgb888::new(
            test_brightness,
            0,
            0,
        ));

        fb.set_pixel_internal(0, 0, color);

        // Should activate frames 0, 1, 2 (thresholds 32, 64, 96)
        // but not frames 3, 4, 5, 6 (thresholds 128, 160, 192, 224)
        for (frame_idx, frame) in fb.data.frames.iter().enumerate() {
            let frame_threshold = (frame_idx as u8 + 1) * brightness_step;
            let should_be_active = test_brightness >= frame_threshold;

            let mapped_col_0 = get_mapped_index(0);
            assert_eq!(frame.rows[0].data[mapped_col_0].red1(), should_be_active);
        }
    }

    #[test]
    fn test_origin_dimensions() {
        let fb = TestFrameBuffer::new();
        let size = fb.size();
        assert_eq!(size.width, TEST_COLS as u32);
        assert_eq!(size.height, TEST_ROWS as u32);

        // Test reference
        let size = (&fb).size();
        assert_eq!(size.width, TEST_COLS as u32);
        assert_eq!(size.height, TEST_ROWS as u32);

        // Test mutable reference
        let mut fb = TestFrameBuffer::new();
        let fb_ref = &mut fb;
        let size = fb_ref.size();
        assert_eq!(size.width, TEST_COLS as u32);
        assert_eq!(size.height, TEST_ROWS as u32);
    }

    #[test]
    fn test_draw_target() {
        let mut fb = TestFrameBuffer::new();

        let pixels = vec![
            embedded_graphics::Pixel(Point::new(0, 0), Color::RED),
            embedded_graphics::Pixel(Point::new(1, 1), Color::GREEN),
            embedded_graphics::Pixel(Point::new(2, 2), Color::BLUE),
        ];

        let result = fb.draw_iter(pixels);
        assert!(result.is_ok());

        // Test mutable reference
        let result = (&mut fb).draw_iter(vec![embedded_graphics::Pixel(
            Point::new(3, 3),
            Color::WHITE,
        )]);
        assert!(result.is_ok());
    }

    #[test]
    fn test_draw_iter_pixel_verification() {
        let mut fb = TestFrameBuffer::new();

        // Create test pixels with specific colors and positions
        let pixels = vec![
            // Upper half pixels (y < NROWS) - should set color0
            embedded_graphics::Pixel(Point::new(5, 2), Color::RED), // (5, 2) -> red
            embedded_graphics::Pixel(Point::new(10, 5), Color::GREEN), // (10, 5) -> green
            embedded_graphics::Pixel(Point::new(15, 8), Color::BLUE), // (15, 8) -> blue
            embedded_graphics::Pixel(Point::new(20, 10), Color::WHITE), // (20, 10) -> white
            // Lower half pixels (y >= NROWS) - should set color1
            embedded_graphics::Pixel(Point::new(25, (TEST_NROWS + 3) as i32), Color::RED), // (25, 19) -> red
            embedded_graphics::Pixel(Point::new(30, (TEST_NROWS + 7) as i32), Color::GREEN), // (30, 23) -> green
            embedded_graphics::Pixel(Point::new(35, (TEST_NROWS + 12) as i32), Color::BLUE), // (35, 28) -> blue
            // Edge case: black pixel (should not be visible in first frame)
            embedded_graphics::Pixel(Point::new(40, 1), Color::BLACK), // (40, 1) -> black
        ];

        let result = fb.draw_iter(pixels);
        assert!(result.is_ok());

        // Check the first frame only
        let first_frame = &fb.data.frames[0];
        let brightness_step = 1 << (8 - TEST_BITS); // 32 for 3-bit
        let first_frame_threshold = brightness_step; // 32

        // Test upper half pixels (color0)
        // Red pixel at (5, 2) - should be red in first frame
        let col_idx = get_mapped_index(5);
        assert_eq!(
            first_frame.rows[2].data[col_idx].red1(),
            Color::RED.r() >= first_frame_threshold
        );
        assert_eq!(
            first_frame.rows[2].data[col_idx].grn1(),
            Color::RED.g() >= first_frame_threshold
        );
        assert_eq!(
            first_frame.rows[2].data[col_idx].blu1(),
            Color::RED.b() >= first_frame_threshold
        );

        // Green pixel at (10, 5) - should be green in first frame
        let col_idx = get_mapped_index(10);
        assert_eq!(
            first_frame.rows[5].data[col_idx].red1(),
            Color::GREEN.r() >= first_frame_threshold
        );
        assert_eq!(
            first_frame.rows[5].data[col_idx].grn1(),
            Color::GREEN.g() >= first_frame_threshold
        );
        assert_eq!(
            first_frame.rows[5].data[col_idx].blu1(),
            Color::GREEN.b() >= first_frame_threshold
        );

        // Blue pixel at (15, 8) - should be blue in first frame
        let col_idx = get_mapped_index(15);
        assert_eq!(
            first_frame.rows[8].data[col_idx].red1(),
            Color::BLUE.r() >= first_frame_threshold
        );
        assert_eq!(
            first_frame.rows[8].data[col_idx].grn1(),
            Color::BLUE.g() >= first_frame_threshold
        );
        assert_eq!(
            first_frame.rows[8].data[col_idx].blu1(),
            Color::BLUE.b() >= first_frame_threshold
        );

        // White pixel at (20, 10) - should be white in first frame
        let col_idx = get_mapped_index(20);
        assert_eq!(
            first_frame.rows[10].data[col_idx].red1(),
            Color::WHITE.r() >= first_frame_threshold
        );
        assert_eq!(
            first_frame.rows[10].data[col_idx].grn1(),
            Color::WHITE.g() >= first_frame_threshold
        );
        assert_eq!(
            first_frame.rows[10].data[col_idx].blu1(),
            Color::WHITE.b() >= first_frame_threshold
        );

        // Test lower half pixels (color1)
        // Red pixel at (25, TEST_NROWS + 3) -> row 3, color1
        let col_idx = get_mapped_index(25);
        assert_eq!(
            first_frame.rows[3].data[col_idx].red2(),
            Color::RED.r() >= first_frame_threshold
        );
        assert_eq!(
            first_frame.rows[3].data[col_idx].grn2(),
            Color::RED.g() >= first_frame_threshold
        );
        assert_eq!(
            first_frame.rows[3].data[col_idx].blu2(),
            Color::RED.b() >= first_frame_threshold
        );

        // Green pixel at (30, TEST_NROWS + 7) -> row 7, color1
        let col_idx = get_mapped_index(30);
        assert_eq!(
            first_frame.rows[7].data[col_idx].red2(),
            Color::GREEN.r() >= first_frame_threshold
        );
        assert_eq!(
            first_frame.rows[7].data[col_idx].grn2(),
            Color::GREEN.g() >= first_frame_threshold
        );
        assert_eq!(
            first_frame.rows[7].data[col_idx].blu2(),
            Color::GREEN.b() >= first_frame_threshold
        );

        // Blue pixel at (35, TEST_NROWS + 12) -> row 12, color1
        let col_idx = get_mapped_index(35);
        assert_eq!(
            first_frame.rows[12].data[col_idx].red2(),
            Color::BLUE.r() >= first_frame_threshold
        );
        assert_eq!(
            first_frame.rows[12].data[col_idx].grn2(),
            Color::BLUE.g() >= first_frame_threshold
        );
        assert_eq!(
            first_frame.rows[12].data[col_idx].blu2(),
            Color::BLUE.b() >= first_frame_threshold
        );

        // Test black pixel - should not be visible in any frame
        let col_idx = get_mapped_index(40);
        assert_eq!(first_frame.rows[1].data[col_idx].red1(), false);
        assert_eq!(first_frame.rows[1].data[col_idx].grn1(), false);
        assert_eq!(first_frame.rows[1].data[col_idx].blu1(), false);
    }

    #[test]
    fn test_embedded_graphics_integration() {
        let mut fb = TestFrameBuffer::new();

        // Draw a rectangle
        let result = Rectangle::new(Point::new(5, 5), Size::new(10, 8))
            .into_styled(PrimitiveStyle::with_fill(Color::RED))
            .draw(&mut fb);
        assert!(result.is_ok());

        // Draw a circle
        let result = Circle::new(Point::new(30, 15), 8)
            .into_styled(PrimitiveStyle::with_fill(Color::BLUE))
            .draw(&mut fb);
        assert!(result.is_ok());
    }

    #[test]
    #[cfg(feature = "skip-black-pixels")]
    fn test_skip_black_pixels_enabled() {
        let mut fb = TestFrameBuffer::new();

        // Set a red pixel first
        fb.set_pixel_internal(10, 5, Color::RED);

        // Verify it's red in the first frame
        let mapped_col_10 = get_mapped_index(10);
        assert_eq!(fb.data.frames[0].rows[5].data[mapped_col_10].red1(), true);
        assert_eq!(fb.data.frames[0].rows[5].data[mapped_col_10].grn1(), false);
        assert_eq!(fb.data.frames[0].rows[5].data[mapped_col_10].blu1(), false);

        // Now set it to black - with skip-black-pixels enabled, this should be ignored
        fb.set_pixel_internal(10, 5, Color::BLACK);

        // The pixel should still be red (black write was skipped)
        assert_eq!(fb.data.frames[0].rows[5].data[mapped_col_10].red1(), true);
        assert_eq!(fb.data.frames[0].rows[5].data[mapped_col_10].grn1(), false);
        assert_eq!(fb.data.frames[0].rows[5].data[mapped_col_10].blu1(), false);
    }

    #[test]
    #[cfg(not(feature = "skip-black-pixels"))]
    fn test_skip_black_pixels_disabled() {
        let mut fb = TestFrameBuffer::new();

        // Set a red pixel first
        fb.set_pixel_internal(10, 5, Color::RED);

        // Verify it's red in the first frame
        let mapped_col_10 = get_mapped_index(10);
        assert_eq!(fb.data.frames[0].rows[5].data[mapped_col_10].red1(), true);
        assert_eq!(fb.data.frames[0].rows[5].data[mapped_col_10].grn1(), false);
        assert_eq!(fb.data.frames[0].rows[5].data[mapped_col_10].blu1(), false);

        // Now set it to black - with skip-black-pixels disabled, this should overwrite
        fb.set_pixel_internal(10, 5, Color::BLACK);

        // The pixel should now be black (all bits false)
        assert_eq!(fb.data.frames[0].rows[5].data[mapped_col_10].red1(), false);
        assert_eq!(fb.data.frames[0].rows[5].data[mapped_col_10].grn1(), false);
        assert_eq!(fb.data.frames[0].rows[5].data[mapped_col_10].blu1(), false);
    }

    #[test]
    fn test_bcm_frame_overwrite() {
        let mut fb = TestFrameBuffer::new();

        // First write a white pixel (255, 255, 255)
        fb.set_pixel_internal(10, 5, Color::WHITE);

        let mapped_col_10 = get_mapped_index(10);

        // Verify white pixel is lit in all frames (255 >= all thresholds)
        for frame in fb.data.frames.iter() {
            // White (255) should be active in all frames since it's >= all thresholds
            assert_eq!(frame.rows[5].data[mapped_col_10].red1(), true);
            assert_eq!(frame.rows[5].data[mapped_col_10].grn1(), true);
            assert_eq!(frame.rows[5].data[mapped_col_10].blu1(), true);
        }

        // Now overwrite with 50% white (128, 128, 128)
        let half_white = Color::from(embedded_graphics::pixelcolor::Rgb888::new(128, 128, 128));
        fb.set_pixel_internal(10, 5, half_white);

        // Verify only the correct frames are lit for 50% white
        // With 3-bit depth: thresholds are 32, 64, 96, 128, 160, 192, 224
        // 128 should activate frames 0, 1, 2, 3 (thresholds 32, 64, 96, 128)
        // but not frames 4, 5, 6 (thresholds 160, 192, 224)
        let brightness_step = 1 << (8 - TEST_BITS); // 32 for 3-bit
        for (frame_idx, frame) in fb.data.frames.iter().enumerate() {
            let frame_threshold = (frame_idx as u8 + 1) * brightness_step;
            let should_be_active = 128 >= frame_threshold;

            assert_eq!(frame.rows[5].data[mapped_col_10].red1(), should_be_active);
            assert_eq!(frame.rows[5].data[mapped_col_10].grn1(), should_be_active);
            assert_eq!(frame.rows[5].data[mapped_col_10].blu1(), should_be_active);
        }

        // Specifically verify the expected pattern for 3-bit depth
        // Frames 0-3 should be active (thresholds 32, 64, 96, 128)
        for frame_idx in 0..4 {
            assert_eq!(
                fb.data.frames[frame_idx].rows[5].data[mapped_col_10].red1(),
                true
            );
        }
        // Frames 4-6 should be inactive (thresholds 160, 192, 224)
        for frame_idx in 4..TEST_FRAME_COUNT {
            assert_eq!(
                fb.data.frames[frame_idx].rows[5].data[mapped_col_10].red1(),
                false
            );
        }
    }

    #[test]
    fn test_read_buffer_implementation() {
        // Test owned implementation - explicitly move the framebuffer to ensure we're testing the owned impl
        let fb = TestFrameBuffer::new();
        let expected_size =
            core::mem::size_of::<FrameData<TEST_ROWS, TEST_COLS, TEST_NROWS, TEST_FRAME_COUNT>>();

        // Test owned ReadBuffer implementation by calling ReadBuffer::read_buffer explicitly
        unsafe {
            let (ptr, len) = <TestFrameBuffer as ReadBuffer>::read_buffer(&fb);
            assert!(!ptr.is_null());
            assert_eq!(len, expected_size);
        }

        // Test direct method call on owned value
        unsafe {
            let (ptr, len) = fb.read_buffer();
            assert!(!ptr.is_null());
            assert_eq!(len, expected_size);
        }

        // Test reference implementation
        let fb = TestFrameBuffer::new();
        let fb_ref = &fb;
        unsafe {
            let (ptr, len) = fb_ref.read_buffer();
            assert!(!ptr.is_null());
            assert_eq!(
                len,
                core::mem::size_of::<FrameData<TEST_ROWS, TEST_COLS, TEST_NROWS, TEST_FRAME_COUNT>>(
                )
            );
        }

        // Test mutable reference implementation
        let mut fb = TestFrameBuffer::new();
        let fb_ref = &mut fb;
        unsafe {
            let (ptr, len) = fb_ref.read_buffer();
            assert!(!ptr.is_null());
            assert_eq!(
                len,
                core::mem::size_of::<FrameData<TEST_ROWS, TEST_COLS, TEST_NROWS, TEST_FRAME_COUNT>>(
                )
            );
        }
    }

    #[test]
    fn test_read_buffer_owned_implementation() {
        // This test specifically ensures the owned ReadBuffer implementation is tested
        // by consuming the framebuffer and testing the pointer validity
        fn test_owned_read_buffer(fb: TestFrameBuffer) -> (bool, usize) {
            unsafe {
                let (ptr, len) = fb.read_buffer();
                (!ptr.is_null(), len)
            }
        }

        let fb = TestFrameBuffer::new();
        let expected_len =
            core::mem::size_of::<FrameData<TEST_ROWS, TEST_COLS, TEST_NROWS, TEST_FRAME_COUNT>>();

        let (ptr_valid, actual_len) = test_owned_read_buffer(fb);
        assert!(ptr_valid);
        assert_eq!(actual_len, expected_len);
    }

    #[test]
    fn test_framebuffer_trait() {
        let fb = TestFrameBuffer::new();
        assert_eq!(fb.get_word_size(), WordSize::Sixteen);

        let fb_ref = &fb;
        assert_eq!(fb_ref.get_word_size(), WordSize::Sixteen);

        let mut fb = TestFrameBuffer::new();
        let fb_ref = &mut fb;
        assert_eq!(fb_ref.get_word_size(), WordSize::Sixteen);
    }

    #[test]
    fn test_debug_formatting() {
        let fb = TestFrameBuffer::new();
        let debug_string = format!("{:?}", fb);
        assert!(debug_string.contains("DmaFrameBuffer"));
        assert!(debug_string.contains("frame_count"));
        assert!(debug_string.contains("frame_size"));
        assert!(debug_string.contains("brightness_step"));
    }

    #[test]
    fn test_default_implementation() {
        let fb1 = TestFrameBuffer::new();
        let fb2 = TestFrameBuffer::default();

        // Both should be equivalent in size, but may differ in content since new() calls format()
        assert_eq!(fb1.data.frames.len(), fb2.data.frames.len());
        assert_eq!(fb1._align, fb2._align);
    }

    #[test]
    fn test_memory_alignment() {
        let fb = TestFrameBuffer::new();
        let ptr = &fb as *const _ as usize;

        // Should be aligned to 64-bit boundary due to the _align field
        assert_eq!(ptr % 8, 0);
    }

    #[test]
    fn test_color_values() {
        let mut fb = TestFrameBuffer::new();

        // Test different color values
        let colors = [
            (Color::RED, (255, 0, 0)),
            (Color::GREEN, (0, 255, 0)),
            (Color::BLUE, (0, 0, 255)),
            (Color::WHITE, (255, 255, 255)),
            (Color::BLACK, (0, 0, 0)),
        ];

        for (i, (color, (r, g, b))) in colors.iter().enumerate() {
            fb.set_pixel(Point::new(i as i32, 0), *color);
            assert_eq!(color.r(), *r);
            assert_eq!(color.g(), *g);
            assert_eq!(color.b(), *b);
        }
    }

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

        row.format(prev_addr);

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

        // Trail blank: indices 0..TRAIL_BLANK_DELAY-1 (DMA start = physical right edge)
        let trail_blank_idx = get_mapped_index(TRAIL_BLANK_DELAY - 1);
        assert_eq!(row.data[trail_blank_idx].output_enable(), !oe_active);

        let after_trail_idx = get_mapped_index(TRAIL_BLANK_DELAY);
        assert_eq!(row.data[after_trail_idx].output_enable(), oe_active);

        // Lead blank: indices before latch (DMA end = physical left edge)
        let before_lead_idx = get_mapped_index(TEST_COLS - LEAD_BLANK_DELAY - 2);
        assert_eq!(row.data[before_lead_idx].output_enable(), oe_active);

        let lead_blank_idx = get_mapped_index(TEST_COLS - LEAD_BLANK_DELAY - 1);
        assert_eq!(row.data[lead_blank_idx].output_enable(), !oe_active);
    }

    #[test]
    fn test_esp32_mapping() {
        // Test the ESP32-specific index mapping
        #[cfg(feature = "esp32-ordering")]
        {
            assert_eq!(map_index(0), 1);
            assert_eq!(map_index(1), 0);
            assert_eq!(map_index(2), 3);
            assert_eq!(map_index(3), 2);
            assert_eq!(map_index(4), 5);
            assert_eq!(map_index(5), 4);
        }
        #[cfg(not(feature = "esp32-ordering"))]
        {
            assert_eq!(map_index(0), 0);
            assert_eq!(map_index(1), 1);
            assert_eq!(map_index(2), 2);
            assert_eq!(map_index(3), 3);
        }
    }

    #[test]
    fn test_bits_assertion() {
        // Test that BITS <= 8 assertion is enforced at compile time
        // This test mainly documents the constraint
        assert!(TEST_BITS <= 8);
    }

    #[test]
    fn test_fast_clear_method() {
        let mut fb = TestFrameBuffer::new();

        // Set some pixels
        fb.set_pixel_internal(10, 5, Color::RED);
        fb.set_pixel_internal(20, 10, Color::GREEN);

        // Verify pixels are set
        let mapped_col_10 = get_mapped_index(10);
        assert_eq!(fb.data.frames[0].rows[5].data[mapped_col_10].red1(), true);

        // Clear using fast method
        fb.erase();

        // Verify pixels are cleared but timing signals remain
        assert_eq!(fb.data.frames[0].rows[5].data[mapped_col_10].red1(), false);
        assert_eq!(fb.data.frames[0].rows[5].data[mapped_col_10].grn1(), false);
        assert_eq!(fb.data.frames[0].rows[5].data[mapped_col_10].blu1(), false);

        // Verify timing signals are still present (check last pixel has latch)
        let last_col = get_mapped_index(TEST_COLS - 1);
        assert_eq!(fb.data.frames[0].rows[5].data[last_col].latch(), true);
    }

    // Remove the old `test_draw_char_bottom_right` and replace with a helper + combined test.

    // Constants for FONT_6X10 glyph size
    const CHAR_W: i32 = 6;
    const CHAR_H: i32 = 10;

    /// Draws glyph 'A' at `origin` and validates framebuffer pixels against a reference.
    fn verify_glyph_at(fb: &mut TestFrameBuffer, origin: Point) {
        use embedded_graphics::mock_display::MockDisplay;
        use embedded_graphics::mono_font::ascii::FONT_6X10;
        use embedded_graphics::mono_font::MonoTextStyle;
        use embedded_graphics::text::{Baseline, Text};

        // Draw the glyph
        let style = MonoTextStyle::new(&FONT_6X10, Color::WHITE);
        Text::with_baseline("A", origin, style, Baseline::Top)
            .draw(fb)
            .unwrap();

        // Reference glyph at (0,0)
        let mut reference: MockDisplay<Color> = MockDisplay::new();
        Text::with_baseline("A", Point::zero(), style, Baseline::Top)
            .draw(&mut reference)
            .unwrap();

        for dy in 0..CHAR_H {
            for dx in 0..CHAR_W {
                let expected_on = reference
                    .get_pixel(Point::new(dx, dy))
                    .unwrap_or(Color::BLACK)
                    != Color::BLACK;

                let gx = (origin.x + dx) as usize;
                let gy = (origin.y + dy) as usize;

                // we have computed the origin to be within the panel, so we don't need to check for bounds
                // if gx >= TEST_COLS || gy >= TEST_ROWS {
                //     continue;
                // }

                // Fetch Entry from frame 0
                let frame0 = &fb.data.frames[0];
                let e = if gy < TEST_NROWS {
                    &frame0.rows[gy].data[get_mapped_index(gx)]
                } else {
                    &frame0.rows[gy - TEST_NROWS].data[get_mapped_index(gx)]
                };

                let (r, g, b) = if gy >= TEST_NROWS {
                    (e.red2(), e.grn2(), e.blu2())
                } else {
                    (e.red1(), e.grn1(), e.blu1())
                };

                if expected_on {
                    assert!(r && g && b,);
                } else {
                    assert!(!r && !g && !b);
                }
            }
        }
    }

    #[test]
    fn test_draw_char_corners() {
        let upper_left = Point::new(0, 0);
        let lower_right = Point::new(TEST_COLS as i32 - CHAR_W, TEST_ROWS as i32 - CHAR_H);

        let mut fb = TestFrameBuffer::new();

        verify_glyph_at(&mut fb, upper_left);
        verify_glyph_at(&mut fb, lower_right);
    }

    #[test]
    fn test_framebuffer_operations_trait_erase() {
        let mut fb = TestFrameBuffer::new();

        // Set pixels so erase has work to do
        fb.set_pixel_internal(10, 5, Color::RED);
        fb.set_pixel_internal(20, 10, Color::GREEN);

        // Explicitly call trait method to hit the FrameBufferOperations impl
        <TestFrameBuffer as FrameBufferOperations>::erase(&mut fb);

        // Verify colors cleared on frame 0
        let mc10 = get_mapped_index(10);
        let mc20 = get_mapped_index(20);
        assert_eq!(fb.data.frames[0].rows[5].data[mc10].red1(), false);
        assert_eq!(fb.data.frames[0].rows[10].data[mc20].grn1(), false);

        // Timing signals preserved: last pixel should have latch
        let last_col = get_mapped_index(TEST_COLS - 1);
        assert!(fb.data.frames[0].rows[0].data[last_col].latch());
    }

    #[test]
    fn test_framebuffer_operations_trait_set_pixel() {
        let mut fb = TestFrameBuffer::new();

        // Explicitly call trait method to hit the FrameBufferOperations impl
        <TestFrameBuffer as FrameBufferOperations>::set_pixel(
            &mut fb,
            Point::new(8, 3),
            Color::BLUE,
        );

        let idx = get_mapped_index(8);
        assert_eq!(fb.data.frames[0].rows[3].data[idx].blu1(), true);
        assert_eq!(fb.data.frames[0].rows[3].data[idx].red1(), false);
        assert_eq!(fb.data.frames[0].rows[3].data[idx].grn1(), false);
    }

    #[test]
    fn test_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 test_make_data_template_oe_polarity() {
        let mut row = Row::<TEST_COLS>::new();
        row.format(4);

        let active_idx = get_mapped_index(TRAIL_BLANK_DELAY);
        let blank_idx = get_mapped_index(TEST_COLS - LEAD_BLANK_DELAY - 1);
        let latch_idx = get_mapped_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: TestFrameBuffer = TestFrameBuffer::new();

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

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

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

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