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.

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.

gfoidl · 2026-09-01T13:35:46Z

+    /// <summary>
+    /// Quantization values
+    /// </summary>
+    public InlineArray64<int> Values;


This struct will be quite big with > 256 bytes in size. Maybe a class is better here (for the JpegQuantizationTable). Depends on the usage though, at least copying the struct should be avoided.

This isn't a decoder or encoder. It's just a parser/writer so the codec can take some quantization parameters from a JPEG file, as JPEG and JPEG XL are very similar.

…ise encoder tools, and complete render pipeline EPF 0 stage Files implemented: - enc_gaborish.cc - enc_gaborish.h - enc_gamma_correct.h - enc_huffman.cc - enc_huffman.h - enc_huffman_tree.cc - enc_huffman_tree.h - enc_noise.cc - enc_noise.h - render_pipeline/stage_epf.cc - render_pipeline/stage_epf.h

1. Reorder the overflow check in JpegData 2. Prefer switch in JpegData instead of multiple if statements 3. Don't explicitly false initialize acOk and dcOk in JpegData (they're already initialized to false). 4. IFjxlFrameInputSource -> FjxlFrameInputSource (it's an abstract class, I prefix is for interfaces) 5. Document that the JxlSqueeze.Average method is specific to the squeeze transform. 6. Prefer RuntimeUtility.Swap over tuple-based swap (micro-optimization)

- Use double for Clamp - Avoid bounds check in while loop

…ge (incomplete)

…nder pipeline stages

gfoidl · 2026-09-03T09:33:13Z

+    public static float RatioOfDerivativesOfCubicRootToSimpleGamma(float v, bool invert = false)
+    {
+        float epsilon = 1e-2f;
+        v = Math.Max(0, v); // cannot be < 0


Instead the comment use a debug guard?

The Math.Max call limits the v variable so it can't be below 0 (and if it is, it gets set to 0), the comment just explains what that line does.

Ey shame on me that I didn't read it this way. W/o the comment it would be more obvious (at least for me), so I'd drop the comment here.

gfoidl · 2026-09-03T09:37:45Z

+                continue;
+            }
+
+            Vector256<float> vsm = Vector256.Create((ReadOnlySpan<float>)sadMul[ix..]);


What's when Vector256 isn't supported?
When it's guarded / checked at the call-site, then add a debug guard in this method to claim that Vec256 is supported.

EPF stages operate at a fixed-size lane of 8 floats per iteration (in reference), and I decided to use Vector256 for this.

That being said, if the CPU doesn't support 256-bit vectors, it shouldn't fail - the JIT will just separate it into halves (if 128bit vectors supported), quarters (if 64bit vectors supported), or scalar (when no SIMD support). For example, my CPU (x86-64) supports vector instruction sets up to AVX2 (which is 256-bit), yet I can still use 512-bit vectors just fine.

Yep, and the JIT may emit software fallback code (which is in it's nature slower).
In order to keep the code clean, your approach is fine.
For tests / CI care has to be taken that these code pathes are also executed when no HW-acceleration is available, etc.
Further an explicit code path for Vec128 (for arm and wasm) can be added later on (if benchmarks show it's necessary).

I think I can use Vector<T> here actually, with minor changes. I'll just need unit tests to ensure that changing it doesn't break stuff, which we don't have yet (the codec isn't ready for tests at the moment). I'll look into using Vector<T> instead of Vector256 when we have working JPEG XL tests set up.

Sounds good 👍🏻

gfoidl · 2026-09-03T09:40:01Z

+        ref Vector256<float> B,
+        ref Vector256<float> w)
+    {
+        Vector256<float> cx = Vector256.Create((ReadOnlySpan<float>)rows[0][1 + row][x..].Span);


gfoidl · 2026-09-03T09:42:43Z

+    {
+        int channels = 3 + extraChannelInfos.Count;
+
+        Span<Memory<float>> rowPtrs = new Memory<float>[channels];


Can the array allocation be avoided?

Unfortunately I wasn't able to remove the array allocation. Trying to stackalloc a Memory gives error CS0208: Cannot take the address of, get the size of, or declare a pointer to a managed type ('Memory<float>').

That being said, the allocation should be very small - should be < 10 items.

Actually, I'll consider using an InlineArray10 with a separate length variable once I implement AddOneRow to JxlPatchDictionary. That should remove the allocation. 💡

gfoidl · 2026-09-03T09:46:25Z

+
+namespace SixLabors.ImageSharp.Formats.Jxl.Processing.RenderPipeline;
+
+internal sealed class WriteToOutputStage


Is there something missing?
All the members are private and so unused at the moment.

Maybe this comment is just a reminder 😉.

Yup, it's incomplete.

The write to output stage in reference had a lot of pointer-heavy code which I found more difficult to port to managed C# compared to other stages. So I implemented a few simple methods and saved this progress for later.

Probably will get back to it today.

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 7 commits August 31, 2026 20:46

Use Math.Clamp

e6ed4ba

Use StartsWith

4858ef3

Remove try/finally

2835528

Add JPEG parsed data

90ddb9d

Use InlineArray for color correlation

3059910

Add JPEG data constants

a955946

Update folder structure

497c27c

gfoidl reviewed Sep 1, 2026

View reviewed changes

winscripter added 5 commits September 1, 2026 22:12

Add JPEG parser for JXL<->JPEG conversion

4b9a74d

This isn't a decoder or encoder. It's just a parser/writer so the codec can take some quantization parameters from a JPEG file, as JPEG and JPEG XL are very similar.

Refactor & optimize

bc7e30e

Optimize

081384d

Make interface an abstract class

80f1075

Add encoder ANS SIMD bit cost estimation

fad73d8

gfoidl reviewed Sep 2, 2026

View reviewed changes

winscripter added 2 commits September 2, 2026 17:18

gfoidl reviewed Sep 2, 2026

View reviewed changes

Comment thread src/ImageSharp/Formats/Jxl/Processing/Encoder/Noise/JxlNoiseHistogram.cs Outdated

Comment thread src/ImageSharp/Formats/Jxl/Processing/Encoder/Noise/JxlNoiseHistogram.cs Outdated

winscripter added 12 commits September 2, 2026 19:45

Complete Edge Preserving Filter render pipeline stages

4116e9c

Optimize JxlNoiseHistogram

5874c4c

- Use double for Clamp - Avoid bounds check in while loop

Further update folder structure, start working on write to output sta…

5f99a65

…ge (incomplete)

Add IJxlImageOutput

9ad0210

Add ShouldFlip methods, fix typo

eead4a9

Add Y'Cb'Cr stage, make Epf1Stage class sealed

a0feb21

Use primary constructor

9f3ccfa

Add Gaborish stage

76ed571

Add patch dictionary stage

64edab5

Partial adaptive quantizer encoder

e0305d7

Add JxlToJpegDecoder static methods

5de2701

Add 3 missing methods to JxlFrameDecoder, add spline and spotcolor re…

4476abd

…nder pipeline stages

gfoidl reviewed Sep 3, 2026

View reviewed changes


		namespace SixLabors.ImageSharp.Formats.Jxl.Processing.RenderPipeline;

		internal sealed class WriteToOutputStage

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

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!

Choose a reason for hiding this comment

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!

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

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!

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

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

winscripter Sep 3, 2026 •

edited

Loading

winscripter Sep 3, 2026 •

edited

Loading