snes_bitplanes/lib.rs
1#![no_std]
2
3//! This is documentation for the `snes-bitplanes` crate.
4//!
5//! The Super NES includes stores its graphics in bitplanes,
6//! a packed format in which the bits representing a specific
7//! pixel are spread across multiple bytes in the same bit
8//! position.
9//!
10//! For example, 2-bit-per-pixel data stored as bitplanes
11//! might have the byte representation:
12//! ```ignore
13//! 00101110 // 0, bitplane 1
14//! 01100101 // 1, bitplane 2
15//! 11101001 // 2, bitplane 1
16//! 10010101 // 3, bitplane 2
17//! // ...
18//! 00010101 // 14, bitplane 1
19//! 00101110 // 15, bitplane 2
20//! ```
21//! The initial decoded values are `00`, `10`, `11`, `00`, `01`, `11`, `01`, `10`.
22//!
23//! The Super NES is little-endian, so the leftmost bits represent
24//! the earliest decoded bytes. Also note that the second bitplane
25//! is the more significant bit in the output.
26//!
27//! In total, 2bpp data will inflate to 4 times its original size
28//! (because `Bitplanes` iterators yield bytes themselves, even though the values
29//! are generally smaller).
30//!
31//! # Usage
32//!
33//! ```
34//! # use snes_bitplanes::{Bitplanes, Tile};
35//! # fn main() {
36//! let bitplanes_data = vec![0u8; 128]; // Extremely boring data
37//! let decoded: Vec<Tile> = Bitplanes::new(&bitplanes_data).collect();
38//! for pixel_row in decoded[0].chunks(8) {
39//! // the Tile struct wraps a 64-byte array, and has a similar API
40//! }
41//! # }
42//! ```
43//!
44//! Currently only 4-bits-per-pixel (16 color) bitplanes are decodable with
45//! this crate. More color depths will be added later.
46//!
47//! # Thanks
48//! This crate would not be possible without the research of others,
49//! notably
50//! * FDwR (Frank Dwayne) [/snesgfx.txt](http://fdwr.tripod.com/docs/snesgfx.txt) 1998
51//! * Qwertie (David Piepgrass) [/snesdoc.html](https://emu-docs.org/Super%20NES/General/snesdoc.html#GraphicsFormat) 1998
52
53mod tile;
54mod bitplanes_4bpp;
55
56pub use tile::Tile;
57pub use bitplanes_4bpp::Bitplanes;