Support for JPEG XL (JXL) images by winscripter · Pull Request #3153 · SixLabors/ImageSharp

winscripter · 2026-07-15T09:41:42Z

Prerequisites

I have written a descriptive pull-request title
I have verified that there are no overlapping pull-requests open
I have verified that I am following the existing coding patterns and practice as demonstrated in the repository. These follow strict Stylecop rules 👮.
I have provided test coverage for my change (where applicable)

Description

This is a work-in-progress PR whose goal is to introduce decoding and encoding of JPEG XL (*.jxl) images.

Reference software
I use libjxl as reference. See https://github.com/libjxl/libjxl.

Performance
I will begin by applying light optimizations as I implement parts of the JPEG XL codec. Once the codec seems complete enough to handle decoding and encoding of JPEG XL images, I will apply heavier optimizations. Examples include but are not limited to stack allocation, array pooling, and SIMD.

Implementations
The JPEG XL codec lives under src/ImageSharp/Formats/Jxl.

Testing
I will start adding tests whenever the codec is complete enough to handle decoding of JPEG XL images.

Additionally, JPEG XL reference software, libjxl, contains its own tests too, which I might also implement without modification.

Progress

🔴 - work didn't start yet
🟠 - exists, but incomplete
🟡 - either decoding side, encoding side, or tests are complete, but not the other
🟢 - complete

