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.

…, reduce errors in JxlDecoderCore

Bit Reader should automatically throw if it reads out of bounds anyway

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

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 8 commits August 24, 2026 21:40

Finish inverse RCT

093d846

Complete RCT

c5a7bb8

Simplify decoder core & add palette shared methods

c8b0a5d

Add missing types, rename JxlBitDepth metadata to JxlBitDepthMetadata…

c079cf9

…, reduce errors in JxlDecoderCore

Add CodestreamMarker, don't manually check for out-of-bounds

7e23670

Bit Reader should automatically throw if it reads out of bounds anyway

Reduce errors

b8f4094

Simplify

2b43fd6

Add box content decoder with Brotli compression & reduce errors

9f8eb4a

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 15 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

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!

gfoidl Aug 26, 2026

Choose a reason for hiding this comment

Uh oh!

winscripter Aug 31, 2026

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

winscripter commented Jul 15, 2026 •

edited

Loading

CLAassistant commented Jul 15, 2026 •

edited

Loading