Files
craft-libs/crates/raster-codecs/README.md
T
vangel76 f31c93cf59 DDS: read and write BC4 and BC5 (grayscale data and normal maps)
BC4 is one block of 16 single-channel values and BC5 two of them, the
block BC3 already stores its alpha in, so the alpha block encoder and
decoder now serve all three (BC3's output stays the same).

Reading: ATI1 and BC4U, and DXGI 79 (typeless) and 80, open as gray;
ATI2 and BC5U, and DXGI 82 (typeless, as Pillow writes it) and 83,
open as RGB with blue 0. ATI2 follows Microsoft's mapping, red in the
first block. Signed BC4S/BC5S and DXGI 81/84 are refused, naming SNORM.

Writing: DdsCompression::Bc4 (bc4, ati1) from gray and Bc5 (bc5, ati2)
from RGB, with the DX10 header (BC4_UNORM, BC5_UNORM, one 2D texture),
mip chains included. The encode plan converts other layouts to gray
and RGB, so the fidelity warnings report colour to gray and dropped
alpha; BC5's dropped blue is documented under LossyCompression.

DdsCompression is now #[non_exhaustive] and ALL has six entries.
2026-11-16 00:00:28 +01:00

62 lines
3.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# craft-raster-codecs
Compatibility facade for the small raster-format modules in older Craft app versions. The
format readers and writers are implemented once in [`craft-image-codecs`](../image-codecs/README.md);
these modules forward calls and adapt the older `Image` and `Limits` types. The `common` RGBA
image facade also delegates to that crate.
```toml
craft-raster-codecs = { git = "https://github.com/storytold/craft-libs", rev = "<commit>" }
```
| Module | Format | Read | Write |
|---|---|---|---|
| `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 |
| `pcx` | ZSoft PCX: RLE scanlines, 16 and 256-colour palettes, 8-bit three-plane RGB and four-plane RGBA; a `dimensions` probe | yes | no |
| `pnm` | Netpbm: PBM, PGM, PPM (plain and raw, 8 and 16 bits), PAM, PFM | yes | PGM, PPM, PAM, PFM |
| `xpm` | X PixMap: XPM3 and XPM2, X11 colour names | yes | no |
## The model
`Image` is a flat raster: width, height, a `ChannelLayout` (gray, RGB or CMYK, each with or
without straight alpha), a `SampleType` (`U8`, `U16`, `F32`) and interleaved, native-endian
samples, top row first. It also carries what these formats state beside the pixels: `dpi` (PCX),
`text` (FITS header cards) and `warnings` (a FITS cube opened as its first plane).
```rust
use craft_raster_codecs::{Limits, pnm};
let image = pnm::decode(b"P2\n2 1\n255\n0 255\n", &Limits::default())?;
assert_eq!(image.data(), &[0, 255]);
let bytes = pnm::encode(&image)?;
```
The module sniffers and the `dds`/`fits` additional-image queries forward to shared detection and
metadata inspection in `craft-image-codecs`.
`xpm::x11_color_rgb` also looks up exact normalized X11 names as RGB channels in `0..=1`.
It accepts only 1–64 lowercase ASCII letters or digits, without normalization, XPM-only aliases,
CSS overrides or color-space conversion. XPM decoding keeps its existing name and alias policy.
Encoders take an image already in a layout and depth the format stores, and return
`CodecError::Encode` for any other. Choosing the nearest layout and converting to it stays in the
app. The same goes for colour management, orientation, format detection across a whole format
list, and mapping `Image` onto the app's own document.
## Limits
`Limits` bounds width, height, pixel count and the bytes of the decoded buffer. The default is
2^18 pixels a side, 2^30 pixels and 8 GiB (1 GiB on 32-bit targets). Compressed formats (IFF,
PCX) also refuse a file too small to hold what its header declares, before allocating. Text
formats (plain PNM, XPM) reserve from the bytes present, not from the header.
## Tests
`cargo test -p craft-raster-codecs`. `tests/roundtrip.rs` writes every layout and depth each
writer stores and reads it back exactly, then truncates, bit-flips and overwrites header bytes of
a valid file of every format: a reader may refuse, never panic. Two tests are ignored by default:
a DDS encode timing, and a PNM peak-memory check that reads the process's RSS.