Skip to content

Abstractions 2.0 - #2

Merged
sdcb merged 39 commits into
mainfrom
v2
Nov 4, 2026
Merged

sdcb merged 39 commits into
mainfrom
v2

Conversation

@sdcb

@sdcb sdcb commented Nov 4, 2026

Copy link
Copy Markdown
Owner

Implements docs/abstractions-2.0-design.md (the plan for the breaking 2.0 of Sdcb.SimdCodecs.Abstractions): PixelFormat (16-bit, premultiplied, grey+alpha), IDecodedImage 2.0, ImageInfo colour/resolution, decode options + cancellation, metadata/thumbnails, the ImageDecoder session API over Stream, public planar YCbCr, the encoder abstraction and pooled rasters.

Draft while in progress; opened early so every push runs the full CI (tiers, arm64, NativeAOT, wasm).

Out of scope for 2.0 (2.x perf items, no API change): true streaming input per codec, native JPEG region decode, JPEG 2000 reduce, TIFF segment skipping.

🤖 Generated with Claude Code

sdcb and others added 30 commits November 4, 2026 15:44
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… 2.0, options, metadata, planar

- PixelFormat (ChannelLayout x 8/16-bit x AlphaMode) replaces ImagePixelFormat.
- PixelConverter: any PixelFormat -> any PixelFormat; 16->8 keeps v >> 8 (8-bit
  goldens unchanged), 8->16 is v x 257, premultiply round(c*a/max), unpremultiply
  min(max, round(c*max/a)) with a = 0 -> 0. Vector128 kernels keep scalar twins.
- IDecodedImage: IDisposable, BitDepth, Metadata, ToRgba16, TryCopyTo.
- RasterImage: Wrap/Allocate/Rent/Create/Crop factories, pooled memory, Dispose.
- IImageDecoder: DecodeOptions + CancellationToken, TryGetClosestSize,
  TryReadMetadata, TryDecodeThumbnail. IPlanarImageDecoder + PlanarInfo.
- ImageInfo: ColorEncoding, Resolution, HasThumbnail.

The rest of the solution is ported in the following commits.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- JpegImageDecoder: PixelFormat (native for the five basic 8-bit formats, generic
  otherwise), DecodeOptions with native DCT-domain scaling (1/2/4/8) and
  TryGetClosestSize, region via crop, cancellation once per MCU row, Exif/XMP/ICC
  metadata, JFIF/Exif resolution, Exif IFD1 thumbnail.
- src/Shared/ExifBlock.cs: bounds-checked IFD0 resolution and IFD1 thumbnail reader.
- Gain map: HDR tier honours options (region crop) and cancellation; SDR tier
  forwards to JPEG.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Ported by a gemini-3.8-flash sub-agent; reviewed and build-verified.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…, planar)

- HeifColor.For16 / ToRgba64420Row: the 16-bit conversion, defined like the
  frozen 8-bit one with 65535 in place of 255 (64-bit products), scalar.
  The 8-bit kernels are untouched.
- Main 10 now decodes to 16-bit samples (BitDepth 10); 8-bit images and every
  8-bit TryDecodeInto output are unchanged.
- HeifImageDecoder implements IPlanarImageDecoder (canvas planes, no transforms),
  TryReadMetadata (cdsc Exif / XMP mime items, ICC), TryDecodeThumbnail (thmb).
- Cancellation per tile and per band of output rows (ParallelOptions).
- ISOBMFF: record a mime item's content_type; SPS VUI chroma_sample_loc_type.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Ported by a gemini-3.8-flash sub-agent; reviewed and build-verified. 16-bit
PixelFormat input writes a 16-bit PNM (maxval 65535).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…tration)

IImageEncoder (static abstract, registration by method group), the
IImageEncoderSession / IImageFrameEncoder session after WIC's frame encoder,
EncodeOptions, and BufferedEncoderSession for codecs that encode a whole image.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Ported by a gemini-3.8-flash sub-agent; reviewed and build-verified. Encoders take
any PixelFormat (converted to the ARGB words by PixelConverter, identical bytes
for the five 1.x formats); cancellation per macroblock row / row group / frame.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…and the ImageDecoder session API

- SimdCodecs: every entry point takes PixelFormat / DecodeOptions / CancellationToken;
  new TryGetClosestSize, TryReadMetadata, TryDecodeThumbnail, TryReadPlanarInfo,
  TryDecodePlanes. The registry is built from each codec's Registration property
  (method groups bound in the codec, never in a generic method).
- ImageDecoder / ImageFrame: the WIC-style session over Stream, memory or a
  memory-mapped file (IByteSource), with OpenAsync for non-seekable streams.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…tions 2.0

- PixelConverterTests: the reference now covers every source PixelFormat x every
  destination PixelFormat (16 x 16, including premultiplied, 16-bit, grey+alpha)
  and in-place conversion; frozen-number tests for x257, >>8, premultiply and
  unpremultiply (every 8-bit pair).
- HEIF: Main 10 decodes to 16-bit samples; its 8-bit TryDecodeInto keeps the
  frozen 1.x conversion (documented exception, <= 1 code value from v >> 8).
- TIFF info reports the baseline 96 dpi the test file writes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The 2.0 decode/encode entry points take a CancellationToken, so xUnit1051 flagged
343 test calls; each now passes TestContext.Current.CancellationToken. The
solution builds with 0 warnings again.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ter (reference)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…am input, metadata)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
….0 draft)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…gisterEncoder)

The encoder registry binds each built-in codec's Registration (PNG, JPEG, TIFF,
WebP so far); SimdCodecs.Encode(IDecodedImage, format, stream) passes the image's
colour encoding and metadata blocks to the encoder, so a transcode keeps them.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Written by a gemini-3.8-flash sub-agent; reviewed, build- and test-verified
(57 tests: every PixelFormat equals the codec's encoder on the converted pixels).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Written by a gemini-3.8-flash sub-agent; reviewed, build- and test-verified
(54 tests, including a 3-frame GIF animation).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
sdcb and others added 9 commits November 4, 2026 17:26
… covers the 2.0 entry points

The smoke now exercises TryGetClosestSize, TryReadMetadata, TryDecodeThumbnail,
TryReadPlanarInfo, scaled and region decodes, Rgba64 and Bgra32Premultiplied
output, the ImageDecoder session and Encode / GetClosestInputFormat for every
built-in encoder, all through registry delegates.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
DecodeOptions.Region is one more translation in HeifCanvas's display map, so the
preimage shrinks to the canvas pixels that land in it: grid tiles outside it are
not decoded, and only its pixels are converted. Tests: random irot / imir chains
x regions spanning tile edges x 8- and 16-bit formats equal the crop of the whole
decode exactly.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Found by the new session tests: TryDecodeInto with a Region went through the
generic decode-to-RGB-then-crop path, so a YCbCr JPEG's Gray8 was the luma of
the RGB instead of its stored Y plane. A region now takes the native path for the
format and copies the region out; the test is un-skipped.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…tes)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@sdcb
sdcb marked this pull request as ready for review November 4, 2026 10:17
@sdcb
sdcb merged commit 609799b into main Nov 4, 2026
7 checks passed
sdcb added a commit that referenced this pull request Nov 4, 2026
Abstractions 2.0
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant