Guiltty Facade Crate
Relevant source files
The following files were used as context for generating this wiki page:
The guiltty crate serves as the primary entry point and facade for the Guiltty project. It simplifies consumption of the library by re-exporting essential types and traits from internal crates, specifically the backend-agnostic rendering engine in guiltty-core and the Kitty terminal graphics protocol implementation in guiltty-kitty.
This architecture allows developers to interact with a single dependency while maintaining a clean separation between core 2D graphics logic and terminal-specific transmission protocols. The crate aims to enable real, pixel-level 2D graphics in terminals that support the Kitty graphics protocol, bypassing the limitations of traditional character-cell TUI toolkits.
Sources: crates/guiltty/src/lib.rs:1-8, README.md:1-12
Architectural Role
The Guiltty project is structured as a Cargo workspace containing three primary crates. The facade crate (guiltty) sits at the top of this hierarchy to provide a unified API.
The diagram above illustrates how the facade crate aggregates functionality from specialized sub-crates to serve the user application.
Sources: crates/guiltty/Cargo.toml:13-16, README.md:17-23
Dependency Structure
The facade crate coordinates the following internal dependencies:
| Crate | Purpose | Key Responsibilities |
|---|---|---|
guiltty-core | Rendering Engine | Defines primitives (Color, Point), Canvas, Shapes, and Sprite logic. |
guiltty-kitty | Backend | Implements the Backend trait for the Kitty graphics protocol. |
Sources: crates/guiltty/Cargo.toml:13-16, crates/guiltty-core/Cargo.toml:10-11, crates/guiltty-kitty/Cargo.toml:13-14
Re-exported API Surface
The facade crate exports the most relevant types for building and rendering a 2D scene. This allows users to import everything from one location rather than managing multiple crate dependencies.
Core Primitives and Rendering
The following types are re-exported from guiltty-core:
- Data Structures:
Color,Point,Rect,Bitmap. - Drawing:
Canvas,Shape,Fill,TextStyle,Sprite. - Traits and Errors:
Backend,Error.
Sources: crates/guiltty/src/lib.rs:4-7
Backends
The crate currently re-exports the KittyBackend from the guiltty-kitty crate, which is the default (and currently only) backend provided by the project.
Sources: crates/guiltty/src/lib.rs:8
Usage Workflow
The intended workflow for a consumer of the guiltty facade involves initializing a Canvas, drawing objects using the core primitives, and then using the KittyBackend to transmit the result to the terminal.
The sequence above demonstrates the typical interaction flow using the facade's re-exported types.
Sources: crates/guiltty-core/src/lib.rs:104-106, crates/guiltty-core/src/lib.rs:374-376, crates/guiltty-kitty/src/lib.rs:48-51, crates/guiltty-kitty/src/lib.rs:77-79
Implementation Detail: The present() Signature
The Backend trait defines the contract for rendering. The KittyBackend implements this by taking a reference to a Canvas and encoding its pixel buffer into Kitty-specific escape sequences.
// Re-exported trait and method
pub trait Backend {
type Error: std::error::Error;
fn present(&mut self, canvas: &Canvas) -> Result<(), Self::Error>;
}
Sources: crates/guiltty-core/src/lib.rs:87-94, crates/guiltty-kitty/src/lib.rs:77-80
Configuration and Workspace Integration
The facade crate inherits common package metadata and lint configurations from the workspace root.
- Rust Version: Pinned to
1.96.0. - Edition:
2021. - License:
MIT. - Lints: The crate uses workspace-wide Clippy lints, including warnings for
too_many_linesandexcessive_nesting.
Sources: Cargo.toml:1-18, crates/guiltty/Cargo.toml:1-11
Summary
The guiltty facade crate provides a convenient and centralized interface for the Guiltty library. By re-exporting the comprehensive 2D drawing capabilities of guiltty-core and the terminal transmission logic of guiltty-kitty, it allows developers to focus on graphics implementation while abstracting away the underlying complexity of terminal protocols and workspace crate management.