Skip to content

docs(backends): update backend comparison and feature matrix #153

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
junkdog merged 6 commits into from
Jan 29, 2026
+35 −27
Merged

docs(backends): update backend comparison and feature matrix #153

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
86ff33d
update backend comparison
junkdog Jan 25, 2026
d60aaf3
update comparison
junkdog Jan 28, 2026
42adbc7
improve docs
junkdog Jan 28, 2026
09ce588
update feature comparison
junkdog Jan 28, 2026
27254ec
Update src/backend/mod.rs
junkdog Jan 28, 2026
8f82ed5
remove misleading feature
junkdog Jan 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 27 additions & 20 deletions src/backend/mod.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,37 +4,44 @@
//! each with different performance characteristics and trade-offs:
//!
//! - [`WebGl2Backend`]: GPU-accelerated rendering powered by [beamterm][beamterm]. Uses prebuilt
//! font atlases. Best performance, capable of 60fps on large terminals (300x100+).
//! or runtime generated font atlases. Very low overhead, typically under 1ms CPU time per frame,
//! even for fullscreen terminals with all cells changing.
//!
//! - [`CanvasBackend`]: Canvas 2D API with full Unicode support via browser font rendering.
//! Good fallback when WebGL2 isn't available or when dynamic character support is required.
//! Does not support hyperlinks or text selection, but can render dynamic Unicode/emoji.
//! - [`CanvasBackend`]: Canvas 2D API with Unicode support via browser font rendering.
//! Good fallback for the `WebGl2Backend`, if WebGL2 isn't available. Does not support hyperlinks
//! or text selection, but can render dynamic Unicode and single-cell emoji.
//!
//! - [`DomBackend`]: Renders cells as HTML elements. Most compatible and accessible,
//! supports hyperlinks, but slowest for large terminals.
//! - [`DomBackend`]: Renders cells as HTML elements. Most compatible, but slowest for large
//! terminals.
//!
//! [beamterm]: https://github.com/junkdog/beamterm
//!
//! ## Backend Comparison
//!
//! | Feature | DomBackend | CanvasBackend | WebGl2Backend |
//! |------------------------------|------------|---------------|------------------|
//! | **60fps on large terminals** | ✗ | ✗ | ✓ |
//! | **Memory Usage** | Highest | Medium | Lowest |
//! | **Hyperlinks** | ✓ | ✗ | ✓ |
//! | **Text Selection** | ✓ | ✗ | ✓ |
//! | **Accessibility** | ✓ | Limited | Limited |
//! | **Unicode/Emoji Support** | Full | Full | Limited to atlas |
//! | **Dynamic Characters** | ✓ | ✓ | ✗ |
//! | **Font Variants** | ✓ | Regular only | ✓ |
//! | **Underline** | ✓ | ✗ | ✓ |
//! | **Strikethrough** | ✓ | ✗ | ✓ |
//! | **Browser Support** | All | All | Modern (2017+) |
//! | Feature | DomBackend | CanvasBackend | WebGl2Backend |
//! |------------------------------|------------|---------------|----------------|
//! | **60fps on large terminals** | ✗ | ✗ | ✓ |
//! | **Memory Usage** | Highest | Medium | Lowest |
//! | **Hyperlinks** | ✗ | ✗ | ✓ |
//! | **Text Selection** | Linear | ✗ | Linear/Block |
//! | **Unicode/Emoji Support** | Full | Limited² | Full¹ |
//! | **Dynamic Characters** | ✓ | ✓ | ✓¹ |
//! | **Font Variants** | ✓ | Regular only | ✓ |
//! | **Underline** | ✓ | ✗ | ✓ |
//! | **Strikethrough** | ✓ | ✗ | ✓ |
//! | **Browser Support** | All | All | Modern (2017+) |
//!
//! ¹: The [dynamic font atlas](webgl2::FontAtlasConfig::Dynamic) rasterizes
//! glyphs on demand with full Unicode/emoji and font variant support. The
//! [static font atlas](webgl2::FontAtlasConfig::Static) is limited to glyphs
//! compiled into the `.atlas` file.
//! ²: Unicode is supported, but emoji only render correctly when it spans one cell.
//! Most emoji occupy two cells.
//!
//! ## Choosing a Backend
//!
//! - **WebGl2Backend**: Preferred for most applications - consumes the least amount of resources
//! - **CanvasBackend**: When you need dynamic Unicode/emoji or must support non-WebGL2 browsers
//! - **CanvasBackend**: When you must support non-WebGL2 browsers
//! - **DomBackend**: When you need better accessibility or CSS styling

