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
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
//! Optional conversion of encoded BLP mipmaps to and from RGBA pixels.
use super::super::{Blp, Blp1ContentRef, Blp1Ref, Blp2ContentRef, Blp2Ref, BlpRef, MIPMAP_SLOTS};
use super::{bgra, dxt, indexed, jpeg};
use image::RgbaImage;
use std::{error::Error, fmt};
/// Maximum decoded RGBA buffer size, including JPEG decoder output.
pub(super) const MAX_DECODE_BYTES: usize = 512 * 1024 * 1024;
/// A failure while converting an encoded mipmap to RGBA pixels.
#[derive(Debug)]
pub enum DecodeError {
/// A required or requested mipmap level is absent.
MissingMipmap {
/// Zero-based mipmap level, with level zero at full resolution.
level: usize,
},
/// An image dimension is zero or the mipmap dimensions are invalid.
InvalidDimensions,
/// Encoded pixels or the supplied output buffer have an invalid layout.
InvalidData {
/// Name of the invalid field.
field: &'static str,
},
/// The requested alpha depth is unsupported by the pixel decoder.
UnsupportedAlphaDepth {
/// Unsupported alpha depth, in bits per pixel.
depth: u32,
},
/// The image exceeds the allocation or size limit.
LimitExceeded,
/// The JPEG codec failed; the contained string describes its failure.
Jpeg(String),
/// The JPEG stream does not have the four unconverted components required by BLP.
UnsupportedJpegColor,
}
impl fmt::Display for DecodeError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::MissingMipmap { level } => write!(f, "missing BLP mipmap {level}"),
Self::InvalidDimensions => f.write_str("invalid BLP mipmap dimensions"),
Self::InvalidData { field } => write!(f, "invalid BLP {field}"),
Self::UnsupportedAlphaDepth { depth } => {
write!(f, "unsupported BLP alpha depth {depth}")
}
Self::LimitExceeded => f.write_str("BLP decoded image exceeds the size limit"),
Self::Jpeg(message) => write!(f, "BLP JPEG decode failed: {message}"),
Self::UnsupportedJpegColor => {
f.write_str("BLP JPEG does not contain four unconverted components")
}
}
}
}
impl Error for DecodeError {}
pub(super) fn dimensions(width: u32, height: u32, level: usize) -> Result<(u32, u32), DecodeError> {
if width == 0 || height == 0 || level >= MIPMAP_SLOTS {
return Err(DecodeError::InvalidDimensions);
}
let width = (width >> level).max(1);
let height = (height >> level).max(1);
rgba_len(width, height)?;
Ok((width, height))
}
fn rgba_len(width: u32, height: u32) -> Result<usize, DecodeError> {
let len = usize::try_from(width)
.ok()
.and_then(|width| {
usize::try_from(height)
.ok()
.and_then(|height| width.checked_mul(height))
})
.and_then(|pixels| pixels.checked_mul(4))
.ok_or(DecodeError::LimitExceeded)?;
if len > MAX_DECODE_BYTES {
return Err(DecodeError::LimitExceeded);
}
Ok(len)
}
pub(super) fn output(width: u32, height: u32) -> Result<Vec<u8>, DecodeError> {
let len = rgba_len(width, height)?;
let mut pixels = Vec::new();
pixels
.try_reserve_exact(len)
.map_err(|_| DecodeError::LimitExceeded)?;
pixels.resize(len, 0);
Ok(pixels)
}
pub(super) fn image(width: u32, height: u32, pixels: Vec<u8>) -> Result<RgbaImage, DecodeError> {
RgbaImage::from_raw(width, height, pixels).ok_or(DecodeError::InvalidDimensions)
}
fn check_output(pixels: &[u8], width: u32, height: u32) -> Result<(), DecodeError> {
if pixels.len() != rgba_len(width, height)? {
return Err(DecodeError::InvalidData {
field: "RGBA output size",
});
}
Ok(())
}
fn mip<'a>(mips: &[Option<&'a [u8]>; MIPMAP_SLOTS], level: usize) -> Result<&'a [u8], DecodeError> {
mips.get(level)
.and_then(|mip| *mip)
.ok_or(DecodeError::MissingMipmap { level })
}
impl Blp1Ref<'_> {
/// Decodes one present mipmap to an image-rs RGBA image.
///
/// `level` is zero-based, with level zero at full resolution. Returns an
/// error for missing levels, malformed pixels, or exceeded allocation limits.
pub fn decode_mip(&self, level: usize) -> Result<RgbaImage, DecodeError> {
let (width, height) = dimensions(self.header.width, self.header.height, level)?;
let mut pixels = output(width, height)?;
self.decode_mip_into(level, &mut pixels)?;
image(width, height, pixels)
}
/// Decodes one present mipmap into a caller-provided RGBA8 buffer.
///
/// `level` is zero-based. The buffer must contain exactly four bytes per
/// pixel at that level, in row-major red, green, blue, alpha order.
/// Invalid dimensions, missing levels, malformed pixels, or an incorrectly
/// sized buffer return an error.
pub fn decode_mip_into(&self, level: usize, pixels: &mut [u8]) -> Result<(), DecodeError> {
let (width, height) = dimensions(self.header.width, self.header.height, level)?;
check_output(pixels, width, height)?;
let data = mip(&self.mipmaps, level)?;
match self.content {
Blp1ContentRef::Indexed { palette } => {
indexed::decode_into(data, palette, self.header.alpha_bits, pixels)
}
Blp1ContentRef::Jpeg { shared_header } => jpeg::decode_into(
data,
shared_header,
self.header.alpha_bits == 0,
width,
height,
pixels,
),
}
}
}
impl Blp2Ref<'_> {
/// Decodes one present mipmap to an image-rs RGBA image.
///
/// `level` is zero-based, with level zero at full resolution. Returns an
/// error for missing levels, malformed pixels, or exceeded allocation limits.
pub fn decode_mip(&self, level: usize) -> Result<RgbaImage, DecodeError> {
let (width, height) = dimensions(self.header.width, self.header.height, level)?;
let mut pixels = output(width, height)?;
self.decode_mip_into(level, &mut pixels)?;
image(width, height, pixels)
}
/// Decodes one present mipmap into a caller-provided RGBA8 buffer.
///
/// `level` is zero-based. The buffer must contain exactly four bytes per
/// pixel at that level, in row-major red, green, blue, alpha order.
/// Invalid dimensions, missing levels, malformed pixels, or an incorrectly
/// sized buffer return an error.
pub fn decode_mip_into(&self, level: usize, pixels: &mut [u8]) -> Result<(), DecodeError> {
let (width, height) = dimensions(self.header.width, self.header.height, level)?;
check_output(pixels, width, height)?;
let data = mip(&self.mipmaps, level)?;
match self.content {
Blp2ContentRef::Indexed { palette, .. } => {
indexed::decode_into(data, palette, u32::from(self.header.alpha_bits), pixels)
}
Blp2ContentRef::Jpeg { shared_header, .. } => jpeg::decode_into(
data,
shared_header,
self.header.alpha_bits == 0,
width,
height,
pixels,
),
Blp2ContentRef::Dxt { format, .. } => dxt::decode_into(
data,
format,
self.header.alpha_bits != 0,
width,
height,
pixels,
),
Blp2ContentRef::Bgra { .. } => bgra::decode_into(data, pixels),
}
}
}
impl BlpRef<'_> {
/// Decodes one present mipmap to an image-rs RGBA image.
///
/// `level` is zero-based, with level zero at full resolution. Returns an
/// error for missing levels, malformed pixels, or exceeded allocation limits.
pub fn decode_mip(&self, level: usize) -> Result<RgbaImage, DecodeError> {
match self {
Self::Blp1(value) => value.decode_mip(level),
Self::Blp2(value) => value.decode_mip(level),
}
}
/// Decodes one present mipmap into a caller-provided RGBA8 buffer.
///
/// `level` is zero-based. The buffer must contain exactly four bytes per
/// pixel at that level, in row-major red, green, blue, alpha order.
/// Invalid dimensions, missing levels, malformed pixels, or an incorrectly
/// sized buffer return an error.
pub fn decode_mip_into(&self, level: usize, pixels: &mut [u8]) -> Result<(), DecodeError> {
match self {
Self::Blp1(value) => value.decode_mip_into(level, pixels),
Self::Blp2(value) => value.decode_mip_into(level, pixels),
}
}
}
impl Blp {
/// Decodes one present mipmap to an image-rs RGBA image.
///
/// `level` is zero-based, with level zero at full resolution. Returns an
/// error for missing levels, malformed pixels, or exceeded allocation limits.
pub fn decode_mip(&self, level: usize) -> Result<RgbaImage, DecodeError> {
self.as_ref().decode_mip(level)
}
/// Decodes one present mipmap into a caller-provided RGBA8 buffer.
///
/// `level` is zero-based. The buffer must contain exactly four bytes per
/// pixel at that level, in row-major red, green, blue, alpha order.
/// Invalid dimensions, missing levels, malformed pixels, or an incorrectly
/// sized buffer return an error.
pub fn decode_mip_into(&self, level: usize, pixels: &mut [u8]) -> Result<(), DecodeError> {
self.as_ref().decode_mip_into(level, pixels)
}
}