🟡 AC strategy
🟢 AC strategy image/row
🟢 AC context
🔴 AC strategy tests
🟠 Adaptive Quantization (encoder)
🟠 ANS Entropy
🟢 ANS Entropy: Common
🟢 ANS Entropy: Common (Tests)
🟠 ANS Entropy: Decoder (symbol reader is incomplete)
🟠 ANS Entropy: Encoder (SIMD bit-cost calculation only)
🔴 ANS Entropy: Tests
🟢 Alpha Blending
🟡 Bit I/O
🟢 Bit I/O: Bit reader
🟢 Bit I/O: Bit writer
🔴 Bit I/O: tests
🟢 Box Content Decoder
🟢 Box Content Decoder: Uncompressed boxes
🟢 Box Content Decoder: Brotli-compressed boxes
🟡 Butteraugli
🟢 Butteraugli: Shared methods
🟢 Butteraugli: Abstractions
🟢 Butteraugli: Default comparator
🔴 Butteraugli: Encoder comparator
🟡 Cache
🟠 Cache: Decoder
🔴 Cache: Encoder
🟠 Chroma From Luma
🟢 Chroma From Luma Abstractions
🔴 Chroma From Luma Encoder
🟡 Coefficient Order
🟢 Coefficient Order: Forward
🟢 Coefficient Order: Main
🟢 Coefficient Order: Encoder
🔴 Coefficient Order: Tests
🔴 Compressed DC
🟡 Context Map
🟢 Context Map: Abstractions
🟢 Context Map: Decoder
🔴 Context Map: Encoder
🟡 Convolution
🟢 Convolution: Symmetric
🟢 Convolution: Separable
🟢 Convolution: Slow
🟢 Convolution: SIMD
🔴 Convolution: Separable5 Encoder
🔴 Convolution: Tests
🟠 Decoder: Frame
🔴 Decoder: Group
🟢 Decoder: Group Border
🟠 Decoder: Main
🟢 Decoder: Main: Codestream parser
🟢 Decoder: Main: Container format parser
🟡 Discrete Cosine Transform
🟢 Discrete Cosine Transform: DCT scales
🟢 Discrete Cosine Transform: Block data wrapper
🟠 Discrete Cosine Transform: Block-based
🟢 Discrete Cosine Transform: Slow DCT for reference in tests
🔴 Discrete Cosine Transform: Tests
🔴 Encoder dot detection
🔴 Encoder dot dictionary
🟠 Entropy coding
🔴 Encoder entropy coding
🟠 Fast Lossless Encoder
🟢 Fields
🟢 Fields: Visitor abstractions
🟢 Fields: Parser
🟢 Fields: Writer
🔴 Frame Encoder
🟢 Gaborish
🟢 Gaborish Encoder
🟢 Gaborish Tests
🔴 Group Encoder
🔴 Heuristics Encoder
🟡 Image Bundle
🟠 Image Bundle: Decoder/Common
🔴 Image Bundle: Encoder
🟡 LZ77 compression
🟢 LZ77: Fast Lossless Encoder
🔴 LZ77: Standard Encoder
🟢 Huffman compression
🟢 Huffman compression: Shared
🟢 Huffman compression: Decoder
🟢 Huffman compression: Encoder
🟡 Modular
🟢 Modular: Transforms
🟢 Modular: Transforms: Palette (Inverse)
🟢 Modular: Transforms: Palette (Forward)
🟢 Modular: Transforms: RCT (Inverse)
🟢 Modular: Transforms: RCT (Forward)
🟢 Modular: Transforms: Squeeze (Inverse)
🟢 Modular: Transforms: Squeeze (Forward)
🟢 Modular: Encoding
🟢 Modular: Encoding: Context Prediction
🟢 Modular: Encoding: MA decoder
🟢 Modular: Encoding: MA encoder
🟢 Modular: Encoding: Tree Samples
🟢 Modular: Encoding: Encoding decoder
🟢 Modular: Encoding: Encoding encoder
🔴 Modular: Decoder
🔴 Modular: Encoder
🔴 Modular: Encoder SIMD
🔴 Modular: Tests
🟠 Patch Dictionary: Decoder
🔴 Patch Dictionary: Encoder
🟠 Passes State: Decoder
🔴 Passes State: Encoder
🟢 Passes State: Shared
🔴 Encoder Main
🔴 Encoder Main
🔴 Encoder Internal
🔴 Encoder Tests
🟢 Encoder: Linear Algebra
🟢 Encoder: Linear Algebra Tests
🟢 Image Operations
🟢 Image Operations
🟢 Image Operations: Tests
🟢 Common I/O: Frame Header
🟢 Common I/O: Metadata
🟢 Common I/O: Container format
🟠 JPEG to JPEG XL lossless compression
🟢 JPEG to JPEG XL lossless compression: JPEG parser/writer
🟠 JPEG to JPEG XL lossless compression (decoder)
🔴 JPEG to JPEG XL lossless compression (encoder)
🟡 Splines
🟢 Splines
🔴 Splines Tests
🟢 Quantizer
🟢 Dequantizer matrices
🟢 Quantizer encoding
🟢 Quantizer weights
🟡 Noise
🟢 Noise: Shared
🟢 Noise: Decoder
🟠 Noise: Encoder
🟢 Noise: Simulation of Photon Noise
🟢 Noise: Simulation of Photon Noise (Tests)
🔴 Noise Tests
🔴 JPEG XL Testing Tools
🟠 Render Pipeline
🔴 Render Pipeline: Main
🔴 Render Pipeline: Low Memory Render Pipeline
🟠 Render Pipeline: Stages Abstractions
🔴 Render Pipeline: Stages: Blending
🔴 Render Pipeline: Stages: Chroma Upsampling
🔴 Render Pipeline: Stages: CMS
🟢 Render Pipeline: Stages: EPF
🔴 Render Pipeline: Stages: From Linear
🟢 Render Pipeline: Stages: Gaborish
🔴 Render Pipeline: Stages: Noise
🟢 Render Pipeline: Stages: Patches
🔴 Render Pipeline: Stages: Splines
🟢 Render Pipeline: Stages: Spot color
🔴 Render Pipeline: Stages: To Linear
🔴 Render Pipeline: Stages: Tone mapping
🔴 Render Pipeline: Stages: Upsampling
🟠 Render Pipeline: Stages: Write to Output
🔴 Render Pipeline: Stages: XYB
🟢 Render Pipeline: Stages: Y'Cb'Cr -> RGB
🟡 Color Management System (CMS)
🟢 CMS: Transfer Functions
🟢 CMS: Abstractions/Color Encoding
🔴 CMS: Tone Mapping
🔴 CMS: Interface

Other completed things:

