Debian Codegraph @

.cargo/vendor/image/src/codecs/dxt.rs

raw
1 //! Decoding of DXT (S3TC) compression
2 //!
3 //! DXT is an image format that supports lossy compression
4 //!
5 //! # Related Links
6 //! * <https://www.khronos.org/registry/OpenGL/extensions/EXT/EXT_texture_compression_s3tc.txt> - Description of the DXT compression OpenGL extensions.
7 //!
8 //! Note: this module only implements bare DXT encoding/decoding, it does not parse formats that can contain DXT files like .dds
9
10 use std::io::{self, Read};
11
12 use crate::color::ColorType;
13 use crate::error::{ImageError, ImageResult, ParameterError, ParameterErrorKind};
14 use crate::io::ReadExt;
15 use crate::ImageDecoder;
16
17 /// What version of DXT compression are we using?
18 /// Note that DXT2 and DXT4 are left away as they're
19 /// just DXT3 and DXT5 with premultiplied alpha
20 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
21 pub(crate) enum DxtVariant {
22 /// The DXT1 format. 48 bytes of RGB data in a 4x4 pixel square is
23 /// compressed into an 8 byte block of DXT1 data
24 DXT1,
25 /// The DXT3 format. 64 bytes of RGBA data in a 4x4 pixel square is
26 /// compressed into a 16 byte block of DXT3 data
27 DXT3,
28 /// The DXT5 format. 64 bytes of RGBA data in a 4x4 pixel square is
29 /// compressed into a 16 byte block of DXT5 data
30 DXT5,
31 }
32
33 impl DxtVariant {
34 /// Returns the amount of bytes of raw image data
35 /// that is encoded in a single DXTn block
36 fn decoded_bytes_per_block(self) -> usize {
37 match self {
38 DxtVariant::DXT1 => 48,
39 DxtVariant::DXT3 | DxtVariant::DXT5 => 64,
40 }
41 }
42
43 /// Returns the amount of bytes per block of encoded DXTn data
44 fn encoded_bytes_per_block(self) -> usize {
45 match self {
46 DxtVariant::DXT1 => 8,
47 DxtVariant::DXT3 | DxtVariant::DXT5 => 16,
48 }
49 }
50
51 /// Returns the color type that is stored in this DXT variant
52 pub(crate) fn color_type(self) -> ColorType {
53 match self {
54 DxtVariant::DXT1 => ColorType::Rgb8,
55 DxtVariant::DXT3 | DxtVariant::DXT5 => ColorType::Rgba8,
56 }
57 }
58 }
59
60 /// DXT decoder
61 pub(crate) struct DxtDecoder<R: Read> {
62 inner: R,
63 width_blocks: u32,
64 height_blocks: u32,
65 variant: DxtVariant,
66 row: u32,
67 }
68
69 impl<R: Read> DxtDecoder<R> {
70 /// Create a new DXT decoder that decodes from the stream ```r```.
71 /// As DXT is often stored as raw buffers with the width/height
72 /// somewhere else the width and height of the image need
73 /// to be passed in ```width``` and ```height```, as well as the
74 /// DXT variant in ```variant```.
75 /// width and height are required to be powers of 2 and at least 4.
76 /// otherwise an error will be returned
77 pub(crate) fn new(
78 r: R,
79 width: u32,
80 height: u32,
81 variant: DxtVariant,
82 ) -> Result<DxtDecoder<R>, ImageError> {
83 if width % 4 != 0 || height % 4 != 0 {
84 // TODO: this is actually a bit of a weird case. We could return `DecodingError` but
85 // it's not really the format that is wrong However, the encoder should surely return
86 // `EncodingError` so it would be the logical choice for symmetry.
87 return Err(ImageError::Parameter(ParameterError::from_kind(
88 ParameterErrorKind::DimensionMismatch,
89 )));
90 }
91 let width_blocks = width / 4;
92 let height_blocks = height / 4;
93 Ok(DxtDecoder {
94 inner: r,
95 width_blocks,
96 height_blocks,
97 variant,
98 row: 0,
99 })
100 }
101
102 fn scanline_bytes(&self) -> u64 {
103 self.variant.decoded_bytes_per_block() as u64 * u64::from(self.width_blocks)
104 }
105
106 fn read_scanline(&mut self, buf: &mut [u8]) -> io::Result<usize> {
107 assert_eq!(
108 u64::try_from(buf.len()),
109 Ok(
110 #[allow(deprecated)]
111 self.scanline_bytes()
112 )
113 );
114
115 let len = self.variant.encoded_bytes_per_block() * self.width_blocks as usize;
116 let mut src = Vec::new();
117 self.inner.read_exact_vec(&mut src, len)?;
118
119 match self.variant {
120 DxtVariant::DXT1 => decode_dxt1_row(&src, buf),
121 DxtVariant::DXT3 => decode_dxt3_row(&src, buf),
122 DxtVariant::DXT5 => decode_dxt5_row(&src, buf),
123 }
124 self.row += 1;
125 Ok(buf.len())
126 }
127 }
128
129 // Note that, due to the way that DXT compression works, a scanline is considered to consist out of
130 // 4 lines of pixels.
131 impl<R: Read> ImageDecoder for DxtDecoder<R> {
132 fn dimensions(&self) -> (u32, u32) {
133 (self.width_blocks * 4, self.height_blocks * 4)
134 }
135
136 fn color_type(&self) -> ColorType {
137 self.variant.color_type()
138 }
139
140 fn read_image(mut self, buf: &mut [u8]) -> ImageResult<()> {
141 assert_eq!(u64::try_from(buf.len()), Ok(self.total_bytes()));
142
143 #[allow(deprecated)]
144 for chunk in buf.chunks_mut(self.scanline_bytes().max(1) as usize) {
145 self.read_scanline(chunk)?;
146 }
147 Ok(())
148 }
149
150 fn read_image_boxed(self: Box<Self>, buf: &mut [u8]) -> ImageResult<()> {
151 (*self).read_image(buf)
152 }
153 }
154
155 /**
156 * Actual encoding/decoding logic below.
157 */
158 type Rgb = [u8; 3];
159
160 /// decodes a 5-bit R, 6-bit G, 5-bit B 16-bit packed color value into 8-bit RGB
161 /// mapping is done so min/max range values are preserved. So for 5-bit
162 /// values 0x00 -> 0x00 and 0x1F -> 0xFF
163 fn enc565_decode(value: u16) -> Rgb {
164 let red = (value >> 11) & 0x1F;
165 let green = (value >> 5) & 0x3F;
166 let blue = (value) & 0x1F;
167 [
168 (red * 0xFF / 0x1F) as u8,
169 (green * 0xFF / 0x3F) as u8,
170 (blue * 0xFF / 0x1F) as u8,
171 ]
172 }
173
174 /*
175 * Functions for decoding DXT compression
176 */
177
178 /// Constructs the DXT5 alpha lookup table from the two alpha entries
179 /// if alpha0 > alpha1, constructs a table of [a0, a1, 6 linearly interpolated values from a0 to a1]
180 /// if alpha0 <= alpha1, constructs a table of [a0, a1, 4 linearly interpolated values from a0 to a1, 0, 0xFF]
181 fn alpha_table_dxt5(alpha0: u8, alpha1: u8) -> [u8; 8] {
182 let mut table = [alpha0, alpha1, 0, 0, 0, 0, 0, 0xFF];
183 if alpha0 > alpha1 {
184 for i in 2..8u16 {
185 table[i as usize] =
186 (((8 - i) * u16::from(alpha0) + (i - 1) * u16::from(alpha1)) / 7) as u8;
187 }
188 } else {
189 for i in 2..6u16 {
190 table[i as usize] =
191 (((6 - i) * u16::from(alpha0) + (i - 1) * u16::from(alpha1)) / 5) as u8;
192 }
193 }
194 table
195 }
196
197 /// decodes an 8-byte dxt color block into the RGB channels of a 16xRGB or 16xRGBA block.
198 /// source should have a length of 8, dest a length of 48 (RGB) or 64 (RGBA)
199 #[allow(clippy::needless_range_loop)] // False positive, the 0..3 loop is not an enumerate
200 fn decode_dxt_colors(source: &[u8], dest: &mut [u8], is_dxt1: bool) {
201 // sanity checks, also enable the compiler to elide all following bound checks
202 assert!(source.len() == 8 && (dest.len() == 48 || dest.len() == 64));
203 // calculate pitch to store RGB values in dest (3 for RGB, 4 for RGBA)
204 let pitch = dest.len() / 16;
205
206 // extract color data
207 let color0 = u16::from(source[0]) | (u16::from(source[1]) << 8);
208 let color1 = u16::from(source[2]) | (u16::from(source[3]) << 8);
209 let color_table = u32::from(source[4])
210 | (u32::from(source[5]) << 8)
211 | (u32::from(source[6]) << 16)
212 | (u32::from(source[7]) << 24);
213 // let color_table = source[4..8].iter().rev().fold(0, |t, &b| (t << 8) | b as u32);
214
215 // decode the colors to rgb format
216 let mut colors = [[0; 3]; 4];
217 colors[0] = enc565_decode(color0);
218 colors[1] = enc565_decode(color1);
219
220 // determine color interpolation method
221 if color0 > color1 || !is_dxt1 {
222 // linearly interpolate the other two color table entries
223 for i in 0..3 {
224 colors[2][i] = ((u16::from(colors[0][i]) * 2 + u16::from(colors[1][i]) + 1) / 3) as u8;
225 colors[3][i] = ((u16::from(colors[0][i]) + u16::from(colors[1][i]) * 2 + 1) / 3) as u8;
226 }
227 } else {
228 // linearly interpolate one other entry, keep the other at 0
229 for i in 0..3 {
230 colors[2][i] = (u16::from(colors[0][i]) + u16::from(colors[1][i])).div_ceil(2) as u8;
231 }
232 }
233
234 // serialize the result. Every color is determined by looking up
235 // two bits in color_table which identify which color to actually pick from the 4 possible colors
236 for i in 0..16 {
237 dest[i * pitch..i * pitch + 3]
238 .copy_from_slice(&colors[(color_table >> (i * 2)) as usize & 3]);
239 }
240 }
241
242 /// Decodes a 16-byte bock of dxt5 data to a 16xRGBA block
243 fn decode_dxt5_block(source: &[u8], dest: &mut [u8]) {
244 assert!(source.len() == 16 && dest.len() == 64);
245
246 // extract alpha index table (stored as little endian 64-bit value)
247 let alpha_table = source[2..8]
248 .iter()
249 .rev()
250 .fold(0, |t, &b| (t << 8) | u64::from(b));
251
252 // alpha level decode
253 let alphas = alpha_table_dxt5(source[0], source[1]);
254
255 // serialize alpha
256 for i in 0..16 {
257 dest[i * 4 + 3] = alphas[(alpha_table >> (i * 3)) as usize & 7];
258 }
259
260 // handle colors
261 decode_dxt_colors(&source[8..16], dest, false);
262 }
263
264 /// Decodes a 16-byte bock of dxt3 data to a 16xRGBA block
265 fn decode_dxt3_block(source: &[u8], dest: &mut [u8]) {
266 assert!(source.len() == 16 && dest.len() == 64);
267
268 // extract alpha index table (stored as little endian 64-bit value)
269 let alpha_table = source[0..8]
270 .iter()
271 .rev()
272 .fold(0, |t, &b| (t << 8) | u64::from(b));
273
274 // serialize alpha (stored as 4-bit values)
275 for i in 0..16 {
276 dest[i * 4 + 3] = ((alpha_table >> (i * 4)) as u8 & 0xF) * 0x11;
277 }
278
279 // handle colors
280 decode_dxt_colors(&source[8..16], dest, false);
281 }
282
283 /// Decodes a 8-byte bock of dxt5 data to a 16xRGB block
284 fn decode_dxt1_block(source: &[u8], dest: &mut [u8]) {
285 assert!(source.len() == 8 && dest.len() == 48);
286 decode_dxt_colors(source, dest, true);
287 }
288
289 /// Decode a row of DXT1 data to four rows of RGB data.
290 /// `source.len()` should be a multiple of 8, otherwise this panics.
291 fn decode_dxt1_row(source: &[u8], dest: &mut [u8]) {
292 assert!(source.len() % 8 == 0);
293 let block_count = source.len() / 8;
294 assert!(dest.len() >= block_count * 48);
295
296 // contains the 16 decoded pixels per block
297 let mut decoded_block = [0u8; 48];
298
299 for (x, encoded_block) in source.chunks(8).enumerate() {
300 decode_dxt1_block(encoded_block, &mut decoded_block);
301
302 // copy the values from the decoded block to linewise RGB layout
303 for line in 0..4 {
304 let offset = (block_count * line + x) * 12;
305 dest[offset..offset + 12].copy_from_slice(&decoded_block[line * 12..(line + 1) * 12]);
306 }
307 }
308 }
309
310 /// Decode a row of DXT3 data to four rows of RGBA data.
311 /// `source.len()` should be a multiple of 16, otherwise this panics.
312 fn decode_dxt3_row(source: &[u8], dest: &mut [u8]) {
313 assert!(source.len() % 16 == 0);
314 let block_count = source.len() / 16;
315 assert!(dest.len() >= block_count * 64);
316
317 // contains the 16 decoded pixels per block
318 let mut decoded_block = [0u8; 64];
319
320 for (x, encoded_block) in source.chunks(16).enumerate() {
321 decode_dxt3_block(encoded_block, &mut decoded_block);
322
323 // copy the values from the decoded block to linewise RGB layout
324 for line in 0..4 {
325 let offset = (block_count * line + x) * 16;
326 dest[offset..offset + 16].copy_from_slice(&decoded_block[line * 16..(line + 1) * 16]);
327 }
328 }
329 }
330
331 /// Decode a row of DXT5 data to four rows of RGBA data.
332 /// `source.len()` should be a multiple of 16, otherwise this panics.
333 fn decode_dxt5_row(source: &[u8], dest: &mut [u8]) {
334 assert!(source.len() % 16 == 0);
335 let block_count = source.len() / 16;
336 assert!(dest.len() >= block_count * 64);
337
338 // contains the 16 decoded pixels per block
339 let mut decoded_block = [0u8; 64];
340
341 for (x, encoded_block) in source.chunks(16).enumerate() {
342 decode_dxt5_block(encoded_block, &mut decoded_block);
343
344 // copy the values from the decoded block to linewise RGB layout
345 for line in 0..4 {
346 let offset = (block_count * line + x) * 16;
347 dest[offset..offset + 16].copy_from_slice(&decoded_block[line * 16..(line + 1) * 16]);
348 }
349 }
350 }