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.

winscripter · 2026-08-25T15:39:41Z

I had originally planned to add a managed Brotli codec under the Compression folder. However, I discovered that .NET has shipped built-in Brotli support since 2018, so a custom implementation is unnecessary. The decoder now uses System.IO.Compression.BrotliStream, as shown here.

- Use Stream for Box Content Decoder - Reduce errors in JxlDecoderCore - Add GetStride method to JxlFrameDecoder - Add JxlDctQuantWeightParameters and JxlQuantizerEncoding to implement more quant_weights.h components, and add proper documentation to each member of JxlQuantMode. - Remove InlineArray2<T> (there's already one built into System.Runtime.CompilerServices, so prefer to use that)

gfoidl · 2026-08-26T11:54:31Z

+            }
+        }
+
+        Span<byte> seen = stackalloc byte[index + 1];


There's the debug guard in L864 above, but how big can references.Length become?

Besides stack allocating to a length which is a power of two, then slicing is better, so e.g. Span<byte> seen = stackalloc byte[128].Slice(index + 1).

Length of references seems to be arbitrary. It's a Span view over frameReferences (on L304) which doesn't have a fixed upper bound.

That being said, I do believe using an ArrayPool here might be necessary, as for really large images the seen Span could become very large and lead to a stack overflow.

Common/Helpers - Add InterleaveLower and InterleaveUpper to Vector128_ and Vector256_ - Add unit test for InterleaveLower and InterleaveUpper (specifically for Vector256_) - Add Average to Numerics.cs Common - Add 32 and 33 to the InlineArray.tt text template Formats/Jxl/IO/Metadata - Remove unnecessary System.Runtime.CompilerServices using directive from JxlCustomTransformData and JxlOpsinInvreseMatrix Formats/Jxl/Processing/Decoder - Remove unncessary using SixLabors.ImageSharp.Formats.Jxl.IO Formats/Jxl/Processing/Encoder - Add partial Fast Lossless Encoder work (+enc_fast_lossless.cc; largest file in libjxl source) - Add linear algebra (+enc_linalg.cc, +enc_linalg.h) Formats/Jxl/Processing/Jpeg - Work that would later become JXL<->JPEG lossless coding mode Formats/Jxl/Processing/Modular/Encoding/ContextPrediction - Finish context prediction (+context_predict.h) Formats/Jxl/Processing/Modular/Transforms - Finish Reversible Color Transform (+rct.cc, +rct.h, +enc_rct.cc, +enc_rct.h) - Finish Palette/Indexed coding (+palette.cc, +palette.h, +enc_palette.cc, enc_palette.h) - Finish Squeeze transform (+squeeze.cc, +squeeze.h, +enc_squeeze.cc, +enc_squeeze.h) Formats/Jxl/Processing/RenderPipeline - Incomplete render pipeline abstractions with EPF (Edge Preserving Filter) 0 stage (+render_pipeline_stage.cc, +render_pipeline_stage.h, +stage_epf.cc, +stage_epf.h) Formats/Jxl/Processing/Splines - Remove unnecessary System.Runtime.CompilerServices using directive Formats/Jxl/Processing - Add dequantizer matrices - Remove JxlEndianness (prefer ByteOrder from ImageSharp/Common) - Add missing constant to JxlLoopFilter - Remove unnecessary using SixLabors.ImageSharp.Common.Helpers from JxlMath - Replace JxlPixelFormat to use ByteOrder - Update quantizers to use dequantizer matrices and quantizer weights - Add quantizer encoding and constants - Add SIMD utilities - Remove System.Runtime.CompilerServices using from JxlWeightsSeparable5 - Remove InlineArray3, InlineArray36 and InlineArray15 from InlineArrays (3 and 15 already exist in System.Runtime.CompilerServices; 36 already exists in InlineArray.tt from ImageSharp/Common) NEXT STEPS The current focus would be applying refactors and optimizations from reviews, followed by completing the JPEG XL modular.

This avoids the stack cookie

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.

gfoidl · 2026-09-01T15:11:44Z

        }
    }
+
+    public static void ComputeMinMax(JxlModularChannel channel, out int min, out int max)