🟢 Frame Dimensions
🟢 Field Encodings
🟢 Gamma correction (tests, encoder)
🟢 Shared math functions
🟢 Lehmer Codes
🟢 Lehmer Codes: Tests
🟢 Luminance helper
🟢 Opsin parameters
🟢 Passes shared state
🟢 SIMD utilities
🟢 TOC
🟢 XorShift128Plus
🟢 XorShift128Plus Tests

CLAassistant · 2026-07-15T09:41:49Z

All committers have signed the CLA.

Implementation of ac_strategy.h and ac_strategy.c

For now JxlMemoryManager will be a wrapper around MemoryPool<T>.

Implementation of image.h and image.c; AC strategy implementation was slightly adjusted to reduce errors.

This is an implementation of field_encodings.h. Note that I avoided implementing EnumValid() and Values() functions, as we have dedicated methods in .NET to do exactly that (Enum.IsDefined, Enum.GetValues)

Implementation of spline.h

Implemented ANS constants

winscripter · 2026-07-16T07:37:16Z

While I'm working on this, I'd like to note something important.

Libjxl is licensed under the BSD 3-Clause license, and since I'm using libjxl code as reference, that means the license must be included.

I'm not really sure what would be the proper way to include the license. I might place the LICENSE.txt file in the Jxl folder or add a README linking to the libjxl repo.

See ans_common.h

It is too large for a struct.

See ans_common.h

Add JxlAnsEntry and JxlAnsSymbol. See ans_common.h. These correspond to the Entry and Symbol structures within AliasTable.

Currently, there's a VarLenUint8/VarLenUint16 as well as histogram parsing implementation. I will additionally have to implement parsing of ANS codes, uint config and LZ77 parameters.

…lass name

… output stage, specify enum type as byte

…signer, complete noise decoder, XYB encoder, reference DCT

gfoidl · 2026-09-08T11:59:37Z