/// Canvas backend.
Expand Down
15 changes: 8 additions & 7 deletions src/backend/webgl2.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@
};
use web_sys::{wasm_bindgen::JsCast, window, Element};

/// Re-export beamterm's atlas data type. Used by [`WebGl2BackendOptions::font_atlas`].
/// Re-export beamterm's atlas data type. Used by [`FontAtlasConfig::Static`].
pub use beamterm_renderer::FontAtlasData;

/// Font atlas configuration.
Expand Down Expand Up @@ -104,9 +104,9 @@
self
}

/// Sets the fallback glyph to use for characters not in the font atlas.
/// Sets the fallback glyph for missing characters.
///
/// If not set, defaults to a space character (` `).
/// Used when a glyph is missing from the font atlas. Defaults to a space character.
pub fn fallback_glyph(mut self, glyph: &str) -> Self {
self.fallback_glyph = Some(glyph.into());
self
Expand Down Expand Up @@ -231,12 +231,13 @@
///
/// WebGL2 is supported in all modern browsers (Chrome 56+, Firefox 51+, Safari 15+).
///
/// ## Font Atlas Limitation
/// ## Font Atlas Options
///
/// [`WebGl2Backend`] uses prebuilt font atlases for performance. Characters not in the atlas
/// will display as ` `. Use [`CanvasBackend`] if you need dynamic Unicode/emoji support.
/// [`WebGl2Backend`] supports two font atlas modes via [`FontAtlasConfig`]:
///
/// [`CanvasBackend`]: crate::backend::canvas::CanvasBackend
/// - **Dynamic**: Rasterizes glyphs on demand with full Unicode/emoji and font variant support.
/// - **Static** (default): Uses pre-generated `.atlas` files. The default atlas is embedded
/// in beamterm. Characters not in the atlas display as the fallback glyph (space by default).
///
/// # Performance Measurement
///
Expand Down Expand Up @@ -558,7 +559,7 @@
fn create_hyperlink_mouse_handler(
beamterm: &Beamterm,
hyperlink_cells: Rc<RefCell<BitVec>>,
callback: Rc<RefCell<dyn FnMut(&str)>>,

Check warning on line 562 in src/backend/webgl2.rs

View workflow job for this annotation

GitHub Actions / clippy

very complex type used. Consider factoring parts into `type` definitions 

warning: very complex type used. Consider factoring parts into `type` definitions
   --> src/backend/webgl2.rs:562:19
    |
562 |         callback: Rc<RefCell<dyn FnMut(&str)>>,
    |                   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    |
    = help: for further information visit https://rust-lang.github.io/rust-clippy/rust-1.93.0/index.html#type_complexity
    = note: `#[warn(clippy::type_complexity)]` on by default
cursor_state: Rc<RefCell<bool>>,
) -> Result<TerminalMouseHandler, Error> {
let grid = beamterm.grid();
Expand Down Expand Up @@ -905,7 +906,7 @@
/// A `Debug`-derive friendly convenience wrapper
#[derive(Clone)]
struct HyperlinkCallback {
callback: Rc<RefCell<dyn FnMut(&str)>>,

Check warning on line 909 in src/backend/webgl2.rs

View workflow job for this annotation

GitHub Actions / clippy

very complex type used. Consider factoring parts into `type` definitions 

warning: very complex type used. Consider factoring parts into `type` definitions
   --> src/backend/webgl2.rs:909:15
    |
909 |     callback: Rc<RefCell<dyn FnMut(&str)>>,
    |               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    |
    = help: for further information visit https://rust-lang.github.io/rust-clippy/rust-1.93.0/index.html#type_complexity
}

impl HyperlinkCallback {
Expand Down
Loading