Image Loading
Relevant source files
The following files were used as context for generating this wiki page:
Image loading in guiltty is the process of importing external pixel data into the library's core structures for use as drawable material. The system centers around the Bitmap struct, which serves as a representation of static image data converted into a project-wide RGBA8 color model. Sources: crates/guiltty-core/src/lib.rs:722-727, tasks/plan.md:112-117
This module allows developers to load common image formats (PNG, JPEG, GIF, BMP) from disk. Once loaded, these images can be used as the visual content for Sprites, which are movable 2D objects that can be drawn onto a Canvas. Sources: crates/guiltty-core/src/lib.rs:777-781, README.md:10-15
Architecture and Components
The image loading system is integrated into guiltty-core and relies on the external image crate for decoding various file formats. Sources: crates/guiltty-core/Cargo.toml:14-14, tasks/plan.md:118-121
Data Structures
| Structure | Description |
|---|---|
Bitmap | Stores a row-major Vec<Color> along with width and height. Represents the decoded image. |
Color | An RGBA8 structure (Red, Green, Blue, Alpha) where each component is a u8. |
Error::ImageLoad | A recoverable error variant used when file access or decoding fails. |
Sources: crates/guiltty-core/src/lib.rs:8-13, crates/guiltty-core/src/lib.rs:82-84, crates/guiltty-core/src/lib.rs:724-729
Image Loading Flow
The following diagram illustrates the sequence of events when a user calls the image loading API:
The process ensures that regardless of the source format (e.g., grayscale or RGB), the data is normalized to RGBA8. Sources: crates/guiltty-core/src/lib.rs:777-795, tasks/plan.md:122-125
Technical Implementation
File Decoding and Normalization
The core logic resides in Bitmap::from_file. This function performs the following steps:
- Decoding: Uses
image::opento detect format and decode. - Conversion: Forces the image into an RGBA8 buffer using
.into_rgba8(). - Mapping: Iterates through the raw pixels and collects them into a
Vec<Color>. - Error Handling: Returns an
Error::ImageLoadif any step fails, preventing panics during runtime for missing or corrupt files.
Sources: crates/guiltty-core/src/lib.rs:786-802, tasks/plan.md:126-130
Coordinate Mapping
The library uses a row-major indexing system. The Bitmap::index function calculates the position in the flat pixel vector based on (x, y) coordinates.
fn index(&self, x: u32, y: u32) -> Option<usize> {
if x >= self.width || y >= self.height {
return None;
}
Some(y as usize * self.width as usize + x as usize)
}
Sources: crates/guiltty-core/src/lib.rs:813-818
Sprite Integration
Once an image is loaded into a Bitmap, it is typically wrapped in a Sprite for rendering. The Sprite maintains a position and a last_draw footprint to support background preservation during movement. Sources: crates/guiltty-core/src/lib.rs:849-854, crates/guiltty-core/src/lib.rs:909-913
The draw_sprite method handles the transfer of pixels from the Bitmap to the Canvas, skipping fully transparent pixels (alpha = 0). Sources: crates/guiltty-core/src/lib.rs:939-943, crates/guiltty-kitty/src/lib.rs:80-85
Error Handling
The system treats image loading as a recoverable operation. The Bitmap::from_file method returns a Result<Self, Error>.
| Error Case | Behavior |
|---|---|
| Missing File | Returns Error::ImageLoad with the file path and system error. |
| Unsupported Format | Returns Error::ImageLoad indicating decoding failure. |
| Corrupt Data | Returns Error::ImageLoad if the image crate cannot process the buffer. |
Sources: crates/guiltty-core/src/lib.rs:786-790, tasks/plan.md:131-135
Conclusion
The image loading system provides a bridge between external assets and the guiltty rendering engine. By enforcing a strict RGBA8 conversion and providing recoverable error handling, it ensures that terminal backends like KittyBackend receive consistent pixel data for transmission. Sources: tasks/plan.md:139-142, crates/guiltty-kitty/src/lib.rs:80-84