+{
+    [Conditional("DEBUG")]
+    public static void LogWarning(string message) =>
+        // TODO: do we allow Debug.WriteLine in this codebase?


@JimBobSquarePants?

gfoidl · 2026-09-08T12:10:12Z

+
+namespace SixLabors.ImageSharp.Formats.Jxl.Processing.Decoder.Modular;
+
+internal sealed class JxlModularFrameDecoder


Just as reminder: this class is WIP

gfoidl · 2026-09-09T09:41:20Z

+    public static ReadOnlySpan<float> GetResampleScales(int x, int y)
+    {
+        DebugGuard.IsTrue(x is 1 or 2 or 4 or 8 or 16 or 32 or 64 or 128 or 256, "x is invalid");
+        if (x == 1)


Can make this a switch?
Roslyn (C# compiler) can often emit more optimized code than for an if-sequence.

gfoidl · 2026-09-09T09:48:30Z

+        // TODO: unrolling this would lead to big performance benefits
+        for (int iy = 0; iy < 4; iy++)


As the count of iterations is constant, the JIT (.NET 8 onwards) will unroll the loop.

gfoidl · 2026-09-09T09:57:19Z

+        for (int iy = 0; iy < 4; iy++)
+        {
+            // Variables so we don't repeat multiplication over and over again
+            int iy4 = iy * 4; // iy multiplied by 4


Instead of that multiplication you could increment the lopp variable by 4, so

for (int iy4 = 0; iy4 < 4 * 4; iy4 += 4) { // ... }

In L462 the check is still correct, after iy -> iy4.

L458 would become:

int iy28 = iy4 * 4;

and to avoid that multiplication you change the loop to

int iy28 = 0; for (int iy4 = 0; iy4 < 16; iy4 += 4) { // loop body here iy28 += 16; }

iy28 could be in the loop declaration itself (for (int iy4 = 0, iy28 = 0; iy4 < 16; iy4 += 4, iy28 += 16)), but then the JIT won't unroll the loop anymore.

The same technique for "strength reduction" could be done in the loops below.
I'm not sure if the JIT does it for us or not (though there were some improvements in the recent JIT versions).

gfoidl · 2026-09-10T11:50:45Z

+        Span<ushort> bits = stackalloc ushort[FjxlSimdVec16.Lanes];
+        Span<ushort> nbits = stackalloc ushort[FjxlSimdVec16.Lanes];
+        Span<ushort> bitsHuff = stackalloc ushort[FjxlSimdVec16.Lanes];
+        Span<ushort> nbitsHuff = stackalloc ushort[FjxlSimdVec16.Lanes];
+        Span<ushort> token = stackalloc ushort[FjxlSimdVec16.Lanes];


Combine and slice?

gfoidl · 2026-09-10T11:51:39Z

+        Span<ushort> bits = stackalloc ushort[FjxlSimdVec16.Lanes];
+        Span<ushort> nbits = stackalloc ushort[FjxlSimdVec16.Lanes];
+        Span<ushort> bitsHuff = stackalloc ushort[FjxlSimdVec16.Lanes];
+        Span<ushort> nbitsHuff = stackalloc ushort[FjxlSimdVec16.Lanes];
+        Span<ushort> token = stackalloc ushort[FjxlSimdVec16.Lanes];


gfoidl · 2026-09-10T11:52:28Z

+        Span<uint> bits = stackalloc uint[FjxlSimdVec16.Lanes];
+        Span<uint> nbits = stackalloc uint[FjxlSimdVec16.Lanes];
+        Span<ushort> bitsHuff = stackalloc ushort[FjxlSimdVec16.Lanes];
+        Span<ushort> nbitsHuff = stackalloc ushort[FjxlSimdVec16.Lanes];
+        Span<ushort> token = stackalloc ushort[FjxlSimdVec16.Lanes];


Two times combine and slice?

gfoidl · 2026-09-10T11:53:16Z

+        Span<ushort> bits = stackalloc ushort[FjxlSimdVec16.Lanes];
+        Span<ushort> nbits = stackalloc ushort[FjxlSimdVec16.Lanes];
+        Span<ushort> bitsHuff = stackalloc ushort[FjxlSimdVec16.Lanes];
+        Span<ushort> nbitsHuff = stackalloc ushort[FjxlSimdVec16.Lanes];
+        Span<ushort> token = stackalloc ushort[FjxlSimdVec16.Lanes];


gfoidl · 2026-09-10T11:54:03Z

+        Vector<short> res = Vector.Create<short>(residuals);
+        Vector<short> token = FjxlSimdUtils.ValueToToken(res);
+        Vector<short> nbits = FjxlSimdUtils.SaturateSubtract(token, Vector<short>.One);
+        Vector<short> bits = FjxlSimdUtils.SaturateSubtract(res, FjxlSimdUtils.Pow2(nbits));


gfoidl · 2026-09-10T11:55:12Z

+        Span<byte> codeLengthLengths = stackalloc byte[32].Slice(0, 18);
+        Span<byte> codeLengthLengthsMinimum = stackalloc byte[32].Slice(0, 18);
+        Span<byte> codeLengthLengthsMaximum = stackalloc byte[32].Slice(0, 18);


winscripter added 3 commits July 14, 2026 22:51

Add JPEG XL format

85c851b

Implement ac_context.h

996e93d

Implemented frame_dimensions.h plus part of ac_strategy.h

d87178f

winscripter added 12 commits July 15, 2026 14:44

Implement AC strategy

1ac6140

Implementation of ac_strategy.h and ac_strategy.c

Implement JxlMemoryManager

31b5505

For now JxlMemoryManager will be a wrapper around MemoryPool<T>.

Implement image and memory buffers

21ff33f

Implementation of image.h and image.c; AC strategy implementation was slightly adjusted to reduce errors.

Add metadata models

6fea920

Add headers & aspect ratio helpers

762edd1

Implement field encodings, move IJxlFields

487410e

This is an implementation of field_encodings.h. Note that I avoided implementing EnumValid() and Values() functions, as we have dedicated methods in .NET to do exactly that (Enum.IsDefined, Enum.GetValues)

Add xorshift implemetation

ac1c866

It's Jxl not Jpeg

8581222

Implement spline abstractions

9b58f4b

Implementation of spline.h

Add quantized spline implementations

064376a

Prefer the term "coefficient"

90680b7

Start work on ANS entropy

1e40482

Implemented ANS constants

gfoidl reviewed Jul 16, 2026

View reviewed changes

winscripter added 6 commits July 16, 2026 13:53

Implement JxlAnsHelper.GetPopulationCountPrecision

396cd8d

See ans_common.h

Turn JxlFrameDimensions into a sealed class

cb364fa

It is too large for a struct.

Implement CreateFlatHistogram

528149f

See ans_common.h

Add ANS entropy structs

490f02f

Add JxlAnsEntry and JxlAnsSymbol. See ans_common.h. These correspond to the Entry and Symbol structures within AliasTable.

Prefer byte for enums

73941c1

Implement ANS entropy helpers

20c2dd3

gfoidl reviewed Jul 16, 2026

View reviewed changes

Comment thread src/ImageSharp/Formats/Jxl/IO/JxlAnsHelper.cs Outdated

Comment thread src/ImageSharp/Formats/Jxl/IO/JxlAnsHelper.cs Outdated

winscripter added 3 commits July 16, 2026 22:15

Add bit-stream reader

fed0af3

Avoid 'using static'

25e41da

Simplify

4ec9b95

gfoidl reviewed Jul 16, 2026

View reviewed changes

Comment thread src/ImageSharp/Formats/Jxl/JxlThrowHelper.cs Outdated

Add ANS VarLen & histogram parser

b716d4e

Currently, there's a VarLenUint8/VarLenUint16 as well as histogram parsing implementation. I will additionally have to implement parsing of ANS codes, uint config and LZ77 parameters.

winscripter added 4 commits September 7, 2026 00:33

Complete core modular functions

412693e

Add PQ transfer function

649034b

Remove double emptyline

f2ccbac

Merge HLG base/derived class into one; abbreviate transfer function c…

e315e04

…lass name

gfoidl reviewed Sep 7, 2026

View reviewed changes

Comment thread src/ImageSharp/Formats/Jxl/Processing/Modular/Encoding/JxlMaEncoder.cs Outdated

winscripter added 6 commits September 7, 2026 15:18

Implement all transfer functions, add unpremultiply alpha to write to…

cebed59

… output stage, specify enum type as byte

Add tests, field writes, update folder structure, add group border as…

ab43e7b

…signer, complete noise decoder, XYB encoder, reference DCT

Add bit writer

836a055

Add visit to custom transform data

22d1d37

Add JPEG parser

1331167

Add JPEG writer (incomplete)

aaf4d1a

gfoidl reviewed Sep 8, 2026

View reviewed changes

winscripter added 7 commits September 8, 2026 20:28

Add transforms decoder, some ANS encoder work

fdba3ee

Blank transforms encoder

06598ee

Add fields tests

5b8cd17

Add encoder image comparators

0520ab3

Mark transforms encoder as TODO

0c2c3a1

Refactor

ec32e42

Add context map decoder

b058eba

gfoidl reviewed Sep 9, 2026

View reviewed changes

winscripter added 9 commits September 9, 2026 21:29

Remove SIMD vectors from FJXL, add some ANS symbol reader work

f872a81

Add SimdUtils.Lzcnt

4d49215

Add some FJXL work

1119f88

Add coeff order encoder

030fb54

Implement remaining SIMD utils in JXL

e81085c

Add TOC encoder

1a23a1a

Add JPEG XL optimize

5223e06

Add progressive split

46522e2

Implement field visitor for metadata

37766b8

gfoidl reviewed Sep 10, 2026

View reviewed changes


		namespace SixLabors.ImageSharp.Formats.Jxl.Processing.Decoder.Modular;

		internal sealed class JxlModularFrameDecoder

		// TODO: unrolling this would lead to big performance benefits
		for (int iy = 0; iy < 4; iy++)

Uh oh!

Uh oh!

Conversation

winscripter commented Jul 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Prerequisites

Description

Progress

Uh oh!

CLAassistant commented Jul 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

winscripter commented Jul 16, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

winscripter commented Jul 15, 2026 •

edited

Loading

CLAassistant commented Jul 15, 2026 •

edited

Loading