feat(backend): add CellSized trait for querying cell dimensions in physical and CSS pixels

Author: junkdog

examples/shared/src/backend.rs

@@ -4,7 +4,7 @@ use ratzilla::{
     error::Error,
     event::{KeyEvent, MouseEvent},
     ratatui::{backend::Backend, prelude::backend::ClearType, Terminal, TerminalOptions},
-    CanvasBackend, DomBackend, WebEventHandler, WebGl2Backend,
+    CanvasBackend, CellSized, DomBackend, WebEventHandler, WebGl2Backend,
 };
 use std::{convert::TryFrom, fmt, io};
 use web_sys::{window, Url};
@@ -78,6 +78,24 @@ impl RatzillaBackend {
     }
 }
 
+impl CellSized for RatzillaBackend {
+    fn cell_size_px(&self) -> (f64, f64) {
+        match self {
+            RatzillaBackend::Dom(backend) => backend.cell_size_px(),
+            RatzillaBackend::Canvas(backend) => backend.cell_size_px(),
+            RatzillaBackend::WebGl2(backend) => backend.cell_size_px(),
+        }
+    }
+
+    fn cell_size_css_px(&self) -> (f64, f64) {
+        match self {
+            RatzillaBackend::Dom(backend) => backend.cell_size_css_px(),
+            RatzillaBackend::Canvas(backend) => backend.cell_size_css_px(),
+            RatzillaBackend::WebGl2(backend) => backend.cell_size_css_px(),
+        }
+    }
+}
+
 impl Backend for RatzillaBackend {
     type Error = io::Error;
 
@@ -244,6 +262,16 @@ impl From<RatzillaBackend> for FpsTrackingBackend {
     }
 }
 
+impl CellSized for FpsTrackingBackend {
+    fn cell_size_px(&self) -> (f64, f64) {
+        self.inner.cell_size_px()
+    }
+
+    fn cell_size_css_px(&self) -> (f64, f64) {
+        self.inner.cell_size_css_px()
+    }
+}
+
 impl Backend for FpsTrackingBackend {
     type Error = io::Error;
 

src/backend/canvas.rs

@@ -10,6 +10,7 @@ use crate::{
         },
         utils::*,
     },
+    cell_sized::CellSized,
     error::Error,
     event::{KeyEvent, MouseEvent},
     render::WebEventHandler,
@@ -438,6 +439,18 @@ impl CanvasBackend {
     }
 }
 
+impl CellSized for CanvasBackend {
+    fn cell_size_px(&self) -> (f64, f64) {
+        let dpr = get_window().map(|w| w.device_pixel_ratio()).unwrap_or(1.0);
+
+        (CELL_WIDTH * dpr, CELL_HEIGHT * dpr)
+    }
+
+    fn cell_size_css_px(&self) -> (f64, f64) {
+        (CELL_WIDTH, CELL_HEIGHT)
+    }
+}
+
 impl Backend for CanvasBackend {
     type Error = IoError;
 

src/backend/dom.rs

@@ -21,6 +21,7 @@ use crate::{
         },
         utils::*,
     },
+    cell_sized::CellSized,
     error::Error,
     event::{KeyEvent, MouseEvent},
     render::WebEventHandler,
@@ -265,6 +266,18 @@ impl DomBackend {
     }
 }
 
+impl CellSized for DomBackend {
+    fn cell_size_px(&self) -> (f64, f64) {
+        let dpr = get_window().map(|w| w.device_pixel_ratio()).unwrap_or(1.0);
+
+        (self.cell_size.0 * dpr, self.cell_size.1 * dpr)
+    }
+
+    fn cell_size_css_px(&self) -> (f64, f64) {
+        self.cell_size
+    }
+}
+
 impl Backend for DomBackend {
     type Error = IoError;
 

src/backend/webgl2.rs

@@ -4,6 +4,7 @@ use crate::{
         event_callback::{EventCallback, KEY_EVENT_TYPES},
         utils::*,
     },
+    cell_sized::CellSized,
     error::Error,
     event::{KeyEvent, MouseEvent},
     render::WebEventHandler,
@@ -702,6 +703,19 @@ impl WebGl2Backend {
     }
 }
 
+impl CellSized for WebGl2Backend {
+    fn cell_size_px(&self) -> (f64, f64) {
+        let (w, h) = self.beamterm.cell_size();
+        (w as f64, h as f64)
+    }
+
+    fn cell_size_css_px(&self) -> (f64, f64) {
+        let (w, h) = self.beamterm.cell_size();
+        let dpr = get_window().map(|w| w.device_pixel_ratio()).unwrap_or(1.0);
+        (w as f64 / dpr, h as f64 / dpr)
+    }
+}
+
 impl Backend for WebGl2Backend {
     type Error = IoError;
 

src/cell_sized.rs

@@ -0,0 +1,19 @@
+/// A type that knows the pixel dimensions of its terminal cells.
+///
+/// # Physical vs. CSS pixels
+///
+/// On HiDPI / Retina displays the device pixel ratio (DPR) causes one
+/// CSS pixel to map to multiple physical (device) pixels.
+///
+/// - **Physical pixels** (`cell_size_px`): the actual device pixels
+///   occupied by a cell. Useful for pixel-perfect rendering and GPU work.
+/// - **CSS pixels** (`cell_size_css_px`): the logical size as seen by
+///   the browser layout engine. Useful for DOM positioning, mouse
+///   coordinate translation, and canvas drawing.
+pub trait CellSized {
+    /// Returns the size of a cell in physical (device) pixels as `(width, height)`.
+    fn cell_size_px(&self) -> (f64, f64);
+
+    /// Returns the size of a cell in CSS (logical) pixels as `(width, height)`.
+    fn cell_size_css_px(&self) -> (f64, f64);
+}

src/lib.rs

@@ -19,6 +19,9 @@ pub mod backend;
 /// Rendering.
 mod render;
 
+/// Cell size metrics for backends.
+pub mod cell_sized;
+
 // Re-export ratatui crate.
 pub use ratatui;
 
@@ -31,4 +34,5 @@ pub use backend::{
     dom::DomBackend,
     webgl2::{FontAtlasConfig, SelectionMode, WebGl2Backend},
 };
+pub use cell_sized::CellSized;
 pub use render::{WebEventHandler, WebRenderer};