wblp

BLP1 image format encoder/decoder written in pure Rust.

BLP is Blizzard's texture format used in Warcraft III.

Installation

Library

[dependencies]
wblp = "0.1.11"

CLI

cargo install wblp --features "blp2png png2blp"

Quick Start

Encoding

use wblp::BLPEncoder;

// Encode image file → BLP bytes
let blp_bytes = BLPEncoder::from_path("texture.png")?
    .quality(85)
    .encode()?;

// Encode and save directly
BLPEncoder::from_path("texture.png")?
    .save("output.blp")?;

Decoding

use wblp::BLPDecoder;

// Decode BLP → PNG
BLPDecoder::from_path("texture.blp")?
    .decode()?
    .save_png("output.png")?;

BLPEncoder

use wblp::BLPEncoder;

// From image file
BLPEncoder::from_path("input.png")?
    .quality(90)
    .mipmaps(true)
    .encode()?
    .save("output.blp")?;

// From RGBA ImageBuffer
let img = image::open("texture.png")?.to_rgba8();
BLPEncoder::from_image(&img)?
    .encode()?;

// From raw pixels (validates size)
let pixels: Vec<u8> = vec![255; 512 * 512 * 4];
BLPEncoder::from_pixels(512, 512, &pixels)?
    .encode()?;

// From image bytes (PNG, JPEG, etc.)
let image_bytes = std::fs::read("image.png")?;
BLPEncoder::from_image_bytes(&image_bytes)?
    .encode()?;

BLPDecoder

use wblp::{BLPDecoder, BLPMetadata, BLPFormat};

// From file
BLPDecoder::from_path("texture.blp")?
    .decode()?
    .save_png("output.png")?;

// From BLP bytes
BLPDecoder::from_blp_bytes(&data)?
    .decode()?
    .to_png_bytes()?;

// All metadata in one call
let meta: BLPMetadata = decoder.metadata()?;
println!("{}x{}, {} mipmaps, alpha={}, format={:?}",
    meta.width, meta.height, meta.mipmaps, meta.has_alpha, meta.format);

Mipmap Levels

// Specific level
let small = decoder.decode_mipmap(2)?;

// All levels
let mipmaps = decoder.decode_all_mipmaps()?;

BLPImage

let img = decoder.decode()?;

// Save/Encode
img.save_png("output.png")?;
img.save_blp("output.blp")?;
let png_bytes = img.to_png_bytes()?;  // or img.to_png()
let blp_bytes = img.to_blp()?;

// Raw data
let rgba_bytes = img.as_rgba();
let owned_rgba = img.into_rgba();

// Alpha mask extraction (for shadows/team colors)
let alpha_mask = img.extract_alpha_mask();

// Iterate pixels
for pixel in img.pixels() {
    // ...
}

Traits

use wblp::BLPImage;

// BLP bytes → BLPImage
let img: BLPImage = std::fs::read("texture.blp")?.try_into()?;

// BLPImage → PNG bytes
let png: Vec<u8> = img.try_into()?;

Error Handling

All operations return Result<T, BLPError> and use the ? operator for error propagation:

use wblp::{BLPDecoder, BLPEncoder, BLPError};

match encoder.encode() {
    Ok(bytes) => { /* success */ }
    Err(BLPError::EncodeFailed(msg)) => { /* compression failed */ }
    Err(BLPError::IoError(e)) => { /* file I/O error */ }
    Err(BLPError::CorruptedData(msg)) => { /* invalid BLP structure */ }
    Err(e) => { /* other error */ }
}

Error Variants

Core Types

Types

enum BLPFormat {
    JPEG,
    Direct,
}

struct BLPMetadata {
    width: u32,
    height: u32,
    mipmaps: usize,
    has_alpha: bool,
    format: BLPFormat,
}

BLPEncoder

BLPDecoder

Deprecated (use metadata() instead):

• dimensions(), has_alpha(), mipmap_count(), content_type()

BLPImage

CLI

The CLI tool converts between BLP and image formats.

Features & Commands

Build with --features "blp2png png2blp" to enable all commands.

Installation

# Full featured (both directions)
cargo install wblp --features "blp2png png2blp"

# BLP to PNG only
cargo install wblp --features "blp2png"

# Image to BLP only
cargo install wblp --features "png2blp"

# Build from source
cargo build --release --features "blp2png png2blp"

Commands

With blp2png feature:

wblp to-png texture.blp -o output.png
wblp to-png texture.blp -o output.png -m 1
wblp blp2-png-dir ./blp_textures -o ./png_output    # recursive

With png2blp feature:

wblp to-blp texture.png -o output.blp
wblp to-blp texture.png -o output.blp -q 90 --no-mipmaps
wblp png2-blp-dir ./images -o ./blp_output          # recursive

Options

Single file (blp2png):

Single file (png2blp):

Batch directory (blp2png):

Batch directory (png2blp):

Features

• Mipmap generation: Automatic mipmap chain (up to 16 levels)
• Alpha detection: Auto-detects alpha channel
• Format support: PNG, JPEG, BMP, GIF, TIFF, WebP via image crate
• Performance: TurboJPEG for fast JPEG encoding
• Zero-copy: Methods that borrow data without allocation where possible

Format Support

Dependencies

• turbojpeg - JPEG encoder
• image - Image loading
• zune-jpeg - JPEG decoder
• rayon - Parallel mipmap decoding
• thiserror - Error handling
• clap - CLI argument parsing
• walkdir - Recursive directory traversal for batch commands

License

MIT