DDS: encode and decode faster with the same bytes

Encoding:
- colour blocks keep their colours and endpoint candidates on the stack
  instead of in per-block vectors (the idea of storytold/photocraft#10669)
- a refinement round whose endpoint pair was already fitted ends the
  search, which could not change the block any more
- a block of one colour skips the principal-axis search, whose result
  for it is that colour at both ends
- the alpha block gathers its 16 values once, finds both ranges in one
  pass and picks indices in a plain loop with the same tie-break
- the nearest palette colour is found the same way
- interior blocks are gathered as four rows of four texels, and
  interior mip pixels average their 2x2 source pixels directly

Decoding:
- block-compressed data is decoded one row of blocks per task, copying
  whole texel rows and checking bounds only on the right edge
- uncompressed rows are decoded one per task; when every channel is a
  whole byte (RGBA, BGRA, BGRX, luminance), pixels are a byte shuffle

The f32 arithmetic and its order are unchanged; the digest oracle pins
the output.
This commit is contained in:
vangel76 committed 2026-11-16 00:00:28 +01:00
1 parent a98aa0b462
commit e22ccf3511
4 files changed
+229 -64

No files matched your search

+1 -1
View File
@@ -12,7 +12,7 @@ workspace = true
[features]
default = []
# Encode rows of blocks and mip levels on several threads.
# Encode and decode rows of blocks (and mip levels) on several threads.
parallel = ["dep:rayon"]
[dependencies]
+1 -1
View File
@@ -39,5 +39,5 @@ under half opacity into its transparent black, and BC3 picks whichever alpha mod
## Features
- `parallel`: encodes rows of blocks and mip levels on several threads with rayon.
- `parallel`: encodes and decodes rows of blocks (and mip levels) on several threads with rayon.
`craft-image-codecs` turns it on for native targets.
+101 -30
View File
@@ -69,7 +69,8 @@ pub(crate) fn encode_bc2(block: &Block, inside: Mask) -> [u8; 16] {
/// A BC3 block: an interpolated alpha block, then a four-colour block.
pub(crate) fn encode_bc3(block: &Block, inside: Mask) -> [u8; 16] {
join(alpha_block(block, inside), colour_block(block, inside, 0, false))
let alphas = std::array::from_fn(|t| block[t][3]);
join(value_block(&alphas, inside), colour_block(block, inside, 0, false))
}
fn join(a: [u8; 8], b: [u8; 8]) -> [u8; 16] {
@@ -92,21 +93,56 @@ fn to565(c: [f32; 3]) -> u16 {
}
fn distance(a: &[u8; 4], b: &[u8; 4]) -> u32 {
(0..3).map(|i| u32::from(a[i].abs_diff(b[i])).pow(2)).sum()
let d = |i: usize| u32::from(a[i].abs_diff(b[i])).pow(2);
d(0) + d(1) + d(2)
}
/// The index of the first of `palette`'s entries nearest by `distance`, and that distance: the
/// entry `Iterator::min_by_key` picks, found without the iterator (a texel equal to an entry
/// stops the search, as no later entry can be nearer and an equal one doesn't win).
fn nearest<T>(palette: &[T], distance: impl Fn(&T) -> u32) -> (usize, u32) {
let mut best = (0, u32::MAX);
for (i, p) in palette.iter().enumerate() {
let d = distance(p);
if d < best.1 {
best = (i, d);
if d == 0 {
break;
}
}
}
if palette.is_empty() { (0, 0) } else { best }
}
/// A colour block (endpoints, then 2-bit indices) for the `opaque` texels' colours, with the
/// `transparent` ones on BC1's transparent index. `bc1` allows the three-colour mode; BC2 and
/// BC3 always decode four colours.
fn colour_block(block: &Block, opaque: Mask, transparent: Mask, bc1: bool) -> [u8; 8] {
let colours: Vec<[f32; 3]> = block.iter().enumerate().filter(|(t, _)| opaque >> t & 1 != 0).map(|(_, texel)| rgb_of(texel)).collect();
if colours.is_empty() {
// The opaque texels' colours in texel order, on the stack (after storytold/photocraft#10669,
// which took the per-block allocations out of PhotoCraft's copy of this encoder).
let mut buffer = [[0f32; 3]; 16];
let mut n = 0;
for (t, texel) in block.iter().enumerate() {
if opaque >> t & 1 != 0
&& let Some(slot) = buffer.get_mut(n)
{
*slot = rgb_of(texel);
n += 1;
}
}
let colours = buffer.get(..n).unwrap_or_default();
let Some((first, rest)) = colours.split_first() else {
// Nothing visible: every texel on the transparent index (or index 0 of black).
let indices = if transparent != 0 { u32::MAX } else { 0 };
return pack(0, 0, indices);
}
let (lo, hi) = principal_endpoints(&colours);
let mut candidates = vec![(to565(lo), to565(hi))];
};
// One colour has no axis: `principal_endpoints` returns that colour (their mean) for both
// ends, so it is skipped. Everything after it runs as for any block.
let (lo, hi) = if rest.iter().all(|c| c == first) { (*first, *first) } else { principal_endpoints(colours) };
let mut candidate = (to565(lo), to565(hi));
// The endpoint pairs fitted so far: at most one per round.
let mut fitted = [candidate; 3];
let mut count = 1;
let modes: &[bool] = if transparent != 0 {
&[false]
} else if bc1 {
@@ -118,22 +154,30 @@ fn colour_block(block: &Block, opaque: Mask, transparent: Mask, bc1: bool) -> [u
// Each refinement starts from the best block so far: its indices give the least-squares
// endpoints, which become one more candidate.
for round in 0..3 {
for &(e0, e1) in &candidates {
for &four in modes {
let (bytes, error) = fit(block, opaque, transparent, e0, e1, four);
if best.is_none_or(|(e, _)| error < e) {
best = Some((error, bytes));
}
let (e0, e1) = candidate;
for &four in modes {
let (bytes, error) = fit(block, opaque, transparent, e0, e1, four);
if best.is_none_or(|(e, _)| error < e) {
best = Some((error, bytes));
}
}
let Some((error, bytes)) = best else { break };
if error == 0 || round == 2 {
break;
}
candidates = least_squares(block, opaque, &bytes).into_iter().collect();
if candidates.is_empty() {
let Some(next) = least_squares(block, opaque, &bytes) else { break };
// A pair fitted before (in either order: `fit` orders the endpoints itself) fits the same
// again and can't beat the best block, which then gives the same pair again: the rounds
// left would change nothing.
let seen = fitted.get(..count).unwrap_or_default();
if seen.iter().any(|&(a, b)| (a, b) == next || (b, a) == next) {
break;
}
if let Some(slot) = fitted.get_mut(count) {
*slot = next;
count += 1;
}
candidate = next;
}
best.map_or([0; 8], |(_, bytes)| bytes)
}
@@ -151,7 +195,7 @@ fn fit(block: &Block, opaque: Mask, transparent: Mask, e0: u16, e1: u16, four: b
let index = if transparent >> t & 1 != 0 {
3
} else if opaque >> t & 1 != 0 {
let (i, d) = palette.iter().take(choices).enumerate().map(|(i, p)| (i, distance(texel, p))).min_by_key(|&(_, d)| d).unwrap_or((0, 0));
let (i, d) = nearest(palette.get(..choices).unwrap_or_default(), |p| distance(texel, p));
error += d;
i as u32
} else {
@@ -248,29 +292,39 @@ fn least_squares(block: &Block, opaque: Mask, bytes: &[u8; 8]) -> Option<(u16, u
Some((to565(e0), to565(e1)))
}
/// A BC3 alpha block: whichever of the two modes (eight values between the extremes, or six
/// between the extremes other than 0 and 255, plus exact 0 and 255) fits better.
fn alpha_block(block: &Block, inside: Mask) -> [u8; 8] {
let alphas = || block.iter().enumerate().filter(move |(t, _)| inside >> t & 1 != 0).map(|(_, texel)| texel[3]);
let range =
|values: &mut dyn Iterator<Item = u8>| values.fold(None, |r: Option<(u8, u8)>, a| Some(r.map_or((a, a), |(lo, hi)| (lo.min(a), hi.max(a)))));
let (lo, hi) = range(&mut alphas()).unwrap_or((0, 0));
/// An interpolated block of 16 single-channel values (BC3's alpha): whichever of the two modes
/// (eight values between the extremes, or six between the extremes other than 0 and 255, plus
/// exact 0 and 255) fits better. Only the values of `inside` count.
pub(crate) fn value_block(values: &[u8; 16], inside: Mask) -> [u8; 8] {
// Both ranges in one pass: of all values, and of those other than 0 and 255.
let mut all: Option<(u8, u8)> = None;
let mut mid = all;
let widen = |r: Option<(u8, u8)>, v: u8| Some(r.map_or((v, v), |(lo, hi)| (lo.min(v), hi.max(v))));
for (t, &v) in values.iter().enumerate() {
if inside >> t & 1 != 0 {
all = widen(all, v);
if !matches!(v, 0 | 255) {
mid = widen(mid, v);
}
}
}
let (lo, hi) = all.unwrap_or((0, 0));
// Eight values need a0 > a1; equal ends fall to the six-value mode, which starts with a0 too.
let eight = alpha_fit(block, inside, hi, lo);
let (mid_lo, mid_hi) = range(&mut alphas().filter(|a| !matches!(a, 0 | 255))).unwrap_or((0, 0));
let six = alpha_fit(block, inside, mid_lo, mid_hi);
let eight = value_fit(values, inside, hi, lo);
let (mid_lo, mid_hi) = mid.unwrap_or((0, 0));
let six = value_fit(values, inside, mid_lo, mid_hi);
if six.1 < eight.1 { six.0 } else { eight.0 }
}
fn alpha_fit(block: &Block, inside: Mask, a0: u8, a1: u8) -> ([u8; 8], u32) {
fn value_fit(values: &[u8; 16], inside: Mask, a0: u8, a1: u8) -> ([u8; 8], u32) {
let palette = alpha_palette(a0, a1);
let mut bits = 0u64;
let mut error = 0u32;
for (t, texel) in block.iter().enumerate() {
for (t, &v) in values.iter().enumerate() {
if inside >> t & 1 == 0 {
continue;
}
let (i, d) = palette.iter().enumerate().map(|(i, &p)| (i, u32::from(p.abs_diff(texel[3])).pow(2))).min_by_key(|&(_, d)| d).unwrap_or((0, 0));
let (i, d) = nearest(&palette, |&p| u32::from(p.abs_diff(v)).pow(2));
error += d;
bits |= (i as u64) << (3 * t);
}
@@ -333,7 +387,7 @@ mod tests {
fn alpha_blocks_pick_the_mode_that_keeps_0_and_255() {
// 0, 255 and a cluster in between: the six-value mode stores 0 and 255 exactly.
let block: Block = std::array::from_fn(|t| [0, 0, 0, [0, 255, 100, 110][t % 4]]);
let bytes = alpha_block(&block, u16::MAX);
let bytes = value_block(&block.map(|t| t[3]), u16::MAX);
assert!(bytes[0] <= bytes[1], "six-value mode");
let palette = alpha_palette(bytes[0], bytes[1]);
let bits = u64::from_le_bytes([bytes[2], bytes[3], bytes[4], bytes[5], bytes[6], bytes[7], 0, 0]);
@@ -358,6 +412,23 @@ mod tests {
assert!(ours < bounding_box, "{ours} vs the bounding box's {bounding_box}");
}
#[test]
fn nearest_picks_what_min_by_key_picks() {
// Ties (equal entries, entries equally far on both sides) and exact hits included.
let mut seed = 0x2545_f491u32;
for _ in 0..2000 {
seed ^= seed << 13;
seed ^= seed >> 17;
seed ^= seed << 5;
let palette = [seed as u8 & 0xf0, (seed >> 8) as u8 & 0xf0, (seed >> 16) as u8 & 0xf0, (seed >> 24) as u8 & 0xf0];
let v = (seed >> 4) as u8 & 0xf8;
let d = |p: &u8| u32::from(p.abs_diff(v)).pow(2);
let want = palette.iter().enumerate().map(|(i, p)| (i, d(p))).min_by_key(|&(_, d)| d).unwrap();
assert_eq!(nearest(&palette, d), want, "{palette:?} {v}");
}
assert_eq!(nearest::<u8>(&[], |_| 7), (0, 0));
}
#[test]
fn texels_outside_the_image_are_ignored() {
// Only the top-left texel is inside: its colour alone decides the endpoints.
+126 -32
View File
@@ -11,8 +11,8 @@
//! so no DX10 header is written; formats only DXGI can name (BC4–BC7, sRGB) aren't written.
//!
//! Pixels are 8 bits per channel, interleaved, top row first, in one of the [`Layout`]s. The
//! crate has no dependencies; the `parallel` feature encodes rows of blocks on several threads
//! with rayon.
//! crate has no dependencies; the `parallel` feature encodes and decodes rows of blocks (and mip
//! levels) on several threads with rayon.
//!
//! ```
//! use craft_dds::{DdsCompression, DdsOptions, Layout};
@@ -385,41 +385,104 @@ impl<'a> Texture<'a> {
let total = row_size.checked_mul(h).ok_or_else(|| bad("pixel size overflow"))?;
let mut pixels = vec![0u8; total];
match encoding {
Encoding::Masks { bytes, gray, fields } => {
for (src_row, dst_row) in data.chunks_exact(row_pitch).zip(pixels.chunks_exact_mut(row_size)) {
// Stop at the output width, leaving any stored row padding unread.
for (src, dst) in src_row.chunks_exact(bytes).zip(dst_row.chunks_exact_mut(channels)) {
let pixel = src.iter().rev().fold(0u32, |v, &byte| v << 8 | u32::from(byte));
let channel = |i: usize| fields[i].map_or(0, |f| f.get(pixel));
let values = if gray { [channel(0), channel(3), 0, 0] } else { [channel(0), channel(1), channel(2), channel(3)] };
dst.copy_from_slice(&values[..channels]);
}
Encoding::Masks { bytes, gray, fields } => decode_masks(Masks { bytes, gray, fields }, data, row_pitch, &mut pixels, row_size),
Encoding::Bc1 | Encoding::Bc2 | Encoding::Bc3 => decode_blocks(encoding, data, (w, channels), &mut pixels),
}
Ok(pixels)
}
}
/// An uncompressed pixel format: bytes per pixel, luminance or RGB, and the red (or
/// luminance), green, blue and alpha fields.
struct Masks {
bytes: usize,
gray: bool,
fields: [Option<Field>; 4],
}
/// Uncompressed rows `row_pitch` apart into `pixels` (rows of `row_size` bytes), one row of
/// pixels per task.
fn decode_masks(m: Masks, data: &[u8], row_pitch: usize, pixels: &mut [u8], row_size: usize) {
let Masks { bytes, gray, fields } = m;
let channels = if gray { 1 + usize::from(fields[3].is_some()) } else { 3 + usize::from(fields[3].is_some()) };
// The field each output channel comes from.
let picks = if gray { [0, 3, 0, 0] } else { [0, 1, 2, 3] };
// An 8-bit field on a byte boundary scales to itself, so when every channel is one (or
// absent, and 0) the pixels are a byte shuffle: the byte each channel copies.
let mut at: [Option<usize>; 4] = [None; 4];
let mut whole_bytes = true;
for (slot, &pick) in at.iter_mut().zip(&picks).take(channels) {
match fields.get(pick).copied().flatten() {
None => {}
Some(f) if f.max == 255 && f.shift % 8 == 0 => *slot = Some(f.shift as usize / 8),
Some(_) => whole_bytes = false,
}
}
// Four bytes to four channels, each present: RGBA, BGRA and the like.
let four = (whole_bytes && bytes == 4 && channels == 4 && at.iter().all(Option::is_some)).then(|| at.map(|i| i.unwrap_or(0) & 3));
rows(pixels, row_size, |y, dst_row| {
// Stop at the output width, leaving any stored row padding unread.
let src_row = data.get(y * row_pitch..).unwrap_or_default();
if let Some(order) = four {
let (src, dst) = (src_row.as_chunks::<4>().0, dst_row.as_chunks_mut::<4>().0);
if order == [0, 1, 2, 3] {
for (d, s) in dst.iter_mut().zip(src) {
*d = *s;
}
} else {
for (d, s) in dst.iter_mut().zip(src) {
*d = order.map(|i| s[i]);
}
}
Encoding::Bc1 | Encoding::Bc2 | Encoding::Bc3 => {
let block_size = if matches!(encoding, Encoding::Bc1) { 8 } else { 16 };
let blocks_x = w.div_ceil(4);
for (i, block) in data.chunks_exact(block_size).enumerate() {
let texels = match encoding {
Encoding::Bc1 => bc1(block, true),
Encoding::Bc2 => with_alpha(bc1(block.get(8..).unwrap_or_default(), false), bc2_alpha(block)),
_ => with_alpha(bc1(block.get(8..).unwrap_or_default(), false), bc3_alpha(block)),
};
let (bx, by) = ((i % blocks_x) * 4, (i / blocks_x) * 4);
for (t, texel) in texels.iter().enumerate() {
let (x, y) = (bx + t % 4, by + t / 4);
if x < w && y < h {
let at = (y * w + x) * 4;
if let Some(dst) = pixels.get_mut(at..at + 4) {
dst.copy_from_slice(texel);
}
}
} else if whole_bytes {
for (src, dst) in src_row.chunks_exact(bytes).zip(dst_row.chunks_exact_mut(channels)) {
for (v, i) in dst.iter_mut().zip(at) {
*v = i.and_then(|i| src.get(i)).copied().unwrap_or(0);
}
}
} else {
for (src, dst) in src_row.chunks_exact(bytes).zip(dst_row.chunks_exact_mut(channels)) {
let pixel = src.iter().rev().fold(0u32, |v, &byte| v << 8 | u32::from(byte));
let channel = |i: usize| fields[i].map_or(0, |f| f.get(pixel));
let values = if gray { [channel(0), channel(3), 0, 0] } else { [channel(0), channel(1), channel(2), channel(3)] };
dst.copy_from_slice(&values[..channels]);
}
}
});
}
/// Block-compressed data into `pixels` of `width` × `channels` bytes a row, one row of blocks
/// per task. Blocks wholly inside the image copy whole rows of texels; only those on the right
/// edge check each texel.
fn decode_blocks(encoding: Encoding, data: &[u8], (width, channels): (usize, usize), pixels: &mut [u8]) {
let block_size = if matches!(encoding, Encoding::Bc1) { 8 } else { 16 };
let blocks_x = width.div_ceil(4);
let row_size = width * channels;
rows(pixels, row_size.saturating_mul(4), |by, band| {
let src = data.get(by * blocks_x * block_size..).unwrap_or_default();
for (bx, block) in src.chunks_exact(block_size).take(blocks_x).enumerate() {
let texels = match encoding {
Encoding::Bc1 => bc1(block, true),
Encoding::Bc2 => with_alpha(bc1(block.get(8..).unwrap_or_default(), false), bc2_alpha(block)),
_ => with_alpha(bc1(block.get(8..).unwrap_or_default(), false), bc3_alpha(block)),
};
let x0 = bx * 4;
// The band holds the block's rows that lie inside the image (fewer than four in the
// last band of a height that isn't a multiple of four).
for (line, row) in band.chunks_exact_mut(row_size).zip(texels.as_chunks::<4>().0) {
if x0 + 4 <= width && channels == 4 {
if let Some(dst) = line.get_mut(x0 * 4..x0 * 4 + 16) {
dst.copy_from_slice(row.as_flattened());
}
} else {
let dst = line.get_mut(x0 * channels..).unwrap_or_default();
for (d, texel) in dst.chunks_exact_mut(channels).zip(row) {
d.copy_from_slice(texel.get(..channels).unwrap_or_default());
}
}
}
}
Ok(pixels)
}
});
}
/// A BC1 colour block. BC2 and BC3 colour blocks always have four colours; only BC1's
@@ -683,6 +746,20 @@ fn write_level(store: Store, pixels: &[u8], (width, height): (usize, usize), dst
/// Block (`bx`, `by`)'s texels, and which of them lie inside the image.
fn gather(texels: &[[u8; 4]], (width, height): (usize, usize), bx: usize, by: usize) -> (Block, Mask) {
let mut block = [[0u8; 4]; 16];
// A block wholly inside the image: four rows of four texels.
let (x0, y0) = (bx * 4, by * 4);
if x0 + 4 <= width && y0 + 4 <= height {
let mut copied = 0;
for (ty, row) in block.as_chunks_mut::<4>().0.iter_mut().enumerate() {
if let Some(src) = texels.get((y0 + ty) * width + x0..).and_then(|s| s.first_chunk::<4>()) {
*row = *src;
copied += 1;
}
}
if copied == 4 {
return (block, Mask::MAX);
}
}
let mut inside: Mask = 0;
for (t, texel) in block.iter_mut().enumerate() {
let (x, y) = (bx * 4 + t % 4, by * 4 + t / 4);
@@ -703,9 +780,26 @@ fn downsample(src: &[u8], (w, h): (usize, usize), (nw, nh): (usize, usize), chan
let len = nw.checked_mul(nh).and_then(|n| n.checked_mul(channels)).ok_or_else(|| encode_err("mip level size overflow"))?;
let mut dst = alloc_zeroed(len)?;
let span = |i: usize, n: usize, size: usize| 2 * i..=if i + 1 == n { size.saturating_sub(1) } else { 2 * i + 1 };
let ch = channels.max(1);
let line = w * ch;
rows(&mut dst, nw * channels, |y, row| {
let ys = span(y, nh, h);
for (x, px) in row.chunks_exact_mut(channels.max(1)).enumerate() {
// Every pixel but those of the last column and row averages exactly 2×2: the same sum
// and rounding as below, from two source rows read in step.
let mut edge = 0;
if y + 1 < nh
&& let (Some(r0), Some(r1)) = (src.get(2 * y * line..(2 * y + 1) * line), src.get((2 * y + 1) * line..(2 * y + 2) * line))
{
let interior = nw.saturating_sub(1);
for ((px, a), b) in row.chunks_exact_mut(ch).zip(r0.chunks_exact(2 * ch)).zip(r1.chunks_exact(2 * ch)).take(interior) {
for (c, v) in px.iter_mut().enumerate() {
let sum = u32::from(a[c]) + u32::from(a[ch + c]) + u32::from(b[c]) + u32::from(b[ch + c]);
*v = ((sum + 2) / 4) as u8;
}
}
edge = interior;
}
for (x, px) in row.chunks_exact_mut(ch).enumerate().skip(edge) {
let xs = span(x, nw, w);
for (c, v) in px.iter_mut().enumerate() {
let (mut sum, mut n) = (0u32, 0u32);