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

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) -> (f32, f32) {
+        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) -> (f32, f32) {
+        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) -> (f32, f32) {
+        self.inner.cell_size_px()
+    }
+
+    fn cell_size_css_px(&self) -> (f32, f32) {
+        self.inner.cell_size_css_px()
+    }
+}
+
 impl Backend for FpsTrackingBackend {
     type Error = io::Error;
 

src/backend/canvas.rs

@@ -4,6 +4,7 @@ use std::io::{Error as IoError, Result as IoResult};
 
 use crate::{
     backend::{
+        cell_sized::CellSized,
         color::{actual_bg_color, actual_fg_color},
         event_callback::{
             create_mouse_event, EventCallback, MouseConfig, KEY_EVENT_TYPES, MOUSE_EVENT_TYPES,
@@ -438,6 +439,17 @@ impl CanvasBackend {
     }
 }
 
+impl CellSized for CanvasBackend {
+    fn cell_size_px(&self) -> (f32, f32) {
+        let dpr = get_device_pixel_ratio();
+        (CELL_WIDTH as f32 * dpr, CELL_HEIGHT as f32 * dpr)
+    }
+
+    fn cell_size_css_px(&self) -> (f32, f32) {
+        (CELL_WIDTH as f32, CELL_HEIGHT as f32)
+    }
+}
+
 impl Backend for CanvasBackend {
     type Error = IoError;
 

src/backend/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) -> (f32, f32);
+
+    /// Returns the size of a cell in CSS (logical) pixels as `(width, height)`.
+    fn cell_size_css_px(&self) -> (f32, f32);
+}

src/backend/dom.rs

@@ -16,6 +16,7 @@ use unicode_width::UnicodeWidthStr;
 
 use crate::{
     backend::{
+        cell_sized::CellSized,
         event_callback::{
             create_mouse_event, EventCallback, MouseConfig, KEY_EVENT_TYPES, MOUSE_EVENT_TYPES,
         },
@@ -265,6 +266,17 @@ impl DomBackend {
     }
 }
 
+impl CellSized for DomBackend {
+    fn cell_size_px(&self) -> (f32, f32) {
+        let dpr = get_device_pixel_ratio();
+        (self.cell_size.0 as f32 * dpr, self.cell_size.1 as f32 * dpr)
+    }
+
+    fn cell_size_css_px(&self) -> (f32, f32) {
+        (self.cell_size.0 as f32, self.cell_size.1 as f32)
+    }
+}
+
 impl Backend for DomBackend {
     type Error = IoError;
 

src/backend/mod.rs

@@ -77,5 +77,7 @@ pub(super) mod event_callback;
 /// Backend utilities.
 pub(crate) mod utils;
 
+/// Cell size metrics for backends.
+pub mod cell_sized;
 /// Cursor shapes.
 pub mod cursor;

src/backend/utils.rs

@@ -246,6 +246,11 @@ pub(crate) fn get_window() -> Result<Window, Error> {
     window().ok_or(Error::UnableToRetrieveWindow)
 }
 
+/// Returns the device pixel ratio from the window.
+pub(crate) fn get_device_pixel_ratio() -> f32 {
+    get_window().map(|w| w.device_pixel_ratio()).unwrap_or(1.0) as f32
+}
+
 /// Returns an element by its ID or the body element if no ID is provided.
 pub(crate) fn get_element_by_id_or_body(id: Option<&String>) -> Result<web_sys::Element, Error> {
     match id {

src/backend/webgl2.rs

@@ -27,8 +27,9 @@ use std::{
     mem::swap,
     rc::Rc,
 };
-use web_sys::{wasm_bindgen::JsCast, window, Element};
+use web_sys::{wasm_bindgen::JsCast, Element};
 
+use crate::backend::cell_sized::CellSized;
 /// Re-export beamterm's atlas data type. Used by [`FontAtlasConfig::Static`].
 pub use beamterm_renderer::FontAtlasData;
 
@@ -205,7 +206,7 @@ impl WebGl2BackendOptions {
     /// Sets up a default mouse handler using [`WebGl2BackendOptions::on_hyperlink_click`].
     pub fn enable_hyperlinks(self) -> Self {
         self.on_hyperlink_click(|url| {
-            if let Some(w) = window() {
+            if let Ok(w) = get_window() {
                 w.open_with_url_and_target(url, "_blank")
                     .unwrap_or_default();
             }
@@ -425,8 +426,13 @@ impl WebGl2Backend {
     ///
     /// For static atlases, this is the cell size from the atlas data.
     /// For dynamic atlases, this is measured from the rasterized font.
+    #[deprecated(
+        since = "0.4.0",
+        note = "Use cell_size_px instead, which returns physical pixel dimensions"
+    )]
     pub fn cell_size(&self) -> (i32, i32) {
-        self.beamterm.cell_size()
+        let (w, h) = self.cell_size_px();
+        (w as i32, h as i32)
     }
 
     /// Resizes the canvas and terminal grid to the specified logical pixel dimensions.
@@ -672,6 +678,17 @@ impl WebGl2Backend {
     }
 }
 
+impl CellSized for WebGl2Backend {
+    fn cell_size_px(&self) -> (f32, f32) {
+        let (w, h) = self.beamterm.cell_size();
+        (w as f32, h as f32)
+    }
+
+    fn cell_size_css_px(&self) -> (f32, f32) {
+        self.beamterm.grid().borrow().css_cell_size()
+    }
+}
+
 impl Backend for WebGl2Backend {
     type Error = IoError;
 

src/lib.rs

@@ -27,6 +27,7 @@ pub use web_sys;
 
 pub use backend::{
     canvas::CanvasBackend,
+    cell_sized::CellSized,
     cursor::CursorShape,
     dom::DomBackend,
     webgl2::{FontAtlasConfig, SelectionMode, WebGl2Backend},