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
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
//! RGBA image encoding for BLP1 and BLP2.
use super::{assemble, bgra, dxt, indexed, jpeg, mipmaps};
use crate::blp::{Blp, DxtFormat, MIPMAP_SLOTS};
use image::RgbaImage;
use std::{error::Error, fmt};
/// BLP container version for formats available in both versions.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum BlpVersion {
/// The original BLP1 container format.
Blp1,
/// The BLP2 container format.
Blp2,
}
/// Alpha storage supported by indexed BLP images.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum IndexedAlpha {
/// No alpha storage; every pixel is opaque.
Opaque,
/// One alpha bit per pixel, representing transparency or opacity.
Bit1,
/// Four alpha bits per pixel.
Bit4,
/// Eight alpha bits per pixel.
Bit8,
}
impl IndexedAlpha {
/// Returns the number of stored alpha bits per pixel.
pub const fn bits(self) -> u8 {
match self {
Self::Opaque => 0,
Self::Bit1 => 1,
Self::Bit4 => 4,
Self::Bit8 => 8,
}
}
}
/// Pixel encoding, with only the settings supported by that encoding.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum EncodeFormat {
/// Palette-indexed pixels with packed alpha storage.
Indexed {
/// Container version to produce.
version: BlpVersion,
/// Alpha precision for the separate alpha plane.
alpha: IndexedAlpha,
},
/// JPEG-compressed color and optional alpha components.
Jpeg {
/// Container version to produce.
version: BlpVersion,
/// Whether to preserve alpha instead of forcing opaque pixels.
alpha: bool,
/// JPEG quality from 1 (lowest) through 100 (highest).
quality: u8,
},
/// BC1 block compression in a BLP2 container.
Dxt1 {
/// Whether to preserve alpha instead of forcing opaque pixels.
alpha: bool,
},
/// BC2 block compression with explicit alpha in a BLP2 container.
Dxt3,
/// BC3 block compression with interpolated alpha in a BLP2 container.
Dxt5,
/// Uncompressed BGRA pixels in a BLP2 container.
Bgra,
}
impl EncodeFormat {
/// Returns the alpha depth recorded for this encoding, in bits per pixel.
pub const fn alpha_bits(self) -> u8 {
match self {
Self::Indexed { alpha, .. } => alpha.bits(),
Self::Jpeg { alpha, .. } => {
if alpha {
8
} else {
0
}
}
Self::Dxt1 { alpha } => {
if alpha {
1
} else {
0
}
}
Self::Dxt3 => 4,
Self::Dxt5 | Self::Bgra => 8,
}
}
}
/// Options for turning RGBA pixels into a BLP container.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct EncodeOptions {
/// Container version, pixel encoding, and encoding-specific settings.
pub format: EncodeFormat,
/// Generate mipmaps when encoding an image; validate a complete chain when encoding supplied levels.
pub mipmaps: bool,
}
impl Default for EncodeOptions {
fn default() -> Self {
Self {
format: EncodeFormat::Indexed {
version: BlpVersion::Blp1,
alpha: IndexedAlpha::Bit8,
},
mipmaps: true,
}
}
}
/// An image or option that cannot be encoded as the requested BLP format.
#[derive(Debug)]
pub enum EncodeError {
/// A supplied image has zero or unsupported dimensions.
InvalidDimensions,
/// JPEG quality is outside the inclusive range 1 through 100.
InvalidJpegQuality,
/// The mipmap count or dimensions do not form the requested chain.
InvalidMipmaps,
/// The encoded image exceeds the supported size limit.
LimitExceeded,
/// The JPEG encoder failed; the contained string describes its failure.
Jpeg(String),
}
impl fmt::Display for EncodeError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::InvalidDimensions => f.write_str("invalid BLP image dimensions"),
Self::InvalidJpegQuality => f.write_str("JPEG quality must be 1 through 100"),
Self::InvalidMipmaps => f.write_str("invalid BLP mipmap sequence"),
Self::LimitExceeded => f.write_str("BLP image exceeds size limit"),
Self::Jpeg(message) => write!(f, "BLP JPEG encoding failed: {message}"),
}
}
}
impl Error for EncodeError {}
fn validate(images: &[RgbaImage], options: EncodeOptions) -> Result<(), EncodeError> {
mipmaps::validate(images, options.mipmaps)?;
if let EncodeFormat::Jpeg { quality, .. } = options.format {
if !(1..=100).contains(&quality) {
return Err(EncodeError::InvalidJpegQuality);
}
}
Ok(())
}
impl Blp {
/// Encodes an RGBA image, optionally generating mipmaps through 1×1.
pub fn encode_image(image: &RgbaImage, options: EncodeOptions) -> Result<Self, EncodeError> {
let images = mipmaps::generate(image, options.mipmaps);
Self::encode_mipmaps(&images, options)
}
/// Encodes a caller-supplied mipmap sequence, with level zero first.
///
/// Each subsequent level must halve both dimensions, clamped to one pixel.
/// When `options.mipmaps` is enabled, the chain must end at 1×1; otherwise
/// exactly one image is required. At most 16 levels are accepted.
/// Returns an error for invalid dimensions, chains, or JPEG settings.
pub fn encode_mipmaps(
images: &[RgbaImage],
options: EncodeOptions,
) -> Result<Self, EncodeError> {
validate(images, options)?;
let mut mips: [Option<Vec<u8>>; MIPMAP_SLOTS] = std::array::from_fn(|_| None);
let palette = if matches!(options.format, EncodeFormat::Indexed { .. }) {
let (palette, encoded) = indexed::encode(images, options.format.alpha_bits());
for (slot, mip) in mips.iter_mut().zip(encoded) {
*slot = Some(mip);
}
Some(palette)
} else {
for (slot, image) in mips.iter_mut().zip(images) {
*slot = Some(match options.format {
EncodeFormat::Jpeg { alpha, quality, .. } => {
jpeg::encode(image, u8::from(alpha) * 8, quality)?
}
EncodeFormat::Dxt1 { alpha } => {
dxt::encode(image, DxtFormat::Dxt1, u8::from(alpha))
}
EncodeFormat::Dxt3 => dxt::encode(image, DxtFormat::Dxt3, 4),
EncodeFormat::Dxt5 => dxt::encode(image, DxtFormat::Dxt5, 8),
EncodeFormat::Bgra => bgra::encode(image),
EncodeFormat::Indexed { .. } => unreachable!(),
});
}
None
};
Ok(assemble::container(
images[0].width(),
images[0].height(),
options.format,
palette,
mips,
))
}
}