rustydemon_blp2/lib.rs
1//! # rustydemon-blp2
2//!
3//! A Rust library for reading BLP texture files (BLP0, BLP1, BLP2).
4//!
5//! BLP is a texture format used in several popular games. This crate parses all
6//! three format versions and all standard
7//! color encodings, returning decoded pixels as raw RGBA bytes.
8//!
9//! ## Quick start
10//!
11//! ```no_run
12//! use rustydemon_blp2::BlpFile;
13//!
14//! let blp = BlpFile::open("texture.blp")?;
15//! println!("{}×{}, {} mip level(s)", blp.width, blp.height, blp.mipmap_count());
16//!
17//! // Decode the base (largest) mipmap — always RGBA, 4 bytes per pixel.
18//! let (pixels, w, h) = blp.get_pixels(0)?;
19//! assert_eq!(pixels.len(), (w * h * 4) as usize);
20//! # Ok::<(), rustydemon_blp2::BlpError>(())
21//! ```
22//!
23//! ## Format support
24//!
25//! | Format | Encoding | Alpha modes |
26//! |--------|----------|-------------|
27//! | BLP0 / BLP1 | Palette, DXT1/3/5, ARGB8888, JPEG | 0 / 1 / 4 / 8-bit |
28//! | BLP2 | Palette, DXT1/3/5, ARGB8888, JPEG | 0 / 1 / 4 / 8-bit |
29//!
30//! ## Output format
31//!
32//! [`BlpFile::get_pixels`] always returns **RGBA** (red first, alpha last),
33//! 4 bytes per pixel, in row-major order. This differs from the on-disk
34//! ARGB8888 representation (which is BGRA) — the swap is applied automatically.
35//!
36//! ## Mipmaps
37//!
38//! BLP files can store up to 16 mipmap levels. Level 0 is always the largest
39//! (base) image. Each successive level is half the dimensions of the previous
40//! one, clamped to a minimum of 1×1. Requesting a level beyond the available
41//! range silently clamps to the last valid level.
42
43pub mod error;
44
45mod blp;
46mod dxt;
47
48pub use blp::{BlpFile, ColorEncoding, PixelFormat};
49pub use error::BlpError;