Merge pull request #1168 from Blenux/dds/import-options

raster-codecs: DDS header info and bounded mip-chain decoding
This commit is contained in:
FredApps authored and GitHub committed 2026-11-17 16:49:12 +01:00
commit e11ee59ed3
6 files changed
+270 -2

No files matched your search

Generated
+1
View File
@@ -2903,6 +2903,7 @@ name = "craft-raster-codecs"
version = "0.1.0"
dependencies = [
"base64 0.23.1",
"craft-dds",
"craft-image-codecs",
"image",
"thiserror 2.0.21",
+48 -1
View File
@@ -430,6 +430,7 @@ pub struct Texture<'a> {
encoding: Encoding,
/// Where the top level's pixel data starts.
start: usize,
levels: u32,
}
impl<'a> Texture<'a> {
@@ -456,7 +457,8 @@ impl<'a> Texture<'a> {
if width == 0 || height == 0 {
return Err(bad("texture dimensions must be nonzero"));
}
Ok(Texture { bytes: b, flags, width, height, encoding, start })
let levels = le32(b, 28)?.max(1).min(mip_levels(width, height));
Ok(Texture { bytes: b, flags, width, height, encoding, start, levels })
}
pub fn width(&self) -> u32 {
@@ -472,6 +474,51 @@ impl<'a> Texture<'a> {
self.encoding.layout()
}
/// Number of declared mip levels, capped by the chain down to one pixel.
pub fn levels(&self) -> u32 {
self.levels
}
/// The encoding named by the header, including unsigned BC4 and BC5.
pub fn compression(&self) -> DdsCompression {
match self.encoding {
Encoding::Masks { .. } | Encoding::Unorm16 { .. } => DdsCompression::None,
Encoding::Bc1 => DdsCompression::Bc1,
Encoding::Bc2 => DdsCompression::Bc2,
Encoding::Bc3 => DdsCompression::Bc3,
Encoding::Bc4 => DdsCompression::Bc4,
Encoding::Bc5 => DdsCompression::Bc5,
}
}
/// A borrowed view of one mip level, without allocating or decoding pixels.
/// Lower levels are tightly packed; only the top level uses the header's row pitch.
pub fn mip_level(&self, index: u32) -> Result<Texture<'a>, DdsError> {
if index >= self.levels {
return Err(bad("mip level index is outside the declared chain"));
}
let (mut width, mut height, mut start) = (self.width, self.height, self.start);
for i in 0..index {
let pitch = if i == 0 && self.flags & DDSD_PITCH != 0 { Some(le32(self.bytes, 20)?) } else { None };
let (_, size) = self.encoding.level_layout(width, height, pitch)?;
start = start.checked_add(size).ok_or_else(|| bad("mip offset overflow"))?;
if start > self.bytes.len() {
return Err(bad("truncated mip data"));
}
width = (width / 2).max(1);
height = (height / 2).max(1);
}
Ok(Texture {
bytes: self.bytes,
flags: if index == 0 { self.flags } else { self.flags & !DDSD_PITCH },
width,
height,
encoding: self.encoding,
start,
levels: self.levels - index,
})
}
/// The top mip level's pixels in [`Texture::layout`], bounded by [`DEFAULT_MAX_DECODE_BYTES`].
pub fn decode(&self) -> Result<Vec<u8>, DdsError> {
self.decode_with_limit(DEFAULT_MAX_DECODE_BYTES)
+50
View File
@@ -44,3 +44,53 @@ fn default_budget_rejects_oversized_header_before_payload_or_allocation() {
assert!(matches!(texture.decode(), Err(craft_dds::DdsError::LimitExceeded { limit: craft_dds::DEFAULT_MAX_DECODE_BYTES, .. })));
assert!(matches!(texture.decode_with_limit(u64::MAX), Err(craft_dds::DdsError::Malformed(_))));
}
#[test]
fn mip_views_reuse_shared_decoders_and_keep_their_bounds() {
for (compression, layout, channels) in [
(DdsCompression::None, Layout::Gray, 1),
(DdsCompression::Bc1, Layout::Rgba, 4),
(DdsCompression::Bc4, Layout::Gray, 1),
(DdsCompression::Bc5, Layout::Rgb, 3),
] {
let bytes = encode(4, 4, layout, &vec![71; 16 * channels], DdsOptions { compression, mipmaps: true }).unwrap();
let texture = Texture::parse(&bytes).unwrap();
assert_eq!(texture.levels(), 3);
assert_eq!(texture.compression(), compression);
assert!(texture.mip_level(3).is_err());
assert!(texture.mip_level(u32::MAX).is_err());
for (index, side) in [(0, 4), (1, 2), (2, 1)] {
let level = texture.mip_level(index).unwrap();
assert_eq!((level.width(), level.height()), (side, side));
let len = side as usize * side as usize * channels;
assert!(matches!(level.decode_with_limit((len - 1) as u64), Err(craft_dds::DdsError::LimitExceeded { .. })));
assert_eq!(level.decode_with_limit(len as u64).unwrap().len(), len);
}
let nested = texture.mip_level(1).unwrap().mip_level(1).unwrap();
assert_eq!(nested.decode().unwrap(), texture.mip_level(2).unwrap().decode().unwrap());
}
}
#[test]
fn sixteen_bit_mip_views_preserve_samples_and_stored_offsets() {
for (layout, channels) in [(Layout::Gray, 1), (Layout::GrayA, 2), (Layout::Rgba, 4)] {
let pixels: Vec<u16> = (0..16).flat_map(|p| (0..channels).map(move |c| (p * 400 + c * 31 + 7) as u16)).collect();
let bytes = craft_dds::encode16(4, 4, layout, &pixels, DdsOptions { compression: DdsCompression::None, mipmaps: true }).unwrap();
let texture = Texture::parse(&bytes).unwrap();
assert_eq!(texture.compression(), DdsCompression::None);
assert_eq!(texture.levels(), 3);
assert_eq!(texture.decode16().unwrap(), pixels);
for (index, averages) in [(1, vec![1000, 1800, 4200, 5000]), (2, vec![3000])] {
let expected: Vec<u16> = averages.iter().flat_map(|p| (0..channels).map(move |c| (p + c * 31 + 7) as u16)).collect();
let level = texture.mip_level(index).unwrap();
let budget = (expected.len() * 2) as u64;
assert!(matches!(level.decode16_with_limit(budget - 1), Err(craft_dds::DdsError::LimitExceeded { .. })));
assert_eq!(level.decode16_with_limit(budget).unwrap(), expected);
let rounded: Vec<u8> = expected.iter().map(|&v| ((u32::from(v) + 128) / 257) as u8).collect();
assert_eq!(level.decode().unwrap(), rounded);
}
assert_eq!(texture.mip_level(1).unwrap().mip_level(1).unwrap().decode16().unwrap(), texture.mip_level(2).unwrap().decode16().unwrap());
let truncated = Texture::parse(&bytes[..bytes.len() - 1]).unwrap();
assert!(truncated.mip_level(2).unwrap().decode16().is_err());
}
}
+1
View File
@@ -13,5 +13,6 @@ workspace = true
[dependencies]
base64 = "0.23"
craft-image-codecs = { workspace = true }
craft-dds = { workspace = true }
thiserror = { workspace = true }
image = { version = "0.25", default-features = false }
+69 -1
View File
@@ -1,4 +1,4 @@
//! DDS compatibility facade; implementation and BC block codecs live in craft-image-codecs.
//! DDS compatibility facade; parsing, mip layout and BC block codecs live in craft-dds.
use crate::{CodecError, Image, Limits, SampleType, bridge};
use craft_image_codecs::Format;
@@ -73,3 +73,71 @@ pub fn encode(image: &Image, options: DdsOptions) -> Result<Vec<u8>, CodecError>
craft_image_codecs::EncodeOptions { dds: craft_image_codecs::DdsOptions { compression, mipmaps: options.mipmaps }, ..Default::default() };
bridge::encode(image, Format::Dds, &opts)
}
/// Metadata for the supported 2D DDS texture, available without pixel data.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct DdsInfo {
pub width: u32,
pub height: u32,
pub levels: u32,
pub alpha: bool,
/// `None` for a shared decoder compression not exposed by this legacy writer API.
pub compression: Option<DdsCompression>,
}
fn dds_error(error: craft_dds::DdsError) -> CodecError {
match error {
craft_dds::DdsError::Malformed(reason) => CodecError::malformed("DDS", reason),
craft_dds::DdsError::Unsupported(reason) => CodecError::unsupported("DDS", reason),
craft_dds::DdsError::Encode(reason) => CodecError::encode("DDS", reason),
craft_dds::DdsError::Alloc(len) => CodecError::LimitExceeded(format!("cannot allocate {len} bytes for DDS")),
craft_dds::DdsError::LimitExceeded { required, limit } => {
CodecError::LimitExceeded(format!("decoded DDS requires {required} bytes, exceeding limit {limit}"))
}
other => CodecError::malformed("DDS", other),
}
}
fn layout(texture: &craft_dds::Texture<'_>) -> crate::ChannelLayout {
match texture.layout() {
craft_dds::Layout::Gray => crate::ChannelLayout::Gray,
craft_dds::Layout::GrayA => crate::ChannelLayout::GrayA,
craft_dds::Layout::Rgb => crate::ChannelLayout::Rgb,
craft_dds::Layout::Rgba => crate::ChannelLayout::Rgba,
}
}
pub fn info(bytes: &[u8]) -> Result<DdsInfo, CodecError> {
let texture = craft_dds::Texture::parse(bytes).map_err(dds_error)?;
let compression = match texture.compression() {
craft_dds::DdsCompression::None => Some(DdsCompression::None),
craft_dds::DdsCompression::Bc1 => Some(DdsCompression::Bc1),
craft_dds::DdsCompression::Bc2 => Some(DdsCompression::Bc2),
craft_dds::DdsCompression::Bc3 => Some(DdsCompression::Bc3),
_ => None,
};
let alpha = matches!(texture.layout(), craft_dds::Layout::GrayA | craft_dds::Layout::Rgba);
Ok(DdsInfo { width: texture.width(), height: texture.height(), levels: texture.levels(), alpha, compression })
}
/// Decode the declared mip chain, charging all retained pixels to one output-byte budget.
/// Cancellation is checked before each level; no partial chain is returned.
pub fn decode_levels(bytes: &[u8], limits: &Limits, cancel: &dyn Fn() -> bool) -> Result<Vec<Image>, CodecError> {
let texture = craft_dds::Texture::parse(bytes).map_err(dds_error)?;
let mut images = Vec::new();
images.try_reserve_exact(texture.levels() as usize).map_err(|_| CodecError::LimitExceeded("cannot allocate DDS mip list".into()))?;
let mut remaining = limits.max_alloc;
for i in 0..texture.levels() {
if cancel() {
return Err(CodecError::malformed("DDS", "DDS import cancelled"));
}
let level = texture.mip_level(i).map_err(dds_error)?;
let layout = layout(&level);
let level_limits = Limits { max_alloc: remaining, ..*limits };
level_limits.check(level.width(), level.height(), layout, SampleType::U8)?;
let pixels = level.decode_with_limit(remaining).map_err(dds_error)?;
remaining = remaining.checked_sub(pixels.len() as u64).ok_or_else(|| CodecError::LimitExceeded("DDS mip chain exceeds max_alloc".into()))?;
images.push(Image::from_u8(level.width(), level.height(), layout, pixels)?);
}
Ok(images)
}
+101
View File
@@ -411,3 +411,104 @@ fn rejects_bogus_sizes_and_pixel_formats() {
no_format.extend([0; 4]);
assert!(matches!(decode(&no_format), Err(CodecError::Unsupported { .. })));
}
fn mip_chain() -> Vec<u8> {
let mut b = compressed(4, 4, b"DXT1");
b[8..12].copy_from_slice(&(0x1007u32 | 0x2_0000).to_le_bytes());
b[28..32].copy_from_slice(&3u32.to_le_bytes());
for c in [RED, GREEN, BLUE] {
b.extend(bc1_block(c, c, [0; 4]));
}
b
}
#[test]
fn import_info_rejects_truncated_legacy_headers() {
let b = compressed(4, 4, b"DXT1");
for n in 0..b.len() {
assert!(matches!(dds::info(&b[..n]), Err(CodecError::Malformed { .. })), "accepted {n} of {} header bytes", b.len());
}
}
#[test]
fn import_info_rejects_truncated_dx10_headers() {
let b = dx10(4, 4, 71, 3, 0, 1);
for n in 0..b.len() {
assert!(matches!(dds::info(&b[..n]), Err(CodecError::Malformed { .. })), "accepted {n} of {} header bytes", b.len());
}
}
#[test]
fn import_info_accepts_complete_headers_without_pixel_data() {
for b in [compressed(4, 4, b"DXT1"), dx10(4, 4, 71, 3, 0, 1)] {
assert_eq!(dds::info(&b).unwrap(), dds::DdsInfo { width: 4, height: 4, levels: 1, alpha: true, compression: Some(dds::DdsCompression::Bc1) });
assert!(matches!(decode(&b), Err(CodecError::Malformed { .. })));
assert!(matches!(dds::decode_levels(&b, &Limits::default(), &|| false), Err(CodecError::Malformed { .. })));
}
}
#[test]
fn import_info_and_all_mips_use_the_shared_decoder() {
let b = mip_chain();
let info = dds::info(&b[..128]).unwrap();
assert_eq!((info.width, info.height, info.levels, info.alpha), (4, 4, 3, true));
assert_eq!(info.compression, Some(dds::DdsCompression::Bc1));
let levels = dds::decode_levels(&b, &Limits::default(), &|| false).unwrap();
assert_eq!(levels.iter().map(Image::dimensions).collect::<Vec<_>>(), [(4, 4), (2, 2), (1, 1)]);
for (img, color) in levels.iter().zip([[255, 0, 0, 255], [0, 255, 0, 255], [0, 0, 255, 255]]) {
assert!(img.data().as_chunks::<4>().0.iter().all(|p| *p == color));
}
assert_eq!(decode(&b).unwrap().data(), levels[0].data());
}
#[test]
fn mip_chain_charges_the_combined_allocation() {
for (budget, accepted) in [(63, false), (64, false), (80, false), (83, false), (84, true)] {
let result = dds::decode_levels(&mip_chain(), &Limits { max_alloc: budget, ..Default::default() }, &|| false);
if accepted {
assert_eq!(result.unwrap().len(), 3);
} else {
assert!(matches!(result, Err(CodecError::LimitExceeded(_))));
}
}
}
#[test]
fn cancellation_is_checked_after_a_level_was_decoded() {
let calls = std::cell::Cell::new(0);
let result = dds::decode_levels(&mip_chain(), &Limits::default(), &|| {
let n = calls.get();
calls.set(n + 1);
n == 1
});
assert!(matches!(result, Err(CodecError::Malformed { message, .. }) if message.contains("cancelled")));
assert_eq!(calls.get(), 2);
}
#[test]
fn mip_import_rejects_truncation_and_bounds_declared_count() {
let mut b = mip_chain();
for n in 0..b.len() {
assert!(dds::decode_levels(&b[..n], &Limits::default(), &|| false).is_err(), "length {n}");
}
b[28..32].copy_from_slice(&u32::MAX.to_le_bytes());
assert_eq!(dds::decode_levels(&b, &Limits::default(), &|| false).unwrap().len(), 3);
b[8..12].copy_from_slice(&0x1007u32.to_le_bytes());
assert_eq!(dds::info(&b).unwrap().levels, 3);
assert_eq!(dds::decode_levels(&b, &Limits::default(), &|| false).unwrap().len(), 3);
b[28..32].copy_from_slice(&0u32.to_le_bytes());
assert_eq!(dds::info(&b).unwrap().levels, 1);
assert_eq!(dds::decode_levels(&b, &Limits::default(), &|| false).unwrap().len(), 1);
}
#[test]
fn lower_mips_do_not_inherit_top_level_pitch() {
let mut b = header(2, 2, DDPF_LUMINANCE, &[0; 4], 8, [0xff, 0, 0, 0]);
set_pitch(&mut b, 4);
b[8..12].copy_from_slice(&(0x1007u32 | DDSD_PITCH | 0x2_0000).to_le_bytes());
b[28..32].copy_from_slice(&2u32.to_le_bytes());
b.extend([1, 2, 99, 99, 3, 4, 99, 99, 5]);
let levels = dds::decode_levels(&b, &Limits::default(), &|| false).unwrap();
assert_eq!(levels[0].data(), [1, 2, 3, 4]);
assert_eq!(levels[1].data(), [5]);
}