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.

Other components
The JPEG XL codec, additionally, uses the LZ77 and Brotli compression codec. I will also have to implement those eventually.

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

Brotli and LZ77 implementations will live under src/ImageSharp/Compression.

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.

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.

See chroma_from_luma.cc and chroma_from_luma.h

See butteraugli.h Added the parameters structure

…dering * CMS - Color Management System

gfoidl · 2026-08-01T21:05:54Z

+
+    public static bool ReadPermutation(int skip, int size, Span<int> order, JxlBitReader bitReader, JxlAnsSymbolReader reader, Span<byte> contextMap)
+    {
+        Span<uint> lehmer = stackalloc uint[size];


Is size limited to some maximum value?
If so, there should be an assert here to make it clear.

For the stackalloc it's better to use a constant value, then slice it if needed. Thus produces most of the time better code. E.g. stackalloc uint[128].Slice(0, size).

Although neither the reference implementation nor this implementation explicitly bounds size here, it is constrained by the JPEG XL bitstream syntax. size is derived from the transform strategy and can only take one of the specification-defined coefficient counts (64, 128, 256, 512, 1024, 2048, 4096, 8192, 16384, 32768, or 65536). The maximum possible value is therefore 65536.

I'll add an assert.

See inverse_mtf-inl.h

- Add decoding of Huffman Codes (see dec_huffman.cc and dec_huffman.h) - Add constructors to JxlImage3* classes - Make JxlColorCorrelationMap.Create 'xyb' parameter use true as a default value - Prototype of DCT quant weight parameters - Add passes shared state (see passes_state.cc and passes_state.h) - Add prototype for image operations (see image_ops.cc and image_ops.h) - Simplify inverse MTF (Move to Front) transform - Add patch context (see patch_dictionary_internal.h) - Add prototype of quantizer weights - Add 2nd prototype of ANS entropy decoding (see dec_ans.cc and dec_ans.h) - Add prototype of patch dictionary decoding (see dec_patch_dictionary.cc and dec_patch_dictionary.h)

This massively reduces number of syntax errors

gfoidl · 2026-08-09T10:31:40Z

+        // Use new because there's only up to 3 elements
+        float[] kernel = new float[(2 * diff) + 1];


only up to 3 elements

Use an inline-array then?

My bad - I misread the Math.Max call and thought it was capping diff at 1 rather than setting its minimum. So the kernel can be well over 3 elements depending on sigma. It still shouldn't get very large in practice, so I'll add a temporary DebugGuard to cap it at 32 while I verify the expected range.

gfoidl · 2026-08-09T10:56:17Z

+        JxlImageF[] hf0 = new JxlImageF[2];
+        JxlImageF[] hf1 = new JxlImageF[2];


Can these allocations be avoided (inline arrays)?

gfoidl · 2026-08-09T10:56:40Z

+        JxlImageF[] uhf0 = new JxlImageF[2];
+        JxlImageF[] uhf1 = new JxlImageF[2];


Also inline arrays?

gfoidl · 2026-08-09T11:16:33Z

+            Span<uint> symbols = stackalloc uint[2];
+            symbols.Clear();


For such small stack-allocs

Suggested change

Span<uint> symbols = stackalloc uint[2];

symbols.Clear();

Span<uint> symbols = [0, 0];

is

the same semantics

easier to read

avoids the stack cookie that the JIT emits for stack-safety validation (which by using the inline array via collection expression the C# compiler does)

note: for small sizes Clear is unrolled by the JIT, so no actual method call needed

gfoidl · 2026-08-09T11:19:40Z

+        // The alphabet size is at most 256
+        Span<byte> codeLengths = stackalloc byte[alphabetSize];


Suggested change

// The alphabet size is at most 256

Span<byte> codeLengths = stackalloc byte[alphabetSize];

Debug.Assert(alphabetSize <= 256);

Span<byte> codeLengths = stackalloc byte[256].Slice(0, alphabetSize);

stack-allocating to a constant produces better code. Then slicing it is also cheaper than stackalloc byte[variable].

gfoidl · 2026-08-09T11:22:57Z

+    {
+        this.memoryOwner?.Dispose();
+        this.ControlPoints = Memory<JxlControlPoint>.Empty;
+        GC.SuppressFinalize(this);


Suggested change

GC.SuppressFinalize(this);

Not needed. This is internal sealed class, so nothing can derive from it and therefore nothing can put a finalizer to this object.

I think I've spotted similar calls above, but didn't flag them. Please revise these.

gfoidl · 2026-08-09T11:32:32Z

+        while (x < 0 || x >= xSize)
+        {
+            if (x < 0)
+            {
+                x = -x - 1;
+            }
+            else
+            {
+                x = (2 * xSize) - 1 - x;
+            }
+        }


Suggested change

while (x < 0 || x >= xSize)

{

if (x < 0)

{

x = -x - 1;

}

else

{

x = (2 * xSize) - 1 - x;

}

}

while (true)

{

if (x < 0)

{

x = -x - 1;

}

else if (x >= xSize)

{

x = (2 * xSize) - 1 - x;

}

else

{

break;

}

}

should produce a tighter loop.

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 6 commits July 21, 2026 16:46

Move, add entropy coding common functions

2758454

Remove aggressive inlining attributes, fix usings

6eda7e2

Use distinct read-only spans

f71bab2

Add CFL

abafaf8

See chroma_from_luma.cc and chroma_from_luma.h

Add Huffman common methods

9c6b4ef

Start work on Butteraugli

3591250

See butteraugli.h Added the parameters structure

gfoidl reviewed Jul 23, 2026

View reviewed changes

Comment thread src/ImageSharp/Formats/Jxl/Processing/Butteraugli/ButteraugliParameters.cs Outdated

Implement Butteraugli core functions

765c892

gfoidl reviewed Jul 25, 2026

View reviewed changes

winscripter added 4 commits August 1, 2026 23:44

Add CMS* prototype, XYB decoding, TOC, convolution and coefficient or…

0d159b9

…dering * CMS - Color Management System

Use inline arrays in quantizer

083385b

Prefer const

a1cae71

Don't use System.Diagnostics.Debug

eb80187

gfoidl reviewed Aug 1, 2026

View reviewed changes

winscripter added 5 commits August 6, 2026 13:15

Add Move to Front transform

79e8ce7

See inverse_mtf-inl.h

Prefer inline arrays

d1f6646

Prevent potential overflow

fe41799

Refactor

8209aa1

Validate the size parameter in JxlCoefficientOrder.ReadPermutation

074ff1b

JimBobSquarePants reviewed Aug 6, 2026

View reviewed changes

Comment thread src/ImageSharp/Formats/Jxl/Processing/JxlInverseMtf.cs Outdated

JimBobSquarePants reviewed Aug 6, 2026

View reviewed changes

Comment thread src/ImageSharp/Formats/Jxl/Processing/JxlInverseMtf.cs Outdated

winscripter added 8 commits August 8, 2026 18:17

Add image copy operations

ff98ffd

Implement image operations

e718a4a

Reduce number of errors

048945c

Implement JPEG XL numerics functions & reduce errors

4f71c52

Add rectangle support to images

4d0a468

This massively reduces number of syntax errors

Document JxlPlane<T> and JxlPlaneBase

2c517a2

Add passes decoder state prototype & reduce errors in JxlQuantizedSpline

50813c1

gfoidl reviewed Aug 9, 2026

View reviewed changes

		// Use new because there's only up to 3 elements
		float[] kernel = new float[(2 * diff) + 1];

		JxlImageF[] hf0 = new JxlImageF[2];
		JxlImageF[] hf1 = new JxlImageF[2];

		JxlImageF[] uhf0 = new JxlImageF[2];
		JxlImageF[] uhf1 = new JxlImageF[2];

	Span<uint> symbols = stackalloc uint[2];
	symbols.Clear();
	Span<uint> symbols = [0, 0];

		// The alphabet size is at most 256
		Span<byte> codeLengths = stackalloc byte[alphabetSize];

Uh oh!

Uh oh!

Conversation

winscripter commented Jul 15, 2026

Prerequisites

Description

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!

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!

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

CLAassistant commented Jul 15, 2026 •

edited

Loading