image_blp/lib.rs
1//! This crate provides decoding/encoding for Blizzard BLP texture
2//! format that is used across several games like Wacraft III and
3//! World of Warcraft. You can load any BLP file into [DynamicImage]
4//! from [image] crate and save any [DynamicImage] into BLP file.
5//!
6//! # Usage
7//! This crate is on crates.io and can be used by adding image-blp to
8//! your dependencies in your project's Cargo.toml.
9//!
10//! ``` toml
11//! [dependencies]
12//! image-blp = "1"
13//! ```
14//!
15//! # Example: loading
16//!
17//! The crate separates loading of BLP file into parsing and converting.
18//! That allows to process BLP files without loosing information due unessesary
19//! conversion back and forth. Typically loading of BLP image into usable RGBA
20//! image looks like:
21//!
22//! ```no_run
23//! # use ::image::DynamicImage;
24//! # use image_blp::{convert::blp_to_image, parser::load_blp};
25//! #
26//! # let blp_filename = "test.blp";
27//! # let output_filename = "output.png";
28//! let blp_file = load_blp(blp_filename).expect("loaded blp");
29//! let mipmap_level = 0;
30//! let image = blp_to_image(&blp_file, mipmap_level).expect("converted");
31//! ```
32//! See example `examples/load.rs` for full code.
33//!
34//! # Example: saving
35//!
36//! The crate provides simplified API for specifing which type of BLP do you want to use.
37//! See [convert::BlpTarget] type for more info. Here the typical way to save image as
38//! ```no_run
39//! # use ::image::{io::Reader, DynamicImage};
40//! # use image_blp::{
41//! # convert::{image_to_blp, AlphaBits, BlpOldFormat, BlpTarget, FilterType},
42//! # encode::save_blp,
43//! # };
44//! # let input_filename = "input.png";
45//! # let output_filename = "output.blp";
46//! let img_file: DynamicImage = Reader::open(input_filename)
47//! .expect("open")
48//! .decode()
49//! .expect("decode");
50//! let make_mipmaps = true;
51//! let blp = image_to_blp(
52//! img_file,
53//! make_mipmaps,
54//! BlpTarget::Blp1(BlpOldFormat::Raw1 {
55//! alpha_bits: AlphaBits::Bit1,
56//! }),
57//! FilterType::Nearest,
58//! )
59//! .expect("converted");
60//! save_blp(&blp, output_filename).expect("saved");
61//! ```
62//! See example `examples/save.rs` for full code.
63//!
64//! # CLI tool
65//!
66//! The library is used to build universal CLI tool [blp-conv] that allows
67//! to convert from/into BLP format for wide range of image formats. You
68//! can install it via:
69//!
70//! ```bash
71//! cargo install blp-conv
72//! ```
73//!
74//! # Features
75//!
76//! The crate supports all known BLP versions like:
77//! * `BLP0` -- is used in old Wacraft III ROC Beta builds.
78//! * `BLP1` -- is common for Wacraft III TFT.
79//! * `BLP2` -- is used in World of Warcraft.
80//!
81//! The crate supports also all known encodings:
82//! * `RAW1` -- paletted images with 256 colors. We use [color_quant]
83//! package for compressing generic images to the format.
84//! * `RAW3` -- like ordinary RGBA bitmaps.
85//! * `JPEG` -- ordinary jpeg compressed image.
86//! * `DXTn` -- [S3TC] compression algorithms for `BLP2` version. We use
87//! [texpresso] for the compression/decompression.
88//!
89//! # Tests
90//!
91//! Tests of the library use original files of Blizzard games. So, they cannot
92//! be distributed with the library due license issues. You should buy the
93//! original games to extract the files for testing.
94//!
95//! [image]: https://crates.io/crates/image
96//! [blp-conv]: https://crates.io/crates/blp-conv
97//! [DynamicImage]: https://docs.rs/image/latest/image/enum.DynamicImage.html
98//! [color_quant]: https://crates.io/crates/color_quant
99//! [texpresso]: https://crates.io/crates/texpresso
100//! [S3TC]: http://en.wikipedia.org/wiki/S3TC
101
102/// Convertion utilities to/from [DynamicImage](https://docs.rs/image/latest/image/enum.DynamicImage.html)
103pub mod convert;
104/// Encoding BLP format into stream of bytes.
105pub mod encode;
106/// Decoding BLP format from raw bytes.
107pub mod parser;
108/// Utilities for mipmaps filename generation
109pub mod path;
110/// Defines structure of parsed BLP file
111pub mod types;
112
113pub use types::*;