Crate dotmax

Crate dotmax 

Source
Expand description

dotmax - High-performance terminal braille rendering

This library provides braille-based rendering capabilities for terminal applications, enabling images, animations, and graphics in any terminal environment.

§Getting Started

Create a braille grid and manipulate individual dots:

use dotmax::BrailleGrid;

// Create an 80×24 braille grid (typical terminal size)
let mut grid = BrailleGrid::new(80, 24).unwrap();

// Set individual dots using pixel coordinates
// Grid is 80×24 cells = 160×96 dots (2×4 dots per cell)
grid.set_dot(0, 0).unwrap(); // Top-left dot of first cell
grid.set_dot(1, 0).unwrap(); // Top-right dot of first cell

// Query dimensions
let (width, height) = grid.dimensions();

§Logging

Dotmax uses the tracing crate for structured logging. The library does not initialize a tracing subscriber - your application must do this if you want to see log output.

To enable logging in your application:

use tracing_subscriber;

// Initialize the tracing subscriber (do this once at startup)
tracing_subscriber::fmt()
    .with_max_level(tracing::Level::DEBUG)
    .init();

// Now dotmax operations will emit trace events
use dotmax::BrailleGrid;
let grid = BrailleGrid::new(80, 24).unwrap();  // Logs: "Creating BrailleGrid: 80×24"

Log Levels:

  • ERROR: Operation failures (e.g., out-of-bounds errors)
  • WARN: Degraded operation (e.g., terminal lacks Unicode support)
  • INFO: Major operations (grid creation, rendering)
  • DEBUG: Detailed flow (resize, color changes)
  • TRACE: Hot path internals (not used by default for performance)

For more information, see the tracing documentation.

§Thread Safety

All types in dotmax are Send and Sync where possible:

  • BrailleGrid: Send + Sync (can be shared across threads)
  • Color: Send + Sync + Copy (trivially thread-safe)
  • ColorScheme: Send + Sync (immutable after creation)
  • DotmaxError: Send + Sync (can be propagated across threads)
  • TerminalRenderer: Send but not Sync (owns terminal handle)

For concurrent rendering, create one TerminalRenderer per thread or use a mutex to serialize access. BrailleGrid buffers can be prepared in parallel and then rendered sequentially.

§License

Licensed under either of:

at your option.

Re-exports§

pub use error::DotmaxError;
pub use grid::BrailleGrid;
pub use grid::Color;
pub use render::TerminalBackend;
pub use render::TerminalCapabilities;
pub use render::TerminalRenderer;
pub use render::TerminalType;
pub use utils::terminal_caps::detect_color_capability;
pub use utils::terminal_caps::ColorCapability;
pub use color::schemes::blue_purple;
pub use color::schemes::cyan_magenta;
pub use color::schemes::get_scheme;
pub use color::schemes::grayscale;
pub use color::schemes::green_yellow;
pub use color::schemes::heat_map;
pub use color::schemes::list_schemes;
pub use color::schemes::monochrome;
pub use color::schemes::rainbow;
pub use color::schemes::ColorScheme;
pub use color::scheme_builder::ColorSchemeBuilder;
pub use color::apply::apply_color_scheme;
pub use color::apply::apply_colors_to_grid;
pub use animation::AnimationLoop;
pub use animation::AnimationLoopBuilder;
pub use animation::DifferentialRenderer;
pub use animation::FrameBuffer;
pub use animation::FrameTimer;
pub use animation::PrerenderedAnimation;

Modules§

animation
Animation and frame management for flicker-free terminal graphics.
color
Color conversion and escape code generation for terminal output.
density
Character density-based rendering
error
Error types for dotmax operations
grid
Core BrailleGrid data structure for terminal braille rendering.
prelude
Prelude module for convenient imports.
primitives
Drawing primitives for braille graphics.
quick
Quick one-liner functions for common dotmax tasks.
render
Terminal rendering module
utils
Utility modules for dotmax.

Type Aliases§

Result
Convenience type alias for Results using DotmaxError