diff --git a/src/backend/mod.rs b/src/backend/mod.rs index a674fdb..75d12a9 100644 --- a/src/backend/mod.rs +++ b/src/backend/mod.rs @@ -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. diff --git a/src/backend/webgl2.rs b/src/backend/webgl2.rs index 11dec5b..b688cb8 100644 --- a/src/backend/webgl2.rs +++ b/src/backend/webgl2.rs @@ -23,7 +23,7 @@ use std::{ }; 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. @@ -104,9 +104,9 @@ impl WebGl2BackendOptions { 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 @@ -231,12 +231,13 @@ impl WebGl2BackendOptions { /// /// 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 ///