dotmax/
lib.rs

1//! dotmax - High-performance terminal braille rendering
2//!
3#![warn(missing_docs)]
4//!
5//! This library provides braille-based rendering capabilities for terminal applications,
6//! enabling images, animations, and graphics in any terminal environment.
7//!
8//! # Getting Started
9//!
10//! Create a braille grid and manipulate individual dots:
11//!
12//! ```
13//! use dotmax::BrailleGrid;
14//!
15//! // Create an 80×24 braille grid (typical terminal size)
16//! let mut grid = BrailleGrid::new(80, 24).unwrap();
17//!
18//! // Set individual dots using pixel coordinates
19//! // Grid is 80×24 cells = 160×96 dots (2×4 dots per cell)
20//! grid.set_dot(0, 0).unwrap(); // Top-left dot of first cell
21//! grid.set_dot(1, 0).unwrap(); // Top-right dot of first cell
22//!
23//! // Query dimensions
24//! let (width, height) = grid.dimensions();
25//! ```
26//!
27//! # Logging
28//!
29//! Dotmax uses the [`tracing`](https://docs.rs/tracing) crate for structured logging.
30//! The library does **not** initialize a tracing subscriber - your application must
31//! do this if you want to see log output.
32//!
33//! To enable logging in your application:
34//!
35//! ```no_run
36//! use tracing_subscriber;
37//!
38//! // Initialize the tracing subscriber (do this once at startup)
39//! tracing_subscriber::fmt()
40//!     .with_max_level(tracing::Level::DEBUG)
41//!     .init();
42//!
43//! // Now dotmax operations will emit trace events
44//! use dotmax::BrailleGrid;
45//! let grid = BrailleGrid::new(80, 24).unwrap();  // Logs: "Creating BrailleGrid: 80×24"
46//! ```
47//!
48//! **Log Levels:**
49//! - `ERROR`: Operation failures (e.g., out-of-bounds errors)
50//! - `WARN`: Degraded operation (e.g., terminal lacks Unicode support)
51//! - `INFO`: Major operations (grid creation, rendering)
52//! - `DEBUG`: Detailed flow (resize, color changes)
53//! - `TRACE`: Hot path internals (not used by default for performance)
54//!
55//! For more information, see the [tracing documentation](https://docs.rs/tracing).
56//!
57//! # Thread Safety
58//!
59//! All types in dotmax are `Send` and `Sync` where possible:
60//!
61//! - [`BrailleGrid`]: `Send + Sync` (can be shared across threads)
62//! - [`Color`]: `Send + Sync + Copy` (trivially thread-safe)
63//! - [`ColorScheme`]: `Send + Sync` (immutable after creation)
64//! - [`DotmaxError`]: `Send + Sync` (can be propagated across threads)
65//! - [`TerminalRenderer`]: `Send` but **not** `Sync` (owns terminal handle)
66//!
67//! For concurrent rendering, create one [`TerminalRenderer`] per thread or use
68//! a mutex to serialize access. [`BrailleGrid`] buffers can be prepared in
69//! parallel and then rendered sequentially.
70//!
71//! # License
72//!
73//! Licensed under either of:
74//! - MIT license ([LICENSE-MIT](../LICENSE-MIT) or <http://opensource.org/licenses/MIT>)
75//! - Apache License, Version 2.0 ([LICENSE-APACHE](../LICENSE-APACHE) or <http://www.apache.org/licenses/LICENSE-2.0>)
76//!
77//! at your option.
78
79// Core modules (Epic 2)
80pub mod error;
81pub mod grid;
82pub mod prelude;
83pub mod quick;
84pub mod render;
85
86// Utility modules (Epic 5)
87pub mod utils;
88
89// Re-export public types for convenience
90pub use error::DotmaxError;
91pub use grid::{BrailleGrid, Color};
92pub use render::{TerminalBackend, TerminalCapabilities, TerminalRenderer, TerminalType};
93
94// Re-export color capability detection (Epic 5)
95pub use utils::terminal_caps::{detect_color_capability, ColorCapability};
96
97// Re-export color scheme types (Epic 5, Story 5.3)
98pub use color::schemes::{
99    blue_purple, cyan_magenta, get_scheme, grayscale, green_yellow, heat_map, list_schemes,
100    monochrome, rainbow, ColorScheme,
101};
102
103// Re-export color scheme builder (Epic 5, Story 5.4)
104pub use color::scheme_builder::ColorSchemeBuilder;
105
106// Re-export color application functions (Epic 5, Story 5.5)
107pub use color::apply::{apply_color_scheme, apply_colors_to_grid};
108
109// Re-export animation types (Epic 6, Stories 6.1, 6.2, 6.3, 6.4, 6.5)
110pub use animation::{AnimationLoop, AnimationLoopBuilder, DifferentialRenderer, FrameBuffer, FrameTimer, PrerenderedAnimation};
111
112/// Convenience type alias for Results using `DotmaxError`
113///
114/// This allows writing `dotmax::Result<T>` instead of `Result<T, DotmaxError>`
115/// in applications using this library.
116pub type Result<T> = std::result::Result<T, DotmaxError>;
117
118// Feature modules (Epic 3+): image, primitives, density, color, animation
119#[cfg(feature = "image")]
120pub mod image;
121
122// Drawing primitives (Epic 4)
123pub mod primitives;
124
125// Character density rendering (Epic 4)
126pub mod density;
127
128// Color conversion (Epic 5)
129pub mod color;
130
131// Animation & frame management (Epic 6)
132pub mod animation;
133
134#[cfg(test)]
135mod tests {
136    #[test]
137    fn test_ci_basic() {
138        assert_eq!(1 + 1, 2); // Intentional formatting issue
139    }
140}
dotmax/lib.rs

dotmax/
lib.rs