Should this be vectorized? Would there be any benefit?
(of course could be done in a follow up PR)

Yes, I think there would be benefit.

TensorPrimitives uses SIMD internally, so I think we can do the following:

public static void ComputeMinMax(JxlModularChannel channel, out int min, out int max) { // Start with opposite bounds so the first iteration // guarantees to set these values min = int.MaxValue; max = int.MinValue; for (int y = 0; y < channel.Height; y++) { ReadOnlySpan<int> p = channel.GetRow(y); int minRow = TensorPrimitives.Min(p); int maxRow = TensorPrimitives.Max(p); min = Math.Min(minRow, min); max = Math.Max(maxRow, max); } }

What do you think?

I don't have a sense how large channel.Width / p.Length can get. When it's in the tenth, then the approach with TensorPrimitives is really nice. When it can get bigger then that approach will be $O(2n)$ (once for min and once for max), so it should be combined into just having one iteration over each row.

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.

gfoidl · 2026-09-02T09:44:36Z

+            }
+
+            int len = jpegData.AppData[i].Count - 17;
+            if (iccPos + len > icc.Length)


I'm a bit paranoid about overflow, so

if (iccPos > icc.Length - len)

to be on the safe side. Perf-wise there's no difference.

gfoidl · 2026-09-02T09:47:31Z

+            info.NumberOfAppMarkers++;
+        }
+
+        if (marker == 0xfe)


The ifs below could be else if or a switch.
Right now every if is checked which is not necessary?

gfoidl · 2026-09-02T10:06:14Z

+        acOk[0] = acOk[1] = acOk[2] = acOk[3] = false;
+        dcOk[0] = dcOk[1] = dcOk[2] = dcOk[3] = false;


This isn't needed. By default above they're already initialized to false (part of the C# language spec).

gfoidl · 2026-09-02T10:07:48Z

+    /// <summary>
+    /// Start of spectral band in zigzag sequence
+    /// </summary>
+    public int Ss;


These should be properties here in that class.

gfoidl · 2026-09-02T10:10:23Z

    /// Abstracts access to a raster frame data required for encoding.
    /// </summary>
-    internal interface IFjxlFrameInputSource : IDisposable
+    internal abstract class IFjxlFrameInputSource : IDisposable


-IFjxlFrameInputSource +FjxlFrameInputSource

For the naming assuming the I is the prefix for interface. But when the name in the reference source is with leading I it should be kept here.

gfoidl · 2026-09-02T10:11:48Z

    private const int MaxFirstPreviewSize = 8;

+    /// <summary>
+    /// Computes the average of two integers.


Please append a hint that this average is specific to JPEG XL usage.

gfoidl · 2026-09-02T10:16:09Z

        if (x < y)
        {
-            RuntimeUtility.Swap(ref x, ref y);
+            (y, x) = (x, y);


For the swap I don't know how "generic" the RuntimeUtility.Swap(ref x, ref y); is.
That swap with the value tuples I just in the quick prototype for Hypot because I was too lazy to bring in the aforementioned method.

I'm fine with either approach here.

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 5 commits August 25, 2026 19:45

Reduce errors & refine documentation

315ea0f

Reduce errors & remove unnecessary if statements

57958f3

Add missing types, reduce errors

0678f35

Complete quantizer encoding

874ec5b

gfoidl reviewed Aug 26, 2026

View reviewed changes

winscripter added 16 commits August 31, 2026 20:25

Don't use stackalloc for two bytes

7b8749d

This avoids the stack cookie

Prefer Math.DivRem

15c32fe

Use Math.DivRem

de8c644

Prefer byte

a5d5ab6

Don't use GetWReference (it should return span)

1b6e824

Parenthesize

c6c6942

Don't use stackalloc

79b0113

Remove SuppressFinalize from sealed class

e7d3608

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

		acOk[0] = acOk[1] = acOk[2] = acOk[3] = false;
		dcOk[0] = dcOk[1] = dcOk[2] = dcOk[3] = false;

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!

winscripter commented Aug 25, 2026

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!

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!

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!

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

winscripter commented Jul 15, 2026 •

edited

Loading

CLAassistant commented Jul 15, 2026 •

edited

Loading