use crate::buffer::Cell;
use crate::canvas::Canvas;
use crossterm::style::{self, Attribute, Color};
pub const DOTS_X: usize = 2;
pub const DOTS_Y: usize = 4;
pub const DOTS_PER_CELL: usize = DOTS_X * DOTS_Y;
const BRAILLE_BASE: u32 = 0x2800;
#[derive(Clone)]
pub struct BrailleGrid {
width: usize,
height: usize,
dots: Vec<u8>,
}
impl BrailleGrid {
pub fn new(width: usize, height: usize) -> Self {
let (width, height) = (width.max(1), height.max(1));
Self {
width,
height,
dots: vec![0; width * height],
}
}
pub fn width(&self) -> usize {
self.width
}
pub fn height(&self) -> usize {
self.height
}
pub fn dot_width(&self) -> usize {
self.width * DOTS_X
}
pub fn dot_height(&self) -> usize {
self.height * DOTS_Y
}
pub fn clear(&mut self) {
self.dots.fill(0);
}
pub fn resize(&mut self, width: usize, height: usize) {
let (width, height) = (width.max(1), height.max(1));
if (width, height) == (self.width, self.height) {
return;
}
*self = Self::new(width, height);
}
#[inline]
pub fn set_dot(&mut self, dot_x: usize, dot_y: usize, raised: bool) {
let Some(index) = self.cell_index(dot_x, dot_y) else {
return;
};
let bit = 1u8 << Self::dot_index(dot_x, dot_y);
if raised {
self.dots[index] |= bit;
} else {
self.dots[index] &= !bit;
}
}
#[inline]
pub fn raise_dot(&mut self, dot_x: usize, dot_y: usize) {
self.set_dot(dot_x, dot_y, true);
}
#[inline]
pub fn lower_dot(&mut self, dot_x: usize, dot_y: usize) {
self.set_dot(dot_x, dot_y, false);
}
#[inline]
pub fn dot(&self, dot_x: usize, dot_y: usize) -> bool {
let Some(index) = self.cell_index(dot_x, dot_y) else {
return false;
};
self.dots[index] & (1u8 << Self::dot_index(dot_x, dot_y)) != 0
}
pub fn cell_char(&self, cell_x: usize, cell_y: usize) -> char {
if cell_x >= self.width || cell_y >= self.height {
return ' ';
}
let bits = self.dots[cell_y * self.width + cell_x];
if bits == 0 {
return ' ';
}
char::from_u32(BRAILLE_BASE + bits as u32).unwrap_or('?')
}
pub fn cell_bits(&self, cell_x: usize, cell_y: usize) -> u8 {
if cell_x >= self.width || cell_y >= self.height {
return 0;
}
self.dots[cell_y * self.width + cell_x]
}
pub fn for_each_dot(&self, mut f: impl FnMut(usize, usize, bool)) {
for cell_y in 0..self.height {
for cell_x in 0..self.width {
let bits = self.dots[cell_y * self.width + cell_x];
for sub in 0..DOTS_PER_CELL {
let (dx, dy) = Self::dot_position(sub);
f(
cell_x * DOTS_X + dx,
cell_y * DOTS_Y + dy,
bits & (1u8 << sub) != 0,
);
}
}
}
}
pub fn write_to(&self, canvas: &mut Canvas, color: Color, attr: Attribute) {
for cell_y in 0..self.height.min(canvas.height()) {
for cell_x in 0..self.width.min(canvas.width()) {
let symbol = self.cell_char(cell_x, cell_y);
canvas.set(cell_x, cell_y, Cell::new(symbol, color, attr));
}
}
}
pub fn overlay_onto(&self, canvas: &mut Canvas, color: Color, attr: Attribute) {
for cell_y in 0..self.height.min(canvas.height()) {
for cell_x in 0..self.width.min(canvas.width()) {
let symbol = self.cell_char(cell_x, cell_y);
if symbol == ' ' {
continue;
}
canvas.set(cell_x, cell_y, Cell::new(symbol, color, attr));
}
}
}
pub fn draw_field(
&mut self,
values: &[f32],
threshold: f32,
spread: f32,
dither: super::dither::Dither,
) {
let (dw, dh) = (self.dot_width(), self.dot_height());
for dot_y in 0..dh {
for dot_x in 0..dw {
let index = dot_y * dw + dot_x;
let value = values.get(index).copied().unwrap_or(0.0);
let jitter = (dither.at(dot_x, dot_y) - 0.5) * spread;
self.set_dot(dot_x, dot_y, value > threshold + jitter);
}
}
}
#[inline]
fn cell_index(&self, dot_x: usize, dot_y: usize) -> Option<usize> {
if dot_x >= self.dot_width() || dot_y >= self.dot_height() {
return None;
}
let cell_x = dot_x / DOTS_X;
let cell_y = dot_y / DOTS_Y;
Some(cell_y * self.width + cell_x)
}
#[inline]
fn dot_index(dot_x: usize, dot_y: usize) -> usize {
let (dx, dy) = (dot_x % DOTS_X, dot_y % DOTS_Y);
let main_rows = DOTS_Y - 1;
if dy == main_rows {
DOTS_X * main_rows + dx
} else {
dy + main_rows * dx
}
}
#[inline]
fn dot_position(index: usize) -> (usize, usize) {
let main_rows = DOTS_Y - 1;
if index < DOTS_X * main_rows {
(index / main_rows, index % main_rows)
} else {
(index - DOTS_X * main_rows, main_rows)
}
}
}
#[inline]
pub fn braille_bit(dot_x: usize, dot_y: usize) -> u8 {
1u8 << BrailleGrid::dot_index(dot_x, dot_y)
}
#[inline]
pub fn braille_dot_position(index: usize) -> (usize, usize) {
BrailleGrid::dot_position(index)
}
pub fn default_color() -> Color {
style::Color::White
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn a_blank_grid_is_spaces() {
let grid = BrailleGrid::new(4, 3);
for y in 0..3 {
for x in 0..4 {
assert_eq!(grid.cell_char(x, y), ' ');
}
}
}
#[test]
fn dot_dimensions_are_eight_times_the_cells() {
let grid = BrailleGrid::new(10, 5);
assert_eq!(grid.dot_width(), 20);
assert_eq!(grid.dot_height(), 20);
assert_eq!(grid.dot_width() * grid.dot_height(), 10 * 5 * 8);
}
#[test]
fn the_first_dot_is_the_top_left_of_the_pattern() {
let mut grid = BrailleGrid::new(1, 1);
grid.raise_dot(0, 0);
assert_eq!(grid.cell_char(0, 0), '\u{2801}');
let mut grid = BrailleGrid::new(1, 1);
grid.raise_dot(1, 3);
assert_eq!(grid.cell_char(0, 0), '\u{2880}');
}
#[test]
fn every_dot_maps_to_its_own_unicode_pattern() {
for sub in 0..DOTS_PER_CELL {
let (dx, dy) = BrailleGrid::dot_position(sub);
let mut grid = BrailleGrid::new(1, 1);
grid.raise_dot(dx, dy);
let expected = char::from_u32(0x2800 + (1u32 << sub)).unwrap();
assert_eq!(
grid.cell_char(0, 0),
expected,
"dot {sub} at ({dx},{dy}) encoded wrongly"
);
}
}
#[test]
fn a_dot_column_is_the_codepoint_for_that_column() {
let mut grid = BrailleGrid::new(1, 1);
grid.raise_dot(0, 0);
grid.raise_dot(0, 1);
grid.raise_dot(0, 2);
assert_eq!(
grid.cell_char(0, 0),
'\u{2807}',
"the left column is not DOTS-123"
);
let mut grid = BrailleGrid::new(1, 1);
grid.raise_dot(1, 0);
grid.raise_dot(1, 1);
grid.raise_dot(1, 2);
assert_eq!(
grid.cell_char(0, 0),
'\u{2838}',
"the right column is not DOTS-456"
);
}
#[test]
fn a_horizontal_run_is_the_two_top_dots() {
let mut grid = BrailleGrid::new(1, 1);
grid.raise_dot(0, 0);
grid.raise_dot(1, 0);
assert_eq!(
grid.cell_char(0, 0),
'\u{2809}',
"the top row is not DOTS-14"
);
let mut grid = BrailleGrid::new(1, 1);
grid.raise_dot(0, 1);
grid.raise_dot(1, 1);
assert_eq!(
grid.cell_char(0, 0),
'\u{2812}',
"the second row is not DOTS-25"
);
}
#[test]
fn each_dot_is_the_codepoint_the_block_names_for_it() {
const CASES: [(usize, usize, u32); 8] = [
(0, 0, 0x2801), (0, 1, 0x2802), (0, 2, 0x2804), (1, 0, 0x2808), (1, 1, 0x2810), (1, 2, 0x2820), (0, 3, 0x2840), (1, 3, 0x2880), ];
for (dx, dy, codepoint) in CASES {
let mut grid = BrailleGrid::new(1, 1);
grid.raise_dot(dx, dy);
assert_eq!(
grid.cell_char(0, 0),
char::from_u32(codepoint).unwrap(),
"dot ({dx},{dy}) is not U+{codepoint:04X}"
);
}
}
#[test]
fn the_bottom_row_is_detached_from_the_columns() {
let mut grid = BrailleGrid::new(1, 1);
grid.raise_dot(0, 3);
grid.raise_dot(1, 3);
assert_eq!(
grid.cell_char(0, 0),
'\u{28c0}',
"the bottom row is not DOTS-78"
);
let mut grid = BrailleGrid::new(1, 1);
grid.raise_dot(0, 2);
grid.raise_dot(1, 2);
grid.raise_dot(0, 3);
grid.raise_dot(1, 3);
assert_eq!(grid.cell_char(0, 0), '\u{28e4}', "dots 3, 6, 7 and 8");
}
#[test]
fn all_eight_dots_make_the_full_block() {
let mut grid = BrailleGrid::new(1, 1);
for dy in 0..DOTS_Y {
for dx in 0..DOTS_X {
grid.raise_dot(dx, dy);
}
}
assert_eq!(grid.cell_char(0, 0), '\u{28ff}');
}
#[test]
fn dots_in_different_cells_do_not_merge() {
let mut grid = BrailleGrid::new(2, 1);
grid.raise_dot(0, 0);
grid.raise_dot(2, 0);
assert_eq!(grid.cell_char(0, 0), '\u{2801}');
assert_eq!(grid.cell_char(1, 0), '\u{2801}');
}
#[test]
fn lowering_a_dot_clears_only_that_bit() {
let mut grid = BrailleGrid::new(1, 1);
grid.raise_dot(0, 0); grid.raise_dot(1, 0); grid.lower_dot(0, 0);
assert_eq!(grid.cell_char(0, 0), '\u{2808}');
}
#[test]
fn reading_a_dot_back_matches_writing_it() {
for dy in 0..DOTS_Y {
for dx in 0..DOTS_X {
let mut grid = BrailleGrid::new(1, 1);
grid.raise_dot(dx, dy);
assert!(grid.dot(dx, dy), "dot ({dx},{dy}) did not read back");
assert_eq!(
grid.cell_bits(0, 0),
braille_bit(dx, dy),
"dot ({dx},{dy}) landed on the wrong bit"
);
}
}
}
#[test]
fn dots_outside_the_grid_are_ignored_rather_than_panicking() {
let mut grid = BrailleGrid::new(2, 2); grid.raise_dot(4, 0);
grid.raise_dot(0, 8);
grid.raise_dot(usize::MAX, usize::MAX);
assert!(!grid.dot(4, 0));
assert!(!grid.dot(usize::MAX, 0));
}
#[test]
fn for_each_dot_visits_every_dot_once() {
let grid = BrailleGrid::new(3, 2);
let mut seen = Vec::new();
grid.for_each_dot(|x, y, _| seen.push((x, y)));
assert_eq!(seen.len(), 3 * 2 * 8);
let mut unique = seen.clone();
unique.sort_unstable();
unique.dedup();
assert_eq!(unique.len(), seen.len(), "a dot was visited twice");
}
#[test]
fn writing_produces_one_cell_per_braille_glyph() {
let mut grid = BrailleGrid::new(3, 2);
grid.raise_dot(5, 7);
let mut canvas = Canvas::new(3, 2);
canvas.clear();
grid.write_to(&mut canvas, Color::Red, Attribute::Bold);
assert_eq!(canvas.get(2, 1).symbol, '\u{2880}');
assert_eq!(canvas.get(2, 1).color, Color::Red);
assert_eq!(canvas.get(0, 0).symbol, ' ');
}
#[test]
fn overlaying_leaves_blank_cells_alone() {
let mut grid = BrailleGrid::new(2, 1);
grid.raise_dot(0, 0);
let mut canvas = Canvas::new(2, 1);
canvas.clear();
canvas.set(1, 0, Cell::new('X', Color::Blue, Attribute::Reset));
grid.overlay_onto(&mut canvas, Color::Red, Attribute::Reset);
assert_eq!(canvas.get(0, 0).symbol, '\u{2801}');
assert_eq!(
canvas.get(1, 0).symbol,
'X',
"a blank braille cell painted over what was underneath"
);
}
#[test]
fn a_field_above_the_threshold_lifts_the_dot() {
let mut grid = BrailleGrid::new(1, 1);
let values = vec![1.0; 8];
grid.draw_field(&values, 0.5, 0.0, super::super::dither::Dither::None);
assert_eq!(grid.cell_char(0, 0), '\u{28ff}');
}
#[test]
fn a_field_below_the_threshold_lifts_nothing() {
let mut grid = BrailleGrid::new(1, 1);
let values = vec![0.0; 8];
grid.draw_field(&values, 0.5, 0.0, super::super::dither::Dither::None);
assert_eq!(grid.cell_char(0, 0), ' ');
}
#[test]
fn a_short_field_is_read_with_clamping_not_a_panic() {
let mut grid = BrailleGrid::new(4, 4); grid.draw_field(&[1.0; 16], 0.5, 0.0, super::super::dither::Dither::None);
assert!(grid.dot(0, 0));
assert!(!grid.dot(7, 15));
}
#[test]
fn resizing_to_the_same_size_keeps_the_dots() {
let mut grid = BrailleGrid::new(2, 2);
grid.raise_dot(1, 1);
grid.resize(2, 2);
assert!(grid.dot(1, 1));
}
}