diff --git a/README.md b/README.md index af98f90e7..7b0c88ded 100644 --- a/README.md +++ b/README.md @@ -89,8 +89,8 @@ See the [release notes](CHANGELOG.md) for included functionality and known limit log, scripts, verification) is in `crates/crw/clean-room/`. Colour stays in each app. - [`craft-csv`](crates/csv/README.md): delimited text (CSV, TSV) and SYLK: encoding detection (UTF-8, UTF-16, Windows-1252 or Windows-1256), delimiter sniffing, a record parser with a cap on fields per record, field quoting for writers, and a SYLK (`.slk`) reader with R1C1 formulas rewritten to A1. - [`craft-dds`](crates/dds/README.md): DirectDraw Surface (DDS) textures, read and written: the - top mip level of uncompressed and BC1 to BC3 (DXT1/3/5) textures, legacy and DX10 headers, and - our own block encoder with optional mip chains. No dependencies (rayon behind `parallel`), so an + top mip level of uncompressed, BC1 to BC3 (DXT1/3/5) and BC4/BC5 (grayscale data and normal + maps) textures, legacy and DX10 headers, and our own block encoder with optional mip chains. No dependencies (rayon behind `parallel`), so an app that only exports textures needn't take the whole `craft-image-codecs` codec set and its licences; `craft-image-codecs` reads and writes DDS through it. - [`craft-dialogs`](crates/dialogs/README.md): native file and message dialogs that never block @@ -245,7 +245,7 @@ See the [release notes](CHANGELOG.md) for included functionality and known limit encoder, from PhotoCraft; includes a frame probe for routing. Metadata interpretation stays in each app. - [`craft-raster-codecs`](crates/raster-codecs/README.md): small raster formats, one module each, - from PhotoCraft: DDS (BC1 to BC3, read and write), DICOM, FITS (read and write), IFF/ILBM (read + from PhotoCraft: DDS (BC1 to BC3 read and write, BC4 and BC5 read), DICOM, FITS (read and write), IFF/ILBM (read and write), PCX, PNM/PAM/PFM (read and write) and XPM, into one flat image type. Bounded and panic-free on hostile input. Colour, orientation and the document mapping stay in each app. - [`craft-kiwi`](crates/kiwi/README.md): clean-room decoder and encoder for the kiwi binary schema diff --git a/crates/dds/Cargo.toml b/crates/dds/Cargo.toml index ca40bd69a..f93e8cbcc 100644 --- a/crates/dds/Cargo.toml +++ b/crates/dds/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "craft-dds" -description = "DirectDraw Surface (DDS) textures: uncompressed and BC1-BC3 block compression, read and write, without dependencies" +description = "DirectDraw Surface (DDS) textures: uncompressed and BC1-BC5 block compression, read and write, without dependencies" version.workspace = true edition.workspace = true license.workspace = true diff --git a/crates/dds/README.md b/crates/dds/README.md index 3871452df..720ec9ba7 100644 --- a/crates/dds/README.md +++ b/crates/dds/README.md @@ -12,15 +12,20 @@ craft-dds = { git = "https://github.com/storytold/craft-libs", rev = "" | | Read | Write | |---|---|---| | Uncompressed | 8, 16, 24 or 32 bits per pixel described by channel masks, RGB or luminance, with or without alpha; padded rows (`DDSD_PITCH`) | BGRA, BGRX, luminance, luminance with alpha | -| Block-compressed | BC1, BC2, BC3 (DXT1, DXT3, DXT5) | BC1, BC2, BC3 | -| Headers | legacy and DX10 | legacy | +| Block-compressed | BC1, BC2, BC3 (DXT1, DXT3, DXT5); unsigned BC4 (ATI1, BC4U, DXGI 79 and 80) and BC5 (ATI2, BC5U, DXGI 82 and 83) | BC1, BC2, BC3, BC4, BC5 | +| Headers | legacy and DX10 | legacy; DX10 for BC4 and BC5 | | Mip levels | the top level only | optional full chain, box-filtered | -Cubemaps, texture arrays, volume textures, premultiplied DXT2/DXT4 and the other DXGI formats -are refused with `DdsError::Unsupported` rather than read in part. +Cubemaps, texture arrays, volume textures, premultiplied DXT2/DXT4, signed (SNORM) BC4/BC5 and +the other DXGI formats (BC6H, BC7, float) are refused with `DdsError::Unsupported` rather than read +in part. Pixels are 8 bits per channel, interleaved and top row first, in one of four `Layout`s (`Gray`, -`GrayA`, `Rgb`, `Rgba`). Block compressions are written from RGBA. +`GrayA`, `Rgb`, `Rgba`). BC1 to BC3 are written from RGBA, BC4 from gray and BC5 from RGB +(`DdsCompression::layout` names it). BC4 reads back as gray. BC5 stores red and green only, so it +reads back as RGB with blue 0: for a tangent-space normal map, X and Y, with Z left to the +renderer. ATI2 files are read as Microsoft's tools read them (red in the first block), not with +the two blocks swapped as FFmpeg does. ```rust use craft_dds::{DdsCompression, DdsOptions, Layout, Texture}; @@ -35,7 +40,9 @@ let decoded = texture.decode()?; The block encoder is our own: RGB565 endpoints fitted along each block's principal axis and refined by least squares, indices picked against the palette the reader decodes; BC1 turns texels -under half opacity into its transparent black, and BC3 picks whichever alpha mode fits. +under half opacity into its transparent black, and BC3, BC4 and BC5 pick whichever mode of their +value blocks fits. The block functions don't depend on the DDS header, so other containers of +the same blocks can share them. ## Features diff --git a/crates/dds/src/bc.rs b/crates/dds/src/bc.rs index 12bf15179..863aa3077 100644 --- a/crates/dds/src/bc.rs +++ b/crates/dds/src/bc.rs @@ -1,6 +1,10 @@ -//! BC1, BC2 and BC3 (DXT1, DXT3, DXT5) blocks, after Microsoft's public block compression +//! BC1 to BC5 (DXT1, DXT3, DXT5, ATI1, ATI2) blocks, after Microsoft's public block compression //! documentation ("Block Compression (Direct3D 10)" and "Texture Block Compression in Direct3D -//! 11"): the palettes the DDS reader decodes with, and the block encoder the DDS writer uses. +//! 11"): the block decoders and the block encoder the DDS reader and writer use. Nothing here +//! knows about DDS headers, so other containers of the same blocks can use it. +//! +//! BC4 is one block of 16 single-channel values, the same block BC3 stores its alpha in; BC5 is +//! two of them, red then green. [`value_block`] and [`decode_values`] serve all three. //! //! The encoder fits a block's colours with two RGB565 endpoints along their principal axis, //! refines them by least squares, and scores every candidate against the exact palette the @@ -35,7 +39,7 @@ pub(crate) fn colour_palette(c0: u16, c1: u16, four: bool) -> [[u8; 4]; 4] { } } -/// A BC3 alpha block's eight values: six interpolated at sevenths when `a0 > a1`, else four +/// A value block's eight values: six interpolated at sevenths when `a0 > a1`, else four /// interpolated at fifths followed by 0 and 255. pub(crate) fn alpha_palette(a0: u8, a1: u8) -> [u8; 8] { let (a0, a1) = (u32::from(a0), u32::from(a1)); @@ -54,6 +58,32 @@ pub(crate) fn alpha_palette(a0: u8, a1: u8) -> [u8; 8] { palette.map(|v| v as u8) } +/// A colour block's 16 texels as RGBA. BC2 and BC3 colour blocks always have four colours +/// (`one_bit_alpha` false); only BC1's `c0 <= c1` order selects three colours and transparent +/// black. Missing bytes read as 0. +pub(crate) fn decode_colour(block: &[u8], one_bit_alpha: bool) -> Block { + let byte = |i: usize| block.get(i).copied().unwrap_or(0); + let (c0, c1) = (u16::from_le_bytes([byte(0), byte(1)]), u16::from_le_bytes([byte(2), byte(3)])); + let palette = colour_palette(c0, c1, c0 > c1 || !one_bit_alpha); + let indices = u32::from_le_bytes([byte(4), byte(5), byte(6), byte(7)]); + std::array::from_fn(|t| palette[(indices >> (2 * t)) as usize & 3]) +} + +/// BC2's alpha: four explicit bits per texel. +pub(crate) fn decode_bc2_alpha(block: &[u8]) -> [u8; 16] { + let bits = u64::from_le_bytes(std::array::from_fn(|i| block.get(i).copied().unwrap_or(0))); + std::array::from_fn(|t| ((bits >> (4 * t)) & 0xf) as u8 * 17) +} + +/// A value block (BC3's alpha, BC4, either half of BC5): two endpoints and a 3-bit index per +/// texel into eight values, or into six plus 0 and 255 when `a0 <= a1`. Missing bytes read as 0. +pub(crate) fn decode_values(block: &[u8]) -> [u8; 16] { + let byte = |i: usize| block.get(i).copied().unwrap_or(0); + let palette = alpha_palette(byte(0), byte(1)); + let bits = u64::from_le_bytes([byte(2), byte(3), byte(4), byte(5), byte(6), byte(7), 0, 0]); + std::array::from_fn(|t| palette[((bits >> (3 * t)) & 7) as usize]) +} + /// A BC1 block. Texels under half opacity become BC1's transparent black, which needs the /// three-colour mode; an opaque block takes whichever mode fits its colours better. pub(crate) fn encode_bc1(block: &Block, inside: Mask) -> [u8; 8] { @@ -299,7 +329,7 @@ fn least_squares(block: &Block, opaque: Mask, bytes: &[u8; 8]) -> Option<(u16, u Some((to565(e0), to565(e1))) } -/// An interpolated block of 16 single-channel values (BC3's alpha): whichever of the two modes +/// A block of 16 single-channel values (BC3's alpha, BC4, either half of BC5): 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] { @@ -343,13 +373,6 @@ fn value_fit(values: &[u8; 16], inside: Mask, a0: u8, a1: u8) -> ([u8; 8], u32) mod tests { use super::*; - fn decode_colour(bytes: &[u8; 8], bc1: bool) -> Block { - let (c0, c1) = (u16::from_le_bytes([bytes[0], bytes[1]]), u16::from_le_bytes([bytes[2], bytes[3]])); - let palette = colour_palette(c0, c1, c0 > c1 || !bc1); - let indices = u32::from_le_bytes([bytes[4], bytes[5], bytes[6], bytes[7]]); - std::array::from_fn(|t| palette[(indices >> (2 * t)) as usize & 3]) - } - #[test] fn solid_blocks_land_on_the_nearest_565_colour() { for colour in [[0, 0, 0, 255], [255, 255, 255, 255], [12, 200, 77, 255]] { @@ -419,6 +442,31 @@ mod tests { assert!(ours < bounding_box, "{ours} vs the bounding box's {bounding_box}"); } + #[test] + fn value_blocks_decode_the_frozen_vectors() { + // Eight-value mode (a0 = 200 > a1 = 50), every index 0. + assert_eq!(decode_values(&[0xc8, 0x32, 0, 0, 0, 0, 0, 0]), [200; 16]); + // Six-value mode (a0 = 10 <= a1 = 250), every index 1. + assert_eq!(decode_values(&[0x0a, 0xfa, 0x49, 0x92, 0x24, 0x49, 0x92, 0x24]), [250; 16]); + // Six-value mode's indices 6 and 7 are 0 and 255 whatever the endpoints. + let bits: u64 = (0..16).fold(0, |b, t| b | (6 + (t % 2)) << (3 * t)); + let b = bits.to_le_bytes(); + let got = decode_values(&[10, 250, b[0], b[1], b[2], b[3], b[4], b[5]]); + assert_eq!(got, std::array::from_fn(|t| if t % 2 == 0 { 0 } else { 255 })); + } + + #[test] + fn value_blocks_round_trip_ramps_and_solids() { + for values in [[200u8; 16], [0; 16], [255; 16], std::array::from_fn(|t| (t * 17) as u8), std::array::from_fn(|t| 100 + t as u8)] { + let back = decode_values(&value_block(&values, u16::MAX)); + let worst = values.iter().zip(back).map(|(a, b)| a.abs_diff(b)).max().unwrap_or(0); + // Within half a step of either mode: 255 / 7 apart in the eight-value mode, about + // 221 / 5 in the six-value one. + assert!(worst <= 23, "{values:?} -> {back:?}"); + } + assert_eq!(decode_values(&value_block(&[200; 16], u16::MAX)), [200; 16]); + } + #[test] fn nearest_picks_what_min_by_key_picks() { // Ties (equal entries, entries equally far on both sides) and exact hits included. diff --git a/crates/dds/src/lib.rs b/crates/dds/src/lib.rs index 079b3e3b5..5c088052a 100644 --- a/crates/dds/src/lib.rs +++ b/crates/dds/src/lib.rs @@ -3,12 +3,16 @@ //! //! Reading: the top mip level of a 2D texture, either uncompressed (8 to 32 bits per pixel //! described by channel masks, RGB or luminance) or block-compressed BC1/BC2/BC3 -//! (DXT1/DXT3/DXT5), with or without the DX10 header. Cubemaps, texture arrays and volume -//! textures are refused rather than flattened to one face or slice. +//! (DXT1/DXT3/DXT5) or unsigned BC4/BC5 (ATI1/ATI2), with or without the DX10 header. BC4 opens +//! as gray and BC5 as RGB with blue 0: BC5 stores only red and green, and a normal map's Z is +//! left for the caller to reconstruct. Cubemaps, texture arrays and volume textures are refused +//! rather than flattened to one face or slice, and signed (SNORM) BC4/BC5 is refused too. //! -//! Writing: a 2D texture, uncompressed (BGRA or BGRX, luminance with or without alpha) or -//! BC1/BC2/BC3, optionally with its full mip chain. The legacy header describes all of these, -//! so no DX10 header is written; formats only DXGI can name (BC4–BC7, sRGB) aren't written. +//! Writing: a 2D texture, uncompressed (BGRA or BGRX, luminance with or without alpha), +//! BC1/BC2/BC3 or BC4/BC5, optionally with its full mip chain. The legacy header describes all +//! but BC4 and BC5, which are written with the DX10 header (`BC4_UNORM`, `BC5_UNORM`): their +//! legacy FourCCs are vendor names that programs read differently (ATI2's two blocks are swapped +//! by some). BC6H, BC7 and sRGB formats 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 and decodes rows of blocks (and mip @@ -86,8 +90,10 @@ impl fmt::Display for DdsError { impl std::error::Error for DdsError {} -/// How a DDS texture stores its pixels. +/// How a DDS texture stores its pixels. More compressions may be added, so a `match` on it needs +/// a wildcard arm. #[derive(Debug, Clone, Copy, PartialEq, Eq, Default)] +#[non_exhaustive] pub enum DdsCompression { /// Uncompressed, 8 bits per channel: BGRA (BGRX without alpha), or luminance with or /// without alpha for grayscale. Lossless. @@ -100,33 +106,55 @@ pub enum DdsCompression { Bc2, /// BC3 (DXT5): 8 bits per pixel, with smooth interpolated alpha. Bc3, + /// BC4 (ATI1): 4 bits per pixel, one channel: gray, for roughness, metallic, height or + /// ambient-occlusion maps. Written from gray pixels. + Bc4, + /// BC5 (ATI2): 8 bits per pixel, two channels: red and green, for tangent-space normal maps + /// (X and Y; Z is reconstructed by the renderer). Written from RGB pixels, blue dropped. + Bc5, } impl DdsCompression { - pub const ALL: [DdsCompression; 4] = [DdsCompression::None, DdsCompression::Bc1, DdsCompression::Bc2, DdsCompression::Bc3]; + pub const ALL: [DdsCompression; 6] = + [DdsCompression::None, DdsCompression::Bc1, DdsCompression::Bc2, DdsCompression::Bc3, DdsCompression::Bc4, DdsCompression::Bc5]; - /// The name scripts and the CLI use: `none`, `bc1`, `bc2` or `bc3`. + /// The name scripts and the CLI use: `none`, `bc1`, `bc2`, `bc3`, `bc4` or `bc5`. pub fn name(self) -> &'static str { match self { DdsCompression::None => "none", DdsCompression::Bc1 => "bc1", DdsCompression::Bc2 => "bc2", DdsCompression::Bc3 => "bc3", + DdsCompression::Bc4 => "bc4", + DdsCompression::Bc5 => "bc5", } } - /// [`Self::name`] back to a compression, also taking the DXT names (`dxt1`, `dxt3`, - /// `dxt5`), in any case. Anything else is `None`. + /// [`Self::name`] back to a compression, also taking the DXT and ATI names (`dxt1`, `dxt3`, + /// `dxt5`, `ati1`, `ati2`), in any case. Anything else is `None`. pub fn from_name(name: &str) -> Option { match name.to_ascii_lowercase().as_str() { "none" => Some(DdsCompression::None), "bc1" | "dxt1" => Some(DdsCompression::Bc1), "bc2" | "dxt3" => Some(DdsCompression::Bc2), "bc3" | "dxt5" => Some(DdsCompression::Bc3), + "bc4" | "ati1" => Some(DdsCompression::Bc4), + "bc5" | "ati2" => Some(DdsCompression::Bc5), _ => None, } } + /// The pixel layout the compression is written from: gray for BC4, RGB for BC5, RGBA for + /// the other block compressions. `None` for uncompressed textures, which take every layout. + pub fn layout(self) -> Option { + match self { + DdsCompression::None => None, + DdsCompression::Bc4 => Some(Layout::Gray), + DdsCompression::Bc5 => Some(Layout::Rgb), + DdsCompression::Bc1 | DdsCompression::Bc2 | DdsCompression::Bc3 => Some(Layout::Rgba), + } + } + /// A block compression (lossy), not uncompressed pixels. pub fn is_block(self) -> bool { self != DdsCompression::None @@ -224,6 +252,10 @@ enum Encoding { Bc1, Bc2, Bc3, + /// One value block: gray. + Bc4, + /// Two value blocks: red, then green. + Bc5, } impl Encoding { @@ -247,10 +279,21 @@ impl Encoding { Encoding::Masks { gray: true, fields, .. } if fields[3].is_some() => Layout::GrayA, Encoding::Masks { gray: true, .. } => Layout::Gray, Encoding::Masks { fields, .. } if fields[3].is_none() => Layout::Rgb, + Encoding::Bc4 => Layout::Gray, + Encoding::Bc5 => Layout::Rgb, _ => Layout::Rgba, } } + /// Bytes per 4×4 block; 0 for uncompressed pixels. + fn block_size(&self) -> usize { + match self { + Encoding::Masks { .. } => 0, + Encoding::Bc1 | Encoding::Bc4 => 8, + Encoding::Bc2 | Encoding::Bc3 | Encoding::Bc5 => 16, + } + } + /// Stored row stride and byte size of the top mip level (block rows for BC). fn level_layout(&self, width: u32, height: u32, pitch: Option) -> Result<(usize, usize), DdsError> { let overflow = || bad("pixel data size overflow"); @@ -267,9 +310,8 @@ impl Encoding { } (row_bytes, h) } - Encoding::Bc1 | Encoding::Bc2 | Encoding::Bc3 => { - let block = if matches!(self, Encoding::Bc1) { 8 } else { 16 }; - (w.div_ceil(4).checked_mul(block).ok_or_else(overflow)?, h.div_ceil(4)) + Encoding::Bc1 | Encoding::Bc2 | Encoding::Bc3 | Encoding::Bc4 | Encoding::Bc5 => { + (w.div_ceil(4).checked_mul(self.block_size()).ok_or_else(overflow)?, h.div_ceil(4)) } }; let size = row_bytes.checked_mul(rows).ok_or_else(overflow)?; @@ -286,8 +328,14 @@ fn legacy_encoding(b: &[u8]) -> Result { b"DXT1" => Ok(Encoding::Bc1), b"DXT3" => Ok(Encoding::Bc2), b"DXT5" => Ok(Encoding::Bc3), + // Microsoft's mapping (DirectXTex reads ATI2 as BC5_UNORM, as Pillow does): red in + // the first block, green in the second. FFmpeg's reader swaps the two blocks of + // ATI2, after the old ATI 3Dc tools; this reader doesn't. + b"ATI1" | b"BC4U" => Ok(Encoding::Bc4), + b"ATI2" | b"BC5U" => Ok(Encoding::Bc5), + b"BC4S" | b"BC5S" => Err(unsupported(format!("signed (SNORM) `{}` textures are not supported", fourcc_name(fourcc)))), b"DXT2" | b"DXT4" => Err(unsupported("premultiplied-alpha DXT2/DXT4 textures are not supported")), - _ => Err(unsupported(format!("compression `{}` is not supported (DXT1, DXT3 and DXT5 are)", fourcc_name(fourcc)))), + _ => Err(unsupported(format!("compression `{}` is not supported (DXT1, DXT3, DXT5, ATI1/BC4U and ATI2/BC5U are)", fourcc_name(fourcc)))), }; } if flags & DDPF_RGB != 0 { @@ -321,7 +369,12 @@ fn dx10_encoding(b: &[u8]) -> Result { 70..=72 => Ok(Encoding::Bc1), 73..=75 => Ok(Encoding::Bc2), 76..=78 => Ok(Encoding::Bc3), - _ => Err(unsupported(format!("DXGI format {dxgi} is not supported (BC1, BC2, BC3 and 8-bit RGBA or BGRA are)"))), + // Typeless, then UNORM: a typeless texture's view is unsigned unless a program says + // otherwise, and Pillow writes BC5 as typeless. + 79 | 80 => Ok(Encoding::Bc4), + 82 | 83 => Ok(Encoding::Bc5), + 81 | 84 => Err(unsupported(format!("signed (SNORM) BC4 and BC5 textures are not supported (DXGI format {dxgi})"))), + _ => Err(unsupported(format!("DXGI format {dxgi} is not supported (BC1 to BC5 and 8-bit RGBA or BGRA are)"))), } } @@ -386,7 +439,9 @@ impl<'a> Texture<'a> { let mut pixels = vec![0u8; total]; match encoding { 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), + Encoding::Bc1 | Encoding::Bc2 | Encoding::Bc3 | Encoding::Bc4 | Encoding::Bc5 => { + decode_blocks(encoding, data, (w, channels), &mut pixels) + } } Ok(pixels) } @@ -455,16 +510,19 @@ fn decode_masks(m: Masks, data: &[u8], row_pitch: usize, pixels: &mut [u8], row_ /// 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 block_size = encoding.block_size().max(1); 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 second = block.get(8..).unwrap_or_default(); 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)), + Encoding::Bc1 => bc::decode_colour(block, true), + Encoding::Bc2 => with_alpha(bc::decode_colour(second, false), bc::decode_bc2_alpha(block)), + Encoding::Bc4 => values(&[bc::decode_values(block)]), + Encoding::Bc5 => values(&[bc::decode_values(block), bc::decode_values(second)]), + _ => with_alpha(bc::decode_colour(second, false), bc::decode_values(block)), }; let x0 = bx * 4; // The band holds the block's rows that lie inside the image (fewer than four in the @@ -485,29 +543,10 @@ fn decode_blocks(encoding: Encoding, data: &[u8], (width, channels): (usize, usi }); } -/// A BC1 colour block. BC2 and BC3 colour blocks always have four colours; only BC1's -/// `c0 <= c1` order selects three colours and transparent black. -fn bc1(block: &[u8], one_bit_alpha: bool) -> [[u8; 4]; 16] { - let byte = |i: usize| block.get(i).copied().unwrap_or(0); - let (c0, c1) = (u16::from_le_bytes([byte(0), byte(1)]), u16::from_le_bytes([byte(2), byte(3)])); - let palette = bc::colour_palette(c0, c1, c0 > c1 || !one_bit_alpha); - let indices = u32::from_le_bytes([byte(4), byte(5), byte(6), byte(7)]); - std::array::from_fn(|t| palette[(indices >> (2 * t)) as usize & 3]) -} - -/// BC2: four explicit bits of alpha per texel. -fn bc2_alpha(block: &[u8]) -> [u8; 16] { - let bits = u64::from_le_bytes(std::array::from_fn(|i| block.get(i).copied().unwrap_or(0))); - std::array::from_fn(|t| ((bits >> (4 * t)) & 0xf) as u8 * 17) -} - -/// BC3: two alpha endpoints and a 3-bit index per texel into eight values, or into six plus -/// 0 and 255 when `a0 <= a1`. -fn bc3_alpha(block: &[u8]) -> [u8; 16] { - let byte = |i: usize| block.get(i).copied().unwrap_or(0); - let palette = bc::alpha_palette(byte(0), byte(1)); - let bits = u64::from_le_bytes([byte(2), byte(3), byte(4), byte(5), byte(6), byte(7), 0, 0]); - std::array::from_fn(|t| palette[((bits >> (3 * t)) & 7) as usize]) +/// Texels whose first channels are `channels`' values, the rest 0: gray for BC4, red and green +/// (and blue 0) for BC5. +fn values(channels: &[[u8; 16]]) -> [[u8; 4]; 16] { + std::array::from_fn(|t| std::array::from_fn(|c| channels.get(c).map_or(0, |v| v[t]))) } fn with_alpha(mut texels: [[u8; 4]; 16], alpha: [u8; 16]) -> [[u8; 4]; 16] { @@ -527,6 +566,8 @@ const DDSD_LINEARSIZE: u32 = 0x8_0000; const DDSCAPS_COMPLEX: u32 = 0x8; const DDSCAPS_TEXTURE: u32 = 0x1000; const DDSCAPS_MIPMAP: u32 = 0x40_0000; +const DXGI_BC4_UNORM: u32 = 80; +const DXGI_BC5_UNORM: u32 = 83; fn encode_err(reason: impl fmt::Display) -> DdsError { DdsError::Encode(reason.to_string()) @@ -554,10 +595,13 @@ enum Store { Bc1, Bc2, Bc3, + Bc4, + Bc5, } impl Store { - /// The storage for pixels of `layout`. Block compressions take RGBA only. + /// The storage for pixels of `layout`. Block compressions take their + /// [`DdsCompression::layout`] only. fn new(compression: DdsCompression, layout: Layout) -> Result { Ok(match (compression, layout) { (DdsCompression::None, Layout::Gray) => Store::Luminance, @@ -567,6 +611,8 @@ impl Store { (DdsCompression::Bc1, Layout::Rgba) => Store::Bc1, (DdsCompression::Bc2, Layout::Rgba) => Store::Bc2, (DdsCompression::Bc3, Layout::Rgba) => Store::Bc3, + (DdsCompression::Bc4, Layout::Gray) => Store::Bc4, + (DdsCompression::Bc5, Layout::Rgb) => Store::Bc5, (_, layout) => return Err(encode_err(format!("{layout:?} pixels can't be written as `{}`", compression.name()))), }) } @@ -577,13 +623,22 @@ impl Store { Store::Luminance => 1, Store::LuminanceAlpha => 2, Store::Bgrx | Store::Bgra => 4, - Store::Bc1 => 8, - Store::Bc2 | Store::Bc3 => 16, + Store::Bc1 | Store::Bc4 => 8, + Store::Bc2 | Store::Bc3 | Store::Bc5 => 16, } } fn is_block(self) -> bool { - matches!(self, Store::Bc1 | Store::Bc2 | Store::Bc3) + matches!(self, Store::Bc1 | Store::Bc2 | Store::Bc3 | Store::Bc4 | Store::Bc5) + } + + /// The DXGI format of the DX10 header, for the formats the legacy header can't name. + fn dxgi(self) -> Option { + match self { + Store::Bc4 => Some(DXGI_BC4_UNORM), + Store::Bc5 => Some(DXGI_BC5_UNORM), + _ => None, + } } /// Bytes of one row of pixels (or of 4×4 blocks) of a level `width` wide. @@ -606,6 +661,7 @@ impl Store { Store::Bc1 => (DDPF_FOURCC, *b"DXT1", 0, [0; 4]), Store::Bc2 => (DDPF_FOURCC, *b"DXT3", 0, [0; 4]), Store::Bc3 => (DDPF_FOURCC, *b"DXT5", 0, [0; 4]), + Store::Bc4 | Store::Bc5 => (DDPF_FOURCC, *b"DX10", 0, [0; 4]), } } } @@ -620,7 +676,8 @@ fn half((w, h): (usize, usize)) -> (usize, usize) { } /// A DDS file of `width` × `height` `pixels` in `layout`, interleaved and top row first. -/// Block compressions take [`Layout::Rgba`] pixels; uncompressed textures take every layout. +/// Block compressions take the layout [`DdsCompression::layout`] names (RGBA for BC1 to BC3, +/// gray for BC4, RGB for BC5); uncompressed textures take every layout. pub fn encode(width: u32, height: u32, layout: Layout, pixels: &[u8], options: DdsOptions) -> Result, DdsError> { let store = Store::new(options.compression, layout)?; let expected = (width as usize).checked_mul(height as usize).and_then(|n| n.checked_mul(layout.channels())); @@ -636,14 +693,18 @@ pub fn encode(width: u32, height: u32, layout: Layout, pixels: &[u8], options: D sizes.push(store.level_bytes(size.0, size.1).ok_or_else(|| encode_err("texture size overflow"))?); size = half(size); } - let total = sizes.iter().try_fold(HEADER, |total, &s| total.checked_add(s)).ok_or_else(|| encode_err("texture size overflow"))?; + let head = if store.dxgi().is_some() { HEADER + DX10_HEADER } else { HEADER }; + let total = sizes.iter().try_fold(head, |total, &s| total.checked_add(s)).ok_or_else(|| encode_err("texture size overflow"))?; let header = header(width, height, store, levels, sizes.first().copied().unwrap_or(0))?; let mut out = alloc_zeroed(total)?; - out.get_mut(..HEADER).ok_or_else(|| encode_err("output buffer too small"))?.copy_from_slice(&header); + let (Some(dst), Some(src)) = (out.get_mut(..head), header.get(..head)) else { + return Err(encode_err("output buffer too small")); + }; + dst.copy_from_slice(src); let channels = layout.channels(); let mut level = Cow::Borrowed(pixels); - let (mut size, mut at) = (top, HEADER); + let (mut size, mut at) = (top, head); for (i, &bytes) in sizes.iter().enumerate() { let dst = out.get_mut(at..at + bytes).ok_or_else(|| encode_err("output buffer too small"))?; write_level(store, &level, size, dst)?; @@ -657,9 +718,10 @@ pub fn encode(width: u32, height: u32, layout: Layout, pixels: &[u8], options: D Ok(out) } -/// The `DDS ` signature and DDS_HEADER. `top` is the top level's size in bytes. -fn header(width: u32, height: u32, store: Store, levels: u32, top: usize) -> Result<[u8; HEADER], DdsError> { - let mut b = [0u8; HEADER]; +/// The `DDS ` signature, DDS_HEADER and, for a format only DXGI names, DDS_HEADER_DXT10 (the +/// caller keeps the first [`HEADER`] bytes otherwise). `top` is the top level's size in bytes. +fn header(width: u32, height: u32, store: Store, levels: u32, top: usize) -> Result<[u8; HEADER + DX10_HEADER], DdsError> { + let mut b = [0u8; HEADER + DX10_HEADER]; let mut put = |at: usize, v: u32| { if let Some(d) = b.get_mut(at..at + 4) { d.copy_from_slice(&v.to_le_bytes()); @@ -686,6 +748,12 @@ fn header(width: u32, height: u32, store: Store, levels: u32, top: usize) -> Res put(92 + 4 * i, mask); } put(108, DDSCAPS_TEXTURE | if mipmapped { DDSCAPS_COMPLEX | DDSCAPS_MIPMAP } else { 0 }); + if let Some(dxgi) = store.dxgi() { + // One 2D texture, no misc flags, alpha mode unknown (the formats have no alpha). + put(HEADER, dxgi); + put(HEADER + 4, DIMENSION_TEXTURE2D); + put(HEADER + 12, 1); + } b[..4].copy_from_slice(b"DDS "); Ok(b) } @@ -739,10 +807,40 @@ fn write_level(store: Store, pixels: &[u8], (width, height): (usize, usize), dst } }); } + Store::Bc4 | Store::Bc5 => { + // BC4: the gray channel; BC5: red, then green, of RGB pixels. + let channels = if store == Store::Bc4 { 1 } else { 3 }; + rows(dst, row_bytes, |by, row| { + for (bx, d) in row.chunks_exact_mut(store.unit()).enumerate() { + for (c, d) in d.as_chunks_mut::<8>().0.iter_mut().enumerate() { + let (values, inside) = gather_channel(pixels, (width, height), channels, c, (bx, by)); + *d = bc::value_block(&values, inside); + } + } + }); + } } Ok(()) } +/// Channel `c` of block (`bx`, `by`) of pixels with `channels` channels, and which of its texels +/// lie inside the image. +fn gather_channel(pixels: &[u8], (width, height): (usize, usize), channels: usize, c: usize, (bx, by): (usize, usize)) -> ([u8; 16], Mask) { + let mut values = [0u8; 16]; + let mut inside: Mask = 0; + for (t, v) in values.iter_mut().enumerate() { + let (x, y) = (bx * 4 + t % 4, by * 4 + t / 4); + if x < width + && y < height + && let Some(&p) = pixels.get((y * width + x) * channels + c) + { + *v = p; + inside |= 1 << t; + } + } + (values, inside) +} + /// 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]; @@ -831,9 +929,17 @@ mod tests { } #[test] - fn block_compressions_take_rgba_only() { + fn block_compressions_take_their_layout_only() { let options = DdsOptions { compression: DdsCompression::Bc3, mipmaps: false }; assert_eq!(encode(1, 1, Layout::Rgb, &[1, 2, 3], options), Err(DdsError::Encode("Rgb pixels can't be written as `bc3`".into()))); + for compression in DdsCompression::ALL { + for layout in [Layout::Gray, Layout::GrayA, Layout::Rgb, Layout::Rgba] { + let options = DdsOptions { compression, mipmaps: false }; + let written = encode(1, 1, layout, &[9; 4][..layout.channels()], options); + let takes = compression.layout().is_none_or(|l| l == layout); + assert_eq!(written.is_ok(), takes, "{compression:?} from {layout:?}"); + } + } } #[test] diff --git a/crates/image-codecs/README.md b/crates/image-codecs/README.md index 27ddddb69..1bdf1418d 100644 --- a/crates/image-codecs/README.md +++ b/crates/image-codecs/README.md @@ -46,7 +46,7 @@ craft-image-codecs = { git = "https://github.com/storytold/craft-libs", rev = "< | BMP | yes | yes | U8 | RGB, RGBA | yes | no | no | no | no | no | no | `image` | | TGA | yes | yes | U8 | Gray, GrayA, RGB, RGBA | yes | no | no | no | no | no | no | `image` (read) / built in (RLE write, one scanline per packet) | | ICO | yes | yes | U8 | RGBA (at most 256×256) | yes | no | no | no | no | no | no | `image` | -| DDS | yes | yes | U8 | Gray, GrayA, RGB, RGBA | yes | no | no | no | no | no | yes (BC1–BC3, when `EncodeOptions::dds` asks for one) | [`craft-dds`](../dds/README.md) | +| DDS | yes | yes | U8 | Gray, GrayA, RGB, RGBA | yes | no | no | no | no | no | yes (BC1–BC5, when `EncodeOptions::dds` asks for one) | [`craft-dds`](../dds/README.md) | | Netpbm (PBM/PGM/PPM/PAM/PFM) | yes | yes | U8, U16, F32 (float: PFM gray/RGB only) | all six (PAM `CMYK`/`CMYK_ALPHA`) | yes (PAM) | no | no | no | no | no | no | built in | | QOI | yes | yes | U8 | RGB, RGBA | yes | no | no | no | no | no | no | `image` | | OpenEXR | yes | yes | F16, F32 | Y, YA, RGB, RGBA | yes | no | no | no | no | no | no | `exr` | @@ -94,19 +94,27 @@ embedded table (and a PNG's transparent entry) so `photocraft-io` can open them * **DDS** (through [`craft-dds`](../dds/README.md), whose `DdsCompression` and `DdsOptions` are re-exported). The top mip level of a 2D texture: uncompressed pixels described by channel masks - (8, 16, 24 or 32 bits, RGB or luminance, with or without alpha) or BC1/BC2/BC3 (DXT1/DXT3/DXT5), - with the legacy header or the DX10 one. Uncompressed row padding follows the header's - `DDSD_PITCH` stride; without that flag, rows are tightly packed. Everything opens as U8; the - other mip levels are ignored. Cubemaps, texture arrays, volume textures, premultiplied DXT2/DXT4 and other formats - (BC4–BC7, float) are refused with `CodecError::Unsupported`. Writing (`EncodeOptions::dds`) makes - a 2D texture with the legacy header: uncompressed by default (BGRA, BGRX, or luminance with or - without alpha, so it reads back exactly), or BC1/BC2/BC3. The block encoder is our own, from + (8, 16, 24 or 32 bits, RGB or luminance, with or without alpha), BC1/BC2/BC3 (DXT1/DXT3/DXT5) or + unsigned BC4/BC5 (ATI1/ATI2, BC4U/BC5U, DXGI 79, 80, 82 and 83), with the legacy header or the + DX10 one. BC4 opens as Gray and BC5 as RGB with blue 0 (BC5 stores only red and green; a normal + map's Z is not reconstructed). ATI2 is read as Microsoft reads it, red in the first block. + Uncompressed row padding follows the header's `DDSD_PITCH` stride; without that flag, rows are + tightly packed. Everything opens as U8; the other mip levels are ignored. Cubemaps, texture + arrays, volume textures, premultiplied DXT2/DXT4, signed (SNORM) BC4/BC5 and other formats + (BC6H, BC7, float) are refused with `CodecError::Unsupported`. Writing (`EncodeOptions::dds`) + makes a 2D texture: uncompressed by default (BGRA, BGRX, or luminance with or without alpha, so + it reads back exactly), BC1/BC2/BC3 (from RGBA) with the legacy header, or BC4 (from gray, for + roughness, height and other single-channel maps) and BC5 (from RGB, blue dropped, for normal + maps) with the DX10 header (`BC4_UNORM`, `BC5_UNORM`). The plan converts other layouts to what + the compression stores, so `fidelity_warnings` reports colour to gray for BC4 and dropped alpha + for both; BC5's dropped blue comes under `LossyCompression`. The block encoder is our own, from Microsoft's public block-compression documentation: RGB565 endpoints fitted along each block's principal axis and refined by least squares, indices picked against the palette the reader - decodes; BC1 turns texels under half opacity into its transparent black, and BC3 picks - whichever alpha mode fits. `mipmaps` adds the full chain down to 1×1, each level a box filter - of the one above (the last column and row of an odd-sized level average three pixels, so none - is dropped). Cubemaps, arrays, BC4–BC7 and sRGB (DX10-only) formats aren't written. + decodes; BC1 turns texels under half opacity into its transparent black, and BC3, BC4 and BC5 + pick whichever mode of their value blocks fits. `mipmaps` adds the full chain down to 1×1, each + level a box filter of the one above (the last column and row of an odd-sized level average + three pixels, so none is dropped). Cubemaps, arrays, BC6H, BC7 and sRGB (DX10-only) formats + aren't written. * **FITS.** The image in the primary HDU, or the first `IMAGE` extension, is read; `NAXIS3 = 3` opens as RGB and any other plane count opens the first plane with `DecodeWarning::MorePages`. diff --git a/crates/image-codecs/src/codecs/dds.rs b/crates/image-codecs/src/codecs/dds.rs index 9d682b03f..26a100fab 100644 --- a/crates/image-codecs/src/codecs/dds.rs +++ b/crates/image-codecs/src/codecs/dds.rs @@ -19,7 +19,7 @@ fn error(e: DdsError) -> CodecError { } } -fn channel_layout(layout: Layout) -> ChannelLayout { +pub(crate) fn channel_layout(layout: Layout) -> ChannelLayout { match layout { Layout::Gray => ChannelLayout::Gray, Layout::GrayA => ChannelLayout::GrayA, diff --git a/crates/image-codecs/src/fidelity.rs b/crates/image-codecs/src/fidelity.rs index 12c285d7b..52d6eaa23 100644 --- a/crates/image-codecs/src/fidelity.rs +++ b/crates/image-codecs/src/fidelity.rs @@ -4,7 +4,7 @@ use std::fmt; -use crate::codecs::dpx; +use crate::codecs::{dds, dpx}; use crate::format::{Format, caps}; use crate::image::{ChannelLayout, Image, SampleType}; use crate::options::{DdsCompression, EncodeOptions}; @@ -45,7 +45,8 @@ pub enum FidelityWarning { ColorToGray, /// The image will be quantized to a 256-colour palette. PaletteQuantized, - /// The format's encoder is lossy. + /// The format's encoder is lossy. DDS BC5 also keeps only red and green: blue is dropped and + /// reads back as 0 (for a normal map, the renderer rebuilds Z from X and Y). LossyCompression, IccDropped, ExifDropped, @@ -175,8 +176,12 @@ pub(crate) fn plan(image: &Image, format: Format, opts: &EncodeOptions) -> Plan }, // CIELab has no float form: float Lab is written with 16 bits. Format::Tiff if layout.is_lab() && sample.is_float() => Plan { layout: pick_layout(layout, c.layouts, c.alpha), sample: SampleType::U16 }, - // A block-compressed DDS stores RGBA whatever the source; uncompressed keeps gray and RGB. - Format::Dds if opts.dds.compression.is_block() => Plan { layout: ChannelLayout::Rgba, sample: SampleType::U8 }, + // A block-compressed DDS stores what its compression holds whatever the source: gray for + // BC4, red and green for BC5 (written from RGB, blue dropped), RGBA for BC1 to BC3. + // Uncompressed keeps gray and RGB. + Format::Dds if opts.dds.compression.is_block() => { + Plan { layout: opts.dds.compression.layout().map_or(ChannelLayout::Rgba, dds::channel_layout), sample: SampleType::U8 } + } _ => Plan { layout: pick_layout(layout, c.layouts, c.alpha), sample: pick_sample(sample, c.depths) }, } } diff --git a/crates/image-codecs/src/format.rs b/crates/image-codecs/src/format.rs index 26696ae2a..4b6ee5bb9 100644 --- a/crates/image-codecs/src/format.rs +++ b/crates/image-codecs/src/format.rs @@ -19,7 +19,7 @@ pub enum Format { Pcx, /// X PixMap icons (XPM2 plain text and XPM3 C-string arrays). Xpm, - /// DirectDraw Surface: a 2D texture, uncompressed or BC1–BC3. Reading takes the top mip + /// DirectDraw Surface: a 2D texture, uncompressed or BC1–BC5. Reading takes the top mip /// level; writing can add the full mip chain ([`crate::DdsOptions`]). Dds, Qoi, diff --git a/crates/image-codecs/tests/it/dds.rs b/crates/image-codecs/tests/it/dds.rs index 4f766a54c..ad927019a 100644 --- a/crates/image-codecs/tests/it/dds.rs +++ b/crates/image-codecs/tests/it/dds.rs @@ -318,10 +318,83 @@ fn refuses_cubemaps_arrays_and_volumes() { unsupported(&dx10(4, 4, 71, 3, 0, 6), "array"); unsupported(&dx10(4, 4, 71, 4, 0, 1), "2D"); unsupported(&dx10(4, 4, 98, 3, 0, 1), "98"); // BC7_UNORM - unsupported(&compressed(4, 4, b"ATI2"), "ATI2"); + unsupported(&compressed(4, 4, b"ATI3"), "ATI3"); unsupported(&compressed(4, 4, b"DXT2"), "premultiplied"); } +/// A BC4 block of 200 everywhere (eight-value mode, a0 = 200 > a1 = 50, every index 0). +const BC4_200: [u8; 8] = [0xc8, 0x32, 0, 0, 0, 0, 0, 0]; +/// A value block of 250 everywhere (six-value mode, a0 = 10 <= a1 = 250, every index 1). +const VALUES_250: [u8; 8] = [0x0a, 0xfa, 0x49, 0x92, 0x24, 0x49, 0x92, 0x24]; + +#[test] +fn decodes_bc4_as_gray_from_every_name() { + // 5×3: two blocks across, one down; the second block's texels outside the image are dropped. + let blocks = [BC4_200, BC4_200].concat(); + let mut files = vec![]; + for fourcc in [b"ATI1", b"BC4U"] { + let mut b = compressed(5, 3, fourcc); + b.extend(&blocks); + files.push((String::from_utf8_lossy(fourcc).into_owned(), b)); + } + for dxgi in [79, 80] { + let mut b = dx10(5, 3, dxgi, 3, 0, 1); // BC4_TYPELESS, BC4_UNORM + b.extend(&blocks); + files.push((format!("DXGI {dxgi}"), b)); + } + for (name, b) in files { + let im = decode(&b).unwrap_or_else(|e| panic!("{name}: {e}")); + assert_eq!((im.dimensions(), im.layout()), ((5, 3), ChannelLayout::Gray), "{name}"); + assert_eq!(im.data(), &[200; 15], "{name}"); + } +} + +#[test] +fn decodes_bc5_as_red_and_green_with_blue_zero() { + let block = [BC4_200, VALUES_250].concat(); + let mut files = vec![]; + // ATI2 is BC5 as Microsoft reads it: red in the first block, not swapped as FFmpeg does. + for fourcc in [b"ATI2", b"BC5U"] { + let mut b = compressed(3, 2, fourcc); + b.extend(&block); + files.push((String::from_utf8_lossy(fourcc).into_owned(), b)); + } + // BC5_TYPELESS (what Pillow writes) and BC5_UNORM. + for dxgi in [82, 83] { + let mut b = dx10(3, 2, dxgi, 3, 0, 1); + b.extend(&block); + files.push((format!("DXGI {dxgi}"), b)); + } + for (name, b) in files { + let im = decode(&b).unwrap_or_else(|e| panic!("{name}: {e}")); + assert_eq!((im.dimensions(), im.layout()), ((3, 2), ChannelLayout::Rgb), "{name}"); + assert!(im.data().chunks(3).all(|p| p == [200, 250, 0]), "{name}: {:?}", &im.data()[..3]); + } +} + +#[test] +fn refuses_signed_bc4_and_bc5() { + for mut b in [compressed(4, 4, b"BC4S"), compressed(4, 4, b"BC5S"), dx10(4, 4, 81, 3, 0, 1), dx10(4, 4, 84, 3, 0, 1)] { + b.extend([0; 16]); + match decode_as(Format::Dds, &b) { + Err(CodecError::Unsupported { reason, .. }) => assert!(reason.contains("SNORM"), "{reason}"), + other => panic!("{other:?}"), + } + } +} + +#[test] +fn truncated_bc4_and_bc5_data_is_refused() { + let mut b = dx10(5, 5, 83, 3, 0, 1); // four 16-byte blocks + b.extend([0x5a; 64]); + assert!(decode(&b).is_ok()); + assert!(matches!(decode_as(Format::Dds, &b[..b.len() - 1]), Err(CodecError::Malformed { .. }))); + let mut b = compressed(5, 5, b"ATI1"); // four 8-byte blocks + b.extend([0x5a; 32]); + assert!(decode(&b).is_ok()); + assert!(matches!(decode_as(Format::Dds, &b[..b.len() - 1]), Err(CodecError::Malformed { .. }))); +} + /// Face declarations matter even when the general cube flag is absent; padding does not. #[test] fn source_probe_distinguishes_extra_faces_from_single_images_and_padding() { diff --git a/crates/image-codecs/tests/it/dds_write.rs b/crates/image-codecs/tests/it/dds_write.rs index f9d9add8e..bc92c87b6 100644 --- a/crates/image-codecs/tests/it/dds_write.rs +++ b/crates/image-codecs/tests/it/dds_write.rs @@ -16,6 +16,8 @@ const DDPF_ALPHAPIXELS: u32 = 0x1; const DDPF_FOURCC: u32 = 0x4; const DDPF_RGB: u32 = 0x40; const DDPF_LUMINANCE: u32 = 0x2_0000; +const DXGI_BC4_UNORM: u32 = 80; +const DXGI_BC5_UNORM: u32 = 83; const BLOCKS: [DdsCompression; 3] = [DdsCompression::Bc1, DdsCompression::Bc2, DdsCompression::Bc3]; @@ -80,11 +82,21 @@ fn psnr(a: &Image, b: &Image) -> f64 { if mse == 0.0 { f64::INFINITY } else { 10.0 * (255.0f64.powi(2) / mse).log10() } } +/// Whether a written texture has the DX10 header after the legacy one. +fn has_dx10(file: &[u8]) -> bool { + le32(file, 80) & DDPF_FOURCC != 0 && &file[84..88] == b"DX10" +} + +/// Bytes of the headers before the first level. +fn head(file: &[u8]) -> usize { + if has_dx10(file) { 148 } else { 128 } +} + /// Bytes of one level as a reader computes them from the header's pixel format. fn level_bytes(file: &[u8], w: usize, h: usize) -> usize { if le32(file, 80) & DDPF_FOURCC != 0 { - let block = if &file[84..88] == b"DXT1" { 8 } else { 16 }; - w.div_ceil(4) * h.div_ceil(4) * block + let eight = &file[84..88] == b"DXT1" || (has_dx10(file) && le32(file, 128) == DXGI_BC4_UNORM); + w.div_ceil(4) * h.div_ceil(4) * if eight { 8 } else { 16 } } else { w * h * le32(file, 88) as usize / 8 } @@ -94,9 +106,9 @@ fn level_bytes(file: &[u8], w: usize, h: usize) -> usize { fn level(file: &[u8], i: u32) -> Image { let (w, h) = (le32(file, 16) as usize, le32(file, 12) as usize); let size = |i: u32| ((w >> i).max(1), (h >> i).max(1)); - let start = 128 + (0..i).map(|j| level_bytes(file, size(j).0, size(j).1)).sum::(); + let start = head(file) + (0..i).map(|j| level_bytes(file, size(j).0, size(j).1)).sum::(); let (lw, lh) = size(i); - let mut b = file[..128].to_vec(); + let mut b = file[..head(file)].to_vec(); b[12..16].copy_from_slice(&(lh as u32).to_le_bytes()); b[16..20].copy_from_slice(&(lw as u32).to_le_bytes()); b[28..32].copy_from_slice(&1u32.to_le_bytes()); @@ -338,15 +350,122 @@ fn fidelity_warnings_follow_the_compression() { } assert!(warns(DdsCompression::Bc1).contains(&FidelityWarning::AlphaBinarized)); assert!(!warns(DdsCompression::Bc3).contains(&FidelityWarning::AlphaBinarized)); + // BC4 is gray and BC5 has no alpha: translucent colour loses what they don't hold. + let bc4 = warns(DdsCompression::Bc4); + for w in [FidelityWarning::LossyCompression, FidelityWarning::ColorToGray, FidelityWarning::AlphaDiscarded] { + assert!(bc4.contains(&w), "BC4: {w:?} missing from {bc4:?}"); + } + let bc5 = warns(DdsCompression::Bc5); + assert!(bc5.contains(&FidelityWarning::LossyCompression) && bc5.contains(&FidelityWarning::AlphaDiscarded), "{bc5:?}"); + assert!(!bc5.contains(&FidelityWarning::ColorToGray) && !bc5.contains(&FidelityWarning::AlphaBinarized), "{bc5:?}"); + // A gray map written as BC4 loses only to the compression. + let gray = ramp(8, 8, ChannelLayout::Gray); + assert_eq!(fidelity_warnings_with(&gray, Format::Dds, &opts(DdsCompression::Bc4, false)), [FidelityWarning::LossyCompression]); +} + +/// The largest difference in channel `c` between two images of `channels` channels. +fn max_diff(a: &Image, b: &Image, channels: usize, c: usize) -> u8 { + a.data().chunks(channels).zip(b.data().chunks(channels)).map(|(x, y)| x[c].abs_diff(y[c])).max().unwrap_or(0) +} + +/// `gradient`'s red as gray, or its red, green and blue. +fn gradient_as(w: u32, h: u32, layout: ChannelLayout) -> Image { + let rgba = gradient(w, h); + let data = rgba.data().chunks(4).flat_map(|p| if layout == ChannelLayout::Gray { vec![p[0]] } else { p[..3].to_vec() }).collect(); + Image::from_u8(w, h, layout, data).unwrap() +} + +#[test] +fn bc4_and_bc5_are_written_with_the_dx10_header() { + for (compression, dxgi, block, layout) in + [(DdsCompression::Bc4, DXGI_BC4_UNORM, 8, ChannelLayout::Gray), (DdsCompression::Bc5, DXGI_BC5_UNORM, 16, ChannelLayout::Rgb)] + { + for (w, h) in [(1, 1), (2, 2), (5, 3), (33, 17)] { + let img = ramp(w, h, layout); + let b = encode(&img, Format::Dds, &opts(compression, false)).unwrap(); + let linear = w.div_ceil(4) * h.div_ceil(4) * block; + assert_eq!(&b[84..88], b"DX10"); + assert_eq!((le32(&b, 80), le32(&b, 88)), (DDPF_FOURCC, 0)); + assert_eq!(le32(&b, 8), REQUIRED | DDSD_LINEARSIZE, "linear size, not pitch"); + assert_eq!(le32(&b, 20), linear, "{compression:?} {w}x{h}: the top level's size"); + // DXGI format, a 2D texture, no misc flags, one texture, alpha mode unknown. + assert_eq!([le32(&b, 128), le32(&b, 132), le32(&b, 136), le32(&b, 140), le32(&b, 144)], [dxgi, 3, 0, 1, 0]); + assert_eq!(b.len(), 148 + linear as usize); + assert!(!craft_image_codecs::has_unretained_source_data(&b).unwrap()); + let back = decode(&b).unwrap(); + assert_eq!((back.dimensions(), back.layout()), ((w, h), layout), "{compression:?} {w}x{h}"); + } + } +} + +#[test] +fn bc4_and_bc5_error_on_gradients_is_bounded() { + // Each block of the gradient spans 12 levels in a channel: eight values (or six and the + // extremes) are under two levels apart. + let gray = gradient_as(64, 64, ChannelLayout::Gray); + let back = decode(&encode(&gray, Format::Dds, &opts(DdsCompression::Bc4, false)).unwrap()).unwrap(); + assert_eq!(back.layout(), ChannelLayout::Gray); + let err = max_diff(&gray, &back, 1, 0); + assert!(err <= 2, "BC4 off by {err}"); + + let rgb = gradient_as(64, 64, ChannelLayout::Rgb); + let back = decode(&encode(&rgb, Format::Dds, &opts(DdsCompression::Bc5, false)).unwrap()).unwrap(); + assert_eq!(back.layout(), ChannelLayout::Rgb); + let (red, green) = (max_diff(&rgb, &back, 3, 0), max_diff(&rgb, &back, 3, 1)); + assert!(red <= 2 && green <= 2, "BC5 red off by {red}, green by {green}"); + assert!(back.data().chunks(3).all(|p| p[2] == 0), "BC5 has no blue"); +} + +#[test] +fn bc4_and_bc5_take_any_source_layout() { + // RGBA to BC4 goes through gray; to BC5 through RGB, dropping alpha and then blue. + let img = gradient(9, 7); + for (compression, layout) in [(DdsCompression::Bc4, ChannelLayout::Gray), (DdsCompression::Bc5, ChannelLayout::Rgb)] { + let back = decode(&encode(&img, Format::Dds, &opts(compression, true)).unwrap()).unwrap(); + let want = img.convert(layout, img.sample_type()); + let ch = layout.channels(); + assert_eq!((back.dimensions(), back.layout()), ((9, 7), layout)); + for c in 0..ch.min(2) { + let err = max_diff(&want, &back, ch, c); + assert!(err <= 8, "{compression:?} channel {c} off by {err}"); + } + } +} + +#[test] +fn bc4_and_bc5_mip_chains_follow_the_box_filter() { + for (compression, layout, block) in [(DdsCompression::Bc4, ChannelLayout::Gray, 8), (DdsCompression::Bc5, ChannelLayout::Rgb, 16)] { + let img = gradient_as(12, 6, layout); + let b = encode(&img, Format::Dds, &opts(compression, true)).unwrap(); + // 12×6, 6×3, 3×1, 1×1: 3×2, 2×1, 1 and 1 blocks after both headers. + assert_eq!(le32(&b, 28), 4); + assert_eq!(le32(&b, 8), REQUIRED | DDSD_LINEARSIZE | DDSD_MIPMAPCOUNT); + assert_eq!(b.len(), 148 + (6 + 2 + 1 + 1) * block); + let mut want = img.clone(); + for i in 0..4 { + let got = level(&b, i); + assert_eq!((got.dimensions(), got.layout()), (want.dimensions(), layout), "{compression:?} level {i}"); + for c in 0..layout.channels().min(2) { + // Smaller levels are steeper (8, then 16 levels a pixel), so a block's values + // sit up to a few levels off its palette. + let err = max_diff(&want, &got, layout.channels(), c); + assert!(err <= 4, "{compression:?} level {i} channel {c} off by {err}"); + } + want = box_filter(&want); + } + } } #[test] fn compression_names_round_trip() { + assert_eq!(DdsCompression::ALL.len(), 6); for c in DdsCompression::ALL { assert_eq!(DdsCompression::from_name(c.name()), Some(c)); } assert_eq!(DdsCompression::from_name("DXT5"), Some(DdsCompression::Bc3)); assert_eq!(DdsCompression::from_name("dxt1"), Some(DdsCompression::Bc1)); + assert_eq!(DdsCompression::from_name("ATI1"), Some(DdsCompression::Bc4)); + assert_eq!(DdsCompression::from_name("ati2"), Some(DdsCompression::Bc5)); for bad in ["", "bc7", "dxt2", "uncompressed "] { assert_eq!(DdsCompression::from_name(bad), None, "{bad:?}"); } diff --git a/crates/raster-codecs/README.md b/crates/raster-codecs/README.md index 907e73763..eec7ac0d5 100644 --- a/crates/raster-codecs/README.md +++ b/crates/raster-codecs/README.md @@ -11,7 +11,7 @@ craft-raster-codecs = { git = "https://github.com/storytold/craft-libs", rev = " | Module | Format | Read | Write | |---|---|---|---| -| `dds` | DirectDraw Surface: uncompressed masks, luminance, BC1/BC2/BC3 (DXT1/3/5), legacy and DX10 headers; top mip level | yes | uncompressed and BC1-BC3, optional mip chain | +| `dds` | DirectDraw Surface: uncompressed masks, luminance, BC1/BC2/BC3 (DXT1/3/5), unsigned BC4/BC5 (ATI1/2, as gray and as RGB with blue 0), legacy and DX10 headers; top mip level | yes | uncompressed and BC1-BC3, optional mip chain | | `dicom` | DICOM Part 10, uncompressed transfer syntaxes: MONOCHROME1/2, RGB, YBR_FULL, 8 and 16 bits | yes | no | | `fits` | FITS primary HDU or first `IMAGE` extension, every `BITPIX`, `BSCALE`/`BZERO`, header cards as text | yes | gray or RGB; 8-bit, 16-bit, float | | `iff` | IFF ILBM (1 to 8 planes with a palette, 24 planes, mask plane or transparent colour) and PBM, stored or ByteRun1; HAM and EHB are refused | yes | 24-plane ILBM with an optional mask plane | diff --git a/crates/raster-codecs/src/lib.rs b/crates/raster-codecs/src/lib.rs index 7e705da99..a9aa7c4c6 100644 --- a/crates/raster-codecs/src/lib.rs +++ b/crates/raster-codecs/src/lib.rs @@ -3,7 +3,7 @@ //! //! | Module | Format | Read | Write | //! |---|---|---|---| -//! | [`dds`] | DirectDraw Surface: uncompressed masks, BC1-BC3 (DXT1/3/5), the DX10 header | yes | yes | +//! | [`dds`] | DirectDraw Surface: uncompressed masks, BC1-BC5 (DXT1/3/5, ATI1/2), the DX10 header | yes | yes (uncompressed, BC1-BC3) | //! | [`dicom`] | DICOM Part 10, uncompressed native pixel data | yes | no | //! | [`fits`] | FITS primary and image-extension HDUs | yes | yes | //! | [`iff`] | IFF ILBM (palette or 24-bit planes, masks) and PBM | yes | yes (24-plane ILBM) | diff --git a/crates/raster-codecs/tests/dds.rs b/crates/raster-codecs/tests/dds.rs index afb9066aa..d5c482aa7 100644 --- a/crates/raster-codecs/tests/dds.rs +++ b/crates/raster-codecs/tests/dds.rs @@ -320,7 +320,8 @@ fn refuses_cubemaps_arrays_and_volumes() { unsupported(&dx10(4, 4, 71, 3, 0, 6), "array"); unsupported(&dx10(4, 4, 71, 4, 0, 1), "2D"); unsupported(&dx10(4, 4, 98, 3, 0, 1), "98"); // BC7_UNORM - unsupported(&compressed(4, 4, b"ATI2"), "ATI2"); + unsupported(&compressed(4, 4, b"ATI3"), "ATI3"); + unsupported(&compressed(4, 4, b"BC5S"), "SNORM"); unsupported(&compressed(4, 4, b"DXT2"), "premultiplied"); }