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