Skip to content

Support for JPEG XL (JXL) images - #3153

Draft
winscripter wants to merge 64 commits into
SixLabors:mainfrom
winscripter:jxl-support
Draft

Support for JPEG XL (JXL) images#3153
winscripter wants to merge 64 commits into
SixLabors:mainfrom
winscripter:jxl-support

Conversation

@winscripter

Copy link
Copy Markdown

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

CLAassistant commented Jul 15, 2026

Copy link
Copy Markdown

CLA assistant check
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

Copy link
Copy Markdown
Author

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.

Comment thread src/ImageSharp/Formats/Jxl/Metadata/JxlExifOrientation.cs Outdated
Comment thread src/ImageSharp/Formats/Jxl/Metadata/JxlExtraChannel.cs Outdated
Comment thread src/ImageSharp/Formats/Jxl/Splines/JxlSplineEntropyContext.cs Outdated
Comment thread src/ImageSharp/Formats/Jxl/JxlFrameDimensions.cs Outdated
It is too large for a struct.
Add JxlAnsEntry and JxlAnsSymbol.

See ans_common.h. These correspond to the Entry and Symbol structures within AliasTable.
Comment thread src/ImageSharp/Formats/Jxl/IO/JxlAnsHelper.cs Outdated
Comment thread src/ImageSharp/Formats/Jxl/IO/JxlAnsHelper.cs Outdated
Comment thread src/ImageSharp/Formats/Jxl/JxlThrowHelper.cs Outdated
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.
Comment thread src/ImageSharp/Formats/Jxl/Fields/JxlF16Coder.cs Outdated
Comment thread src/ImageSharp/Formats/Jxl/IO/FrameHeader/JxlColorTransformHelpers.cs Outdated
Comment thread src/ImageSharp/Formats/Jxl/Processing/Butteraugli/ButteraugliParameters.cs Outdated
Comment thread src/ImageSharp/Formats/Jxl/Processing/Butteraugli/Butteraugli.cs Outdated
Comment thread src/ImageSharp/Formats/Jxl/Processing/Butteraugli/Butteraugli.cs
Comment thread src/ImageSharp/Formats/Jxl/Processing/JxlQuantizer.cs Outdated
Comment thread src/ImageSharp/Formats/Jxl/Processing/JxlQuantizer.cs Outdated
Comment thread src/ImageSharp/Formats/Jxl/IO/Metadata/JxlOpsinInverseMatrix.cs Outdated
Comment thread src/ImageSharp/Formats/Jxl/Processing/Decoder/JxlDecoderCore.cs Outdated
Comment thread src/ImageSharp/Formats/Jxl/Processing/Decoder/JxlOpsinParameters.cs Outdated

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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread src/ImageSharp/Formats/Jxl/Processing/JxlCoefficientOrder.cs
// 128-bit vector code for each quarter. And if the CPU
// doesn't support SIMD at all, the JIT will emit scalar
// instructions.
public static void MoveToFront(Span<byte> v, byte index)

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I do not think that this custom Vector512 path belongs here yet. It adds unsafe memory access, architecture-dependent behavior, and a hidden padding requirement.
As I read it the MTF table contains only 256 entries. A simple overlapping copy is easier to prove correct and lets the runtime select an appropriate implementation.

public static void MoveToFront(Span<byte> values, byte index)
{
    byte value = values[index];

    // CopyTo supports overlapping source and destination regions.
    values[..index].CopyTo(values[1..]);
    values[0] = value;
}

v[0] = value;
}

public static void InverseMoveToFrontTransform(Span<byte> v, int vLength)

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

InverseMoveToFrontTransform can use the span length as its input length. This removes the separate vLength contract.
The method also needs only a 256-byte table after removal of the custom vector path:

public static void InverseMoveToFrontTransform(Span<byte> values)
{
    Span<byte> table = stackalloc byte[256];

    for (int i = 0; i < table.Length; i++)
    {
        table[i] = (byte)i;
    }

    for (int i = 0; i < values.Length; i++)
    {
        byte index = values[i];
        byte value = table[index];
        values[i] = value;

        if (index != 0)
        {
            // CopyTo handles the overlap and shifts the preceding entries.
            table[..index].CopyTo(table[1..]);
            table[0] = value;
        }
    }
}

If the source buffer contains extra data, the caller can pass the required slice:
JxlInverseMtf.InverseMoveToFrontTransform(values[..valueCount]);
This version has no unsafe access, hidden padding, or architecture-specific behaviour.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants